pgc-transformation 2.0.0__tar.gz

pgc_transformation-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_transformation-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_transformation-2.0.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: pgc-transformation
+Version: 2.0.0
+Summary: PGC transformation compiler — the governed change request to authoring mandate pipeline (P0-P8), and the construction compiler that renders artifacts from an approved design (command: tc)
+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/transformation
+Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
+Keywords: protocol-governed-computing,pgc,transformation,change-request,evolution
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pgc-inspector>=2.0.0
+Requires-Dist: pgc-runtime>=2.0.0
+Requires-Dist: click
+Requires-Dist: pyyaml
+Dynamic: license-file
+
+# transformation
+
+**The governed Change Request → Protocol Artifact pipeline**, and it holds **two compilers**.
+
+| Compiler | Transforms | Code | Registry |
+|---|---|---|---|
+| **Design** | problem → design | `transformation/design/` | `registry/design/` |
+| **Construction** | design → protocol artifacts | `transformation/build/` | `registry/build/` |
+
+They are two because they fail differently. A *design* failure is a mandate that is incomplete or
+contradictory, and a phase's rule set catches it. A *construction* failure is a mandate that was
+valid and did not uniquely determine an artifact — only the thing that renders can expose that, and
+the repair amends the design language rather than one register. Merging them would blur two failure
+classes that different layers repair.
+
+The repository is named for the lifecycle, not for either compiler. **`transformation` is not a
+third compiler.** A functional rehost of RI-0's `pgs_change_mgmt`, extended well past where RI-0
+stopped.
+
+A change begins as a plain-language problem statement and is driven through gated phases into an
+**Authoring Mandate** — a complete, reviewable dossier — *before* any protocol artifact is written.
+Only after the mandate is approved are artifacts authored, and the protocol compiler then governs
+their admissibility.
+
+```
+problem statement → P0 → Gate 0 → seed → dossier P1..P7 → Gate 1 → P8 → Gate 2
+     → construction → authored artifacts
+     → protocol_compiler S1..S9 → snapshot_assembler → conformance → runtime → trace
+```
+
+This pipeline is measured in **phases (P0–P8)**; `protocol_compiler` is measured in **stages
+(S1–S9)**. RI-0 numbered both S1–S7/S1–S9, which made every piece of evidence ambiguous about which
+pipeline produced it. A dossier has phases, a compilation has stages, and nothing uses one word for
+the other.
+
+## Install
+
+```bash
+pip install pgc-transformation
+```
+
+Once installed:
+
+```bash
+tc --help
+```
+
+## Build-time tool
+
+`transformation` is **CLI only** — no TI/TE boundary contract, no Operation Identity, not
+reachable over transport. A boundary contract governs a runtime surface served from a sealed
+snapshot; this tool runs *before* a snapshot exists, its output is authored artifacts a human
+gates, and its only reader is the person driving the change.
+
+```bash
+tc phase list                              # phases this build governs
+tc phase check --phase p0 <seed.md>        # structural oracle — ADMISSIBLE / INADMISSIBLE
+tc phase check --phase p1 <register.md>
+tc phase check --phase p2 <register.md> --snapshot <root>   # grounds against the composition
+tc phase template --phase p1               # the required section structure
+tc phase rules --phase p1                  # the declared rule set
+tc phase project <prior.md> --phase p1 --out <doc.md>       # phases that decide nothing
+
+tc phase meta                              # do the rule sets themselves hold?
+tc phase emit --check                      # are the sealed workflows current?
+
+tc baseline show --snapshot <root>                 # the composition present, as a pin
+tc baseline verify <pin.json> --snapshot <root>
+tc baseline approve <pin.json> --phase p2 --by <who>
+
+tc construction check <dossier> --snapshot <root>   # does the design determine its artifacts?
+tc construction emit  <dossier> --root <domain>     # render them, at 100% or not at all
+```
+
+Two of these judge the pipeline rather than a dossier. `tc phase meta` asserts that every declared
+rule can run and every implemented mechanism is declared — if that correspondence breaks, a verdict
+over a document is meaningless, because a rule that cannot run reports green over a subject it never
+evaluated. `tc phase emit --check` asserts the sealed copy of a rule set still agrees with the
+generator that produces it; a rule added after a workflow was emitted once left 52 rules sealed
+against 55 declared, and every run reported confidently on the smaller set. Both belong in a build.
+
+`tc construction check` measures **determinacy** before anything is written: the fraction of the
+facts the artifacts require that the design determines. Below 100% nothing is emitted, because a
+generator choosing a value it was not given is a generator inventing one.
+
+## The two loops
+
+`$W` is the workspace root holding the sibling repos.
+
+**After editing a dossier's P7 or P8** — skipping a step leaves the snapshot describing a design that
+no longer exists:
+
+```bash
+D=$W/business_domains/book_library_mgmt/cr_dossiers/cr_01_catalog
+
+tc construction check $D --snapshot $W/snapshot
+tc construction emit  $D --root $W/business_domains/book_library_mgmt
+
+python $W/transformation/scripts/testbed/construction_acceptance.py
+$W/protocol_compiler/compile_domain.sh $W/business_domains/book_library_mgmt
+PGC_SNAPSHOT_PROFILE=REFERENCE_PLATFORM_PROFILE_V1 $W/snapshot_assembler/assemble.sh
+```
+
+`--snapshot` on the check is not optional in practice. Completeness never looks at what already
+exists, so an artifact inventoried `EXTEND` is rendered whole and replaces its predecessor — a design
+stating only the delta deletes the rest, at 100% completeness. The flag is what runs the narrowing
+check; without it that check does not run, and says so.
+
+Construction writes into `data/`, never into the domain. **Promotion is a separate, deliberate act.**
+A `tc construction build` CLI existed once and was removed, because it duplicated a governed path
+with an ungoverned one.
+
+A new capability transform is a protocol artifact *and* a Python implementation. Construction renders
+the first; the second is hand-authored at
+`business_domains/<domain>/implementation/capability_transforms/atoms/<code_lower>.py` with a
+callable `execute(inputs, context)` raising `CTExecutionError`. A CT whose module is missing returns
+nothing and its contract yields `VIOLATION` — while every check above still passes.
+
+**After changing a phase's rule set** — the rules are declared in
+`transformation/design/<phase>/rules.py` and *sealed* into that phase's workflow artifact. Editing
+the declaration alone leaves `tc phase check` and the governed workflow evaluating different rule
+sets:
+
+```bash
+tc phase emit --check                                  # names the drifted phase
+python $W/transformation/scripts/emit_rule_sets.py     # re-seal
+$W/protocol_compiler/compile_domain.sh $W/transformation
+PGC_SNAPSHOT_PROFILE=REFERENCE_PLATFORM_PROFILE_V1 $W/snapshot_assembler/assemble.sh
+python $W/transformation/scripts/testbed/build_fixtures.py
+python $W/transformation/scripts/testbed/build_payloads.py
+```
+
+Fixtures and payloads are **derived from the live dossier** — never hand-edit one; change the dossier
+or the mutator in `build_fixtures.py`. A derived fixture cannot go stale silently, because the
+derivation raises rather than producing a wrong one.
+
+The fast inner loop is `python scripts/testbed/differential.py`, which drives the capability
+transforms directly. It proves the rule sets and the check logic and nothing about workflow wiring;
+`scripts/testbed/e2e_phases_test.py` boots the assembled snapshot and proves the wiring. Neither
+substitutes for the other — a workflow that bound `$.capability_result.header` across nodes passed
+the differential and failed immediately under the runtime.
+
+From P2 a phase also needs its **priors**, or the handoff between phases goes unchecked:
+P1←p0 · P2←p1 · P3←p2 · P4←p3 · **P5←p0** · P6←p5 · P7←p5+p6 · P8←p7. P5 reads the seed, not P4: the
+subdomain purpose is authored once at P0, has no register to travel in through P1–P4, and reappears
+at P5.
+
+## Why "transformation", not "change management"
+
+**PGC evolution is never greenfield.** Every change is a transformation of an existing composition:
+a new domain still compiles against the platform's normative closure and composes into a snapshot
+that already exists. The name states what the tool does; `change_mgmt` named the process around it.
+
+That property is also what makes the tool testable. Its distinguishing logic — REUSE / EXTEND
+decisions, placement, ownership, semantic preservation, roundtrip equivalence — is meaningful only
+against a baseline. A greenfield run exercises none of it.
+
+## Relationship to the rest of the toolchain
+
+```
+protocol_compiler       source      → compiled projections
+snapshot_assembler      projections → assembled snapshot
+protocol_runtime        snapshot    → execution
+snapshot_inspector      snapshot    → inspection
+transformation           problem     → change request → authoring mandate   (this repo)
+```
+
+Every snapshot fact this pipeline needs arrives through
+`inspector.api.query(operation, params, snapshot_root)`. It imports nothing from `compiler.*`.
+RI-0's pipeline reached directly into `pgs_compiler.compiler.projections` to build indexes itself;
+removing that coupling is why `snapshot_inspector` was completed first, and building this repo
+without it is that work's acceptance test.
+
+## Validation is pinned
+
+Runs are validated against a **named, frozen snapshot**, never "the current snapshot" — every
+register a snapshot-reading phase emits encodes facts about one specific composition. A run that
+observes a different `snapshot_id` fails before any phase executes.
+
+Rebaselining is deliberate and has two halves. `tc baseline verify` proves the composition is the
+one named; `tc baseline approve` records that someone re-read the registers asserting facts about
+it. Which registers a phase owes is derived from its rule set — a register rests on a snapshot fact
+exactly when a rule governing it consults an observation. The approval lives in the pin, so re-pinning
+drops it: an approval is against one composition and survives no other.
+
+## Documents
+
+- `doc/THE_SHAPE_OF_A_CHANGE_V0.md` — when a subject is a new change request and when it is the
+  same one re-authored, and which artifacts a governance change may amend.
+- `doc/TRANSFORMATION_COMPILER_PLAN_V1_ADDENDUM_A.md` — the `book_library_mgmt` domain, its
+  decomposition, and the change request sequence it is worked through.
+- `doc/TRANSFORMATION_COMPILER_PLAN_V1_ADDENDUM_B.md` — self-hosting: why the pipeline's first
+  governed change is itself, and what that settles. Plan V1 itself has been removed; the addenda are
+  what survives, and a settled ruling is restated where it is needed rather than by restoring the
+  plan.
+- `doc/REGISTER_COVERAGE_VERIFICATION.md` — whether a design can state, for an artifact it amends,
+  every fact that artifact carries. Four observed instances of one pattern: a fact the authoring
+  path never had to state because authoring supplies it, and the amending path must state and
+  cannot.
+- `templates/` — the phase templates. **These are the authority**: registers, columns, controlled
+  vocabularies and optionality are read from them, and rule sets are derived. A shape declared
+  anywhere else is not a template.
+
+---
+
+## 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_transformation-2.0.0/README.md

@@ -0,0 +1,246 @@
+# transformation
+
+**The governed Change Request → Protocol Artifact pipeline**, and it holds **two compilers**.
+
+| Compiler | Transforms | Code | Registry |
+|---|---|---|---|
+| **Design** | problem → design | `transformation/design/` | `registry/design/` |
+| **Construction** | design → protocol artifacts | `transformation/build/` | `registry/build/` |
+
+They are two because they fail differently. A *design* failure is a mandate that is incomplete or
+contradictory, and a phase's rule set catches it. A *construction* failure is a mandate that was
+valid and did not uniquely determine an artifact — only the thing that renders can expose that, and
+the repair amends the design language rather than one register. Merging them would blur two failure
+classes that different layers repair.
+
+The repository is named for the lifecycle, not for either compiler. **`transformation` is not a
+third compiler.** A functional rehost of RI-0's `pgs_change_mgmt`, extended well past where RI-0
+stopped.
+
+A change begins as a plain-language problem statement and is driven through gated phases into an
+**Authoring Mandate** — a complete, reviewable dossier — *before* any protocol artifact is written.
+Only after the mandate is approved are artifacts authored, and the protocol compiler then governs
+their admissibility.
+
+```
+problem statement → P0 → Gate 0 → seed → dossier P1..P7 → Gate 1 → P8 → Gate 2
+     → construction → authored artifacts
+     → protocol_compiler S1..S9 → snapshot_assembler → conformance → runtime → trace
+```
+
+This pipeline is measured in **phases (P0–P8)**; `protocol_compiler` is measured in **stages
+(S1–S9)**. RI-0 numbered both S1–S7/S1–S9, which made every piece of evidence ambiguous about which
+pipeline produced it. A dossier has phases, a compilation has stages, and nothing uses one word for
+the other.
+
+## Install
+
+```bash
+pip install pgc-transformation
+```
+
+Once installed:
+
+```bash
+tc --help
+```
+
+## Build-time tool
+
+`transformation` is **CLI only** — no TI/TE boundary contract, no Operation Identity, not
+reachable over transport. A boundary contract governs a runtime surface served from a sealed
+snapshot; this tool runs *before* a snapshot exists, its output is authored artifacts a human
+gates, and its only reader is the person driving the change.
+
+```bash
+tc phase list                              # phases this build governs
+tc phase check --phase p0 <seed.md>        # structural oracle — ADMISSIBLE / INADMISSIBLE
+tc phase check --phase p1 <register.md>
+tc phase check --phase p2 <register.md> --snapshot <root>   # grounds against the composition
+tc phase template --phase p1               # the required section structure
+tc phase rules --phase p1                  # the declared rule set
+tc phase project <prior.md> --phase p1 --out <doc.md>       # phases that decide nothing
+
+tc phase meta                              # do the rule sets themselves hold?
+tc phase emit --check                      # are the sealed workflows current?
+
+tc baseline show --snapshot <root>                 # the composition present, as a pin
+tc baseline verify <pin.json> --snapshot <root>
+tc baseline approve <pin.json> --phase p2 --by <who>
+
+tc construction check <dossier> --snapshot <root>   # does the design determine its artifacts?
+tc construction emit  <dossier> --root <domain>     # render them, at 100% or not at all
+```
+
+Two of these judge the pipeline rather than a dossier. `tc phase meta` asserts that every declared
+rule can run and every implemented mechanism is declared — if that correspondence breaks, a verdict
+over a document is meaningless, because a rule that cannot run reports green over a subject it never
+evaluated. `tc phase emit --check` asserts the sealed copy of a rule set still agrees with the
+generator that produces it; a rule added after a workflow was emitted once left 52 rules sealed
+against 55 declared, and every run reported confidently on the smaller set. Both belong in a build.
+
+`tc construction check` measures **determinacy** before anything is written: the fraction of the
+facts the artifacts require that the design determines. Below 100% nothing is emitted, because a
+generator choosing a value it was not given is a generator inventing one.
+
+## The two loops
+
+`$W` is the workspace root holding the sibling repos.
+
+**After editing a dossier's P7 or P8** — skipping a step leaves the snapshot describing a design that
+no longer exists:
+
+```bash
+D=$W/business_domains/book_library_mgmt/cr_dossiers/cr_01_catalog
+
+tc construction check $D --snapshot $W/snapshot
+tc construction emit  $D --root $W/business_domains/book_library_mgmt
+
+python $W/transformation/scripts/testbed/construction_acceptance.py
+$W/protocol_compiler/compile_domain.sh $W/business_domains/book_library_mgmt
+PGC_SNAPSHOT_PROFILE=REFERENCE_PLATFORM_PROFILE_V1 $W/snapshot_assembler/assemble.sh
+```
+
+`--snapshot` on the check is not optional in practice. Completeness never looks at what already
+exists, so an artifact inventoried `EXTEND` is rendered whole and replaces its predecessor — a design
+stating only the delta deletes the rest, at 100% completeness. The flag is what runs the narrowing
+check; without it that check does not run, and says so.
+
+Construction writes into `data/`, never into the domain. **Promotion is a separate, deliberate act.**
+A `tc construction build` CLI existed once and was removed, because it duplicated a governed path
+with an ungoverned one.
+
+A new capability transform is a protocol artifact *and* a Python implementation. Construction renders
+the first; the second is hand-authored at
+`business_domains/<domain>/implementation/capability_transforms/atoms/<code_lower>.py` with a
+callable `execute(inputs, context)` raising `CTExecutionError`. A CT whose module is missing returns
+nothing and its contract yields `VIOLATION` — while every check above still passes.
+
+**After changing a phase's rule set** — the rules are declared in
+`transformation/design/<phase>/rules.py` and *sealed* into that phase's workflow artifact. Editing
+the declaration alone leaves `tc phase check` and the governed workflow evaluating different rule
+sets:
+
+```bash
+tc phase emit --check                                  # names the drifted phase
+python $W/transformation/scripts/emit_rule_sets.py     # re-seal
+$W/protocol_compiler/compile_domain.sh $W/transformation
+PGC_SNAPSHOT_PROFILE=REFERENCE_PLATFORM_PROFILE_V1 $W/snapshot_assembler/assemble.sh
+python $W/transformation/scripts/testbed/build_fixtures.py
+python $W/transformation/scripts/testbed/build_payloads.py
+```
+
+Fixtures and payloads are **derived from the live dossier** — never hand-edit one; change the dossier
+or the mutator in `build_fixtures.py`. A derived fixture cannot go stale silently, because the
+derivation raises rather than producing a wrong one.
+
+The fast inner loop is `python scripts/testbed/differential.py`, which drives the capability
+transforms directly. It proves the rule sets and the check logic and nothing about workflow wiring;
+`scripts/testbed/e2e_phases_test.py` boots the assembled snapshot and proves the wiring. Neither
+substitutes for the other — a workflow that bound `$.capability_result.header` across nodes passed
+the differential and failed immediately under the runtime.
+
+From P2 a phase also needs its **priors**, or the handoff between phases goes unchecked:
+P1←p0 · P2←p1 · P3←p2 · P4←p3 · **P5←p0** · P6←p5 · P7←p5+p6 · P8←p7. P5 reads the seed, not P4: the
+subdomain purpose is authored once at P0, has no register to travel in through P1–P4, and reappears
+at P5.
+
+## Why "transformation", not "change management"
+
+**PGC evolution is never greenfield.** Every change is a transformation of an existing composition:
+a new domain still compiles against the platform's normative closure and composes into a snapshot
+that already exists. The name states what the tool does; `change_mgmt` named the process around it.
+
+That property is also what makes the tool testable. Its distinguishing logic — REUSE / EXTEND
+decisions, placement, ownership, semantic preservation, roundtrip equivalence — is meaningful only
+against a baseline. A greenfield run exercises none of it.
+
+## Relationship to the rest of the toolchain
+
+```
+protocol_compiler       source      → compiled projections
+snapshot_assembler      projections → assembled snapshot
+protocol_runtime        snapshot    → execution
+snapshot_inspector      snapshot    → inspection
+transformation           problem     → change request → authoring mandate   (this repo)
+```
+
+Every snapshot fact this pipeline needs arrives through
+`inspector.api.query(operation, params, snapshot_root)`. It imports nothing from `compiler.*`.
+RI-0's pipeline reached directly into `pgs_compiler.compiler.projections` to build indexes itself;
+removing that coupling is why `snapshot_inspector` was completed first, and building this repo
+without it is that work's acceptance test.
+
+## Validation is pinned
+
+Runs are validated against a **named, frozen snapshot**, never "the current snapshot" — every
+register a snapshot-reading phase emits encodes facts about one specific composition. A run that
+observes a different `snapshot_id` fails before any phase executes.
+
+Rebaselining is deliberate and has two halves. `tc baseline verify` proves the composition is the
+one named; `tc baseline approve` records that someone re-read the registers asserting facts about
+it. Which registers a phase owes is derived from its rule set — a register rests on a snapshot fact
+exactly when a rule governing it consults an observation. The approval lives in the pin, so re-pinning
+drops it: an approval is against one composition and survives no other.
+
+## Documents
+
+- `doc/THE_SHAPE_OF_A_CHANGE_V0.md` — when a subject is a new change request and when it is the
+  same one re-authored, and which artifacts a governance change may amend.
+- `doc/TRANSFORMATION_COMPILER_PLAN_V1_ADDENDUM_A.md` — the `book_library_mgmt` domain, its
+  decomposition, and the change request sequence it is worked through.
+- `doc/TRANSFORMATION_COMPILER_PLAN_V1_ADDENDUM_B.md` — self-hosting: why the pipeline's first
+  governed change is itself, and what that settles. Plan V1 itself has been removed; the addenda are
+  what survives, and a settled ruling is restated where it is needed rather than by restoring the
+  plan.
+- `doc/REGISTER_COVERAGE_VERIFICATION.md` — whether a design can state, for an artifact it amends,
+  every fact that artifact carries. Four observed instances of one pattern: a fact the authoring
+  path never had to state because authoring supplies it, and the amending path must state and
+  cannot.
+- `templates/` — the phase templates. **These are the authority**: registers, columns, controlled
+  vocabularies and optionality are read from them, and rule sets are derived. A shape declared
+  anywhere else is not a template.
+
+---
+
+## 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