okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/convergence.py

@@ -2,8 +2,9 @@
 from __future__ import annotations
 
 import argparse
+from collections.abc import Mapping
 import json
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 import sys
 from typing import Any
 
@@ -32,6 +33,9 @@ from .convergence_store import (
     write_final_state_atomic,
     write_json_atomic,
 )
+from .execution_identity import ExecutionManifest
+from .execution_manifest import read_execution_manifest_view
+from .paths import RunRef
 from .verdict_blocks import FindingVote, VerdictBlockError, parse_finding_votes
 
 
@@ -154,7 +158,7 @@ def _parser() -> argparse.ArgumentParser:
         prog="okstra convergence",
         description="Advance and validate deterministic re-verification state.",
         epilog=(
-            "Working lifecycle: groups v1.0 → work v1.0 → "
+            "Working lifecycle: groups v1.0/v2.0 → work v1.0/v2.0 → "
             "round-plan/results v1.0 → final v1.3\n"
             "historical final readers: v1.0, v1.1, v1.2"
         ),
@@ -188,6 +192,7 @@ def _parser() -> argparse.ArgumentParser:
 
     seed = subparsers.add_parser("seed", help="create, resume, or recover working state")
     seed.add_argument("--groups", type=Path, required=True)
+    seed.add_argument("--run-manifest", type=Path)
     seed.add_argument("--work-state", type=Path, required=True)
     seed.add_argument("--final-state", type=Path, required=True)
     seed.add_argument("--migration-dir", type=Path, required=True)
@@ -314,13 +319,402 @@ def _seeded_groups_provenance_errors(groups_path: Path, document: dict) -> list[
     )
 
 
+def _seed_execution_manifest(
+    groups_path: Path,
+    grouped_input: dict[str, Any],
+    manifest_path: Path | None,
+    work_state_path: Path,
+    final_state_path: Path,
+) -> ExecutionManifest | None:
+    if manifest_path is None:
+        return None
+    manifest, authority = read_execution_manifest_view(manifest_path)
+    if grouped_input.get("schemaVersion") == "2.0":
+        _validate_v2_seed_authority(
+            groups_path,
+            grouped_input,
+            manifest_path,
+            authority,
+            work_state_path,
+            final_state_path,
+            execution_manifest=manifest,
+        )
+    return manifest
+
+
+def _validate_v2_seed_authority(
+    groups_path: Path,
+    grouped_input: dict[str, Any],
+    manifest_path: Path,
+    authority: Mapping[str, Any],
+    work_state_path: Path,
+    final_state_path: Path,
+    *,
+    execution_manifest: ExecutionManifest,
+) -> None:
+    validated = _validated_v2_work_authority(
+        work_state_path,
+        grouped_input,
+        manifest_snapshot=(manifest_path, execution_manifest, authority),
+        path_label="state output",
+    )
+    if validated is None:
+        raise ConvergenceContractError("v2 convergence groups require v2 work authority")
+    _manifest, run_dir, task_type, state_sequence = validated
+    expected_groups_name = _canonical_run_artifact_name(
+        "convergence-groups",
+        task_type,
+        state_sequence,
+    )
+    if groups_path.name != expected_groups_name:
+        raise ConvergenceContractError(
+            "convergence groups filename does not match run authority"
+        )
+    expected_state_dir = run_dir / "state"
+    if groups_path.absolute() != groups_path.resolve():
+        raise ConvergenceContractError("groups artifact path must be canonical")
+    if groups_path.resolve().parent != expected_state_dir:
+        raise ConvergenceContractError(
+            "groups artifact is outside the current run state directory"
+        )
+    _validate_v2_state_artifact_path(
+        final_state_path,
+        state_dir=expected_state_dir,
+        task_type=task_type,
+        state_sequence=state_sequence,
+        prefix="convergence",
+        label="state output",
+    )
+
+
+def _validated_v2_work_authority(
+    work_state_path: Path,
+    state: Mapping[str, Any],
+    *,
+    manifest_snapshot: tuple[
+        Path,
+        ExecutionManifest,
+        Mapping[str, Any],
+    ] | None = None,
+    path_label: str = "working state",
+) -> tuple[ExecutionManifest, Path, str, str] | None:
+    if state.get("schemaVersion") != "2.0":
+        return None
+    if state.get("executionIdentityVersion") != 2:
+        raise ConvergenceContractError(
+            "v2 working state requires executionIdentityVersion 2"
+        )
+    task_key = _manifest_authority_string(state, "taskKey")
+    run_ref = _manifest_authority_string(state, "runManifestPath")
+    project_root = _project_root_for_v2_work_state(work_state_path, path_label)
+    expected_manifest_path = _canonical_project_artifact_path(
+        project_root,
+        run_ref,
+        "working runManifestPath",
+    )
+    if manifest_snapshot is None:
+        execution_manifest, authority = read_execution_manifest_view(
+            expected_manifest_path
+        )
+        manifest_path = expected_manifest_path
+    else:
+        supplied_manifest_path, execution_manifest, authority = manifest_snapshot
+        manifest_path = supplied_manifest_path.resolve()
+        if (
+            supplied_manifest_path.absolute() != manifest_path
+            or manifest_path != expected_manifest_path
+        ):
+            raise ConvergenceContractError(
+                "--run-manifest must use the canonical run manifest path; "
+                "runManifestPath does not match supplied path"
+            )
+    manifest_project_root = _manifest_project_root(authority)
+    if project_root != manifest_project_root:
+        raise ConvergenceContractError(
+            "working state path does not match run manifest projectRoot"
+        )
+    canonical_run_ref = _manifest_run_ref(
+        authority,
+        project_root,
+        manifest_path,
+    )
+    if task_key != authority.get("taskKey"):
+        raise ConvergenceContractError(
+            "working state taskKey does not match run manifest"
+        )
+    if run_ref != canonical_run_ref:
+        raise ConvergenceContractError(
+            "working state runManifestPath does not match run manifest"
+        )
+    run_dir, task_type, state_sequence = _validated_run_artifact_authority(
+        authority,
+        project_root,
+        manifest_path,
+        canonical_run_ref,
+    )
+    _validate_v2_state_artifact_path(
+        work_state_path,
+        state_dir=run_dir / "state",
+        task_type=task_type,
+        state_sequence=state_sequence,
+        prefix="convergence-work",
+        label=path_label,
+    )
+    return execution_manifest, run_dir, task_type, state_sequence
+
+
+def _project_root_for_v2_work_state(
+    work_state_path: Path,
+    path_label: str,
+) -> Path:
+    supplied_path = work_state_path.absolute()
+    resolved_path = work_state_path.resolve()
+    if supplied_path != resolved_path:
+        raise ConvergenceContractError(
+            f"{path_label} path does not match run authority"
+        )
+    for parent in supplied_path.parents:
+        if parent.name == ".okstra":
+            return parent.parent
+    raise ConvergenceContractError(
+        f"{path_label} path does not match run authority"
+    )
+
+
+def _validated_run_artifact_authority(
+    authority: Mapping[str, Any],
+    project_root: Path,
+    manifest_path: Path,
+    run_ref: str,
+) -> tuple[Path, str, str]:
+    run_dir = _manifest_run_directory(authority, project_root, manifest_path)
+    task_type = _manifest_authority_string(authority, "taskType")
+    manifest_sequence = _manifest_sequence(authority, "manifests")
+    expected_name = _canonical_run_artifact_name(
+        "run-manifest",
+        task_type,
+        manifest_sequence,
+    )
+    try:
+        recovered = RunRef.from_run_dir(
+            run_dir,
+            seq=int(manifest_sequence),
+        )
+    except ValueError as exc:
+        raise ConvergenceContractError(
+            "run manifest runDirectoryPath is not a canonical run directory"
+        ) from exc
+    if recovered.project_root != project_root:
+        raise ConvergenceContractError(
+            "run manifest projectRoot does not match recovered run directory"
+        )
+    if recovered.task_type != task_type:
+        raise ConvergenceContractError(
+            "run manifest taskType does not match run directory"
+        )
+    stage = recovered.stage
+    invalid_stage = (
+        (task_type == "implementation" and (stage is None or stage < 1))
+        or (task_type == "final-verification" and stage is not None and stage < 1)
+        or (
+            task_type not in ("implementation", "final-verification")
+            and stage is not None
+        )
+    )
+    if invalid_stage:
+        raise ConvergenceContractError(
+            "run manifest stage semantics do not match taskType"
+        )
+    if recovered.run_dir != run_dir:
+        raise ConvergenceContractError(
+            "run manifest stage does not match runDirectoryPath"
+        )
+    if manifest_path.name != expected_name:
+        raise ConvergenceContractError(
+            "run manifest filename does not match run authority"
+        )
+    if manifest_path != recovered.manifest:
+        raise ConvergenceContractError(
+            "run manifest path does not match runDirectoryPath authority"
+        )
+    expected_ref = recovered.manifest.relative_to(project_root).as_posix()
+    if run_ref != expected_ref:
+        raise ConvergenceContractError(
+            "runManifestPath does not match canonical run authority"
+        )
+    return run_dir, task_type, _manifest_sequence(authority, "state")
+
+
+def _manifest_authority_string(
+    authority: Mapping[str, Any],
+    key: str,
+) -> str:
+    value = authority.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ConvergenceContractError(f"run manifest has no {key}")
+    return value
+
+
+def _manifest_sequence(authority: Mapping[str, Any], category: str) -> str:
+    sequences = authority.get("runSequencesByCategory")
+    if not isinstance(sequences, Mapping):
+        raise ConvergenceContractError(
+            "run manifest has no runSequencesByCategory object"
+        )
+    return _manifest_authority_string(sequences, category)
+
+
+def _canonical_run_artifact_name(
+    prefix: str,
+    task_type: str,
+    sequence: str,
+) -> str:
+    try:
+        sequence_number = int(sequence)
+    except ValueError as exc:
+        raise ConvergenceContractError(
+            "run manifest sequence is not canonical"
+        ) from exc
+    if sequence_number < 1:
+        raise ConvergenceContractError(
+            "run manifest sequence is not canonical"
+        )
+    probe = RunRef(
+        project_root=Path("/"),
+        task_group="group",
+        task_id="task",
+        task_type=task_type,
+        seq=sequence_number,
+    ).manifest.name
+    if not probe.endswith(f"-{sequence}.json"):
+        raise ConvergenceContractError(
+            "run manifest sequence is not canonical"
+        )
+    suffix = probe.removeprefix("run-manifest").removesuffix(".json")
+    return f"{prefix}{suffix}.json"
+
+
+def _manifest_run_directory(
+    authority: Mapping[str, Any],
+    project_root: Path,
+    manifest_path: Path,
+) -> Path:
+    value = _manifest_authority_string(authority, "runDirectoryPath")
+    posix = PurePosixPath(value)
+    if (
+        posix.is_absolute()
+        or posix.as_posix() != value
+        or not posix.parts
+        or posix.parts[0] != ".okstra"
+        or ".." in posix.parts
+    ):
+        raise ConvergenceContractError(
+            "run manifest runDirectoryPath is not canonical"
+        )
+    resolved = (project_root / value).resolve()
+    if not resolved.is_relative_to(project_root):
+        raise ConvergenceContractError(
+            "run manifest runDirectoryPath escapes projectRoot"
+        )
+    if resolved != manifest_path.parent.parent:
+        raise ConvergenceContractError(
+            "run manifest runDirectoryPath does not identify the supplied run"
+        )
+    return resolved
+
+
+def _validate_v2_state_artifact_path(
+    supplied_path: Path,
+    *,
+    state_dir: Path,
+    task_type: str,
+    state_sequence: str,
+    prefix: str,
+    label: str,
+) -> None:
+    expected_path = state_dir / _canonical_run_artifact_name(
+        prefix,
+        task_type,
+        state_sequence,
+    )
+    if (
+        supplied_path.absolute() != supplied_path.resolve()
+        or supplied_path.resolve() != expected_path
+    ):
+        raise ConvergenceContractError(
+            f"{label} path does not match run authority"
+        )
+
+
+def _manifest_project_root(authority: dict[str, Any]) -> Path:
+    value = authority.get("projectRoot")
+    if not isinstance(value, str) or not value.strip():
+        raise ConvergenceContractError("run manifest has no projectRoot")
+    project_root = Path(value)
+    if not project_root.is_absolute() or project_root.absolute() != project_root.resolve():
+        raise ConvergenceContractError("run manifest projectRoot must be canonical")
+    return project_root
+
+
+def _manifest_run_ref(
+    authority: dict[str, Any],
+    project_root: Path,
+    manifest_path: Path,
+) -> str:
+    value = _manifest_authority_string(authority, "runManifestPath")
+    resolved = _canonical_project_artifact_path(
+        project_root,
+        value,
+        "run manifest runManifestPath",
+    )
+    if resolved != manifest_path:
+        raise ConvergenceContractError(
+            "run manifest runManifestPath does not identify the supplied manifest"
+        )
+    return value
+
+
+def _canonical_project_artifact_path(
+    project_root: Path,
+    value: str,
+    label: str,
+) -> Path:
+    posix = PurePosixPath(value)
+    supplied = project_root.joinpath(*posix.parts)
+    resolved = supplied.resolve()
+    if not resolved.is_relative_to(project_root):
+        raise ConvergenceContractError(f"{label} escapes projectRoot")
+    if (
+        posix.is_absolute()
+        or posix.as_posix() != value
+        or not posix.parts
+        or posix.parts[0] != ".okstra"
+        or ".." in posix.parts
+    ):
+        raise ConvergenceContractError(f"{label} is not canonical")
+    if supplied.absolute() != resolved:
+        raise ConvergenceContractError(f"{label} escapes projectRoot")
+    return resolved
+
+
 def _seed(args: argparse.Namespace) -> tuple[str, Path]:
     grouped_input = load_json_object(args.groups)
+    execution_manifest = _seed_execution_manifest(
+        args.groups,
+        grouped_input,
+        args.run_manifest,
+        args.work_state,
+        args.final_state,
+    )
     provenance = _seeded_groups_provenance_errors(args.groups, grouped_input)
     if provenance:
         raise ConvergenceContractError(
             "grouping cites source items no worker reported: " + "; ".join(provenance)
         )
+    state = seed_working_state(
+        grouped_input,
+        execution_manifest=execution_manifest,
+    )
     decision = decide_seed_action(
         grouped_input=grouped_input,
         work_state_path=args.work_state,
@@ -338,7 +732,6 @@ def _seed(args: argparse.Namespace) -> tuple[str, Path]:
         )
         return decision.action, args.work_state
 
-    state = seed_working_state(grouped_input)
     if decision.action == "restart-round0":
         migration = _archive_existing_states(
             work_state_path=args.work_state,
@@ -364,6 +757,7 @@ def _plan_round(args: argparse.Namespace) -> tuple[str, Path]:
 
 def _apply_round(args: argparse.Namespace) -> tuple[str, Path]:
     state = load_json_object(args.work_state)
+    _validated_v2_work_authority(args.work_state, state)
     plan = load_json_object(args.plan)
     results = load_json_object(args.results)
     updated = apply_round_results(state, plan, results)
@@ -376,6 +770,7 @@ def _apply_round(args: argparse.Namespace) -> tuple[str, Path]:
 
 def _apply_critic_gaps(args: argparse.Namespace) -> tuple[str, Path]:
     state = load_json_object(args.work_state)
+    _validated_v2_work_authority(args.work_state, state)
     results = load_json_object(args.results)
     updated = apply_critic_gap_results(state, results)
     write_json_atomic(args.work_state, updated)
@@ -384,6 +779,17 @@ def _apply_critic_gaps(args: argparse.Namespace) -> tuple[str, Path]:
 
 def _finalize(args: argparse.Namespace) -> tuple[str, Path]:
     state = load_json_object(args.work_state)
+    authority = _validated_v2_work_authority(args.work_state, state)
+    if authority is not None:
+        _manifest, run_dir, task_type, state_sequence = authority
+        _validate_v2_state_artifact_path(
+            args.output,
+            state_dir=run_dir / "state",
+            task_type=task_type,
+            state_sequence=state_sequence,
+            prefix="convergence",
+            label="final state",
+        )
     final = finalize_working_state(state)
     migration = state.get("migration")
     write_final_state_atomic(args.output, final, migration=migration)