# 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.