ThothII/.superpowers/sdd/task-3-report.md

Task 3 report — vector port and wrappers

Status

Complete. Added the transport-neutral vector port, HTTP and legacy-direct wrappers, and routed the existing RestSearcher and DirectSearcher through them while retaining the canonical VectorRecord and VectorHit models.

TDD evidence

• RED: cd harness && .venv/bin/pytest tests/test_vector_port_contract.py -q
  • Result: collection failed with ModuleNotFoundError: No module named 'tht.adapters.vector' (expected missing-port failure).
• GREEN: cd harness && .venv/bin/pytest tests/test_vector_port_contract.py -q
  • Result: 4 passed in 0.11s.

Verification

• Required regression command: cd harness && .venv/bin/pytest tests/test_vector_port_contract.py tests/test_vector_dual_key.py tests/test_search_similar_kinds.py tests/test_memory_save_one.py tests/test_solved_question.py -q
  • Result: 26 passed in 0.12s (fresh final run; earlier run: 26 passed in 0.16s).
• Broader vector-focused regression: cd harness && .venv/bin/pytest tests -q -k 'vector or search_similar or memory_save_one or solved_question'
  • Result: 29 passed, 370 deselected in 0.49s.
• Scoped lint: cd harness && .venv/bin/ruff check tht/ports/vector.py tht/adapters/vector tht/vectorstore/reader.py tests/test_vector_port_contract.py
  • Result: All checks passed!.
• Whitespace check: git diff --check
  • Result: exit 0, no output.
• Staged whitespace check: git diff --cached --check
  • Result: exit 0, no output.

Commit

ff4d662 refactor(vector): define store contract

Only the six Task 3 implementation/test files were included in the commit.

Self-review / concerns

• Reader and writer clients remain separate: search and health use only the reader; hashes and upsert use only the writer.
• A missing writer reports upsert=False and raises VectorWriteUnavailable, including for an empty upsert, so deployments cannot silently bypass the write credential gate.
• Existing REST kind forwarding, legacy-404 fallback, post-filtering, global similarity merge, and direct table-per-kind behavior remain delegated to their established code.
• The port re-exports existing vector models instead of duplicating result types.
• Non-blocking design constraint: embedded values for the new generic upsert contract are carried in VectorRecord.metadata['embedding']; this preserves the existing canonical record model and REST payload without changing out-of-scope records.py. A later direct pgvector implementation may choose to formalize that field across adapters.

Authorized contract correction

Status: complete. Commit: fe8d70d fix(vector): separate write transport fields.

The earlier metadata-envelope concern above is superseded. The contract now exports a dedicated frozen VectorWriteRecord containing the canonical VectorRecord, precomputed embedding, and content hash. VectorStore.upsert accepts only that envelope. HTTP row serialization takes transport fields from the envelope and preserves record.metadata unchanged, including legitimate metadata keys named embedding and content_hash.

Corrective TDD evidence

• RED: cd harness && .venv/bin/pytest tests/test_vector_port_contract.py -q
  • Result: collection failed with ImportError: cannot import name 'VectorWriteRecord' from 'tht.ports.vector' (expected missing-envelope failure).
• GREEN: cd harness && .venv/bin/pytest tests/test_vector_port_contract.py -q
  • Result: 7 passed in 0.11s.
• Required regression suite: cd harness && .venv/bin/pytest tests/test_vector_port_contract.py tests/test_vector_dual_key.py tests/test_search_similar_kinds.py tests/test_memory_save_one.py tests/test_solved_question.py -q
  • Result: 29 passed in 0.15s (fresh final run; earlier run: 29 passed in 0.14s).
• Scoped lint: cd harness && .venv/bin/ruff check tht/ports/__init__.py tht/ports/vector.py tht/adapters/vector tht/vectorstore/reader.py tests/test_vector_port_contract.py
  • Result: All checks passed!.
• Whitespace check: git diff --check
  • Result: exit 0, no output.

Corrective self-review

• A real evidence_records(...) canonical builder record is serialized in the contract tests.
• Collision coverage proves semantic embedding and content_hash metadata survive while distinct envelope values occupy the RPC row's top-level transport fields.
• Reader health/search still use only the reader client; hashes/upsert still use only writer.
• Existing kind forwarding, legacy 404 fallback, post-filtering, similarity merge, and direct search behavior remain unchanged and covered by the required regression suite.
• The tracked plan, regenerated Task 3 scratch brief, port exports, adapter signature, and this report now consistently describe VectorWriteRecord.
• Concerns: none known.

---

Task simple-config-3 report — one bundle for local-vector and preprocess

Status

Complete. Local pgvector bootstrap, reconciliation, migration, and preprocess services now mount only /run/secrets/thothii.secrets. deploy/vector/secret-policy.sh validates the whole bundle (allowlist, duplicate/empty/unknown keys, comments/blank lines, mode and symlink policy) and returns only the requested value. The core entrypoint exposes DWH/vector/CA values to the harness and materializes short-lived 0600 password files for workspace resolution.

TDD evidence

• RED: ./scripts/test-preprocess-compose-config.sh failed on the pre-existing vector_reader_password Compose secret declaration.
• GREEN: the same command passes after the bundle conversion and verifies local-vector workspace interpolation and shared secret mounts.
• Added bundle parser regressions to ./scripts/test-vector-secret-policy.sh: comments/blank lines are accepted and an unrelated duplicate key is rejected.

Verification

• ./scripts/test-vector-secret-policy.sh — passed.
• ./scripts/test-preprocess-compose-config.sh — passed.
• ./scripts/test-vector-backup-restore-safety.sh — passed.
• ./scripts/test-default-compose.sh — passed.
• ./scripts/test-container-deployment.sh — passed.
• ./scripts/local-vector-smoke.sh — passed (real Docker; bootstrap rotation, role reconciliation, migration, persistence and restart).
• ./scripts/preprocess-smoke.sh — passed (real Docker; unchanged rerun, mutation, DWH job, ACTIVE publication and cleanup).
• git diff --check and sh -n gates — passed.

Commit

Pending: feat(compose): use one secret bundle for local services.

Concerns

The rotation helper still accepts old/new scratch files because that is its explicit CLI contract; the smoke script keeps those files outside Compose and mounts only the bundle.