pgc-runtime 4.0.0__tar.gz → 6.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 (49) hide show
  1. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/NOTICE +1 -1
  2. {pgc_runtime-4.0.0/pgc_runtime.egg-info → pgc_runtime-6.0.0}/PKG-INFO +57 -29
  3. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/README.md +54 -28
  4. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0/pgc_runtime.egg-info}/PKG-INFO +57 -29
  5. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/SOURCES.txt +9 -4
  6. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/requires.txt +3 -0
  7. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pyproject.toml +4 -1
  8. pgc_runtime-6.0.0/runtime/api.py +176 -0
  9. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/boot.py +39 -3
  10. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/cli.py +136 -15
  11. pgc_runtime-6.0.0/runtime/conformance.py +385 -0
  12. pgc_runtime-6.0.0/runtime/coordinator.py +184 -0
  13. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/ct_execute.py +6 -13
  14. pgc_runtime-6.0.0/runtime/ct_executor.py +436 -0
  15. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/dispatcher.py +209 -90
  16. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/evidence.py +78 -9
  17. pgc_runtime-6.0.0/runtime/examine/__init__.py +49 -0
  18. pgc_runtime-6.0.0/runtime/examine/parser.py +72 -0
  19. pgc_runtime-6.0.0/runtime/examine/reporter.py +57 -0
  20. pgc_runtime-6.0.0/runtime/federation/__init__.py +16 -0
  21. pgc_runtime-6.0.0/runtime/federation/client.py +106 -0
  22. pgc_runtime-6.0.0/runtime/federation/coordinator.py +106 -0
  23. pgc_runtime-6.0.0/runtime/federation/defaults.py +22 -0
  24. pgc_runtime-6.0.0/runtime/federation/store.py +85 -0
  25. pgc_runtime-6.0.0/runtime/federation/worker.py +72 -0
  26. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/loader.py +27 -32
  27. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/memory.py +40 -23
  28. pgc_runtime-6.0.0/runtime/replay.py +77 -0
  29. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/scheduler.py +62 -35
  30. pgc_runtime-6.0.0/runtime/trace_viz.py +233 -0
  31. pgc_runtime-4.0.0/runtime/api.py +0 -71
  32. pgc_runtime-4.0.0/runtime/conformance.py +0 -249
  33. pgc_runtime-4.0.0/runtime/ct_executor.py +0 -360
  34. pgc_runtime-4.0.0/runtime/examine/__init__.py +0 -126
  35. pgc_runtime-4.0.0/runtime/examine/classifier.py +0 -350
  36. pgc_runtime-4.0.0/runtime/examine/hint_engine.py +0 -245
  37. pgc_runtime-4.0.0/runtime/examine/locator.py +0 -148
  38. pgc_runtime-4.0.0/runtime/examine/parser.py +0 -223
  39. pgc_runtime-4.0.0/runtime/examine/reporter.py +0 -110
  40. pgc_runtime-4.0.0/runtime/trace_viz.py +0 -276
  41. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/LICENSE +0 -0
  42. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/MANIFEST.in +0 -0
  43. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/dependency_links.txt +0 -0
  44. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/entry_points.txt +0 -0
  45. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/top_level.txt +0 -0
  46. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/__init__.py +0 -0
  47. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/ct_errors.py +0 -0
  48. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/examine/cli.py +0 -0
  49. {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/setup.cfg +0 -0
@@ -1,4 +1,4 @@
1
- PGS — Protocol-Governed Systems
1
+ PGC — Protocol-Governed Computing
2
2
  Copyright 2026 Bhash Ganti aka Bachi
3
3
 
4
4
  This project introduces a protocol-first execution model in which:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pgc-runtime
3
- Version: 4.0.0
3
+ Version: 6.0.0
4
4
  Summary: PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)
5
5
  Author-email: Bhash Ganti <bachipeachy@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -22,6 +22,8 @@ License-File: LICENSE
22
22
  License-File: NOTICE
23
23
  Provides-Extra: reference
24
24
  Requires-Dist: pgc-governance>=2.0.0; extra == "reference"
25
+ Provides-Extra: render
26
+ Requires-Dist: pgc-inspector>=6.0.0; extra == "render"
25
27
  Dynamic: license-file
26
28
 
27
29
  # protocol_runtime
@@ -78,17 +80,17 @@ payload external input (JSON)
78
80
  data-root the state storage boundary; one data root is one instance
79
81
  ```
80
82
 
81
- A run writes an append-only trace alongside the state its declared side effects produce:
83
+ A run writes an append-only trace beside the state its declared side effects produce, both under
84
+ the data root:
82
85
 
83
86
  ```
84
- traces/<TRACE_ID>/
85
- <TRACE_ID>.jsonl append-only execution log
86
- <TRACE_ID>.md human-readable summary
87
- <TRACE_ID>.png the execution path, rendered
88
-
89
- data/
90
- registry/ idempotent state
91
- events/ append-only history
87
+ <data-root>/traces/<domain>/<WF>/<TRACE_ID>/
88
+ <TRACE_ID>.jsonl append-only execution log, one SCHEMA_TRACE_EVENT_V0 event per line
89
+ <TRACE_ID>.png the path the run took, drawn only on request (`run --behavior-logic`,
90
+ or `behavior-logic <trace>`)
91
+
92
+ <data-root>/<domain>/<subdomain>/
93
+ the stores the domain's runtime binding declares
92
94
  ```
93
95
 
94
96
  ## Running
@@ -100,15 +102,18 @@ data/
100
102
  ./run.sh examine /abs/trace.jsonl
101
103
  ```
102
104
 
103
- `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
104
- subcommands:
105
+ `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script:
105
106
 
106
107
  | command | what it does |
107
108
  |---|---|
108
109
  | `run` | execute a workflow against a data root |
110
+ | `replay` | re-execute a run from its recorded outcomes and compare it with the original |
111
+ | `conformance` | run a compiled domain's test vectors; report each transform proven, unproven or refused |
109
112
  | `boot` | warm-boot the assembled snapshot — load and hash-verify every manifest domain |
110
- | `examine` | analyze a completed trace file |
111
- | `behavior-logic` | render the execution path from a completed trace as a PNG |
113
+ | `coordinator` | serve as the coordinating node of a federated node group |
114
+ | `worker` | serve as a worker node of a federated node group |
115
+ | `examine` | read a completed trace: its path by node, contracts, results, events and errors |
116
+ | `behavior-logic` | render a completed trace as a PNG: the path, each route's outcome, and why each node decided as far as the trace records it (drawn from the inspector's `si.execution.explain`; needs `pgc-runtime[render]`) |
112
117
 
113
118
  `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
114
119
  roots on `PYTHONPATH` for domain capability implementations.
@@ -117,6 +122,12 @@ roots on `PYTHONPATH` for domain capability implementations.
117
122
  establishes that the snapshot is intact and executable before any workflow runs. A surface-only
118
123
  snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
119
124
 
125
+ **A process verifies a snapshot once.** `runtime.api` keeps a booted snapshot resident and runs
126
+ against it as often as it is asked. A rewritten manifest, or a different trust anchor or profile
127
+ root, is verified afresh, and a snapshot that no longer verifies is refused. `boot` itself always
128
+ performs the full determination. A governed run then costs a few milliseconds, not a third of a
129
+ second.
130
+
120
131
  **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
121
132
  independent instances of the same governed behavior.
122
133
 
@@ -128,6 +139,21 @@ invoking transforms, applying side effects — and routes on the declared outcom
128
139
  nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
129
140
  on those.
130
141
 
142
+ **A workflow may run one contract at several places.** Each place is a node key, and the contract
143
+ it runs is named separately. The compiler seals each place's routing on its own, and refuses a sealed
144
+ dispatch that does not realize every transition declared at that node. Routing is by node, and the
145
+ trace names the place that ran.
146
+
147
+ **Not every step is determined by its inputs.** A transform is a deterministic atom, a
148
+ non-deterministic atom, or a molecule, and a different constitution governs each. A molecule has no
149
+ implementation: the runtime runs its declared steps. A non-deterministic atom's result is recorded
150
+ where it is produced, and `replay` substitutes the recorded result, so a run is reproducible even
151
+ when a step is not.
152
+
153
+ **One snapshot can run across nodes.** Under a federated placement, a coordinator schedules units of
154
+ work to workers over a shared store. Under the signed federated profile, every node verifies the
155
+ snapshot's signature before it runs anything.
156
+
131
157
  Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
132
158
  the path actually taken through a graph that was fixed before the run began, which is what makes a
133
159
  run reproducible and reviewable after the fact.
@@ -146,7 +172,7 @@ Apache-2.0. See `LICENSE` and `NOTICE`.
146
172
  | `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
147
173
  | `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
148
174
  | `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
149
- | `pgc-transformation` | `transformation` | change request → protocol artifacts |
175
+ | `pgc-transformation` | `transformation_compilers` | change request → protocol artifacts |
150
176
  | `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
151
177
  | `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
152
178
  | `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
@@ -166,26 +192,28 @@ pgc # reports what is installed and whether the anchor resolves
166
192
 
167
193
  `PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
168
194
  directory that *directly contains* it, not the repository above it; pointing one level too high is a
169
- silent no-op. `PGC_SNAPSHOT_ROOT` is where compiled output is written, and each domain build needs
170
- its own: every layer's output consolidates into one root, and verification rejects any file in that
171
- root the current build did not declare. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot
172
- profiles, required by the assembler and the runtime alike.
195
+ silent no-op. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot profiles, required by the
196
+ assembler and the runtime alike.
197
+
198
+ **Where a build writes is declared, not supplied.** Each build configuration names its root in
199
+ `output_configuration.root`, and every layer's output consolidates there. The compiler does not read
200
+ `PGC_SNAPSHOT_ROOT`; the runtime does, with its own meaning — the assembled snapshot to execute.
173
201
 
174
- `PGC_BUILD_ROOT` is accepted and reported and **nothing reads it** — `PGC_SNAPSHOT_ROOT` is the
175
- anchor that controls output.
202
+ `PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
176
203
 
177
204
  The full sequence, with the repositories it needs, is in
178
205
  [`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
179
206
 
180
- **Versioning.** Two schemes, and the published version follows the second.
207
+ **Versioning.** Two numbers name two different things.
181
208
 
182
- - **Internal** — each repository's `VERSION` file, a monotonic composition ordinal. PGC versions the
183
- composition rather than each repo: they release together and the governance closure forces lockstep,
184
- so the ordinal names which composition a repo belongs to. Development happens on `dev/<N>` and each
185
- cycle is tagged `release-<N>`. This is not published.
186
- - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
209
+ - **Published** — this distribution's `version` in `pyproject.toml`. It moves on its own. A release
210
+ that changes this repository bumps it, and a release that leaves the repository unchanged keeps it.
211
+ - **Composition** — the public identity (`v6`, …) names one composition of the whole family.
212
+ `pgc_release` records which version of each distribution that composition holds, and `pgc_install`
213
+ pins exactly those versions.
187
214
 
188
- **The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
189
- separate artifact on its own track and is not this number.
215
+ Each repository's `VERSION` file holds the workspace's cycle ordinal, which names the `dev/<N>`
216
+ branch. It is development accounting, and it is never published. The standard the packages
217
+ implement is a separate artifact on its own track, and none of these numbers is its revision.
190
218
 
191
219
  The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616
@@ -52,17 +52,17 @@ payload external input (JSON)
52
52
  data-root the state storage boundary; one data root is one instance
53
53
  ```
54
54
 
55
- A run writes an append-only trace alongside the state its declared side effects produce:
55
+ A run writes an append-only trace beside the state its declared side effects produce, both under
56
+ the data root:
56
57
 
57
58
  ```
58
- traces/<TRACE_ID>/
59
- <TRACE_ID>.jsonl append-only execution log
60
- <TRACE_ID>.md human-readable summary
61
- <TRACE_ID>.png the execution path, rendered
62
-
63
- data/
64
- registry/ idempotent state
65
- events/ append-only history
59
+ <data-root>/traces/<domain>/<WF>/<TRACE_ID>/
60
+ <TRACE_ID>.jsonl append-only execution log, one SCHEMA_TRACE_EVENT_V0 event per line
61
+ <TRACE_ID>.png the path the run took, drawn only on request (`run --behavior-logic`,
62
+ or `behavior-logic <trace>`)
63
+
64
+ <data-root>/<domain>/<subdomain>/
65
+ the stores the domain's runtime binding declares
66
66
  ```
67
67
 
68
68
  ## Running
@@ -74,15 +74,18 @@ data/
74
74
  ./run.sh examine /abs/trace.jsonl
75
75
  ```
76
76
 
77
- `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
78
- subcommands:
77
+ `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script:
79
78
 
80
79
  | command | what it does |
81
80
  |---|---|
82
81
  | `run` | execute a workflow against a data root |
82
+ | `replay` | re-execute a run from its recorded outcomes and compare it with the original |
83
+ | `conformance` | run a compiled domain's test vectors; report each transform proven, unproven or refused |
83
84
  | `boot` | warm-boot the assembled snapshot — load and hash-verify every manifest domain |
84
- | `examine` | analyze a completed trace file |
85
- | `behavior-logic` | render the execution path from a completed trace as a PNG |
85
+ | `coordinator` | serve as the coordinating node of a federated node group |
86
+ | `worker` | serve as a worker node of a federated node group |
87
+ | `examine` | read a completed trace: its path by node, contracts, results, events and errors |
88
+ | `behavior-logic` | render a completed trace as a PNG: the path, each route's outcome, and why each node decided as far as the trace records it (drawn from the inspector's `si.execution.explain`; needs `pgc-runtime[render]`) |
86
89
 
87
90
  `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
88
91
  roots on `PYTHONPATH` for domain capability implementations.
@@ -91,6 +94,12 @@ roots on `PYTHONPATH` for domain capability implementations.
91
94
  establishes that the snapshot is intact and executable before any workflow runs. A surface-only
92
95
  snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
93
96
 
97
+ **A process verifies a snapshot once.** `runtime.api` keeps a booted snapshot resident and runs
98
+ against it as often as it is asked. A rewritten manifest, or a different trust anchor or profile
99
+ root, is verified afresh, and a snapshot that no longer verifies is refused. `boot` itself always
100
+ performs the full determination. A governed run then costs a few milliseconds, not a third of a
101
+ second.
102
+
94
103
  **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
95
104
  independent instances of the same governed behavior.
96
105
 
@@ -102,6 +111,21 @@ invoking transforms, applying side effects — and routes on the declared outcom
102
111
  nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
103
112
  on those.
104
113
 
114
+ **A workflow may run one contract at several places.** Each place is a node key, and the contract
115
+ it runs is named separately. The compiler seals each place's routing on its own, and refuses a sealed
116
+ dispatch that does not realize every transition declared at that node. Routing is by node, and the
117
+ trace names the place that ran.
118
+
119
+ **Not every step is determined by its inputs.** A transform is a deterministic atom, a
120
+ non-deterministic atom, or a molecule, and a different constitution governs each. A molecule has no
121
+ implementation: the runtime runs its declared steps. A non-deterministic atom's result is recorded
122
+ where it is produced, and `replay` substitutes the recorded result, so a run is reproducible even
123
+ when a step is not.
124
+
125
+ **One snapshot can run across nodes.** Under a federated placement, a coordinator schedules units of
126
+ work to workers over a shared store. Under the signed federated profile, every node verifies the
127
+ snapshot's signature before it runs anything.
128
+
105
129
  Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
106
130
  the path actually taken through a graph that was fixed before the run began, which is what makes a
107
131
  run reproducible and reviewable after the fact.
@@ -120,7 +144,7 @@ Apache-2.0. See `LICENSE` and `NOTICE`.
120
144
  | `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
121
145
  | `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
122
146
  | `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
123
- | `pgc-transformation` | `transformation` | change request → protocol artifacts |
147
+ | `pgc-transformation` | `transformation_compilers` | change request → protocol artifacts |
124
148
  | `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
125
149
  | `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
126
150
  | `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
@@ -140,26 +164,28 @@ pgc # reports what is installed and whether the anchor resolves
140
164
 
141
165
  `PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
142
166
  directory that *directly contains* it, not the repository above it; pointing one level too high is a
143
- silent no-op. `PGC_SNAPSHOT_ROOT` is where compiled output is written, and each domain build needs
144
- its own: every layer's output consolidates into one root, and verification rejects any file in that
145
- root the current build did not declare. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot
146
- profiles, required by the assembler and the runtime alike.
167
+ silent no-op. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot profiles, required by the
168
+ assembler and the runtime alike.
169
+
170
+ **Where a build writes is declared, not supplied.** Each build configuration names its root in
171
+ `output_configuration.root`, and every layer's output consolidates there. The compiler does not read
172
+ `PGC_SNAPSHOT_ROOT`; the runtime does, with its own meaning — the assembled snapshot to execute.
147
173
 
148
- `PGC_BUILD_ROOT` is accepted and reported and **nothing reads it** — `PGC_SNAPSHOT_ROOT` is the
149
- anchor that controls output.
174
+ `PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
150
175
 
151
176
  The full sequence, with the repositories it needs, is in
152
177
  [`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
153
178
 
154
- **Versioning.** Two schemes, and the published version follows the second.
179
+ **Versioning.** Two numbers name two different things.
155
180
 
156
- - **Internal** — each repository's `VERSION` file, a monotonic composition ordinal. PGC versions the
157
- composition rather than each repo: they release together and the governance closure forces lockstep,
158
- so the ordinal names which composition a repo belongs to. Development happens on `dev/<N>` and each
159
- cycle is tagged `release-<N>`. This is not published.
160
- - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
181
+ - **Published** — this distribution's `version` in `pyproject.toml`. It moves on its own. A release
182
+ that changes this repository bumps it, and a release that leaves the repository unchanged keeps it.
183
+ - **Composition** — the public identity (`v6`, …) names one composition of the whole family.
184
+ `pgc_release` records which version of each distribution that composition holds, and `pgc_install`
185
+ pins exactly those versions.
161
186
 
162
- **The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
163
- separate artifact on its own track and is not this number.
187
+ Each repository's `VERSION` file holds the workspace's cycle ordinal, which names the `dev/<N>`
188
+ branch. It is development accounting, and it is never published. The standard the packages
189
+ implement is a separate artifact on its own track, and none of these numbers is its revision.
164
190
 
165
191
  The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pgc-runtime
3
- Version: 4.0.0
3
+ Version: 6.0.0
4
4
  Summary: PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)
5
5
  Author-email: Bhash Ganti <bachipeachy@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -22,6 +22,8 @@ License-File: LICENSE
22
22
  License-File: NOTICE
23
23
  Provides-Extra: reference
24
24
  Requires-Dist: pgc-governance>=2.0.0; extra == "reference"
25
+ Provides-Extra: render
26
+ Requires-Dist: pgc-inspector>=6.0.0; extra == "render"
25
27
  Dynamic: license-file
26
28
 
27
29
  # protocol_runtime
@@ -78,17 +80,17 @@ payload external input (JSON)
78
80
  data-root the state storage boundary; one data root is one instance
79
81
  ```
80
82
 
81
- A run writes an append-only trace alongside the state its declared side effects produce:
83
+ A run writes an append-only trace beside the state its declared side effects produce, both under
84
+ the data root:
82
85
 
83
86
  ```
84
- traces/<TRACE_ID>/
85
- <TRACE_ID>.jsonl append-only execution log
86
- <TRACE_ID>.md human-readable summary
87
- <TRACE_ID>.png the execution path, rendered
88
-
89
- data/
90
- registry/ idempotent state
91
- events/ append-only history
87
+ <data-root>/traces/<domain>/<WF>/<TRACE_ID>/
88
+ <TRACE_ID>.jsonl append-only execution log, one SCHEMA_TRACE_EVENT_V0 event per line
89
+ <TRACE_ID>.png the path the run took, drawn only on request (`run --behavior-logic`,
90
+ or `behavior-logic <trace>`)
91
+
92
+ <data-root>/<domain>/<subdomain>/
93
+ the stores the domain's runtime binding declares
92
94
  ```
93
95
 
94
96
  ## Running
@@ -100,15 +102,18 @@ data/
100
102
  ./run.sh examine /abs/trace.jsonl
101
103
  ```
102
104
 
103
- `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
104
- subcommands:
105
+ `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script:
105
106
 
106
107
  | command | what it does |
107
108
  |---|---|
108
109
  | `run` | execute a workflow against a data root |
110
+ | `replay` | re-execute a run from its recorded outcomes and compare it with the original |
111
+ | `conformance` | run a compiled domain's test vectors; report each transform proven, unproven or refused |
109
112
  | `boot` | warm-boot the assembled snapshot — load and hash-verify every manifest domain |
110
- | `examine` | analyze a completed trace file |
111
- | `behavior-logic` | render the execution path from a completed trace as a PNG |
113
+ | `coordinator` | serve as the coordinating node of a federated node group |
114
+ | `worker` | serve as a worker node of a federated node group |
115
+ | `examine` | read a completed trace: its path by node, contracts, results, events and errors |
116
+ | `behavior-logic` | render a completed trace as a PNG: the path, each route's outcome, and why each node decided as far as the trace records it (drawn from the inspector's `si.execution.explain`; needs `pgc-runtime[render]`) |
112
117
 
113
118
  `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
114
119
  roots on `PYTHONPATH` for domain capability implementations.
@@ -117,6 +122,12 @@ roots on `PYTHONPATH` for domain capability implementations.
117
122
  establishes that the snapshot is intact and executable before any workflow runs. A surface-only
118
123
  snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
119
124
 
125
+ **A process verifies a snapshot once.** `runtime.api` keeps a booted snapshot resident and runs
126
+ against it as often as it is asked. A rewritten manifest, or a different trust anchor or profile
127
+ root, is verified afresh, and a snapshot that no longer verifies is refused. `boot` itself always
128
+ performs the full determination. A governed run then costs a few milliseconds, not a third of a
129
+ second.
130
+
120
131
  **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
121
132
  independent instances of the same governed behavior.
122
133
 
@@ -128,6 +139,21 @@ invoking transforms, applying side effects — and routes on the declared outcom
128
139
  nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
129
140
  on those.
130
141
 
142
+ **A workflow may run one contract at several places.** Each place is a node key, and the contract
143
+ it runs is named separately. The compiler seals each place's routing on its own, and refuses a sealed
144
+ dispatch that does not realize every transition declared at that node. Routing is by node, and the
145
+ trace names the place that ran.
146
+
147
+ **Not every step is determined by its inputs.** A transform is a deterministic atom, a
148
+ non-deterministic atom, or a molecule, and a different constitution governs each. A molecule has no
149
+ implementation: the runtime runs its declared steps. A non-deterministic atom's result is recorded
150
+ where it is produced, and `replay` substitutes the recorded result, so a run is reproducible even
151
+ when a step is not.
152
+
153
+ **One snapshot can run across nodes.** Under a federated placement, a coordinator schedules units of
154
+ work to workers over a shared store. Under the signed federated profile, every node verifies the
155
+ snapshot's signature before it runs anything.
156
+
131
157
  Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
132
158
  the path actually taken through a graph that was fixed before the run began, which is what makes a
133
159
  run reproducible and reviewable after the fact.
@@ -146,7 +172,7 @@ Apache-2.0. See `LICENSE` and `NOTICE`.
146
172
  | `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
147
173
  | `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
148
174
  | `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
149
- | `pgc-transformation` | `transformation` | change request → protocol artifacts |
175
+ | `pgc-transformation` | `transformation_compilers` | change request → protocol artifacts |
150
176
  | `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
151
177
  | `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
152
178
  | `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
@@ -166,26 +192,28 @@ pgc # reports what is installed and whether the anchor resolves
166
192
 
167
193
  `PGC_DOMAIN_ROOTS` names an additional domain contributing its own `registry/structures` — the
168
194
  directory that *directly contains* it, not the repository above it; pointing one level too high is a
169
- silent no-op. `PGC_SNAPSHOT_ROOT` is where compiled output is written, and each domain build needs
170
- its own: every layer's output consolidates into one root, and verification rejects any file in that
171
- root the current build did not declare. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot
172
- profiles, required by the assembler and the runtime alike.
195
+ silent no-op. `PGC_SNAPSHOT_PROFILES` is the directory holding snapshot profiles, required by the
196
+ assembler and the runtime alike.
197
+
198
+ **Where a build writes is declared, not supplied.** Each build configuration names its root in
199
+ `output_configuration.root`, and every layer's output consolidates there. The compiler does not read
200
+ `PGC_SNAPSHOT_ROOT`; the runtime does, with its own meaning — the assembled snapshot to execute.
173
201
 
174
- `PGC_BUILD_ROOT` is accepted and reported and **nothing reads it** — `PGC_SNAPSHOT_ROOT` is the
175
- anchor that controls output.
202
+ `PGC_BUILD_ROOT` is accepted and reported and **nothing reads it**.
176
203
 
177
204
  The full sequence, with the repositories it needs, is in
178
205
  [`pgc_install`](https://github.com/protocol-governed-computing/pgc_install).
179
206
 
180
- **Versioning.** Two schemes, and the published version follows the second.
207
+ **Versioning.** Two numbers name two different things.
181
208
 
182
- - **Internal** — each repository's `VERSION` file, a monotonic composition ordinal. PGC versions the
183
- composition rather than each repo: they release together and the governance closure forces lockstep,
184
- so the ordinal names which composition a repo belongs to. Development happens on `dev/<N>` and each
185
- cycle is tagged `release-<N>`. This is not published.
186
- - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v3`**.
209
+ - **Published** — this distribution's `version` in `pyproject.toml`. It moves on its own. A release
210
+ that changes this repository bumps it, and a release that leaves the repository unchanged keeps it.
211
+ - **Composition** — the public identity (`v6`, …) names one composition of the whole family.
212
+ `pgc_release` records which version of each distribution that composition holds, and `pgc_install`
213
+ pins exactly those versions.
187
214
 
188
- **The published version is the public one: `v4` is `4.0.0`.** The standard the packages implement is a
189
- separate artifact on its own track and is not this number.
215
+ Each repository's `VERSION` file holds the workspace's cycle ordinal, which names the `dev/<N>`
216
+ branch. It is development accounting, and it is never published. The standard the packages
217
+ implement is a separate artifact on its own track, and none of these numbers is its revision.
190
218
 
191
219
  The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616
@@ -14,6 +14,7 @@ runtime/api.py
14
14
  runtime/boot.py
15
15
  runtime/cli.py
16
16
  runtime/conformance.py
17
+ runtime/coordinator.py
17
18
  runtime/ct_errors.py
18
19
  runtime/ct_execute.py
19
20
  runtime/ct_executor.py
@@ -21,12 +22,16 @@ runtime/dispatcher.py
21
22
  runtime/evidence.py
22
23
  runtime/loader.py
23
24
  runtime/memory.py
25
+ runtime/replay.py
24
26
  runtime/scheduler.py
25
27
  runtime/trace_viz.py
26
28
  runtime/examine/__init__.py
27
- runtime/examine/classifier.py
28
29
  runtime/examine/cli.py
29
- runtime/examine/hint_engine.py
30
- runtime/examine/locator.py
31
30
  runtime/examine/parser.py
32
- runtime/examine/reporter.py
31
+ runtime/examine/reporter.py
32
+ runtime/federation/__init__.py
33
+ runtime/federation/client.py
34
+ runtime/federation/coordinator.py
35
+ runtime/federation/defaults.py
36
+ runtime/federation/store.py
37
+ runtime/federation/worker.py
@@ -1,3 +1,6 @@
1
1
 
2
2
  [reference]
3
3
  pgc-governance>=2.0.0
4
+
5
+ [render]
6
+ pgc-inspector>=6.0.0
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pgc-runtime"
7
- version = "4.0.0"
7
+ version = "6.0.0"
8
8
  description = "PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -32,6 +32,9 @@ dependencies = []
32
32
 
33
33
  [project.optional-dependencies]
34
34
  reference = ["pgc-governance>=2.0.0"]
35
+ # The PNG projection (`--behavior-logic`, `behavior-logic`) draws the inspector's explanation of a
36
+ # run. Execution never imports the inspector; only `runtime.trace_viz` does.
37
+ render = ["pgc-inspector>=6.0.0"]
35
38
 
36
39
  [project.scripts]
37
40
  protocol_runtime = "runtime.cli:main"