protocol-governed-computing 4.0.0__tar.gz → 5.0.0__tar.gz

{protocol_governed_computing-4.0.0 → protocol_governed_computing-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protocol-governed-computing
-Version: 4.0.0
+Version: 5.0.0
 Summary: Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute
 Author-email: Bhash Ganti <bachipeachy@gmail.com>
 License-Expression: Apache-2.0
@@ -15,16 +15,16 @@ Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Compilers
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: pgc-compiler==4.0.0
-Requires-Dist: pgc-assembler==4.0.0
-Requires-Dist: pgc-runtime==4.0.0
-Requires-Dist: pgc-inspector==4.0.0
-Requires-Dist: pgc-transformation==4.0.0
-Requires-Dist: pgc-governance==4.0.0
-Requires-Dist: pgc-workloads==4.0.0
-Requires-Dist: pgc-domains==4.0.0
+Requires-Dist: pgc-compiler==5.0.0
+Requires-Dist: pgc-assembler==5.0.0
+Requires-Dist: pgc-runtime==5.0.0
+Requires-Dist: pgc-inspector==5.0.0
+Requires-Dist: pgc-transformation==5.0.0
+Requires-Dist: pgc-governance==5.0.0
+Requires-Dist: pgc-workloads==5.0.0
+Requires-Dist: pgc-domains==5.0.0
 Provides-Extra: blockchain
-Requires-Dist: pgc-domains[blockchain]==4.0.0; extra == "blockchain"
+Requires-Dist: pgc-domains[blockchain]==5.0.0; extra == "blockchain"
 
 # pgc_install
 
@@ -107,16 +107,34 @@ git clone https://github.com/protocol-governed-computing/.github pgc_github
 `.github` carries the snapshot profiles, which are conformance contracts rather than
 code and are not published in any wheel.
 
+A **fifth** clone is needed only to reach the platform over HTTP (§7), and only on
+whichever node serves the boundary:
+
+```bash
+git clone https://github.com/protocol-governed-computing/protocol_transport
+```
+
+`protocol_transport` is deliberately not published. It provisions its import roots —
+`adapters` and `resolver` — from its repository root rather than from an installed
+package, so the boundary is composed by whoever deploys it rather than carried into
+every install. Steps 4 through 6 need none of it.
+
+**Pin what you clone.** These commands fetch the default branch, which moves. A wheel at
+one version against declarations from a later branch is an incoherence nothing reports:
+the implementations are one composition's and the declarations another's. Clone
+`--branch <tag>` at the release matching your toolchain — `v5` for `5.0.0` — whenever the
+build has to be reproducible.
+
 ### 3. The anchors
 
-Six environment variables govern where the toolchain reads and writes.
+Five environment variables govern where the toolchain reads and writes. Where the compiler
+writes is not one of them.
 
 | Anchor | Read by | Meaning |
 |---|---|---|
 | `PGC_PLATFORM_ROOT` | compiler | the governance repository — the directory containing `registry/` |
 | `PGC_DOMAIN_ROOTS` | compiler | the domain being compiled — the directory containing `registry/structures/` |
-| `PGC_SNAPSHOT_ROOT` | compiler | where compiled projections are written |
-| `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute — a different meaning; prefer `--snapshot` |
+| `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute; prefer `--snapshot` |
 | `PGC_SNAPSHOT_PROFILES` | assembler | the directory holding snapshot profiles |
 | `PGC_DATA_ROOT` | runtime | side-effect state and traces — or pass `--data-root` |
 
@@ -125,9 +143,12 @@ the repository above it. For `conformance_workloads` that is the workload direct
 (`workloads/collatz`); for `snapshot_inspector` it is the repository root. Pointing it one
 level too high is silent — the build config is simply never found.
 
-`PGC_SNAPSHOT_ROOT` must differ for each domain build. Every layer's output consolidates
-into one snapshot root, and verification rejects any file in that root the current build
-did not declare. Two domains sharing a root cannot both verify.
+**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. Every shipped configuration declares `snapshot`, so each domain writes
+into its own repository's `snapshot/`. Two in-force configurations of one repository naming the
+same root are refused, and a configuration naming none cannot be built. The compiler does not read
+`PGC_SNAPSHOT_ROOT`.
 
 ### 4. Compile each domain
 
@@ -136,21 +157,22 @@ read from `$PGC_PLATFORM_ROOT/snapshot` regardless of where output is being writ
 
 ```bash
 export PGC_PLATFORM_ROOT=$PWD/software_governance
-protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V1
+protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V2
 ```
 
-Then each domain, into its own output root:
+Then each domain, into the root its build configuration declares:
 
 ```bash
 PGC_DOMAIN_ROOTS=$PWD/conformance_workloads/workloads/collatz \
-PGC_SNAPSHOT_ROOT=$PWD/workload_snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_WORKLOAD_CONFIG_V0
 
 PGC_DOMAIN_ROOTS=$PWD/snapshot_inspector \
-PGC_SNAPSHOT_ROOT=$PWD/inspection_snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_INSPECTION_CONFIG_V0
 ```
 
+Each domain writes into its own repository's `snapshot/`, which is where the platform
+already wrote its own and which every one of these repositories gitignores.
+
 Each run reports its stages, artifact count, and whether the result verified and attested.
 
 ### 5. Assemble and seal
@@ -163,8 +185,8 @@ export PGC_SNAPSHOT_PROFILES=$PWD/pgc_github/snapshot_profiles
 
 snapshot_assembler assemble \
   --source $PWD/software_governance/snapshot/compiled \
-  --source $PWD/workload_snapshot/compiled \
-  --source $PWD/inspection_snapshot/compiled \
+  --source $PWD/conformance_workloads/workloads/collatz/snapshot/compiled \
+  --source $PWD/snapshot_inspector/snapshot/compiled \
   --out $PWD/snapshot \
   --profile GOVERNANCE_SURFACE_PROFILE_V0
 ```
@@ -187,6 +209,50 @@ protocol_runtime run \
 `boot` loads and hash-verifies every domain in the manifest before anything executes. The
 payloads are declarations and live in the cloned repository, not in a wheel.
 
+`boot` also reads `PGC_SNAPSHOT_PROFILES`, exported in §5. A sealed snapshot's profile claim was
+evaluated when it was sealed, so booting one should not need the profile root — today it does, and
+reports an error before proceeding if the anchor is unset.
+
+### 7. Reach it over HTTP
+
+Steps 1 through 6 execute through the CLI. The interaction boundary is a separate surface, and two
+of the cloned repositories ship a client for it: `conformance_workloads/workloads/collatz/client`
+submits work, and `snapshot_inspector/client` reads the snapshot. Each carries its own `web/`, a
+`bindings/http.json` naming which operations are reachable at which route, and a `serve.sh`.
+
+**Those `serve.sh` scripts assume a development checkout**, where `runtime`, `inspector` and
+`assembler` are sibling repository roots on `PYTHONPATH`. Here they are installed packages, so the
+roots point at site-packages instead. `protocol_transport` is the exception, and is genuinely a
+repository root because it is unpublished.
+
+```bash
+SP=$(python3 -c 'import site; print(site.getsitepackages()[0])')
+CLIENT=$PWD/conformance_workloads/workloads/collatz/client
+
+PGC_RUNTIME_ROOT=$SP PGC_INSPECTOR_ROOT=$SP PGC_ASSEMBLER_ROOT=$SP PGC_IMPL_ROOTS=$SP \
+PGC_SNAPSHOT_ROOT=$PWD/snapshot \
+PGC_DATA_ROOT=$PWD/data/collatz \
+PGC_HTTP_BINDINGS=$CLIENT/bindings/http.json \
+PGC_STATIC_MOUNTS="/=$CLIENT/web;/snapshot=$PWD/snapshot" \
+PGC_HTTP_PORT=8000 \
+  $PWD/protocol_transport/run_http.sh
+```
+
+Substitute `$PWD/snapshot_inspector/client` and another port for the read surface. Then:
+
+```bash
+curl -s -X POST http://localhost:8000/collatz -d '{"number":27}'
+curl -s -X POST http://localhost:8001/si -d '{"operation":"si.snapshot.validate"}'
+```
+
+The read surface routes every `si.*` operation through one binding, named in the request body
+rather than in the path. The boundary reads its bindings once, at startup: restart it after any
+rebuild.
+
+`run_http.sh` launches `python3`, which is the virtual environment's interpreter while §1's
+environment is active. Set `PYTHON` to an absolute path if you invoke this without activating it —
+not to `$(command -v python)`, which returns an alias rather than a path under some shells.
+
 ## Adding your own domain
 
 A domain is a directory the compiler is pointed at. It declares what it contributes, compiles against
@@ -239,6 +305,7 @@ artifact_discovery:
     domain: platform              # compile against the platform's compiled surface
   artifact_types: [AC, IN, WF, CC, CT]
 output_configuration:
+  root: snapshot                # where this build writes, inside your_domain
   artifacts:
     layer: PROTOCOL_BUILD_ROOT
     subpath: compiled/canonical
@@ -253,7 +320,8 @@ output_configuration:
       subpath: compiled/canonical
 ```
 
-**All five projection paths are required.** Omitting them does not fail early: the build passes
+**`root` and all five projection paths are required.** A configuration without `root` is refused
+before anything is compiled. Omitting them does not fail early: the build passes
 discovery, governance and construction and dies at S7 with five `E301_WRITE_FAILED` errors naming
 each missing path. It reads like a compiler fault and is a missing declaration.
 
@@ -265,7 +333,6 @@ succeeds, conformance passes, and the domain is simply wrongly named. Nothing ca
 
 ```bash
 PGC_DOMAIN_ROOTS=$PWD/your_domain \
-PGC_SNAPSHOT_ROOT=$PWD/your_domain/snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
 ```
 
@@ -292,17 +359,27 @@ violate the claimed profile: a snapshot may carry more than a profile requires a
 
 ## Known rough edges
 
-- **`--all-structures` and `STRUCTURE_BUILD_PLATFORM_CONFIG_V0` do not build.** The `_V0`
-  config requires a layer the resolver does not map, and `--all-structures` additionally
-  names domain structures that are not part of the governance surface. Compile
-  `STRUCTURE_BUILD_PLATFORM_CONFIG_V1` by name.
+- **A successful compile may end with `⚠ Machine-block health: N candidate unconsumed key(s)`.**
+  It is expected, and it is not a failure: the build has already verified and attested by the
+  time it prints. It is a heuristic run after the build. For each artifact kind that no schema
+  closes, it looks for machine-block keys whose names appear nowhere in the compiler's source. A
+  key it lists is a *candidate* for a declaration nothing reads, not proof of one. `--verbose`
+  shows the keys.
 - **`PGC_BUILD_ROOT` is inert.** It is accepted and reported, and nothing reads it.
-  `PGC_SNAPSHOT_ROOT` is the anchor that controls compiled output.
-- **`PGC_SNAPSHOT_ROOT` carries two meanings** — compiled output to the compiler, assembled
-  snapshot to the runtime. Pass `--snapshot` to the runtime rather than relying on it.
 - **`pgc` reports readiness for the platform compile only.** It reads three anchors and
   reports "Ready" once the governance surface resolves; assembly and execution need the
   other three.
+- **`protocol_runtime boot` requires `PGC_SNAPSHOT_PROFILES`.** A sealed snapshot carries its
+  profile claim, and that claim was evaluated when the snapshot was sealed, so booting it should
+  not need the profile root. Unset, `boot` prints an error and then proceeds and succeeds. The
+  sequence above exports it in §5, so §6 inherits it — which makes the ordering load-bearing
+  rather than incidental.
+- **`--data-root` rejects a relative path.** `$PWD/data` above is absolute and passes. A bare
+  `data` does not, which will surface first in whatever script wraps this.
+- **No serving path is published for an installed platform.** Both clients' `serve.sh` resolve
+  `runtime`, `inspector` and `assembler` from sibling repository roots, which exist in a
+  development checkout and not in an install. §7 gives the equivalent invocation; nothing in any
+  repository does.
 
 ## The family
 
@@ -319,9 +396,9 @@ violate the claimed profile: a snapshot may carry more than a profile requires a
 
 **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
 internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
-public identity, tagged on every component repository; the platform is at **`v4`**.
+public identity, tagged on every component repository; the platform is at **`v5`**.
 
-**The published version follows the public one: `v4` opens at `4.0.0`.** The family releases in
+**The published version follows the public one: `v5` opens at `5.0.0`.** The family releases in
 lockstep, so the composition pins exact versions rather than ranges.
 
 A public identity may carry more than one published version. A packaging or distribution defect can
@@ -329,10 +406,10 @@ be corrected in a patch release within the same identity, because such a fix cha
 contains and not what the composition determines. A change to what the composition determines takes
 the next public identity, and only that mints a new DOI.
 
-`v4` is the second kind. The wheels stopped shipping declarations, which is the first; but an
-identity published by more than one domain now resolves to its authoring copy rather than to
-whichever sorted last, and that changes what the composition answers. A patch release would have
-said otherwise.
+`v5` is the second kind. The snapshot identity now covers the claimed profile's content, so
+acceptance refuses a profile changed after sealing, and refuses every snapshot sealed before `v5`.
+A superseded artifact no longer confers effect. Both change what the composition admits, and a patch
+release would have said otherwise.
 
 The standard these packages implement is a separate artifact on its own track, is not this number,
 and is published separately: https://doi.org/10.5281/zenodo.22150616

{protocol_governed_computing-4.0.0 → protocol_governed_computing-5.0.0}/README.md

@@ -79,16 +79,34 @@ git clone https://github.com/protocol-governed-computing/.github pgc_github
 `.github` carries the snapshot profiles, which are conformance contracts rather than
 code and are not published in any wheel.
 
+A **fifth** clone is needed only to reach the platform over HTTP (§7), and only on
+whichever node serves the boundary:
+
+```bash
+git clone https://github.com/protocol-governed-computing/protocol_transport
+```
+
+`protocol_transport` is deliberately not published. It provisions its import roots —
+`adapters` and `resolver` — from its repository root rather than from an installed
+package, so the boundary is composed by whoever deploys it rather than carried into
+every install. Steps 4 through 6 need none of it.
+
+**Pin what you clone.** These commands fetch the default branch, which moves. A wheel at
+one version against declarations from a later branch is an incoherence nothing reports:
+the implementations are one composition's and the declarations another's. Clone
+`--branch <tag>` at the release matching your toolchain — `v5` for `5.0.0` — whenever the
+build has to be reproducible.
+
 ### 3. The anchors
 
-Six environment variables govern where the toolchain reads and writes.
+Five environment variables govern where the toolchain reads and writes. Where the compiler
+writes is not one of them.
 
 | Anchor | Read by | Meaning |
 |---|---|---|
 | `PGC_PLATFORM_ROOT` | compiler | the governance repository — the directory containing `registry/` |
 | `PGC_DOMAIN_ROOTS` | compiler | the domain being compiled — the directory containing `registry/structures/` |
-| `PGC_SNAPSHOT_ROOT` | compiler | where compiled projections are written |
-| `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute — a different meaning; prefer `--snapshot` |
+| `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute; prefer `--snapshot` |
 | `PGC_SNAPSHOT_PROFILES` | assembler | the directory holding snapshot profiles |
 | `PGC_DATA_ROOT` | runtime | side-effect state and traces — or pass `--data-root` |
 
@@ -97,9 +115,12 @@ the repository above it. For `conformance_workloads` that is the workload direct
 (`workloads/collatz`); for `snapshot_inspector` it is the repository root. Pointing it one
 level too high is silent — the build config is simply never found.
 
-`PGC_SNAPSHOT_ROOT` must differ for each domain build. Every layer's output consolidates
-into one snapshot root, and verification rejects any file in that root the current build
-did not declare. Two domains sharing a root cannot both verify.
+**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. Every shipped configuration declares `snapshot`, so each domain writes
+into its own repository's `snapshot/`. Two in-force configurations of one repository naming the
+same root are refused, and a configuration naming none cannot be built. The compiler does not read
+`PGC_SNAPSHOT_ROOT`.
 
 ### 4. Compile each domain
 
@@ -108,21 +129,22 @@ read from `$PGC_PLATFORM_ROOT/snapshot` regardless of where output is being writ
 
 ```bash
 export PGC_PLATFORM_ROOT=$PWD/software_governance
-protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V1
+protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V2
 ```
 
-Then each domain, into its own output root:
+Then each domain, into the root its build configuration declares:
 
 ```bash
 PGC_DOMAIN_ROOTS=$PWD/conformance_workloads/workloads/collatz \
-PGC_SNAPSHOT_ROOT=$PWD/workload_snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_WORKLOAD_CONFIG_V0
 
 PGC_DOMAIN_ROOTS=$PWD/snapshot_inspector \
-PGC_SNAPSHOT_ROOT=$PWD/inspection_snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_INSPECTION_CONFIG_V0
 ```
 
+Each domain writes into its own repository's `snapshot/`, which is where the platform
+already wrote its own and which every one of these repositories gitignores.
+
 Each run reports its stages, artifact count, and whether the result verified and attested.
 
 ### 5. Assemble and seal
@@ -135,8 +157,8 @@ export PGC_SNAPSHOT_PROFILES=$PWD/pgc_github/snapshot_profiles
 
 snapshot_assembler assemble \
   --source $PWD/software_governance/snapshot/compiled \
-  --source $PWD/workload_snapshot/compiled \
-  --source $PWD/inspection_snapshot/compiled \
+  --source $PWD/conformance_workloads/workloads/collatz/snapshot/compiled \
+  --source $PWD/snapshot_inspector/snapshot/compiled \
   --out $PWD/snapshot \
   --profile GOVERNANCE_SURFACE_PROFILE_V0
 ```
@@ -159,6 +181,50 @@ protocol_runtime run \
 `boot` loads and hash-verifies every domain in the manifest before anything executes. The
 payloads are declarations and live in the cloned repository, not in a wheel.
 
+`boot` also reads `PGC_SNAPSHOT_PROFILES`, exported in §5. A sealed snapshot's profile claim was
+evaluated when it was sealed, so booting one should not need the profile root — today it does, and
+reports an error before proceeding if the anchor is unset.
+
+### 7. Reach it over HTTP
+
+Steps 1 through 6 execute through the CLI. The interaction boundary is a separate surface, and two
+of the cloned repositories ship a client for it: `conformance_workloads/workloads/collatz/client`
+submits work, and `snapshot_inspector/client` reads the snapshot. Each carries its own `web/`, a
+`bindings/http.json` naming which operations are reachable at which route, and a `serve.sh`.
+
+**Those `serve.sh` scripts assume a development checkout**, where `runtime`, `inspector` and
+`assembler` are sibling repository roots on `PYTHONPATH`. Here they are installed packages, so the
+roots point at site-packages instead. `protocol_transport` is the exception, and is genuinely a
+repository root because it is unpublished.
+
+```bash
+SP=$(python3 -c 'import site; print(site.getsitepackages()[0])')
+CLIENT=$PWD/conformance_workloads/workloads/collatz/client
+
+PGC_RUNTIME_ROOT=$SP PGC_INSPECTOR_ROOT=$SP PGC_ASSEMBLER_ROOT=$SP PGC_IMPL_ROOTS=$SP \
+PGC_SNAPSHOT_ROOT=$PWD/snapshot \
+PGC_DATA_ROOT=$PWD/data/collatz \
+PGC_HTTP_BINDINGS=$CLIENT/bindings/http.json \
+PGC_STATIC_MOUNTS="/=$CLIENT/web;/snapshot=$PWD/snapshot" \
+PGC_HTTP_PORT=8000 \
+  $PWD/protocol_transport/run_http.sh
+```
+
+Substitute `$PWD/snapshot_inspector/client` and another port for the read surface. Then:
+
+```bash
+curl -s -X POST http://localhost:8000/collatz -d '{"number":27}'
+curl -s -X POST http://localhost:8001/si -d '{"operation":"si.snapshot.validate"}'
+```
+
+The read surface routes every `si.*` operation through one binding, named in the request body
+rather than in the path. The boundary reads its bindings once, at startup: restart it after any
+rebuild.
+
+`run_http.sh` launches `python3`, which is the virtual environment's interpreter while §1's
+environment is active. Set `PYTHON` to an absolute path if you invoke this without activating it —
+not to `$(command -v python)`, which returns an alias rather than a path under some shells.
+
 ## Adding your own domain
 
 A domain is a directory the compiler is pointed at. It declares what it contributes, compiles against
@@ -211,6 +277,7 @@ artifact_discovery:
     domain: platform              # compile against the platform's compiled surface
   artifact_types: [AC, IN, WF, CC, CT]
 output_configuration:
+  root: snapshot                # where this build writes, inside your_domain
   artifacts:
     layer: PROTOCOL_BUILD_ROOT
     subpath: compiled/canonical
@@ -225,7 +292,8 @@ output_configuration:
       subpath: compiled/canonical
 ```
 
-**All five projection paths are required.** Omitting them does not fail early: the build passes
+**`root` and all five projection paths are required.** A configuration without `root` is refused
+before anything is compiled. Omitting them does not fail early: the build passes
 discovery, governance and construction and dies at S7 with five `E301_WRITE_FAILED` errors naming
 each missing path. It reads like a compiler fault and is a missing declaration.
 
@@ -237,7 +305,6 @@ succeeds, conformance passes, and the domain is simply wrongly named. Nothing ca
 
 ```bash
 PGC_DOMAIN_ROOTS=$PWD/your_domain \
-PGC_SNAPSHOT_ROOT=$PWD/your_domain/snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
 ```
 
@@ -264,17 +331,27 @@ violate the claimed profile: a snapshot may carry more than a profile requires a
 
 ## Known rough edges
 
-- **`--all-structures` and `STRUCTURE_BUILD_PLATFORM_CONFIG_V0` do not build.** The `_V0`
-  config requires a layer the resolver does not map, and `--all-structures` additionally
-  names domain structures that are not part of the governance surface. Compile
-  `STRUCTURE_BUILD_PLATFORM_CONFIG_V1` by name.
+- **A successful compile may end with `⚠ Machine-block health: N candidate unconsumed key(s)`.**
+  It is expected, and it is not a failure: the build has already verified and attested by the
+  time it prints. It is a heuristic run after the build. For each artifact kind that no schema
+  closes, it looks for machine-block keys whose names appear nowhere in the compiler's source. A
+  key it lists is a *candidate* for a declaration nothing reads, not proof of one. `--verbose`
+  shows the keys.
 - **`PGC_BUILD_ROOT` is inert.** It is accepted and reported, and nothing reads it.
-  `PGC_SNAPSHOT_ROOT` is the anchor that controls compiled output.
-- **`PGC_SNAPSHOT_ROOT` carries two meanings** — compiled output to the compiler, assembled
-  snapshot to the runtime. Pass `--snapshot` to the runtime rather than relying on it.
 - **`pgc` reports readiness for the platform compile only.** It reads three anchors and
   reports "Ready" once the governance surface resolves; assembly and execution need the
   other three.
+- **`protocol_runtime boot` requires `PGC_SNAPSHOT_PROFILES`.** A sealed snapshot carries its
+  profile claim, and that claim was evaluated when the snapshot was sealed, so booting it should
+  not need the profile root. Unset, `boot` prints an error and then proceeds and succeeds. The
+  sequence above exports it in §5, so §6 inherits it — which makes the ordering load-bearing
+  rather than incidental.
+- **`--data-root` rejects a relative path.** `$PWD/data` above is absolute and passes. A bare
+  `data` does not, which will surface first in whatever script wraps this.
+- **No serving path is published for an installed platform.** Both clients' `serve.sh` resolve
+  `runtime`, `inspector` and `assembler` from sibling repository roots, which exist in a
+  development checkout and not in an install. §7 gives the equivalent invocation; nothing in any
+  repository does.
 
 ## The family
 
@@ -291,9 +368,9 @@ violate the claimed profile: a snapshot may carry more than a profile requires a
 
 **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
 internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
-public identity, tagged on every component repository; the platform is at **`v4`**.
+public identity, tagged on every component repository; the platform is at **`v5`**.
 
-**The published version follows the public one: `v4` opens at `4.0.0`.** The family releases in
+**The published version follows the public one: `v5` opens at `5.0.0`.** The family releases in
 lockstep, so the composition pins exact versions rather than ranges.
 
 A public identity may carry more than one published version. A packaging or distribution defect can
@@ -301,10 +378,10 @@ be corrected in a patch release within the same identity, because such a fix cha
 contains and not what the composition determines. A change to what the composition determines takes
 the next public identity, and only that mints a new DOI.
 
-`v4` is the second kind. The wheels stopped shipping declarations, which is the first; but an
-identity published by more than one domain now resolves to its authoring copy rather than to
-whichever sorted last, and that changes what the composition answers. A patch release would have
-said otherwise.
+`v5` is the second kind. The snapshot identity now covers the claimed profile's content, so
+acceptance refuses a profile changed after sealing, and refuses every snapshot sealed before `v5`.
+A superseded artifact no longer confers effect. Both change what the composition admits, and a patch
+release would have said otherwise.
 
 The standard these packages implement is a separate artifact on its own track, is not this number,
 and is published separately: https://doi.org/10.5281/zenodo.22150616

{protocol_governed_computing-4.0.0 → protocol_governed_computing-5.0.0}/protocol_governed_computing.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protocol-governed-computing
-Version: 4.0.0
+Version: 5.0.0
 Summary: Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute
 Author-email: Bhash Ganti <bachipeachy@gmail.com>
 License-Expression: Apache-2.0
@@ -15,16 +15,16 @@ Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Compilers
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: pgc-compiler==4.0.0
-Requires-Dist: pgc-assembler==4.0.0
-Requires-Dist: pgc-runtime==4.0.0
-Requires-Dist: pgc-inspector==4.0.0
-Requires-Dist: pgc-transformation==4.0.0
-Requires-Dist: pgc-governance==4.0.0
-Requires-Dist: pgc-workloads==4.0.0
-Requires-Dist: pgc-domains==4.0.0
+Requires-Dist: pgc-compiler==5.0.0
+Requires-Dist: pgc-assembler==5.0.0
+Requires-Dist: pgc-runtime==5.0.0
+Requires-Dist: pgc-inspector==5.0.0
+Requires-Dist: pgc-transformation==5.0.0
+Requires-Dist: pgc-governance==5.0.0
+Requires-Dist: pgc-workloads==5.0.0
+Requires-Dist: pgc-domains==5.0.0
 Provides-Extra: blockchain
-Requires-Dist: pgc-domains[blockchain]==4.0.0; extra == "blockchain"
+Requires-Dist: pgc-domains[blockchain]==5.0.0; extra == "blockchain"
 
 # pgc_install
 
@@ -107,16 +107,34 @@ git clone https://github.com/protocol-governed-computing/.github pgc_github
 `.github` carries the snapshot profiles, which are conformance contracts rather than
 code and are not published in any wheel.
 
+A **fifth** clone is needed only to reach the platform over HTTP (§7), and only on
+whichever node serves the boundary:
+
+```bash
+git clone https://github.com/protocol-governed-computing/protocol_transport
+```
+
+`protocol_transport` is deliberately not published. It provisions its import roots —
+`adapters` and `resolver` — from its repository root rather than from an installed
+package, so the boundary is composed by whoever deploys it rather than carried into
+every install. Steps 4 through 6 need none of it.
+
+**Pin what you clone.** These commands fetch the default branch, which moves. A wheel at
+one version against declarations from a later branch is an incoherence nothing reports:
+the implementations are one composition's and the declarations another's. Clone
+`--branch <tag>` at the release matching your toolchain — `v5` for `5.0.0` — whenever the
+build has to be reproducible.
+
 ### 3. The anchors
 
-Six environment variables govern where the toolchain reads and writes.
+Five environment variables govern where the toolchain reads and writes. Where the compiler
+writes is not one of them.
 
 | Anchor | Read by | Meaning |
 |---|---|---|
 | `PGC_PLATFORM_ROOT` | compiler | the governance repository — the directory containing `registry/` |
 | `PGC_DOMAIN_ROOTS` | compiler | the domain being compiled — the directory containing `registry/structures/` |
-| `PGC_SNAPSHOT_ROOT` | compiler | where compiled projections are written |
-| `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute — a different meaning; prefer `--snapshot` |
+| `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute; prefer `--snapshot` |
 | `PGC_SNAPSHOT_PROFILES` | assembler | the directory holding snapshot profiles |
 | `PGC_DATA_ROOT` | runtime | side-effect state and traces — or pass `--data-root` |
 
@@ -125,9 +143,12 @@ the repository above it. For `conformance_workloads` that is the workload direct
 (`workloads/collatz`); for `snapshot_inspector` it is the repository root. Pointing it one
 level too high is silent — the build config is simply never found.
 
-`PGC_SNAPSHOT_ROOT` must differ for each domain build. Every layer's output consolidates
-into one snapshot root, and verification rejects any file in that root the current build
-did not declare. Two domains sharing a root cannot both verify.
+**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. Every shipped configuration declares `snapshot`, so each domain writes
+into its own repository's `snapshot/`. Two in-force configurations of one repository naming the
+same root are refused, and a configuration naming none cannot be built. The compiler does not read
+`PGC_SNAPSHOT_ROOT`.
 
 ### 4. Compile each domain
 
@@ -136,21 +157,22 @@ read from `$PGC_PLATFORM_ROOT/snapshot` regardless of where output is being writ
 
 ```bash
 export PGC_PLATFORM_ROOT=$PWD/software_governance
-protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V1
+protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V2
 ```
 
-Then each domain, into its own output root:
+Then each domain, into the root its build configuration declares:
 
 ```bash
 PGC_DOMAIN_ROOTS=$PWD/conformance_workloads/workloads/collatz \
-PGC_SNAPSHOT_ROOT=$PWD/workload_snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_WORKLOAD_CONFIG_V0
 
 PGC_DOMAIN_ROOTS=$PWD/snapshot_inspector \
-PGC_SNAPSHOT_ROOT=$PWD/inspection_snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_INSPECTION_CONFIG_V0
 ```
 
+Each domain writes into its own repository's `snapshot/`, which is where the platform
+already wrote its own and which every one of these repositories gitignores.
+
 Each run reports its stages, artifact count, and whether the result verified and attested.
 
 ### 5. Assemble and seal
@@ -163,8 +185,8 @@ export PGC_SNAPSHOT_PROFILES=$PWD/pgc_github/snapshot_profiles
 
 snapshot_assembler assemble \
   --source $PWD/software_governance/snapshot/compiled \
-  --source $PWD/workload_snapshot/compiled \
-  --source $PWD/inspection_snapshot/compiled \
+  --source $PWD/conformance_workloads/workloads/collatz/snapshot/compiled \
+  --source $PWD/snapshot_inspector/snapshot/compiled \
   --out $PWD/snapshot \
   --profile GOVERNANCE_SURFACE_PROFILE_V0
 ```
@@ -187,6 +209,50 @@ protocol_runtime run \
 `boot` loads and hash-verifies every domain in the manifest before anything executes. The
 payloads are declarations and live in the cloned repository, not in a wheel.
 
+`boot` also reads `PGC_SNAPSHOT_PROFILES`, exported in §5. A sealed snapshot's profile claim was
+evaluated when it was sealed, so booting one should not need the profile root — today it does, and
+reports an error before proceeding if the anchor is unset.
+
+### 7. Reach it over HTTP
+
+Steps 1 through 6 execute through the CLI. The interaction boundary is a separate surface, and two
+of the cloned repositories ship a client for it: `conformance_workloads/workloads/collatz/client`
+submits work, and `snapshot_inspector/client` reads the snapshot. Each carries its own `web/`, a
+`bindings/http.json` naming which operations are reachable at which route, and a `serve.sh`.
+
+**Those `serve.sh` scripts assume a development checkout**, where `runtime`, `inspector` and
+`assembler` are sibling repository roots on `PYTHONPATH`. Here they are installed packages, so the
+roots point at site-packages instead. `protocol_transport` is the exception, and is genuinely a
+repository root because it is unpublished.
+
+```bash
+SP=$(python3 -c 'import site; print(site.getsitepackages()[0])')
+CLIENT=$PWD/conformance_workloads/workloads/collatz/client
+
+PGC_RUNTIME_ROOT=$SP PGC_INSPECTOR_ROOT=$SP PGC_ASSEMBLER_ROOT=$SP PGC_IMPL_ROOTS=$SP \
+PGC_SNAPSHOT_ROOT=$PWD/snapshot \
+PGC_DATA_ROOT=$PWD/data/collatz \
+PGC_HTTP_BINDINGS=$CLIENT/bindings/http.json \
+PGC_STATIC_MOUNTS="/=$CLIENT/web;/snapshot=$PWD/snapshot" \
+PGC_HTTP_PORT=8000 \
+  $PWD/protocol_transport/run_http.sh
+```
+
+Substitute `$PWD/snapshot_inspector/client` and another port for the read surface. Then:
+
+```bash
+curl -s -X POST http://localhost:8000/collatz -d '{"number":27}'
+curl -s -X POST http://localhost:8001/si -d '{"operation":"si.snapshot.validate"}'
+```
+
+The read surface routes every `si.*` operation through one binding, named in the request body
+rather than in the path. The boundary reads its bindings once, at startup: restart it after any
+rebuild.
+
+`run_http.sh` launches `python3`, which is the virtual environment's interpreter while §1's
+environment is active. Set `PYTHON` to an absolute path if you invoke this without activating it —
+not to `$(command -v python)`, which returns an alias rather than a path under some shells.
+
 ## Adding your own domain
 
 A domain is a directory the compiler is pointed at. It declares what it contributes, compiles against
@@ -239,6 +305,7 @@ artifact_discovery:
     domain: platform              # compile against the platform's compiled surface
   artifact_types: [AC, IN, WF, CC, CT]
 output_configuration:
+  root: snapshot                # where this build writes, inside your_domain
   artifacts:
     layer: PROTOCOL_BUILD_ROOT
     subpath: compiled/canonical
@@ -253,7 +320,8 @@ output_configuration:
       subpath: compiled/canonical
 ```
 
-**All five projection paths are required.** Omitting them does not fail early: the build passes
+**`root` and all five projection paths are required.** A configuration without `root` is refused
+before anything is compiled. Omitting them does not fail early: the build passes
 discovery, governance and construction and dies at S7 with five `E301_WRITE_FAILED` errors naming
 each missing path. It reads like a compiler fault and is a missing declaration.
 
@@ -265,7 +333,6 @@ succeeds, conformance passes, and the domain is simply wrongly named. Nothing ca
 
 ```bash
 PGC_DOMAIN_ROOTS=$PWD/your_domain \
-PGC_SNAPSHOT_ROOT=$PWD/your_domain/snapshot \
   protocol_compiler compile --structure STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
 ```
 
@@ -292,17 +359,27 @@ violate the claimed profile: a snapshot may carry more than a profile requires a
 
 ## Known rough edges
 
-- **`--all-structures` and `STRUCTURE_BUILD_PLATFORM_CONFIG_V0` do not build.** The `_V0`
-  config requires a layer the resolver does not map, and `--all-structures` additionally
-  names domain structures that are not part of the governance surface. Compile
-  `STRUCTURE_BUILD_PLATFORM_CONFIG_V1` by name.
+- **A successful compile may end with `⚠ Machine-block health: N candidate unconsumed key(s)`.**
+  It is expected, and it is not a failure: the build has already verified and attested by the
+  time it prints. It is a heuristic run after the build. For each artifact kind that no schema
+  closes, it looks for machine-block keys whose names appear nowhere in the compiler's source. A
+  key it lists is a *candidate* for a declaration nothing reads, not proof of one. `--verbose`
+  shows the keys.
 - **`PGC_BUILD_ROOT` is inert.** It is accepted and reported, and nothing reads it.
-  `PGC_SNAPSHOT_ROOT` is the anchor that controls compiled output.
-- **`PGC_SNAPSHOT_ROOT` carries two meanings** — compiled output to the compiler, assembled
-  snapshot to the runtime. Pass `--snapshot` to the runtime rather than relying on it.
 - **`pgc` reports readiness for the platform compile only.** It reads three anchors and
   reports "Ready" once the governance surface resolves; assembly and execution need the
   other three.
+- **`protocol_runtime boot` requires `PGC_SNAPSHOT_PROFILES`.** A sealed snapshot carries its
+  profile claim, and that claim was evaluated when the snapshot was sealed, so booting it should
+  not need the profile root. Unset, `boot` prints an error and then proceeds and succeeds. The
+  sequence above exports it in §5, so §6 inherits it — which makes the ordering load-bearing
+  rather than incidental.
+- **`--data-root` rejects a relative path.** `$PWD/data` above is absolute and passes. A bare
+  `data` does not, which will surface first in whatever script wraps this.
+- **No serving path is published for an installed platform.** Both clients' `serve.sh` resolve
+  `runtime`, `inspector` and `assembler` from sibling repository roots, which exist in a
+  development checkout and not in an install. §7 gives the equivalent invocation; nothing in any
+  repository does.
 
 ## The family
 
@@ -319,9 +396,9 @@ violate the claimed profile: a snapshot may carry more than a profile requires a
 
 **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
 internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
-public identity, tagged on every component repository; the platform is at **`v4`**.
+public identity, tagged on every component repository; the platform is at **`v5`**.
 
-**The published version follows the public one: `v4` opens at `4.0.0`.** The family releases in
+**The published version follows the public one: `v5` opens at `5.0.0`.** The family releases in
 lockstep, so the composition pins exact versions rather than ranges.
 
 A public identity may carry more than one published version. A packaging or distribution defect can
@@ -329,10 +406,10 @@ be corrected in a patch release within the same identity, because such a fix cha
 contains and not what the composition determines. A change to what the composition determines takes
 the next public identity, and only that mints a new DOI.
 
-`v4` is the second kind. The wheels stopped shipping declarations, which is the first; but an
-identity published by more than one domain now resolves to its authoring copy rather than to
-whichever sorted last, and that changes what the composition answers. A patch release would have
-said otherwise.
+`v5` is the second kind. The snapshot identity now covers the claimed profile's content, so
+acceptance refuses a profile changed after sealing, and refuses every snapshot sealed before `v5`.
+A superseded artifact no longer confers effect. Both change what the composition admits, and a patch
+release would have said otherwise.
 
 The standard these packages implement is a separate artifact on its own track, is not this number,
 and is published separately: https://doi.org/10.5281/zenodo.22150616

protocol_governed_computing-5.0.0/protocol_governed_computing.egg-info/requires.txt

@@ -0,0 +1,11 @@
+pgc-compiler==5.0.0
+pgc-assembler==5.0.0
+pgc-runtime==5.0.0
+pgc-inspector==5.0.0
+pgc-transformation==5.0.0
+pgc-governance==5.0.0
+pgc-workloads==5.0.0
+pgc-domains==5.0.0
+
+[blockchain]
+pgc-domains[blockchain]==5.0.0

{protocol_governed_computing-4.0.0 → protocol_governed_computing-5.0.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 # composition takes the full project name. The import package and the console script are unaffected:
 # a user still runs `pgc`.
 name = "protocol-governed-computing"
-version = "4.0.0"
+version = "5.0.0"
 description = "Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,20 +28,20 @@ classifiers = [
 # the repos release together and the governance closure forces lockstep, so a
 # mixed-version install is not a supported configuration.
 dependencies = [
-  "pgc-compiler==4.0.0",
-  "pgc-assembler==4.0.0",
-  "pgc-runtime==4.0.0",
-  "pgc-inspector==4.0.0",
-  "pgc-transformation==4.0.0",
-  "pgc-governance==4.0.0",
-  "pgc-workloads==4.0.0",
-  "pgc-domains==4.0.0",
+  "pgc-compiler==5.0.0",
+  "pgc-assembler==5.0.0",
+  "pgc-runtime==5.0.0",
+  "pgc-inspector==5.0.0",
+  "pgc-transformation==5.0.0",
+  "pgc-governance==5.0.0",
+  "pgc-workloads==5.0.0",
+  "pgc-domains==5.0.0",
 ]
 
 # The blockchain domain's capability transforms need Keccak-256, which is optional in pgc-domains
 # for the same reason it is optional there: the core compile path imports none of it.
 [project.optional-dependencies]
-blockchain = ["pgc-domains[blockchain]==4.0.0"]
+blockchain = ["pgc-domains[blockchain]==5.0.0"]
 
 [project.scripts]
 pgc = "pgc.cli:main"

protocol_governed_computing-4.0.0/protocol_governed_computing.egg-info/requires.txt

@@ -1,11 +0,0 @@
-pgc-compiler==4.0.0
-pgc-assembler==4.0.0
-pgc-runtime==4.0.0
-pgc-inspector==4.0.0
-pgc-transformation==4.0.0
-pgc-governance==4.0.0
-pgc-workloads==4.0.0
-pgc-domains==4.0.0
-
-[blockchain]
-pgc-domains[blockchain]==4.0.0