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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgs_runtime
-Version: 0.3.1
+Version: 0.4.0
 Summary: PGS runtime for Protocol-Governed Systems
 Author: Bachi
 License-Expression: Apache-2.0

{pgs_runtime-0.3.1 → pgs_runtime-0.4.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.
+    visualize — 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 --visualize: 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,13 @@ def _build_parser() -> argparse.ArgumentParser:
              "tokenized_snapshot/ and traces/ live here",
     )
 
+    # ── run: optional visualization flag ─────────────────────────
+    run_p.add_argument(
+        "--visualize",
+        action="store_true",
+        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 +86,22 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Path to a completed .jsonl trace file",
     )
 
+    # ── visualize ─────────────────────────────────────────────────
+    viz_p = subs.add_parser(
+        "visualize",
+        help="Render execution-path PNG from a completed trace file",
+    )
+    viz_p.add_argument(
+        "trace_file",
+        metavar="FILE",
+        help="Path to a completed .jsonl trace file",
+    )
+    viz_p.add_argument(
+        "--workspace",
+        metavar="PATH",
+        help="Absolute path to pgs_workspace root (or set PGS_WORKSPACE)",
+    )
+
     return parser
 
 
@@ -161,6 +186,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.visualize:
+        png_path = _render_visualization(workspace, trace_path)
+
     print("=" * 60)
     print("[pgs_runtime] Workflow Complete")
     print("=" * 60)
@@ -170,12 +201,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"Visual:     {png_path}")
+    elif args.visualize:
+        print("Visual:     (graphviz not available — PNG skipped)")
     print("=" * 60)
 
     if result_status not in ("SUCCESS", "ALREADY_EXISTS"):
         sys.exit(1)
 
 
+def _handle_visualize(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_visualization(workspace, trace_path)
+    if png_path:
+        print(f"[pgs_runtime] Execution path PNG: {png_path}")
+    else:
+        print(
+            "[pgs_runtime] Visualization 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 +263,16 @@ def _handle_examine(args: argparse.Namespace) -> None:
 # Utilities
 # ---------------------------------------------------------------------------
 
+def _render_visualization(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] Visualization error: {exc}", file=sys.stderr)
+        return None
+
+
 def _load_payload(payload_path: str | None) -> dict:
     if not payload_path:
         return {}
@@ -234,6 +302,8 @@ def main() -> None:
         _handle_run(args)
     elif args.command == "examine":
         _handle_examine(args)
+    elif args.command == "visualize":
+        _handle_visualize(args)
 
 
 if __name__ == "__main__":

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

@@ -202,9 +202,7 @@ 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)
 
     # Instantiate CS runtime

{pgs_runtime-0.3.1 → pgs_runtime-0.4.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.4.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):
@@ -122,7 +122,7 @@ 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

pgs_runtime-0.4.0/pgs_runtime/trace_viz.py

@@ -0,0 +1,264 @@
+"""
+trace_viz.py — Evidence projection: execution path visualization.
+
+Reads a completed trace (.jsonl) and the compiled workflow graph (.graph.json)
+from the protocol snapshot visualization 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/visualization/<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/visualization/  (compiled graph artifacts)
+      - the caller-supplied trace .jsonl   (execution evidence)
+    It does NOT walk protocol_snapshot/artifacts/ or any other canonical
+    protocol location. Visualization is overlay-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/visualization/
+    graph_path = (
+        workspace
+        / "protocol_snapshot"
+        / "visualization"
+        / 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 visualization 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"]
+    }
+
+    cc_completions = [e for e in events if e["event_type"] == "CC_COMPLETE"]
+
+    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.4.0/pgs_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgs_runtime
-Version: 0.3.1
+Version: 0.4.0
 Summary: PGS runtime for Protocol-Governed Systems
 Author: Bachi
 License-Expression: Apache-2.0

{pgs_runtime-0.3.1 → pgs_runtime-0.4.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.4.0}/pyproject.toml

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