---
name: teleo-kb-db-change-workflow
description: Use for Teleo document-to-claim composition, proposal normalization, separate review/apply authority, isolated apply canaries, row-level proof, rollback, and production-apply gating.
---

# Teleo KB DB Change Workflow

## Working Target

Turn a source document, post, or operator correction into source-bound evidence,
atomic claims, graph links, and a reviewable proposal; then move an approved
change into exact canonical rows only through a guarded apply transaction.

Composition and application are separate capabilities. A synthetic apply test
does not prove source ingestion, and a staged source extraction does not prove
canonical application.

## State Model

- `pending_review`: staged, not approved, canonical rows unchanged.
- `approved`: reviewed intent exists, but `applied_at` may still be null.
- `applied`: guarded transaction and canonical postflight completed.
- `packet_ready_not_executed`: rehearsed artifacts exist; production is
  unchanged.

Never infer `applied` from chat text, a packet, a clone, or `status=approved`.

## Composition Contract

A useful composed change must retain:

1. immutable source locator, captured bytes or excerpt, and SHA-256 binding;
2. atomic claim body plus type, confidence, tags, and provenance metadata;
3. exact evidence excerpt linked to both claim and source;
4. graph edges, conflict/update/supersession candidates, and uncertainty;
5. duplicate and existing-row search before staging;
6. a proposal payload that accounts for every intended canonical row.

Do not flatten strategy, governance, concept maps, identity, and reasoning tools
into generic claim rows merely because the input document discusses them.

Run the deterministic source-to-proposal canary:

```bash
.venv/bin/python scripts/run_leo_local_ingestion_proposal_canary.py \
  --fixture fixtures/working-leo/document-ingestion-v1.json \
  --output /tmp/leo-local-ingestion-proposal-canary-current.json
```

Require the source, claim, evidence, and proposal UUIDs to link exactly; claim
and evidence text must be exact substrings of the source; status must remain
`pending_review`; the container must use network `none` and leave no volume or
container behind.

## Canonical Apply Contract

The strict `approve_claim` v2 payload may create:

- `public.claims`
- `public.sources`
- `public.claim_evidence`
- `public.claim_edges`
- `public.reasoning_tools`

The lifecycle is split across:

- `scripts/kb_proposal_normalize.py`: fail-closed rich intent to strict payload;
- `scripts/approve_proposal.py`: `kb_review` approves the exact type/payload;
- `scripts/apply_proposal.py`: operator-only `kb_apply` writes and verifies;
- `scripts/kb_apply_prereqs.sql`: roles, immutable approval row, gate functions,
  ownership, indexes, and ACLs;
- `scripts/run_approve_claim_isolated_container_canary.sh`: disposable
  lifecycle plus optional live-readonly source/service checks.

## Authority Invariants

1. `kb_review` and `kb_apply` are separate `NOINHERIT` login roles.
2. `kb_gate_owner` is `NOLOGIN` and owns immutable approval/gate functions.
3. Review binds DB role, reviewer, type, full payload, timestamp, and note.
4. Apply locks and compares that snapshot before canonical writes.
5. Payload-controlled fields and exact table deltas are verified.
6. Existing evidence/edge semantic mismatches roll back the transaction.
7. Replay, stale payload, source-hash drift, and direct privilege probes fail.
8. `kb_apply` remains a trusted operator-only canonical writer, not autonomous
   chat write authority.

## Operator Path

1. Read the proposal, source bytes/hash, and canonical target rows.
2. Normalize rich intent; reject lossy, duplicate, or unsupported mappings.
3. Run focused tests:

```bash
.venv/bin/python -m pytest -q \
  tests/test_kb_proposal_normalize.py \
  tests/test_approve_proposal.py \
  tests/test_apply_proposal.py \
  tests/test_kb_apply_prereqs.py
```

4. Run the generic and real-packet disposable canaries.
5. Require exact before/after projections, deltas, source hashes, approval row,
   applied timestamp, service state, rollback, and cleanup.
6. Treat source checkout deployment, permission migration, worker enablement,
   and production proposal application as separate windows.

## Current Proof - 2026-07-12

- Deterministic source composition passes all `13` checks and links one source,
  one extracted claim, one evidence row, and one `pending_review` proposal. It
  proves the retained fixture path, not arbitrary-source model extraction.
  Arbitrary production document/tweet ingestion is not proven.
- The isolated approved-change lifecycle creates exact deltas of `2` claims,
  `2` sources, `2` evidence rows, `1` edge, and `1` reasoning tool, stamps the
  proposal applied, rolls back, and leaves no container or volume.
- The earlier generic and Helmer v3 source-bound receipts remain `37/37`; the
  newer lifecycle receipt adds stricter service/source isolation and cleanup.
- A VPS live-readonly T3 clone run passed with unchanged canonical counts and
  unchanged gateway PID. Production was not applied.
- The broader live-VPS full-data source-composition checkpoint passes `34/34`:
  new hash-bound document/post, conflicting atomic claims, exact source/evidence
  links, strict proposal, separated approval/apply, restarted discovery, graph
  reasoning, and cleanup. This is isolated clone proof, not Telegram delivery
  or production mutation.
- PR #86 merged the harness/operator fixes. VPS auto-deploy synchronized source
  without restarting Leo; the gateway remained PID `2403328`, `NRestarts=0`.
- Current VPS canonical counts remain claims `1837`, sources `4145`, evidence
  `4670`, edges `4916`, proposals `26`.

Read:

- `docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.json`
- `docs/reports/leo-working-state-20260709/leo-source-composition-clone-checkpoint-current.json`
- `docs/reports/leo-working-state-20260709/leo-v3-document-source-lifecycle-current.md`
- `docs/reports/leo-working-state-20260709/source-document-compiler-canary-20260713.md`

## Claim Ceiling

Leo has strong isolated proof for source-bound composition, guarded canonical
application, restarted discovery, and graph reasoning. Production still has
three approved-but-unapplied legacy packets and fourteen pending-review
proposals. No broad autonomous production apply authority exists, and no
production rich packet should be applied without exact retained authorization,
operator identity, postflight, regression, rollback, and cleanup evidence.