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.
- pgc_runtime-2.0.0/LICENSE +67 -0
- pgc_runtime-2.0.0/MANIFEST.in +8 -0
- pgc_runtime-2.0.0/NOTICE +11 -0
- pgc_runtime-2.0.0/PKG-INFO +181 -0
- pgc_runtime-2.0.0/README.md +155 -0
- pgc_runtime-2.0.0/pgc_runtime.egg-info/PKG-INFO +181 -0
- pgc_runtime-2.0.0/pgc_runtime.egg-info/SOURCES.txt +32 -0
- pgc_runtime-2.0.0/pgc_runtime.egg-info/dependency_links.txt +1 -0
- pgc_runtime-2.0.0/pgc_runtime.egg-info/entry_points.txt +2 -0
- pgc_runtime-2.0.0/pgc_runtime.egg-info/requires.txt +3 -0
- pgc_runtime-2.0.0/pgc_runtime.egg-info/top_level.txt +1 -0
- pgc_runtime-2.0.0/pyproject.toml +50 -0
- pgc_runtime-2.0.0/runtime/__init__.py +0 -0
- pgc_runtime-2.0.0/runtime/api.py +71 -0
- pgc_runtime-2.0.0/runtime/boot.py +147 -0
- pgc_runtime-2.0.0/runtime/cli.py +387 -0
- pgc_runtime-2.0.0/runtime/conformance.py +249 -0
- pgc_runtime-2.0.0/runtime/ct_errors.py +33 -0
- pgc_runtime-2.0.0/runtime/ct_execute.py +84 -0
- pgc_runtime-2.0.0/runtime/ct_executor.py +312 -0
- pgc_runtime-2.0.0/runtime/dispatcher.py +448 -0
- pgc_runtime-2.0.0/runtime/evidence.py +245 -0
- pgc_runtime-2.0.0/runtime/examine/__init__.py +126 -0
- pgc_runtime-2.0.0/runtime/examine/classifier.py +350 -0
- pgc_runtime-2.0.0/runtime/examine/cli.py +35 -0
- pgc_runtime-2.0.0/runtime/examine/hint_engine.py +245 -0
- pgc_runtime-2.0.0/runtime/examine/locator.py +148 -0
- pgc_runtime-2.0.0/runtime/examine/parser.py +223 -0
- pgc_runtime-2.0.0/runtime/examine/reporter.py +110 -0
- pgc_runtime-2.0.0/runtime/loader.py +360 -0
- pgc_runtime-2.0.0/runtime/memory.py +125 -0
- pgc_runtime-2.0.0/runtime/scheduler.py +264 -0
- pgc_runtime-2.0.0/runtime/trace_viz.py +276 -0
- 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.
|
pgc_runtime-2.0.0/NOTICE
ADDED
|
@@ -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 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
runtime
|