okstra 0.173.0 → 0.175.1

package/runtime/python/okstra_ctl/attempt_evidence.py

@@ -0,0 +1,342 @@
+"""Atomic attempt evidence seals and orchestrator-owned host event streams."""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .domain.worker_stream import host_event_row
+from .execution_identity import Attempt, ExecutionManifestError
+from .execution_manifest import read_execution_manifest
+from .execution_manifest import _replace_manifest, _write_manifest_over_existing
+from .run_context import task_mutex
+
+
+class AttemptEvidenceError(ValueError):
+    """Raised when an attempt cannot be sealed from the observed terminal state."""
+
+
+def _sha(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass(frozen=True)
+class TerminalObservation:
+    status: str
+    source_diff_digest: str
+    git_projection_digest: str
+    changed_paths: tuple[str, ...]
+    artifact_paths: tuple[Path, ...]
+    host_event_stream_path: Path
+    project_root: Path
+    worktree: Path | None
+    interrupted_before_record: bool = False
+
+
+@dataclass(frozen=True)
+class AttemptEvidenceSeal:
+    seal_ref: str
+    attempt_ref: str
+    captured_at: str
+    source_diff_digest: str
+    git_projection_digest: str
+    changed_paths: tuple[str, ...]
+    host_event_stream: Mapping[str, Any]
+    artifacts: tuple[Mapping[str, Any], ...]
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "sealRef": self.seal_ref,
+            "attemptRef": self.attempt_ref,
+            "capturedAt": self.captured_at,
+            "sourceDiffDigest": self.source_diff_digest,
+            "gitProjectionDigest": self.git_projection_digest,
+            "changedPaths": list(self.changed_paths),
+            "hostEventStream": dict(self.host_event_stream),
+            "hostEventStreamRef": self.host_event_stream.get("path"),
+            "artifacts": [dict(row) for row in self.artifacts],
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "AttemptEvidenceSeal":
+        stream = payload.get("hostEventStream")
+        if not isinstance(stream, Mapping):
+            stream = {}
+        return cls(
+            seal_ref=str(payload["sealRef"]),
+            attempt_ref=str(payload["attemptRef"]),
+            captured_at=str(payload["capturedAt"]),
+            source_diff_digest=str(payload["sourceDiffDigest"]),
+            git_projection_digest=str(payload["gitProjectionDigest"]),
+            changed_paths=tuple(payload.get("changedPaths") or ()),
+            host_event_stream=dict(stream),
+            artifacts=tuple(payload.get("artifacts") or ()),
+        )
+
+
+class HostEventStreamWriter:
+    """Append-only JSONL writer for orchestrator-owned host events."""
+
+    def __init__(
+        self, path: Path, *, invocation_ref: str, attempt: int
+    ) -> None:
+        self.path = path
+        self.invocation_ref = invocation_ref
+        self.attempt = attempt
+        self._sequence = 0
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, event_type: str, payload: Mapping[str, Any]) -> dict[str, Any]:
+        self._sequence += 1
+        row = host_event_row(
+            event_id=f"evt-{self._sequence:04d}",
+            sequence=self._sequence,
+            event_type=event_type,
+            invocation_ref=self.invocation_ref,
+            attempt=self.attempt,
+            payload=payload,
+            timestamp=_utc_now(),
+        )
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+        return row
+
+
+def _split_attempt_ref(attempt_ref: str) -> tuple[str, int]:
+    invocation_ref, sep, raw = attempt_ref.rpartition(":")
+    kind, dash, number = raw.partition("-")
+    if (
+        not sep
+        or kind != "attempt"
+        or dash != "-"
+        or not invocation_ref
+        or not number.isdigit()
+    ):
+        raise AttemptEvidenceError("attemptRef is malformed")
+    return invocation_ref, int(number)
+
+
+def _artifact_rows(paths: Sequence[Path]) -> tuple[dict[str, Any], ...]:
+    rows: list[dict[str, Any]] = []
+    for path in paths:
+        if path.is_symlink():
+            raise AttemptEvidenceError("sealed artifact must not be a symlink")
+        data = path.read_bytes() if path.is_file() else b""
+        rows.append({
+            "kind": "artifact",
+            "normalizedPath": str(path),
+            "byteLength": len(data),
+            "sha256": _sha(data),
+        })
+    return tuple(rows)
+
+
+def _stream_payload(path: Path) -> dict[str, Any]:
+    data = path.read_bytes() if path.is_file() else b""
+    sequences = []
+    event_ids = []
+    for line in data.decode("utf-8").splitlines():
+        if not line.strip():
+            continue
+        row = json.loads(line)
+        sequences.append(int(row["sequence"]))
+        event_ids.append(str(row["eventId"]))
+    low = sequences[0] if sequences else 0
+    high = sequences[-1] if sequences else 0
+    return {
+        "path": str(path),
+        "schemaVersion": "1.0",
+        "byteLength": len(data),
+        "sha256": _sha(data),
+        "sequenceRange": [low, high],
+        "eventIds": event_ids,
+    }
+
+
+def _build_seal(
+    attempt_ref: str, terminal: TerminalObservation
+) -> AttemptEvidenceSeal:
+    stream = _stream_payload(terminal.host_event_stream_path)
+    captured = _utc_now()
+    digest = _sha(
+        json.dumps(
+            {
+                "attemptRef": attempt_ref,
+                "source": terminal.source_diff_digest,
+                "git": terminal.git_projection_digest,
+                "stream": stream["sha256"],
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8")
+    )
+    return AttemptEvidenceSeal(
+        seal_ref=f"seal-{digest[7:23]}",
+        attempt_ref=attempt_ref,
+        captured_at=captured,
+        source_diff_digest=terminal.source_diff_digest,
+        git_projection_digest=terminal.git_projection_digest,
+        changed_paths=terminal.changed_paths,
+        host_event_stream=stream,
+        artifacts=_artifact_rows(terminal.artifact_paths),
+    )
+
+
+def _same_observation(seal: AttemptEvidenceSeal, terminal: TerminalObservation) -> bool:
+    stream = _stream_payload(terminal.host_event_stream_path)
+    return (
+        seal.source_diff_digest == terminal.source_diff_digest
+        and seal.git_projection_digest == terminal.git_projection_digest
+        and seal.host_event_stream.get("sha256") == stream["sha256"]
+    )
+
+
+def finalize_attempt(
+    manifest_path: Path,
+    attempt_ref: str,
+    terminal: TerminalObservation,
+    *,
+    task_key: str,
+) -> AttemptEvidenceSeal:
+    """Seal host events, artifacts, source diff and git projection atomically."""
+    invocation_ref, attempt_number = _split_attempt_ref(attempt_ref)
+    with task_mutex(task_key):
+        manifest = read_execution_manifest(manifest_path)
+        index = next(
+            (
+                offset
+                for offset, row in enumerate(manifest.attempts)
+                if row.invocation_ref == invocation_ref and row.attempt == attempt_number
+            ),
+            None,
+        )
+        if index is None:
+            raise AttemptEvidenceError("attempt to seal is unknown")
+        existing = manifest.attempts[index]
+        if terminal.interrupted_before_record:
+            closed = Attempt(
+                invocation_ref=existing.invocation_ref,
+                attempt=existing.attempt,
+                started_at=existing.started_at,
+                finished_at=_utc_now(),
+                status="evidence-unsealed",
+                result_path=existing.result_path,
+                error_path=existing.error_path,
+                change_summary=dict(existing.change_summary),
+                evidence_seal_ref=None,
+            )
+            attempts = list(manifest.attempts)
+            attempts[index] = closed
+            _write_manifest_over_existing(
+                manifest_path,
+                _replace_manifest(manifest, attempts=tuple(attempts)),
+            )
+            raise AttemptEvidenceError("attempt closed as evidence-unsealed")
+        seal = _build_seal(attempt_ref, terminal)
+        existing_seal = next(
+            (
+                AttemptEvidenceSeal.from_payload(row)
+                for row in manifest.attempt_evidence_seals
+                if row.get("attemptRef") == attempt_ref
+            ),
+            None,
+        )
+        if existing_seal is not None:
+            if not _same_observation(existing_seal, terminal):
+                raise AttemptEvidenceError("attempt already sealed with different observation")
+            return existing_seal
+        closed = Attempt(
+            invocation_ref=existing.invocation_ref,
+            attempt=existing.attempt,
+            started_at=existing.started_at,
+            finished_at=existing.finished_at or _utc_now(),
+            status=terminal.status,
+            result_path=existing.result_path,
+            error_path=existing.error_path,
+            change_summary=dict(existing.change_summary),
+            evidence_seal_ref=seal.seal_ref,
+        )
+        attempts = list(manifest.attempts)
+        attempts[index] = closed
+        updated = _replace_manifest(
+            manifest,
+            attempts=tuple(attempts),
+            attempt_evidence_seals=(
+                *manifest.attempt_evidence_seals,
+                seal.to_payload(),
+            ),
+        )
+        _write_manifest_over_existing(manifest_path, updated)
+        return seal
+
+
+def reject_unsealed_attempt(
+    manifest_path: Path,
+    attempt_ref: str,
+    original_baseline_digest: str,
+    *,
+    task_key: str,
+):
+    """Close an unsealed attempt and record a cleanup-only reject."""
+    from .mutation_recovery import MutationRecoveryDecision
+
+    invocation_ref, attempt_number = _split_attempt_ref(attempt_ref)
+    with task_mutex(task_key):
+        manifest = read_execution_manifest(manifest_path)
+        index = next(
+            (
+                offset
+                for offset, row in enumerate(manifest.attempts)
+                if row.invocation_ref == invocation_ref and row.attempt == attempt_number
+            ),
+            None,
+        )
+        if index is None:
+            raise AttemptEvidenceError("attempt to reject is unknown")
+        existing = manifest.attempts[index]
+        closed = Attempt(
+            invocation_ref=existing.invocation_ref,
+            attempt=existing.attempt,
+            started_at=existing.started_at,
+            finished_at=existing.finished_at or _utc_now(),
+            status="evidence-unsealed",
+            result_path=existing.result_path,
+            error_path=existing.error_path,
+            change_summary=dict(existing.change_summary),
+            evidence_seal_ref=None,
+        )
+        decision = MutationRecoveryDecision(
+            recovery_ref=f"recovery-unsealed-{attempt_number}",
+            source_invocation_ref=invocation_ref,
+            source_attempt_ref=attempt_ref,
+            source_evidence_seal_ref=None,
+            original_baseline_digest=original_baseline_digest,
+            terminal_source_diff_digest="",
+            terminal_git_chain_digest="",
+            verifier_role_execution_ref=None,
+            verifier_invocation_ref=None,
+            recovered_evidence_refs=(),
+            recovered_out_of_plan_edits=(),
+            unmet_obligations=("evidence-unsealed",),
+            decision="reject",
+            reason="evidence-unsealed",
+        )
+        attempts = list(manifest.attempts)
+        attempts[index] = closed
+        updated = _replace_manifest(
+            manifest,
+            attempts=tuple(attempts),
+            mutation_recovery_decisions=(
+                *manifest.mutation_recovery_decisions,
+                decision.to_payload(),
+            ),
+        )
+        _write_manifest_over_existing(manifest_path, updated)
+        return decision

package/runtime/python/okstra_ctl/conformance.py

@@ -25,6 +25,74 @@ EXTERNAL_ADVISORY_CAPABILITIES: frozenset[str] = frozenset(
 )
 
 
+# --- 계획 산출물의 stage conformance 선언 파싱 ---
+#
+# 정본 형식은 prompts/profiles/implementation-planning.md 의
+# `Conformance tests: stage-<N> — <script> (requires=[db|io|http|external,...])`
+# 이고, data.json 의 `conformanceTests` 는 그 줄에서 `stage-<N> — ` 접두사를 뗀
+# 나머지다. 승인 경계(run.py `_validate_approved_plan`)와 구현 런 끝
+# (validators/validate-run.py)이 이 한 규칙을 같이 읽는다 — 규칙을 두 곳에
+# 복제하면 승인은 통과하는데 구현 런은 막히는 상태가 다시 만들어진다.
+_CONFORMANCE_TESTS_RE = re.compile(
+    r"^(?P<script>\S+)\s+\(requires=\[(?P<requires>[^\]]+)\]\)$"
+)
+
+
+def normalize_conformance_script(script: str) -> str:
+    """`<task_root>/` 접두사를 뗀다. 선언과 매니페스트 entry 가 같은 스크립트를
+    서로 다른 접두사로 적을 수 있어, 대조 전에 양쪽을 이 형태로 맞춘다."""
+    prefix = "<task_root>/"
+    return script[len(prefix):] if script.startswith(prefix) else script
+
+
+def parse_conformance_tests(value: object) -> tuple[str, frozenset[str]] | None:
+    """stage 선언의 `<script> (requires=[cap,...])` 를 파싱. 형식이 아니면 None."""
+    if not isinstance(value, str):
+        return None
+    match = _CONFORMANCE_TESTS_RE.fullmatch(value.strip())
+    if match is None:
+        return None
+    script = normalize_conformance_script(match.group("script"))
+    capabilities = [part.strip() for part in match.group("requires").split(",")]
+    if (
+        not script
+        or any(not capability for capability in capabilities)
+        or len(set(capabilities)) != len(capabilities)
+        or any(capability not in CAPABILITY_WHITELIST for capability in capabilities)
+    ):
+        return None
+    return script, frozenset(capabilities)
+
+
+def malformed_conformance_stages(data: object) -> list[int]:
+    """`conformanceTests` 를 선언했으나 파싱되지 않는 stage 번호들.
+
+    선언이 아예 없는 stage 는 대상이 아니다 — 둘 중 하나를 요구하는 XOR 은
+    validators/validate-implementation-plan-stages.py 의 check S11 이 계획
+    단계에서 이미 판정한다. `stage` 가 양의 정수가 아닌 경우도 여기 몫이 아니다:
+    스키마(`stage: integer, minimum 1`)가 계획 런의 validate-run 에서 먼저 막는다.
+    `conformanceTests` 가 문자열이 아닌 경우도 같은 이유로 뺀다 — 스키마가
+    `type: string, minLength: 1` 로 못박아 그 값은 계획 런의 validate-run 을
+    통과하지 못한다. 여기서 그것까지 malformed 로 세면 스키마가 이미 낸 판정을
+    이 게이트가 다른 문구로 되풀이한다.
+    """
+    planning = data.get("implementationPlanning") if isinstance(data, dict) else None
+    stages = planning.get("stages") if isinstance(planning, dict) else None
+    bad: list[int] = []
+    for stage in stages if isinstance(stages, list) else []:
+        if not isinstance(stage, dict):
+            continue
+        declared = stage.get("conformanceTests")
+        if not isinstance(declared, str) or not declared.strip():
+            continue
+        number = stage.get("stage")
+        if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+            continue
+        if parse_conformance_tests(declared) is None:
+            bad.append(number)
+    return bad
+
+
 def is_advisory_conformance_entry(entry: object) -> bool:
     """Return whether one entry depends on user-owned external QA."""
     if not isinstance(entry, dict):