okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/convergence_provenance.py

@@ -18,8 +18,12 @@ from __future__ import annotations
 import json
 import re
 from pathlib import Path
+from typing import Mapping
 
 from okstra_ctl.convergence_engine import grouped_input_digest
+from okstra_ctl.json_boundary import (
+    load_owned_object,
+)
 
 GROUPS_BASENAME_RE = re.compile(
     r"^convergence-groups-(?P<suffix>[a-z][a-z-]*?-\d{3})\.json$"
@@ -84,7 +88,7 @@ def groups_digest_ok(state_dir: Path, suffix: str, document: dict) -> bool:
     """
     work_path = state_dir / f"convergence-work-{suffix}.json"
     try:
-        work = json.loads(work_path.read_text(encoding="utf-8"))
+        work = load_owned_object(work_path, artifact="convergence work state")
     except (OSError, ValueError):
         return True
     recorded = work.get("groupsDigest") if isinstance(work, dict) else None
@@ -96,10 +100,18 @@ def groups_digest_ok(state_dir: Path, suffix: str, document: dict) -> bool:
 def read_canonical_worker_result(
     worker_results_dir: Path, worker: str, suffix: str
 ) -> str | None:
-    """Return the `<worker>-<suffix>.md` text, or ``None`` when it is not a
-    resolvable file directly inside ``worker-results/`` (missing, unreadable,
-    or a worker slug that is not a single path component)."""
-    candidate = worker_results_dir / f"{worker}-{suffix}.md"
+    """Return the `<worker>-worker-<suffix>.md` text, or ``None`` when it is not
+    a resolvable file directly inside ``worker-results/`` (missing, unreadable,
+    or a worker slug that is not a single path component).
+
+    The literal `-worker` marker comes from the writer,
+    `worker_artifacts.artifacts_from_context`, which names results
+    `f"{worker_id}-worker{result_suffix}.md"` from a bare worker id. Dropping it
+    here made every lookup miss once the roster moved to bare ids, and a missed
+    lookup is silent by design (see `provenance_errors`), so the guard stopped
+    firing without any signal.
+    """
+    candidate = worker_results_dir / f"{worker}-worker-{suffix}.md"
     try:
         if candidate.resolve().parent != worker_results_dir.resolve():
             return None
@@ -141,13 +153,46 @@ def provenance_errors(
         errors.append(
             f"convergence groups `{groups_label}` group {finding_id} "
             f"cites source item `{worker}:{item_id}`, but that ID does not "
-            f"occur in the worker's result file `{worker}-{suffix}.md` — a "
+            f"occur in the worker's result file `{worker}-worker-{suffix}.md` — a "
             "grouping may not invent a provenance link to an item the "
             "worker never reported."
         )
     return errors
 
 
+def worker_result_suffix(run_dir: Path, document: object) -> str | None:
+    """`<task-type>-<seq>` naming the worker results a grouping cites.
+
+    A grouping's own filename carries the **state** sequence, but worker results
+    are named with the **workerResults** sequence — separate counters, both
+    written by `render.render_run_manifest`. They happened to agree on early
+    runs, which is why reusing the groups suffix went unnoticed.
+
+    The link is the grouping's `runManifestPath`, required by
+    `convergence-groups-v2.0.schema.json`. Only its basename is used: the
+    grouping and its run manifest live in the same run directory, so this does
+    not need a project root.
+    """
+    if not isinstance(document, Mapping):
+        return None
+    recorded = document.get("runManifestPath")
+    if not _nonempty_string(recorded):
+        return None
+    manifest_path = Path(run_dir) / "manifests" / Path(str(recorded)).name
+    try:
+        manifest = load_owned_object(manifest_path, artifact="run manifest")
+    except (OSError, ValueError):
+        return None
+    if not isinstance(manifest, Mapping):
+        return None
+    task_type = manifest.get("taskType")
+    sequences = manifest.get("runSequencesByCategory")
+    seq = sequences.get("workerResults") if isinstance(sequences, Mapping) else None
+    if not _nonempty_string(task_type) or not _nonempty_string(seq):
+        return None
+    return f"{task_type}-{seq}"
+
+
 def run_dir_provenance_errors(run_dir: Path) -> list[str]:
     """Provenance errors across every grouping persisted under ``run_dir``.
 
@@ -167,18 +212,23 @@ def run_dir_provenance_errors(run_dir: Path) -> list[str]:
             continue
         suffix = match.group("suffix")
         try:
-            document = json.loads(groups_path.read_text(encoding="utf-8"))
+            document = load_owned_object(
+                groups_path, artifact="convergence groups input"
+            )
         except (OSError, ValueError):
             continue
         if not isinstance(document, dict):
             continue
         if not groups_digest_ok(state_dir, suffix, document):
             continue
+        result_suffix = worker_result_suffix(Path(run_dir), document)
+        if result_suffix is None:
+            continue
         errors.extend(
             provenance_errors(
                 document,
                 worker_results_dir=worker_results_dir,
-                suffix=suffix,
+                suffix=result_suffix,
                 groups_label=groups_path.name,
             )
         )

package/runtime/python/okstra_ctl/convergence_store.py

@@ -1,10 +1,7 @@
 """Validated JSON loading and atomic persistence for convergence artifacts."""
 from __future__ import annotations
 
-import json
-import os
 from pathlib import Path
-import tempfile
 from typing import Any, Mapping
 
 from .convergence_engine import ConvergenceContractError
@@ -14,6 +11,8 @@ from .execution_manifest import (
     read_execution_manifest,
     reserve_derived_role_invocation,
 )
+from .final_report_schema import load_named_schema
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .worker_request import verifier_extra_dirs
 from .write_policy import build_invocation_write_contract
 
@@ -25,44 +24,66 @@ DYNAMIC_VERIFIER_SOURCE_ROLES = frozenset({
     "verifier",
 })
 
+_CRITIC_BATCH_SCHEMA = {
+    "type": "object",
+    "required": [
+        "schemaVersion", "taskKey", "mode", "provider",
+        "modelExecutionValue", "dispatches", "gaps",
+    ],
+    "additionalProperties": False,
+    "properties": {
+        "schemaVersion": {"const": "1.0"},
+        "taskKey": {"type": "string", "pattern": "\\S"},
+        "mode": {"const": "coverage"},
+        "provider": {"type": "string", "pattern": "\\S"},
+        "modelExecutionValue": {"type": "string", "pattern": "\\S"},
+        "dispatches": {"type": "array", "items": {"type": "object"}},
+        "gaps": {"type": "array", "items": {"type": "object"}},
+    },
+}
+
+
+def load_owned_json_object(path: Path) -> dict[str, Any]:
+    try:
+        return load_owned_object(path, artifact="convergence artifact")
+    except JsonBoundaryError as exc:
+        raise ConvergenceContractError(str(exc)) from exc
+
+
+def _load_convergence_result(
+    path: Path, *, schema: Mapping[str, Any]
+) -> dict[str, Any]:
+    try:
+        return load_owned_object(
+            path, artifact="convergence result", schema=schema
+        )
+    except JsonBoundaryError as exc:
+        raise ConvergenceContractError(str(exc)) from exc
+
+
+def load_convergence_round_results(path: Path) -> dict[str, Any]:
+    return _load_convergence_result(
+        path,
+        schema=load_named_schema("convergence-round-results-v1.0.schema.json"),
+    )
+
+
+def load_convergence_critic_batch(path: Path) -> dict[str, Any]:
+    return _load_convergence_result(path, schema=_CRITIC_BATCH_SCHEMA)
+
 
 def load_json_object(path: Path) -> dict[str, Any]:
-    value = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(value, dict):
-        raise ConvergenceContractError(f"JSON input must be an object: {path}")
-    return value
+    """Compatibility alias for convergence artifacts owned by okstra."""
+    return load_owned_json_object(path)
 
 
 def write_json_atomic(path: Path, payload: Mapping[str, Any]) -> None:
     if not isinstance(payload, Mapping):
         raise ConvergenceContractError("JSON output payload must be an object")
-    path.parent.mkdir(parents=True, exist_ok=True)
-    temp_path: Path | None = None
     try:
-        with tempfile.NamedTemporaryFile(
-            mode="w",
-            encoding="utf-8",
-            dir=path.parent,
-            prefix=f".{path.name}.",
-            suffix=".tmp",
-            delete=False,
-        ) as handle:
-            temp_path = Path(handle.name)
-            json.dump(
-                payload,
-                handle,
-                ensure_ascii=False,
-                sort_keys=True,
-                indent=2,
-            )
-            handle.write("\n")
-            handle.flush()
-            os.fsync(handle.fileno())
-        os.replace(temp_path, path)
-        temp_path = None
-    finally:
-        if temp_path is not None:
-            temp_path.unlink(missing_ok=True)
+        write_owned_object_atomic(path, payload, artifact="convergence artifact")
+    except JsonBoundaryError as exc:
+        raise ConvergenceContractError(str(exc)) from exc
 
 
 def write_final_state_atomic(
@@ -111,7 +132,7 @@ def reserve_dynamic_verifier(
         source_role_execution_ref,
         duty_id,
     )
-    authority = load_json_object(manifest_path)
+    authority = load_owned_json_object(manifest_path)
     if authority.get("taskKey") not in (None, task_key):
         raise ExecutionManifestError("dynamic verifier taskKey does not match manifest")
     project_root = _manifest_project_root(authority, manifest_path)

package/runtime/python/okstra_ctl/design_prep.py

@@ -21,6 +21,7 @@ from pathlib import Path
 from typing import Any, Iterator
 
 from .final_report_schema import load_schema, validate as validate_schema
+from .json_boundary import JsonBoundaryError, load_owned_object
 from okstra_project import ResolverError, resolve_project_root
 
 
@@ -166,8 +167,10 @@ def assessment_fingerprint(item: Mapping[str, Any]) -> str:
 
 def _load_plan_data(data_path: Path) -> dict[str, Any]:
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        data = load_owned_object(data_path, artifact="planning report record")
+    except JsonBoundaryError as exc:
+        if exc.reason == "top-level JSON value must be an object":
+            raise DesignPrepError(f"planning data must be an object: {data_path}") from exc
         raise DesignPrepError(f"cannot read planning data {data_path}: {exc}") from exc
     if not isinstance(data, dict):
         raise DesignPrepError(f"planning data must be an object: {data_path}")
@@ -1045,8 +1048,8 @@ def _read_carry(path: Path, stage: int, warnings: list[str]) -> Mapping[str, Any
     if not path.is_file():
         return None
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        payload = load_owned_object(path, artifact="design preparation carry")
+    except JsonBoundaryError as exc:
         warnings.append(f"malformed carry stage {stage}; ignored: {exc}")
         return None
     if not isinstance(payload, Mapping):

package/runtime/python/okstra_ctl/design_snapshot.py

@@ -0,0 +1,134 @@
+"""보고서 서사에서 설계 표면 탐지기 소유 스냅샷을 생성한다."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Mapping
+
+from .convergence_store import write_json_atomic
+from .design_surfaces import DesignSurfaceError, detect_design_surfaces
+from .final_report_schema import load_schema_version
+from .report_narrative import NarrativeContractError, parse_narrative
+
+
+def _evidence(trigger: Any) -> list[dict[str, Any]]:
+    return [
+        {"step": row.step, "field": row.field, "match": row.match}
+        for row in trigger.evidence
+    ]
+
+
+def build_design_snapshot(planning: Mapping[str, Any]) -> dict[str, Any]:
+    """계획 본문에서 재현 가능한 설계 표면과 보수적 준비 항목을 만든다."""
+    triggers = detect_design_surfaces(planning)
+    by_stage: dict[int, list[dict[str, Any]]] = {}
+    items = []
+    for index, trigger in enumerate(triggers, start=1):
+        evidence = _evidence(trigger)
+        prep_id = f"PREP-{index:03d}"
+        evidence_refs = [
+            f"Stage {trigger.stage} step {row['step'] or 'n/a'} "
+            f"{row['field']}={row['match']}"
+            for row in evidence
+        ]
+        by_stage.setdefault(trigger.stage, []).append({
+            "kind": trigger.kind,
+            "triggerEvidence": evidence,
+            "disposition": "prep-item",
+            "prepItemId": prep_id,
+        })
+        items.append({
+            "id": prep_id,
+            "kind": trigger.kind,
+            "title": f"Stage {trigger.stage} {trigger.kind} contract",
+            "stageRefs": [trigger.stage],
+            "status": "provisional",
+            "need": (
+                f"Stage {trigger.stage} touches a {trigger.kind} surface, but the "
+                "detector evidence does not define its implementation contract."
+            ),
+            "knownFacts": [
+                {"statement": "The plan triggered this design surface.", "evidence": ref}
+                for ref in evidence_refs
+            ],
+            "openQuestions": [
+                f"What exact {trigger.kind} contract must Stage {trigger.stage} implement?"
+            ],
+            "aiProposal": {
+                "summary": "Preserve existing behaviour until the contract is confirmed.",
+                "details": [
+                    "Record the concrete contract before an irreversible implementation step."
+                ],
+                "assumptions": [
+                    "Detector evidence proves surface presence, not the missing contract details."
+                ],
+                "evidence": evidence_refs,
+                "confidence": "low",
+            },
+            "humanConfirmation": {
+                "required": True,
+                "reason": "The plan does not contain enough evidence to infer the contract.",
+                "suggestedAction": "confirm-or-edit",
+            },
+            "workingAssumption": "Preserve existing behaviour and avoid irreversible changes.",
+            "guardrails": [
+                "Do not present a synthetic or inferred contract as externally verified."
+            ],
+            "reviewAt": {"phase": "implementation", "stage": trigger.stage},
+            "ifStillOpen": "block",
+            "requestPath": (
+                f"design-prep-requests/design-prep-request-{trigger.stage}-{prep_id}.md"
+            ),
+            "replanTriggerFields": ["aiProposal", "workingAssumption"],
+        })
+    preparation = {
+        "mode": "assessed" if triggers else "no-design-inputs",
+        "reason": (
+            f"Detector found {len(triggers)} design surface(s)."
+            if triggers else "Detector found no design surfaces in the plan."
+        ),
+        "items": items,
+    }
+    return {
+        "schemaVersion": "1.0",
+        "owner": "design-surface-detector",
+        "designPreparation": preparation,
+        "stageCoverage": [
+            {"stage": stage, "rows": rows}
+            for stage, rows in sorted(by_stage.items())
+        ],
+    }
+
+
+def write_snapshot(narrative_path: Path, output_path: Path) -> dict[str, Any]:
+    narrative = parse_narrative(
+        narrative_path.read_text(encoding="utf-8"), load_schema_version("3.0")
+    )
+    planning = narrative.get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        raise DesignSurfaceError("implementationPlanning is missing from narrative")
+    snapshot = build_design_snapshot(planning)
+    write_json_atomic(output_path, snapshot)
+    return snapshot
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra design-snapshot")
+    parser.add_argument("--narrative", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args(argv)
+    try:
+        snapshot = write_snapshot(args.narrative, args.output)
+    except (OSError, UnicodeError, DesignSurfaceError, NarrativeContractError) as exc:
+        print(f"design-snapshot: {exc}", file=sys.stderr)
+        return 2
+    print(json.dumps({"ok": True, "surfaces": sum(
+        len(row["rows"]) for row in snapshot["stageCoverage"]
+    )}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())