docs/continuity_materializer_v0.md

# Continuity Materializer v0

Clean product one-liner: the local continuity materializer is now an explicit fallback seam, while the live NextGen continuity runtime is the primary provider.

## Why

The missing primitive from the earlier continuity thread was:

`manifest -> materializer -> live surface`

This repo already had:

`work manifest -> runtime -> receipt`

So the Pareto move is not a new runtime. It is one thin materializer that converts a continuity manifest into the current runtime contract.

## Flow

```bash
./bin/bvtctl continuity-materialize
```

That does:

1. read [`runtime/examples/continuity_v1_manifest.json`](/Users/jobs/Desktop/bit-vector-tensor-control-policy/runtime/examples/continuity_v1_manifest.json:1)
2. compile it into a lawful [`work_manifest_v0`](/Users/jobs/Desktop/bit-vector-tensor-control-policy/runtime/work_manifest_v0.json:1)
3. execute that manifest through [`runtime/execute_manifest.sh`](/Users/jobs/Desktop/bit-vector-tensor-control-policy/runtime/execute_manifest.sh:1)
4. emit a receipt-backed continuity slice under `runs/continuity/`

## Materialized Surfaces

| Surface | Role |
| --- | --- |
| `runs/continuity/<version>/lineage.json` | continuity lineage slice |
| `runs/continuity/<version>/surface_registry.json` | continuity surface picker state |
| `runs/continuity/latest.json` | deterministic pointer for the active continuity slice |

## Why in plain English

The graph or packet can propose the next continuity version, but the shell needs something concrete it can read without asking the model again.

The local materializer still turns:

- continuity version
- predecessor
- endpoints
- surfaces
- eval gate

into one small live state slice the deterministic kernel can answer from.

## Provider-first rule

Primary path:

```bash
./bin/bvtctl continuity-materialize
./bin/bvtctl continuity-status
./bin/bvtctl continuity-surfaces
./bin/bvtctl continuity-lineage hv-continuity-control-plane-v1
```

Fallback path:

```bash
./bin/bvtctl continuity-materialize-local
```

Why in plain English: the external continuity engine already owns the real runtime object and live routes, so this repo should wrap it first and only fall back to the local materializer when that provider is unavailable.