Repository navigation
fix(kb): add kb_documents.world_id migration and KB schema-drift test - #9
Merged
Merged
Conversation
setup_db_schema() runs all DDL in one transaction. On databases that already dropped the legacy kb_chunks.embedding column, the unguarded 'ALTER COLUMN embedding DROP NOT NULL' raised and rolled back the whole transaction, including 'ADD COLUMN world_id' and every table created after it. Guard the ALTER with an information_schema check. Also create kb_documents.world_id as TEXT (an opaque scope key from callers outside the kernel) to match migration 005. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019KQ4WmeseA49GumEaZfYyj
- 003b_knowledgebase_tables: idempotent CREATE/ADD COLUMN for kb_documents, kb_chunks and kb_activity. Sorts before 004, which failed on a fresh DB's first boot because the migration runner runs before setup_db_schema() creates the tables. - 005_kb_documents_world_id: ADD COLUMN IF NOT EXISTS world_id TEXT, converts an existing UUID column, adds idx_kb_documents_world_id, and drops the legacy NOT NULL on kb_chunks.embedding when present. Fixes POST /knowledgebase/upload 500: column world_id of relation kb_documents does not exist. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019KQ4WmeseA49GumEaZfYyj
Replays app/migrations/sql into a column model, captures the SQL every knowledgebase_repository function sends through a fake asyncpg pool, and asserts each referenced column exists. Also checks migration ordering for KB tables, setup_db_schema type agreement, and the guarded legacy ALTER. Runs without Postgres. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019KQ4WmeseA49GumEaZfYyj
Ian-Tharp
marked this pull request as ready for review
November 3, 2026 14:34
Ian-Tharp
added a commit
that referenced
this pull request
Nov 3, 2026
Brings in #8 (fail-safe fault capture wiring), #9 (kb world_id migration), #10 (coverage pass) and #11 (comprehension gate Phase 3). Conflict resolutions: - backend/app/evaluation/__init__.py: union of exports (develop's fault_reasons / maybe_capture_fault plus the claims API). - backend/app/evaluation/capture.py: kept develop's fault_reasons / state_failed / maybe_capture_fault (CORE_EVAL_CAPTURE_FAULTS gate, never raises); the branch's unsupported-claim check becomes a new "unsupported_claims" fault reason instead of an early return in state_failed. Branch's dispatched_tool filter and refusal / blocked_actions / unsupported_claims metadata kept in fault_report_from_state. - backend/app/models/core_state.py: kept both field sets (refusal, blocked_actions, claim_report from the branch; step_checks from develop). - docs/evaluation_spec.md: auto-merged; added the unsupported_claims fault reason and the extra metadata keys to "Live fault capture". - tests/evaluation/test_claims.py: asserts fault_reasons == ["unsupported_claims"] for the unsupported-claim run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Changed
backend/app/migrations/sql/005_kb_documents_world_id.sql(new):ADD COLUMN IF NOT EXISTS world_id TEXTonkb_documents, plusidx_kb_documents_world_id. Ifworld_idalready exists asUUID, it is converted in place toTEXT. The migration also drops the legacyNOT NULLonkb_chunks.embedding, and only when that column still exists.backend/app/migrations/sql/003b_knowledgebase_tables.sql(new): idempotent baseline forkb_documents,kb_chunksandkb_activity(CREATE TABLE IF NOT EXISTS+ADD COLUMN IF NOT EXISTSfor every column added later). It sorts before004on purpose.backend/app/dependencies.py:setup_db_schema()now guardsALTER COLUMN embedding DROP NOT NULLwith aninformation_schemacheck, and createsworld_idasTEXTto match the migration.backend/tests/test_kb_schema_drift.py(new): schema-drift test. It needs no Postgres.Why
Only
backend/app/migrations/sql/is applied at startup, byapp/migrations/runner.pyfrom themain.pylifespan.backend/migrations/is never applied automatically, so this PR adds nothing there.I reproduced both failures against a real Postgres 16 + pgvector database:
world_id):world_idwas only ever added insidesetup_db_schema(), which runs all of its DDL in one transaction. On a DB whose legacykb_chunks.embeddingcolumn was already dropped (for example bybackend/migrations/003_remove_openai_embeddings.sql), the unguardedALTER TABLE kb_chunks ALTER COLUMN embedding DROP NOT NULLraised. That rolled back the whole transaction,world_idincluded.main.pylogs the error and then skips every laterensure_*_tables()call as well.004_knowledge_attributionruns before the KB tables exist and fails. The first boot is left withoutinstance_name,instance_timestampandsource_discussion, so uploads 500 oninstance_nameuntil a restart.003bfixes the ordering.Other tables the repository touches:
kb_activitymatches the code.kb_chunkshad the legacyNOT NULLembeddingproblem, fixed in 005. The attribution functions are placeholders and run no SQL.world_idisTEXTbecause it is an opaque scope key supplied by callers outside the kernel (world logic is archived, see ADR 006). It is not a foreign key toworlds.How to Test
What the drift test does:
app/migrations/sql/*.sqlin the runner's order into a{table: {column: type}}model.knowledgebase_repositoryfunction against a fake asyncpg pool that records the SQL.setup_db_schema()and the migrations agree on column types, and that the legacy ALTER is guarded.Checks that fail without the fix:
005→create_document: kb_documents.world_idandlist_documents_by_world: world_id003b→ ordering errors for004dependencies.py→ the type-mismatch and unguarded-ALTER tests failManual verification (real Postgres 16 + pgvector):
setup_db_schema()) twice each on three databases:world_idmissing andkb_chunks.embeddingdropped (the broken state; before this fix, setup failed there withcolumn "embedding" ... does not exist)world_idalready existed asUUIDworld_id textplus the index, and both boots succeeded each time.create_document(world_id=...)andlist_documents_by_world.Applying to an existing local DB
Option A (recommended): restart the backend. The runner applies
003band005automatically at startup. Both are idempotent, so this works whether or not your DB already ran004. Look forApplying migration: 005_kb_documents_world_idin the logs.Option B: apply by hand with psql, for example when the backend isn't running:
Check with
\d kb_documents:world_idshould betext, andidx_kb_documents_world_idshould exist.Checklist
black --check app/ tests/clean)Known gaps
knowledgebase_repository, not every repository.backend/migrations/(not auto-applied) still duplicates part ofapp/migrations/sql/. Consolidating or removing it is follow-up work.setup_db_schema()is still one large transaction, so any other failing statement could cause the same kind of silent rollback. This PR only fixes the KB statement that is known to fail.004_knowledge_attribution.sqlcontainsBEGIN/COMMITinside the runner's transaction. It works today, but it is fragile. I left the file unchanged because it has already been applied on existing DBs.Generated by Claude Code