"""working_dir 在 DB 与文件系统两种形态之间的归一(原 `task_dir` 已改名)。

存储约定(DESIGN §7.4):
- working_dir → 相对 ROOT 的 posix 串(如 `workspace/users/<uid>/<name>`)
- 空串 → 空串(legacy / 未绑项目;新建路径已 NOT NULL)

写入入口(`web/app.py POST /v1/tasks` → `working_dir_from_name`)只接 simple name,
拼到 `<workspace>/users/<uid>/<name>` 必在 ROOT 内 —— 越界视为 bug,`to_db_path` raise。

Read 端唯一入口:DB tasks.working_dir → `from_db_path(s)` → absolute Path。
Write 端唯一入口:absolute Path → `to_db_path(p)` → DB 串。
"""
from __future__ import annotations

from pathlib import Path
from typing import Union

ROOT: Path = Path(__file__).resolve().parent.parent


def to_db_path(p: Union[Path, str, None]) -> str:
    """absolute Path / str → DB 串(相对 ROOT posix)。

    输入应已是绝对路径(build_agent / web 路由那一层都 .resolve() 过)。
    越出 ROOT 直接 raise —— 写入入口不允许外部目录(简单名 join workspace)。
    空 → ""。
    """
    if not p:
        return ""
    pp = Path(p).resolve()
    return pp.relative_to(ROOT).as_posix()


def from_db_path(s: str) -> Path:
    """DB 串(相对 ROOT posix)→ absolute Path。空 → Path("")(调用方判)。"""
    if not s or not s.strip():
        return Path("")
    return (ROOT / s).resolve()