---
name: teleo-reconstruction-recovery
description: Use when restoring, rebuilding, recompiling, or incident-recovering Leo's Teleo knowledge database, including snapshot recovery, genesis-plus-ledger replay, source recompilation, parity verification, and honest recovery claim ceilings.
---

# Teleo Reconstruction Recovery

## Job

Choose the smallest recovery path that restores a usable Leo knowledge system
without confusing snapshot restoration, strict ledger replay, and semantic
source recompilation.

## Authority

Read `docs/kb-rebuild-and-recompile.md` first. It is the canonical recovery
contract. Use `docs/reports/leo-working-state-20260709/current-truth-index.md`
only for the newest retained proof point, and refresh live state before making a
current VPS or GCP claim.

PR #146 is merged and owns the deterministic genesis-plus-ledger reconstruction
slice in `ops/run_local_genesis_ledger_rebuild.py`. PR #147 is merged and owns
the current unseen-reasoning verifier in
`scripts/verify_leo_unseen_reasoning_chain.py`. PR #148 is a separate, open GCP
least-privilege candidate; do not treat its branch files or proposed live state
as canonical `main` recovery instructions until it merges.

## Select The Recovery Mode

| Need | Path | Honest result |
|---|---|---|
| Restore the latest verified state quickly | `ops/run_local_canonical_postgres_rebuild.py` | Exact snapshot recovery |
| Snapshot a Forgejo/text corpus for extraction | `ops/run_local_corpus_knowledge_rebuild.py` | Content-addressed UTF-8 sources and work items; no claims |
| Partition verified extraction work | `ops/shard_corpus_extraction_work.py` | Deterministic exact-once work shards; no source interpretation |
| Prove strict post-genesis applies replay exactly | `ops/run_local_genesis_ledger_rebuild.py` | Isolated insert-only ledger replay |
| Assemble reviewed V3 replay materials | `ops/build_v3_genesis_ledger_bundle.py` | Hash-pinned V3 ledger; optional operator-supplied admission metadata |
| Turn one retained source into a reviewed packet | `scripts/compile_kb_source_packet.py` | Deterministic proposal packet, not canonical knowledge |
| Rebuild every row from original sources | Follow the semantic recompilation contract in `docs/kb-rebuild-and-recompile.md` | Partial until every row and receipt is accounted for |
| Diagnose a live incident before recovery | Use `.agents/skills/teleo-vps-runtime-ops/SKILL.md` and `.agents/skills/teleo-infra-provenance/SKILL.md` | Fresh read-only incident map |

## Safe Order

1. Identify the intended source database, snapshot, manifest, commit, and hashes.
2. Keep private dumps, row payloads, source excerpts, and replay material outside
   the repository and mode `0600`.
3. Inventory text sources before semantic extraction. For a binary original,
   retain its exact bytes and provide text from a separately pinned extractor;
   this repository does not yet supply a general PDF/office extractor.
4. Build and independently verify the V3 ledger before running genesis replay.
   Admission metadata is operator-supplied and is not a cryptographic signature
   from `m3taversal`.
5. Run the selected path in an isolated, network-disabled local container.
6. Verify schema, constraints, roles, counts, row hashes, key queries, and exact
   cleanup.
7. Run the relevant focused tests, then the unseen-reasoning verifier when the
   restored state is meant to support Leo answers.
8. Separate local reconstruction from VPS restore, GCP restore, service restart,
   Telegram delivery, promotion, and production apply. Each is its own proof row.

## Commands

Use the repository virtual environment documented in `README.md`:

```bash
.venv/bin/python ops/run_local_canonical_postgres_rebuild.py --help
.venv/bin/python ops/run_local_corpus_knowledge_rebuild.py --help
.venv/bin/python ops/shard_corpus_extraction_work.py --help
.venv/bin/python ops/build_v3_genesis_ledger_bundle.py --help
.venv/bin/python ops/run_local_genesis_ledger_rebuild.py --help
.venv/bin/python scripts/compile_kb_source_packet.py --help
.venv/bin/python -m pytest -q \
  tests/test_run_local_corpus_knowledge_rebuild.py \
  tests/test_shard_corpus_extraction_work.py \
  tests/test_v3_source_rebuild_lifecycle_postgres.py \
  tests/test_build_v3_genesis_ledger_bundle.py \
  tests/test_run_local_canonical_postgres_rebuild.py \
  tests/test_run_local_genesis_ledger_rebuild.py \
  tests/test_verify_leo_unseen_reasoning_chain.py
```

The help and focused-test commands are safe local canaries. A real recovery
requires caller-supplied private material and must retain a sanitized receipt
without the material itself.

## Stop Conditions

Stop before any live restore or restart when the source snapshot is not
hash-bound, the source authority is ambiguous, parity fails, private material
would enter Git or logs, cleanup cannot be proved, or the requested operation
would promote GCP or mutate production without exact authorization.

## Claim Ceiling

- Exact snapshot recovery is working when its parity receipt passes.
- Corpus inventory proves exact copied text bytes and extraction work locations,
  not semantic claims or binary extraction.
- The V3 ledger builder accepts only exact source-normalized applied materials,
  selects every ordered entry, and never infers admission from proposal status.
- The merged genesis-plus-ledger path proves an isolated insert-only slice.
- Semantic source-to-blank-database recompilation remains incomplete until every
  canonical row traces to a genesis record or reviewed replay receipt.
- No local receipt proves a live VPS/GCP restore, service restart, Telegram
  delivery, production apply, or GCP promotion.
