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.
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/NOTICE +1 -1
- {pgc_runtime-4.0.0/pgc_runtime.egg-info → pgc_runtime-6.0.0}/PKG-INFO +57 -29
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/README.md +54 -28
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0/pgc_runtime.egg-info}/PKG-INFO +57 -29
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/SOURCES.txt +9 -4
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/requires.txt +3 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pyproject.toml +4 -1
- pgc_runtime-6.0.0/runtime/api.py +176 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/boot.py +39 -3
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/cli.py +136 -15
- pgc_runtime-6.0.0/runtime/conformance.py +385 -0
- pgc_runtime-6.0.0/runtime/coordinator.py +184 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/ct_execute.py +6 -13
- pgc_runtime-6.0.0/runtime/ct_executor.py +436 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/dispatcher.py +209 -90
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/evidence.py +78 -9
- pgc_runtime-6.0.0/runtime/examine/__init__.py +49 -0
- pgc_runtime-6.0.0/runtime/examine/parser.py +72 -0
- pgc_runtime-6.0.0/runtime/examine/reporter.py +57 -0
- pgc_runtime-6.0.0/runtime/federation/__init__.py +16 -0
- pgc_runtime-6.0.0/runtime/federation/client.py +106 -0
- pgc_runtime-6.0.0/runtime/federation/coordinator.py +106 -0
- pgc_runtime-6.0.0/runtime/federation/defaults.py +22 -0
- pgc_runtime-6.0.0/runtime/federation/store.py +85 -0
- pgc_runtime-6.0.0/runtime/federation/worker.py +72 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/loader.py +27 -32
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/memory.py +40 -23
- pgc_runtime-6.0.0/runtime/replay.py +77 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/scheduler.py +62 -35
- pgc_runtime-6.0.0/runtime/trace_viz.py +233 -0
- pgc_runtime-4.0.0/runtime/api.py +0 -71
- pgc_runtime-4.0.0/runtime/conformance.py +0 -249
- pgc_runtime-4.0.0/runtime/ct_executor.py +0 -360
- pgc_runtime-4.0.0/runtime/examine/__init__.py +0 -126
- pgc_runtime-4.0.0/runtime/examine/classifier.py +0 -350
- pgc_runtime-4.0.0/runtime/examine/hint_engine.py +0 -245
- pgc_runtime-4.0.0/runtime/examine/locator.py +0 -148
- pgc_runtime-4.0.0/runtime/examine/parser.py +0 -223
- pgc_runtime-4.0.0/runtime/examine/reporter.py +0 -110
- pgc_runtime-4.0.0/runtime/trace_viz.py +0 -276
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/LICENSE +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/MANIFEST.in +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/dependency_links.txt +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/entry_points.txt +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/pgc_runtime.egg-info/top_level.txt +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/__init__.py +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/ct_errors.py +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/runtime/examine/cli.py +0 -0
- {pgc_runtime-4.0.0 → pgc_runtime-6.0.0}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pgc-runtime
|
|
3
|
-
Version:
|
|
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
|
|
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>.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
data
|
|
90
|
-
|
|
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
|
|
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
|
-
| `
|
|
111
|
-
| `
|
|
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` | `
|
|
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. `
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
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
|
|
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
|
|
207
|
+
**Versioning.** Two numbers name two different things.
|
|
181
208
|
|
|
182
|
-
- **
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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
|
-
|
|
189
|
-
|
|
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
|
|
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>.
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
data
|
|
64
|
-
|
|
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
|
|
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
|
-
| `
|
|
85
|
-
| `
|
|
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` | `
|
|
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. `
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
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
|
|
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
|
|
179
|
+
**Versioning.** Two numbers name two different things.
|
|
155
180
|
|
|
156
|
-
- **
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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
|
-
|
|
163
|
-
|
|
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:
|
|
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
|
|
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>.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
data
|
|
90
|
-
|
|
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
|
|
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
|
-
| `
|
|
111
|
-
| `
|
|
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` | `
|
|
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. `
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
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
|
|
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
|
|
207
|
+
**Versioning.** Two numbers name two different things.
|
|
181
208
|
|
|
182
|
-
- **
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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
|
-
|
|
189
|
-
|
|
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
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "pgc-runtime"
|
|
7
|
-
version = "
|
|
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"
|