pgc-compiler 2.0.0__tar.gz

pgc_compiler-2.0.0/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_compiler-2.0.0/MANIFEST.in

@@ -0,0 +1,15 @@
+# The in-tree build backend and the file it stages.
+#
+# `pyproject.toml` sets build-backend = "_build_hook" with backend-path = ["."],
+# so the hook must travel in the sdist: `python -m build` builds the wheel FROM
+# the sdist, in an isolated directory where anything not shipped does not exist.
+# Without these two lines the sdist builds and the wheel step then fails with
+# `Backend '_build_hook' is not available`.
+#
+# VERSION is the repo-root composition ordinal the hook copies into the package.
+# Omitting it does not fail the build — `_stage_ordinal` skips a missing file —
+# it produces a wheel whose ordinal is silently absent.
+include _build_hook.py
+include VERSION
+
+global-exclude __pycache__ *.pyc .DS_Store

pgc_compiler-2.0.0/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_compiler-2.0.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: pgc-compiler
+Version: 2.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 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_compiler-2.0.0/README.md

@@ -0,0 +1,175 @@
+# 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 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_compiler-2.0.0/VERSION

@@ -0,0 +1 @@
+14

pgc_compiler-2.0.0/_build_hook.py

@@ -0,0 +1,24 @@
+"""Build-time hook: stage the composition ordinal inside the package.
+
+The repo-root VERSION is the single authored declaration and `release.sh`
+enforces it across every repo. A wheel has no repo root, so the value is copied
+into the package during the build. The copy is a build artifact — gitignored,
+regenerated every build, and never edited.
+"""
+from setuptools import build_meta as _orig
+from setuptools.build_meta import *          # noqa: F401,F403
+import pathlib
+
+def _stage_ordinal():
+    root = pathlib.Path(__file__).parent
+    src = root / "VERSION"
+    if src.is_file():
+        (root / "compiler" / "VERSION").write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+
+def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+    _stage_ordinal()
+    return _orig.build_wheel(wheel_directory, config_settings, metadata_directory)
+
+def build_sdist(sdist_directory, config_settings=None):
+    _stage_ordinal()
+    return _orig.build_sdist(sdist_directory, config_settings)

pgc_compiler-2.0.0/compiler/VERSION

@@ -0,0 +1 @@
+14

pgc_compiler-2.0.0/compiler/__init__.py

@@ -0,0 +1 @@
+"""compiler — Protocol Intermediate Representation compiler for PGS."""

pgc_compiler-2.0.0/compiler/atoms/__init__.py

@@ -0,0 +1,54 @@
+"""
+Atoms: Pure functions with no side effects.
+
+Design:
+- Single responsibility
+- Explicit inputs/outputs
+- No I/O, no state
+- Independently testable
+- Reusable across phases
+"""
+
+from compiler.atoms.error_codes import ErrorCode, ERROR_SUGGESTIONS
+from compiler.atoms.errors import CompilerError, Severity
+from compiler.atoms.fqdn import FQDN, parse_fqdn, build_fqdn, to_fqdn
+from compiler.atoms.invariants import require, require_not_none, require_exists
+from compiler.atoms.phase import PhaseResult, PhaseStatus, PhaseMetrics
+from compiler.atoms.pipeline import strip_transient_pipeline_fields
+from compiler.atoms.sorting import (
+    ensure_deterministic_output,
+    sort_artifacts_by_fqdn,
+    sort_by_fqdn,
+    sort_dict_keys,
+)
+from compiler.atoms.snapshot_gate import assert_snapshot_valid
+
+__all__ = [
+    # Error model
+    "CompilerError",
+    "ErrorCode",
+    "ERROR_SUGGESTIONS",
+    "Severity",
+    # FQDN identity
+    "FQDN",
+    "parse_fqdn",
+    "build_fqdn",
+    "to_fqdn",
+    # Phase results
+    "PhaseResult",
+    "PhaseStatus",
+    "PhaseMetrics",
+    # Invariant enforcement
+    "require",
+    "require_not_none",
+    "require_exists",
+    # Pipeline metadata
+    "strip_transient_pipeline_fields",
+    # Deterministic ordering
+    "ensure_deterministic_output",
+    "sort_artifacts_by_fqdn",
+    "sort_by_fqdn",
+    "sort_dict_keys",
+    # Snapshot admission control
+    "assert_snapshot_valid",
+]