ThothII/.superpowers/sdd/pgvector-final-fix-report.md

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.