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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. protocol_governed_computing-4.0.0/PKG-INFO +338 -0
  2. protocol_governed_computing-4.0.0/README.md +310 -0
  3. protocol_governed_computing-4.0.0/protocol_governed_computing.egg-info/PKG-INFO +338 -0
  4. protocol_governed_computing-4.0.0/protocol_governed_computing.egg-info/requires.txt +11 -0
  5. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/pyproject.toml +10 -10
  6. protocol_governed_computing-3.0.0/PKG-INFO +0 -83
  7. protocol_governed_computing-3.0.0/README.md +0 -55
  8. protocol_governed_computing-3.0.0/protocol_governed_computing.egg-info/PKG-INFO +0 -83
  9. protocol_governed_computing-3.0.0/protocol_governed_computing.egg-info/requires.txt +0 -11
  10. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/pgc/__init__.py +0 -0
  11. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/pgc/cli.py +0 -0
  12. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/protocol_governed_computing.egg-info/SOURCES.txt +0 -0
  13. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/protocol_governed_computing.egg-info/dependency_links.txt +0 -0
  14. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/protocol_governed_computing.egg-info/entry_points.txt +0 -0
  15. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/protocol_governed_computing.egg-info/top_level.txt +0 -0
  16. {protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/setup.cfg +0 -0
protocol_governed_computing-4.0.0/PKG-INFO ADDED
@@ -0,0 +1,338 @@
1
+ Metadata-Version: 2.4
2
+ Name: protocol-governed-computing
3
+ Version: 4.0.0
4
+ Summary: Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute
5
+ Author-email: Bhash Ganti <bachipeachy@gmail.com>
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://omnibachi.org/
8
+ Project-URL: Repository, https://github.com/protocol-governed-computing
9
+ Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
10
+ Keywords: protocol-governed-computing,pgc,governance,authorization,sdlc
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Topic :: Software Development :: Compilers
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ Requires-Dist: pgc-compiler==4.0.0
19
+ Requires-Dist: pgc-assembler==4.0.0
20
+ Requires-Dist: pgc-runtime==4.0.0
21
+ Requires-Dist: pgc-inspector==4.0.0
22
+ Requires-Dist: pgc-transformation==4.0.0
23
+ Requires-Dist: pgc-governance==4.0.0
24
+ Requires-Dist: pgc-workloads==4.0.0
25
+ Requires-Dist: pgc-domains==4.0.0
26
+ Provides-Extra: blockchain
27
+ Requires-Dist: pgc-domains[blockchain]==4.0.0; extra == "blockchain"
28
+
29
+ # pgc_install
30
+
31
+ **Protocol-Governed Computing — the whole toolchain in one install.**
32
+
33
+ This repository publishes the `protocol-governed-computing` distribution. PyPI prohibits the
34
+ short name `pgc`, so the composition carries the full project name; the command it installs is
35
+ still `pgc`. It is the composition as *installable
36
+ software*, the counterpart to `pgc_release`, which is the same composition as *sealed
37
+ evidence* — assembled, immutable, and cited by DOI. The parallel is in role, not in citation:
38
+ a release is a thing a paper points at; an install is a thing that changes each version.
39
+
40
+ ```bash
41
+ pip install protocol-governed-computing
42
+ ```
43
+
44
+ That brings in the eight component packages of the family, pinned to one composition, and puts
45
+ `pgc` on the path. To run the sealed composition a paper cites, rather than build one, see
46
+ [`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
47
+
48
+ ## Two steps, not one
49
+
50
+ 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.
51
+
52
+
53
+ ```bash
54
+ git clone https://github.com/protocol-governed-computing/software_governance
55
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
56
+ pgc # reports what is installed and whether the anchor resolves
57
+ ```
58
+
59
+ 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.
60
+
61
+ ## Who this is for
62
+
63
+ Two kinds of work start here, and they diverge after the toolchain is installed.
64
+
65
+ **Kicking the tires — you want to see the platform build and run.** Clone the declaration
66
+ repositories, compile them, assemble a snapshot, execute a workflow. That is the sequence below,
67
+ unmodified.
68
+
69
+ **Adding a domain — you trust the platform and want to author against it.** Same sequence, with
70
+ your own domain in place of the shipped ones. See *Adding your own domain*.
71
+
72
+ A third case is not served here: **verifying the sealed composition a paper cites**. That artifact
73
+ is published separately and needs no build — see
74
+ [`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
75
+
76
+ **One thing surprises domain authors, so it is worth saying early.** You must clone
77
+ `software_governance` even though you never modify it. The wheels give you the toolchain *and* the
78
+ platform's capability implementations; they do not give you the governance surface, because
79
+ declarations never ship in a wheel. Trusting the platform does not spare you the clone.
80
+
81
+ ## Installing a working platform
82
+
83
+ A **Profiled Normative Platform** is a composition: a governance surface, one or more
84
+ conformance workloads, and the inspection boundary, sealed together under a profile. The
85
+ wheels carry implementations; every declaration comes from a cloned repository. Reaching a
86
+ snapshot that executes therefore means cloning four repositories and setting the anchors
87
+ that tell each build where to read and where to write.
88
+
89
+ ### 1. The toolchain
90
+
91
+ ```bash
92
+ python3.12 -m venv .venv && source .venv/bin/activate
93
+ pip install protocol-governed-computing
94
+ ```
95
+
96
+ ### 2. The declaration repositories
97
+
98
+ ```bash
99
+ git clone https://github.com/protocol-governed-computing/software_governance
100
+ git clone https://github.com/protocol-governed-computing/conformance_workloads
101
+ git clone https://github.com/protocol-governed-computing/snapshot_inspector
102
+ git clone https://github.com/protocol-governed-computing/.github pgc_github
103
+ ```
104
+
105
+ `software_governance` is the governance surface. `conformance_workloads` and
106
+ `snapshot_inspector` each contribute a domain the reference profile requires.
107
+ `.github` carries the snapshot profiles, which are conformance contracts rather than
108
+ code and are not published in any wheel.
109
+
110
+ ### 3. The anchors
111
+
112
+ Six environment variables govern where the toolchain reads and writes.
113
+
114
+ | Anchor | Read by | Meaning |
115
+ |---|---|---|
116
+ | `PGC_PLATFORM_ROOT` | compiler | the governance repository — the directory containing `registry/` |
117
+ | `PGC_DOMAIN_ROOTS` | compiler | the domain being compiled — the directory containing `registry/structures/` |
118
+ | `PGC_SNAPSHOT_ROOT` | compiler | where compiled projections are written |
119
+ | `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute — a different meaning; prefer `--snapshot` |
120
+ | `PGC_SNAPSHOT_PROFILES` | assembler | the directory holding snapshot profiles |
121
+ | `PGC_DATA_ROOT` | runtime | side-effect state and traces — or pass `--data-root` |
122
+
123
+ `PGC_DOMAIN_ROOTS` names the directory that directly contains `registry/structures/`, not
124
+ the repository above it. For `conformance_workloads` that is the workload directory
125
+ (`workloads/collatz`); for `snapshot_inspector` it is the repository root. Pointing it one
126
+ level too high is silent — the build config is simply never found.
127
+
128
+ `PGC_SNAPSHOT_ROOT` must differ for each domain build. Every layer's output consolidates
129
+ into one snapshot root, and verification rejects any file in that root the current build
130
+ did not declare. Two domains sharing a root cannot both verify.
131
+
132
+ ### 4. Compile each domain
133
+
134
+ The platform compiles first: every other domain imports its compiled surface, which is
135
+ read from `$PGC_PLATFORM_ROOT/snapshot` regardless of where output is being written.
136
+
137
+ ```bash
138
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
139
+ protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V1
140
+ ```
141
+
142
+ Then each domain, into its own output root:
143
+
144
+ ```bash
145
+ PGC_DOMAIN_ROOTS=$PWD/conformance_workloads/workloads/collatz \
146
+ PGC_SNAPSHOT_ROOT=$PWD/workload_snapshot \
147
+ protocol_compiler compile --structure STRUCTURE_BUILD_WORKLOAD_CONFIG_V0
148
+
149
+ PGC_DOMAIN_ROOTS=$PWD/snapshot_inspector \
150
+ PGC_SNAPSHOT_ROOT=$PWD/inspection_snapshot \
151
+ protocol_compiler compile --structure STRUCTURE_BUILD_INSPECTION_CONFIG_V0
152
+ ```
153
+
154
+ Each run reports its stages, artifact count, and whether the result verified and attested.
155
+
156
+ ### 5. Assemble and seal
157
+
158
+ `--source` is repeatable and takes one compiled root per domain. The profile is the
159
+ conformance contract the assembled snapshot claims.
160
+
161
+ ```bash
162
+ export PGC_SNAPSHOT_PROFILES=$PWD/pgc_github/snapshot_profiles
163
+
164
+ snapshot_assembler assemble \
165
+ --source $PWD/software_governance/snapshot/compiled \
166
+ --source $PWD/workload_snapshot/compiled \
167
+ --source $PWD/inspection_snapshot/compiled \
168
+ --out $PWD/snapshot \
169
+ --profile GOVERNANCE_SURFACE_PROFILE_V0
170
+ ```
171
+
172
+ A conformant assembly reports the domains composed, the snapshot id, a round-trip verify,
173
+ and composition conformance over the artifacts it sealed.
174
+
175
+ ### 6. Boot and execute
176
+
177
+ ```bash
178
+ protocol_runtime boot --snapshot $PWD/snapshot
179
+
180
+ protocol_runtime run \
181
+ --wf workload::WF_COLLATZ_CONJECTURE_V0 \
182
+ --payload $PWD/conformance_workloads/workloads/collatz/test_payloads/01_happy_path.json \
183
+ --snapshot $PWD/snapshot \
184
+ --data-root $PWD/data
185
+ ```
186
+
187
+ `boot` loads and hash-verifies every domain in the manifest before anything executes. The
188
+ payloads are declarations and live in the cloned repository, not in a wheel.
189
+
190
+ ## Adding your own domain
191
+
192
+ A domain is a directory the compiler is pointed at. It declares what it contributes, compiles against
193
+ the platform's compiled surface, and composes into a snapshot alongside it. You author it; nothing
194
+ generates it for you.
195
+
196
+ The smallest domain that admits a request, does work, and returns a result is **six files producing
197
+ seventeen artifacts**. `.github/process/domain_authoring.py` builds exactly that from scratch on every
198
+ regression run, so what follows is executed rather than described.
199
+
200
+ **The shape.**
201
+
202
+ ```
203
+ your_domain/
204
+ registry/
205
+ structures/STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0.md the build manifest
206
+ <subdomain>/
207
+ actors/AC_*.md intents/IN_*.md workflows/WF_*.md
208
+ capability_contracts/CC_*.md capability_transforms/CT_*.md
209
+ implementation/
210
+ capability_transforms/atoms/*.py one module per CT, each exposing execute(inputs, context)
211
+ ```
212
+
213
+ **The build manifest.** Three parts of it are easy to get wrong, and each fails in its own way:
214
+
215
+ ```yaml
216
+ fqdn: your_domain::STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
217
+ artifact_kind: STRUCTURE
218
+ version: V0
219
+ governed_by: structure::CONSTITUTION_STRUCTURE_V0
220
+ authority: pgc.platform
221
+ concern: your_domain
222
+ structure_scope: your_domain # names the composed domain — see below
223
+ reuse_visibility: business
224
+ core:
225
+ summary: Build-time STRUCTURE manifest for the your_domain scope
226
+ layer_definitions:
227
+ YOUR_DOMAIN:
228
+ domain_subpath: registry
229
+ registry_module: your_domain.registry
230
+ implementation_namespace: your_domain.implementation.capability_transforms.atoms
231
+ layer_category: domain
232
+ identity_rules:
233
+ - match: your_domain.registry
234
+ namespace: your_domain
235
+ artifact_discovery:
236
+ search_layers:
237
+ - YOUR_DOMAIN
238
+ import_surface:
239
+ domain: platform # compile against the platform's compiled surface
240
+ artifact_types: [AC, IN, WF, CC, CT]
241
+ output_configuration:
242
+ artifacts:
243
+ layer: PROTOCOL_BUILD_ROOT
244
+ subpath: compiled/canonical
245
+ vocabulary_projection_path: {layer: GOVERNANCE, subpath: compiled/vocabulary}
246
+ tokenized_projection_path: {layer: GOVERNANCE, subpath: compiled/tokenized}
247
+ evidence_projection_path: {layer: GOVERNANCE, subpath: compiled/evidence}
248
+ trust_attestation_path: {layer: GOVERNANCE, subpath: compiled/trust}
249
+ visualization_projection_path: {layer: GOVERNANCE, subpath: compiled/visualization}
250
+ layer_outputs:
251
+ YOUR_DOMAIN:
252
+ layer: YOUR_DOMAIN
253
+ subpath: compiled/canonical
254
+ ```
255
+
256
+ **All five projection paths are required.** Omitting them does not fail early: the build passes
257
+ discovery, governance and construction and dies at S7 with five `E301_WRITE_FAILED` errors naming
258
+ each missing path. It reads like a compiler fault and is a missing declaration.
259
+
260
+ **`structure_scope` names the composed domain**, not `layer_category` and not the namespace. Set it
261
+ to something generic and the snapshot composes a domain literally called that — the assembly
262
+ succeeds, conformance passes, and the domain is simply wrongly named. Nothing catches it.
263
+
264
+ **Building it** is step 4 above with your directory in place of a shipped one:
265
+
266
+ ```bash
267
+ PGC_DOMAIN_ROOTS=$PWD/your_domain \
268
+ PGC_SNAPSHOT_ROOT=$PWD/your_domain/snapshot \
269
+ protocol_compiler compile --structure STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
270
+ ```
271
+
272
+ Then add `--source $PWD/your_domain/snapshot/compiled` to the assemble in step 5. The platform must
273
+ be compiled first: `import_surface` reads its compiled vocabulary, and a domain cannot compile
274
+ against a surface that does not yet exist.
275
+
276
+ **Your domain must be importable at execution time.** The compiler reads declarations from the
277
+ filesystem, but the runtime *imports* the module a CT names. If your package is not on the path, the
278
+ workflow does not raise — it returns `VIOLATION` with the transform's outputs null, which looks like
279
+ a failed business rule rather than a missing module. Either `pip install -e your_domain` or:
280
+
281
+ ```bash
282
+ export PYTHONPATH=$PWD
283
+ ```
284
+
285
+ **What you do not need:** `conformance_workloads`. It contributes the collatz workload, which the
286
+ profile in force does not require — verified by building this path without it. You still need
287
+ `software_governance` for the declarations and `snapshot_inspector` for the inspection domain the
288
+ profile does require.
289
+
290
+ **A profile permits more than it requires.** Composing your domain alongside the platform does not
291
+ violate the claimed profile: a snapshot may carry more than a profile requires and still conform.
292
+
293
+ ## Known rough edges
294
+
295
+ - **`--all-structures` and `STRUCTURE_BUILD_PLATFORM_CONFIG_V0` do not build.** The `_V0`
296
+ config requires a layer the resolver does not map, and `--all-structures` additionally
297
+ names domain structures that are not part of the governance surface. Compile
298
+ `STRUCTURE_BUILD_PLATFORM_CONFIG_V1` by name.
299
+ - **`PGC_BUILD_ROOT` is inert.** It is accepted and reported, and nothing reads it.
300
+ `PGC_SNAPSHOT_ROOT` is the anchor that controls compiled output.
301
+ - **`PGC_SNAPSHOT_ROOT` carries two meanings** — compiled output to the compiler, assembled
302
+ snapshot to the runtime. Pass `--snapshot` to the runtime rather than relying on it.
303
+ - **`pgc` reports readiness for the platform compile only.** It reads three anchors and
304
+ reports "Ready" once the governance surface resolves; assembly and execution need the
305
+ other three.
306
+
307
+ ## The family
308
+
309
+ | Package | Role |
310
+ |---|---|
311
+ | `pgc-compiler` | declarations → compiled projections |
312
+ | `pgc-assembler` | projections → sealed snapshot |
313
+ | `pgc-runtime` | snapshot → governed execution |
314
+ | `pgc-inspector` | snapshot → read-only inspection |
315
+ | `pgc-transformation` | change request → protocol artifacts |
316
+ | `pgc-governance` | the governance surface and its capability implementations |
317
+ | `pgc-workloads` | the workloads that make conformance observable |
318
+ | `pgc-domains` | the business domain implementations the composed snapshot binds |
319
+
320
+ **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
321
+ internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
322
+ public identity, tagged on every component repository; the platform is at **`v4`**.
323
+
324
+ **The published version follows the public one: `v4` opens at `4.0.0`.** The family releases in
325
+ lockstep, so the composition pins exact versions rather than ranges.
326
+
327
+ A public identity may carry more than one published version. A packaging or distribution defect can
328
+ be corrected in a patch release within the same identity, because such a fix changes what a wheel
329
+ contains and not what the composition determines. A change to what the composition determines takes
330
+ the next public identity, and only that mints a new DOI.
331
+
332
+ `v4` is the second kind. The wheels stopped shipping declarations, which is the first; but an
333
+ identity published by more than one domain now resolves to its authoring copy rather than to
334
+ whichever sorted last, and that changes what the composition answers. A patch release would have
335
+ said otherwise.
336
+
337
+ The standard these packages implement is a separate artifact on its own track, is not this number,
338
+ and is published separately: https://doi.org/10.5281/zenodo.22150616
protocol_governed_computing-4.0.0/README.md ADDED
@@ -0,0 +1,310 @@
1
+ # pgc_install
2
+
3
+ **Protocol-Governed Computing — the whole toolchain in one install.**
4
+
5
+ This repository publishes the `protocol-governed-computing` distribution. PyPI prohibits the
6
+ short name `pgc`, so the composition carries the full project name; the command it installs is
7
+ still `pgc`. It is the composition as *installable
8
+ software*, the counterpart to `pgc_release`, which is the same composition as *sealed
9
+ evidence* — assembled, immutable, and cited by DOI. The parallel is in role, not in citation:
10
+ a release is a thing a paper points at; an install is a thing that changes each version.
11
+
12
+ ```bash
13
+ pip install protocol-governed-computing
14
+ ```
15
+
16
+ That brings in the eight component packages of the family, pinned to one composition, and puts
17
+ `pgc` on the path. To run the sealed composition a paper cites, rather than build one, see
18
+ [`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
19
+
20
+ ## Two steps, not one
21
+
22
+ 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.
23
+
24
+
25
+ ```bash
26
+ git clone https://github.com/protocol-governed-computing/software_governance
27
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
28
+ pgc # reports what is installed and whether the anchor resolves
29
+ ```
30
+
31
+ 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.
32
+
33
+ ## Who this is for
34
+
35
+ Two kinds of work start here, and they diverge after the toolchain is installed.
36
+
37
+ **Kicking the tires — you want to see the platform build and run.** Clone the declaration
38
+ repositories, compile them, assemble a snapshot, execute a workflow. That is the sequence below,
39
+ unmodified.
40
+
41
+ **Adding a domain — you trust the platform and want to author against it.** Same sequence, with
42
+ your own domain in place of the shipped ones. See *Adding your own domain*.
43
+
44
+ A third case is not served here: **verifying the sealed composition a paper cites**. That artifact
45
+ is published separately and needs no build — see
46
+ [`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
47
+
48
+ **One thing surprises domain authors, so it is worth saying early.** You must clone
49
+ `software_governance` even though you never modify it. The wheels give you the toolchain *and* the
50
+ platform's capability implementations; they do not give you the governance surface, because
51
+ declarations never ship in a wheel. Trusting the platform does not spare you the clone.
52
+
53
+ ## Installing a working platform
54
+
55
+ A **Profiled Normative Platform** is a composition: a governance surface, one or more
56
+ conformance workloads, and the inspection boundary, sealed together under a profile. The
57
+ wheels carry implementations; every declaration comes from a cloned repository. Reaching a
58
+ snapshot that executes therefore means cloning four repositories and setting the anchors
59
+ that tell each build where to read and where to write.
60
+
61
+ ### 1. The toolchain
62
+
63
+ ```bash
64
+ python3.12 -m venv .venv && source .venv/bin/activate
65
+ pip install protocol-governed-computing
66
+ ```
67
+
68
+ ### 2. The declaration repositories
69
+
70
+ ```bash
71
+ git clone https://github.com/protocol-governed-computing/software_governance
72
+ git clone https://github.com/protocol-governed-computing/conformance_workloads
73
+ git clone https://github.com/protocol-governed-computing/snapshot_inspector
74
+ git clone https://github.com/protocol-governed-computing/.github pgc_github
75
+ ```
76
+
77
+ `software_governance` is the governance surface. `conformance_workloads` and
78
+ `snapshot_inspector` each contribute a domain the reference profile requires.
79
+ `.github` carries the snapshot profiles, which are conformance contracts rather than
80
+ code and are not published in any wheel.
81
+
82
+ ### 3. The anchors
83
+
84
+ Six environment variables govern where the toolchain reads and writes.
85
+
86
+ | Anchor | Read by | Meaning |
87
+ |---|---|---|
88
+ | `PGC_PLATFORM_ROOT` | compiler | the governance repository — the directory containing `registry/` |
89
+ | `PGC_DOMAIN_ROOTS` | compiler | the domain being compiled — the directory containing `registry/structures/` |
90
+ | `PGC_SNAPSHOT_ROOT` | compiler | where compiled projections are written |
91
+ | `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute — a different meaning; prefer `--snapshot` |
92
+ | `PGC_SNAPSHOT_PROFILES` | assembler | the directory holding snapshot profiles |
93
+ | `PGC_DATA_ROOT` | runtime | side-effect state and traces — or pass `--data-root` |
94
+
95
+ `PGC_DOMAIN_ROOTS` names the directory that directly contains `registry/structures/`, not
96
+ the repository above it. For `conformance_workloads` that is the workload directory
97
+ (`workloads/collatz`); for `snapshot_inspector` it is the repository root. Pointing it one
98
+ level too high is silent — the build config is simply never found.
99
+
100
+ `PGC_SNAPSHOT_ROOT` must differ for each domain build. Every layer's output consolidates
101
+ into one snapshot root, and verification rejects any file in that root the current build
102
+ did not declare. Two domains sharing a root cannot both verify.
103
+
104
+ ### 4. Compile each domain
105
+
106
+ The platform compiles first: every other domain imports its compiled surface, which is
107
+ read from `$PGC_PLATFORM_ROOT/snapshot` regardless of where output is being written.
108
+
109
+ ```bash
110
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
111
+ protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V1
112
+ ```
113
+
114
+ Then each domain, into its own output root:
115
+
116
+ ```bash
117
+ PGC_DOMAIN_ROOTS=$PWD/conformance_workloads/workloads/collatz \
118
+ PGC_SNAPSHOT_ROOT=$PWD/workload_snapshot \
119
+ protocol_compiler compile --structure STRUCTURE_BUILD_WORKLOAD_CONFIG_V0
120
+
121
+ PGC_DOMAIN_ROOTS=$PWD/snapshot_inspector \
122
+ PGC_SNAPSHOT_ROOT=$PWD/inspection_snapshot \
123
+ protocol_compiler compile --structure STRUCTURE_BUILD_INSPECTION_CONFIG_V0
124
+ ```
125
+
126
+ Each run reports its stages, artifact count, and whether the result verified and attested.
127
+
128
+ ### 5. Assemble and seal
129
+
130
+ `--source` is repeatable and takes one compiled root per domain. The profile is the
131
+ conformance contract the assembled snapshot claims.
132
+
133
+ ```bash
134
+ export PGC_SNAPSHOT_PROFILES=$PWD/pgc_github/snapshot_profiles
135
+
136
+ snapshot_assembler assemble \
137
+ --source $PWD/software_governance/snapshot/compiled \
138
+ --source $PWD/workload_snapshot/compiled \
139
+ --source $PWD/inspection_snapshot/compiled \
140
+ --out $PWD/snapshot \
141
+ --profile GOVERNANCE_SURFACE_PROFILE_V0
142
+ ```
143
+
144
+ A conformant assembly reports the domains composed, the snapshot id, a round-trip verify,
145
+ and composition conformance over the artifacts it sealed.
146
+
147
+ ### 6. Boot and execute
148
+
149
+ ```bash
150
+ protocol_runtime boot --snapshot $PWD/snapshot
151
+
152
+ protocol_runtime run \
153
+ --wf workload::WF_COLLATZ_CONJECTURE_V0 \
154
+ --payload $PWD/conformance_workloads/workloads/collatz/test_payloads/01_happy_path.json \
155
+ --snapshot $PWD/snapshot \
156
+ --data-root $PWD/data
157
+ ```
158
+
159
+ `boot` loads and hash-verifies every domain in the manifest before anything executes. The
160
+ payloads are declarations and live in the cloned repository, not in a wheel.
161
+
162
+ ## Adding your own domain
163
+
164
+ A domain is a directory the compiler is pointed at. It declares what it contributes, compiles against
165
+ the platform's compiled surface, and composes into a snapshot alongside it. You author it; nothing
166
+ generates it for you.
167
+
168
+ The smallest domain that admits a request, does work, and returns a result is **six files producing
169
+ seventeen artifacts**. `.github/process/domain_authoring.py` builds exactly that from scratch on every
170
+ regression run, so what follows is executed rather than described.
171
+
172
+ **The shape.**
173
+
174
+ ```
175
+ your_domain/
176
+ registry/
177
+ structures/STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0.md the build manifest
178
+ <subdomain>/
179
+ actors/AC_*.md intents/IN_*.md workflows/WF_*.md
180
+ capability_contracts/CC_*.md capability_transforms/CT_*.md
181
+ implementation/
182
+ capability_transforms/atoms/*.py one module per CT, each exposing execute(inputs, context)
183
+ ```
184
+
185
+ **The build manifest.** Three parts of it are easy to get wrong, and each fails in its own way:
186
+
187
+ ```yaml
188
+ fqdn: your_domain::STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
189
+ artifact_kind: STRUCTURE
190
+ version: V0
191
+ governed_by: structure::CONSTITUTION_STRUCTURE_V0
192
+ authority: pgc.platform
193
+ concern: your_domain
194
+ structure_scope: your_domain # names the composed domain — see below
195
+ reuse_visibility: business
196
+ core:
197
+ summary: Build-time STRUCTURE manifest for the your_domain scope
198
+ layer_definitions:
199
+ YOUR_DOMAIN:
200
+ domain_subpath: registry
201
+ registry_module: your_domain.registry
202
+ implementation_namespace: your_domain.implementation.capability_transforms.atoms
203
+ layer_category: domain
204
+ identity_rules:
205
+ - match: your_domain.registry
206
+ namespace: your_domain
207
+ artifact_discovery:
208
+ search_layers:
209
+ - YOUR_DOMAIN
210
+ import_surface:
211
+ domain: platform # compile against the platform's compiled surface
212
+ artifact_types: [AC, IN, WF, CC, CT]
213
+ output_configuration:
214
+ artifacts:
215
+ layer: PROTOCOL_BUILD_ROOT
216
+ subpath: compiled/canonical
217
+ vocabulary_projection_path: {layer: GOVERNANCE, subpath: compiled/vocabulary}
218
+ tokenized_projection_path: {layer: GOVERNANCE, subpath: compiled/tokenized}
219
+ evidence_projection_path: {layer: GOVERNANCE, subpath: compiled/evidence}
220
+ trust_attestation_path: {layer: GOVERNANCE, subpath: compiled/trust}
221
+ visualization_projection_path: {layer: GOVERNANCE, subpath: compiled/visualization}
222
+ layer_outputs:
223
+ YOUR_DOMAIN:
224
+ layer: YOUR_DOMAIN
225
+ subpath: compiled/canonical
226
+ ```
227
+
228
+ **All five projection paths are required.** Omitting them does not fail early: the build passes
229
+ discovery, governance and construction and dies at S7 with five `E301_WRITE_FAILED` errors naming
230
+ each missing path. It reads like a compiler fault and is a missing declaration.
231
+
232
+ **`structure_scope` names the composed domain**, not `layer_category` and not the namespace. Set it
233
+ to something generic and the snapshot composes a domain literally called that — the assembly
234
+ succeeds, conformance passes, and the domain is simply wrongly named. Nothing catches it.
235
+
236
+ **Building it** is step 4 above with your directory in place of a shipped one:
237
+
238
+ ```bash
239
+ PGC_DOMAIN_ROOTS=$PWD/your_domain \
240
+ PGC_SNAPSHOT_ROOT=$PWD/your_domain/snapshot \
241
+ protocol_compiler compile --structure STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
242
+ ```
243
+
244
+ Then add `--source $PWD/your_domain/snapshot/compiled` to the assemble in step 5. The platform must
245
+ be compiled first: `import_surface` reads its compiled vocabulary, and a domain cannot compile
246
+ against a surface that does not yet exist.
247
+
248
+ **Your domain must be importable at execution time.** The compiler reads declarations from the
249
+ filesystem, but the runtime *imports* the module a CT names. If your package is not on the path, the
250
+ workflow does not raise — it returns `VIOLATION` with the transform's outputs null, which looks like
251
+ a failed business rule rather than a missing module. Either `pip install -e your_domain` or:
252
+
253
+ ```bash
254
+ export PYTHONPATH=$PWD
255
+ ```
256
+
257
+ **What you do not need:** `conformance_workloads`. It contributes the collatz workload, which the
258
+ profile in force does not require — verified by building this path without it. You still need
259
+ `software_governance` for the declarations and `snapshot_inspector` for the inspection domain the
260
+ profile does require.
261
+
262
+ **A profile permits more than it requires.** Composing your domain alongside the platform does not
263
+ violate the claimed profile: a snapshot may carry more than a profile requires and still conform.
264
+
265
+ ## Known rough edges
266
+
267
+ - **`--all-structures` and `STRUCTURE_BUILD_PLATFORM_CONFIG_V0` do not build.** The `_V0`
268
+ config requires a layer the resolver does not map, and `--all-structures` additionally
269
+ names domain structures that are not part of the governance surface. Compile
270
+ `STRUCTURE_BUILD_PLATFORM_CONFIG_V1` by name.
271
+ - **`PGC_BUILD_ROOT` is inert.** It is accepted and reported, and nothing reads it.
272
+ `PGC_SNAPSHOT_ROOT` is the anchor that controls compiled output.
273
+ - **`PGC_SNAPSHOT_ROOT` carries two meanings** — compiled output to the compiler, assembled
274
+ snapshot to the runtime. Pass `--snapshot` to the runtime rather than relying on it.
275
+ - **`pgc` reports readiness for the platform compile only.** It reads three anchors and
276
+ reports "Ready" once the governance surface resolves; assembly and execution need the
277
+ other three.
278
+
279
+ ## The family
280
+
281
+ | Package | Role |
282
+ |---|---|
283
+ | `pgc-compiler` | declarations → compiled projections |
284
+ | `pgc-assembler` | projections → sealed snapshot |
285
+ | `pgc-runtime` | snapshot → governed execution |
286
+ | `pgc-inspector` | snapshot → read-only inspection |
287
+ | `pgc-transformation` | change request → protocol artifacts |
288
+ | `pgc-governance` | the governance surface and its capability implementations |
289
+ | `pgc-workloads` | the workloads that make conformance observable |
290
+ | `pgc-domains` | the business domain implementations the composed snapshot binds |
291
+
292
+ **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
293
+ internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
294
+ public identity, tagged on every component repository; the platform is at **`v4`**.
295
+
296
+ **The published version follows the public one: `v4` opens at `4.0.0`.** The family releases in
297
+ lockstep, so the composition pins exact versions rather than ranges.
298
+
299
+ A public identity may carry more than one published version. A packaging or distribution defect can
300
+ be corrected in a patch release within the same identity, because such a fix changes what a wheel
301
+ contains and not what the composition determines. A change to what the composition determines takes
302
+ the next public identity, and only that mints a new DOI.
303
+
304
+ `v4` is the second kind. The wheels stopped shipping declarations, which is the first; but an
305
+ identity published by more than one domain now resolves to its authoring copy rather than to
306
+ whichever sorted last, and that changes what the composition answers. A patch release would have
307
+ said otherwise.
308
+
309
+ The standard these packages implement is a separate artifact on its own track, is not this number,
310
+ and is published separately: https://doi.org/10.5281/zenodo.22150616
protocol_governed_computing-4.0.0/protocol_governed_computing.egg-info/PKG-INFO ADDED
@@ -0,0 +1,338 @@
1
+ Metadata-Version: 2.4
2
+ Name: protocol-governed-computing
3
+ Version: 4.0.0
4
+ Summary: Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute
5
+ Author-email: Bhash Ganti <bachipeachy@gmail.com>
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://omnibachi.org/
8
+ Project-URL: Repository, https://github.com/protocol-governed-computing
9
+ Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
10
+ Keywords: protocol-governed-computing,pgc,governance,authorization,sdlc
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Topic :: Software Development :: Compilers
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ Requires-Dist: pgc-compiler==4.0.0
19
+ Requires-Dist: pgc-assembler==4.0.0
20
+ Requires-Dist: pgc-runtime==4.0.0
21
+ Requires-Dist: pgc-inspector==4.0.0
22
+ Requires-Dist: pgc-transformation==4.0.0
23
+ Requires-Dist: pgc-governance==4.0.0
24
+ Requires-Dist: pgc-workloads==4.0.0
25
+ Requires-Dist: pgc-domains==4.0.0
26
+ Provides-Extra: blockchain
27
+ Requires-Dist: pgc-domains[blockchain]==4.0.0; extra == "blockchain"
28
+
29
+ # pgc_install
30
+
31
+ **Protocol-Governed Computing — the whole toolchain in one install.**
32
+
33
+ This repository publishes the `protocol-governed-computing` distribution. PyPI prohibits the
34
+ short name `pgc`, so the composition carries the full project name; the command it installs is
35
+ still `pgc`. It is the composition as *installable
36
+ software*, the counterpart to `pgc_release`, which is the same composition as *sealed
37
+ evidence* — assembled, immutable, and cited by DOI. The parallel is in role, not in citation:
38
+ a release is a thing a paper points at; an install is a thing that changes each version.
39
+
40
+ ```bash
41
+ pip install protocol-governed-computing
42
+ ```
43
+
44
+ That brings in the eight component packages of the family, pinned to one composition, and puts
45
+ `pgc` on the path. To run the sealed composition a paper cites, rather than build one, see
46
+ [`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
47
+
48
+ ## Two steps, not one
49
+
50
+ 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.
51
+
52
+
53
+ ```bash
54
+ git clone https://github.com/protocol-governed-computing/software_governance
55
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
56
+ pgc # reports what is installed and whether the anchor resolves
57
+ ```
58
+
59
+ 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.
60
+
61
+ ## Who this is for
62
+
63
+ Two kinds of work start here, and they diverge after the toolchain is installed.
64
+
65
+ **Kicking the tires — you want to see the platform build and run.** Clone the declaration
66
+ repositories, compile them, assemble a snapshot, execute a workflow. That is the sequence below,
67
+ unmodified.
68
+
69
+ **Adding a domain — you trust the platform and want to author against it.** Same sequence, with
70
+ your own domain in place of the shipped ones. See *Adding your own domain*.
71
+
72
+ A third case is not served here: **verifying the sealed composition a paper cites**. That artifact
73
+ is published separately and needs no build — see
74
+ [`pgc_release`](https://github.com/protocol-governed-computing/pgc_release).
75
+
76
+ **One thing surprises domain authors, so it is worth saying early.** You must clone
77
+ `software_governance` even though you never modify it. The wheels give you the toolchain *and* the
78
+ platform's capability implementations; they do not give you the governance surface, because
79
+ declarations never ship in a wheel. Trusting the platform does not spare you the clone.
80
+
81
+ ## Installing a working platform
82
+
83
+ A **Profiled Normative Platform** is a composition: a governance surface, one or more
84
+ conformance workloads, and the inspection boundary, sealed together under a profile. The
85
+ wheels carry implementations; every declaration comes from a cloned repository. Reaching a
86
+ snapshot that executes therefore means cloning four repositories and setting the anchors
87
+ that tell each build where to read and where to write.
88
+
89
+ ### 1. The toolchain
90
+
91
+ ```bash
92
+ python3.12 -m venv .venv && source .venv/bin/activate
93
+ pip install protocol-governed-computing
94
+ ```
95
+
96
+ ### 2. The declaration repositories
97
+
98
+ ```bash
99
+ git clone https://github.com/protocol-governed-computing/software_governance
100
+ git clone https://github.com/protocol-governed-computing/conformance_workloads
101
+ git clone https://github.com/protocol-governed-computing/snapshot_inspector
102
+ git clone https://github.com/protocol-governed-computing/.github pgc_github
103
+ ```
104
+
105
+ `software_governance` is the governance surface. `conformance_workloads` and
106
+ `snapshot_inspector` each contribute a domain the reference profile requires.
107
+ `.github` carries the snapshot profiles, which are conformance contracts rather than
108
+ code and are not published in any wheel.
109
+
110
+ ### 3. The anchors
111
+
112
+ Six environment variables govern where the toolchain reads and writes.
113
+
114
+ | Anchor | Read by | Meaning |
115
+ |---|---|---|
116
+ | `PGC_PLATFORM_ROOT` | compiler | the governance repository — the directory containing `registry/` |
117
+ | `PGC_DOMAIN_ROOTS` | compiler | the domain being compiled — the directory containing `registry/structures/` |
118
+ | `PGC_SNAPSHOT_ROOT` | compiler | where compiled projections are written |
119
+ | `PGC_SNAPSHOT_ROOT` | runtime | the assembled snapshot to execute — a different meaning; prefer `--snapshot` |
120
+ | `PGC_SNAPSHOT_PROFILES` | assembler | the directory holding snapshot profiles |
121
+ | `PGC_DATA_ROOT` | runtime | side-effect state and traces — or pass `--data-root` |
122
+
123
+ `PGC_DOMAIN_ROOTS` names the directory that directly contains `registry/structures/`, not
124
+ the repository above it. For `conformance_workloads` that is the workload directory
125
+ (`workloads/collatz`); for `snapshot_inspector` it is the repository root. Pointing it one
126
+ level too high is silent — the build config is simply never found.
127
+
128
+ `PGC_SNAPSHOT_ROOT` must differ for each domain build. Every layer's output consolidates
129
+ into one snapshot root, and verification rejects any file in that root the current build
130
+ did not declare. Two domains sharing a root cannot both verify.
131
+
132
+ ### 4. Compile each domain
133
+
134
+ The platform compiles first: every other domain imports its compiled surface, which is
135
+ read from `$PGC_PLATFORM_ROOT/snapshot` regardless of where output is being written.
136
+
137
+ ```bash
138
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
139
+ protocol_compiler compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V1
140
+ ```
141
+
142
+ Then each domain, into its own output root:
143
+
144
+ ```bash
145
+ PGC_DOMAIN_ROOTS=$PWD/conformance_workloads/workloads/collatz \
146
+ PGC_SNAPSHOT_ROOT=$PWD/workload_snapshot \
147
+ protocol_compiler compile --structure STRUCTURE_BUILD_WORKLOAD_CONFIG_V0
148
+
149
+ PGC_DOMAIN_ROOTS=$PWD/snapshot_inspector \
150
+ PGC_SNAPSHOT_ROOT=$PWD/inspection_snapshot \
151
+ protocol_compiler compile --structure STRUCTURE_BUILD_INSPECTION_CONFIG_V0
152
+ ```
153
+
154
+ Each run reports its stages, artifact count, and whether the result verified and attested.
155
+
156
+ ### 5. Assemble and seal
157
+
158
+ `--source` is repeatable and takes one compiled root per domain. The profile is the
159
+ conformance contract the assembled snapshot claims.
160
+
161
+ ```bash
162
+ export PGC_SNAPSHOT_PROFILES=$PWD/pgc_github/snapshot_profiles
163
+
164
+ snapshot_assembler assemble \
165
+ --source $PWD/software_governance/snapshot/compiled \
166
+ --source $PWD/workload_snapshot/compiled \
167
+ --source $PWD/inspection_snapshot/compiled \
168
+ --out $PWD/snapshot \
169
+ --profile GOVERNANCE_SURFACE_PROFILE_V0
170
+ ```
171
+
172
+ A conformant assembly reports the domains composed, the snapshot id, a round-trip verify,
173
+ and composition conformance over the artifacts it sealed.
174
+
175
+ ### 6. Boot and execute
176
+
177
+ ```bash
178
+ protocol_runtime boot --snapshot $PWD/snapshot
179
+
180
+ protocol_runtime run \
181
+ --wf workload::WF_COLLATZ_CONJECTURE_V0 \
182
+ --payload $PWD/conformance_workloads/workloads/collatz/test_payloads/01_happy_path.json \
183
+ --snapshot $PWD/snapshot \
184
+ --data-root $PWD/data
185
+ ```
186
+
187
+ `boot` loads and hash-verifies every domain in the manifest before anything executes. The
188
+ payloads are declarations and live in the cloned repository, not in a wheel.
189
+
190
+ ## Adding your own domain
191
+
192
+ A domain is a directory the compiler is pointed at. It declares what it contributes, compiles against
193
+ the platform's compiled surface, and composes into a snapshot alongside it. You author it; nothing
194
+ generates it for you.
195
+
196
+ The smallest domain that admits a request, does work, and returns a result is **six files producing
197
+ seventeen artifacts**. `.github/process/domain_authoring.py` builds exactly that from scratch on every
198
+ regression run, so what follows is executed rather than described.
199
+
200
+ **The shape.**
201
+
202
+ ```
203
+ your_domain/
204
+ registry/
205
+ structures/STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0.md the build manifest
206
+ <subdomain>/
207
+ actors/AC_*.md intents/IN_*.md workflows/WF_*.md
208
+ capability_contracts/CC_*.md capability_transforms/CT_*.md
209
+ implementation/
210
+ capability_transforms/atoms/*.py one module per CT, each exposing execute(inputs, context)
211
+ ```
212
+
213
+ **The build manifest.** Three parts of it are easy to get wrong, and each fails in its own way:
214
+
215
+ ```yaml
216
+ fqdn: your_domain::STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
217
+ artifact_kind: STRUCTURE
218
+ version: V0
219
+ governed_by: structure::CONSTITUTION_STRUCTURE_V0
220
+ authority: pgc.platform
221
+ concern: your_domain
222
+ structure_scope: your_domain # names the composed domain — see below
223
+ reuse_visibility: business
224
+ core:
225
+ summary: Build-time STRUCTURE manifest for the your_domain scope
226
+ layer_definitions:
227
+ YOUR_DOMAIN:
228
+ domain_subpath: registry
229
+ registry_module: your_domain.registry
230
+ implementation_namespace: your_domain.implementation.capability_transforms.atoms
231
+ layer_category: domain
232
+ identity_rules:
233
+ - match: your_domain.registry
234
+ namespace: your_domain
235
+ artifact_discovery:
236
+ search_layers:
237
+ - YOUR_DOMAIN
238
+ import_surface:
239
+ domain: platform # compile against the platform's compiled surface
240
+ artifact_types: [AC, IN, WF, CC, CT]
241
+ output_configuration:
242
+ artifacts:
243
+ layer: PROTOCOL_BUILD_ROOT
244
+ subpath: compiled/canonical
245
+ vocabulary_projection_path: {layer: GOVERNANCE, subpath: compiled/vocabulary}
246
+ tokenized_projection_path: {layer: GOVERNANCE, subpath: compiled/tokenized}
247
+ evidence_projection_path: {layer: GOVERNANCE, subpath: compiled/evidence}
248
+ trust_attestation_path: {layer: GOVERNANCE, subpath: compiled/trust}
249
+ visualization_projection_path: {layer: GOVERNANCE, subpath: compiled/visualization}
250
+ layer_outputs:
251
+ YOUR_DOMAIN:
252
+ layer: YOUR_DOMAIN
253
+ subpath: compiled/canonical
254
+ ```
255
+
256
+ **All five projection paths are required.** Omitting them does not fail early: the build passes
257
+ discovery, governance and construction and dies at S7 with five `E301_WRITE_FAILED` errors naming
258
+ each missing path. It reads like a compiler fault and is a missing declaration.
259
+
260
+ **`structure_scope` names the composed domain**, not `layer_category` and not the namespace. Set it
261
+ to something generic and the snapshot composes a domain literally called that — the assembly
262
+ succeeds, conformance passes, and the domain is simply wrongly named. Nothing catches it.
263
+
264
+ **Building it** is step 4 above with your directory in place of a shipped one:
265
+
266
+ ```bash
267
+ PGC_DOMAIN_ROOTS=$PWD/your_domain \
268
+ PGC_SNAPSHOT_ROOT=$PWD/your_domain/snapshot \
269
+ protocol_compiler compile --structure STRUCTURE_BUILD_YOUR_DOMAIN_CONFIG_V0
270
+ ```
271
+
272
+ Then add `--source $PWD/your_domain/snapshot/compiled` to the assemble in step 5. The platform must
273
+ be compiled first: `import_surface` reads its compiled vocabulary, and a domain cannot compile
274
+ against a surface that does not yet exist.
275
+
276
+ **Your domain must be importable at execution time.** The compiler reads declarations from the
277
+ filesystem, but the runtime *imports* the module a CT names. If your package is not on the path, the
278
+ workflow does not raise — it returns `VIOLATION` with the transform's outputs null, which looks like
279
+ a failed business rule rather than a missing module. Either `pip install -e your_domain` or:
280
+
281
+ ```bash
282
+ export PYTHONPATH=$PWD
283
+ ```
284
+
285
+ **What you do not need:** `conformance_workloads`. It contributes the collatz workload, which the
286
+ profile in force does not require — verified by building this path without it. You still need
287
+ `software_governance` for the declarations and `snapshot_inspector` for the inspection domain the
288
+ profile does require.
289
+
290
+ **A profile permits more than it requires.** Composing your domain alongside the platform does not
291
+ violate the claimed profile: a snapshot may carry more than a profile requires and still conform.
292
+
293
+ ## Known rough edges
294
+
295
+ - **`--all-structures` and `STRUCTURE_BUILD_PLATFORM_CONFIG_V0` do not build.** The `_V0`
296
+ config requires a layer the resolver does not map, and `--all-structures` additionally
297
+ names domain structures that are not part of the governance surface. Compile
298
+ `STRUCTURE_BUILD_PLATFORM_CONFIG_V1` by name.
299
+ - **`PGC_BUILD_ROOT` is inert.** It is accepted and reported, and nothing reads it.
300
+ `PGC_SNAPSHOT_ROOT` is the anchor that controls compiled output.
301
+ - **`PGC_SNAPSHOT_ROOT` carries two meanings** — compiled output to the compiler, assembled
302
+ snapshot to the runtime. Pass `--snapshot` to the runtime rather than relying on it.
303
+ - **`pgc` reports readiness for the platform compile only.** It reads three anchors and
304
+ reports "Ready" once the governance surface resolves; assembly and execution need the
305
+ other three.
306
+
307
+ ## The family
308
+
309
+ | Package | Role |
310
+ |---|---|
311
+ | `pgc-compiler` | declarations → compiled projections |
312
+ | `pgc-assembler` | projections → sealed snapshot |
313
+ | `pgc-runtime` | snapshot → governed execution |
314
+ | `pgc-inspector` | snapshot → read-only inspection |
315
+ | `pgc-transformation` | change request → protocol artifacts |
316
+ | `pgc-governance` | the governance surface and its capability implementations |
317
+ | `pgc-workloads` | the workloads that make conformance observable |
318
+ | `pgc-domains` | the business domain implementations the composed snapshot binds |
319
+
320
+ **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
321
+ internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
322
+ public identity, tagged on every component repository; the platform is at **`v4`**.
323
+
324
+ **The published version follows the public one: `v4` opens at `4.0.0`.** The family releases in
325
+ lockstep, so the composition pins exact versions rather than ranges.
326
+
327
+ A public identity may carry more than one published version. A packaging or distribution defect can
328
+ be corrected in a patch release within the same identity, because such a fix changes what a wheel
329
+ contains and not what the composition determines. A change to what the composition determines takes
330
+ the next public identity, and only that mints a new DOI.
331
+
332
+ `v4` is the second kind. The wheels stopped shipping declarations, which is the first; but an
333
+ identity published by more than one domain now resolves to its authoring copy rather than to
334
+ whichever sorted last, and that changes what the composition answers. A patch release would have
335
+ said otherwise.
336
+
337
+ The standard these packages implement is a separate artifact on its own track, is not this number,
338
+ and is published separately: https://doi.org/10.5281/zenodo.22150616
protocol_governed_computing-4.0.0/protocol_governed_computing.egg-info/requires.txt ADDED
@@ -0,0 +1,11 @@
1
+ pgc-compiler==4.0.0
2
+ pgc-assembler==4.0.0
3
+ pgc-runtime==4.0.0
4
+ pgc-inspector==4.0.0
5
+ pgc-transformation==4.0.0
6
+ pgc-governance==4.0.0
7
+ pgc-workloads==4.0.0
8
+ pgc-domains==4.0.0
9
+
10
+ [blockchain]
11
+ pgc-domains[blockchain]==4.0.0
{protocol_governed_computing-3.0.0 → protocol_governed_computing-4.0.0}/pyproject.toml RENAMED
@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
7
7
  # composition takes the full project name. The import package and the console script are unaffected:
8
8
  # a user still runs `pgc`.
9
9
  name = "protocol-governed-computing"
10
- version = "3.0.0"
10
+ version = "4.0.0"
11
11
  description = "Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.10"
@@ -28,20 +28,20 @@ classifiers = [
28
28
  # the repos release together and the governance closure forces lockstep, so a
29
29
  # mixed-version install is not a supported configuration.
30
30
  dependencies = [
31
- "pgc-compiler==3.0.0",
32
- "pgc-assembler==3.0.0",
33
- "pgc-runtime==3.0.0",
34
- "pgc-inspector==3.0.0",
35
- "pgc-transformation==3.0.0",
36
- "pgc-governance==3.0.0",
37
- "pgc-workloads==3.0.0",
38
- "pgc-domains==3.0.0",
31
+ "pgc-compiler==4.0.0",
32
+ "pgc-assembler==4.0.0",
33
+ "pgc-runtime==4.0.0",
34
+ "pgc-inspector==4.0.0",
35
+ "pgc-transformation==4.0.0",
36
+ "pgc-governance==4.0.0",
37
+ "pgc-workloads==4.0.0",
38
+ "pgc-domains==4.0.0",
39
39
  ]
40
40
 
41
41
  # The blockchain domain's capability transforms need Keccak-256, which is optional in pgc-domains
42
42
  # for the same reason it is optional there: the core compile path imports none of it.
43
43
  [project.optional-dependencies]
44
- blockchain = ["pgc-domains[blockchain]==3.0.0"]
44
+ blockchain = ["pgc-domains[blockchain]==4.0.0"]
45
45
 
46
46
  [project.scripts]
47
47
  pgc = "pgc.cli:main"
protocol_governed_computing-3.0.0/PKG-INFO DELETED
@@ -1,83 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: protocol-governed-computing
3
- Version: 3.0.0
4
- Summary: Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute
5
- Author-email: Bhash Ganti <bachipeachy@gmail.com>
6
- License-Expression: Apache-2.0
7
- Project-URL: Homepage, https://omnibachi.org/
8
- Project-URL: Repository, https://github.com/protocol-governed-computing
9
- Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
10
- Keywords: protocol-governed-computing,pgc,governance,authorization,sdlc
11
- Classifier: Development Status :: 4 - Beta
12
- Classifier: Intended Audience :: Developers
13
- Classifier: Programming Language :: Python :: 3
14
- Classifier: Operating System :: OS Independent
15
- Classifier: Topic :: Software Development :: Compilers
16
- Requires-Python: >=3.10
17
- Description-Content-Type: text/markdown
18
- Requires-Dist: pgc-compiler==3.0.0
19
- Requires-Dist: pgc-assembler==3.0.0
20
- Requires-Dist: pgc-runtime==3.0.0
21
- Requires-Dist: pgc-inspector==3.0.0
22
- Requires-Dist: pgc-transformation==3.0.0
23
- Requires-Dist: pgc-governance==3.0.0
24
- Requires-Dist: pgc-workloads==3.0.0
25
- Requires-Dist: pgc-domains==3.0.0
26
- Provides-Extra: blockchain
27
- Requires-Dist: pgc-domains[blockchain]==3.0.0; extra == "blockchain"
28
-
29
- # pgc_install
30
-
31
- **Protocol-Governed Computing — the whole toolchain in one install.**
32
-
33
- This repository publishes the `protocol-governed-computing` distribution. PyPI prohibits the
34
- short name `pgc`, so the composition carries the full project name; the command it installs is
35
- still `pgc`. It is the composition as *installable
36
- software*, the counterpart to `pgc_release`, which is the same composition as *sealed
37
- evidence* — assembled, immutable, and cited by DOI. The parallel is in role, not in citation:
38
- a release is a thing a paper points at; an install is a thing that changes each version.
39
-
40
- ```bash
41
- pip install protocol-governed-computing
42
- ```
43
-
44
- That brings in the eight component packages of the family, pinned to one composition, and puts
45
- `pgc` on the path.
46
-
47
- ## Two steps, not one
48
-
49
- Installing the toolchain is half of a working environment. The compiler resolves the
50
- governance surface from `PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, zero
51
- inference — so the **declarations come from a repository you point at, not from a
52
- wheel**. A registry inside a package would be a second governance surface competing
53
- with the repository's, and a build could then be governed by a stale copy.
54
-
55
- ```bash
56
- git clone https://github.com/protocol-governed-computing/software_governance
57
- export PGC_PLATFORM_ROOT=$PWD/software_governance
58
- pgc # reports what is installed and whether the anchor resolves
59
- ```
60
-
61
- ## The family
62
-
63
- | Package | Role |
64
- |---|---|
65
- | `pgc-compiler` | declarations → compiled projections |
66
- | `pgc-assembler` | projections → sealed snapshot |
67
- | `pgc-runtime` | snapshot → governed execution |
68
- | `pgc-inspector` | snapshot → read-only inspection |
69
- | `pgc-transformation` | change request → protocol artifacts |
70
- | `pgc-governance` | the governance surface and its capability implementations |
71
- | `pgc-workloads` | the workloads that make conformance observable |
72
- | `pgc-domains` | the business domain implementations the composed snapshot binds |
73
-
74
- **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
75
- internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
76
- public identity, tagged on every component repository; the platform is at **`v3`**.
77
-
78
- **The published version is the public one: `v3` is `3.0.0`.** The family releases in lockstep, so the
79
- composition pins exact versions rather than ranges. The standard these packages implement is a separate artifact on
80
- its own track and is not this number.
81
-
82
- The standard these packages implement is published separately:
83
- https://doi.org/10.5281/zenodo.22150616
protocol_governed_computing-3.0.0/README.md DELETED
@@ -1,55 +0,0 @@
1
- # pgc_install
2
-
3
- **Protocol-Governed Computing — the whole toolchain in one install.**
4
-
5
- This repository publishes the `protocol-governed-computing` distribution. PyPI prohibits the
6
- short name `pgc`, so the composition carries the full project name; the command it installs is
7
- still `pgc`. It is the composition as *installable
8
- software*, the counterpart to `pgc_release`, which is the same composition as *sealed
9
- evidence* — assembled, immutable, and cited by DOI. The parallel is in role, not in citation:
10
- a release is a thing a paper points at; an install is a thing that changes each version.
11
-
12
- ```bash
13
- pip install protocol-governed-computing
14
- ```
15
-
16
- That brings in the eight component packages of the family, pinned to one composition, and puts
17
- `pgc` on the path.
18
-
19
- ## Two steps, not one
20
-
21
- Installing the toolchain is half of a working environment. The compiler resolves the
22
- governance surface from `PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, zero
23
- inference — so the **declarations come from a repository you point at, not from a
24
- wheel**. A registry inside a package would be a second governance surface competing
25
- with the repository's, and a build could then be governed by a stale copy.
26
-
27
- ```bash
28
- git clone https://github.com/protocol-governed-computing/software_governance
29
- export PGC_PLATFORM_ROOT=$PWD/software_governance
30
- pgc # reports what is installed and whether the anchor resolves
31
- ```
32
-
33
- ## The family
34
-
35
- | Package | Role |
36
- |---|---|
37
- | `pgc-compiler` | declarations → compiled projections |
38
- | `pgc-assembler` | projections → sealed snapshot |
39
- | `pgc-runtime` | snapshot → governed execution |
40
- | `pgc-inspector` | snapshot → read-only inspection |
41
- | `pgc-transformation` | change request → protocol artifacts |
42
- | `pgc-governance` | the governance surface and its capability implementations |
43
- | `pgc-workloads` | the workloads that make conformance observable |
44
- | `pgc-domains` | the business domain implementations the composed snapshot binds |
45
-
46
- **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
47
- internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
48
- public identity, tagged on every component repository; the platform is at **`v3`**.
49
-
50
- **The published version is the public one: `v3` is `3.0.0`.** The family releases in lockstep, so the
51
- composition pins exact versions rather than ranges. The standard these packages implement is a separate artifact on
52
- its own track and is not this number.
53
-
54
- The standard these packages implement is published separately:
55
- https://doi.org/10.5281/zenodo.22150616
protocol_governed_computing-3.0.0/protocol_governed_computing.egg-info/PKG-INFO DELETED
@@ -1,83 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: protocol-governed-computing
3
- Version: 3.0.0
4
- Summary: Protocol-Governed Computing — installs the full toolchain and reports whether an environment is ready to compile, seal, and execute
5
- Author-email: Bhash Ganti <bachipeachy@gmail.com>
6
- License-Expression: Apache-2.0
7
- Project-URL: Homepage, https://omnibachi.org/
8
- Project-URL: Repository, https://github.com/protocol-governed-computing
9
- Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
10
- Keywords: protocol-governed-computing,pgc,governance,authorization,sdlc
11
- Classifier: Development Status :: 4 - Beta
12
- Classifier: Intended Audience :: Developers
13
- Classifier: Programming Language :: Python :: 3
14
- Classifier: Operating System :: OS Independent
15
- Classifier: Topic :: Software Development :: Compilers
16
- Requires-Python: >=3.10
17
- Description-Content-Type: text/markdown
18
- Requires-Dist: pgc-compiler==3.0.0
19
- Requires-Dist: pgc-assembler==3.0.0
20
- Requires-Dist: pgc-runtime==3.0.0
21
- Requires-Dist: pgc-inspector==3.0.0
22
- Requires-Dist: pgc-transformation==3.0.0
23
- Requires-Dist: pgc-governance==3.0.0
24
- Requires-Dist: pgc-workloads==3.0.0
25
- Requires-Dist: pgc-domains==3.0.0
26
- Provides-Extra: blockchain
27
- Requires-Dist: pgc-domains[blockchain]==3.0.0; extra == "blockchain"
28
-
29
- # pgc_install
30
-
31
- **Protocol-Governed Computing — the whole toolchain in one install.**
32
-
33
- This repository publishes the `protocol-governed-computing` distribution. PyPI prohibits the
34
- short name `pgc`, so the composition carries the full project name; the command it installs is
35
- still `pgc`. It is the composition as *installable
36
- software*, the counterpart to `pgc_release`, which is the same composition as *sealed
37
- evidence* — assembled, immutable, and cited by DOI. The parallel is in role, not in citation:
38
- a release is a thing a paper points at; an install is a thing that changes each version.
39
-
40
- ```bash
41
- pip install protocol-governed-computing
42
- ```
43
-
44
- That brings in the eight component packages of the family, pinned to one composition, and puts
45
- `pgc` on the path.
46
-
47
- ## Two steps, not one
48
-
49
- Installing the toolchain is half of a working environment. The compiler resolves the
50
- governance surface from `PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, zero
51
- inference — so the **declarations come from a repository you point at, not from a
52
- wheel**. A registry inside a package would be a second governance surface competing
53
- with the repository's, and a build could then be governed by a stale copy.
54
-
55
- ```bash
56
- git clone https://github.com/protocol-governed-computing/software_governance
57
- export PGC_PLATFORM_ROOT=$PWD/software_governance
58
- pgc # reports what is installed and whether the anchor resolves
59
- ```
60
-
61
- ## The family
62
-
63
- | Package | Role |
64
- |---|---|
65
- | `pgc-compiler` | declarations → compiled projections |
66
- | `pgc-assembler` | projections → sealed snapshot |
67
- | `pgc-runtime` | snapshot → governed execution |
68
- | `pgc-inspector` | snapshot → read-only inspection |
69
- | `pgc-transformation` | change request → protocol artifacts |
70
- | `pgc-governance` | the governance surface and its capability implementations |
71
- | `pgc-workloads` | the workloads that make conformance observable |
72
- | `pgc-domains` | the business domain implementations the composed snapshot binds |
73
-
74
- **Versioning.** Two schemes. Each repository's `VERSION` is a monotonic composition ordinal —
75
- internal build accounting, tagged `release-<N>`, never published. `PUBLIC_VERSION` is the platform's
76
- public identity, tagged on every component repository; the platform is at **`v3`**.
77
-
78
- **The published version is the public one: `v3` is `3.0.0`.** The family releases in lockstep, so the
79
- composition pins exact versions rather than ranges. The standard these packages implement is a separate artifact on
80
- its own track and is not this number.
81
-
82
- The standard these packages implement is published separately:
83
- https://doi.org/10.5281/zenodo.22150616
protocol_governed_computing-3.0.0/protocol_governed_computing.egg-info/requires.txt DELETED
@@ -1,11 +0,0 @@
1
- pgc-compiler==3.0.0
2
- pgc-assembler==3.0.0
3
- pgc-runtime==3.0.0
4
- pgc-inspector==3.0.0
5
- pgc-transformation==3.0.0
6
- pgc-governance==3.0.0
7
- pgc-workloads==3.0.0
8
- pgc-domains==3.0.0
9
-
10
- [blockchain]
11
- pgc-domains[blockchain]==3.0.0