# Leo Architecture, Work, And Outcomes Original delivery summary from `2026-07-14 01:40 UTC`, reconciled with merged repository truth on 2026-07-15. This is the executive summary of what Leo is, how its knowledge system works, what changed during the July 10-14 delivery wave, what is genuinely working, and what remains incomplete on the VPS, GCP, and database-rebuild paths. ## Plain-Language Verdict **Leo on the VPS is materially working at the live database-grounded handler tier.** It can find current knowledge without being handed row IDs, distinguish proposals from live knowledge, remember the current conversation, prepare a document into grounded candidates, stage a review proposal, explain uncertainty, use only the visible handle `m3taversal`, and preserve this behavior across a managed gateway restart. The current broad no-post suite passes `15/15`. **The whole system is not complete.** The current broad suite has not yet been repeated visibly in the real Telegram group through authenticated Google Chrome. The newest post-V3 database copy has since been restored to a disposable private GCP Cloud SQL clone with exact parity and a bounded no-send reasoning replay, then cleaned up. Persistent GCP remains staging and older than that disposable proof point. No V3 production proposal has been canonically applied. A snapshot can rebuild the current database exactly, and merged PR #146 adds an exact insert-only genesis-plus-ledger slice; the entire historical database still cannot be recompiled from raw documents and review history alone. Repository reconciliation: PRs #146 and #147 are merged `main` truth. PR #148 remains an open least-privilege GCP candidate and is not canonical runtime proof. ## The Architecture ```mermaid flowchart TD U["Telegram user"] --> T["Telegram gateway"] T --> H["Hermes / Leo runtime"] H --> C["Fresh DB context compiler"] C --> P[("Canonical Postgres in VPS Docker")] H --> V["Response validator"] P --> V V --> T D["Document, post, transcript, or extraction"] --> S["Private source preparation"] S --> X["Exact source fragments and candidate claims"] X --> Q["kb_stage proposal"] Q --> R["Human review"] R --> A["Guarded kb_apply operator"] A --> P A --> L["Private row-level replay receipt"] P --> B["Verified snapshot and manifest"] B --> DR["Exact restore on demand"] B --> G["GCP staging copy"] L --> SR["Genesis plus accepted-ledger replayer"] ``` ### 1. User and runtime layer - Telegram is the user-facing surface. - The gateway sends the message to the Hermes-based Leo runtime. - Same-session conversation memory belongs to the runtime, not to canonical knowledge. - Runtime files such as profile state or `SOUL.md` can shape behavior, but they are not the authoritative claim and evidence database. ### 2. Database truth layer The live canonical database is PostgreSQL in the `teleo-pg` Docker container on the VPS. Its current key counts are: | Data | Rows | | --- | ---: | | Claims | `1,837` | | Sources | `4,145` | | Claim-evidence links | `4,670` | | Claim edges | `4,916` | | Reasoning tools | `17` | | Proposals | `29` | The important ownership boundary is: - `public.*` is canonical, live knowledge; - `kb_stage.*` is imports, mappings, proposals, review state, and apply state; - runtime memory and workspace files are supporting state, not canonical DB proof; - a proposal is not live knowledge merely because it exists or is approved; - canonical apply requires committed `public.*` rows, proposal status `applied`, non-null `applied_at`, and row-level postflight readback. The live database does not currently have the decision-matrix tables described in the architecture direction. Current proposal approval is reviewer approval, not a decision-matrix vote. The V3 architecture document is direction for future schema and policy; it is not proof that those tables are deployed. ### 3. How the initial database was built Most of the initial canonical database came from retained Forgejo-era workspace files, not from another live Forgejo database being queried on every answer: ```text Forgejo-era file workspace -> retained inventory/import runs -> kb_stage staged rows -> canonical UUID mappings -> public claims, sources, evidence, and edges -> current PostgreSQL database ``` The database retains enough mappings to account for most initial rows: - `1,807` of `1,837` claims map to retained staged imports; - all `4,145` canonical sources have canonical mappings; - `4,254` of `4,670` evidence links are directly reproduced by retained joins; - `4,878` of `4,916` edge rows are accounted for by staged relations. The remaining historical rows need explicit genesis records, source-synthesis rules, or later-change receipts. This is why snapshot recovery is complete while full source-derived recompilation remains partial. ### 4. How Leo reads knowledge now For database-dependent questions, the runtime compiles fresh facts from Postgres before the model answers. The validator then checks the draft against the same receipt. Unsupported state claims fail closed instead of being accepted because they sound plausible. This now covers: - current counts and schema boundaries; - relevant claims, sources, evidence, and graph edges; - proposal status and `applied_at`; - named and versioned proposal packets; - reviewer approval versus canonical apply; - source-intake limits; - runtime memory versus canonical provenance; - handler execution versus Telegram-visible delivery. ### 5. How Leo changes knowledge now The bounded source path is: ```text private source artifact -> duplicate retrieval against canonical knowledge -> up to three atomic candidates -> exact source-fragment binding -> provenance and uncertainty manifest -> deterministic strict proposal payload -> pending_review -> human review -> guarded apply -> exact canonical row readback -> private replay receipt ``` Leo can propose and prepare. It does not self-approve or silently self-apply. The separate `kb_review` and `kb_apply` capabilities enforce the review/apply boundary at the database level. After a guarded apply, the operator now writes a private mode-`0600` receipt that binds: - the immutable reviewed payload; - reviewer and applier metadata; - the exact executed apply-SQL hash; - exact canonical rows, including generated IDs and timestamps; - per-row, per-table, payload, and replay-material hashes. If the file write is lost after commit, `--receipt-only` can recover the current row-level receipt without reapplying, provided all payload-controlled fields still match. A recovered engine hash is labeled as reconstructed, not falsely presented as original execution proof. ## Work Completed ### Expected behavior became testable The vague report that “Leo is broken” was converted into separate proof tiers: - database truth; - hidden handler execution; - Telegram-visible delivery; - same-session memory; - proposal preparation and staging; - reviewer approval; - canonical apply; - restart persistence; - GCP parity. This prevents a unit test, a handler response, a Telegram message, and a database mutation from being treated as the same result. ### Broad reasoning was repaired An early blind run exposed schema invention, incorrect edge semantics, memory used as provenance, overly long answers, and participant-name leakage. Those failures became runtime contracts and regression tests. The current live VPS no-post GatewayRunner suite passes `15/15`. It covers broad m3taversal-style questions about database composition, source intake, identity, restart truth, evidence linkage, memory, runtime versus canonical state, shared claims versus positions, forecast resolution, supersession, and uncertainty. ### The V3 document became a real lifecycle canary The V3 identity architecture document exposed and led to fixes for: - non-byte-exact model quotes; - line IDs that could point to blank lines; - exact source wording being confused with atomic canonical claim text; - named/versioned proposal questions routing to the wrong state readback; - a valid database-grounded answer being rejected by the response validator. The corrected proposal is `10bc0719-1c2b-5f42-a41e-86e6478692cb`, status `pending_review`, with database `applied_at: NULL`. Its candidates are not canonical and no production apply ran. ### Restart survival was proven After the managed restart, the exact V3 question still returned current DB counts and the correct proposal boundary. The gateway remains active with PID `366950`, `NRestarts=0`, and start time `2026-07-14 00:25:49 UTC`. The restart proof was captured at runtime merge `aa1246c603020bef07a575e4aebf4f2d2ed5db0c`. Later operator-script and documentation deliveries through `c7d91b679bd69ee2d1545ee7e169f7c2585d71c2` did not restart the gateway. ### Exact database recovery was proven The newest post-V3 dump contains `39` tables and `52,167` rows with `29` proposals. It restored into a fresh network-isolated PostgreSQL container with: - zero schema, constraint, role, row, hash, or performance mismatch; - `2.71` seconds for `pg_restore`; - `10.56` seconds total verification time; - no persistent storage; - no production DB contact; - complete container cleanup. This is a real on-demand recovery path today. ### Future apply provenance stopped getting worse PRs `#136` and `#137` added, merged, deployed, and live-proved private replay receipts. The deployed command ran as the real `teleo` service user against an existing strict applied proposal in read-only recovery mode. It recovered one exact edge, wrote a `teleo:teleo` mode-`600` receipt, changed no DB counts, left the gateway unchanged, and removed the private receipt afterward. ## What Is Achieved | Outcome | Evidence tier | Status | | --- | --- | --- | | Broad VPS database reasoning | live VPS no-post handler, `15/15` | Achieved | | Current claim/source/evidence/proposal readback | live VPS DB-grounded handler | Achieved | | Same-session memory without false DB provenance | live VPS handler | Achieved | | Exact `m3taversal` naming | live VPS handler and regression tests | Achieved | | Restart persistence | managed restart plus post-restart V3 readback | Achieved | | One-document source preparation | live VPS private source path | Achieved | | Grounded proposal staging | live VPS `pending_review` row | Achieved | | Exact snapshot rebuild | isolated local Postgres, `52,167` rows | Achieved | | New strict-apply row receipt | deployed VPS read-only recovery | Achieved | | Current disposable GCP copy and ID-free replay | private Cloud SQL and GCP compute, `52,167/52,167` rows | Achieved and cleaned up | | Genesis plus strict insert-only replay | isolated local Postgres through merged PR #146 | Achieved for supported strict contracts | ## What Is Not Achieved | Missing outcome | Why it is still open | | --- | --- | | Current broad Telegram-visible proof | Telegram Web in the connected Google Chrome is not authenticated; handler proof is not visible-chat proof | | V3 production canonical apply | proposal remains `pending_review`; no review or apply was authorized | | Arbitrary automatic document/post/tweet intake | the current source command handles one bounded text-like artifact; general fetch/extract/stage automation is not complete | | Persistent GCP parity and promotion | the disposable `52,167`-row proof passed, but persistent `teleo_canonical` remains the older staging copy and is not cut over | | Full source-to-blank-DB recompilation | historical provenance gaps and unsupported mutating contracts remain beyond the merged insert-only genesis-plus-ledger slice | | General DB-to-identity rendering | no complete scheduled DB-to-`SOUL.md` renderer is proven | | Deployed decision matrix | matrix tables and voting flow are absent from the current live schema | ## How This Moves The VPS Forward - Leo relies less on repeatedly trained answer style and more on current DB readback. - Broad questions work without the user supplying claim IDs. - Proposed, approved, and applied knowledge are visibly separated. - Source preparation has exact provenance instead of model-only summaries. - Restart behavior and database-backed answers are repeatable. - Future approved changes can carry row-level replay material instead of becoming another historical mystery. ## How This Moves GCP Forward - The current post-V3 snapshot has been restored to a disposable private Cloud SQL clone with exact parity, bounded no-send replay, and cleanup. - Persistent `teleo_canonical` remains the older staging copy; promotion, continuous replication, Telegram delivery, and production cutover are separate decisions and proof rows. - Open PR #148 proposes least-privilege runtime access. Its branch and proposed live end state remain candidate evidence until merge and receipt verification. ## How This Moves On-Demand Rebuild Forward There are now two distinct capabilities: 1. **Exact recovery, working now:** restore the verified snapshot and compare schema, roles, hashes, rows, and performance. 2. **Semantic recompilation, still partial:** rebuild from immutable sources, deterministic extraction, reviewed payloads, and accepted row receipts. The practical architecture is: ```text verified post-V3 snapshot = genesis epoch + every later accepted strict payload + every later row-level replay receipt -> deterministic replay -> canonical manifest comparison -> restart -> broad answer benchmark ``` The new receipt path closes the future side of this model. Merged PR #146 now replays supported strict insert-only receipts on a clean genesis clone and proves exact post-apply parity. The next reconstruction work is to retain complete deltas for mutating contracts, handle or reject legacy freeform applies, and repair historical import gaps without allowing new gaps to accumulate. ## Delivery Chain The latest coherent delivery sequence is merged: | PR | Outcome | | --- | --- | | `#127` | VPS document preparation and review staging | | `#128` | byte-exact source references | | `#129` | nonempty dense source-fragment IDs | | `#130` | atomic claims separated from exact quotes | | `#131` | retained V3 lifecycle proof | | `#132` | named/versioned proposal routing | | `#133` | response-validator compatibility | | `#134` | three-day VPS/GCP/rebuild handoff | | `#135` | current post-V3 snapshot and exact rebuild proof | | `#136` | private replay receipts for guarded applies | | `#137` | deployed receipt runtime proof | | `#144` | GCP database-first restore, fail-closed helper, and live restart proof | | `#146` | unified turn manifest and deterministic genesis-plus-ledger replay | | `#147` | unseen-reasoning verifier hardened for valid reasoning variance | PR #148 is open candidate work and is intentionally excluded from the merged delivery chain above. ## Immediate Next Outcomes 1. Authenticate Telegram Web in the connected Google Chrome and run visible, out-of-sample m3taversal-style questions. 2. Review and merge or reject PR #148, then verify the least-privilege runtime receipt before considering any persistent GCP promotion. 3. Extend genesis-plus-receipt reconstruction beyond supported insert-only contracts while retaining exact before/after deltas. 4. Run one explicitly reviewed source packet through guarded apply in a disposable clone before seeking any production apply authorization. 5. Reconstruct the remaining historical source, evidence, and edge provenance. ## Evidence - [Current truth index](current-truth-index.md) - [Three-day outcome and forward path](working-leo-three-day-outcome-and-forward-path-20260714.md) - [Database rebuild and recompilation](../../kb-rebuild-and-recompile.md) - [Broad VPS suite score](telegram-handler-m3taversal-oos-suite-score-current.md) - [Post-restart V3 readback](telegram-handler-v3-proposal-readback-post-restart-current.json) - [V3 document lifecycle](leo-v3-document-source-lifecycle-current.md) - [Post-V3 snapshot](gcp-refresh-post-v3-snapshot-current.json) - [Post-V3 exact local rebuild](gcp-refresh-post-v3-local-rebuild-current.json) - [Deployed replay-receipt proof](kb-apply-replay-receipt-current.json) ## Final Claim Ceiling The last three days produced a stable, testable, database-grounded Leo on the VPS at the handler tier, a real source-to-review path, exact snapshot recovery, and durable replay evidence for future strict applies. Subsequent work added disposable current GCP parity plus no-send replay and an exact insert-only genesis-plus-ledger slice. The system still lacks current Telegram-visible broad proof, persistent GCP parity/promotion, a V3 production apply, general automatic source ingestion, and full historical source-derived database recompilation.