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

./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

./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.