fix(vector): close local pgvector final review

2026-07-12 02:48:10 +02:00
parent 407c4a6faf
commit 6c67235caf
16 changed files with 265 additions and 28 deletions
@@ -0,0 +1,49 @@
+# Local pgvector whole-plan final fix report
+
+## Outcome
+
+All four binding final-review findings are closed.
+
+1. `PgVectorStore.health()` checks namespace `USAGE` independently for reader and writer
+   before inspecting vector types. Real PostgreSQL tests revoke only schema `USAGE`, prove both
+   health sides false and operations unavailable, then grant it back and prove recovery.
+2. Direct reader/writer passwords use workspace `password_file` references. Compose mounts the
+   two files read-only into core and exposes only `_FILE` paths. Rendered Compose and live
+   `docker inspect` checks prove secret contents are absent.
+3. Direct search failures map to `VectorReadUnavailable`; hash/upsert failures map to
+   `VectorWriteUnavailable`. Messages are fixed and sanitized, original exceptions remain chained,
+   and upsert rollback is preserved.
+4. The shared secret policy uses Linux `stat -c` with macOS `stat -f` fallback. Host files permit
+   only `0600`/`0400`; Docker's read-only `0444` is accepted only beneath `/run/secrets`. Tests and
+   operator docs pin this exact policy.
+
+## TDD evidence
+
+The new config, mode, schema-usage, unavailable-connection, and permission regressions failed
+before their implementations. The first live secret-policy run also caught GNU `stat -f` accepting
+an incompatible format invocation; detection now tries the native Linux form first. The next live
+run caught smoke-generated rotation fixtures at `0644`; fixtures now model the documented host
+policy.
+
+## Verification
+
+- Real direct pgvector + HTTP parity: `31 passed`.
+- Full harness from `harness/`: `493 passed, 5 deselected`.
+- Live `local-vector` rotation, restart persistence, inspect boundary, and backup/restore: pass.
+- Core image vector migration discovery/status smoke: pass.
+- External and local Compose deployment security contracts: pass.
+- Config/port focused suite: `26 passed`.
+- Secret policy, bootstrap rotation, and backup/restore safety scripts: pass.
+- Changed Python Ruff, shell syntax, and `git diff --check`: pass.
+
+One attempted full-harness invocation from the repository root produced a path-dependent failure
+in an existing test that opens `workflow.yaml` relative to CWD. It was immediately rerun using the
+documented `cd harness && .venv/bin/pytest -q` command and passed completely.
+
+## Operational notes
+
+Workspace files contain file paths, never direct passwords. Secret contents necessarily exist in
+the in-process validated `DatabaseConfig` used to establish PostgreSQL connections, but are not
+serialized by doctor/Compose/inspect paths. Docker Desktop file-backed secrets may appear as bind
+mounts; the safe runtime exception is therefore based on the read-only service mount location
+`/run/secrets`, while source files remain owner-only on the host.