143 lines
6.3 KiB
Markdown
143 lines
6.3 KiB
Markdown
---
|
|
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 outputs/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`
|
|
- `outputs/leo-local-ingestion-proposal-canary-current.json`
|
|
|
|
## 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.
|