Metadata-Version: 2.4
Name: omnibachi
Version: 0.2.0
Summary: OmniBachi runtime for Protocol-Governed Systems (PGS)
Author: Bachi
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/bachipeachy/pgs_runtime
Project-URL: Repository, https://github.com/bachipeachy/pgs_runtime
Keywords: pgs,protocol,runtime,workflow,execution
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# pgs_runtime

**Deterministic execution engine for Protocol-Governed Systems.**

The runtime traverses a precompiled execution graph and produces traceable, governed outcomes.  
It does not discover behavior. It does not interpret intent. It does not contain business logic.

Behavior is declared in protocol, executed by runtime, implemented in capabilities, and observed via traces and state.

---

## What this component is (and is not)

**This is:**
- A generic execution substrate
- A graph traversal engine
- A trace generator
- A host for capability implementations (CT/CS bindings)

**This is not:**
- A workflow authoring system
- A rules engine
- A business logic container
- A framework with pluggable behavior

All behavior is declared and compiled before execution. The runtime only consumes a sealed snapshot.

---

## Inputs → Outputs

**Inputs:**
```
protocol_snapshot/   ← compiled artifacts (from pgs_compiler)
payload              ← external input (JSON)
data_root            ← state storage boundary
workspace            ← execution context
```

**Outputs:**
```
traces/<TRACE_ID>/
├── <TRACE_ID>.jsonl   ← append-only execution log
├── <TRACE_ID>.md      ← human-readable summary
└── <TRACE_ID>.png     ← visual execution path

data/
├── registry/          ← idempotent state
├── events/            ← append-only history
└── ...                ← additional declared side-effects
```

---

## CLI surface

```bash
omnibachi run \
  --wf blockchain::WF_REGISTER_ACTOR_UNVERIFIED_V0 \
  --payload payload.json \
  --data-root ./data \
  --workspace .

omnibachi examine ./traces/<TRACE_ID>/<TRACE_ID>.jsonl
```

That is the entire public interface. Everything else is governed by the protocol snapshot.

---

## How execution works

You run a workflow. The runtime:

1. Loads the compiled DAG from `protocol_snapshot/`
2. Resolves inputs via JSONPath expressions
3. Executes CT/CS nodes (transforms and side-effects)
4. Routes based on declared outcomes
5. Emits trace + state

No logic exists in the runtime for any specific workflow.

**Example:** `omnibachi run --wf blockchain::WF_REGISTER_ACTOR_UNVERIFIED_V0 ...`

The runtime has no knowledge of blockchain. It only traverses the precomputed graph compiled from that workflow's protocol declaration.

---

## What makes this runtime different

**1. Compile-time closure**

All routing, bindings, and side-effect semantics are resolved before execution begins:
- no reflection
- no dynamic imports
- no fallback logic

Execution is a pure traversal of a sealed graph.  
No runtime decision can alter the graph.

**2. Outcome-driven control flow**

Every node produces an explicit outcome:
```
SUCCESS
ALREADY_EXISTS
VIOLATION
...
```

These outcomes map to named edges in the graph. There is no implicit branching, no hidden control flow, no exception-driven logic.

**3. Side-effects are governed, not coded**

Side-effects (CS) declare their own semantics:

| Behavior | Example |
|----------|---------|
| Idempotent | registry insert → `ALREADY_EXISTS` on repeat |
| Append-only | event stream → always records |
| Mutable | state overwrite (explicitly declared) |

The runtime executes these semantics as declared. It does not interpret them.

**4. Execution ≠ effect**

A workflow can succeed even when a side-effect returns `ALREADY_EXISTS`. Execution is structural. Effects are governed independently. This separation is visible in traces and state.

**5. Trace is first-class output**

Every run produces a complete causal execution record keyed by `trace_id`. This enables:
- deterministic replay
- auditability
- debugging without code instrumentation

---

## Where this fits in the system

PGS is intentionally split into layers:

| Layer | Repo | Responsibility |
|-------|------|----------------|
| Governance | `pgs_governance` | Invariants, constitutional rules, structural definitions |
| Compilation | `pgs_compiler` | Produce `protocol_snapshot/` |
| Transport | `pgs_transport` | Ingress/egress adapters for HTTP and CLI |
| **Execution** | **`pgs_runtime` ← here** | **Traverse compiled graph deterministically** |
| Capabilities | `pgs_capabilities` | Provide CT/CS implementations |
| Domains | `pgs_blockchain`, `pgs_ai_governance` | Real-world workflows |
| Entry point | `pgs_workspace` | Run and observe |

---

## What you should explore next

| Go here | To... |
|---------|-------|
| `pgs_workspace` | Run end-to-end and observe traces |
| `protocol_snapshot/` | Inspect what the runtime actually reads |
| `pgs_governance` + `pgs_compiler` | Author and compile new workflows |
| `pgs_capabilities` | Add new capability implementations |

---

## Research context

This implementation demonstrates:

> *"Extensibility by declaration, not refactor."*

And more broadly: governance-driven execution, compile-time closure of behavior, separation of execution from semantics.

---

## Final note

The runtime does not decide what to do.  
It only executes what has already been decided.

If you find yourself wanting to add logic to this runtime — stop.  
That logic belongs in the protocol (declaration) or in capability implementations (CT/CS).  
The runtime should remain boringly deterministic.

---

## License

Apache-2.0. See LICENSE and NOTICE for details.
