docs/runtime_and_cli.md

# Runtime And CLI

Clean product one-liner: the single runtime here is a thin agent-harness runtime over graph state, controlled by bits, vectors, and tensors, with one local CLI to operate it.

## What this product is

Pareto read:

| Claim | Accurate read | Why in plain English |
| --- | --- | --- |
| agent harness | yes | one operator-facing runtime over graph state |
| metacognitive | yes | it can inspect its own state, confidence, and route choice |
| metacybernetic | yes | it can regulate lane, gates, escalation, and proof loops |
| federated learning runtime | not yet, not in the strict ML sense | this is cross-surface policy distillation, not weight aggregation |

Layman version: this is a thinking-and-steering harness, not a model-training cluster.

## Single runtime we need

The one runtime we need is:

`conversation -> runtime manifest -> graph kernel -> receipts -> control benchmarks`

## Responsibility split

Clean product one-liner: the runtime kernel should hold the law, and the model should operate as the semantic interpreter over lawful state.

| Surface | Deterministic kernel | Model lane | Why in plain English |
| --- | --- | --- | --- |
| receipt generation | yes | no | proof must replay cleanly |
| graph/state updates | yes | no | the same input should not mutate memory randomly |
| exact runtime lookups | yes | no | latest-artifact and schedule reads are retrieval, not interpretation |
| execution gates | yes | no | allow/block is law, not style |
| packet-first synthesis | no | yes | this is where ambiguity and abstraction belong |
| semantic explanation | no | yes | the operator needs a concise read over state, not raw packets |

Layman version: the model may operate at the kernel-spec layer by reading formal packet state and explaining it, but it should not own the kernel rules that decide exact retrieval, state mutation, or authority.

| Layer | Local home | Why | Real-world analog |
| --- | --- | --- | --- |
| graph kernel | `vendor/meta3-graph-core/` | durable state + receipt-first execution | engine block |
| runtime | `runtime/` | one manifest-driven harness loop | drivetrain |
| control language | `policy/` | bits, vectors, tensors, gates, confidence | instrument cluster |
| benchmarks | `benchmarks/` | prove memory, tensor, safety, economics | test track |
| API | `api/` | one front door | reception desk |
| UX | `ux/` | one operator desk | cockpit |

## CLI

The thin CLI entrypoint is:

`bin/bvtctl`

### Primary path

```bash
./bin/bvtctl "summarise the current runtime"
./bin/bvtctl ask "run the demo manifest" runtime/examples/demo_manifest.json
./bin/bvtctl chat
./bin/bvtctl context
./bin/bvtctl bootstrap-context
```

Layman version: the operator should be able to type a sentence first, and a fresh agent should be able to pull one context packet before reaching for lower-level surfaces.

### Commands

```bash
./bin/bvtctl "summarise the current runtime"
./bin/bvtctl chat
./bin/bvtctl context
./bin/bvtctl bootstrap
./bin/bvtctl packet migration_brief
./bin/bvtctl run migration_brief
```

### What each command does

| Command | Result |
| --- | --- |
| `"..."` | routes a plain-English request through the local conversational turn runner |
| `ask` | explicit conversational alias for sentence-driven requests |
| `chat` | opens a local conversational loop |
| `context` | prints the hydrated system lineage, VSM policy, and payload templates |
| `bootstrap-context` | writes the reusable session handoff packet |
| `bootstrap` | builds the bootstrap hotgraph |
| `packet` | generates one bounded control packet |
| `run` | runs bootstrap + packet generation in one pass |
| `continuity-status` | reads the provider-first continuity runtime state |
| `continuity-surfaces` | reads the provider-first continuity surface registry |
| `continuity-lineage` | reads one provider-first continuity lineage slice |
| `continuity-flow` | returns one operator packet with route, context, action, and receipt |
| `continuity-resume` | returns the continuity desk packet for resume, active surface, and next command |
| `continuity-activate` | activates one provider continuity surface |
| `continuity-materialize` | instantiates the live continuity runtime through the provider, with local fallback only if needed |
| `continuity-materialize-local` | compiles the local fallback continuity manifest into a receipt-backed live slice |
| `pm-products` | reads the delivery candidates compiled from user-data reductions |
| `pm-resume` | returns the PM desk packet over candidate products, continuity state, and benchmark state |
| `pm-next` | returns the next bounded delivery move from the PM desk |
| `pm-verify` | returns the benchmark-gated PM verification packet |
| `memory-readiness` | shows the deterministic-memory readiness read and the remaining typed-ledger gap |
| `memory-runtime` | shows the compiled typed memory runtime artifact |
| `memory-get` | returns one typed memory unit by exact deterministic id |
| `memory-as-of` | returns the typed memory unit effective at a given time |
| `memory-expand` | expands one typed memory unit through deterministic relation edges |

## When the CLI becomes the real operator surface

Now for bootstrap.

It becomes the real runtime CLI once:

1. the graph kernel is vendored into `vendor/meta3-graph-core/`
2. the manifest runtime contract lands in `runtime/`
3. the control policy pack lands in `policy/`
4. the API and UX contracts are wired to the same local state

That is the minimum honest bar.

## Continuity Desk

Clean product one-liner: the continuity shell should resume from one tiny desk packet, not by replaying raw history or hopping across separate reads.

| Rule from user data | Shell behavior |
| --- | --- |
| route by purpose before text | continuity asks hit provider status, lineage, and surfaces first |
| smallest meaningful surface first | use the continuity desk packet before graph-wide semantic reasoning |
| prior chat should be resumed as state | `continuity-resume` returns the current active surface and next command |
| minimal active cut | the desk keeps to the provider status, lineage, and surface registry unless those miss |

## PM Operator

Clean product one-liner: the PM operator is a thin delivery desk over product candidates, continuity state, and benchmark gates.

| Surface | Role |
| --- | --- |
| `pm-products` | candidate registry from user-data reductions |
| `pm-resume` | current PM desk packet |
| `pm-next` | bounded next delivery move |
| `pm-verify` | benchmark gate over the delivery desk |

Why in plain English: memory may help find what exists, but product delivery still needs one desk that decides what to ship next and what proof is required.

## Typed Memory Runtime

Clean product one-liner: the typed memory runtime is the shell-owned ledger cut that unifies exact recall, temporal recall, and relational expansion without widening into semantic search first.

| Surface | Role |
| --- | --- |
| `memory-runtime` | compiled ledger artifact with typed memory units |
| `memory-get` | exact deterministic recall by stable unit id |
| `memory-as-of` | historical recall by logical id and timestamp |
| `memory-expand` | rationale/provenance expansion through relation edges |

Why in plain English: if the shell already has the exact thing, it should fetch it directly; if the question is about the past, it should fetch the right version; if the answer depends on context, it should follow the recorded edges.