ThothII/.superpowers/sdd/pgvector-task-1-report.md

Local pgvector Task 1 report

Status

Implemented the direct PgVectorStore behind the transport-neutral VectorStore port. The adapter uses separate optional reader and writer database configurations, derives capabilities from configured authority, validates strict positive search limits, filters kinds in SQL before limiting, and merges multi-collection results by cosine similarity.

All collection identifiers are selected from the fixed schema_records, evidence, and memory allowlist and composed with psycopg2.sql.Identifier. Values, vectors, kinds, hashes, and limits remain bound parameters. Collection/kind mismatches fail with VectorStoreError.

Upserts preserve the canonical metadata shape, use record_key conflict semantics, update the transport hash and embedding, and leave semantic metadata fields intact. Health probes reader and writer independently and reports observed vector(N) dimensions against the configured embedding dimension.

Configuration and factory

pgvector_direct now accepts explicit optional reader and writer DatabaseConfig entries. The former connection entry remains supported as a deprecated read-only compatibility path. build_vector_store(..., require_write=True) accepts writer-only direct configurations and fails early when no explicit writer is present.

The transitional build_vector_loader bulk-sync path remains in place. It uses an explicit direct writer when present, or the legacy connection; it deliberately does not treat a new reader-only credential as writable. No production schema migration was added.

TDD and verification

• RED: the new tests initially failed at collection because PgVectorStore did not exist.
• Docker L0 pgvector tests: 11 passed.
• Direct + HTTP parity/factory/config focus: 51 passed.
• Full harness: 461 passed, 5 deselected.
• Changed-file Ruff lint: clean.
• Changed-file Ruff format check: clean.
• git diff --check: clean.

The repository-wide ruff check . still reports 34 pre-existing test-file findings outside Task 1; none are in changed files. The full pytest suite emits 17 existing legacy-config deprecation warnings.

Scope and concerns

• Test fixtures create only the three existing vector tables needed to exercise the adapter; migration/versioning remains Task 2.
• The legacy single connection form stays read-only through the public port, matching its previous adapter behavior, while remaining available to the explicitly documented bulk-loader transition.