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

{pgs_runtime-0.3.0 → pgs_runtime-0.4.0}/MANIFEST.in

@@ -4,6 +4,5 @@ exclude *.sh
 
 prune scripts
 prune testbed
-prune pgs_*
 
 global-exclude __pycache__ *.pyc

{pgs_runtime-0.3.0 → pgs_runtime-0.4.0}/PKG-INFO

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

pgs_runtime-0.4.0/pgs_runtime/cli.py

@@ -0,0 +1,310 @@
+"""
+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.
+
+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>/<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.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+from pgs_runtime.evidence import TraceWriter, make_trace_id
+from pgs_runtime.loader import load_domain
+from pgs_runtime.scheduler import run_wf
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pgs_runtime",
+        description="PGS token-native workflow runtime",
+    )
+    subs = parser.add_subparsers(dest="command", required=True)
+
+    # ── run ──────────────────────────────────────────────────────
+    run_p = subs.add_parser("run", help="Execute a workflow")
+
+    run_p.add_argument(
+        "--wf",
+        required=True,
+        metavar="FQDN",
+        help="Workflow FQDN (e.g. blockchain::WF_REGISTER_ACTOR_UNVERIFIED_V0)",
+    )
+    run_p.add_argument(
+        "--payload",
+        metavar="FILE",
+        help="Path to JSON payload file (omit for empty payload)",
+    )
+    run_p.add_argument(
+        "--data-root",
+        dest="data_root",
+        metavar="PATH",
+        help="Absolute path for CS domain data root (or set PGS_DATA_ROOT)",
+    )
+    run_p.add_argument(
+        "--workspace",
+        metavar="PATH",
+        help="Absolute path to pgs_workspace root (or set PGS_WORKSPACE); "
+             "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(
+        "trace_file",
+        metavar="FILE",
+        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
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+def _handle_run(args: argparse.Namespace) -> None:
+    wf_fqdn = args.wf
+
+    # Extract domain from FQDN (part before ::)
+    if "::" not in wf_fqdn:
+        _fatal(f"Invalid WF FQDN (expected <domain>::<CODE>): {wf_fqdn!r}")
+    domain = wf_fqdn.split("::")[0]
+
+    # Resolve paths from args or environment
+    data_root_str = args.data_root or os.environ.get("PGS_DATA_ROOT")
+    if not data_root_str:
+        _fatal("--data-root PATH or PGS_DATA_ROOT is required")
+    data_root = Path(data_root_str)
+    if not data_root.is_absolute():
+        _fatal(f"--data-root must be an absolute path, got: {data_root_str}")
+
+    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}")
+
+    # Load payload
+    payload = _load_payload(args.payload)
+
+    # Load tokenized snapshot (verifies hash; raises on mismatch or missing files)
+    print(f"[pgs_runtime] Loading {domain} snapshot...")
+    try:
+        pkg = load_domain(workspace, domain)
+    except (FileNotFoundError, RuntimeError, ValueError) as exc:
+        _fatal(str(exc))
+
+    # Generate trace ID and resolve trace directory
+    # Structure: traces/<domain>/<WF_CODE>/<trace_id>/
+    trace_id = make_trace_id(domain, wf_fqdn, payload)
+    wf_code = wf_fqdn.split("::")[-1]  # e.g. "WF_CREATE_WALLET_V0"
+    trace_dir = workspace / "traces" / domain / wf_code / trace_id
+    trace_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"[pgs_runtime] Workflow:  {wf_fqdn}")
+    print(f"[pgs_runtime] Trace ID:  {trace_id}")
+    print(f"[pgs_runtime] Trace dir: {trace_dir}")
+    print()
+
+    # Resolve WF address for TraceWriter
+    try:
+        wf_addr = pkg.vocab.addr(wf_fqdn)
+    except KeyError:
+        _fatal(f"WF FQDN not in vocab: {wf_fqdn!r}")
+
+    writer = TraceWriter(
+        trace_dir = trace_dir,
+        trace_id  = trace_id,
+        domain    = domain,
+        wf_addr   = wf_addr,
+        wf_fqdn   = wf_fqdn,
+    )
+
+    t0 = time.monotonic()
+    try:
+        result_status, surface = run_wf(
+            wf_fqdn   = wf_fqdn,
+            payload   = payload,
+            pkg       = pkg,
+            writer    = writer,
+            data_root = str(data_root),
+        )
+    except Exception as exc:
+        writer.error(str(exc))
+        writer.close()
+        _fatal(f"Runtime error: {exc}")
+    finally:
+        writer.close()
+
+    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)
+    print(f"Workflow:   {wf_fqdn}")
+    print(f"Status:     {result_status}")
+    print(f"Trace ID:   {trace_id}")
+    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():
+        _fatal(f"Trace file not found: {args.trace_file}")
+
+    # Delegate to the examine module (reads JSONL trace format)
+    try:
+        from pgs_runtime.examine import analyze, TraceParseError
+    except ImportError:
+        _fatal(
+            "Trace examiner unavailable — pgs_runtime may not be fully installed.\n"
+            "  Re-install with: pip install -e /path/to/pgs_runtime"
+        )
+
+    try:
+        report = analyze(trace_path)
+    except Exception as exc:
+        _fatal(f"Trace parse error: {exc}")
+
+    print(report.format())
+
+    if report.has_structural_failure:
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# 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 {}
+    path = Path(payload_path)
+    if not path.exists():
+        _fatal(f"Payload file not found: {payload_path}")
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        _fatal(f"Payload file is not valid JSON: {exc}")
+
+
+def _fatal(message: str) -> None:
+    print(f"[pgs_runtime] Error: {message}", file=sys.stderr)
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.command == "run":
+        _handle_run(args)
+    elif args.command == "examine":
+        _handle_examine(args)
+    elif args.command == "visualize":
+        _handle_visualize(args)
+
+
+if __name__ == "__main__":
+    main()

pgs_runtime-0.4.0/pgs_runtime/conformance.py

@@ -0,0 +1,232 @@
+"""
+conformance.py — CT Conformance Runner
+
+Loads compiled CT_CONFORMANCE artifacts from protocol_snapshot/conformance/
+and executes each via CTExecutor, asserting expected outputs against actual outputs.
+
+Called by pgs build — not by pgs_runtime run.
+Does NOT write snapshot_status.json; that is the caller's responsibility.
+"""
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pgs_runtime.ct_executor import CTExecutor, CTExecutionError
+
+
+@dataclass
+class CaseResult:
+    fqdn: str
+    passed: bool
+    error: str | None = None
+
+
+@dataclass
+class ConformanceResult:
+    passed: int = 0
+    failed: int = 0
+    artifact_count: int = 0
+    snapshot_hash: str = ""
+    cases: list[CaseResult] = field(default_factory=list)
+
+    @property
+    def all_passed(self) -> bool:
+        return self.failed == 0 and self.artifact_count > 0
+
+
+_ALLOWED_MODES: frozenset[str] = frozenset({"exact", "property", "schema"})
+_ALLOWED_TYPES: dict[str, frozenset[str]] = {
+    "property": frozenset({"hex_string", "byte_length_range", "non_zero"}),
+    "schema": frozenset({"json_schema"}),
+}
+
+
+def _assert_structural(actual: dict[str, Any], assertions: dict[str, Any]) -> str | None:
+    """
+    Validate structural assertions for non-deterministic fields.
+
+    Assertion spec shape (INVARIANT_CONFORMANCE_ASSERTION_MODE_VALID_V0):
+        {field_name: {mode: <mode>, type: <type>, ...params}}
+
+    Mode vocabulary: { exact, property, schema }
+    Type vocabulary per mode:
+        property → { hex_string, byte_length_range, non_zero }
+        schema   → { json_schema }
+
+    Returns an error message string if any assertion fails, else None.
+    Raises AssertionError for unknown modes or types (hard failure — never silent).
+    """
+    for field_name, spec in assertions.items():
+        if field_name not in actual:
+            return f"assertion field '{field_name}' missing from actual output"
+        value = actual[field_name]
+
+        mode = spec.get("mode")
+        if mode is None:
+            raise AssertionError(
+                f"Assertion spec for '{field_name}' missing required 'mode' field. "
+                f"Allowed: {sorted(_ALLOWED_MODES)}. "
+                f"This indicates invalid TEST_DATA that should have been caught at compile time."
+            )
+        if mode not in _ALLOWED_MODES:
+            raise AssertionError(
+                f"Assertion for '{field_name}' has unknown mode '{mode}'. "
+                f"Allowed: {sorted(_ALLOWED_MODES)}. "
+                f"This indicates invalid TEST_DATA that should have been caught at compile time."
+            )
+
+        if mode == "exact":
+            # exact mode: field is checked via expected dict, not assertions block
+            continue
+
+        assert_type = spec.get("type")
+        allowed_types = _ALLOWED_TYPES.get(mode, frozenset())
+        if assert_type is None:
+            raise AssertionError(
+                f"Assertion for '{field_name}' with mode '{mode}' missing required 'type' field. "
+                f"Allowed types: {sorted(allowed_types)}."
+            )
+        if assert_type not in allowed_types:
+            raise AssertionError(
+                f"Assertion for '{field_name}' has unknown type '{assert_type}' for mode '{mode}'. "
+                f"Allowed: {sorted(allowed_types)}. "
+                f"This indicates invalid TEST_DATA that should have been caught at compile time."
+            )
+
+        if mode == "property":
+            if assert_type == "hex_string":
+                if not isinstance(value, str):
+                    return f"field '{field_name}': expected hex string, got {type(value).__name__}"
+                hex_val = value[2:] if value.startswith("0x") else value
+                try:
+                    raw = bytes.fromhex(hex_val)
+                except ValueError:
+                    return f"field '{field_name}': not a valid hex string: {value!r}"
+                byte_length = spec.get("byte_length")
+                if byte_length is not None and len(raw) != byte_length:
+                    return (
+                        f"field '{field_name}': expected {byte_length} bytes, "
+                        f"got {len(raw)} bytes (value: {value!r})"
+                    )
+
+            elif assert_type == "byte_length_range":
+                min_len = spec["min"]
+                max_len = spec["max"]
+                hex_val = value[2:] if isinstance(value, str) and value.startswith("0x") else value
+                try:
+                    raw = bytes.fromhex(hex_val) if isinstance(value, str) else value
+                except (ValueError, AttributeError):
+                    return f"field '{field_name}': cannot determine byte length: {value!r}"
+                if not (min_len <= len(raw) <= max_len):
+                    return (
+                        f"field '{field_name}': expected {min_len}–{max_len} bytes, "
+                        f"got {len(raw)} bytes"
+                    )
+
+            elif assert_type == "non_zero":
+                if value == 0 or value == "0x0" or value == b"\x00" or value == "" or value is None:
+                    return f"field '{field_name}': expected non-zero value, got {value!r}"
+
+        elif mode == "schema":
+            raise AssertionError(
+                f"Assertion for '{field_name}': schema/json_schema validation is not supported in the conformance runner."
+            )
+
+    return None
+
+
+def _resolve_outputs(ct_ir: dict[str, Any], vars_result: dict[str, Any]) -> dict[str, Any]:
+    """
+    Resolve ct_ir output mapping from executor result vars.
+
+    ct_ir.outputs maps output key → {"from": "<var_name>"}
+    Each output key is looked up inside the named var dict.
+    """
+    outputs_spec = ct_ir.get("outputs", {})
+    if not outputs_spec:
+        return vars_result
+
+    actual: dict[str, Any] = {}
+    for output_key, output_spec in outputs_spec.items():
+        from_var = output_spec.get("from")
+        if not from_var or from_var not in vars_result:
+            continue
+        source = vars_result[from_var]
+        if isinstance(source, dict) and output_key in source:
+            actual[output_key] = source[output_key]
+        else:
+            actual[output_key] = source
+    return actual
+
+
+def _snapshot_hash(conformance_dir: Path) -> str:
+    """Stable SHA-256 over sorted conformance artifact names + contents."""
+    h = hashlib.sha256()
+    for path in sorted(conformance_dir.glob("*.json")):
+        h.update(path.name.encode())
+        h.update(path.read_bytes())
+    return h.hexdigest()[:16]
+
+
+def run(snapshot_root: Path) -> ConformanceResult:
+    """
+    Execute all CT conformance tests in snapshot_root/conformance/.
+
+    Returns ConformanceResult with per-case pass/fail detail.
+    Raises FileNotFoundError if conformance dir is missing.
+    """
+    conformance_dir = snapshot_root / "conformance"
+    if not conformance_dir.exists():
+        raise FileNotFoundError(f"Conformance directory not found: {conformance_dir}")
+
+    case_files = sorted(conformance_dir.glob("*.json"))
+    result = ConformanceResult(
+        artifact_count=len(case_files),
+        snapshot_hash=_snapshot_hash(conformance_dir),
+    )
+
+    executor = CTExecutor()
+
+    for case_file in case_files:
+        artifact = json.loads(case_file.read_text())
+        fqdn = artifact.get("fqdn", case_file.stem)
+        ct_ir = artifact.get("ct_ir", {})
+        inputs = ct_ir.get("inputs", {})
+        expected = artifact.get("expected", {})
+        assertions = artifact.get("assertions", {})
+
+        try:
+            vars_result = executor.execute(ct_ir=ct_ir, inputs=inputs)
+            actual = _resolve_outputs(ct_ir, vars_result)
+
+            # 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
+
+            # Exact match on fields NOT covered by assertions
+            asserted_keys = set(assertions.keys())
+            expected_exact = {k: v for k, v in expected.items() if k not in asserted_keys}
+            actual_exact = {k: v for k, v in actual.items() if k not in asserted_keys}
+
+            if assertion_error:
+                result.failed += 1
+                result.cases.append(CaseResult(fqdn=fqdn, passed=False, error=f"assertion failed: {assertion_error}"))
+            elif actual_exact != expected_exact:
+                result.failed += 1
+                result.cases.append(CaseResult(
+                    fqdn=fqdn,
+                    passed=False,
+                    error=f"output mismatch\n    expected: {json.dumps(expected_exact)}\n    actual:   {json.dumps(actual_exact)}",
+                ))
+            else:
+                result.passed += 1
+                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)))
+
+    return result

pgs_runtime-0.4.0/pgs_runtime/ct_errors.py

@@ -0,0 +1,33 @@
+"""
+errors.py — Structured error types for CT execution.
+
+All CT execution exceptions that carry structured error metadata
+MUST subclass StructuredError. This enables the workflow runner
+to emit deterministic, schema-compliant error trace events.
+
+Never raise StructuredError without error_code.
+"""
+
+
+class StructuredError(RuntimeError):
+    """
+    Base exception carrying structured error metadata.
+
+    Fields:
+        error_code: One of the codes defined in STRUCTURE_TRACE_SCHEMA_V0 §10.2
+        node_category: One of WF, IN, CC, CT, CS per §10.3
+        message: Human-readable description
+        cause: Original exception if wrapping an unstructured error
+    """
+
+    def __init__(
+        self,
+        error_code: str,
+        node_category: str,
+        message: str,
+        cause: Exception | None = None,
+    ):
+        super().__init__(message)
+        self.error_code = error_code
+        self.node_category = node_category
+        self.cause = cause

pgs_runtime-0.4.0/pgs_runtime/ct_execute.py

@@ -0,0 +1,84 @@
+"""
+execute.py — CT-IR execution entry point.
+
+Adapter between the dispatcher and CTExecutor.
+"""
+
+from typing import Any
+
+from pgs_runtime.ct_errors import StructuredError
+from pgs_runtime.ct_executor import CTExecutor
+
+# Module-level executor singleton — avoids re-creating per call,
+# preserves federated IR directory cache and atom loading.
+# Lazy initialization to avoid import-time side effects (bootstrap requirement)
+_executor: CTExecutor | None = None
+
+
+def _get_executor() -> CTExecutor:
+    """Get or create the CT executor singleton (lazy initialization)."""
+    global _executor
+    if _executor is None:
+        _executor = CTExecutor()
+    return _executor
+
+
+def execute_ct(ct_ir: dict[str, Any], inputs: dict[str, Any]) -> Any:
+    """
+    Execute CT-IR and adapt result to CC expectation.
+
+    CONTRACT (STRICT):
+    - CT-IR MUST be pre-validated by compiler before reaching execution
+    - CTExecutor blindly executes pre-validated CT-IR
+    - CT-IR declares exactly one output
+    - That output is returned directly (unwrapped)
+
+    SOVEREIGNTY: Execution layer is a blind executor.
+    Validation is compiler's responsibility.
+    """
+
+    # ---- Execution (CT-IR assumed pre-validated by compiler) ----
+    symbol_table = _get_executor().execute(
+        ct_ir=ct_ir,
+        inputs=inputs,
+    )
+
+    # ---- Output adaptation ----
+    outputs = ct_ir.get("outputs")
+    if not outputs:
+        raise StructuredError(
+            error_code="CT_EXECUTION_FAILED",
+            node_category="CT",
+            message="CT must declare at least one output",
+        )
+
+    # Build CT outputs by mapping from symbol table
+    ct_outputs = {}
+    for output_name, spec in outputs.items():
+        from_symbol = spec["from"]
+
+        if from_symbol not in symbol_table:
+            raise StructuredError(
+                error_code="CT_EXECUTION_FAILED",
+                node_category="CT",
+                message=f"CT output symbol '{from_symbol}' was not produced by CT execution",
+            )
+
+        symbol_value = symbol_table[from_symbol]
+
+        # Extract output field from atom result dict
+        # Atoms return a single dict containing all output fields
+        # e.g., {"valid": True, "failed_rule": None}
+        if isinstance(symbol_value, dict):
+            if output_name in symbol_value:
+                # Multi-output atom: extract this specific output field
+                symbol_value = symbol_value[output_name]
+            elif len(symbol_value) == 1:
+                # Single-output atom: unwrap the single field
+                symbol_value = next(iter(symbol_value.values()))
+
+        ct_outputs[output_name] = symbol_value
+
+    # Return contract-shaped outputs (always as dict, never unwrap)
+    # Contract declares output shape - return exactly that shape
+    return ct_outputs