taskledger 0.1.0__py3-none-any.whl

taskledger/storage/task_store.py

@@ -0,0 +1,836 @@
+# Derived index files
+#
+# Index files under .taskledger/indexes/ are derived caches.
+# They are rebuilt from canonical Markdown/YAML records by 'taskledger reindex'.
+# They may be plain JSON arrays with no version metadata.
+# They are never the authoritative source of truth.
+# 'doctor indexes' checks staleness but not schema mismatches as migration blockers.
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypeVar
+
+import yaml
+
+from taskledger.domain.models import (
+    ActiveActorState,
+    ActiveHarnessState,
+    ActiveTaskState,
+    CodeChangeRecord,
+    DependencyRequirement,
+    FileLink,
+    IntroductionRecord,
+    LinkCollection,
+    PlanRecord,
+    QuestionRecord,
+    RequirementCollection,
+    TaskHandoffRecord,
+    TaskLock,
+    TaskRecord,
+    TaskRunRecord,
+    TaskTodo,
+    TodoCollection,
+)
+from taskledger.domain.states import (
+    TASKLEDGER_SCHEMA_VERSION,
+    TASKLEDGER_V2_FILE_VERSION,
+)
+from taskledger.errors import ActiveTaskNotFound, LaunchError, NoActiveTask
+from taskledger.storage.atomic import atomic_write_text
+from taskledger.storage.frontmatter import (
+    normalize_front_matter_newlines,
+    read_markdown_front_matter,
+    write_markdown_front_matter,
+)
+from taskledger.storage.locks import read_lock, update_lock, write_lock
+from taskledger.storage.paths import resolve_taskledger_root
+from taskledger.timeutils import utc_now_iso
+
+T = TypeVar("T")
+
+
+def _link_id_from_path(path: str) -> str:
+    """Generate a deterministic link id from the path."""
+    import hashlib
+
+    digest = hashlib.sha256(path.encode("utf-8")).hexdigest()[:8]
+    return f"link-{digest}"
+
+
+def _requirement_id_from_task(task_id: str) -> str:
+    """Generate a deterministic requirement id from the required task id."""
+    import re
+
+    match = re.match(r"task-(\d+)", task_id)
+    if match:
+        return f"req-{match.group(1)}"
+    return f"req-{task_id}"
+
+
+@dataclass(slots=True, frozen=True)
+class V2Paths:
+    workspace_root: Path
+    project_dir: Path
+    introductions_dir: Path
+    tasks_dir: Path
+    plans_dir: Path
+    questions_dir: Path
+    runs_dir: Path
+    changes_dir: Path
+    events_dir: Path
+    indexes_dir: Path
+    active_task_path: Path
+    actor_path: Path
+    harness_path: Path
+    active_locks_index_path: Path
+    dependencies_index_path: Path
+    introductions_index_path: Path
+
+
+def resolve_v2_paths(workspace_root: Path) -> V2Paths:
+    project_dir = resolve_taskledger_root(workspace_root)
+    indexes_dir = project_dir / "indexes"
+    return V2Paths(
+        workspace_root=workspace_root,
+        project_dir=project_dir,
+        introductions_dir=project_dir / "intros",
+        tasks_dir=project_dir / "tasks",
+        plans_dir=project_dir / "plans",
+        questions_dir=project_dir / "questions",
+        runs_dir=project_dir / "runs",
+        changes_dir=project_dir / "changes",
+        events_dir=project_dir / "events",
+        indexes_dir=indexes_dir,
+        active_task_path=project_dir / "active-task.yaml",
+        actor_path=project_dir / "actor.yaml",
+        harness_path=project_dir / "harness.yaml",
+        active_locks_index_path=indexes_dir / "active_locks.json",
+        dependencies_index_path=indexes_dir / "dependencies.json",
+        introductions_index_path=indexes_dir / "introductions.json",
+    )
+
+
+def ensure_v2_layout(workspace_root: Path) -> V2Paths:
+    paths = resolve_v2_paths(workspace_root)
+    for directory in (
+        paths.project_dir,
+        paths.introductions_dir,
+        paths.tasks_dir,
+        paths.events_dir,
+        paths.indexes_dir,
+    ):
+        directory.mkdir(parents=True, exist_ok=True)
+    for index_path in (
+        paths.active_locks_index_path,
+        paths.dependencies_index_path,
+        paths.introductions_index_path,
+    ):
+        if index_path.exists():
+            continue
+        atomic_write_text(index_path, "[]\n")
+    return paths
+
+
+def list_tasks(workspace_root: Path) -> list[TaskRecord]:
+    paths = ensure_v2_layout(workspace_root)
+    return sorted(
+        [_load_task(path) for path in paths.tasks_dir.glob("task-*/task.md")],
+        key=lambda item: item.id,
+    )
+
+
+def resolve_task(workspace_root: Path, ref: str) -> TaskRecord:
+    normalized_ref = ref.strip().lower()
+    normalized_id = _normalize_numeric_ref(normalized_ref, "task")
+    for task in list_tasks(workspace_root):
+        if task.id == ref or task.id == normalized_id or task.slug == normalized_ref:
+            return task
+    raise LaunchError(f"Task not found: {ref}")
+
+
+def load_active_task_state(workspace_root: Path) -> ActiveTaskState | None:
+    paths = ensure_v2_layout(workspace_root)
+    if not paths.active_task_path.exists():
+        return None
+    try:
+        payload = yaml.safe_load(paths.active_task_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise LaunchError(f"Invalid active task state: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise LaunchError("Invalid active task state: expected mapping.")
+    return ActiveTaskState.from_dict(payload)
+
+
+def save_active_task_state(
+    workspace_root: Path,
+    state: ActiveTaskState,
+) -> ActiveTaskState:
+    paths = ensure_v2_layout(workspace_root)
+    _write_yaml(paths.active_task_path, state.to_dict())
+    return state
+
+
+def clear_active_task_state(workspace_root: Path) -> ActiveTaskState | None:
+    paths = ensure_v2_layout(workspace_root)
+    state = load_active_task_state(workspace_root)
+    if paths.active_task_path.exists():
+        paths.active_task_path.unlink()
+    return state
+
+
+def load_actor_state(workspace_root: Path) -> ActiveActorState | None:
+    paths = ensure_v2_layout(workspace_root)
+    if not paths.actor_path.exists():
+        return None
+    try:
+        payload = yaml.safe_load(paths.actor_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise LaunchError(f"Invalid actor state: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise LaunchError("Invalid actor state: expected mapping.")
+    return ActiveActorState.from_dict(payload)
+
+
+def save_actor_state(
+    workspace_root: Path,
+    state: ActiveActorState,
+) -> ActiveActorState:
+    paths = ensure_v2_layout(workspace_root)
+    _write_yaml(paths.actor_path, state.to_dict())
+    return state
+
+
+def clear_actor_state(workspace_root: Path) -> ActiveActorState | None:
+    paths = ensure_v2_layout(workspace_root)
+    state = load_actor_state(workspace_root)
+    if paths.actor_path.exists():
+        paths.actor_path.unlink()
+    return state
+
+
+def load_harness_state(workspace_root: Path) -> ActiveHarnessState | None:
+    paths = ensure_v2_layout(workspace_root)
+    if not paths.harness_path.exists():
+        return None
+    try:
+        payload = yaml.safe_load(paths.harness_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise LaunchError(f"Invalid harness state: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise LaunchError("Invalid harness state: expected mapping.")
+    return ActiveHarnessState.from_dict(payload)
+
+
+def save_harness_state(
+    workspace_root: Path,
+    state: ActiveHarnessState,
+) -> ActiveHarnessState:
+    paths = ensure_v2_layout(workspace_root)
+    _write_yaml(paths.harness_path, state.to_dict())
+    return state
+
+
+def clear_harness_state(workspace_root: Path) -> ActiveHarnessState | None:
+    paths = ensure_v2_layout(workspace_root)
+    state = load_harness_state(workspace_root)
+    if paths.harness_path.exists():
+        paths.harness_path.unlink()
+    return state
+
+
+def resolve_active_task(workspace_root: Path) -> TaskRecord:
+    state = load_active_task_state(workspace_root)
+    if state is None:
+        raise NoActiveTask()
+    try:
+        return resolve_task(workspace_root, state.task_id)
+    except LaunchError as exc:
+        raise ActiveTaskNotFound(
+            f"Active task points to missing task: {state.task_id}",
+            details={"task_id": state.task_id},
+            task_id=state.task_id,
+        ) from exc
+
+
+def resolve_task_or_active(
+    workspace_root: Path,
+    ref: str | None = None,
+) -> TaskRecord:
+    if ref is not None and ref.strip():
+        return resolve_task(workspace_root, ref)
+    return resolve_active_task(workspace_root)
+
+
+def save_task(workspace_root: Path, task: TaskRecord) -> TaskRecord:
+    paths = ensure_v2_layout(workspace_root)
+    _ensure_task_bundle(paths, task.id)
+    path = task_markdown_path(paths, task.id)
+    if path.parent.name != task.id:
+        raise LaunchError(f"Task id/path mismatch for {task.id}")
+    metadata = task.to_dict()
+    metadata.pop("todos", None)
+    metadata.pop("file_links", None)
+    metadata.pop("requirements", None)
+    _write_markdown_record(path, metadata, task.body)
+    return task
+
+
+def list_introductions(workspace_root: Path) -> list[IntroductionRecord]:
+    paths = ensure_v2_layout(workspace_root)
+    return sorted(
+        [_load_intro(path) for path in paths.introductions_dir.glob("intro-*.md")],
+        key=lambda item: item.id,
+    )
+
+
+def resolve_introduction(workspace_root: Path, ref: str) -> IntroductionRecord:
+    normalized_ref = ref.strip().lower()
+    for intro in list_introductions(workspace_root):
+        if intro.id == ref or intro.slug == normalized_ref:
+            return intro
+    raise LaunchError(f"Introduction not found: {ref}")
+
+
+def save_introduction(
+    workspace_root: Path, introduction: IntroductionRecord
+) -> IntroductionRecord:
+    paths = ensure_v2_layout(workspace_root)
+    path = paths.introductions_dir / f"{introduction.id}.md"
+    _write_markdown_record(path, introduction.to_dict(), introduction.body)
+    return introduction
+
+
+def list_plans(workspace_root: Path, task_id: str) -> list[PlanRecord]:
+    paths = ensure_v2_layout(workspace_root)
+    directory = task_plans_dir(paths, task_id)
+    return sorted(
+        [_load_plan(path) for path in directory.glob("plan-v*.md")],
+        key=lambda item: item.plan_version,
+    )
+
+
+def save_plan(workspace_root: Path, plan: PlanRecord) -> PlanRecord:
+    paths = ensure_v2_layout(workspace_root)
+    path = plan_markdown_path(paths, plan.task_id, plan.plan_version)
+    if path.exists():
+        raise LaunchError(
+            f"Plan version already exists: {plan.task_id} v{plan.plan_version}"
+        )
+    _write_markdown_record(path, plan.to_dict(), plan.body)
+    return plan
+
+
+def overwrite_plan(workspace_root: Path, plan: PlanRecord) -> PlanRecord:
+    paths = ensure_v2_layout(workspace_root)
+    path = plan_markdown_path(paths, plan.task_id, plan.plan_version)
+    _write_markdown_record(path, plan.to_dict(), plan.body)
+    return plan
+
+
+def resolve_plan(
+    workspace_root: Path,
+    task_id: str,
+    *,
+    version: int | None = None,
+) -> PlanRecord:
+    plans = list_plans(workspace_root, task_id)
+    if not plans:
+        raise LaunchError(f"No plans found for task {task_id}")
+    if version is None:
+        return plans[-1]
+    for plan in plans:
+        if plan.plan_version == version:
+            return plan
+    raise LaunchError(f"Plan version not found for task {task_id}: {version}")
+
+
+def list_questions(workspace_root: Path, task_id: str) -> list[QuestionRecord]:
+    paths = ensure_v2_layout(workspace_root)
+    directory = task_questions_dir(paths, task_id)
+    return sorted(
+        [_load_question(path) for path in directory.glob("q-*.md")],
+        key=lambda item: item.id,
+    )
+
+
+def resolve_question(
+    workspace_root: Path, task_id: str, question_id: str
+) -> QuestionRecord:
+    normalized_id = _normalize_numeric_ref(question_id, "q")
+    for question in list_questions(workspace_root, task_id):
+        if question.id == question_id or question.id == normalized_id:
+            return question
+    raise LaunchError(f"Question not found: {question_id}")
+
+
+def save_question(workspace_root: Path, question: QuestionRecord) -> QuestionRecord:
+    paths = ensure_v2_layout(workspace_root)
+    path = question_markdown_path(paths, question.task_id, question.id)
+    _write_markdown_record(path, question.to_dict(), _render_question_body(question))
+    return question
+
+
+def list_runs(workspace_root: Path, task_id: str) -> list[TaskRunRecord]:
+    paths = ensure_v2_layout(workspace_root)
+    directory = task_runs_dir(paths, task_id)
+    return sorted(
+        [_load_run(path) for path in directory.glob("*.md")],
+        key=lambda item: item.run_id,
+    )
+
+
+def resolve_run(workspace_root: Path, task_id: str, run_id: str) -> TaskRunRecord:
+    normalized_id = _normalize_numeric_ref(run_id, "run")
+    for run in list_runs(workspace_root, task_id):
+        if run.run_id == run_id or run.run_id == normalized_id:
+            return run
+    raise LaunchError(f"Run not found: {run_id}")
+
+
+def save_run(workspace_root: Path, run: TaskRunRecord) -> TaskRunRecord:
+    paths = ensure_v2_layout(workspace_root)
+    path = run_markdown_path(paths, run.task_id, run.run_id)
+    _write_markdown_record(path, run.to_dict(), _render_run_body(run))
+    return run
+
+
+def list_changes(workspace_root: Path, task_id: str) -> list[CodeChangeRecord]:
+    paths = ensure_v2_layout(workspace_root)
+    directory = task_changes_dir(paths, task_id)
+    return sorted(
+        [_load_change(path) for path in directory.glob("change-*.md")],
+        key=lambda item: item.change_id,
+    )
+
+
+def save_change(workspace_root: Path, change: CodeChangeRecord) -> CodeChangeRecord:
+    paths = ensure_v2_layout(workspace_root)
+    path = change_markdown_path(paths, change.task_id, change.change_id)
+    _write_markdown_record(path, change.to_dict(), change.summary)
+    return change
+
+
+def resolve_change(
+    workspace_root: Path, task_id: str, change_id: str
+) -> CodeChangeRecord:
+    normalized_id = _normalize_numeric_ref(change_id, "change")
+    for change in list_changes(workspace_root, task_id):
+        if change.change_id == change_id or change.change_id == normalized_id:
+            return change
+    raise LaunchError(f"Change not found: {change_id}")
+
+
+def load_active_locks(workspace_root: Path) -> list[TaskLock]:
+    paths = ensure_v2_layout(workspace_root)
+    locks: list[TaskLock] = []
+    for path in sorted(paths.tasks_dir.glob("task-*/lock.yaml")):
+        lock = read_lock(path)
+        if lock is not None:
+            locks.append(lock)
+    return locks
+
+
+def load_todos(workspace_root: Path, task_id: str) -> TodoCollection:
+    paths = ensure_v2_layout(workspace_root)
+    directory = task_todos_dir(paths, task_id)
+    records = sorted(
+        [_load_record(p, TaskTodo.from_dict) for p in directory.glob("todo-*.md")],
+        key=lambda t: t.id,
+    )
+    return TodoCollection(task_id=task_id, todos=tuple(records))
+
+
+def save_todos(workspace_root: Path, collection: TodoCollection) -> TodoCollection:
+    paths = ensure_v2_layout(workspace_root)
+    _ensure_task_bundle(paths, collection.task_id)
+    directory = task_todos_dir(paths, collection.task_id)
+    directory.mkdir(parents=True, exist_ok=True)
+    keep_ids = set()
+    now = utc_now_iso()
+    for todo in collection.todos:
+        keep_ids.add(todo.id)
+        metadata = todo.to_dict()
+        metadata["task_id"] = collection.task_id
+        metadata["file_version"] = TASKLEDGER_V2_FILE_VERSION
+        metadata["schema_version"] = TASKLEDGER_SCHEMA_VERSION
+        metadata["object_type"] = "todo"
+        if "updated_at" not in metadata or metadata["updated_at"] is None:
+            metadata["updated_at"] = now
+        body = todo.text
+        path = todo_markdown_path(paths, collection.task_id, todo.id)
+        _write_markdown_record(path, metadata, body)
+    # Remove stale files
+    for path in directory.glob("todo-*.md"):
+        if path.stem not in keep_ids:
+            path.unlink()
+    return collection
+
+
+def load_links(workspace_root: Path, task_id: str) -> LinkCollection:
+    paths = ensure_v2_layout(workspace_root)
+    directory = task_links_dir(paths, task_id)
+    records = sorted(
+        [_load_record(p, FileLink.from_dict) for p in directory.glob("link-*.md")],
+        key=lambda lk: lk.id or "",
+    )
+    return LinkCollection(task_id=task_id, links=tuple(records))
+
+
+def save_links(workspace_root: Path, collection: LinkCollection) -> LinkCollection:
+    paths = ensure_v2_layout(workspace_root)
+    _ensure_task_bundle(paths, collection.task_id)
+    directory = task_links_dir(paths, collection.task_id)
+    directory.mkdir(parents=True, exist_ok=True)
+    keep_ids = set()
+    now = utc_now_iso()
+    for link in collection.links:
+        link_id = link.id or _link_id_from_path(link.path)
+        keep_ids.add(link_id)
+        metadata = link.to_dict()
+        metadata["id"] = link_id
+        metadata["task_id"] = collection.task_id
+        metadata["file_version"] = TASKLEDGER_V2_FILE_VERSION
+        metadata["schema_version"] = TASKLEDGER_SCHEMA_VERSION
+        metadata["object_type"] = "link"
+        if metadata.get("created_at") is None:
+            metadata["created_at"] = now
+        if metadata.get("updated_at") is None:
+            metadata["updated_at"] = now
+        body = link.path
+        path = link_markdown_path(paths, collection.task_id, link_id)
+        _write_markdown_record(path, metadata, body)
+    # Remove stale files
+    for path in directory.glob("link-*.md"):
+        if path.stem not in keep_ids:
+            path.unlink()
+    return collection
+
+
+def load_requirements(workspace_root: Path, task_id: str) -> RequirementCollection:
+    paths = ensure_v2_layout(workspace_root)
+    directory = task_requirements_dir(paths, task_id)
+    records = sorted(
+        [
+            _load_record(p, DependencyRequirement.from_dict)
+            for p in directory.glob("req-*.md")
+        ],
+        key=lambda r: r.id or "",
+    )
+    return RequirementCollection(task_id=task_id, requirements=tuple(records))
+
+
+def save_requirements(
+    workspace_root: Path, collection: RequirementCollection
+) -> RequirementCollection:
+    paths = ensure_v2_layout(workspace_root)
+    _ensure_task_bundle(paths, collection.task_id)
+    directory = task_requirements_dir(paths, collection.task_id)
+    directory.mkdir(parents=True, exist_ok=True)
+    keep_ids = set()
+    now = utc_now_iso()
+    for req in collection.requirements:
+        req_id = req.id or _requirement_id_from_task(req.task_id)
+        keep_ids.add(req_id)
+        metadata = req.to_dict()
+        metadata["id"] = req_id
+        metadata["task_id"] = collection.task_id
+        metadata["required_task_id"] = req.required_task_id or req.task_id
+        metadata["file_version"] = TASKLEDGER_V2_FILE_VERSION
+        metadata["schema_version"] = TASKLEDGER_SCHEMA_VERSION
+        metadata["object_type"] = "requirement"
+        if metadata.get("created_at") is None:
+            metadata["created_at"] = now
+        if metadata.get("updated_at") is None:
+            metadata["updated_at"] = now
+        body = (
+            f"Requires {req.required_task_id or req.task_id}"
+            f" to be {req.required_status}."
+        )
+        path = requirement_markdown_path(paths, collection.task_id, req_id)
+        _write_markdown_record(path, metadata, body)
+    # Remove stale files
+    for path in directory.glob("req-*.md"):
+        if path.stem not in keep_ids:
+            path.unlink()
+    return collection
+
+
+def task_dir(paths: V2Paths, task_id: str) -> Path:
+    return paths.tasks_dir / task_id
+
+
+def task_markdown_path(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "task.md"
+
+
+def task_lock_path(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "lock.yaml"
+
+
+def task_todos_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "todos"
+
+
+def task_links_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "links"
+
+
+def task_requirements_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "requirements"
+
+
+def task_todos_path(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "todos.yaml"
+
+
+def task_links_path(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "links.yaml"
+
+
+def task_requirements_path(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "requirements.yaml"
+
+
+def todo_markdown_path(paths: V2Paths, task_id: str, todo_id: str) -> Path:
+    return task_todos_dir(paths, task_id) / f"{todo_id}.md"
+
+
+def link_markdown_path(paths: V2Paths, task_id: str, link_id: str) -> Path:
+    return task_links_dir(paths, task_id) / f"{link_id}.md"
+
+
+def requirement_markdown_path(paths: V2Paths, task_id: str, req_id: str) -> Path:
+    return task_requirements_dir(paths, task_id) / f"{req_id}.md"
+
+
+def task_plans_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "plans"
+
+
+def task_questions_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "questions"
+
+
+def task_runs_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "runs"
+
+
+def task_changes_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "changes"
+
+
+def task_artifacts_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "artifacts"
+
+
+def task_audit_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "audit"
+
+
+def task_handoffs_dir(paths: V2Paths, task_id: str) -> Path:
+    return task_dir(paths, task_id) / "handoffs"
+
+
+def handoff_markdown_path(paths: V2Paths, task_id: str, handoff_id: str) -> Path:
+    return task_handoffs_dir(paths, task_id) / f"{handoff_id}.md"
+
+
+def plan_markdown_path(paths: V2Paths, task_id: str, version: int) -> Path:
+    return task_plans_dir(paths, task_id) / f"plan-v{version}.md"
+
+
+def question_markdown_path(paths: V2Paths, task_id: str, question_id: str) -> Path:
+    return task_questions_dir(paths, task_id) / f"{question_id}.md"
+
+
+def run_markdown_path(paths: V2Paths, task_id: str, run_id: str) -> Path:
+    return task_runs_dir(paths, task_id) / f"{run_id}.md"
+
+
+def change_markdown_path(paths: V2Paths, task_id: str, change_id: str) -> Path:
+    return task_changes_dir(paths, task_id) / f"{change_id}.md"
+
+
+def _load_task(path: Path) -> TaskRecord:
+    return _load_record(path, TaskRecord.from_dict)
+
+
+def _load_intro(path: Path) -> IntroductionRecord:
+    return _load_record(path, IntroductionRecord.from_dict)
+
+
+def _load_plan(path: Path) -> PlanRecord:
+    return _load_record(path, PlanRecord.from_dict)
+
+
+def _load_question(path: Path) -> QuestionRecord:
+    return _load_record(path, QuestionRecord.from_dict)
+
+
+def _load_run(path: Path) -> TaskRunRecord:
+    return _load_record(path, TaskRunRecord.from_dict)
+
+
+def _load_change(path: Path) -> CodeChangeRecord:
+    return _load_record(path, CodeChangeRecord.from_dict)
+
+
+def _load_record(path: Path, parser: Callable[[dict[str, object]], T]) -> T:
+    metadata, body = read_markdown_front_matter(path)
+    metadata["body"] = normalize_front_matter_newlines(body).rstrip("\n")
+    metadata = _ensure_schema_compat(metadata)
+    return parser(metadata)
+
+
+def _ensure_schema_compat(record: dict) -> dict:
+    """Ensure record schema is compatible."""
+    version = record.get("schema_version", 1)
+    if version > TASKLEDGER_SCHEMA_VERSION:
+        raise LaunchError(
+            f"Record schema too new: {version} "
+            f"(current max: {TASKLEDGER_SCHEMA_VERSION}). "
+            "Please upgrade taskledger."
+        )
+    return record
+
+
+def _write_markdown_record(path: Path, metadata: dict[str, object], body: str) -> None:
+    metadata = dict(metadata)
+    metadata.pop("body", None)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_markdown_front_matter(path, metadata, body.rstrip() + "\n")
+
+
+def _ensure_task_bundle(paths: V2Paths, task_id: str) -> None:
+    for directory in (
+        task_dir(paths, task_id),
+        task_plans_dir(paths, task_id),
+        task_questions_dir(paths, task_id),
+        task_todos_dir(paths, task_id),
+        task_links_dir(paths, task_id),
+        task_requirements_dir(paths, task_id),
+        task_runs_dir(paths, task_id),
+        task_changes_dir(paths, task_id),
+        task_artifacts_dir(paths, task_id),
+        task_audit_dir(paths, task_id),
+        task_handoffs_dir(paths, task_id),
+    ):
+        directory.mkdir(parents=True, exist_ok=True)
+
+
+def _write_yaml(path: Path, payload: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(path, yaml.safe_dump(payload, sort_keys=False))
+
+
+def _normalize_numeric_ref(ref: str, prefix: str) -> str:
+    raw_prefix = f"{prefix}-"
+    if not ref.startswith(raw_prefix):
+        return ref
+    suffix = ref.removeprefix(raw_prefix)
+    if not suffix.isdigit():
+        return ref
+    return f"{prefix}-{int(suffix):04d}"
+
+
+def _render_question_body(question: QuestionRecord) -> str:
+    lines = ["## Question", "", question.question.strip()]
+    lines.extend(["", "## Answer", "", (question.answer or "").strip()])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _render_run_body(run: TaskRunRecord) -> str:
+    lines: list[str] = ["## Summary", "", (run.summary or "").strip()]
+    if run.run_type == "validation":
+        lines.extend(["", "## Checks", ""])
+        for check in run.checks:
+            mark = "x" if check.status == "pass" else " "
+            lines.append(f"- [{mark}] {check.name}")
+        lines.extend(["", "## Evidence", ""])
+        for entry in run.evidence:
+            lines.append(f"- {entry}")
+        lines.extend(["", "## Recommendation", "", (run.recommendation or "").strip()])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def list_handoffs(workspace_root: Path, task_id: str) -> list[TaskHandoffRecord]:
+    handoffs, errors = list_handoffs_with_errors(workspace_root, task_id)
+    if errors:
+        raise LaunchError(errors[0])
+    return handoffs
+
+
+def list_handoffs_with_errors(
+    workspace_root: Path,
+    task_id: str,
+) -> tuple[list[TaskHandoffRecord], list[str]]:
+    paths = resolve_v2_paths(workspace_root)
+    handoffs_dir = task_handoffs_dir(paths, task_id)
+    if not handoffs_dir.exists():
+        return [], []
+    result: list[TaskHandoffRecord] = []
+    errors: list[str] = []
+    for md_file in handoffs_dir.glob("*.md"):
+        try:
+            metadata, _ = read_markdown_front_matter(md_file)
+            metadata = dict(metadata)
+            metadata["context_body"] = ""
+            handoff = TaskHandoffRecord.from_dict(metadata)
+            result.append(handoff)
+        except Exception as exc:
+            label = _path_label(workspace_root, md_file)
+            errors.append(f"Malformed handoff record {label}: {exc}")
+    return sorted(result, key=lambda h: h.created_at), errors
+
+
+def resolve_handoff(
+    workspace_root: Path, task_id: str, handoff_ref: str
+) -> TaskHandoffRecord:
+    paths = resolve_v2_paths(workspace_root)
+    path = handoff_markdown_path(paths, task_id, handoff_ref)
+    if not path.exists():
+        raise LaunchError(f"Handoff not found: {handoff_ref}")
+    metadata, body = read_markdown_front_matter(path)
+    metadata = dict(metadata)
+    metadata["context_body"] = body or str(metadata.get("context_body") or "")
+    return TaskHandoffRecord.from_dict(metadata)
+
+
+def _path_label(workspace_root: Path, path: Path) -> str:
+    try:
+        return str(path.relative_to(workspace_root))
+    except ValueError:
+        return str(path)
+
+
+def save_handoff(workspace_root: Path, handoff: TaskHandoffRecord) -> Path:
+    paths = resolve_v2_paths(workspace_root)
+    handoffs_dir = task_handoffs_dir(paths, handoff.task_id)
+    handoffs_dir.mkdir(parents=True, exist_ok=True)
+    path = handoff_markdown_path(paths, handoff.task_id, handoff.handoff_id)
+    metadata = handoff.to_dict()
+    metadata.pop("context_body", None)
+    content = handoff.context_body or ""
+    _write_markdown_record(path, metadata, content)
+    return path
+
+
+def resolve_lock(workspace_root: Path, task_id: str) -> TaskLock | None:
+    """Resolve a lock by task ID."""
+    paths = resolve_v2_paths(workspace_root)
+    lock_path = task_lock_path(paths, task_id)
+    return read_lock(lock_path)
+
+
+def save_lock(workspace_root: Path, task_id: str, lock: TaskLock) -> Path:
+    """Save a lock record (creates if new, updates if exists)."""
+    paths = resolve_v2_paths(workspace_root)
+    lock_path = task_lock_path(paths, task_id)
+    if lock_path.exists():
+        update_lock(lock_path, lock)
+    else:
+        write_lock(lock_path, lock)
+    return lock_path