pgs-runtime 0.3.1__tar.gz → 0.5.0__tar.gz

{pgs_runtime-0.3.1/pgs_runtime.egg-info → pgs_runtime-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgs_runtime
-Version: 0.3.1
+Version: 0.5.0
 Summary: PGS runtime for Protocol-Governed Systems
 Author: Bachi
 License-Expression: Apache-2.0
@@ -29,7 +29,7 @@ It does not discover behavior. It does not interpret intent. It does not contain
 
 Behavior is declared in protocol, executed by runtime, implemented in capabilities, and observed via traces and state.
 
-> **New to PGS?** This is one of eight repositories in the Protocol-Governed Systems ecosystem.
+> **New to PGS?** This is one of the repositories in the Protocol-Governed Systems ecosystem.
 > For orientation, architecture overview, and end-to-end execution, start at [pgs_workspace](https://github.com/bachipeachy/pgs_workspace).
 
 ---

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/README.md

@@ -7,7 +7,7 @@ It does not discover behavior. It does not interpret intent. It does not contain
 
 Behavior is declared in protocol, executed by runtime, implemented in capabilities, and observed via traces and state.
 
-> **New to PGS?** This is one of eight repositories in the Protocol-Governed Systems ecosystem.
+> **New to PGS?** This is one of the repositories in the Protocol-Governed Systems ecosystem.
 > For orientation, architecture overview, and end-to-end execution, start at [pgs_workspace](https://github.com/bachipeachy/pgs_workspace).
 
 ---

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pgs_runtime/cli.py

@@ -2,16 +2,18 @@
 cli.py — Token-native CLI entry point for the pgs_runtime.
 
 Commands:
-    run     — Execute a workflow against the tokenized snapshot.
-    examine — Analyze a completed trace file and print a diagnostic report.
+    run           — Execute a workflow against the tokenized snapshot.
+    examine       — Analyze a completed trace file and print a diagnostic report.
+    behavior-logic — Render execution-path PNG from a completed trace file.
 
 Execution path (run):
     1. Load tokenized snapshot for the domain via loader.load_domain()
        — verifies topology hash against trust attestation; fails hard on mismatch
     2. Generate deterministic trace ID from (domain, wf_fqdn, payload)
-    3. Open TraceWriter at traces/<domain>/<trace_id>/
+    3. Open TraceWriter at traces/<domain>/<wf_code>/<trace_id>/
     4. Drive workflow topology via scheduler.run_wf()
     5. Print result summary; exit 1 on non-SUCCESS
+    6. If --behavior-logic: invoke evidence projection (trace_viz) to render PNG
 
 All runtime behavior comes from the compiled tokenized_snapshot.
 The CLI does not implement any domain logic.
@@ -69,6 +71,14 @@ def _build_parser() -> argparse.ArgumentParser:
              "tokenized_snapshot/ and traces/ live here",
     )
 
+    # ── run: optional behavior-logic flag ────────────────────────
+    run_p.add_argument(
+        "--behavior-logic",
+        action="store_true",
+        dest="behavior_logic",
+        help="Render execution-path PNG after run (requires graphviz)",
+    )
+
     # ── examine ───────────────────────────────────────────────────
     ex_p = subs.add_parser("examine", help="Analyze a completed trace file")
     ex_p.add_argument(
@@ -77,6 +87,22 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Path to a completed .jsonl trace file",
     )
 
+    # ── behavior-logic ────────────────────────────────────────────
+    bl_p = subs.add_parser(
+        "behavior-logic",
+        help="Render execution-path PNG from a completed trace file",
+    )
+    bl_p.add_argument(
+        "trace_file",
+        metavar="FILE",
+        help="Path to a completed .jsonl trace file",
+    )
+    bl_p.add_argument(
+        "--workspace",
+        metavar="PATH",
+        help="Absolute path to pgs_workspace root (or set PGS_WORKSPACE)",
+    )
+
     return parser
 
 
@@ -161,6 +187,12 @@ def _handle_run(args: argparse.Namespace) -> None:
 
     duration_ms = int((time.monotonic() - t0) * 1000)
 
+    # Evidence projection: render execution-path PNG if requested
+    trace_path = trace_dir / f"{trace_id}.jsonl"
+    png_path = None
+    if args.behavior_logic:
+        png_path = _render_behavior_logic(workspace, trace_path)
+
     print("=" * 60)
     print("[pgs_runtime] Workflow Complete")
     print("=" * 60)
@@ -170,12 +202,39 @@ def _handle_run(args: argparse.Namespace) -> None:
     print(f"Duration:   {duration_ms}ms")
     if surface:
         print(f"Output:     {json.dumps(surface, separators=(',', ':'))}")
+    if png_path:
+        print(f"Graph:      {png_path}")
+    elif args.behavior_logic:
+        print("Graph:      (graphviz not available — PNG skipped)")
     print("=" * 60)
 
     if result_status not in ("SUCCESS", "ALREADY_EXISTS"):
         sys.exit(1)
 
 
+def _handle_behavior_logic(args: argparse.Namespace) -> None:
+    trace_path = Path(args.trace_file)
+    if not trace_path.exists():
+        _fatal(f"Trace file not found: {args.trace_file}")
+
+    workspace_str = args.workspace or os.environ.get("PGS_WORKSPACE")
+    if not workspace_str:
+        _fatal("--workspace PATH or PGS_WORKSPACE is required")
+    workspace = Path(workspace_str)
+    if not workspace.is_absolute():
+        _fatal(f"--workspace must be an absolute path, got: {workspace_str}")
+
+    png_path = _render_behavior_logic(workspace, trace_path)
+    if png_path:
+        print(f"[pgs_runtime] Execution path PNG: {png_path}")
+    else:
+        print(
+            "[pgs_runtime] Behavior logic render skipped — graphviz (dot) not available.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
 def _handle_examine(args: argparse.Namespace) -> None:
     trace_path = Path(args.trace_file)
     if not trace_path.exists():
@@ -205,6 +264,16 @@ def _handle_examine(args: argparse.Namespace) -> None:
 # Utilities
 # ---------------------------------------------------------------------------
 
+def _render_behavior_logic(workspace: Path, trace_path: Path) -> "Path | None":
+    """Invoke evidence projection to render execution-path PNG. Best-effort."""
+    from pgs_runtime.trace_viz import render_trace_png
+    try:
+        return render_trace_png(workspace, trace_path)
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"[pgs_runtime] Behavior logic render error: {exc}", file=sys.stderr)
+        return None
+
+
 def _load_payload(payload_path: str | None) -> dict:
     if not payload_path:
         return {}
@@ -234,6 +303,8 @@ def main() -> None:
         _handle_run(args)
     elif args.command == "examine":
         _handle_examine(args)
+    elif args.command == "behavior-logic":
+        _handle_behavior_logic(args)
 
 
 if __name__ == "__main__":

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pgs_runtime/conformance.py

@@ -198,10 +198,22 @@ def run(snapshot_root: Path) -> ConformanceResult:
         expected = artifact.get("expected", {})
         assertions = artifact.get("assertions", {})
 
+        expected_outcome = artifact.get("expected_outcome", "SUCCESS")
+
         try:
             vars_result = executor.execute(ct_ir=ct_ir, inputs=inputs)
             actual = _resolve_outputs(ct_ir, vars_result)
 
+            if expected_outcome == "VIOLATION":
+                # CT completed without error but a VIOLATION was expected.
+                result.failed += 1
+                result.cases.append(CaseResult(
+                    fqdn=fqdn,
+                    passed=False,
+                    error="expected CTExecutionError (VIOLATION) but CT completed without raising",
+                ))
+                continue
+
             # Structural assertions validate non-deterministic fields by shape/type/size.
             # Fields covered by assertions are excluded from exact-match comparison.
             assertion_error = _assert_structural(actual, assertions) if assertions else None
@@ -226,7 +238,12 @@ def run(snapshot_root: Path) -> ConformanceResult:
                 result.cases.append(CaseResult(fqdn=fqdn, passed=True))
 
         except CTExecutionError as e:
-            result.failed += 1
-            result.cases.append(CaseResult(fqdn=fqdn, passed=False, error=str(e)))
+            if expected_outcome == "VIOLATION":
+                # CT raised as expected — PASS.
+                result.passed += 1
+                result.cases.append(CaseResult(fqdn=fqdn, passed=True))
+            else:
+                result.failed += 1
+                result.cases.append(CaseResult(fqdn=fqdn, passed=False, error=str(e)))
 
     return result

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pgs_runtime/dispatcher.py

@@ -86,6 +86,10 @@ def execute_cc(
     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")
@@ -104,7 +108,7 @@ def execute_cc(
         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
+                step_addr, op, resolved_inputs, rb_addr, pkg, data_root, wf_executor
             )
 
         # Apply outputs mapping: {cc_field: "$.capability_result.<ct_field>"} → surface fragment
@@ -177,6 +181,29 @@ def _execute_ct_step(
         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 pgs_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,
@@ -184,6 +211,7 @@ def _execute_cs_step(
     rb_addr: int,
     pkg: RuntimePackage,
     data_root: str,
+    wf_executor=None,
 ) -> tuple[str, dict[str, Any]]:
     """
     Execute a CS (side effect) step.
@@ -202,11 +230,14 @@ def _execute_cs_step(
     # 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, {})
-    # Compiler emits either "policy" or "config" as the key name depending on
-    # the structure; accept both to remain forward/backward compatible.
-    policy_raw = policy_entry.get("policy") or policy_entry.get("config") or {}
+    policy_raw = policy_entry.get("policy") or {}
     policy = _expand_policy(policy_raw, data_root)
 
+    # 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", {})

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pgs_runtime/evidence.py

@@ -15,12 +15,12 @@ Each execution event is a self-contained JSON line with:
     - ts_ns         — monotonic nanosecond timestamp
 
 The trace file is written to:
-    <traces_root>/<domain>/<subdomain>/<trace_id>/<trace_id>.jsonl
+    <traces_root>/<domain>/<wf_code>/<trace_id>/<trace_id>.jsonl
 
 subdomain is not known to this module — caller passes the full trace dir path.
 
-Projection (human-readable reports, visualizations) belongs in tooling/compiler,
-not here. The runtime produces .jsonl only.
+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

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pgs_runtime/loader.py

@@ -44,10 +44,10 @@ class DispatchTable:
     """
     Integer-keyed routing substrate from dispatch.json.
 
-    routing:  {wf_addr: {cc_addr: {condition_addr: next_cc_addr}}}
+    routing:  {wf_addr: {cc_addr: {condition_addr: {"addr": next_cc_addr, "key": node_key}}}}
     pipeline: {cc_addr: [step, ...]}
-    entry:    {wf_addr: {"start": cc_addr, "rb": rb_addr, "in": in_addr}}
-    bindings: {wf_addr: {cc_addr: {input_name: path_or_literal}}}
+    entry:    {wf_addr: {"start": cc_addr, "start_key": node_key, "rb": rb_addr, "in": in_addr}}
+    bindings: {wf_addr: {node_key: {input_name: path_or_literal}}}
 
     Each pipeline step is a named-field execution instruction record:
         {
@@ -59,14 +59,19 @@ class DispatchTable:
             "step_id":   str,        # symbolic step name for $.results.<step_id>.<field> references
         }
 
+    Routing values carry both the next CC address and the target node_key so that
+    the scheduler can disambiguate distinct WF usages of the same shared CC
+    (e.g. four denial audit nodes that all bind to CC_RECORD_DENIED_ACTION_V0).
+
+    Bindings are keyed by node_key (not CC address) for the same reason.
+
     All semantics are compiler-materialized. The dispatcher is a blind executor.
-    All dict keys are ints. All address values are ints.
     The nested dicts are plain Python dicts (not frozen) — callers must not mutate.
     """
-    routing:  dict[int, dict[int, dict[int, int]]]
+    routing:  dict[int, dict[int, dict[int, Any]]]
     pipeline: dict[int, list[dict]]
-    entry:    dict[int, dict[str, int]]
-    bindings: dict[int, dict[int, dict[str, Any]]]
+    entry:    dict[int, dict[str, Any]]
+    bindings: dict[int, dict[str, dict[str, Any]]]
 
 
 @dataclass(frozen=True)
@@ -209,14 +214,16 @@ def _build_dispatch(raw: dict) -> DispatchTable:
     """
     Parse dispatch.json into integer-keyed DispatchTable.
 
-    JSON keys are strings (JSON spec). Addresses are hex-string or int values.
-    All converted to int on load.
+    JSON keys are strings (JSON spec). Addresses are int values.
+    Outer WF and CC keys are converted to int. Routing values are
+    {"addr": int, "key": str} dicts — preserved as-is. Bindings keys
+    are node_key strings — preserved as-is (not int-converted).
     """
-    routing: dict[int, dict[int, dict[int, int]]] = {}
+    routing: dict[int, dict[int, dict[int, Any]]] = {}
     for wf_key, cc_map in raw.get("routing", {}).items():
         wf_addr = int(wf_key)
         routing[wf_addr] = {
-            int(cc_key): {int(cond): int(tgt) for cond, tgt in cond_map.items()}
+            int(cc_key): {int(cond): tgt for cond, tgt in cond_map.items()}
             for cc_key, cond_map in cc_map.items()
         }
 
@@ -225,15 +232,20 @@ def _build_dispatch(raw: dict) -> DispatchTable:
         cc_addr = int(cc_key)
         pipeline[cc_addr] = steps  # list of named-field step dicts
 
-    entry: dict[int, dict[str, int]] = {}
+    entry: dict[int, dict[str, Any]] = {}
     for wf_key, e in raw.get("entry", {}).items():
         wf_addr = int(wf_key)
-        entry[wf_addr] = {k: int(v) for k, v in e.items()}
+        # int-convert only numeric values (start, rb, in); leave start_key as str
+        entry[wf_addr] = {
+            k: (int(v) if isinstance(v, (int, float)) else v)
+            for k, v in e.items()
+        }
 
-    bindings: dict[int, dict[int, dict[str, Any]]] = {}
-    for wf_key, cc_map in raw.get("bindings", {}).items():
+    bindings: dict[int, dict[str, dict[str, Any]]] = {}
+    for wf_key, node_map in raw.get("bindings", {}).items():
         wf_addr = int(wf_key)
-        bindings[wf_addr] = {int(cc_key): inp for cc_key, inp in cc_map.items()}
+        # node_map keys are node_key strings (e.g. "CC_NORMALIZE_AGENT_REQUEST_V0")
+        bindings[wf_addr] = {node_key: inp for node_key, inp in node_map.items()}
 
     return DispatchTable(
         routing  = routing,

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pgs_runtime/scheduler.py

@@ -20,8 +20,8 @@ Topology traversal rules:
 
 Boundary nodes (IN_, EXIT_):
     Nodes without a pipeline entry (not in dispatch.pipeline) are boundary nodes.
-    IN_ nodes perform admission gating; for v0.3.0, prior to admission_snapshot
-    integration, they pass through as ACK. The routing table routes ACK forward.
+    IN_ nodes perform admission gating; prior to admission_snapshot integration,
+    they pass through as ACK. The routing table routes ACK forward.
     EXIT_ nodes (no routing) terminate the loop naturally.
 
 Bindings path grammar (WF-level, compiler-emitted):
@@ -90,6 +90,7 @@ def run_wf(
 
     rb_addr = entry["rb"]
     current_addr: int | None = entry["start"]
+    current_node_key: str = entry.get("start_key", "")
 
     ctx = ExecutionContext(payload)
     writer.wf_start(payload)
@@ -107,11 +108,14 @@ def run_wf(
         hops += 1
 
         if current_addr in pkg.dispatch.pipeline:
-            # CC node — resolve WF-level bindings and execute
+            # CC node — resolve WF-level bindings and execute.
+            # Bindings are keyed by node_key (not CC addr) so that distinct WF
+            # usages of the same CC (e.g. four denial audit nodes) each carry
+            # their own literal inputs (e.g. different denial_reason values).
             wf_bindings = (
                 pkg.dispatch.bindings
                 .get(wf_addr, {})
-                .get(current_addr, {})
+                .get(current_node_key, {})
             )
             cc_inputs = ctx.resolve_inputs(wf_bindings)
 
@@ -122,13 +126,21 @@ def run_wf(
 
         else:
             # Boundary node (IN_, EXIT_) — no pipeline
-            # v0.3.0: admission_snapshot not yet integrated; IN_ nodes pass as ACK
+            # admission_snapshot not yet integrated; IN_ nodes pass as ACK
             result_status = "ACK"
 
-        # Resolve result_status → condition address and route to next node
+        # Resolve result_status → condition address and route to next node.
+        # Routing values are {"addr": int, "key": str} — addr is the next CC address,
+        # key is the next node_key for bindings disambiguation.
         condition_addr = _condition_addr(result_status, pkg)
         routing = pkg.dispatch.routing.get(wf_addr, {}).get(current_addr, {})
-        current_addr = routing.get(condition_addr)  # None → terminal
+        next_entry = routing.get(condition_addr)  # None → terminal
+        if isinstance(next_entry, dict):
+            current_addr = next_entry.get("addr")
+            current_node_key = next_entry.get("key", "")
+        else:
+            current_addr = next_entry  # bare int (legacy) or None
+            current_node_key = ""
 
     writer.wf_complete(result_status)
     return result_status, surface

pgs_runtime-0.5.0/pgs_runtime/trace_viz.py

@@ -0,0 +1,276 @@
+"""
+trace_viz.py — Evidence projection: execution path behavior logic.
+
+Reads a completed trace (.jsonl) and the compiled workflow graph (.graph.json)
+from the protocol snapshot behavior_logic directory, then generates a PNG with
+the actual execution path overlaid in red on the static compiled graph.
+
+This is Evidence Projection — not a runtime execution feature:
+
+    topology (graph.json)
+    +
+    evidence (trace.jsonl)
+    ───────────────────────
+    → execution path PNG
+
+Inputs (both already materialized, read-only):
+    protocol_snapshot/behavior_logic/<WF_CODE>/<WF_CODE>.graph.json
+    traces/<domain>/<wf_code>/<trace_id>/<trace_id>.jsonl
+
+Output:
+    traces/<domain>/<wf_code>/<trace_id>/<trace_id>.png
+
+Architectural invariant:
+    This module reads ONLY from:
+      - protocol_snapshot/behavior_logic/  (compiled graph artifacts)
+      - the caller-supplied trace .jsonl   (execution evidence)
+    It does NOT walk protocol_snapshot/artifacts/ or any other canonical
+    protocol location. Behavior logic overlay is read-only — no protocol interpretation.
+
+Uses graphviz (dot) — returns None silently if dot is not available.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def render_trace_png(
+    workspace: Path,
+    trace_path: Path,
+) -> Optional[Path]:
+    """
+    Generate execution-path overlay PNG for a completed trace.
+
+    Reads CC_COMPLETE events from trace_path to reconstruct the actual
+    execution path, then overlays it (red) on the compiled workflow graph.
+
+    Args:
+        workspace:   Absolute path to pgs_workspace root.
+        trace_path:  Path to the completed .jsonl trace file.
+
+    Returns:
+        Path to the generated PNG, or None if graphviz is unavailable.
+
+    Raises:
+        FileNotFoundError: trace_path or graph.json does not exist.
+        ValueError:        Trace is empty or missing WF_START event.
+    """
+    if not trace_path.exists():
+        raise FileNotFoundError(f"Trace file not found: {trace_path}")
+
+    # Parse trace events
+    events: list[dict] = []
+    for line in trace_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            events.append(json.loads(line))
+
+    if not events:
+        raise ValueError(f"Trace file is empty: {trace_path}")
+
+    # Extract WF code from WF_START event
+    wf_start = next((e for e in events if e["event_type"] == "WF_START"), None)
+    if wf_start is None:
+        raise ValueError(f"No WF_START event found in: {trace_path}")
+
+    wf_fqdn = wf_start["detail"]["wf_fqdn"]
+    wf_code = wf_fqdn.split("::")[-1]  # e.g. "WF_REGISTER_ACTOR_UNVERIFIED_V0"
+
+    # Load compiled graph from protocol_snapshot/behavior_logic/
+    graph_path = (
+        workspace
+        / "protocol_snapshot"
+        / "behavior_logic"
+        / wf_code
+        / f"{wf_code}.graph.json"
+    )
+    if not graph_path.exists():
+        raise FileNotFoundError(
+            f"Compiled graph not found: {graph_path}\n"
+            f"Re-run the compiler to regenerate behavior_logic artifacts."
+        )
+
+    graph = json.loads(graph_path.read_text(encoding="utf-8"))
+
+    # Reconstruct actual execution path from trace events + graph edges
+    path = _extract_execution_path(events, graph)
+
+    # Build visited node and taken edge sets
+    visited_nodes: set[str] = set()
+    taken_edges: set[tuple[str, str, str]] = set()  # (from_node, to_node, condition)
+    for from_node, condition, to_node in path:
+        visited_nodes.add(from_node)
+        visited_nodes.add(to_node)
+        taken_edges.add((from_node, to_node, condition))
+
+    # Generate DOT source with execution-path overlay
+    dot_content = _generate_dot(graph, visited_nodes, taken_edges)
+
+    # Render: write DOT, invoke graphviz, clean up DOT
+    png_path = trace_path.with_suffix(".png")
+    dot_path = trace_path.with_suffix(".dot")
+    dot_path.write_text(dot_content, encoding="utf-8")
+
+    try:
+        subprocess.run(
+            ["dot", "-Tpng", str(dot_path), "-o", str(png_path)],
+            check=True,
+            capture_output=True,
+        )
+        dot_path.unlink()
+        return png_path
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        dot_path.unlink(missing_ok=True)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Path reconstruction
+# ---------------------------------------------------------------------------
+
+def _extract_execution_path(
+    events: list[dict],
+    graph: dict,
+) -> list[tuple[str, str, str]]:
+    """
+    Reconstruct [(from_node, condition, to_node), ...] from trace events.
+
+    Uses CC_COMPLETE events (in emission order) and graph edges to walk
+    the actual execution path. IN_ boundary nodes always yield ACK in
+    the current runtime (admission_snapshot not yet integrated).
+
+    Args:
+        events: Parsed JSONL trace events.
+        graph:  Compiled graph dict (from graph.json).
+
+    Returns:
+        Ordered list of (from_node_id, condition, to_node_id) tuples.
+    """
+    entry_node: str = graph["entry"]  # e.g. "IN_ACTOR_REGISTERED_V0"
+
+    # (from_node, condition) → to_node
+    edge_map: dict[tuple[str, str], str] = {
+        (e["from"], e["condition"]): e["to"]
+        for e in graph["edges"]
+    }
+
+    # Filter to top-level workflow CC events only.
+    # Sub-workflows emit CC_COMPLETE events with the same wf_addr as the
+    # top-level workflow (the runtime reuses the same address), so wf_addr
+    # filtering is insufficient. Instead, restrict to CCs that are declared
+    # nodes in the top-level graph — sub-workflow CCs won't appear there.
+    graph_cc_nodes: set[str] = {
+        n["id"] for n in graph["nodes"] if n["type"] == "CC"
+    }
+    cc_completions = [
+        e for e in events
+        if e["event_type"] == "CC_COMPLETE"
+        and e["detail"]["cc_fqdn"].split("::")[-1] in graph_cc_nodes
+    ]
+
+    if not cc_completions:
+        # No CC nodes executed — IN_ gated as NACK and routed to EXIT
+        to_node = edge_map.get((entry_node, "NACK"), "EXIT")
+        return [(entry_node, "NACK", to_node)]
+
+    path: list[tuple[str, str, str]] = []
+
+    # IN_ → first CC: always ACK (admission passes through in current runtime)
+    first_cc_code = cc_completions[0]["detail"]["cc_fqdn"].split("::")[-1]
+    path.append((entry_node, "ACK", first_cc_code))
+
+    # CC → CC (or EXIT) — follow result_status routing
+    for cc_event in cc_completions:
+        cc_code = cc_event["detail"]["cc_fqdn"].split("::")[-1]
+        result_status = cc_event["result_status"]
+        to_node = edge_map.get((cc_code, result_status))
+        if to_node is None:
+            break  # no further routing — terminal
+        path.append((cc_code, result_status, to_node))
+
+    return path
+
+
+# ---------------------------------------------------------------------------
+# DOT generation
+# ---------------------------------------------------------------------------
+
+def _generate_dot(
+    graph: dict,
+    visited_nodes: set[str],
+    taken_edges: set[tuple[str, str, str]],
+) -> str:
+    """
+    Generate Graphviz DOT with actual execution path highlighted in red.
+
+    Visited nodes:  red border + solid red fill.
+    Taken edges:    red, bold, red label.
+    Unvisited:      standard fill, grey border, grey edges.
+    """
+    lines = [
+        f'digraph "{graph["wf_id"]}" {{',
+        "  rankdir=LR;",
+        '  node [fontname="Arial"];',
+        "",
+    ]
+
+    # --- Nodes ---
+    for node in graph["nodes"]:
+        node_id = node["id"]
+        node_type = node["type"]
+        visited = node_id in visited_nodes
+
+        if node_type == "IN":
+            fill = "tomato" if visited else "lightblue"
+            shape = "ellipse"
+        elif node_type == "CC":
+            fill = "tomato" if visited else "lightgreen"
+            shape = "box"
+        elif node_type == "EXIT":
+            fill = "tomato" if visited else "lightcoral"
+            shape = "ellipse"
+        else:
+            fill = "white"
+            shape = "box"
+
+        if visited:
+            lines.append(
+                f'  "{node_id}" [label="{node_id}", shape={shape},'
+                f" style=filled, fillcolor={fill}, color=red, penwidth=2.5];"
+            )
+        else:
+            lines.append(
+                f'  "{node_id}" [label="{node_id}", shape={shape},'
+                f" style=filled, fillcolor={fill}, color=gray];"
+            )
+
+    lines.append("")
+
+    # --- Edges ---
+    for edge in graph["edges"]:
+        from_id = edge["from"]
+        to_id = edge["to"]
+        condition = edge["condition"]
+        taken = (from_id, to_id, condition) in taken_edges
+
+        if taken:
+            lines.append(
+                f'  "{from_id}" -> "{to_id}"'
+                f' [label="{condition}", color=red, penwidth=2.5, fontcolor=red];'
+            )
+        else:
+            lines.append(
+                f'  "{from_id}" -> "{to_id}"'
+                f' [label="{condition}", color=gray, fontcolor=gray];'
+            )
+
+    lines.append("}")
+    return "\n".join(lines)

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0/pgs_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgs_runtime
-Version: 0.3.1
+Version: 0.5.0
 Summary: PGS runtime for Protocol-Governed Systems
 Author: Bachi
 License-Expression: Apache-2.0
@@ -29,7 +29,7 @@ It does not discover behavior. It does not interpret intent. It does not contain
 
 Behavior is declared in protocol, executed by runtime, implemented in capabilities, and observed via traces and state.
 
-> **New to PGS?** This is one of eight repositories in the Protocol-Governed Systems ecosystem.
+> **New to PGS?** This is one of the repositories in the Protocol-Governed Systems ecosystem.
 > For orientation, architecture overview, and end-to-end execution, start at [pgs_workspace](https://github.com/bachipeachy/pgs_workspace).
 
 ---

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pgs_runtime.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ pgs_runtime/loader.py
 pgs_runtime/memory.py
 pgs_runtime/scheduler.py
 pgs_runtime/server.py
+pgs_runtime/trace_viz.py
 pgs_runtime.egg-info/PKG-INFO
 pgs_runtime.egg-info/SOURCES.txt
 pgs_runtime.egg-info/dependency_links.txt

{pgs_runtime-0.3.1 → pgs_runtime-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pgs_runtime"
-version = "0.3.1"
+version = "0.5.0"
 description = "PGS runtime for Protocol-Governed Systems"
 readme = "README.md"
 requires-python = ">=3.10"