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

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

1. 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`.
2. `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.
3. `ThothRestDwhAdapter` accepts `DatabaseIdentityConfig`, matching its resource contract.
4. Both vector adapters reject bools, floats, zero, and negative search limits using one exact
   positive-integer guard.
5. Port tests explicitly cover public exports and frozen capability records.
6. A real `tht` subprocess test proves one legacy deprecation warning per config load on stderr
   while JSON stdout remains parseable and uncontaminated.
7. 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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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 `FutureWarning`s 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`.