pgc-runtime 2.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 (34) hide show
  1. pgc_runtime-2.0.0/LICENSE +67 -0
  2. pgc_runtime-2.0.0/MANIFEST.in +8 -0
  3. pgc_runtime-2.0.0/NOTICE +11 -0
  4. pgc_runtime-2.0.0/PKG-INFO +181 -0
  5. pgc_runtime-2.0.0/README.md +155 -0
  6. pgc_runtime-2.0.0/pgc_runtime.egg-info/PKG-INFO +181 -0
  7. pgc_runtime-2.0.0/pgc_runtime.egg-info/SOURCES.txt +32 -0
  8. pgc_runtime-2.0.0/pgc_runtime.egg-info/dependency_links.txt +1 -0
  9. pgc_runtime-2.0.0/pgc_runtime.egg-info/entry_points.txt +2 -0
  10. pgc_runtime-2.0.0/pgc_runtime.egg-info/requires.txt +3 -0
  11. pgc_runtime-2.0.0/pgc_runtime.egg-info/top_level.txt +1 -0
  12. pgc_runtime-2.0.0/pyproject.toml +50 -0
  13. pgc_runtime-2.0.0/runtime/__init__.py +0 -0
  14. pgc_runtime-2.0.0/runtime/api.py +71 -0
  15. pgc_runtime-2.0.0/runtime/boot.py +147 -0
  16. pgc_runtime-2.0.0/runtime/cli.py +387 -0
  17. pgc_runtime-2.0.0/runtime/conformance.py +249 -0
  18. pgc_runtime-2.0.0/runtime/ct_errors.py +33 -0
  19. pgc_runtime-2.0.0/runtime/ct_execute.py +84 -0
  20. pgc_runtime-2.0.0/runtime/ct_executor.py +312 -0
  21. pgc_runtime-2.0.0/runtime/dispatcher.py +448 -0
  22. pgc_runtime-2.0.0/runtime/evidence.py +245 -0
  23. pgc_runtime-2.0.0/runtime/examine/__init__.py +126 -0
  24. pgc_runtime-2.0.0/runtime/examine/classifier.py +350 -0
  25. pgc_runtime-2.0.0/runtime/examine/cli.py +35 -0
  26. pgc_runtime-2.0.0/runtime/examine/hint_engine.py +245 -0
  27. pgc_runtime-2.0.0/runtime/examine/locator.py +148 -0
  28. pgc_runtime-2.0.0/runtime/examine/parser.py +223 -0
  29. pgc_runtime-2.0.0/runtime/examine/reporter.py +110 -0
  30. pgc_runtime-2.0.0/runtime/loader.py +360 -0
  31. pgc_runtime-2.0.0/runtime/memory.py +125 -0
  32. pgc_runtime-2.0.0/runtime/scheduler.py +264 -0
  33. pgc_runtime-2.0.0/runtime/trace_viz.py +276 -0
  34. pgc_runtime-2.0.0/setup.cfg +4 -0
@@ -0,0 +1,67 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ Copyright 2026 Bhash Ganti aka Bachi
6
+
7
+ Licensed under the Apache License, Version 2.0 (the "License");
8
+ you may not use this file except in compliance with the License.
9
+ You may obtain a copy of the License at
10
+
11
+ http://www.apache.org/licenses/LICENSE-2.0
12
+
13
+ Unless required by applicable law or agreed to in writing, software
14
+ distributed under the License is distributed on an "AS IS" BASIS,
15
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
+ See the License for the specific language governing permissions and
17
+ limitations under the License.
18
+
19
+
20
+ ------------------------
21
+ FULL LICENSE TEXT BELOW
22
+ ------------------------
23
+
24
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
25
+
26
+ 1. Definitions.
27
+ "License" shall mean the terms and conditions for use, reproduction,
28
+ and distribution as defined by Sections 1 through 9 of this document.
29
+ "Licensor" shall mean the copyright owner.
30
+ "Legal Entity" shall mean the union of the acting entity and all other
31
+ entities that control, are controlled by, or are under common control.
32
+ "You" shall mean an individual or Legal Entity exercising permissions.
33
+ "Source" form shall mean the preferred form for making modifications.
34
+ "Object" form shall mean any form resulting from mechanical transformation.
35
+ "Work" shall mean the work of authorship.
36
+ "Derivative Works" shall mean any work based on the Work.
37
+ "Contribution" shall mean any work intentionally submitted.
38
+ "Contributor" shall mean Licensor and any individual submitting Contributions.
39
+
40
+ 2. Grant of Copyright License.
41
+ Each Contributor grants You a perpetual, worldwide, non-exclusive,
42
+ no-charge, royalty-free copyright license.
43
+
44
+ 3. Grant of Patent License.
45
+ Each Contributor grants a patent license to make, use, sell, etc.
46
+
47
+ 4. Redistribution.
48
+ You may reproduce and distribute copies provided that:
49
+ - You include a copy of this License
50
+ - You retain notices
51
+ - You state modifications
52
+ - You include NOTICE file if present
53
+
54
+ 5. Submission of Contributions.
55
+ Contributions are under this License unless stated otherwise.
56
+
57
+ 6. Trademarks.
58
+ This License does not grant trademark rights.
59
+
60
+ 7. Disclaimer of Warranty.
61
+ Provided "AS IS", without warranties.
62
+
63
+ 8. Limitation of Liability.
64
+ No liability for damages.
65
+
66
+ 9. Accepting Warranty or Additional Liability.
67
+ You may offer support/warranty on your own behalf only.
@@ -0,0 +1,8 @@
1
+ exclude *.log
2
+ exclude *.jsonl
3
+ exclude *.sh
4
+
5
+ prune scripts
6
+ prune testbed
7
+
8
+ global-exclude __pycache__ *.pyc
@@ -0,0 +1,11 @@
1
+ PGS — Protocol-Governed Systems
2
+ Copyright 2026 Bhash Ganti aka Bachi
3
+
4
+ This project introduces a protocol-first execution model in which:
5
+
6
+ - Behavior is declared in protocol artifacts
7
+ - Execution is performed by a deterministic runtime
8
+ - Capability implementations are bound at compile time
9
+ - Governance is enforced through invariants and assertions
10
+
11
+ Extensibility is achieved by declaration, not refactor.
@@ -0,0 +1,181 @@
1
+ Metadata-Version: 2.4
2
+ Name: pgc-runtime
3
+ Version: 2.0.0
4
+ Summary: PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)
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/protocol_runtime
9
+ Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
10
+ Keywords: protocol-governed-computing,pgc,protocol,runtime,workflow,execution
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Topic :: System :: Distributed Computing
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ License-File: NOTICE
23
+ Provides-Extra: reference
24
+ Requires-Dist: pgc-governance>=2.0.0; extra == "reference"
25
+ Dynamic: license-file
26
+
27
+ # protocol_runtime
28
+
29
+ **Deterministic execution engine for Protocol-Governed Computing** (import package: `runtime`).
30
+
31
+ The runtime traverses a precompiled execution graph and produces traceable, governed outcomes. It
32
+ does not discover behavior, interpret intent, or contain business logic. Everything it will do was
33
+ decided at compile time; execution is a traversal of what the snapshot already says.
34
+
35
+ ## Install
36
+
37
+ ```bash
38
+ pip install pgc-runtime
39
+ ```
40
+
41
+ Once installed:
42
+
43
+ ```bash
44
+ protocol_runtime --help
45
+ ```
46
+
47
+ ## Where it fits
48
+
49
+ ```
50
+ software_governance the normative surface every composition rests on
51
+ conformance_workloads workloads that prove conformance
52
+ business_domains domains built on the surface
53
+
54
+ protocol_compiler source → compiled projections
55
+ snapshot_assembler projections → assembled snapshot
56
+ protocol_runtime snapshot → execution (this repo)
57
+ snapshot_inspector snapshot → inspection
58
+ ```
59
+
60
+ `protocol_transport` governs the boundary at either end of execution — ingress and egress as
61
+ first-class contracts. The runtime consumes only the **assembled** snapshot, never an individual
62
+ repo's compiled layout.
63
+
64
+ ## What it is, and is not
65
+
66
+ **It is** a deterministic graph traverser, a trace generator, and a host for the capability
67
+ implementations a snapshot names.
68
+
69
+ **It is not** a workflow authoring system, a rules engine, a business-logic container, or a
70
+ framework with pluggable behavior. There is no extension point, because an extension point is a
71
+ place where ungoverned behavior could enter.
72
+
73
+ ## Inputs and outputs
74
+
75
+ ```
76
+ snapshot root the assembled snapshot — the sole source of behavior
77
+ payload external input (JSON)
78
+ data-root the state storage boundary; one data root is one instance
79
+ ```
80
+
81
+ A run writes an append-only trace alongside the state its declared side effects produce:
82
+
83
+ ```
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
92
+ ```
93
+
94
+ ## Running
95
+
96
+ ```bash
97
+ ./run.sh # warm-boot the sibling assembled snapshot
98
+ ./run.sh boot --snapshot /abs/snapshot # explicit boot
99
+ ./run.sh run --wf <domain>::WF_… --data-root /abs/instance
100
+ ./run.sh examine /abs/trace.jsonl
101
+ ```
102
+
103
+ `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
104
+ subcommands:
105
+
106
+ | command | what it does |
107
+ |---|---|
108
+ | `run` | execute a workflow against a data root |
109
+ | `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 |
112
+
113
+ `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
114
+ roots on `PYTHONPATH` for domain capability implementations.
115
+
116
+ **Warm reboot is its own proof.** Bringing every manifest domain resident and hash-verified
117
+ establishes that the snapshot is intact and executable before any workflow runs. A surface-only
118
+ snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
119
+
120
+ **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
121
+ independent instances of the same governed behavior.
122
+
123
+ ## How execution works
124
+
125
+ The runtime loads the compiled graph, admits the request against the intent that declares it, and
126
+ walks the workflow node by node. At each node it executes the capability contract's steps —
127
+ invoking transforms, applying side effects — and routes on the declared outcome. It resolves
128
+ nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
129
+ on those.
130
+
131
+ Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
132
+ the path actually taken through a graph that was fixed before the run began, which is what makes a
133
+ run reproducible and reviewable after the fact.
134
+
135
+ ## License
136
+
137
+ Apache-2.0. See `LICENSE` and `NOTICE`.
138
+
139
+ ---
140
+
141
+ ## The package family
142
+
143
+ | Package | Repository | Role |
144
+ |---|---|---|
145
+ | `pgc-compiler` | `protocol_compiler` | declarations → compiled projections |
146
+ | `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
147
+ | `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
148
+ | `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
149
+ | `pgc-transformation` | `transformation` | change request → protocol artifacts |
150
+ | `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
151
+ | `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
152
+ | `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
153
+
154
+ `pip install pgc` brings in the whole family.
155
+
156
+ **Installing the toolchain is one of two steps.** The compiler resolves the governance surface from
157
+ `PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, zero inference — so the *declarations* come from a
158
+ repository you point at, never from a wheel. A registry inside a package would be a second governance
159
+ surface competing with the repository's, and a build could then be governed by a stale copy.
160
+
161
+ ```bash
162
+ git clone https://github.com/protocol-governed-computing/software_governance
163
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
164
+ pgc # reports what is installed and whether the anchor resolves
165
+ ```
166
+
167
+ `PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
168
+ (additional domains contributing their own `registry/structures`) are optional.
169
+
170
+ **Versioning.** Two schemes, and the published version follows the second.
171
+
172
+ - **Internal** — each repository's `VERSION` file, a monotonic composition ordinal. PGC versions the
173
+ composition rather than each repo: they release together and the governance closure forces lockstep,
174
+ so the ordinal names which composition a repo belongs to. Development happens on `dev/<N>` and each
175
+ cycle is tagged `release-<N>`. This is not published.
176
+ - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v2`**.
177
+
178
+ **The published version is the public one: `v2` is `2.0.0`.** The standard the packages implement is a
179
+ separate artifact on its own track and is not this number.
180
+
181
+ The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616
@@ -0,0 +1,155 @@
1
+ # protocol_runtime
2
+
3
+ **Deterministic execution engine for Protocol-Governed Computing** (import package: `runtime`).
4
+
5
+ The runtime traverses a precompiled execution graph and produces traceable, governed outcomes. It
6
+ does not discover behavior, interpret intent, or contain business logic. Everything it will do was
7
+ decided at compile time; execution is a traversal of what the snapshot already says.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pip install pgc-runtime
13
+ ```
14
+
15
+ Once installed:
16
+
17
+ ```bash
18
+ protocol_runtime --help
19
+ ```
20
+
21
+ ## Where it fits
22
+
23
+ ```
24
+ software_governance the normative surface every composition rests on
25
+ conformance_workloads workloads that prove conformance
26
+ business_domains domains built on the surface
27
+
28
+ protocol_compiler source → compiled projections
29
+ snapshot_assembler projections → assembled snapshot
30
+ protocol_runtime snapshot → execution (this repo)
31
+ snapshot_inspector snapshot → inspection
32
+ ```
33
+
34
+ `protocol_transport` governs the boundary at either end of execution — ingress and egress as
35
+ first-class contracts. The runtime consumes only the **assembled** snapshot, never an individual
36
+ repo's compiled layout.
37
+
38
+ ## What it is, and is not
39
+
40
+ **It is** a deterministic graph traverser, a trace generator, and a host for the capability
41
+ implementations a snapshot names.
42
+
43
+ **It is not** a workflow authoring system, a rules engine, a business-logic container, or a
44
+ framework with pluggable behavior. There is no extension point, because an extension point is a
45
+ place where ungoverned behavior could enter.
46
+
47
+ ## Inputs and outputs
48
+
49
+ ```
50
+ snapshot root the assembled snapshot — the sole source of behavior
51
+ payload external input (JSON)
52
+ data-root the state storage boundary; one data root is one instance
53
+ ```
54
+
55
+ A run writes an append-only trace alongside the state its declared side effects produce:
56
+
57
+ ```
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
66
+ ```
67
+
68
+ ## Running
69
+
70
+ ```bash
71
+ ./run.sh # warm-boot the sibling assembled snapshot
72
+ ./run.sh boot --snapshot /abs/snapshot # explicit boot
73
+ ./run.sh run --wf <domain>::WF_… --data-root /abs/instance
74
+ ./run.sh examine /abs/trace.jsonl
75
+ ```
76
+
77
+ `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
78
+ subcommands:
79
+
80
+ | command | what it does |
81
+ |---|---|
82
+ | `run` | execute a workflow against a data root |
83
+ | `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 |
86
+
87
+ `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
88
+ roots on `PYTHONPATH` for domain capability implementations.
89
+
90
+ **Warm reboot is its own proof.** Bringing every manifest domain resident and hash-verified
91
+ establishes that the snapshot is intact and executable before any workflow runs. A surface-only
92
+ snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
93
+
94
+ **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
95
+ independent instances of the same governed behavior.
96
+
97
+ ## How execution works
98
+
99
+ The runtime loads the compiled graph, admits the request against the intent that declares it, and
100
+ walks the workflow node by node. At each node it executes the capability contract's steps —
101
+ invoking transforms, applying side effects — and routes on the declared outcome. It resolves
102
+ nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
103
+ on those.
104
+
105
+ Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
106
+ the path actually taken through a graph that was fixed before the run began, which is what makes a
107
+ run reproducible and reviewable after the fact.
108
+
109
+ ## License
110
+
111
+ Apache-2.0. See `LICENSE` and `NOTICE`.
112
+
113
+ ---
114
+
115
+ ## The package family
116
+
117
+ | Package | Repository | Role |
118
+ |---|---|---|
119
+ | `pgc-compiler` | `protocol_compiler` | declarations → compiled projections |
120
+ | `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
121
+ | `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
122
+ | `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
123
+ | `pgc-transformation` | `transformation` | change request → protocol artifacts |
124
+ | `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
125
+ | `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
126
+ | `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
127
+
128
+ `pip install pgc` brings in the whole family.
129
+
130
+ **Installing the toolchain is one of two steps.** The compiler resolves the governance surface from
131
+ `PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, zero inference — so the *declarations* come from a
132
+ repository you point at, never from a wheel. A registry inside a package would be a second governance
133
+ surface competing with the repository's, and a build could then be governed by a stale copy.
134
+
135
+ ```bash
136
+ git clone https://github.com/protocol-governed-computing/software_governance
137
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
138
+ pgc # reports what is installed and whether the anchor resolves
139
+ ```
140
+
141
+ `PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
142
+ (additional domains contributing their own `registry/structures`) are optional.
143
+
144
+ **Versioning.** Two schemes, and the published version follows the second.
145
+
146
+ - **Internal** — each repository's `VERSION` file, a monotonic composition ordinal. PGC versions the
147
+ composition rather than each repo: they release together and the governance closure forces lockstep,
148
+ so the ordinal names which composition a repo belongs to. Development happens on `dev/<N>` and each
149
+ cycle is tagged `release-<N>`. This is not published.
150
+ - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v2`**.
151
+
152
+ **The published version is the public one: `v2` is `2.0.0`.** The standard the packages implement is a
153
+ separate artifact on its own track and is not this number.
154
+
155
+ The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616
@@ -0,0 +1,181 @@
1
+ Metadata-Version: 2.4
2
+ Name: pgc-runtime
3
+ Version: 2.0.0
4
+ Summary: PGC protocol runtime — executes a sealed snapshot as governed DAG traversal and emits traces (import package: runtime)
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/protocol_runtime
9
+ Project-URL: Standard, https://doi.org/10.5281/zenodo.22150616
10
+ Keywords: protocol-governed-computing,pgc,protocol,runtime,workflow,execution
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Topic :: System :: Distributed Computing
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ License-File: NOTICE
23
+ Provides-Extra: reference
24
+ Requires-Dist: pgc-governance>=2.0.0; extra == "reference"
25
+ Dynamic: license-file
26
+
27
+ # protocol_runtime
28
+
29
+ **Deterministic execution engine for Protocol-Governed Computing** (import package: `runtime`).
30
+
31
+ The runtime traverses a precompiled execution graph and produces traceable, governed outcomes. It
32
+ does not discover behavior, interpret intent, or contain business logic. Everything it will do was
33
+ decided at compile time; execution is a traversal of what the snapshot already says.
34
+
35
+ ## Install
36
+
37
+ ```bash
38
+ pip install pgc-runtime
39
+ ```
40
+
41
+ Once installed:
42
+
43
+ ```bash
44
+ protocol_runtime --help
45
+ ```
46
+
47
+ ## Where it fits
48
+
49
+ ```
50
+ software_governance the normative surface every composition rests on
51
+ conformance_workloads workloads that prove conformance
52
+ business_domains domains built on the surface
53
+
54
+ protocol_compiler source → compiled projections
55
+ snapshot_assembler projections → assembled snapshot
56
+ protocol_runtime snapshot → execution (this repo)
57
+ snapshot_inspector snapshot → inspection
58
+ ```
59
+
60
+ `protocol_transport` governs the boundary at either end of execution — ingress and egress as
61
+ first-class contracts. The runtime consumes only the **assembled** snapshot, never an individual
62
+ repo's compiled layout.
63
+
64
+ ## What it is, and is not
65
+
66
+ **It is** a deterministic graph traverser, a trace generator, and a host for the capability
67
+ implementations a snapshot names.
68
+
69
+ **It is not** a workflow authoring system, a rules engine, a business-logic container, or a
70
+ framework with pluggable behavior. There is no extension point, because an extension point is a
71
+ place where ungoverned behavior could enter.
72
+
73
+ ## Inputs and outputs
74
+
75
+ ```
76
+ snapshot root the assembled snapshot — the sole source of behavior
77
+ payload external input (JSON)
78
+ data-root the state storage boundary; one data root is one instance
79
+ ```
80
+
81
+ A run writes an append-only trace alongside the state its declared side effects produce:
82
+
83
+ ```
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
92
+ ```
93
+
94
+ ## Running
95
+
96
+ ```bash
97
+ ./run.sh # warm-boot the sibling assembled snapshot
98
+ ./run.sh boot --snapshot /abs/snapshot # explicit boot
99
+ ./run.sh run --wf <domain>::WF_… --data-root /abs/instance
100
+ ./run.sh examine /abs/trace.jsonl
101
+ ```
102
+
103
+ `run.sh` wraps the CLI, also installed as the `protocol_runtime` console script, with four
104
+ subcommands:
105
+
106
+ | command | what it does |
107
+ |---|---|
108
+ | `run` | execute a workflow against a data root |
109
+ | `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 |
112
+
113
+ `PGC_SNAPSHOT_ROOT` overrides the snapshot location; `PGC_IMPL_ROOTS` is the colon-separated set of
114
+ roots on `PYTHONPATH` for domain capability implementations.
115
+
116
+ **Warm reboot is its own proof.** Bringing every manifest domain resident and hash-verified
117
+ establishes that the snapshot is intact and executable before any workflow runs. A surface-only
118
+ snapshot has no workflow to traverse, and warm reboot is exactly what proves it sound anyway.
119
+
120
+ **A data root is an instance, not an interface.** Two data roots against the same snapshot are two
121
+ independent instances of the same governed behavior.
122
+
123
+ ## How execution works
124
+
125
+ The runtime loads the compiled graph, admits the request against the intent that declares it, and
126
+ walks the workflow node by node. At each node it executes the capability contract's steps —
127
+ invoking transforms, applying side effects — and routes on the declared outcome. It resolves
128
+ nothing by name at execution time: the compiler assigned integer addresses, and traversal operates
129
+ on those.
130
+
131
+ Every step emits evidence. The trace is not a log the runtime chose to write; it is the record of
132
+ the path actually taken through a graph that was fixed before the run began, which is what makes a
133
+ run reproducible and reviewable after the fact.
134
+
135
+ ## License
136
+
137
+ Apache-2.0. See `LICENSE` and `NOTICE`.
138
+
139
+ ---
140
+
141
+ ## The package family
142
+
143
+ | Package | Repository | Role |
144
+ |---|---|---|
145
+ | `pgc-compiler` | `protocol_compiler` | declarations → compiled projections |
146
+ | `pgc-assembler` | `snapshot_assembler` | projections → sealed snapshot |
147
+ | `pgc-runtime` | `protocol_runtime` | snapshot → governed execution |
148
+ | `pgc-inspector` | `snapshot_inspector` | snapshot → read-only inspection |
149
+ | `pgc-transformation` | `transformation` | change request → protocol artifacts |
150
+ | `pgc-governance` | `software_governance` | the governance surface and its capability implementations |
151
+ | `pgc-workloads` | `conformance_workloads` | the workloads that make conformance observable |
152
+ | `pgc-domains` | `business_domains` | the business domain implementations the composed snapshot binds |
153
+
154
+ `pip install pgc` brings in the whole family.
155
+
156
+ **Installing the toolchain is one of two steps.** The compiler resolves the governance surface from
157
+ `PGC_PLATFORM_ROOT` — fail-hard, cwd-independent, zero inference — so the *declarations* come from a
158
+ repository you point at, never from a wheel. A registry inside a package would be a second governance
159
+ surface competing with the repository's, and a build could then be governed by a stale copy.
160
+
161
+ ```bash
162
+ git clone https://github.com/protocol-governed-computing/software_governance
163
+ export PGC_PLATFORM_ROOT=$PWD/software_governance
164
+ pgc # reports what is installed and whether the anchor resolves
165
+ ```
166
+
167
+ `PGC_BUILD_ROOT` (compiled output, keeping the governance repo read-only) and `PGC_DOMAIN_ROOTS`
168
+ (additional domains contributing their own `registry/structures`) are optional.
169
+
170
+ **Versioning.** Two schemes, and the published version follows the second.
171
+
172
+ - **Internal** — each repository's `VERSION` file, a monotonic composition ordinal. PGC versions the
173
+ composition rather than each repo: they release together and the governance closure forces lockstep,
174
+ so the ordinal names which composition a repo belongs to. Development happens on `dev/<N>` and each
175
+ cycle is tagged `release-<N>`. This is not published.
176
+ - **Public** — `PUBLIC_VERSION`, tagged on every component repository. The platform is at **`v2`**.
177
+
178
+ **The published version is the public one: `v2` is `2.0.0`.** The standard the packages implement is a
179
+ separate artifact on its own track and is not this number.
180
+
181
+ The standard these packages implement is published separately: https://doi.org/10.5281/zenodo.22150616
@@ -0,0 +1,32 @@
1
+ LICENSE
2
+ MANIFEST.in
3
+ NOTICE
4
+ README.md
5
+ pyproject.toml
6
+ pgc_runtime.egg-info/PKG-INFO
7
+ pgc_runtime.egg-info/SOURCES.txt
8
+ pgc_runtime.egg-info/dependency_links.txt
9
+ pgc_runtime.egg-info/entry_points.txt
10
+ pgc_runtime.egg-info/requires.txt
11
+ pgc_runtime.egg-info/top_level.txt
12
+ runtime/__init__.py
13
+ runtime/api.py
14
+ runtime/boot.py
15
+ runtime/cli.py
16
+ runtime/conformance.py
17
+ runtime/ct_errors.py
18
+ runtime/ct_execute.py
19
+ runtime/ct_executor.py
20
+ runtime/dispatcher.py
21
+ runtime/evidence.py
22
+ runtime/loader.py
23
+ runtime/memory.py
24
+ runtime/scheduler.py
25
+ runtime/trace_viz.py
26
+ runtime/examine/__init__.py
27
+ runtime/examine/classifier.py
28
+ runtime/examine/cli.py
29
+ runtime/examine/hint_engine.py
30
+ runtime/examine/locator.py
31
+ runtime/examine/parser.py
32
+ runtime/examine/reporter.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ protocol_runtime = runtime.cli:main
@@ -0,0 +1,3 @@
1
+
2
+ [reference]
3
+ pgc-governance>=2.0.0
@@ -0,0 +1 @@
1
+ runtime