pgc-runtime 2.0.0__py3-none-any.whl

pgc_runtime-2.0.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: pgc-runtime
+Version: 2.0.0
+Summary: PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)
+Author-email: Bhash Ganti <bachipeachy@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://omnibachi.org/
+Project-URL: Repository, https://github.com/protocol-governed-computing/protocol_runtime
+Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
+Keywords: protocol-governed-computing,pgc,protocol,runtime,workflow,execution
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: reference
+Requires-Dist: pgc-governance>=2.0.0; extra == "reference"
+Dynamic: license-file
+
+# protocol_runtime
+
+**Deterministic execution engine for Protocol-Governed Computing** (import package: `runtime`).
+
+The runtime traverses a precompiled execution graph and produces traceable, governed outcomes. It
+does not discover behavior, interpret intent, or contain business logic. Everything it will do was
+decided at compile time; execution is a traversal of what the snapshot already says.
+
+## Install
+
+```bash
+pip install pgc-runtime
+```
+
+Once installed:
+
+```bash
+protocol_runtime --help
+```
+
+## Where it fits
+
+```
+software_governance    the normative surface every composition rests on
+conformance_workloads  workloads that prove conformance
+business_domains       domains built on the surface
+
+protocol_compiler      source      → compiled projections
+snapshot_assembler     projections → assembled snapshot
+protocol_runtime       snapshot    → execution            (this repo)
+snapshot_inspector     snapshot    → inspection
+```
+
+`protocol_transport` governs the boundary at either end of execution — ingress and egress as
+first-class contracts. The runtime consumes only the **assembled** snapshot, never an individual
+repo's compiled layout.
+
+## What it is, and is not
+
+**It is** a deterministic graph traverser, a trace generator, and a host for the capability
+implementations a snapshot names.
+
+**It is not** a workflow authoring system, a rules engine, a business-logic container, or a
+framework with pluggable behavior. There is no extension point, because an extension point is a
+place where ungoverned behavior could enter.
+
+## Inputs and outputs
+
+```
+snapshot root   the assembled snapshot — the sole source of behavior
+payload         external input (JSON)
+data-root       the state storage boundary; one data root is one instance
+```
+
+A run writes an append-only trace alongside the state its declared side effects produce:
+
+```
+traces/<TRACE_ID>/
+    <TRACE_ID>.jsonl    append-only execution log
+    <TRACE_ID>.md       human-readable summary
+    <TRACE_ID>.png      the execution path, rendered
+
+data/
+    registry/           idempotent state
+    events/             append-only history
+```
+
+## Running
+
+```bash
+./run.sh                                       # warm-boot the sibling assembled snapshot
+./run.sh boot --snapshot /abs/snapshot         # explicit boot
+./run.sh run --wf <domain>::WF_… --data-root /abs/instance
+./run.sh examine /abs/trace.jsonl
+```
+
+`run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
+subcommands:
+
+| command | what it does |
+|---|---|
+| `run` | execute a workflow against a data root |
+| `boot` | warm-boot the assembled snapshot — load and hash-verify every manifest domain |
+| `examine` | analyze a completed trace file |
+| `behavior-logic` | render the execution path from a completed trace as a PNG |
+
+`PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
+roots on `PYTHONPATH` for domain capability implementations.
+
+**Warm reboot is its own proof.** Bringing every manifest domain resident and hash-verified
+establishes that the snapshot is intact and executable before any workflow runs. A surface-only
+snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
+
+**A data root is an instance, not an interface.** Two data roots against the same snapshot are two
+independent instances of the same governed behavior.
+
+## How execution works
+
+The runtime loads the compiled graph, admits the request against the intent that declares it, and
+walks the workflow node by node. At each node it executes the capability contract's steps —
+invoking transforms, applying side effects — and routes on the declared outcome. It resolves
+nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
+on those.
+
+Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
+the path actually taken through a graph that was fixed before the run began, which is what makes a
+run reproducible and reviewable after the fact.
+
+## License
+
+Apache-2.0. See `LICENSE` and `NOTICE`.
+
+---
+
+## The package family
+
+| Package | Repository | Role |
+|---|---|---|
+| `pgc-compiler` | `protocol_compiler` | declarations → compiled projections |
+| `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
+| `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
+| `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
+| `pgc-transformation` | `transformation` | change request → protocol artifacts |
+| `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
+| `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
+| `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
+
+`pip install pgc` brings in the whole family.
+
+**Installing the toolchain is one of two steps.** The compiler resolves the governance surface from
+`PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, zero inference — so the *declarations* come from a
+repository you point at, never from a wheel. A registry inside a package would be a second governance
+surface competing with the repository's, and a build could then be governed by a stale copy.
+
+```bash
+git clone https://github.com/protocol-governed-computing/software_governance
+export PGC_PLATFORM_ROOT=$PWD/software_governance
+pgc            # reports what is installed and whether the anchor resolves
+```
+
+`PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
+(additional domains contributing their own `registry/structures`) are optional.
+
+**Versioning.** Two schemes, and the published version follows the second.
+
+- **Internal** — each repository's `VERSION` file, a monotonic composition ordinal. PGC versions the
+  composition rather than each repo: they release together and the governance closure forces lockstep,
+  so the ordinal names which composition a repo belongs to. Development happens on `dev/<N>` and each
+  cycle is tagged `release-<N>`. This is not published.
+- **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v2`**.
+
+**The published version is the public one: `v2` is `2.0.0`.** The standard the packages implement is a
+separate artifact on its own track and is not this number.
+
+The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616

pgc_runtime-2.0.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+pgc_runtime-2.0.0.dist-info/licenses/LICENSE,sha256=wf4s-Px76q2zHB2b8Gbvuu4ULua8AMds2IY01MkBn0A,2544
+pgc_runtime-2.0.0.dist-info/licenses/NOTICE,sha256=nE4--l6r3rMCz0nVaFyFohZtY4NYADnrhcS9K2pdNr0,407
+runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runtime/api.py,sha256=zMBTeMHYL2WlcIeZZXT9v3hakt_2jk6nywt_rDlTjxM,2927
+runtime/boot.py,sha256=sVdQMXSDs8ncmaDjORwxArO8SyJMtiDm-q4bvrdYFrE,6384
+runtime/cli.py,sha256=y1Vurnirxqg1p5WNZpdiEAZ4-YWMlOXlsSS0JspRMSE,14478
+runtime/conformance.py,sha256=h_50oqS0A6AZhwAf_CGcP372kQogRz_KRXiDdV1IMsA,9835
+runtime/ct_errors.py,sha256=Uywmhi_-Zr94fUW7IpLx7RnVrKhjn7UaLHswv9HXEVI,974
+runtime/ct_execute.py,sha256=BqeYskwggWo9J7Jm1qZoWk5bBdhA5d_3fGbw-SwQpA0,2821
+runtime/ct_executor.py,sha256=ETxYAaHk1sEePVinsOShHFgH62VRGi6Zeqltg02UU4Q,11104
+runtime/dispatcher.py,sha256=bJL15rFtNFacHv4urWRaz8TtOxp7-fRHHBFb8EbTqNA,18506
+runtime/evidence.py,sha256=yHVLpkFam-hv_RZogQ1cmHYltllmdaEQJxCHy2FNAr4,9944
+runtime/loader.py,sha256=Nponv5HHhspGfVdWvQl9P5Cvld6L0vh5rfevAWpub1w,14262
+runtime/memory.py,sha256=3relq5_mA_kBK0SF_j2pqRt3e8D-7WoZY5H3mxN1twI,4597
+runtime/scheduler.py,sha256=g0SsWi1sFKU1RZyVGYK42aq3_X5AACjvzJYJaAl8FLQ,12299
+runtime/trace_viz.py,sha256=ZNTxKLI-T9m6Hma94cbwR980Hih_1f9qFcpK73vMSq4,9335
+runtime/examine/__init__.py,sha256=3k-QGphzMSqgHsIRLAfs_x_D6ZcMtnCekZw3qCLXAcM,4057
+runtime/examine/classifier.py,sha256=w_aemZJSouYgZh-k4-yKcNekZnct9QgCHY99TJ7jhN4,12530
+runtime/examine/cli.py,sha256=xSxwr3GdwNgy7KU_toRo5GIsw1_VmSsak5-gKeopHSc,731
+runtime/examine/hint_engine.py,sha256=c1ZwwSUxDhMmT4IUKHdstuG_gBicG6JvyNRJI9oP318,8700
+runtime/examine/locator.py,sha256=MPo6U8McsBeLjt_7PTqK8qdZTRaSrMnApmNjZM6ftfE,5682
+runtime/examine/parser.py,sha256=csUt_iHHaygrWHhuNAgTX___dK8Q72GRSlpLyuj75hs,8469
+runtime/examine/reporter.py,sha256=eG47mj4KwYGzwi_WvHEw8W58B5YaiWcjE6AX5jcPgqE,3344
+pgc_runtime-2.0.0.dist-info/METADATA,sha256=KlAEUKC0Q7jox_Ta1NupfqqqxUDvlwJ-0kErHMwW9JM,7706
+pgc_runtime-2.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pgc_runtime-2.0.0.dist-info/entry_points.txt,sha256=Braa-8c9Zk3ONAJmtDK982Yra7JVfqbPHOm8HCC6UQ0,54
+pgc_runtime-2.0.0.dist-info/top_level.txt,sha256=-unY84bWeVaGfe3vfIlHYZmkol7p_-E1YKa_rnrmxAc,8
+pgc_runtime-2.0.0.dist-info/RECORD,,

pgc_runtime-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pgc_runtime-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+protocol_runtime = runtime.cli:main

pgc_runtime-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,67 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 Bhash Ganti aka Bachi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+------------------------
+FULL LICENSE TEXT BELOW
+------------------------
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+   "Licensor" shall mean the copyright owner.
+   "Legal Entity" shall mean the union of the acting entity and all other
+   entities that control, are controlled by, or are under common control.
+   "You" shall mean an individual or Legal Entity exercising permissions.
+   "Source" form shall mean the preferred form for making modifications.
+   "Object" form shall mean any form resulting from mechanical transformation.
+   "Work" shall mean the work of authorship.
+   "Derivative Works" shall mean any work based on the Work.
+   "Contribution" shall mean any work intentionally submitted.
+   "Contributor" shall mean Licensor and any individual submitting Contributions.
+
+2. Grant of Copyright License.
+   Each Contributor grants You a perpetual, worldwide, non-exclusive,
+   no-charge, royalty-free copyright license.
+
+3. Grant of Patent License.
+   Each Contributor grants a patent license to make, use, sell, etc.
+
+4. Redistribution.
+   You may reproduce and distribute copies provided that:
+   - You include a copy of this License
+   - You retain notices
+   - You state modifications
+   - You include NOTICE file if present
+
+5. Submission of Contributions.
+   Contributions are under this License unless stated otherwise.
+
+6. Trademarks.
+   This License does not grant trademark rights.
+
+7. Disclaimer of Warranty.
+   Provided "AS IS", without warranties.
+
+8. Limitation of Liability.
+   No liability for damages.
+
+9. Accepting Warranty or Additional Liability.
+   You may offer support/warranty on your own behalf only.

pgc_runtime-2.0.0.dist-info/licenses/NOTICE

@@ -0,0 +1,11 @@
+PGS — Protocol-Governed Systems
+Copyright 2026 Bhash Ganti aka Bachi
+
+This project introduces a protocol-first execution model in which:
+
+- Behavior is declared in protocol artifacts
+- Execution is performed by a deterministic runtime
+- Capability implementations are bound at compile time
+- Governance is enforced through invariants and assertions
+
+Extensibility is achieved by declaration, not refactor.

pgc_runtime-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+runtime

runtime/api.py

@@ -0,0 +1,71 @@
+"""Programmatic runtime entry — run a workflow against a snapshot and return its result surface.
+
+This is the in-process core behind `runtime run`: it loads the domain snapshot, opens a trace, drives
+the workflow topology via `scheduler.run_wf`, and returns the terminal status **and result surface**. The
+CLI is a thin wrapper over it, and out-of-process consumers that need the workflow surface programmatically
+(e.g. the change-management validation pipeline) call this directly instead of shelling out and parsing
+stdout or data files.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from runtime.boot import boot
+from runtime.evidence import TraceWriter, make_trace_id
+from runtime.scheduler import run_wf
+
+
+@dataclass(frozen=True)
+class RunResult:
+    status: str                     # terminal workflow outcome (e.g. "SUCCESS", "ACK", "VIOLATION")
+    surface: dict[str, Any]         # workflow result surface (the observable outputs)
+    trace_id: str
+    trace_dir: Path
+
+
+def run_workflow(
+    *,
+    wf_fqdn: str,
+    payload: dict[str, Any],
+    data_root: str | Path,
+    snapshot_root: str | Path | None = None,
+) -> RunResult:
+    """Warm-boot the assembled snapshot and execute a workflow; return `(status, surface, trace)`.
+
+    The snapshot (assembled product) is read-only input, verified via its manifest (root of trust).
+    All mutable output is scoped to the instance root `data_root`: CS state and `data_root/traces/`.
+    `snapshot_root` defaults to the sibling `../snapshot` when None.
+    Raises on load/vocab errors and propagates runtime exceptions (after recording them to the trace).
+    """
+    data_root = Path(data_root)
+    domain = wf_fqdn.split("::")[0]
+
+    booted = boot(snapshot_root)
+    pkg = booted.domains.get(domain)
+    if pkg is None:
+        raise RuntimeError(
+            f"Domain {domain!r} is not in the assembled snapshot "
+            f"(manifest domains: {sorted(booted.domains)})."
+        )
+
+    trace_id = make_trace_id(domain, wf_fqdn, payload)
+    wf_code = wf_fqdn.split("::")[-1]
+    trace_dir = data_root / "traces" / domain / wf_code / trace_id
+    trace_dir.mkdir(parents=True, exist_ok=True)
+
+    wf_addr = pkg.vocab.addr(wf_fqdn)   # KeyError if the WF is not in the snapshot vocab
+    writer = TraceWriter(trace_dir=trace_dir, trace_id=trace_id, domain=domain,
+                         wf_addr=wf_addr, wf_fqdn=wf_fqdn, snapshot_root=booted.snapshot_root,
+                         snapshot_id=booted.snapshot_id)
+    try:
+        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))
+        raise
+    finally:
+        writer.close()
+
+    return RunResult(status=status, surface=surface or {}, trace_id=trace_id, trace_dir=trace_dir)

runtime/boot.py

@@ -0,0 +1,147 @@
+"""
+boot.py — warm reboot: bring the assembled snapshot resident and hash-verified.
+
+The manifest is the ROOT OF TRUST. The runtime boots *through* it, never by scanning the
+filesystem. Contract: snapshot_assembler/doc/SNAPSHOT_ASSEMBLY_CONTRACT.md
+
+Boot sequence:
+    1. load manifest.json
+    2. recompute composite_hash from the identity view of domains[]  →  MUST equal manifest's
+       (verifier INDEPENDENCE: the runtime recomputes per the contract; it does not import the
+        assembler's code to verify the assembler's output)
+    3. per domain: load_domain(..., expected_tokenized_hash=<manifest>) — anchors on-disk to manifest
+    4. build one RuntimePackage per domain
+    5. warm reboot complete = all manifest domains resident + hash-verified
+
+There is no WF to traverse in a surface-only snapshot (e.g. platform); warm reboot proves the
+substrate loads and verifies. Execution is a separate step against an already-booted universe.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from runtime.loader import RuntimePackage, load_domain
+
+
+@dataclass(frozen=True)
+class BootedSnapshot:
+    """The resident, verified executable universe."""
+    snapshot_id: str
+    snapshot_root: Path
+    manifest: dict[str, Any]
+    domains: dict[str, RuntimePackage]
+
+    # The nine execution concerns, in flow order (shown when present in a domain).
+    _CONCERNS = ("TI", "AC", "IN", "WF", "CC", "CT", "CS", "EV", "TE")
+    _SYSTEM_NS = ("node_kind", "edge_kind", "outcome", "transition")
+
+    def summary(self) -> str:
+        from collections import Counter
+
+        lines = [
+            f"snapshot_id: {self.snapshot_id}",
+            f"domains:     {len(self.domains)}",
+        ]
+        for name, pkg in self.domains.items():
+            # Concern breakdown straight from the domain vocabulary (counts every declared artifact,
+            # including AC_/EV_ which are not in the executable dispatch/handlers tables).
+            counts: Counter = Counter()
+            for fqdn in pkg.vocab.forward.values():
+                if "::" not in fqdn:
+                    continue
+                ns, code = fqdn.split("::", 1)
+                if ns in self._SYSTEM_NS:
+                    continue
+                counts[code.split("_")[0]] += 1
+            concerns = " ".join(f"{counts[c]} {c}" for c in self._CONCERNS if counts.get(c))
+            lines.append(f"  - {name}: {concerns or '(no execution concerns)'} · {len(pkg.vocab.forward)} addr")
+        return "\n".join(lines)
+
+
+def default_snapshot_root() -> Path:
+    """PGC_SNAPSHOT_ROOT, or the sibling `../snapshot` of this repo (umbrella product dir)."""
+    env = os.environ.get("PGC_SNAPSHOT_ROOT")
+    if env:
+        return Path(env)
+    # runtime/boot.py → runtime/ (pkg) → protocol_runtime/ (repo) → protocol-governed-computing/
+    return Path(__file__).resolve().parents[2] / "snapshot"
+
+
+# --- composite hash: independent reimplementation of the assembly contract -----------------
+
+def _identity_view(domains: list[dict]) -> list[dict]:
+    view = [
+        {
+            "domain": d["domain"],
+            "tokenized_projection_hash":  d["projections"]["tokenized"]["projection_hash"],
+            "vocabulary_projection_hash": d["projections"]["vocabulary"]["projection_hash"],
+            # Canonical joins the view because every other member is graph-derived, and STRUCTURE
+            # artifacts never enter the semantic graph — without it a STRUCTURE artifact could
+            # change inside a sealed snapshot and boot would still attest the same identity.
+            "canonical_projection_hash":  d["projections"]["canonical"]["projection_hash"],
+            "attestation_hash":           d["projections"]["trust"]["attestation_hash"],
+            "graph_address_hash":         d["graph_address_hash"],
+        }
+        for d in domains
+    ]
+    return sorted(view, key=lambda e: e["domain"])
+
+
+def _composite_hash(domains: list[dict]) -> str:
+    canonical = json.dumps(_identity_view(domains), sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _load_manifest(snapshot_root: Path) -> dict:
+    path = snapshot_root / "manifest.json"
+    if not path.exists():
+        raise FileNotFoundError(f"Assembled snapshot manifest missing: {path}")
+    with path.open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+def boot(snapshot_root: str | Path | None = None) -> BootedSnapshot:
+    """Warm-boot the assembled snapshot: verify the manifest, load + anchor every domain."""
+    root = Path(snapshot_root) if snapshot_root is not None else default_snapshot_root()
+    manifest = _load_manifest(root)
+    domains_meta = manifest.get("domains", [])
+
+    # 2. ACCEPTANCE — all four conditions of `3b` §7, established from content.
+    #
+    # The runtime does not carry its own weaker copy of this. It previously recomputed the composite
+    # over the manifest's RECORDED per-domain hashes, which detects a tampered manifest and not a
+    # tampered constituent — and a snapshot with an edited projection booted and reported healthy.
+    # `assembler.core.verify_snapshot` recomputes every constituent from its bytes; there is one
+    # acceptance determination and both the assembler and the runtime reach it.
+    #
+    # Importing it is not a layering breach: acceptance is a determination ABOUT a snapshot (`3b` §7),
+    # not part of assembling one, and a second implementation of one determination is two things that
+    # can disagree.
+    from assembler.core import AssemblyError, verify_snapshot
+    try:
+        verify_snapshot(root)
+    except AssemblyError as exc:
+        raise RuntimeError(f"Snapshot refused at acceptance: {exc}") from exc
+    recomputed = manifest.get("snapshot_id")
+
+    # 3-4. per-domain load, anchored to the manifest's tokenized hash
+    domains: dict[str, RuntimePackage] = {}
+    for d in domains_meta:
+        name = d["domain"]
+        domains[name] = load_domain(
+            root, name,
+            expected_tokenized_hash=d["projections"]["tokenized"]["projection_hash"],
+        )
+
+    return BootedSnapshot(
+        snapshot_id=manifest.get("snapshot_id", recomputed),
+        snapshot_root=root,
+        manifest=manifest,
+        domains=domains,
+    )