Metadata-Version: 2.4
Name: pgc-compiler
Version: 4.0.0
Summary: PGC protocol compiler — compiles governed declarations into sealed, verified projections (import package: compiler)
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_compiler
Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
Keywords: protocol-governed-computing,pgc,governance-compilation,topology-compiler,semantic-addressing,authorization
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 :: Software Development :: Compilers
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: click
Requires-Dist: pyyaml
Requires-Dist: jsonschema
Dynamic: license-file

# 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

```bash
pip install pgc-compiler
```

Once installed:

```bash
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:

```bash
./compile.sh STRUCTURE_BUILD_PLATFORM_CONFIG_V1   # 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:

```bash
protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V1
protocol_compiler compile --all-structures
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` and `PGC_SNAPSHOT_ROOT` override the
default sibling paths.

## 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 check, hash and conformance verification |
| 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.

**Conformance runs at compile time.** Capability-transform implementations are tested against their
declared `TEST_DATA` during every build; one that fails blocks snapshot validation.

## 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` | 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_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_ROOT` is where compiled output is written, and each domain build needs
its own: every layer's output consolidates into one root, and verification rejects any file in that
root the current build did not declare. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot
profiles, required by the assembler and the runtime alike.

`PGC_BUILD_ROOT` is accepted and reported and **nothing reads it** — `PGC_SNAPSHOT_ROOT` is the
anchor that controls output.

The full sequence, with the repositories it needs, is in
[`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).

**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: `v4` is `4.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
