One durable election authority commits a coordinated vector-plane generation

Sub of epic #17018 — delivers AC-C (D#17015 r6 authoritative text). Sibling of #17019 (authority), #17021 (routing), #17022 (composition proof); the migration-scale contract is the separate leaf AC-E sub (one PR each — the authority/barrier primitive and the resumable rebuild runner are separable deliverables).

Live latest-open sweep: checked latest open issues at 2026-08-12T12:15Z; no equivalent found (#17021/#17022 are routing/composition, not generation election). A2A claim sweep: AC-C claimed by me in the #17018 kickoff and Emmy's epic-review gate names it as an unowned leaf awaiting exactly this filing.

Context

Any change to a load-bearing embedding-generation coordinate (provider/engine, immutable model digest, quantization, output dimension, pooling/normalization + distance semantics, preprocessing/chunk-strategy version — the OQ2 tuple) invalidates every existing vector. The epic's lane switch changes the embedding engine, so the cutover REQUIRES a new corpus generation — and today no global election authority exists: VectorService.embedViaShadowSwap() performs sequential live→parking / shadow→canonical renames with rollback handling for ONE KB collection (VectorService.mjs#L1037-L1068 at dev@173129edd394), while MC owns its own embedding collections (memories, session summaries, temporal summaries, graph collections) with separate shadow/recovery machinery. Per-collection swaps without one authority can disagree — a reader could see the new generation in KB and the old one in MC memories, which is precisely the mixed-generation state OQ2 forbids.

The Problem

Emmy's STEP_BACK correction (D#17015 DC_kwDODSospM4BEnrR) and r5 recheck falsified the "extend the KB-only primitive + no second pointer" framing as self-contradictory for a plane-wide election. The converged contract (r6 AC-C): per-collection work may proceed independently, but GENERATION VISIBILITY must commit through one durable authority — partial promotion never advertises the new generation.

The Architectural Reality

• KB: ai/services/knowledge-base/VectorService.mjs — shadow build, embedViaShadowSwap(), parking/rollback collections.
• MC: ai/services/memory-core/ embedding collections + their shadow/recovery equivalents (target-set recovery; the WAL drain writes embeddings per collection).
• Health surfaces (KB/MC healthcheck + deployment-state snapshot) must report the ELECTED and PARKED generations — acceptance reads them.
• ADR-0019 governs any config leaf this adds (the generation identity/pointer is deployment-state, not env-derived config).

The Fix

Introduce the coordinated vector-plane generation contract:

1. A generation identity = the full OQ2 coordinate tuple, durably recorded.
2. Per-collection candidate build + validation (reusing the existing shadow primitives per store) — validation receipts per collection BEFORE any promotion.
3. One durable election authority (implementation open — deployment-state record, not a per-collection flag) that commits the generation via a stale-writer-fenced commit barrier or an explicitly quiesced bounded transition. No per-collection authorities that can disagree.
4. Partial promotion never advertises: until the barrier commits, every reader resolves the prior generation.
5. Full-set prior generation retained as rollback authority through the acceptance window; lifecycle candidate → current → rollback-retained → retired with retention/GC after acceptance.
6. Health/acceptance surfaces report elected + parked generations.

Acceptance Criteria

• Generation identity carries the complete OQ2 tuple and is durably recorded with the election.
• The commit barrier is stale-writer-fenced (a writer holding the pre-election view cannot commit into the new generation) OR the transition is explicitly quiesced and bounded — the chosen mechanism documented with its receipt.
• A partially-promoted state (some collections swapped, barrier not committed) resolves every reader to the PRIOR generation — proven by a fixture that halts mid-promotion.
• Rollback restores the full prior set (all collections) — proven by a fixture; a code-only rollback without the generation restore is impossible by construction.
• KB + MC health report elected + parked generation identities.
• No mixed-generation reads possible in any live collection (mutation test).

Out of Scope

• The resumable/budgeted rebuild runner + canonical-scale proof (the AC-E sibling leaf).
• The engine/lane switch itself (#17021/#17022) and the external cutover letter (AC-D stage 5).

Decision Record impact

aligned-with ADR-0014 (as amended by #17019/PR #17020); depends-on the D#17015 graduation (Decision Record from Discussion: Required — delivered by #17019).

Related

Epic #17018 · D#17015 r6 (AC-C) · #17019 · #17021 · #17022 · #16706 (incident evidence)

Origin Session ID: 8637b4b9-b852-45d9-b057-de34184aae8b Retrieval Hint: "coordinated vector-plane generation election commit barrier shadow swap"

Contract Ledger