103 lines
5.5 KiB
Markdown
103 lines
5.5 KiB
Markdown
---
|
|
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.
|