okstra 0.167.0 → 0.169.0

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -0,0 +1,1502 @@
+"""Compose and verify auditable LLM invocation specifications."""
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+from pathlib import PurePosixPath
+import re
+import tempfile
+from typing import Iterator, Literal, Mapping, get_args
+
+
+AgentAudience = Literal[
+    "lead",
+    "analysis-worker",
+    "implementation-executor",
+    "implementation-verifier",
+    "acceptance-verifier",
+    "reverification-worker",
+    "scope-critic",
+    "acceptance-critic",
+    "report-writer",
+    "translator",
+    "code-reviewer",
+    "schedule-verifier",
+]
+
+_SUPPORTED_AUDIENCES = frozenset(get_args(AgentAudience))
+_SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_TOP_LEVEL_KEYS = {
+    "schemaVersion",
+    "invocationId",
+    "audience",
+    "dispatchKind",
+    "workerId",
+    "assignmentRef",
+    "contractSource",
+    "modelAssignment",
+    "dutyContract",
+    "instruction",
+    "prompt",
+    "digests",
+}
+_NESTED_KEYS = {
+    "contractSource": {"mode", "runManifestPath", "dutyRootPath"},
+    "modelAssignment": {
+        "provider",
+        "model",
+        "modelExecutionValue",
+        "runner",
+        "hostRuntime",
+        "hostModelValue",
+    },
+    "dutyContract": {"id", "version"},
+    "instruction": {"sourcePaths"},
+    "prompt": {"path"},
+    "digests": {
+        "catalogDigest",
+        "assignmentDigest",
+        "dutyDigest",
+        "instructionDigest",
+        "promptDigest",
+    },
+}
+
+
+class AgentInvocationError(RuntimeError):
+    """Raised when an invocation contract cannot be safely materialized."""
+
+    def __init__(self, message: str, *, reason: str = "invalid_agent_invocation"):
+        super().__init__(message)
+        self.reason = reason
+
+
+@dataclass(frozen=True)
+class DutyContract:
+    id: str
+    version: int
+    kind: Literal["common", "role"]
+    applies_to: AgentAudience | None
+    body: str
+    source_path: Path
+
+
+@dataclass(frozen=True)
+class AgentModelAssignment:
+    provider: str
+    model: str
+    model_execution_value: str
+    runner: str
+    host_runtime: str
+    host_model_value: str | None
+
+
+@dataclass(frozen=True)
+class AgentInstructionSource:
+    kind: Literal["project", "runtime"]
+    path: str
+
+
+@dataclass(frozen=True)
+class AgentInstruction:
+    anchor_lines: tuple[str, ...]
+    body: str
+    source_paths: tuple[AgentInstructionSource, ...]
+
+
+@dataclass(frozen=True)
+class AgentInvocationRequest:
+    invocation_id: str
+    worker_id: str | None
+    audience: AgentAudience
+    assignment_ref: str | None
+    purpose: str | None
+    assignment: AgentModelAssignment
+    instruction: AgentInstruction
+    project_root: Path
+    run_manifest_path: Path | None
+    duty_root: Path
+    prompt_path: Path
+    metadata_path: Path
+    dispatch_kind: str
+
+
+@dataclass(frozen=True)
+class PreparedAgentInvocation:
+    invocation_id: str
+    worker_id: str | None
+    assignment_ref: str | None
+    prompt_path: Path
+    metadata_path: Path
+    assignment: AgentModelAssignment
+    duty_id: str
+    duty_version: int
+    catalog_digest: str
+    assignment_digest: str
+    duty_digest: str
+    instruction_digest: str
+    prompt_digest: str
+
+
+@dataclass(frozen=True)
+class MaterializedStandaloneResult:
+    purpose: str
+    invocation_id: str
+    prompt_metadata_path: Path
+    result_path: Path
+    result_envelope_digest: str
+
+
+@dataclass(frozen=True)
+class VerifiedStandaloneResult:
+    purpose: str
+    invocation_id: str
+    prompt_metadata_path: Path
+    result_path: Path
+    completion_path: Path
+    result_envelope_digest: str
+    returned_body: str
+
+
+def agent_model_assignment_from_payload(payload: object) -> AgentModelAssignment:
+    """Parse the exact persisted six-field model assignment contract."""
+    if not isinstance(payload, Mapping) or set(payload) != _NESTED_KEYS["modelAssignment"]:
+        raise AgentInvocationError("model assignment payload is invalid")
+    string_fields = (
+        "provider",
+        "model",
+        "modelExecutionValue",
+        "runner",
+        "hostRuntime",
+    )
+    if any(not isinstance(payload[key], str) for key in string_fields):
+        raise AgentInvocationError("model assignment payload is invalid")
+    host_model_value = payload["hostModelValue"]
+    if host_model_value is not None and not isinstance(host_model_value, str):
+        raise AgentInvocationError("model assignment payload is invalid")
+    assignment = AgentModelAssignment(
+        provider=payload["provider"],
+        model=payload["model"],
+        model_execution_value=payload["modelExecutionValue"],
+        runner=payload["runner"],
+        host_runtime=payload["hostRuntime"],
+        host_model_value=host_model_value,
+    )
+    _validate_assignment(assignment)
+    return assignment
+
+
+@dataclass(frozen=True)
+class _MaterializedInvocation:
+    prepared: PreparedAgentInvocation
+    prompt_bytes: bytes
+    metadata: dict[str, object]
+    metadata_bytes: bytes
+    reservation_root: Path | None
+    reservation: dict[str, object] | None
+
+
+def load_common_duty_contract(duty_root: Path) -> DutyContract:
+    """Load the common fragment, which is deliberately outside the role catalog."""
+    path = duty_root / "common.md"
+    fields, body = _parse_duty_file(path)
+    if set(fields) != {"id", "version", "kind"}:
+        raise AgentInvocationError(f"invalid common duty frontmatter: {path}")
+    if fields["id"] != "common" or fields["kind"] != "common":
+        raise AgentInvocationError(f"invalid common duty frontmatter: {path}")
+    return DutyContract(
+        id="common",
+        version=_parse_version(fields["version"], path),
+        kind="common",
+        applies_to=None,
+        body=body,
+        source_path=path,
+    )
+
+
+def load_duty_catalog(duty_root: Path) -> dict[AgentAudience, DutyContract]:
+    """Load one role contract for every supported invocation audience."""
+    catalog: dict[AgentAudience, DutyContract] = {}
+    seen_ids: set[str] = set()
+    for path in sorted(duty_root.glob("*.md")):
+        if path.name == "common.md":
+            continue
+        duty = _load_role_duty(path)
+        if duty.id in seen_ids:
+            raise AgentInvocationError(f"duplicate duty id: {duty.id}")
+        if duty.applies_to in catalog:
+            raise AgentInvocationError(f"duplicate duty audience: {duty.applies_to}")
+        seen_ids.add(duty.id)
+        catalog[duty.applies_to] = duty
+    missing = sorted(_SUPPORTED_AUDIENCES - set(catalog))
+    if missing:
+        raise AgentInvocationError(f"missing duty audiences: {', '.join(missing)}")
+    return catalog
+
+
+def digest_duty_catalog(duty_root: Path) -> str:
+    """Return the canonical digest of every duty file in a snapshot."""
+    names = [path.relative_to(duty_root).as_posix() for path in duty_root.glob("*.md")]
+    return _digest_framed_files(duty_root, names)
+
+
+def prepare_agent_invocation(
+    request: AgentInvocationRequest,
+) -> PreparedAgentInvocation:
+    """Materialize one immutable prompt and its adjacent completion metadata."""
+    _validate_request(request)
+    materialized = _materialize(request)
+    if materialized.reservation_root is None:
+        with _exclusive_lock(_prompt_lock_path(request.prompt_path)):
+            _publish_or_reuse(materialized)
+    else:
+        reservation_lock = materialized.reservation_root / "publish.lock"
+        with _exclusive_lock(reservation_lock):
+            _publish_or_reuse_reservation(materialized)
+            with _exclusive_lock(_prompt_lock_path(request.prompt_path)):
+                _publish_or_reuse(materialized)
+    errors = verify_agent_invocation(
+        request.metadata_path,
+        project_root=request.project_root,
+        expected_run_manifest_path=request.run_manifest_path,
+        expected_assignment=request.assignment,
+        expected_invocation_id=request.invocation_id,
+        expected_worker_id=request.worker_id,
+        expected_assignment_ref=request.assignment_ref,
+        expected_audience=request.audience,
+    )
+    if errors:
+        raise AgentInvocationError("; ".join(errors))
+    return materialized.prepared
+
+
+def compose_agent_prompt(request: AgentInvocationRequest) -> str:
+    """Render and validate a prompt candidate without publishing artifacts."""
+    _validate_request(request)
+    return _materialize(request).prompt_bytes.decode("utf-8")
+
+
+def verify_agent_invocation(
+    metadata_path: Path,
+    *,
+    project_root: Path,
+    expected_run_manifest_path: Path | None,
+    expected_assignment: AgentModelAssignment | None = None,
+    expected_invocation_id: str | None = None,
+    expected_worker_id: str | None = None,
+    expected_assignment_ref: str | None = None,
+    expected_audience: AgentAudience | None = None,
+) -> list[str]:
+    """Return every deterministic violation found in a published invocation."""
+    metadata = _read_metadata(metadata_path)
+    if metadata is None or not _metadata_schema_is_exact(metadata):
+        return ["agent invocation metadata schema is invalid"]
+    errors = _verify_expected_identity(
+        metadata,
+        expected_invocation_id=expected_invocation_id,
+        expected_worker_id=expected_worker_id,
+        expected_assignment_ref=expected_assignment_ref,
+        expected_audience=expected_audience,
+    )
+    errors.extend(_verify_prompt_file(metadata, project_root))
+    errors.extend(_verify_assignment(metadata, expected_assignment))
+    errors.extend(
+        _verify_contract_source(
+            metadata,
+            metadata_path=metadata_path,
+            project_root=project_root,
+            expected_run_manifest_path=expected_run_manifest_path,
+        )
+    )
+    return _deduplicate(errors)
+
+
+def materialize_standalone_result(
+    *,
+    project_root: Path,
+    purpose: str,
+    metadata_path: Path,
+    returned_body: bytes,
+) -> MaterializedStandaloneResult:
+    """Publish one immutable raw-return envelope for a standalone invocation."""
+    try:
+        returned_text = returned_body.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise AgentInvocationError("returned body must be valid UTF-8") from exc
+    invocation_id, root = _standalone_lock_identity(
+        project_root=project_root, purpose=purpose, metadata_path=metadata_path,
+    )
+    with _exclusive_lock(root / f"{invocation_id}.result.publish.lock"):
+        invocation_id, root, canonical_metadata = _standalone_authority(
+            project_root=project_root,
+            purpose=purpose,
+            metadata_path=metadata_path,
+        )
+        result_path = root / f"{invocation_id}.result.json"
+        envelope = {
+            "schemaVersion": 1,
+            "purpose": purpose,
+            "invocationId": invocation_id,
+            "promptMetadataPath": _project_relative(
+                canonical_metadata,
+                project_root,
+                must_exist=True,
+            ),
+            "returnedBody": returned_text,
+        }
+        envelope_bytes = _canonical_json(envelope)
+        _publish_exclusive(result_path, envelope_bytes)
+    return MaterializedStandaloneResult(
+        purpose=purpose,
+        invocation_id=invocation_id,
+        prompt_metadata_path=canonical_metadata,
+        result_path=result_path,
+        result_envelope_digest=_sha256(envelope_bytes),
+    )
+
+
+def publish_standalone_completion(
+    *,
+    project_root: Path,
+    purpose: str,
+    metadata_path: Path,
+    completed_at: datetime,
+) -> Path:
+    """Publish the completion marker last, after re-verifying prompt and result."""
+    completed = _utc_seconds(completed_at)
+    invocation_id, root = _standalone_lock_identity(
+        project_root=project_root, purpose=purpose, metadata_path=metadata_path,
+    )
+    with _exclusive_lock(root / f"{invocation_id}.result.publish.lock"):
+        invocation_id, root, canonical_metadata = _standalone_authority(
+            project_root=project_root,
+            purpose=purpose,
+            metadata_path=metadata_path,
+        )
+        result_path = root / f"{invocation_id}.result.json"
+        completion_path = root / f"{invocation_id}.prompt.md.completion.json"
+        envelope_bytes, _returned_body = _verified_result_envelope(
+            result_path,
+            project_root=project_root,
+            purpose=purpose,
+            invocation_id=invocation_id,
+            metadata_path=canonical_metadata,
+        )
+        completion = {
+            "schemaVersion": 1,
+            "purpose": purpose,
+            "invocationId": invocation_id,
+            "status": "completed",
+            "promptMetadataPath": _project_relative(
+                canonical_metadata,
+                project_root,
+                must_exist=True,
+            ),
+            "resultPath": _project_relative(
+                result_path,
+                project_root,
+                must_exist=True,
+            ),
+            "resultEnvelopeDigest": _sha256(envelope_bytes),
+            "completedAt": completed,
+        }
+        _publish_exclusive(completion_path, _canonical_json(completion))
+    return completion_path
+
+
+def verify_standalone_completion(
+    completion_path: Path,
+    *,
+    project_root: Path,
+    expected_purpose: str,
+) -> VerifiedStandaloneResult:
+    """Verify a completion marker and return its already-read immutable body."""
+    _validate_slug(expected_purpose, "standalone purpose")
+    completion = _load_json_object(completion_path, "standalone completion")
+    expected_keys = {
+        "schemaVersion",
+        "purpose",
+        "invocationId",
+        "status",
+        "promptMetadataPath",
+        "resultPath",
+        "resultEnvelopeDigest",
+        "completedAt",
+    }
+    if set(completion) != expected_keys or completion.get("schemaVersion") != 1:
+        raise AgentInvocationError("standalone completion schema is invalid")
+    if completion.get("purpose") != expected_purpose:
+        raise AgentInvocationError("standalone completion purpose does not match")
+    invocation_id = completion.get("invocationId")
+    if not isinstance(invocation_id, str):
+        raise AgentInvocationError("standalone completion invocation ID is invalid")
+    _validate_slug(invocation_id, "standalone invocation ID")
+    root = project_root / ".okstra" / "agent-invocations" / expected_purpose
+    canonical_completion = root / f"{invocation_id}.prompt.md.completion.json"
+    if completion_path.resolve(strict=True) != canonical_completion.resolve(strict=True):
+        raise AgentInvocationError("standalone completion path is not canonical")
+    metadata_path = root / f"{invocation_id}.prompt.md.meta.json"
+    result_path = root / f"{invocation_id}.result.json"
+    if completion.get("status") != "completed":
+        raise AgentInvocationError("standalone completion status is invalid")
+    if completion.get("promptMetadataPath") != _project_relative(
+        metadata_path,
+        project_root,
+        must_exist=True,
+    ):
+        raise AgentInvocationError("standalone completion metadata path does not match")
+    if completion.get("resultPath") != _project_relative(
+        result_path,
+        project_root,
+        must_exist=True,
+    ):
+        raise AgentInvocationError("standalone completion result path does not match")
+    with _exclusive_lock(root / f"{invocation_id}.result.publish.lock"):
+        authority_id, _authority_root, canonical_metadata = _standalone_authority(
+            project_root=project_root,
+            purpose=expected_purpose,
+            metadata_path=metadata_path,
+        )
+        if authority_id != invocation_id:
+            raise AgentInvocationError("standalone completion identity does not match")
+        envelope_bytes, returned_body = _verified_result_envelope(
+            result_path,
+            project_root=project_root,
+            purpose=expected_purpose,
+            invocation_id=invocation_id,
+            metadata_path=canonical_metadata,
+        )
+        digest = _sha256(envelope_bytes)
+        if completion.get("resultEnvelopeDigest") != digest:
+            raise AgentInvocationError("result envelope digest does not match completion")
+    return VerifiedStandaloneResult(
+        purpose=expected_purpose,
+        invocation_id=invocation_id,
+        prompt_metadata_path=metadata_path,
+        result_path=result_path,
+        completion_path=canonical_completion,
+        result_envelope_digest=digest,
+        returned_body=returned_body,
+    )
+
+
+def _standalone_authority(
+    *, project_root: Path, purpose: str, metadata_path: Path,
+) -> tuple[str, Path, Path]:
+    _validate_slug(purpose, "standalone purpose")
+    root = project_root / ".okstra" / "agent-invocations" / purpose
+    metadata = _load_json_object(metadata_path, "agent invocation metadata")
+    source = metadata.get("contractSource")
+    if not isinstance(source, Mapping) or source.get("mode") != "standalone":
+        raise AgentInvocationError("result completion requires standalone metadata")
+    invocation_id = metadata.get("invocationId")
+    if not isinstance(invocation_id, str):
+        raise AgentInvocationError("standalone invocation ID is invalid")
+    _validate_slug(invocation_id, "standalone invocation ID")
+    canonical_metadata = root / f"{invocation_id}.prompt.md.meta.json"
+    if metadata_path.resolve(strict=True) != canonical_metadata.resolve(strict=True):
+        raise AgentInvocationError("standalone metadata path is not canonical")
+    errors = verify_agent_invocation(
+        canonical_metadata,
+        project_root=project_root,
+        expected_run_manifest_path=None,
+        expected_invocation_id=invocation_id,
+    )
+    if errors:
+        raise AgentInvocationError("; ".join(errors))
+    return invocation_id, root, canonical_metadata
+
+
+def _standalone_lock_identity(
+    *, project_root: Path, purpose: str, metadata_path: Path,
+) -> tuple[str, Path]:
+    """Derive only the stable lock name; verify all authority after locking."""
+    _validate_slug(purpose, "standalone purpose")
+    suffix = ".prompt.md.meta.json"
+    if not metadata_path.name.endswith(suffix):
+        raise AgentInvocationError("standalone metadata path is not canonical")
+    invocation_id = metadata_path.name.removesuffix(suffix)
+    _validate_slug(invocation_id, "standalone invocation ID")
+    return invocation_id, project_root / ".okstra" / "agent-invocations" / purpose
+
+
+def _verified_result_envelope(
+    result_path: Path,
+    *,
+    project_root: Path,
+    purpose: str,
+    invocation_id: str,
+    metadata_path: Path,
+) -> tuple[bytes, str]:
+    try:
+        body = result_path.read_bytes()
+        envelope = json.loads(body.decode("utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise AgentInvocationError(
+            f"standalone result envelope is missing or invalid: {result_path}"
+        ) from exc
+    expected_keys = {
+        "schemaVersion", "purpose", "invocationId", "promptMetadataPath", "returnedBody",
+    }
+    expected_metadata = _project_relative(
+        metadata_path,
+        project_root,
+        must_exist=True,
+    )
+    if (
+        not isinstance(envelope, dict)
+        or set(envelope) != expected_keys
+        or envelope.get("schemaVersion") != 1
+        or envelope.get("purpose") != purpose
+        or envelope.get("invocationId") != invocation_id
+        or envelope.get("promptMetadataPath") != expected_metadata
+        or not isinstance(envelope.get("returnedBody"), str)
+    ):
+        raise AgentInvocationError("standalone result envelope contract does not match")
+    if body != _canonical_json(envelope):
+        raise AgentInvocationError("standalone result envelope is not canonical JSON")
+    return body, envelope["returnedBody"]
+
+
+def _validate_slug(value: str, label: str) -> None:
+    if not _SLUG_RE.fullmatch(value):
+        raise AgentInvocationError(f"{label} must be a slug")
+
+
+def _utc_seconds(value: datetime) -> str:
+    if value.tzinfo is None or value.utcoffset() != timezone.utc.utcoffset(value):
+        raise AgentInvocationError("completedAt must be a UTC datetime")
+    return value.astimezone(timezone.utc).replace(microsecond=0).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+
+
+def _materialize(request: AgentInvocationRequest) -> _MaterializedInvocation:
+    common = load_common_duty_contract(request.duty_root)
+    catalog = load_duty_catalog(request.duty_root)
+    duty = catalog[request.audience]
+    prompt_bytes = _render_prompt(request, common, duty).encode("utf-8")
+    digests = _invocation_digests(request, duty, prompt_bytes)
+    metadata = _metadata_payload(request, duty, digests)
+    prepared = PreparedAgentInvocation(
+        invocation_id=request.invocation_id,
+        worker_id=request.worker_id,
+        assignment_ref=request.assignment_ref,
+        prompt_path=request.prompt_path,
+        metadata_path=request.metadata_path,
+        assignment=request.assignment,
+        duty_id=duty.id,
+        duty_version=duty.version,
+        catalog_digest=digests["catalogDigest"],
+        assignment_digest=digests["assignmentDigest"],
+        duty_digest=digests["dutyDigest"],
+        instruction_digest=digests["instructionDigest"],
+        prompt_digest=digests["promptDigest"],
+    )
+    reservation_root, reservation = _reservation_spec(request)
+    return _MaterializedInvocation(
+        prepared=prepared,
+        prompt_bytes=prompt_bytes,
+        metadata=metadata,
+        metadata_bytes=_pretty_json(metadata),
+        reservation_root=reservation_root,
+        reservation=reservation,
+    )
+
+
+def _validate_request(request: AgentInvocationRequest) -> None:
+    if request.audience not in _SUPPORTED_AUDIENCES:
+        raise AgentInvocationError(f"unknown duty audience: {request.audience}")
+    adjacent = request.prompt_path.with_name(request.prompt_path.name + ".meta.json")
+    if request.metadata_path != adjacent:
+        raise AgentInvocationError("metadata path must be adjacent to prompt path")
+    _validate_assignment(request.assignment)
+    _validate_instruction(request.instruction)
+    _project_relative(request.duty_root, request.project_root, must_exist=True)
+    _project_relative(request.prompt_path, request.project_root, must_exist=False)
+    _project_relative(request.metadata_path, request.project_root, must_exist=False)
+    if request.run_manifest_path is None:
+        _validate_standalone_identity(request)
+    else:
+        _validate_run_identity(request)
+
+
+def _validate_assignment(assignment: AgentModelAssignment) -> None:
+    values = (
+        assignment.provider,
+        assignment.model,
+        assignment.model_execution_value,
+        assignment.runner,
+        assignment.host_runtime,
+    )
+    if any(not value.strip() for value in values):
+        raise AgentInvocationError("model assignment fields must be non-empty")
+    if assignment.runner == "native-session" and not assignment.host_model_value:
+        raise AgentInvocationError("native assignment requires a host model value")
+    if assignment.runner == "cli-wrapper" and assignment.host_model_value is not None:
+        raise AgentInvocationError("CLI assignment must not define a host model value")
+
+
+def _validate_instruction(instruction: AgentInstruction) -> None:
+    if re.search(r"(?m)^## (?:Duty Contract|Task Instructions)\s*$", instruction.body):
+        raise AgentInvocationError("task instruction contains a reserved duty heading")
+    if any("\n" in line for line in instruction.anchor_lines):
+        raise AgentInvocationError("instruction anchorLines must be single lines")
+    normalized = [_source_payload(source) for source in instruction.source_paths]
+    if not normalized or len({_canonical_json(item) for item in normalized}) != len(normalized):
+        raise AgentInvocationError("instruction sourcePaths must be non-empty and unique")
+
+
+def _validate_standalone_identity(request: AgentInvocationRequest) -> None:
+    if not request.purpose or not _SLUG_RE.fullmatch(request.purpose):
+        raise AgentInvocationError("standalone purpose must be a slug")
+    if not _SLUG_RE.fullmatch(request.invocation_id):
+        raise AgentInvocationError("standalone invocation ID must be a slug")
+    if request.worker_id is not None or request.assignment_ref is not None:
+        raise AgentInvocationError("standalone invocation cannot bind a run worker")
+    root = (
+        request.project_root
+        / ".okstra"
+        / "agent-invocations"
+        / request.purpose
+    )
+    expected_prompt = root / f"{request.invocation_id}.prompt.md"
+    expected_duty = root / f"{request.invocation_id}.duty-contracts"
+    if request.prompt_path != expected_prompt or request.duty_root != expected_duty:
+        raise AgentInvocationError("prompt does not use canonical standalone path")
+
+
+def _validate_run_identity(request: AgentInvocationRequest) -> None:
+    if request.purpose is not None:
+        raise AgentInvocationError("run invocation cannot define standalone purpose")
+    if not request.worker_id or not _SLUG_RE.fullmatch(request.worker_id):
+        raise AgentInvocationError("run worker ID must be a non-empty slug")
+    if not request.assignment_ref:
+        raise AgentInvocationError("run assignment reference is required")
+    _project_relative(
+        request.run_manifest_path,
+        request.project_root,
+        must_exist=True,
+    )
+    suffix = request.assignment_ref.partition("/")[2]
+    if suffix and request.assignment_ref.split("/", 1)[0] in {"initial", "reverify"}:
+        if suffix != request.worker_id:
+            raise AgentInvocationError("run worker ID does not match assignment reference")
+
+
+def _render_prompt(
+    request: AgentInvocationRequest,
+    common: DutyContract,
+    duty: DutyContract,
+) -> str:
+    assignment = request.assignment
+    header = [
+        *request.instruction.anchor_lines,
+        f"**Provider:** {assignment.provider}",
+        f"**Model:** {assignment.model}",
+        f"**Model execution value:** {assignment.model_execution_value}",
+        f"**Runner:** {assignment.runner}",
+        f"**Host runtime:** {assignment.host_runtime}",
+    ]
+    if assignment.host_model_value is not None:
+        header.append(f"**Host model value:** {assignment.host_model_value}")
+    duty_body = f"{common.body.rstrip()}\n\n{duty.body.rstrip()}"
+    task_body = request.instruction.body.rstrip("\n")
+    return (
+        "\n".join(header)
+        + "\n\n## Duty Contract\n\n"
+        + duty_body
+        + "\n\n## Task Instructions\n\n"
+        + task_body
+        + "\n"
+    )
+
+
+def _invocation_digests(
+    request: AgentInvocationRequest,
+    duty: DutyContract,
+    prompt_bytes: bytes,
+) -> dict[str, str]:
+    assignment = _assignment_payload(request.assignment)
+    instruction = {
+        "anchorLines": list(request.instruction.anchor_lines),
+        "body": request.instruction.body,
+        "sourcePaths": [
+            _source_payload(source) for source in request.instruction.source_paths
+        ],
+    }
+    selected_names = ["common.md", duty.source_path.name]
+    return {
+        "catalogDigest": digest_duty_catalog(request.duty_root),
+        "assignmentDigest": _sha256(_canonical_json(assignment)),
+        "dutyDigest": _digest_framed_files(request.duty_root, selected_names),
+        "instructionDigest": _sha256(_canonical_json(instruction)),
+        "promptDigest": _sha256(prompt_bytes),
+    }
+
+
+def _metadata_payload(
+    request: AgentInvocationRequest,
+    duty: DutyContract,
+    digests: Mapping[str, str],
+) -> dict[str, object]:
+    mode = "run" if request.run_manifest_path is not None else "standalone"
+    manifest_path = (
+        _project_relative(
+            request.run_manifest_path,
+            request.project_root,
+            must_exist=True,
+        )
+        if request.run_manifest_path is not None
+        else None
+    )
+    return {
+        "schemaVersion": 1,
+        "invocationId": request.invocation_id,
+        "audience": request.audience,
+        "dispatchKind": request.dispatch_kind,
+        "workerId": request.worker_id,
+        "assignmentRef": request.assignment_ref,
+        "contractSource": {
+            "mode": mode,
+            "runManifestPath": manifest_path,
+            "dutyRootPath": _project_relative(
+                request.duty_root,
+                request.project_root,
+                must_exist=True,
+            ),
+        },
+        "modelAssignment": _assignment_payload(request.assignment),
+        "dutyContract": {"id": duty.id, "version": duty.version},
+        "instruction": {
+            "sourcePaths": [
+                _source_payload(source)
+                for source in request.instruction.source_paths
+            ]
+        },
+        "prompt": {
+            "path": _project_relative(
+                request.prompt_path,
+                request.project_root,
+                must_exist=False,
+            )
+        },
+        "digests": dict(digests),
+    }
+
+
+def _reservation_spec(
+    request: AgentInvocationRequest,
+) -> tuple[Path | None, dict[str, object] | None]:
+    if request.run_manifest_path is None:
+        return None, None
+    manifest = _load_json_object(request.run_manifest_path, "run manifest")
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, dict):
+        raise AgentInvocationError("run manifest has no agent contract")
+    _validate_manifest_contract(request, manifest, contract)
+    reservation_value = contract.get("invocationReservationRootPath")
+    reservation_root = _project_path(
+        request.project_root,
+        reservation_value,
+        must_exist=False,
+    )
+    reservation = {
+        "schemaVersion": 1,
+        "invocationId": request.invocation_id,
+        "workerId": request.worker_id,
+        "assignmentRef": request.assignment_ref,
+        "audience": request.audience,
+        "dispatchKind": request.dispatch_kind,
+        "promptPath": _project_relative(
+            request.prompt_path,
+            request.project_root,
+            must_exist=False,
+        ),
+        "metadataPath": _project_relative(
+            request.metadata_path,
+            request.project_root,
+            must_exist=False,
+        ),
+    }
+    return reservation_root, reservation
+
+
+def _validate_manifest_contract(
+    request: AgentInvocationRequest,
+    manifest: Mapping[str, object],
+    contract: Mapping[str, object],
+) -> None:
+    duty_path = _project_relative(
+        request.duty_root,
+        request.project_root,
+        must_exist=True,
+    )
+    if contract.get("dutyRootPath") != duty_path:
+        raise AgentInvocationError("duty root does not match run manifest")
+    if contract.get("catalogDigest") != digest_duty_catalog(request.duty_root):
+        raise AgentInvocationError("catalog digest does not match run duty snapshot")
+    allowed = contract.get("allowedAudiences")
+    if not isinstance(allowed, list) or request.audience not in allowed:
+        raise AgentInvocationError("audience is not allowed by run manifest")
+    assignments = manifest.get("invocationAssignments")
+    manifest_assignment = (
+        assignments.get(request.assignment_ref)
+        if isinstance(assignments, dict)
+        else None
+    )
+    if manifest_assignment != _assignment_payload(request.assignment):
+        raise AgentInvocationError("model assignment does not match run manifest")
+    _validate_authorized_prompt_path(request, contract)
+
+
+def _validate_authorized_prompt_path(
+    request: AgentInvocationRequest,
+    contract: Mapping[str, object],
+) -> None:
+    authorized = contract.get("authorizedPaths")
+    roots = authorized.get("promptRoots") if isinstance(authorized, dict) else None
+    if not isinstance(roots, list) or not roots:
+        raise AgentInvocationError("run manifest has no authorized prompt roots")
+    prompt = request.prompt_path.resolve(strict=False)
+    allowed = [
+        _project_path(request.project_root, value, must_exist=True)
+        for value in roots
+    ]
+    if not any(_is_relative_to(prompt, root) for root in allowed):
+        raise AgentInvocationError("prompt path is outside authorized prompt roots")
+
+
+def _publish_or_reuse_reservation(materialized: _MaterializedInvocation) -> None:
+    root = materialized.reservation_root
+    reservation = materialized.reservation
+    if root is None or reservation is None:
+        return
+    path = root / f"{materialized.prepared.invocation_id}.json"
+    if path.exists():
+        if _read_json_if_object(path) != reservation:
+            raise AgentInvocationError(
+                "invocation reservation conflicts with existing invocation",
+                reason="invocation_reservation_conflict",
+            )
+        return
+    _publish_exclusive(path, _pretty_json(reservation))
+
+
+def _publish_or_reuse(materialized: _MaterializedInvocation) -> None:
+    prompt = materialized.prepared.prompt_path
+    metadata = materialized.prepared.metadata_path
+    prompt_exists = prompt.exists()
+    metadata_exists = metadata.exists()
+    if metadata_exists and not prompt_exists:
+        raise _existing_conflict("metadata exists without prompt")
+    if prompt_exists and prompt.read_bytes() != materialized.prompt_bytes:
+        raise _existing_conflict("existing prompt differs")
+    if prompt_exists and metadata_exists:
+        if metadata.read_bytes() != materialized.metadata_bytes:
+            raise _existing_conflict("existing metadata differs")
+        return
+    if not prompt_exists:
+        _publish_exclusive(prompt, materialized.prompt_bytes)
+    _publish_exclusive(metadata, materialized.metadata_bytes)
+
+
+def _existing_conflict(detail: str) -> AgentInvocationError:
+    return AgentInvocationError(
+        f"existing_invocation_conflict: {detail}",
+        reason="existing_invocation_conflict",
+    )
+
+
+@contextlib.contextmanager
+def _exclusive_lock(path: Path) -> Iterator[None]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle = path.open("a+")
+    try:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        handle.close()
+
+
+def _prompt_lock_path(prompt_path: Path) -> Path:
+    return prompt_path.with_name(prompt_path.name + ".publish.lock")
+
+
+def _publish_exclusive(path: Path, body: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_path = Path(handle.name)
+            handle.write(body)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.link(temp_path, path)
+    except FileExistsError as exc:
+        raise _existing_conflict(f"published path already exists: {path}") from exc
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+
+
+def _verify_expected_identity(
+    metadata: Mapping[str, object],
+    *,
+    expected_invocation_id: str | None,
+    expected_worker_id: str | None,
+    expected_assignment_ref: str | None,
+    expected_audience: AgentAudience | None,
+) -> list[str]:
+    expected = {
+        "invocationId": expected_invocation_id,
+        "workerId": expected_worker_id,
+        "assignmentRef": expected_assignment_ref,
+        "audience": expected_audience,
+    }
+    errors = []
+    for key, value in expected.items():
+        if value is not None and metadata.get(key) != value:
+            errors.append(f"{key} does not match expected invocation identity")
+    return errors
+
+
+def _verify_prompt_file(
+    metadata: Mapping[str, object],
+    project_root: Path,
+) -> list[str]:
+    prompt = metadata["prompt"]
+    digests = metadata["digests"]
+    assert isinstance(prompt, dict)
+    assert isinstance(digests, dict)
+    try:
+        path = _project_path(project_root, prompt["path"], must_exist=True)
+    except AgentInvocationError:
+        return ["prompt path is invalid or missing"]
+    body = path.read_bytes()
+    if digests["promptDigest"] != _sha256(body):
+        return ["prompt digest does not match prompt file"]
+    errors = []
+    errors.extend(_verify_instruction_digest(metadata, body))
+    errors.extend(_verify_model_header(metadata, body))
+    return errors
+
+
+def _verify_instruction_digest(
+    metadata: Mapping[str, object],
+    prompt_bytes: bytes,
+) -> list[str]:
+    try:
+        prompt = prompt_bytes.decode("utf-8")
+        prefix, task_body = _split_prompt(prompt)
+        anchor_lines = _extract_anchor_lines(prefix)
+    except (UnicodeDecodeError, ValueError):
+        return ["prompt structure is invalid"]
+    instruction = metadata["instruction"]
+    digests = metadata["digests"]
+    assert isinstance(instruction, dict)
+    assert isinstance(digests, dict)
+    base = {
+        "anchorLines": anchor_lines,
+        "sourcePaths": instruction["sourcePaths"],
+    }
+    candidates = (
+        {**base, "body": task_body},
+        {**base, "body": task_body.rstrip("\n")},
+    )
+    actual = digests["instructionDigest"]
+    if not any(_sha256(_canonical_json(candidate)) == actual for candidate in candidates):
+        return ["instruction digest does not match prompt instructions"]
+    return []
+
+
+def _verify_model_header(
+    metadata: Mapping[str, object],
+    prompt_bytes: bytes,
+) -> list[str]:
+    assignment = metadata["modelAssignment"]
+    assert isinstance(assignment, dict)
+    prompt = prompt_bytes.decode("utf-8")
+    required = {
+        f"**Provider:** {assignment['provider']}",
+        f"**Model:** {assignment['model']}",
+        f"**Model execution value:** {assignment['modelExecutionValue']}",
+        f"**Runner:** {assignment['runner']}",
+        f"**Host runtime:** {assignment['hostRuntime']}",
+    }
+    host_model = assignment["hostModelValue"]
+    if host_model is not None:
+        required.add(f"**Host model value:** {host_model}")
+    prefix = prompt.split("\n\n## Duty Contract\n\n", 1)[0]
+    if not required.issubset(set(prefix.splitlines())):
+        return ["prompt model header does not match model assignment"]
+    return []
+
+
+def _split_prompt(prompt: str) -> tuple[str, str]:
+    duty_marker = "\n\n## Duty Contract\n\n"
+    task_marker = "\n\n## Task Instructions\n\n"
+    if prompt.count(duty_marker) != 1 or prompt.count(task_marker) != 1:
+        raise ValueError("prompt markers are invalid")
+    prefix, remainder = prompt.split(duty_marker, 1)
+    _duty, task = remainder.split(task_marker, 1)
+    return prefix, task
+
+
+def _extract_anchor_lines(prefix: str) -> list[str]:
+    lines = prefix.splitlines()
+    try:
+        provider_index = next(
+            index for index, line in enumerate(lines) if line.startswith("**Provider:**")
+        )
+    except StopIteration as exc:
+        raise ValueError("model header is missing") from exc
+    return lines[:provider_index]
+
+
+def _verify_assignment(
+    metadata: Mapping[str, object],
+    expected: AgentModelAssignment | None,
+) -> list[str]:
+    assignment = metadata["modelAssignment"]
+    digests = metadata["digests"]
+    assert isinstance(assignment, dict)
+    assert isinstance(digests, dict)
+    errors = []
+    if digests["assignmentDigest"] != _sha256(_canonical_json(assignment)):
+        errors.append("assignment digest does not match model assignment")
+    if expected is not None and assignment != _assignment_payload(expected):
+        errors.append("model assignment does not match expected assignment")
+    return errors
+
+
+def _verify_contract_source(
+    metadata: Mapping[str, object],
+    *,
+    metadata_path: Path,
+    project_root: Path,
+    expected_run_manifest_path: Path | None,
+) -> list[str]:
+    source = metadata["contractSource"]
+    assert isinstance(source, dict)
+    mode = source["mode"]
+    if mode == "standalone":
+        if expected_run_manifest_path is not None:
+            return ["standalone invocation cannot use a run manifest"]
+        errors = _verify_metadata_adjacency(metadata, metadata_path, project_root)
+        errors.extend(_verify_duty_snapshot(metadata, project_root, None))
+        return errors
+    if mode != "run":
+        return ["contract source mode is invalid"]
+    if expected_run_manifest_path is None:
+        return ["run invocation requires expected run manifest"]
+    errors = _verify_metadata_adjacency(metadata, metadata_path, project_root)
+    errors.extend(
+        _verify_run_contract(
+            metadata,
+            project_root=project_root,
+            expected_run_manifest_path=expected_run_manifest_path,
+        )
+    )
+    return errors
+
+
+def _verify_metadata_adjacency(
+    metadata: Mapping[str, object],
+    metadata_path: Path,
+    project_root: Path,
+) -> list[str]:
+    prompt = metadata["prompt"]
+    assert isinstance(prompt, dict)
+    try:
+        prompt_path = _project_path(project_root, prompt["path"], must_exist=False)
+        expected = prompt_path.with_name(prompt_path.name + ".meta.json")
+        if metadata_path.resolve(strict=True) != expected.resolve(strict=True):
+            return ["metadata path is not adjacent to prompt path"]
+    except (AgentInvocationError, OSError):
+        return ["metadata path is invalid"]
+    return []
+
+
+def _verify_run_contract(
+    metadata: Mapping[str, object],
+    *,
+    project_root: Path,
+    expected_run_manifest_path: Path,
+) -> list[str]:
+    source = metadata["contractSource"]
+    assert isinstance(source, dict)
+    try:
+        recorded = _project_path(
+            project_root,
+            source["runManifestPath"],
+            must_exist=True,
+        )
+        expected = expected_run_manifest_path.resolve(strict=True)
+    except (AgentInvocationError, OSError):
+        return ["run manifest path is invalid"]
+    if recorded != expected:
+        return ["run manifest path does not match expected run manifest"]
+    try:
+        manifest = _load_json_object(expected, "run manifest")
+    except AgentInvocationError:
+        return ["run manifest is invalid"]
+    errors = _verify_run_manifest_contract(metadata, manifest, project_root)
+    errors.extend(_verify_duty_snapshot(metadata, project_root, manifest))
+    errors.extend(_verify_reservation(metadata, manifest, project_root))
+    return errors
+
+
+def _verify_run_manifest_contract(
+    metadata: Mapping[str, object],
+    manifest: Mapping[str, object],
+    project_root: Path,
+) -> list[str]:
+    source = metadata["contractSource"]
+    digests = metadata["digests"]
+    assert isinstance(source, dict)
+    assert isinstance(digests, dict)
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, dict):
+        return ["run manifest agent contract is missing"]
+    errors = []
+    if contract.get("dutyRootPath") != source["dutyRootPath"]:
+        errors.append("duty root does not match run manifest")
+    if contract.get("catalogDigest") != digests["catalogDigest"]:
+        errors.append("catalog digest does not match run manifest")
+    allowed = contract.get("allowedAudiences")
+    if not isinstance(allowed, list) or metadata["audience"] not in allowed:
+        errors.append("audience is not allowed by run manifest")
+    errors.extend(_verify_manifest_assignment(metadata, manifest))
+    return errors
+
+
+def _verify_manifest_assignment(
+    metadata: Mapping[str, object],
+    manifest: Mapping[str, object],
+) -> list[str]:
+    assignments = manifest.get("invocationAssignments")
+    reference = metadata["assignmentRef"]
+    if not isinstance(assignments, dict) or reference not in assignments:
+        return ["assignment reference is missing from run manifest"]
+    if assignments[reference] != metadata["modelAssignment"]:
+        return ["model assignment does not match run manifest"]
+    return []
+
+
+def _verify_duty_snapshot(
+    metadata: Mapping[str, object],
+    project_root: Path,
+    manifest: Mapping[str, object] | None,
+) -> list[str]:
+    source = metadata["contractSource"]
+    duty_contract = metadata["dutyContract"]
+    digests = metadata["digests"]
+    assert isinstance(source, dict)
+    assert isinstance(duty_contract, dict)
+    assert isinstance(digests, dict)
+    try:
+        root = _project_path(project_root, source["dutyRootPath"], must_exist=True)
+        common = load_common_duty_contract(root)
+        catalog = load_duty_catalog(root)
+        duty = catalog[duty_contract["id"]]
+    except (AgentInvocationError, KeyError):
+        return ["duty snapshot is invalid"]
+    errors = _verify_duty_metadata(duty_contract, duty)
+    actual_catalog = digest_duty_catalog(root)
+    expected_catalog = (
+        manifest["agentContract"]["catalogDigest"]
+        if manifest is not None
+        else digests["catalogDigest"]
+    )
+    if actual_catalog != expected_catalog or digests["catalogDigest"] != actual_catalog:
+        errors.append("catalog digest does not match run duty snapshot")
+        return errors
+    actual_duty = _digest_framed_files(root, ["common.md", duty.source_path.name])
+    if digests["dutyDigest"] != actual_duty:
+        errors.append("duty digest does not match run duty snapshot")
+        return errors
+    errors.extend(_verify_prompt_duty_body(metadata, project_root, common, duty))
+    return errors
+
+
+def _verify_duty_metadata(
+    recorded: Mapping[str, object],
+    duty: DutyContract,
+) -> list[str]:
+    if recorded["id"] != duty.id or recorded["version"] != duty.version:
+        return ["duty identity does not match duty snapshot"]
+    return []
+
+
+def _verify_prompt_duty_body(
+    metadata: Mapping[str, object],
+    project_root: Path,
+    common: DutyContract,
+    duty: DutyContract,
+) -> list[str]:
+    prompt_spec = metadata["prompt"]
+    assert isinstance(prompt_spec, dict)
+    try:
+        prompt_path = _project_path(project_root, prompt_spec["path"], must_exist=True)
+        prompt = prompt_path.read_text(encoding="utf-8")
+        _prefix, remainder = prompt.split("\n\n## Duty Contract\n\n", 1)
+        rendered_duty, _task = remainder.split("\n\n## Task Instructions\n\n", 1)
+    except (AgentInvocationError, OSError, UnicodeDecodeError, ValueError):
+        return ["prompt duty contract does not match duty snapshot"]
+    expected = f"{common.body.rstrip()}\n\n{duty.body.rstrip()}"
+    if rendered_duty != expected:
+        return ["prompt duty contract does not match duty snapshot"]
+    return []
+
+
+def _verify_reservation(
+    metadata: Mapping[str, object],
+    manifest: Mapping[str, object],
+    project_root: Path,
+) -> list[str]:
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, dict):
+        return ["run manifest agent contract is missing"]
+    try:
+        root = _project_path(
+            project_root,
+            contract["invocationReservationRootPath"],
+            must_exist=True,
+        )
+        path = root / f"{metadata['invocationId']}.json"
+        actual = _load_json_object(path, "invocation reservation")
+    except (AgentInvocationError, KeyError):
+        return ["invocation reservation is missing or invalid"]
+    prompt = metadata["prompt"]
+    assert isinstance(prompt, dict)
+    expected = {
+        "schemaVersion": 1,
+        "invocationId": metadata["invocationId"],
+        "workerId": metadata["workerId"],
+        "assignmentRef": metadata["assignmentRef"],
+        "audience": metadata["audience"],
+        "dispatchKind": metadata["dispatchKind"],
+        "promptPath": prompt["path"],
+        "metadataPath": f"{prompt['path']}.meta.json",
+    }
+    if actual != expected:
+        return ["invocation reservation does not match invocation metadata"]
+    return []
+
+
+def _metadata_schema_is_exact(metadata: Mapping[str, object]) -> bool:
+    if set(metadata) != _TOP_LEVEL_KEYS or metadata.get("schemaVersion") != 1:
+        return False
+    for key, expected_keys in _NESTED_KEYS.items():
+        value = metadata.get(key)
+        if not isinstance(value, dict) or set(value) != expected_keys:
+            return False
+    sources = metadata["instruction"]["sourcePaths"]
+    if not isinstance(sources, list) or not sources:
+        return False
+    if any(not isinstance(item, dict) or set(item) != {"kind", "path"} for item in sources):
+        return False
+    return _digest_paths(metadata) == {
+        "digests.catalogDigest",
+        "digests.assignmentDigest",
+        "digests.dutyDigest",
+        "digests.instructionDigest",
+        "digests.promptDigest",
+    }
+
+
+def _digest_paths(value: object, prefix: str = "") -> set[str]:
+    if not isinstance(value, dict):
+        return set()
+    found: set[str] = set()
+    for key, child in value.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if key == "digest" or key.endswith("Digest"):
+            found.add(path)
+        found.update(_digest_paths(child, path))
+    return found
+
+
+def _assignment_payload(assignment: AgentModelAssignment) -> dict[str, object]:
+    return {
+        "provider": assignment.provider,
+        "model": assignment.model,
+        "modelExecutionValue": assignment.model_execution_value,
+        "runner": assignment.runner,
+        "hostRuntime": assignment.host_runtime,
+        "hostModelValue": assignment.host_model_value,
+    }
+
+
+def _source_payload(source: AgentInstructionSource) -> dict[str, str]:
+    if source.kind not in {"project", "runtime"}:
+        raise AgentInvocationError("instruction sourcePaths contains an invalid kind")
+    path = source.path
+    pure = PurePosixPath(path)
+    if (
+        not path
+        or "\\" in path
+        or pure.is_absolute()
+        or any(part in {"", ".", ".."} for part in pure.parts)
+    ):
+        raise AgentInvocationError("instruction sourcePaths must use relative POSIX paths")
+    return {"kind": source.kind, "path": pure.as_posix()}
+
+
+def _project_relative(
+    path: Path,
+    project_root: Path,
+    *,
+    must_exist: bool,
+) -> str:
+    root = project_root.resolve(strict=True)
+    try:
+        if must_exist:
+            resolved = path.resolve(strict=True)
+        else:
+            resolved = path.parent.resolve(strict=True) / path.name
+        return resolved.relative_to(root).as_posix()
+    except (OSError, ValueError) as exc:
+        raise AgentInvocationError(f"path escapes project root: {path}") from exc
+
+
+def _project_path(
+    project_root: Path,
+    value: object,
+    *,
+    must_exist: bool,
+) -> Path:
+    if not isinstance(value, str) or not value:
+        raise AgentInvocationError("project-relative path is invalid")
+    pure = PurePosixPath(value)
+    if pure.is_absolute() or any(part in {"", ".", ".."} for part in pure.parts):
+        raise AgentInvocationError("project-relative path is invalid")
+    candidate = project_root.joinpath(*pure.parts)
+    _project_relative(candidate, project_root, must_exist=must_exist)
+    return candidate.resolve(strict=must_exist)
+
+
+def _is_relative_to(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def _digest_framed_files(root: Path, relative_names: list[str]) -> str:
+    framed = bytearray(b"okstra-digest-v1\0")
+    for name in sorted(relative_names):
+        name_bytes = name.encode("utf-8")
+        body = (root / name).read_bytes()
+        framed.extend(len(name_bytes).to_bytes(8, "big"))
+        framed.extend(name_bytes)
+        framed.extend(len(body).to_bytes(8, "big"))
+        framed.extend(body)
+    return _sha256(bytes(framed))
+
+
+def _sha256(data: bytes) -> str:
+    return f"sha256:{hashlib.sha256(data).hexdigest()}"
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def _pretty_json(value: object) -> bytes:
+    return (
+        json.dumps(value, ensure_ascii=False, indent=2, allow_nan=False) + "\n"
+    ).encode("utf-8")
+
+
+def _load_json_object(path: Path, label: str) -> dict[str, object]:
+    value = _read_json_if_object(path)
+    if value is None:
+        raise AgentInvocationError(f"{label} is missing or invalid: {path}")
+    return value
+
+
+def _read_json_if_object(path: Path) -> dict[str, object] | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def _read_metadata(path: Path) -> dict[str, object] | None:
+    return _read_json_if_object(path)
+
+
+def _deduplicate(errors: list[str]) -> list[str]:
+    return list(dict.fromkeys(errors))
+
+
+def _load_role_duty(path: Path) -> DutyContract:
+    fields, body = _parse_duty_file(path)
+    if set(fields) != {"id", "version", "kind", "appliesTo"}:
+        raise AgentInvocationError(f"invalid role duty frontmatter: {path}")
+    audience = fields["appliesTo"]
+    if audience not in _SUPPORTED_AUDIENCES:
+        raise AgentInvocationError(f"unknown duty audience: {audience}")
+    if fields["kind"] != "role" or fields["id"] != audience:
+        raise AgentInvocationError(f"invalid role duty frontmatter: {path}")
+    return DutyContract(
+        id=fields["id"],
+        version=_parse_version(fields["version"], path),
+        kind="role",
+        applies_to=audience,
+        body=body,
+        source_path=path,
+    )
+
+
+def _parse_duty_file(path: Path) -> tuple[dict[str, str], str]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise AgentInvocationError(f"cannot read duty contract: {path}") from exc
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        raise AgentInvocationError(f"missing duty frontmatter: {path}")
+    try:
+        end = next(index for index, line in enumerate(lines[1:], 1) if line.strip() == "---")
+    except StopIteration as exc:
+        raise AgentInvocationError(f"unterminated duty frontmatter: {path}") from exc
+    fields: dict[str, str] = {}
+    for line in lines[1:end]:
+        key, separator, value = line.partition(":")
+        if not separator or not key.strip() or key.strip() in fields:
+            raise AgentInvocationError(f"invalid duty frontmatter: {path}")
+        fields[key.strip()] = value.strip()
+    return fields, "".join(lines[end + 1 :]).lstrip("\n")
+
+
+def _parse_version(value: str, path: Path) -> int:
+    try:
+        version = int(value)
+    except ValueError as exc:
+        raise AgentInvocationError(f"invalid duty version: {path}") from exc
+    if version < 1:
+        raise AgentInvocationError(f"invalid duty version: {path}")
+    return version