protocol_compiler

Topology-native governance compiler for Protocol-Governed Computing.

The compiler translates protocol declarations into sealed, verified projections. It does not execute behavior, contain runtime logic, or interpret intent. Everything a governed system will do is decided here, before anything runs.

Install

pip install pgc-compiler

Once installed:

protocol_compiler --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      (this repo)
snapshot_assembler     projections → assembled snapshot
protocol_runtime       snapshot    → execution
snapshot_inspector     snapshot    → inspection

transformation sits upstream of all of it, turning a problem statement into the artifacts this compiler consumes. protocol_transport governs the boundary at either end of execution.

The compiler is where admissibility is decided. A protocol artifact that violates a constitutional boundary fails compilation, so the runtime is never in a position to execute ungoverned behavior — it receives sealed, self-consistent instructions or the build does not complete.

What it is, and is not

It is a nine-stage compilation pipeline, a governance enforcement gate, a projection producer, and a conformance runner for capability-transform implementations.

It is not a runtime engine, a workflow interpreter, or a code generator for application logic. Schema correctness is a governance concern declared in software_governance; the compiler enforces what governance declares rather than deciding it.

Inputs and outputs

Protocol source is Markdown with YAML frontmatter, discriminated by artifact kind:

AC_ actors          CC_ capability contracts    CS_ capability side effects
CT_ capability transforms                       EV_ events
IN_ intents         RB_ runtime bindings        WF_ workflows
TI_ transport ingress                           TE_ transport egress

Compilation writes per-domain projections, each shaped for one consumer: canonical (the complete governed artifact graph, human-readable), tokenized (the integer-addressed execution substrate), vocabulary (FQDN ↔ address index), evidence (the semantic causality graph), dispatch (per-workflow routing and pipeline steps), handlers (CT-IR, side-effect handler refs, binding policy), plus the artifact index. snapshot_assembler composes these into the snapshot the runtime consumes.

Building

The platform surface compiles first — a domain resolves its governance and capability references against the platform's compiled vocabulary:

./compile.sh STRUCTURE_BUILD_PLATFORM_CONFIG_V0   # the platform surface — named, no default
./compile_domain.sh <domain_root>             # one domain, against the compiled platform

Both wrap the same CLI, which is also installed as a console script:

protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V0
protocol_compiler inspect --structure <CODE> --artifact <fqdn>     # identity + causality chain
protocol_compiler inspect --structure <CODE> --upstream <fqdn>     # walk causality upstream

A domain is self-describing: its build manifest declares its own layer and namespace rule, so adding one requires no compiler edit. PGC_PLATFORM_ROOT overrides the default sibling path. Where a build writes is declared by its configuration, not by the environment.

How compilation works

Nine stages, run in order. Each transforms an immutable State — no stage mutates a prior stage's output, and S7 performs the only side effect in the pipeline.

Stage	Name	What it does
S1	Extract	Parses frontmatter from source artifacts; builds raw graph nodes
S2	Canonicalize	Resolves local keys to FQDNs; builds reference and topology edges
S3	Semantic Addressing	Assigns deterministic integer addresses to every node and edge
S4	Govern	Enforces constitutional invariants; validates governance boundaries
S5	Construct	Assembles the full graph — CT-IR, CS-IR, contract projection, workflow enrichment
S6	Project	Derives the deterministic execution projections
S7	Materialize	Writes projections to disk — the pipeline's only side effect
S8	Verify	Roundtrip validation, determinism and hash checks; the sealed dispatch realizes every declared transition at its own node; no superseded artifact is in force
S9	Attest	Computes the trust attestation binding the verified projections

What makes it different

Governance is a compilation stage, not a linting pass. S4 is a gate: an artifact that violates a constitutional boundary fails the build.

Addressing is topology-native. Every artifact receives a deterministic integer address derived from graph position and content, so the runtime operates on integers and resolves no strings at execution time.

Closure is proven before anything is written. Routing, bindings, input paths and output mappings are all resolved and validated ahead of materialization.

A transform's cases are compiled beside it. A domain that declares TEST_DATA has each vector checked against its target at S7 and written as runnable cases. protocol_runtime conformance runs them and reports each transform proven, unproven or refused; the workspace regression does so for every domain on every build.

Purity rules

The semantic graph is the sole authority and every projection is a derived materialization of it. Graph dataclasses are frozen; stages return new graphs rather than mutating in place. Assertion handlers are statically enumerated in a closed registry and resolved by static lookup — no dynamic import, no filesystem discovery, and a missing handler fails the compile rather than falling back.

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_compilers	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.

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_DOMAIN_ROOTS names an additional domain contributing its own registry/structures — the directory that directly contains it, not the repository above it; pointing one level too high is a silent no-op. PGC_SNAPSHOT_PROFILES is the directory holding snapshot profiles, required by the assembler and the runtime alike.

Where a build writes is declared, not supplied. Each build configuration names its root in output_configuration.root, resolved inside the repository that declares it, and every layer's output consolidates there. Two in-force configurations of one repository naming the same root are refused, and a configuration naming none cannot be built. python -m compiler.cli output-root --structure <code> prints the resolved root. The compiler does not read PGC_SNAPSHOT_ROOT; the runtime does, with its own meaning — the assembled snapshot to execute.

PGC_BUILD_ROOT is accepted and reported and nothing reads it.

The full sequence, with the repositories it needs, is in pgc_install.

Versioning. Two numbers name two different things.

• Published — this distribution's version in pyproject.toml. It moves on its own. A release that changes this repository bumps it, and a release that leaves the repository unchanged keeps it.
• Composition — the public identity (v6, …) names one composition of the whole family. pgc_release records which version of each distribution that composition holds, and pgc_install pins exactly those versions.

Each repository's VERSION file holds the workspace's cycle ordinal, which names the dev/<N> branch. It is development accounting, and it is never published. The standard the packages implement is a separate artifact on its own track, and none of these numbers is its revision.

The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616