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

protocol_governed_computing-5.0.0/PKG-INFO

@@ -0,0 +1,415 @@
+Metadata-Version: 2.4
+Name: protocol-governed-computing
+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
+Project-URL: Homepage, https://omnibachi.org/
+Project-URL: Repository, https://github.com/protocol-governed-computing
+Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
+Keywords: protocol-governed-computing,pgc,governance,authorization,sdlc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+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]==5.0.0; extra == "blockchain"
+
+# pgc_install
+
+**Protocol-Governed Computing — the whole toolchain in one install.**
+
+This repository publishes the `protocol-governed-computing` distribution. PyPI prohibits the
+short name `pgc`, so the composition carries the full project name; the command it installs is
+still `pgc`. It is the composition as *installable
+software*, the counterpart to `pgc_release`, which is the same composition as *sealed
+evidence* — assembled, immutable, and cited by DOI. The parallel is in role, not in citation:
+a release is a thing a paper points at; an install is a thing that changes each version.
+
+```bash
+pip install protocol-governed-computing
+```
+
+That brings in the eight component packages of the family, pinned to one composition, and puts
+`pgc` on the path. To run the sealed composition a paper cites, rather than build one, see
+[`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
+
+## Two steps, not one
+
+Installing the toolchain installs the machinery, not the declarations that govern it. PGC reads those declarations from the repository named by `PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, with no inference. The wheel supplies the implementation; the repository supplies the governance surface.
+
+
+```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
+```
+
+These two steps establish the working platform: install the toolchain, then point it at its governance surface. The compiler can now resolve and compile the platform. Assembling and executing a snapshot requires additional repositories and anchors, described below.
+
+## Who this is for
+
+Two kinds of work start here, and they diverge after the toolchain is installed.
+
+**Kicking the tires — you want to see the platform build and run.** Clone the declaration
+repositories, compile them, assemble a snapshot, execute a workflow. That is the sequence below,
+unmodified.
+
+**Adding a domain — you trust the platform and want to author against it.** Same sequence, with
+your own domain in place of the shipped ones. See *Adding your own domain*.
+
+A third case is not served here: **verifying the sealed composition a paper cites**. That artifact
+is published separately and needs no build — see
+[`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
+
+**One thing surprises domain authors, so it is worth saying early.** You must clone
+`software_governance` even though you never modify it. The wheels give you the toolchain *and* the
+platform's capability implementations; they do not give you the governance surface, because
+declarations never ship in a wheel. Trusting the platform does not spare you the clone.
+
+## Installing a working platform
+
+A **Profiled Normative Platform** is a composition: a governance surface, one or more
+conformance workloads, and the inspection boundary, sealed together under a profile. The
+wheels carry implementations; every declaration comes from a cloned repository. Reaching a
+snapshot that executes therefore means cloning four repositories and setting the anchors
+that tell each build where to read and where to write.
+
+### 1. The toolchain
+
+```bash
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install protocol-governed-computing
+```
+
+### 2. The declaration repositories
+
+```bash
+git clone https://github.com/protocol-governed-computing/software_governance
+git clone https://github.com/protocol-governed-computing/conformance_workloads
+git clone https://github.com/protocol-governed-computing/snapshot_inspector
+git clone https://github.com/protocol-governed-computing/.github pgc_github
+```
+
+`software_governance` is the governance surface. `conformance_workloads` and
+`snapshot_inspector` each contribute a domain the reference profile requires.
+`.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
+
+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` | 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` |
+
+`PGC_DOMAIN_ROOTS` names the directory that directly contains `registry/structures/`, not
+the repository above it. For `conformance_workloads` that is the workload directory
+(`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.
+
+**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
+
+The platform compiles first: every other domain imports its compiled surface, which is
+read from `$PGC_PLATFORM_ROOT/snapshot` regardless of where output is being written.
+
+```bash
+export PGC_PLATFORM_ROOT=$PWD/software_governance
+protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V2
+```
+
+Then each domain, into the root its build configuration declares:
+
+```bash
+PGC_DOMAIN_ROOTS=$PWD/conformance_workloads/workloads/collatz \
+  protocol_compiler compile --structure STRUCTURE_BUILD_WORKLOAD_CONFIG_V0
+
+PGC_DOMAIN_ROOTS=$PWD/snapshot_inspector \
+  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
+
+`--source` is repeatable and takes one compiled root per domain. The profile is the
+conformance contract the assembled snapshot claims.
+
+```bash
+export PGC_SNAPSHOT_PROFILES=$PWD/pgc_github/snapshot_profiles
+
+snapshot_assembler assemble \
+  --source $PWD/software_governance/snapshot/compiled \
+  --source $PWD/conformance_workloads/workloads/collatz/snapshot/compiled \
+  --source $PWD/snapshot_inspector/snapshot/compiled \
+  --out $PWD/snapshot \
+  --profile GOVERNANCE_SURFACE_PROFILE_V0
+```
+
+A conformant assembly reports the domains composed, the snapshot id, a round-trip verify,
+and composition conformance over the artifacts it sealed.
+
+### 6. Boot and execute
+
+```bash
+protocol_runtime boot --snapshot $PWD/snapshot
+
+protocol_runtime run \
+  --wf workload::WF_COLLATZ_CONJECTURE_V0 \
+  --payload $PWD/conformance_workloads/workloads/collatz/test_payloads/01_happy_path.json \
+  --snapshot $PWD/snapshot \
+  --data-root $PWD/data
+```
+
+`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
+the platform's compiled surface, and composes into a snapshot alongside it. You author it; nothing
+generates it for you.
+
+The smallest domain that admits a request, does work, and returns a result is **six files producing
+seventeen artifacts**. `.github/process/domain_authoring.py` builds exactly that from scratch on every
+regression run, so what follows is executed rather than described.
+
+**The shape.**
+
+```
+your_domain/
+  registry/
+    structures/STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0.md   the build manifest
+    <subdomain>/
+      actors/AC_*.md              intents/IN_*.md         workflows/WF_*.md
+      capability_contracts/CC_*.md    capability_transforms/CT_*.md
+  implementation/
+    capability_transforms/atoms/*.py   one module per CT, each exposing execute(inputs, context)
+```
+
+**The build manifest.** Three parts of it are easy to get wrong, and each fails in its own way:
+
+```yaml
+fqdn: your_domain::STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
+artifact_kind: STRUCTURE
+version: V0
+governed_by: structure::CONSTITUTION_STRUCTURE_V0
+authority: pgc.platform
+concern: your_domain
+structure_scope: your_domain        # names the composed domain — see below
+reuse_visibility: business
+core:
+  summary: Build-time STRUCTURE manifest for the your_domain scope
+layer_definitions:
+  YOUR_DOMAIN:
+    domain_subpath: registry
+    registry_module: your_domain.registry
+    implementation_namespace: your_domain.implementation.capability_transforms.atoms
+    layer_category: domain
+identity_rules:
+- match: your_domain.registry
+  namespace: your_domain
+artifact_discovery:
+  search_layers:
+  - YOUR_DOMAIN
+  import_surface:
+    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
+  vocabulary_projection_path:   {layer: GOVERNANCE, subpath: compiled/vocabulary}
+  tokenized_projection_path:    {layer: GOVERNANCE, subpath: compiled/tokenized}
+  evidence_projection_path:     {layer: GOVERNANCE, subpath: compiled/evidence}
+  trust_attestation_path:       {layer: GOVERNANCE, subpath: compiled/trust}
+  visualization_projection_path: {layer: GOVERNANCE, subpath: compiled/visualization}
+  layer_outputs:
+    YOUR_DOMAIN:
+      layer: YOUR_DOMAIN
+      subpath: compiled/canonical
+```
+
+**`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.
+
+**`structure_scope` names the composed domain**, not `layer_category` and not the namespace. Set it
+to something generic and the snapshot composes a domain literally called that — the assembly
+succeeds, conformance passes, and the domain is simply wrongly named. Nothing catches it.
+
+**Building it** is step 4 above with your directory in place of a shipped one:
+
+```bash
+PGC_DOMAIN_ROOTS=$PWD/your_domain \
+  protocol_compiler compile --structure STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
+```
+
+Then add `--source $PWD/your_domain/snapshot/compiled` to the assemble in step 5. The platform must
+be compiled first: `import_surface` reads its compiled vocabulary, and a domain cannot compile
+against a surface that does not yet exist.
+
+**Your domain must be importable at execution time.** The compiler reads declarations from the
+filesystem, but the runtime *imports* the module a CT names. If your package is not on the path, the
+workflow does not raise — it returns `VIOLATION` with the transform's outputs null, which looks like
+a failed business rule rather than a missing module. Either `pip install -e your_domain` or:
+
+```bash
+export PYTHONPATH=$PWD
+```
+
+**What you do not need:** `conformance_workloads`. It contributes the collatz workload, which the
+profile in force does not require — verified by building this path without it. You still need
+`software_governance` for the declarations and `snapshot_inspector` for the inspection domain the
+profile does require.
+
+**A profile permits more than it requires.** Composing your domain alongside the platform does not
+violate the claimed profile: a snapshot may carry more than a profile requires and still conform.
+
+## Known rough edges
+
+- **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` 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
+
+| Package | Role |
+|---|---|
+| `pgc-compiler` | declarations → compiled projections |
+| `pgc-assembler` | projections → sealed snapshot |
+| `pgc-runtime` | snapshot → governed execution |
+| `pgc-inspector` | snapshot → read-only inspection |
+| `pgc-transformation` | change request → protocol artifacts |
+| `pgc-governance` | the governance surface and its capability implementations |
+| `pgc-workloads` | the workloads that make conformance observable |
+| `pgc-domains` | the business domain implementations the composed snapshot binds |
+
+**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 **`v5`**.
+
+**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
+be corrected in a patch release within the same identity, because such a fix changes what a wheel
+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.
+
+`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