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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgs_runtime
-Version: 0.4.0
+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.4.0 → 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.4.0 → pgs_runtime-0.5.0}/pgs_runtime/cli.py

@@ -2,9 +2,9 @@
 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.
-    visualize — Render execution-path PNG from a completed trace file.
+    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()
@@ -13,7 +13,7 @@ Execution path (run):
     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
+    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.
@@ -71,10 +71,11 @@ def _build_parser() -> argparse.ArgumentParser:
              "tokenized_snapshot/ and traces/ live here",
     )
 
-    # ── run: optional visualization flag ─────────────────────────
+    # ── run: optional behavior-logic flag ────────────────────────
     run_p.add_argument(
-        "--visualize",
+        "--behavior-logic",
         action="store_true",
+        dest="behavior_logic",
         help="Render execution-path PNG after run (requires graphviz)",
     )
 
@@ -86,17 +87,17 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Path to a completed .jsonl trace file",
     )
 
-    # ── visualize ─────────────────────────────────────────────────
-    viz_p = subs.add_parser(
-        "visualize",
+    # ── behavior-logic ────────────────────────────────────────────
+    bl_p = subs.add_parser(
+        "behavior-logic",
         help="Render execution-path PNG from a completed trace file",
     )
-    viz_p.add_argument(
+    bl_p.add_argument(
         "trace_file",
         metavar="FILE",
         help="Path to a completed .jsonl trace file",
     )
-    viz_p.add_argument(
+    bl_p.add_argument(
         "--workspace",
         metavar="PATH",
         help="Absolute path to pgs_workspace root (or set PGS_WORKSPACE)",
@@ -189,8 +190,8 @@ def _handle_run(args: argparse.Namespace) -> None:
     # 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)
+    if args.behavior_logic:
+        png_path = _render_behavior_logic(workspace, trace_path)
 
     print("=" * 60)
     print("[pgs_runtime] Workflow Complete")
@@ -202,16 +203,16 @@ def _handle_run(args: argparse.Namespace) -> None:
     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(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_visualize(args: argparse.Namespace) -> None:
+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}")
@@ -223,12 +224,12 @@ def _handle_visualize(args: argparse.Namespace) -> None:
     if not workspace.is_absolute():
         _fatal(f"--workspace must be an absolute path, got: {workspace_str}")
 
-    png_path = _render_visualization(workspace, trace_path)
+    png_path = _render_behavior_logic(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.",
+            "[pgs_runtime] Behavior logic render skipped — graphviz (dot) not available.",
             file=sys.stderr,
         )
         sys.exit(1)
@@ -263,13 +264,13 @@ def _handle_examine(args: argparse.Namespace) -> None:
 # Utilities
 # ---------------------------------------------------------------------------
 
-def _render_visualization(workspace: Path, trace_path: Path) -> "Path | None":
+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] Visualization error: {exc}", file=sys.stderr)
+        print(f"[pgs_runtime] Behavior logic render error: {exc}", file=sys.stderr)
         return None
 
 
@@ -302,8 +303,8 @@ def main() -> None:
         _handle_run(args)
     elif args.command == "examine":
         _handle_examine(args)
-    elif args.command == "visualize":
-        _handle_visualize(args)
+    elif args.command == "behavior-logic":
+        _handle_behavior_logic(args)
 
 
 if __name__ == "__main__":

{pgs_runtime-0.4.0 → 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.4.0 → 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.
@@ -205,6 +233,11 @@ def _execute_cs_step(
     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.4.0 → 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.4.0 → pgs_runtime-0.5.0}/pgs_runtime/scheduler.py

@@ -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)
 
@@ -125,10 +129,18 @@ def run_wf(
             # 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.4.0 → pgs_runtime-0.5.0}/pgs_runtime/trace_viz.py

@@ -1,8 +1,8 @@
 """
-trace_viz.py — Evidence projection: execution path visualization.
+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 visualization directory, then generates a PNG with
+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:
@@ -14,7 +14,7 @@ This is Evidence Projection — not a runtime execution feature:
     → execution path PNG
 
 Inputs (both already materialized, read-only):
-    protocol_snapshot/visualization/<WF_CODE>/<WF_CODE>.graph.json
+    protocol_snapshot/behavior_logic/<WF_CODE>/<WF_CODE>.graph.json
     traces/<domain>/<wf_code>/<trace_id>/<trace_id>.jsonl
 
 Output:
@@ -22,10 +22,10 @@ Output:
 
 Architectural invariant:
     This module reads ONLY from:
-      - protocol_snapshot/visualization/  (compiled graph artifacts)
+      - 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. Visualization is overlay-only — no protocol interpretation.
+    protocol location. Behavior logic overlay is read-only — no protocol interpretation.
 
 Uses graphviz (dot) — returns None silently if dot is not available.
 """
@@ -84,18 +84,18 @@ def render_trace_png(
     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/
+    # Load compiled graph from protocol_snapshot/behavior_logic/
     graph_path = (
         workspace
         / "protocol_snapshot"
-        / "visualization"
+        / "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 visualization artifacts."
+            f"Re-run the compiler to regenerate behavior_logic artifacts."
         )
 
     graph = json.loads(graph_path.read_text(encoding="utf-8"))
@@ -162,7 +162,19 @@ def _extract_execution_path(
         for e in graph["edges"]
     }
 
-    cc_completions = [e for e in events if e["event_type"] == "CC_COMPLETE"]
+    # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgs_runtime
-Version: 0.4.0
+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.4.0 → pgs_runtime-0.5.0}/pyproject.toml

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