okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -24,6 +24,13 @@ from .agent_invocation import (
 )
 from .path_hints import hydrate_active_run_context
 from .report_language import resolve_report_language
+from .report_inputs import report_narrative_path, uses_report_contract_v3
+from .report_synthesis_packet import (
+    ReportSynthesisPacketError,
+    materialize_report_synthesis_packet,
+    report_synthesis_packet_paths,
+)
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .worker_prompt_body import (
     REPORT_WRITER_WORKER_ID,
     analysis_prompt_body,
@@ -444,7 +451,17 @@ def _render_prompt_parts(
             f"**Prompt Delivery Mode:** {context.request.delivery_mode.value}"
         )
         anchors.extend(_implementation_anchor_lines(context, item.plan))
-        body = _prompt_body(context, state, worker, item.plan)
+        synthesis_packet_path = _materialize_report_writer_packet(
+            context,
+            item.plan,
+        )
+        body = _prompt_body(
+            context,
+            state,
+            worker,
+            item.plan,
+            synthesis_packet_path,
+        )
         body.extend(_resource_lines(context, item))
     except InitialPromptMaterializationError:
         raise
@@ -503,7 +520,7 @@ def _agent_invocation_request(
             f"requested model does not match {assignment_ref}",
         )
     anchors, body = _render_prompt_parts(context, item)
-    source_paths = (
+    source_paths = [
         AgentInstructionSource(
             "project",
             _project_relative(context.project_root, context.request.run_manifest_path),
@@ -514,7 +531,10 @@ def _agent_invocation_request(
         AgentInstructionSource(
             "project", _required_string(context.manifest, "teamStatePath")
         ),
-    )
+    ]
+    packet_source = _report_writer_packet_source(context, item.plan)
+    if packet_source is not None:
+        source_paths.append(packet_source)
     invocation_id = _worker_invocation_id(context.manifest, item.worker.worker_id)
     return AgentInvocationRequest(
         invocation_id=invocation_id,
@@ -526,7 +546,7 @@ def _agent_invocation_request(
         instruction=AgentInstruction(
             anchor_lines=tuple(anchors),
             body="\n".join(body).rstrip() + "\n",
-            source_paths=source_paths,
+            source_paths=tuple(source_paths),
         ),
         project_root=context.project_root,
         run_manifest_path=context.request.run_manifest_path,
@@ -549,6 +569,7 @@ def _prompt_body(
     state: Mapping[str, Any],
     worker: InitialPromptWorkerRequest,
     plan: PromptPlan,
+    synthesis_packet_path: str = "",
 ) -> list[str]:
     if plan.audience == "report-writer":
         return report_writer_prompt_body(
@@ -561,6 +582,7 @@ def _prompt_body(
                 context.manifest,
                 context.active_context,
             ),
+            synthesis_packet_path,
         )
     return analysis_prompt_body(
         context.manifest,
@@ -571,6 +593,56 @@ def _prompt_body(
     )
 
 
+def _report_writer_narrative_path(context: _MaterializationContext) -> Path:
+    return report_narrative_path(context.project_root, context.manifest)
+
+
+def _report_writer_packet_source(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> AgentInstructionSource | None:
+    if (
+        plan.audience != "report-writer"
+        or not uses_report_contract_v3(context.manifest)
+    ):
+        return None
+    _, markdown_path = report_synthesis_packet_paths(
+        _report_writer_narrative_path(context)
+    )
+    return AgentInstructionSource(
+        "project",
+        _project_relative(context.project_root, markdown_path),
+    )
+
+
+def _materialize_report_writer_packet(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> str:
+    packet_source = _report_writer_packet_source(context, plan)
+    if packet_source is None:
+        return ""
+    try:
+        _, markdown_path = materialize_report_synthesis_packet(
+            project_root=context.project_root,
+            manifest=context.manifest,
+            active_context=context.active_context,
+            team_state=context.team_state,
+            narrative_path=_report_writer_narrative_path(context),
+        )
+    except ReportSynthesisPacketError as exc:
+        defects = "; ".join(
+            f"owner={issue.owner} source={issue.label} path={issue.path} "
+            f"reason={issue.reason}"
+            for issue in exc.issues
+        )
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"report synthesis packet contract defects: {defects}",
+        ) from exc
+    return _project_relative(context.project_root, markdown_path)
+
+
 def _resource_lines(
     context: _MaterializationContext,
     item: _PromptItem,
@@ -1325,12 +1397,12 @@ def _load_referenced_json(
 
 def _load_json_object(path: Path, label: str) -> Mapping[str, Any]:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        payload = load_owned_object(path, artifact=label)
+    except JsonBoundaryError as exc:
         raise InitialPromptMaterializationError(
             "required_input_missing",
             f"cannot load {label}: {path}: {exc}",
-        ) from exc
+        ) from (exc.__cause__ or exc)
     if not isinstance(payload, dict):
         raise InitialPromptMaterializationError(
             "required_input_missing",

package/runtime/python/okstra_ctl/invocation.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Optional
 
 from .ids import _safe_fs_segment
+from .json_boundary import load_owned_object, write_owned_object_atomic
 
 
 def invocation_path(home: Path, project_id: str,
@@ -32,11 +33,7 @@ def save_invocation(home: Path, project_id: str,
                     run_seq: int, payload: dict) -> None:
     """invocation 을 원자적으로 저장(임시파일 + os.replace)."""
     target = invocation_path(home, project_id, task_group, task_id, task_type, run_seq)
-    target.parent.mkdir(parents=True, exist_ok=True)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(payload, indent=2) + "\n")
-    os.chmod(tmp, 0o600)
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, payload, artifact="invocation metadata")
 
 
 def load_invocation(home: Path, project_id: str,
@@ -46,4 +43,4 @@ def load_invocation(home: Path, project_id: str,
     target = invocation_path(home, project_id, task_group, task_id, task_type, run_seq)
     if not target.is_file():
         return None
-    return json.loads(target.read_text())
+    return load_owned_object(target, artifact="invocation metadata")

package/runtime/python/okstra_ctl/json_boundary.py

@@ -0,0 +1,366 @@
+"""Strict JSON boundaries for okstra-owned artifacts."""
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+import tempfile
+from typing import Any
+
+from .final_report_schema import SchemaError, validate as validate_schema
+
+
+class JsonBoundaryError(ValueError):
+    """An owned JSON artifact could not satisfy its persistence contract."""
+
+    def __init__(self, path: Path, artifact: str, reason: str) -> None:
+        self.path = path
+        self.artifact = artifact
+        self.reason = reason
+        super().__init__(f"{artifact}: {reason}: {path}")
+
+
+_EXTERNAL_SOURCE_SEAL = object()
+
+
+@dataclass(frozen=True, init=False)
+class ExternalJsonSource:
+    """검증된 외부 생산자가 소유한 JSON 입력 경로다."""
+
+    path: Path
+    producer: str
+
+    def __init__(self, path: Path, producer: str, seal: object = None) -> None:
+        if seal is not _EXTERNAL_SOURCE_SEAL:
+            raise TypeError("ExternalJsonSource is sealed")
+        object.__setattr__(self, "path", path)
+        object.__setattr__(self, "producer", producer)
+
+
+@dataclass(frozen=True)
+class OwnedJsonSnapshot:
+    """한 번 읽은 원시 바이트와 그 바이트에서 검증한 객체다."""
+
+    value: dict[str, Any]
+    raw_bytes: bytes
+
+
+def _issue_external_source(path: Path, producer: str) -> ExternalJsonSource:
+    if not isinstance(path, Path):
+        raise TypeError("external JSON source requires Path")
+    return ExternalJsonSource(path, producer, _EXTERNAL_SOURCE_SEAL)
+
+
+def _is_okstra_owned_path(path: Path) -> bool:
+    lexical = Path(os.path.abspath(path))
+    resolved = path.resolve(strict=False)
+    return ".okstra" in lexical.parts or ".okstra" in resolved.parts
+
+
+def external_user_json_source(path: Path) -> ExternalJsonSource:
+    """사용자 제공 JSON이 Okstra 소유 트리 밖에 있을 때만 승인한다."""
+    if _is_okstra_owned_path(path):
+        raise JsonBoundaryError(path, "external JSON", "Okstra-owned path")
+    return _issue_external_source(path, "user")
+
+
+def external_worker_json_source(
+    path: Path, *, trusted_root: Path, lane_root: Path
+) -> ExternalJsonSource:
+    """신뢰 루트 아래의 정확한 worker 결과 lane만 승인한다."""
+    lexical_root = Path(os.path.abspath(trusted_root))
+    lexical_lane = Path(os.path.abspath(lane_root))
+    lexical_path = Path(os.path.abspath(path))
+    try:
+        lane_parts = lexical_lane.relative_to(lexical_root).parts
+    except ValueError:
+        lane_parts = ()
+    is_worker_lane = (
+        len(lane_parts) in {7, 8}
+        and lane_parts[:2] == (".okstra", "tasks")
+        and lane_parts[4] == "runs"
+        and lane_parts[-1] == "worker-results"
+        and (len(lane_parts) == 7 or lane_parts[6].startswith("stage-"))
+    )
+    if not is_worker_lane or lexical_path.parent != lexical_lane:
+        raise JsonBoundaryError(
+            path, "worker JSON", "outside worker result lanes"
+        )
+    try:
+        lexical_lane.relative_to(lexical_root)
+        lexical_path.relative_to(lexical_lane)
+        resolved_lane = lane_root.resolve(strict=False)
+        resolved_lane.relative_to(trusted_root.resolve(strict=False))
+        path.resolve(strict=False).relative_to(resolved_lane)
+    except ValueError as exc:
+        raise JsonBoundaryError(
+            path, "worker JSON", "outside worker result lanes"
+        ) from exc
+    if _has_symlink_component(lexical_lane, lexical_root) or _has_symlink_component(
+        lexical_path, lexical_lane
+    ):
+        raise JsonBoundaryError(path, "worker JSON", "outside worker result lanes")
+    return _issue_external_source(path, "worker")
+
+
+def external_invocation_json_source(
+    path: Path, *, project_root: Path, purpose: str
+) -> ExternalJsonSource:
+    """정확한 standalone purpose lane의 직접 결과만 승인한다."""
+    if not purpose or any(char not in "abcdefghijklmnopqrstuvwxyz0123456789-" for char in purpose):
+        raise JsonBoundaryError(path, "invocation JSON", "outside invocation result lane")
+    lane = project_root / ".okstra" / "agent-invocations" / purpose
+    lexical_path = Path(os.path.abspath(path))
+    lexical_lane = Path(os.path.abspath(lane))
+    lexical_root = Path(os.path.abspath(project_root))
+    if lexical_path.parent != lexical_lane or path.is_symlink():
+        raise JsonBoundaryError(path, "invocation JSON", "outside invocation result lane")
+    try:
+        lane.resolve(strict=False).relative_to(project_root.resolve(strict=False))
+        path.resolve(strict=False).relative_to(lane.resolve(strict=False))
+    except ValueError as exc:
+        raise JsonBoundaryError(
+            path, "invocation JSON", "outside invocation result lane"
+        ) from exc
+    if _has_symlink_component(lexical_lane, lexical_root):
+        raise JsonBoundaryError(path, "invocation JSON", "outside invocation result lane")
+    return _issue_external_source(path, "standalone worker")
+
+
+def _has_symlink_component(path: Path, root: Path) -> bool:
+    current = path
+    while current != root:
+        if current.is_symlink():
+            return True
+        if current.parent == current:
+            return True
+        current = current.parent
+    return root.is_symlink()
+
+
+def external_claude_global_json_source(
+    path: Path, home_dir: Path
+) -> ExternalJsonSource:
+    """호스트 어댑터가 지정한 home의 전역 Claude 설정만 승인한다."""
+    expected = home_dir / ".claude.json"
+    if Path(os.path.abspath(path)) != Path(os.path.abspath(expected)) or path.is_symlink():
+        raise JsonBoundaryError(path, "Claude JSON", "outside fixed adapter path")
+    return _issue_external_source(path, "Claude Code")
+
+
+def external_claude_team_json_source(path: Path) -> ExternalJsonSource:
+    """현재 사용자의 Claude team roster 설정만 승인한다."""
+    root = Path.home() / ".claude" / "teams"
+    try:
+        Path(os.path.abspath(path)).relative_to(Path(os.path.abspath(root)))
+        path.resolve(strict=False).relative_to(root.resolve(strict=False))
+    except ValueError as exc:
+        raise JsonBoundaryError(path, "Claude JSON", "outside Claude team root") from exc
+    if path.name != "config.json" or path.is_symlink():
+        raise JsonBoundaryError(path, "Claude JSON", "outside Claude team root")
+    return _issue_external_source(path, "Claude Code")
+
+
+def external_tool_json_source(path: Path, workspace_root: Path) -> ExternalJsonSource:
+    """외부 도구가 workspace의 비-Okstra 경로에 쓴 보고서만 승인한다."""
+    try:
+        path.resolve(strict=False).relative_to(workspace_root.resolve(strict=False))
+    except ValueError as exc:
+        raise JsonBoundaryError(path, "tool JSON", "outside tool workspace") from exc
+    if _is_okstra_owned_path(path):
+        raise JsonBoundaryError(path, "tool JSON", "Okstra-owned path")
+    return _issue_external_source(path, "external tool")
+
+
+def external_error_sidecar_source(path: Path) -> ExternalJsonSource:
+    """worker-results lane 또는 Okstra 밖 레거시 sidecar만 승인한다."""
+    if _is_okstra_owned_path(path):
+        raise JsonBoundaryError(
+            path, "worker error sidecar", "trusted worker lane is required"
+        )
+    return _issue_external_source(path, "legacy automation")
+
+
+class _NonstandardJsonConstant(ValueError):
+    """Raised by ``json.loads`` when a non-standard numeric token appears."""
+
+
+def load_owned_object(
+    path: Path,
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> dict[str, Any]:
+    """Load and validate one okstra-owned JSON object."""
+    return load_owned_object_snapshot(
+        path,
+        artifact=artifact,
+        schema=schema,
+        validate_cross_fields=validate_cross_fields,
+    ).value
+
+
+def load_owned_object_snapshot(
+    path: Path,
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> OwnedJsonSnapshot:
+    """한 번 읽은 바이트에서 객체를 파싱·검증해 함께 반환한다."""
+    try:
+        raw_bytes = path.read_bytes()
+        value = json.loads(
+            raw_bytes.decode("utf-8"),
+            parse_constant=_reject_nonstandard_json_constant,
+        )
+    except FileNotFoundError as exc:
+        raise JsonBoundaryError(path, artifact, "missing") from exc
+    except UnicodeDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON encoding") from exc
+    except _NonstandardJsonConstant as exc:
+        raise JsonBoundaryError(path, artifact, str(exc)) from exc
+    except json.JSONDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON") from exc
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
+    return OwnedJsonSnapshot(
+        value=_validate_owned(
+            value,
+            path=path,
+            artifact=artifact,
+            schema=schema,
+            validate_cross_fields=validate_cross_fields,
+        ),
+        raw_bytes=raw_bytes,
+    )
+
+
+def load_external_json(
+    source: ExternalJsonSource,
+    *,
+    artifact: str,
+    object_pairs_hook: Callable[[list[tuple[str, Any]]], Any] | None = None,
+) -> Any:
+    """Load external JSON without applying an owned-artifact contract."""
+    if not isinstance(source, ExternalJsonSource):
+        raise TypeError("load_external_json requires ExternalJsonSource")
+    path = source.path
+    try:
+        return json.loads(
+            path.read_text(encoding="utf-8"),
+            object_pairs_hook=object_pairs_hook,
+        )
+    except FileNotFoundError as exc:
+        raise JsonBoundaryError(path, artifact, "missing") from exc
+    except UnicodeDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON encoding") from exc
+    except json.JSONDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON") from exc
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
+
+
+def write_owned_object_atomic(
+    path: Path,
+    payload: Mapping[str, Any],
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> None:
+    """Validate a payload before atomically replacing an owned artifact."""
+    serialized = serialize_owned_object(
+        path,
+        payload,
+        artifact=artifact,
+        schema=schema,
+        validate_cross_fields=validate_cross_fields,
+    )
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, raw_temp = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while preparing write ({exc})") from exc
+    temporary = Path(raw_temp)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(serialized)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except (TypeError, ValueError) as exc:
+        raise JsonBoundaryError(path, artifact, f"JSON serialization failed ({exc})") from exc
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while writing ({exc})") from exc
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def serialize_owned_object(
+    path: Path,
+    payload: Mapping[str, Any],
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> str:
+    """전용 게시 프로토콜이 사용할 검증된 canonical 객체 문자열이다."""
+    owned = _validate_owned(
+        payload, path=path, artifact=artifact, schema=schema,
+        validate_cross_fields=validate_cross_fields,
+    )
+    try:
+        return json.dumps(
+            owned, ensure_ascii=False, indent=2, allow_nan=False
+        ) + "\n"
+    except (TypeError, ValueError) as exc:
+        raise JsonBoundaryError(
+            path, artifact, f"JSON serialization failed ({exc})"
+        ) from exc
+
+
+def mutate_owned_object_atomic(
+    path: Path,
+    mutation: Callable[[dict[str, Any]], dict[str, Any]],
+    **contract: Any,
+) -> dict[str, Any]:
+    """Load, mutate, validate, and atomically replace one owned object."""
+    payload = load_owned_object(path, **contract)
+    updated = mutation(dict(payload))
+    write_owned_object_atomic(path, updated, **contract)
+    return updated
+
+
+def _reject_nonstandard_json_constant(constant: str) -> None:
+    raise _NonstandardJsonConstant(f"non-standard JSON constant: {constant}")
+
+
+def _validate_owned(
+    value: object,
+    *,
+    path: Path,
+    artifact: str,
+    schema: Mapping[str, Any] | None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None,
+) -> dict[str, Any]:
+    if not isinstance(value, Mapping):
+        raise JsonBoundaryError(path, artifact, "top-level JSON value must be an object")
+    owned = dict(value)
+    if schema is not None:
+        try:
+            schema_errors = validate_schema(owned, dict(schema))
+        except SchemaError as exc:
+            raise JsonBoundaryError(path, artifact, f"invalid schema ({exc})") from exc
+        if schema_errors:
+            raise JsonBoundaryError(path, artifact, f"schema validation failed ({schema_errors[0]})")
+    if validate_cross_fields is not None:
+        errors = validate_cross_fields(owned)
+        if isinstance(errors, str):
+            errors = [errors]
+        if errors:
+            raise JsonBoundaryError(path, artifact, f"cross-field validation failed ({next(iter(errors))})")
+    return owned

package/runtime/python/okstra_ctl/json_registry.py

@@ -3,11 +3,15 @@ from __future__ import annotations
 
 import contextlib
 import fcntl
-import json
-import os
 from collections.abc import Callable, Iterator
 from pathlib import Path
 
+from .json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
+
 
 @contextlib.contextmanager
 def registry_lock(lock_path: Path) -> Iterator[None]:
@@ -26,18 +30,12 @@ def registry_lock(lock_path: Path) -> Iterator[None]:
 
 def load_registry_json(path: Path, default_factory: Callable[[], dict]) -> dict:
     """Load a registry dict, or a fresh default when absent/corrupt."""
-    if not path.exists():
-        return default_factory()
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        return load_owned_object(path, artifact="registry")
+    except JsonBoundaryError:
         return default_factory()
-    return data if isinstance(data, dict) else default_factory()
 
 
 def save_registry_json(path: Path, data: dict) -> None:
-    """Persist registry JSON via temp file + ``os.replace``."""
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    os.replace(tmp, path)
+    """Persist registry JSON through the owned-artifact boundary."""
+    write_owned_object_atomic(path, data, artifact="registry")

package/runtime/python/okstra_ctl/jsonl.py

@@ -8,14 +8,31 @@ from pathlib import Path
 from typing import Callable, List, Optional
 
 
-def append_jsonl(path: Path, row: dict) -> None:
+def append_jsonl(
+    path: Path, row: dict, *, ensure_ascii: bool = True, compact: bool = True
+) -> None:
     """jsonl 파일 끝에 한 줄 append. 파일이 없으면 생성."""
     path.parent.mkdir(parents=True, exist_ok=True)
-    line = json.dumps(row, separators=(",", ":")) + "\n"
+    line = json.dumps(
+        row, separators=(",", ":") if compact else None,
+        ensure_ascii=ensure_ascii,
+    ) + "\n"
     with path.open("a") as f:
         f.write(line)
 
 
+def rewrite_jsonl(path: Path, rows: List[dict], *, ensure_ascii: bool = True) -> None:
+    """JSONL 행 전체를 임시 파일에 쓴 뒤 원자 교체한다."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    with temporary.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(
+                row, separators=(",", ":"), ensure_ascii=ensure_ascii
+            ) + "\n")
+    os.replace(temporary, path)
+
+
 def read_jsonl(path: Path) -> List[dict]:
     """jsonl 파일을 모두 읽어 dict 목록으로 반환. 파싱 실패 라인은 스킵."""
     if not path.is_file():

package/runtime/python/okstra_ctl/lead_events.py

@@ -2,7 +2,9 @@
 from __future__ import annotations
 
 import json
+import hashlib
 import re
+import uuid
 from contextlib import contextmanager
 from dataclasses import dataclass, field, replace
 from pathlib import Path
@@ -107,14 +109,44 @@ def _next_activity_id(events: list[LeadEvent]) -> str:
     return f"A-{max(numbers, default=0) + 1:03d}"
 
 
+def _activity_request_digest(details: Mapping[str, Any]) -> str:
+    payload = {
+        key: value for key, value in details.items()
+        if key not in {"activityId", "activityRequestDigest", "activityRequestRef", "activityVersion"}
+    }
+    encoded = json.dumps(_stable_json_value(payload), ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
 def append_activity_event(path: Path, event: LeadEvent) -> LeadEvent:
     """Assign the next activity ID and append the event under one lock."""
     if event.event_type != "activity":
         raise ValueError("activity append requires eventType=activity")
     with _event_log_lock(path):
         details = dict(event.details)
+        request_ref = details.get("activityRequestRef")
+        events = read_lead_events(path)
+        digest = _activity_request_digest(details)
+        if request_ref is not None:
+            if not isinstance(request_ref, str) or not request_ref:
+                raise ValueError("activityRequestRef must be a non-empty string")
+            for previous in events:
+                if (
+                    previous.event_type == event.event_type
+                    and previous.lead_runtime == event.lead_runtime
+                    and previous.task_key == event.task_key
+                    and previous.task_type == event.task_type
+                    and previous.run_seq == event.run_seq
+                    and previous.details.get("activityRequestRef") == request_ref
+                ):
+                    if previous.details.get("activityRequestDigest") != digest:
+                        raise ValueError("activity request reference has different payload")
+                    return previous
+            raise ValueError("unknown activity request reference")
+        details["activityRequestRef"] = f"activity-{uuid.uuid4().hex}"
+        details["activityRequestDigest"] = digest
         details["activityVersion"] = 1
-        details["activityId"] = _next_activity_id(read_lead_events(path))
+        details["activityId"] = _next_activity_id(events)
         stored = replace(event, details=details)
         _append_unlocked(path, stored)
     return stored