pgc-runtime 2.0.0__py3-none-any.whl

runtime/dispatcher.py

@@ -0,0 +1,448 @@
+"""
+dispatcher.py — CC-level pipeline executor for the token-native runtime.
+
+Executes a single Capability Contract by iterating its compiled pipeline steps.
+Each step is a named-field execution instruction record materialized by the
+compiler — the dispatcher consumes them blindly with no semantic reconstruction.
+
+Consumed from RuntimePackage:
+    pkg.dispatch.pipeline[cc_addr]             — ordered list of step dicts
+    pkg.handlers.ct[ct_addr]["ct_ir"]          — CT-IR for pure transforms
+    pkg.handlers.cs[cs_addr]                   — handler_ref + cs_metadata for side effects
+    pkg.handlers.rb_policy[rb_addr][cs_addr]   — per-binding config (path, etc.)
+    pkg.vocab.fqdn(addr)                       — address → FQDN for trace labels
+
+Pipeline step format (named-field execution instruction record):
+    {
+        "addr":      int,        # CT or CS integer address
+        "op":        str|None,   # None for CT, operation name for CS
+        "inputs":    dict|None,  # resolved input bindings
+        "outputs":   dict|None,  # surface mapping: {cc_field: "$.capability_result.ct_field"}
+        "on_result": dict|None,  # continuation: {"SUCCESS": "continue", "VIOLATION": "exit"}
+        "step_id":   str,        # symbolic name for cross-step $.results.<step_id>.X refs
+    }
+
+Input path grammar (step-level, compiler-emitted):
+    $.inputs.<field>               — CC-level input (from cc_inputs)
+    $.results.<step_id>.<field>    — previous step output (from step_results)
+    <anything else>                — literal value (returned as-is)
+
+Output path grammar:
+    $.capability_result.<field>    — extract named field from raw step result
+
+on_result actions:
+    "continue"   — proceed to next step (default if status not listed)
+    "exit"       — terminate pipeline and return this result_status
+
+Result status:
+    CT steps:  "SUCCESS" on completion, "VIOLATION" on any exception
+    CS steps:  raw_result["result_status"] (declared by the CS runtime)
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from typing import Any
+
+from runtime.loader import RuntimePackage
+from runtime.evidence import TraceWriter
+from runtime.ct_execute import execute_ct
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def execute_cc(
+    cc_addr:   int,
+    rb_addr:   int,
+    cc_inputs: dict[str, Any],
+    pkg:       RuntimePackage,
+    writer:    TraceWriter,
+    data_root: str,
+    wf_addr:   int = -1,
+) -> tuple[str, dict[str, Any]]:
+    """
+    Execute a CC pipeline and return (result_status, surface).
+
+    Args:
+        cc_addr:   Integer address of the Capability Contract to execute.
+        rb_addr:   Integer address of the Runtime Binding governing this CC.
+        cc_inputs: Resolved inputs for this CC (already bound by the scheduler).
+        pkg:       Frozen RuntimePackage (loader output).
+        writer:    TraceWriter for this execution trace.
+        data_root: Absolute data directory root (for {{module_data_root}} expansion).
+
+    Returns:
+        (result_status, surface) where:
+            result_status — final outcome string (e.g. "SUCCESS", "VIOLATION")
+            surface       — dict of CC-level named outputs for downstream binding
+    """
+    cc_fqdn = pkg.vocab.fqdn(cc_addr)
+    writer.cc_start(cc_addr, cc_fqdn, cc_inputs)
+
+    steps = pkg.dispatch.pipeline.get(cc_addr, [])
+    step_results: dict[str, dict[str, Any]] = {}  # step_id → surface fragment
+    surface: dict[str, Any] = {}
+    result_status = "SUCCESS"
+
+    # Build a workflow executor closure for CS types that need nested WF invocation.
+    # Injected unconditionally — CSs that don't need it ignore it.
+    wf_executor = _make_workflow_executor(pkg, writer, data_root)
+
+    for step in steps:
+        step_addr:   int        = step["addr"]
+        op:          str | None = step.get("op")
+        inputs_spec: dict       = step.get("inputs") or {}
+        outputs_spec: dict      = step.get("outputs") or {}
+        on_result:   dict       = step.get("on_result") or {}
+        # The compiler emits a step's name under `step`; `step_id` was the older spelling and is
+        # still honoured. Reading only the latter left `step_results` unkeyed, so every
+        # `$.results.<step>.<field>` resolved to None — a binding the grammar accepts, the compiler
+        # renders and the runtime silently dropped.
+        step_id:     str        = step.get("step_id") or step.get("step") or ""
+
+        # Resolve step inputs from CC inputs and accumulated step results
+        resolved_inputs = _resolve_step_inputs(inputs_spec, cc_inputs, step_results)
+
+        # --- Execute step ---
+        if op is None:
+            # CT step — pure computation, zero side effects
+            result_status, raw_result = _execute_ct_step(step_addr, resolved_inputs, pkg)
+        else:
+            # CS step — controlled side effect via declared handler
+            result_status, raw_result = _execute_cs_step(
+                step_addr, op, resolved_inputs, rb_addr, pkg, data_root, wf_executor, wf_addr
+            )
+
+        # Apply outputs mapping: {cc_field: "$.capability_result.<ct_field>"} → surface fragment
+        surface_fragment = _apply_outputs(outputs_spec, raw_result, step_results)
+
+        # Store surface fragment + raw capability_result for cross-step references.
+        # $.results.<step_id>.<field>              — addresses the mapped surface
+        # $.results.<step_id>.capability_result.<field> — addresses the raw result
+        if step_id:
+            step_results[step_id] = {**surface_fragment, "capability_result": raw_result}
+
+        # Accumulate into CC surface
+        surface.update(surface_fragment)
+
+        # Emit step trace event
+        writer.cc_step(
+            cc_addr,
+            step_addr,
+            pkg.vocab.fqdn(step_addr),
+            op,
+            surface_fragment,
+        )
+
+        # Route: "exit" → break pipeline; "continue" (or unlisted) → proceed
+        action = on_result.get(result_status, "continue")
+        if action == "exit":
+            break
+
+    # Merge cc_inputs fields not covered by pipeline outputs into the surface.
+    # The pipeline outputs_spec is compiler-declared and may not map every input
+    # field (e.g. CC_STORE_RESULTS receives sequences/all_terminate/non_terminating
+    # as cc_inputs but only declares result_status in its outputs). Merging here
+    # restores the expected surface without changing the pipeline contract.
+    _INTERNAL_KEYS = {"__store__", "__pgs_store_entity__"}
+    for key, value in cc_inputs.items():
+        if key not in surface and key not in _INTERNAL_KEYS:
+            surface[key] = value
+
+    writer.cc_complete(cc_addr, cc_fqdn, result_status, surface)
+    return result_status, surface
+
+
+# ---------------------------------------------------------------------------
+# Step executors
+# ---------------------------------------------------------------------------
+
+def _execute_ct_step(
+    ct_addr: int,
+    resolved_inputs: dict[str, Any],
+    pkg: RuntimePackage,
+) -> tuple[str, dict[str, Any]]:
+    """
+    Execute a CT (pure transform) step.
+
+    Returns ("SUCCESS", ct_outputs) on completion.
+    Returns ("VIOLATION", {}) on any exception — CT failure is a protocol violation.
+    """
+    ct_entry = pkg.handlers.ct.get(ct_addr)
+    if ct_entry is None:
+        raise RuntimeError(
+            f"CT addr {ct_addr} not found in handlers — snapshot may be stale"
+        )
+    ct_ir = ct_entry.get("ct_ir", {})
+
+    try:
+        raw_result = execute_ct(ct_ir, resolved_inputs)
+        return "SUCCESS", (raw_result if isinstance(raw_result, dict) else {})
+    except Exception:
+        # CT exception → protocol VIOLATION; do not propagate
+        return "VIOLATION", {}
+
+
+def _make_workflow_executor(
+    pkg: RuntimePackage,
+    writer: TraceWriter,
+    data_root: str,
+):
+    """
+    Build a workflow executor callable for injection into CS config.
+
+    The returned callable lets CS implementations invoke sub-workflows without
+    importing the scheduler directly (avoids circular imports at module load time).
+
+    Interface: executor(wf_fqdn: str, payload: dict) -> (result_status: str, surface: dict)
+    """
+    def executor(wf_fqdn_or_addr, payload: dict) -> tuple[str, dict]:
+        from runtime.scheduler import run_wf  # lazy import — avoids circular dependency
+        # Compiler tokenizes nested dict string values to int addresses.
+        # CS_WORKFLOW_LOOP_V0 receives int addrs from the compiled mapping; resolve to FQDN here.
+        if isinstance(wf_fqdn_or_addr, int):
+            wf_fqdn_or_addr = pkg.vocab.fqdn(wf_fqdn_or_addr)
+        return run_wf(wf_fqdn_or_addr, payload, pkg, writer, data_root)
+    return executor
+
+
+def _execute_cs_step(
+    cs_addr: int,
+    op: str,
+    resolved_inputs: dict[str, Any],
+    rb_addr: int,
+    pkg: RuntimePackage,
+    data_root: str,
+    wf_executor=None,
+    wf_addr: int = -1,
+) -> tuple[str, dict[str, Any]]:
+    """
+    Execute a CS (side effect) step.
+
+    Looks up the CS handler and per-binding policy, expands path templates,
+    instantiates the CS runtime, and calls execute(op, payload).
+
+    Returns (result_status, raw_result) where result_status is declared by the CS.
+    """
+    cs_entry = pkg.handlers.cs.get(cs_addr)
+    if cs_entry is None:
+        raise RuntimeError(
+            f"CS addr {cs_addr} not found in handlers — snapshot may be stale"
+        )
+
+    # Resolve per-RB policy config for this CS
+    rb_cs_map = pkg.handlers.rb_policy.get(rb_addr, {})
+    policy_entry = rb_cs_map.get(cs_addr, {})
+    policy_raw = policy_entry.get("policy") or {}
+
+    # An act that declared a reach resolves against the composed description the compiler sealed
+    # for it — its own entities and the consulted ones, each marked. Handed over, not resolved
+    # here: the runtime reads what the composition gives it.
+    composed = pkg.handlers.wf_storage.get(wf_addr)
+    if composed is not None and policy_raw.get("storage_structure_artifact") is not None:
+        policy_raw = {**policy_raw, "storage_structure_artifact": composed}
+
+    policy = _expand_policy(policy_raw, data_root, pkg.snapshot_root)
+
+    # A reach reads and never writes. The operation declares whether it writes and the composed
+    # description declares whether the entity is consulted, so the refusal rests on two declared
+    # facts and infers nothing. Refused before the capability runs, because a write that has
+    # happened cannot be unhappened.
+    store_entity = resolved_inputs.get("__store__")
+    if composed is not None and store_entity:
+        entity = (composed.get("frontmatter", {}).get("core", {})
+                  .get("entity_stores", {}).get(store_entity, {}))
+        effect = ((cs_entry.get("cs_metadata", {}).get("operations", {})
+                   .get("operations", {}).get(op, {})).get("effect"))
+        if entity.get("reach") == "consulted" and effect == "write":
+            # VIOLATION rather than an exception: a step states its outcome and the act routes on
+            # it, which is how every other refusal reaches the workflow. Returned before the
+            # capability runs, because a write that has happened cannot be unhappened.
+            return "VIOLATION", {
+                "result_status": "VIOLATION",
+                "refusal": "REACH_IS_READ_ONLY",
+                "store": store_entity,
+                "described_by": entity.get("described_by"),
+                "message": (
+                    f"act may not write to '{store_entity}': it is described by "
+                    f"{entity.get('described_by')}, which this act consults and does not own. "
+                    f"The subdomain that owns a record is the only writer of it"
+                ),
+            }
+
+    # Inject workflow executor for CS types that need nested WF invocation.
+    # Injected unconditionally — CSs that don't use it ignore the key.
+    if wf_executor is not None:
+        policy = {**policy, "workflow_executor": wf_executor}
+
+    # Instantiate CS runtime
+    handler_ref = cs_entry["handler_ref"]
+    cs_metadata = cs_entry.get("cs_metadata", {})
+    cs_fqdn = pkg.vocab.fqdn(cs_addr)
+
+    mod = importlib.import_module(handler_ref["module"])
+    cls = getattr(mod, handler_ref["callable"])
+    runtime = cls(config=policy, metadata=cs_metadata, capability_code=cs_fqdn)
+
+    # Translate __store__ (compiler-emitted entity tag) to __pgs_store_entity__ (CS protocol key)
+    store_entity = resolved_inputs.get("__store__")
+    cs_inputs = {k: v for k, v in resolved_inputs.items() if k != "__store__"}
+    if store_entity:
+        cs_inputs["__pgs_store_entity__"] = store_entity
+
+    raw_result = runtime.execute(op=op, payload=cs_inputs)
+    if not isinstance(raw_result, dict):
+        raw_result = {}
+
+    result_status = raw_result.get("result_status", "SUCCESS")
+    return result_status, raw_result
+
+
+# ---------------------------------------------------------------------------
+# Input resolution
+# ---------------------------------------------------------------------------
+
+def _resolve_step_inputs(
+    inputs_spec: dict[str, Any],
+    cc_inputs: dict[str, Any],
+    step_results: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    """
+    Resolve step input bindings to concrete values.
+
+    Path grammar:
+        $.inputs.<field>               → cc_inputs[field]
+        $.results.<step_id>.<field>    → step_results[step_id][field]
+        <other>                        → literal (returned as-is)
+    """
+    resolved: dict[str, Any] = {}
+    for key, value in inputs_spec.items():
+        resolved[key] = _resolve_value(value, cc_inputs, step_results)
+    return resolved
+
+
+def _resolve_value(
+    value: Any,
+    cc_inputs: dict[str, Any],
+    step_results: dict[str, dict[str, Any]],
+) -> Any:
+    """Resolve a single binding value — recursively handles nested dicts/lists."""
+    if isinstance(value, str):
+        if value.startswith("$.inputs."):
+            field = value[len("$.inputs."):]
+            return _nested_get(cc_inputs, field)
+
+        if value.startswith("$.results."):
+            # $.results.<step_id>.<field>[.<nested>...]
+            after = value[len("$.results."):]
+            dot = after.find(".")
+            if dot < 0:
+                return None  # malformed path
+            step_id = after[:dot]
+            field_path = after[dot + 1:]
+            step_surface = step_results.get(step_id, {})
+            return _nested_get(step_surface, field_path)
+
+        # Literal string value
+        return value
+
+    if isinstance(value, dict):
+        return {k: _resolve_value(v, cc_inputs, step_results) for k, v in value.items()}
+
+    if isinstance(value, (list, tuple)):
+        return [_resolve_value(v, cc_inputs, step_results) for v in value]
+
+    return value  # int, float, bool, None — returned as-is
+
+
+def _nested_get(obj: Any, dotted_key: str) -> Any:
+    """Traverse a nested dict by a dot-separated key path. Returns None on miss."""
+    parts = dotted_key.split(".")
+    current = obj
+    for part in parts:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Output mapping
+# ---------------------------------------------------------------------------
+
+def _apply_outputs(
+    outputs_spec: dict[str, str],
+    raw_result: dict[str, Any],
+    step_results: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    """
+    Apply the compiler-emitted outputs mapping to the raw step result.
+
+    Supported path prefixes:
+        $.capability_result.<field>        — field from this step's raw result
+        $.results.<step_id>.<field>        — field from a prior step's surface fragment
+
+    Unmapped fields from raw_result are NOT included — surface is compiler-declared.
+    """
+    if not outputs_spec:
+        return {}
+
+    fragment: dict[str, Any] = {}
+    for surface_field, path in outputs_spec.items():
+        if not isinstance(path, str):
+            fragment[surface_field] = path
+        elif path.startswith("$.capability_result."):
+            result_field = path[len("$.capability_result."):]
+            fragment[surface_field] = _nested_get(raw_result, result_field)
+        elif path.startswith("$.results."):
+            after = path[len("$.results."):]
+            dot = after.find(".")
+            if dot < 0:
+                fragment[surface_field] = None
+            else:
+                step_id = after[:dot]
+                field_path = after[dot + 1:]
+                step_surface = step_results.get(step_id, {})
+                fragment[surface_field] = _nested_get(step_surface, field_path)
+        elif path.startswith("$."):
+            # Bare $.field path — direct reference into the raw step result
+            field_path = path[len("$."):]
+            fragment[surface_field] = _nested_get(raw_result, field_path)
+        else:
+            # Literal value — returned as-is
+            fragment[surface_field] = path
+
+    return fragment
+
+
+# ---------------------------------------------------------------------------
+# Policy template expansion
+# ---------------------------------------------------------------------------
+
+def _expand_policy(
+    policy_raw: dict[str, Any], data_root: str, snapshot_root: str = ""
+) -> dict[str, Any]:
+    """
+    Expand path templates in the CS policy config.
+
+        {{module_data_root}}   where a capability keeps its state
+        {{snapshot_root}}      the composition this workflow is executing from
+
+    The second exists for capabilities that *observe* the composition rather than store state in
+    it. Such a capability must be bound to the snapshot it is running inside — if the root came
+    from a caller, a workflow could be pointed at a different composition and would report
+    confidently about the wrong one.
+
+    Serializes to JSON, replaces the template strings, deserializes back. Both roots must be
+    absolute path strings — never relative.
+    """
+    if not policy_raw:
+        return {}
+
+    policy_str = json.dumps(policy_raw)
+    policy_str = policy_str.replace("{{module_data_root}}", str(data_root).rstrip("/"))
+    policy_str = policy_str.replace("{{snapshot_root}}", str(snapshot_root).rstrip("/"))
+    return json.loads(policy_str)

runtime/evidence.py

@@ -0,0 +1,245 @@
+"""
+evidence.py — Structured trace event emitter for the token-native runtime.
+
+Writes append-only JSONL trace events to the trace output directory.
+Each execution event is a self-contained JSON line with:
+    - trace_id      — deterministic per-invocation ID
+    - event_type    — WF_START, CC_START, CC_STEP, CC_COMPLETE, WF_COMPLETE, ERROR
+    - domain        — domain/structure identifier (e.g. "blockchain")
+    - wf_addr       — integer WF address
+    - cc_addr       — integer CC address (None for WF-level events)
+    - step_addr     — integer step (CT/CS) address (None for CC-level events)
+    - step_op       — CS operation name or None for CT steps
+    - result_status — outcome string (e.g. "SUCCESS") or None
+    - detail        — arbitrary dict (serializable)
+    - ts_ns         — monotonic nanosecond timestamp
+
+The trace file is written to:
+    <traces_root>/<domain>/<wf_code>/<trace_id>/<trace_id>.jsonl
+
+subdomain is not known to this module — caller passes the full trace dir path.
+
+This module produces the raw JSONL evidence only. Evidence projection
+(execution-path PNG overlay) is handled separately in trace_viz.py.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+
+CLASSIFICATION_FQDN = "vocabulary::VOCAB_EVIDENCE_CONTENT_CLASSIFICATION_V0"
+
+
+def _content_classification(snapshot_root: Path) -> dict[str, list[str]]:
+    """Which trace content is determinative and which observational, from the sealed composition.
+
+    `3e` EV-5 requires the distinction be declared rather than inferred, and the declaration is a
+    governed artifact rather than a constant here — adding a field is an authoring act, sealed and
+    attested. No fallback: evidence written under an unknown classification is evidence a checker
+    cannot compare, which is the state EV-5 exists to end.
+    """
+    for path in (snapshot_root / "canonical").rglob("*.json"):
+        if path.name == "metadata.json":
+            continue
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if data.get("fqdn_id") != CLASSIFICATION_FQDN:
+            continue
+        fm = data.get("frontmatter") or {}
+        return {
+            "determinative": list(fm["determinative_fields"]["entries"]),
+            "observational": list(fm["observational_fields"]["entries"]),
+        }
+    raise RuntimeError(
+        f"{CLASSIFICATION_FQDN} is not in the composition at {snapshot_root} — the "
+        f"determinative/observational classification this trace would be written under is not in "
+        f"force (3e EV-5)."
+    )
+
+
+class TraceWriter:
+    """
+    Append-only trace writer for a single workflow execution.
+
+    Usage:
+        writer = TraceWriter(trace_dir, trace_id, domain, wf_addr, wf_fqdn)
+        writer.wf_start(payload)
+        writer.cc_start(cc_addr, cc_fqdn, cc_inputs)
+        writer.cc_step(cc_addr, step_addr, step_fqdn, op, result)
+        writer.cc_complete(cc_addr, result_status, outputs)
+        writer.wf_complete(result_status)
+        writer.close()
+    """
+
+    def __init__(
+        self,
+        trace_dir: Path,
+        trace_id: str,
+        domain: str,
+        wf_addr: int,
+        wf_fqdn: str,
+        snapshot_root: Path,
+        snapshot_id: str,
+    ) -> None:
+        trace_dir.mkdir(parents=True, exist_ok=True)
+        self._path = trace_dir / f"{trace_id}.jsonl"
+        self._fh = self._path.open("a", encoding="utf-8")
+        self._trace_id = trace_id
+        self._domain = domain
+        self._wf_addr = wf_addr
+        self._wf_fqdn = wf_fqdn
+
+        # The trace states which of its content is determinative, as its first record. Evidence that
+        # carried the values and not the classification would be evidence a checker had to guess at,
+        # and `3e` §5.2 says a checker that guesses is deciding for itself what governance meant.
+        # Carried in the trace rather than looked up later so the record is checkable by a party with
+        # no access to the producing system (EV-16, AI-16).
+        classification = _content_classification(snapshot_root)
+        self._fh.write(json.dumps({
+            "trace_schema_version": "v0",
+            "event_type": "trace_classification",
+            "classified_by": CLASSIFICATION_FQDN,
+            # Which closure applied — `3e` §3.1 point 1. At execution the sealed snapshot IS the
+            # closure: SN-10 makes it the sole source of governed behaviour, so naming it names
+            # every governing element that applied and every rule the closure supplied. A checker
+            # holding this id and the snapshot can resolve every address below to what governed it.
+            "snapshot_id": snapshot_id,
+            **classification,
+        }, separators=(",", ":")) + "\n")
+        self._fh.flush()
+
+    # --- Public event methods ---
+
+    def wf_start(self, payload: dict[str, Any], actor: str | None = None) -> None:
+        # Authority: attribute the actor context this WF executes under (declaration/binding only —
+        # not an authorization decision). Absent when the WF binds no actor.
+        detail = {"wf_fqdn": self._wf_fqdn, "payload_keys": list(payload.keys())}
+        if actor:
+            detail["actor"] = actor
+        self._emit("WF_START", detail=detail)
+
+    def event(self, ev_fqdn: str, payload: dict[str, Any]) -> None:
+        # Observation: a governed domain event (EV_) emitted during execution, recorded in the trace.
+        self._emit("EVENT", detail={"ev_fqdn": ev_fqdn, "payload": payload})
+
+    def cc_start(self, cc_addr: int, cc_fqdn: str, cc_inputs: dict[str, Any]) -> None:
+        self._emit("CC_START", cc_addr=cc_addr, detail={"cc_fqdn": cc_fqdn, "inputs": cc_inputs})
+
+    def cc_step(
+        self,
+        cc_addr: int,
+        step_addr: int,
+        step_fqdn: str,
+        op: str | None,
+        result: dict[str, Any],
+    ) -> None:
+        self._emit(
+            "CC_STEP",
+            cc_addr=cc_addr,
+            step_addr=step_addr,
+            step_op=op,
+            detail={"step_fqdn": step_fqdn, "result_keys": list(result.keys())},
+        )
+
+    def cc_complete(
+        self,
+        cc_addr: int,
+        cc_fqdn: str,
+        result_status: str,
+        outputs: dict[str, Any],
+    ) -> None:
+        self._emit(
+            "CC_COMPLETE",
+            cc_addr=cc_addr,
+            result_status=result_status,
+            detail={"cc_fqdn": cc_fqdn, "output_keys": list(outputs.keys())},
+        )
+
+    def wf_complete(self, result_status: str) -> None:
+        self._emit("WF_COMPLETE", result_status=result_status, detail={"wf_fqdn": self._wf_fqdn})
+
+    def route(self, from_addr: int | None, condition: str, to_addr: int | None) -> None:
+        """The routing determination — `3e` §3.1 point 4, the dominant consequence.
+
+        The trace recorded the sequence of nodes and not the decision that produced it. A reader
+        could see that one contract followed another and not that the transition was the one the
+        sealed routing table declared for that outcome. Recording the decision makes the path
+        checkable against the representation rather than merely consistent with it (EX-15).
+
+        `to_addr` None is terminal: the outcome routed nowhere, which is the traversal ending.
+        """
+        self._emit("WF_ROUTE", cc_addr=from_addr, step_addr=to_addr, result_status=condition,
+                   detail={"terminal": to_addr is None})
+
+    def error(self, message: str, **extra: Any) -> None:
+        self._emit("ERROR", detail={"message": message, **extra})
+
+    def close(self) -> None:
+        if not self._fh.closed:
+            self._fh.close()
+
+    # --- Internal ---
+
+    def _emit(
+        self,
+        event_type: str,
+        cc_addr: int | None = None,
+        step_addr: int | None = None,
+        step_op: str | None = None,
+        result_status: str | None = None,
+        detail: dict[str, Any] | None = None,
+    ) -> None:
+        event = {
+            "trace_schema_version": "v0",
+            "trace_id":      self._trace_id,
+            "event_type":    event_type,
+            "domain":        self._domain,
+            "wf_addr":       self._wf_addr,
+            "cc_addr":       cc_addr,
+            "step_addr":     step_addr,
+            "step_op":       step_op,
+            "result_status": result_status,
+            "detail":        detail or {},
+            "ts_ns":         time.monotonic_ns(),
+        }
+        self._fh.write(json.dumps(event, separators=(",", ":")) + "\n")
+        self._fh.flush()
+
+
+# ---------------------------------------------------------------------------
+# Trace ID generation
+# ---------------------------------------------------------------------------
+
+def make_trace_id(domain: str, wf_fqdn: str, payload: dict[str, Any]) -> str:
+    """
+    Generate a human-sortable trace ID from (domain, wf_fqdn, payload).
+
+    Format: YYYYMMDDTHHMMSSmmmZ__WF_CODE__XXXX
+        - Timestamp prefix (UTC, millisecond resolution) — chronological sort
+        - WF code extracted from wf_fqdn — self-describing
+        - 4-char uppercase hex suffix from sha256(wf_fqdn + payload) — weak idempotency signal
+
+    Example: 20260524T151422183Z__WF_CREATE_WALLET_V0__A7K2
+
+    Not purely deterministic (timestamp advances each call). The hash suffix
+    signals identical-input executions without enforcing uniqueness.
+    """
+    from datetime import datetime, timezone
+
+    now = datetime.now(timezone.utc)
+    ts = now.strftime("%Y%m%dT%H%M%S") + f"{now.microsecond // 1000:03d}Z"
+    wf_code = wf_fqdn.split("::")[-1]  # e.g. "WF_CREATE_WALLET_V0"
+
+    canonical = json.dumps(
+        {"domain": domain, "wf": wf_fqdn, "payload": payload},
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=True,
+    )
+    suffix = hashlib.sha256(canonical.encode()).hexdigest()[:4].upper()
+
+    return f"{ts}__{wf_code}__{suffix}"