60 lines
3.4 KiB
Markdown
60 lines
3.4 KiB
Markdown
# 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.
|
|
|
|
## External-profile regression follow-up
|
|
|
|
Local pgvector is now an explicit `deploy/compose.local-vector.yaml` overlay. The base Compose and
|
|
production external override contain no direct vector password declarations, mounts, or `_FILE`
|
|
variables, so external deployments do not resolve or require local password files. A real lifecycle
|
|
gate unsets all local secret-file variables, renders external config, builds and starts core, waits
|
|
for health, and inspects the live container for absence of local direct-vector secret paths. The
|
|
local overlay retains its live inspect assertion (paths present, values absent), rotation, restart
|
|
persistence, and transactional backup/restore drill.
|