Metadata-Version: 2.4
Name: pgc-runtime
Version: 3.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 protocol-governed-computing` 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 **`v3`**.

**The published version is the public one: `v3` is `3.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
