Adapter Foundations final-review fix report

Date: 2026-07-11 Branch: codex/portable-deployment Worktree: /Users/mp/projects/ThothII/.worktrees/portable-deployment Binding findings: .superpowers/sdd/adapter-final-review-findings.md

Outcome

All seven final-review findings are addressed as one coherent adapter-foundations change:

HTTP vector reader and writer clients are independently optional. Capabilities reflect the configured side; writer-only new and legacy configurations build successfully for targeted writes; search without a reader raises public VectorReadUnavailable.
VectorHealth now reports read/write configured and reachable state independently, preserves side-specific errors, and reports expected/observed embedding dimensions plus compatibility. HTTP diagnostics cover read-only, write-only, both-up, and writer-down cases. Direct health exposes its configured expected dimension without adding schema or migration work.
ThothRestDwhAdapter accepts DatabaseIdentityConfig, matching its resource contract.
Both vector adapters reject bools, floats, zero, and negative search limits using one exact positive-integer guard.
Port tests explicitly cover public exports and frozen capability records.
A real tht subprocess test proves one legacy deprecation warning per config load on stderr while JSON stdout remains parseable and uncontaminated.
The adapter plan and SDD progress explicitly constrain build_vector_loader to transitional bulk sync and schedule its removal/migration in the local pgvector plan. Targeted memory and solved-question writes remain on build_vector_store(..., require_write=True).

No pgvector schema or migration changes were made.

Files changed

harness/tht/ports/vector.py
harness/tht/ports/__init__.py
harness/tht/adapters/vector/thoth_http.py
harness/tht/adapters/vector/legacy_direct.py
harness/tht/adapters/factory.py
harness/tht/adapters/dwh/thoth_rest.py
harness/tests/test_vector_port_contract.py
harness/tests/test_adapter_factory.py
harness/tests/test_config_resources.py
harness/tests/test_config_legacy_compat.py
harness/tests/test_adapter_command_regressions.py
harness/tests/test_dwh_port_contract.py
docs/superpowers/plans/2026-07-11-adapter-foundations.md
.superpowers/sdd/progress.md
.superpowers/sdd/adapter-final-fix-report.md

TDD and verification evidence

RED:

cd harness && .venv/bin/pytest tests/test_vector_port_contract.py \
  tests/test_adapter_factory.py tests/test_config_resources.py \
  tests/test_config_legacy_compat.py -q

Result: collection failed as expected because VectorReadUnavailable did not exist. After the initial implementation, the same command exposed two expected contract/test-harness corrections: dimension mismatch makes aggregate health unhealthy, and the installed CLI entry point is tht rather than python -m tht.cli.

GREEN, covering adapter/config/command regressions:

cd harness && .venv/bin/pytest tests/test_vector_port_contract.py \
  tests/test_adapter_factory.py tests/test_config_resources.py \
  tests/test_config_legacy_compat.py tests/test_adapter_command_regressions.py \
  tests/test_dwh_port_contract.py tests/test_memory_save_one.py \
  tests/test_solved_question.py tests/test_search_similar_kinds.py \
  tests/test_vector_dual_key.py -q

Result: 66 passed in 0.45s.

Docker availability:

docker info --format '{{.ServerVersion}}'

Result: 29.4.1 (available; command required Docker socket access).

Full repository-default non-L2 harness suite, with Docker available for L0 tests:

cd harness && .venv/bin/pytest -q

Result: 433 passed, 5 deselected, 17 warnings in 9.14s. The five deselections are the configured L2/live-service tests. Warnings are existing legacy-workspace FutureWarning emissions.

Scoped lint and diff hygiene:

cd harness && .venv/bin/ruff check tht/ports tht/adapters \
  tests/test_vector_port_contract.py tests/test_adapter_factory.py \
  tests/test_config_resources.py tests/test_config_legacy_compat.py \
  tests/test_adapter_command_regressions.py tests/test_dwh_port_contract.py
git diff --check

Result: All checks passed!; git diff --check produced no output.

Commit

Commit subject: fix(adapter): close final foundation review

The report is part of that same final commit. A Git object cannot contain its own SHA without changing that SHA; the exact resulting commit ID is therefore recorded in the task handoff from git rev-parse HEAD after creation.

Self-review

Reader/writer separation is preserved: search dereferences only _reader; hashes/upsert only _writer; health probes each configured client independently and never substitutes one result for the other.
Writer failure contributes to aggregate ok=False, even when the reader succeeds.
Dimension compatibility is derived only from configured embedding dimension and existing list_tables metadata. Missing metadata remains None, not a guessed success/failure.
The shared limit guard uses type(limit) is int, intentionally rejecting Python booleans and numeric coercions before either adapter reaches its transport.
Existing JSON/CLI behavior is preserved; the subprocess regression parses stdout as JSON and counts exactly one deprecation marker on stderr.
Scope remains adapter foundations. No vector DDL, schema initialization, or migration work was introduced.

Concerns / follow-up

Write reachability uses the existing list_tables diagnostic on the separately authenticated writer client. Deployments must allow that non-mutating diagnostic RPC to the writer credential; failures are intentionally visible rather than hidden by reader success.
Existing legacy-workspace tests emit 17 FutureWarnings in the full suite. This wave pins the required production stderr behavior but does not migrate unrelated test fixtures.
build_vector_loader remains transitional technical debt only for bulk sync, explicitly assigned to 2026-07-11-local-pgvector-profile.md.

6.0 KiB Raw Blame History