Backend contract drift: design notes + vd-add-backend skill describe an API base.py doesn't implement

[thorwhalen]

The dev-facing backend contract is described in two places that disagree with the actual code.

Documented (design notes + dev skill):

• .claude/skills/vd-add-backend/SKILL.md and misc/docs/vd_design_notes.md / .claude/CLAUDE.md describe create_collection(name, *, dimension, distance, index_config=None, schema=None, **kw) and search(query, k=10, *, filter=None, egress=None) returning SearchHit NamedTuples.

Implemented (vd/base.py):

• Client.create_collection(name, *, schema=None, **kwargs) — no dimension / distance / index_config.
• Collection.search(query, *, limit=10, filter=None, egress=None, **kwargs) — limit, not k; returns SearchResult dicts, not SearchHit.

A developer following vd-add-backend today would implement a backend that does not conform to the protocol clients actually code against.

Related half-applied refactors:

• The Collection Protocol still lists add_documents / upsert as baseline methods even though SupportsBatch exists and vd_design_notes.md §3.2 explicitly calls for demoting them to that capability.
• Escape-hatch naming is inconsistent across the codebase: BaseBackend.client (property), ChromaCollection.native (property), plus .raw / underlying_client mentioned in docs and design notes.

Decide the canonical contract and converge code + design notes + skill in one change:

• create_collection: are dimension / distance / index_config create-time params? (vd_design_notes.md §3.6 says yes — needed for real ANN backends.)
• search: k or limit? SearchHit NamedTuple or dict SearchResult?
• Demote add_documents / upsert from the Collection baseline to SupportsBatch (keep as a convenience mixin so existing skills stay valid).
• Pick canonical escape-hatch names (suggest .client = raw backend client, .native = raw collection handle) and apply everywhere.
• Re-run the skill-sync skill so vd-add-backend matches.

vd is free-to-change (no users yet) — this is the moment to lock the contract before more backends are written against it.