feat(vector): version pgvector schema

2026-07-12 01:21:29 +02:00
parent 409f806aae
commit c0d50e9b08
7 changed files with 509 additions and 0 deletions
@@ -0,0 +1,52 @@
+# Local pgvector Task 2 report
+
+## Outcome
+
+Implemented ordered, idempotent production migrations and the `tht vector migrate`
+interface, including `tht vector migrate --status --json` with pristine JSON output.
+
+## Implementation
+
+- `001_extensions.sql` installs pgvector.
+- `002_schema_tables.sql` creates `vectors.schema_records`, `vectors.evidence`, and
+  `vectors.memory` with the `VectorWriteRecord` columns and `vector(768)` embeddings.
+- `003_roles.sql` creates passwordless `NOLOGIN` reader/writer roles. Deployments inject
+  credentials (or grant these roles to separately-created login roles); no production secret
+  is stored in the repository.
+- Reader authority is schema usage plus table `SELECT`.
+- Writer authority is schema usage, table `INSERT`/`UPDATE`, narrow hash-probe column `SELECT`,
+  and sequence `USAGE`. It has no `DELETE`, broad row `SELECT`, DDL, or ownership authority.
+- The migration runner discovers ordered SQL files, records SHA-256 checksums in
+  `public.tht_vector_migrations`, serializes runners with a transaction-scoped advisory lock,
+  and applies the full pending batch in one transaction.
+- Status distinguishes applied, pending, and checksum-drifted migrations. Apply refuses drift.
+  A failed migration rolls back both prior migrations in that batch and ledger writes.
+
+## TDD evidence
+
+RED was observed with a real `pgvector/pgvector:pg16` testcontainer: 6 failures for the missing
+module, missing command, and missing schema.
+
+GREEN verification:
+
+- Focused migration + direct adapter integration: `23 passed`.
+- Full harness from the documented `harness/` cwd: `473 passed, 5 deselected`.
+- Targeted Ruff (`tht` plus the new L0 test): clean.
+- `git diff --check`: clean.
+
+The new L0 coverage exercises clean install, idempotent rerun, pristine JSON status, checksum
+drift, transaction rollback, exact tables/columns/dimensions, role isolation, sequence authority,
+and the real `PgVectorStore.health()` plus `VectorWriteRecord` upsert path.
+
+## Existing repository lint baseline
+
+The requested full `ruff check .` was run. It reports 34 pre-existing violations in unrelated
+test files (unused imports and one-line semicolon statements). None are in Task 2 files; changing
+them would exceed this task's scope. The complete harness test gate is green.
+
+## Self-review
+
+No unresolved Task 2 correctness concern found. One deliberate contract choice is worth noting:
+writer `INSERT` and `UPDATE` are table-level because the approved direct adapter health probe uses
+`has_table_privilege` for those authorities. Least privilege is retained by withholding broad
+`SELECT`, `DELETE`, DDL, ownership, and credentials.