fed5cb0805
- Normalize rich proposals into atomic reviewed canonical graph bundles with exact row verification. - Harden reviewer/apply roles, upgrade ACLs, and prove generic plus Helmer lifecycles in isolated PostgreSQL. - Publish repo-native VPS/GCP/Cory skills and live-readonly GCP inventory without changing the live VPS runtime. `.agents/skills/crabbox/SKILL.md` `.agents/skills/teleo-gcp-parity-ops/SKILL.md` `.agents/skills/teleo-kb-db-change-workflow/SKILL.md` `.agents/skills/teleo-leo-onboarding/SKILL.md` `.agents/skills/teleo-vps-runtime-ops/SKILL.md` `.agents/skills/working-leo-cory-outcomes/SKILL.md` `docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.json` `docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.md` `docs/reports/leo-working-state-20260709/current-truth-index.md` `docs/reports/leo-working-state-20260709/gcp-cloud-sql-t3-live-readonly-current.json` `docs/reports/leo-working-state-20260709/gcp-cloud-sql-t3-live-readonly-current.md` `docs/reports/leo-working-state-20260709/gcp-cloudsql-studio-parity-gate-current.json` `docs/reports/leo-working-state-20260709/gcp-cloudsql-studio-parity-gate-current.md` `docs/reports/leo-working-state-20260709/gcp-parallel-delegation-current.json` `docs/reports/leo-working-state-20260709/helmer-approve-claim-clone-canary-current.json` `docs/reports/leo-working-state-20260709/helmer-approve-claim-normalization-current.json` `docs/reports/leo-working-state-20260709/skill-pack-manifest.json` `docs/reports/leo-working-state-20260709/skill-pack-readme.md` `docs/reports/leo-working-state-20260709/working-leo-current-state-20260709.md` `docs/reports/leo-working-state-20260709/working-leo-definition-20260709.md` `docs/reports/leo-working-state-20260709/working-leo-execution-plan-current.md` `scripts/apply_proposal.py` `scripts/apply_worker.py` `scripts/approve_proposal.py` `scripts/kb_apply_prereqs.sql` `scripts/kb_proposal_normalize.py` `scripts/probe_gcp_db_parity.py` `scripts/run_approve_claim_clone_canary.py` `scripts/run_approve_claim_isolated_container_canary.sh` `tests/test_apply_proposal.py` `tests/test_apply_worker.py` `tests/test_approve_proposal.py` `tests/test_kb_apply_prereqs.py` `tests/test_kb_proposal_normalize.py` `tests/test_kb_proposal_routes.py` `tests/test_probe_gcp_db_parity.py` `tests/test_repo_skill_pack.py`
103 lines
4.2 KiB
Markdown
103 lines
4.2 KiB
Markdown
---
|
|
name: teleo-kb-db-change-workflow
|
|
description: Use for Teleo canonical Postgres changes, proposal normalization, separate review and apply authority, isolated approve_claim canaries, row-level proof, rollback, and production-apply gating.
|
|
---
|
|
|
|
# Teleo KB DB Change Workflow
|
|
|
|
## Working Target
|
|
|
|
Move one reviewed knowledge change from `kb_stage.kb_proposals` to exact
|
|
canonical rows without confusing approval with application or silently changing
|
|
production.
|
|
|
|
## State Model
|
|
|
|
- `pending_review`: staged, not approved, canonical rows unchanged.
|
|
- `approved`: reviewed intent exists, but `applied_at` may still be null.
|
|
- `applied`: the guarded transaction finished and canonical postflight matches.
|
|
- `packet_ready_not_executed`: rehearsed artifacts exist; production is unchanged.
|
|
|
|
Never infer `applied` from chat text, a packet, a clone, or `status=approved`.
|
|
|
|
## Canonical 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` login approves the exact type/payload.
|
|
- `scripts/apply_proposal.py`: operator-only `kb_apply` login writes and verifies.
|
|
- `scripts/kb_apply_prereqs.sql`: roles, immutable approval row, gate functions,
|
|
ownership, indexes, and exact ACL matrix.
|
|
- `scripts/run_approve_claim_isolated_container_canary.sh`: disposable runtime
|
|
proof plus read-only live count/service endpoints.
|
|
|
|
## Authority Invariants
|
|
|
|
1. `kb_review` and `kb_apply` are separate `NOINHERIT` login roles with no role
|
|
memberships.
|
|
2. `kb_gate_owner` is `NOLOGIN` and owns the immutable approval table and three
|
|
`SECURITY DEFINER` gate functions.
|
|
3. The legacy three-argument approval overload must be absent.
|
|
4. Review binds DB role, reviewer principal, type, full payload, timestamp, and
|
|
note in one immutable row.
|
|
5. Apply locks and compares that snapshot before writes, verifies every
|
|
payload-controlled field and exact table deltas, then finishes the ledger.
|
|
6. Existing semantic evidence/edge rows must match approved weights and owners;
|
|
a mismatch rolls back.
|
|
7. `kb_apply` remains a trusted operator-only canonical writer. This design does
|
|
not claim resistance to a compromised apply credential.
|
|
|
|
## Operator Path
|
|
|
|
1. Read the proposal and canonical target rows.
|
|
2. Normalize rich intent; reject malformed, duplicate, lossy, or unsupported
|
|
candidates instead of guessing.
|
|
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 both disposable canaries from the repo root:
|
|
|
|
```bash
|
|
scripts/run_approve_claim_isolated_container_canary.sh \
|
|
--output docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.json
|
|
|
|
scripts/run_approve_claim_isolated_container_canary.sh \
|
|
--normalization-json docs/reports/leo-working-state-20260709/helmer-approve-claim-normalization-current.json \
|
|
--output docs/reports/leo-working-state-20260709/helmer-approve-claim-clone-canary-current.json
|
|
```
|
|
|
|
5. Require `status=pass`, every check true, expected deltas equal measured
|
|
deltas, source hashes matching current files, zero live count deltas, stable
|
|
service endpoints, and independent clone/container/workdir cleanup.
|
|
6. Treat production deployment, permission migration, worker enablement, and a
|
|
production proposal apply as separate authorization windows.
|
|
|
|
## Current Proof And Claim Ceiling
|
|
|
|
The retained generic and Helmer v3 receipts each pass `37/37`. Generic proves
|
|
`2/2/2/1/1`; Helmer proves `5/13/17/7/1`. Live read-only endpoint counts stayed
|
|
`1837/4145/4670/4916/17/26`, and the gateway stayed on PID `2999690` with zero
|
|
restarts during those runs.
|
|
|
|
This proves current-source behavior in disposable PostgreSQL and unchanged live
|
|
count/service endpoints. It does not prove byte-for-byte live content, code
|
|
deployment, the production permission migration, or Helmer application.
|
|
|
|
Read `docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.md`
|
|
and both JSON receipts before making a current claim.
|