{"row":{"id":"ADR-029","title":"EmbeddingSpec value-type reservation (Cortex seed)","file":"adr-029-embedding-spec-reservation.md","status":"accepted","date":"2026-04-17","cites":4,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5"],"tags":["l0","cortex","embedding","reservation"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-029: EmbeddingSpec value-type reservation (Cortex seed)","id":"adr-029-embeddingspec-value-type-reservation-cortex-seed"},{"k":"quote","inline":[{"k":"text","text":"Accepted 2026-07-11 (operator-delegated ADR ruling): the decision has\nbeen load-bearing in code since v0.81 and the reservation held its\nshape for three months — a "},{"k":"code","text":"proposed"},{"k":"text","text":" status no longer described\nreality. This prose replaces the Phase-C stub."}]},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The memory/Connectome era needs embedding storage whose index layout and\ndistance kernel are decided by three axes — "},{"k":"strong","text":"dim"},{"k":"text","text":", "},{"k":"strong","text":"dtype"},{"k":"text","text":", "},{"k":"strong","text":"metric"},{"k":"text","text":" —\nplus the model identity that produced the vector. The embedding landscape\nmoves monthly (Matryoshka truncation; 256→3072 dims; f32/f16/bf16/i8/binary\ndtypes; cosine/dot/euclidean/hamming metrics), so whatever type we reserve\nmust be able to grow fields without a breaking-change migration."}]},{"k":"p","inline":[{"k":"text","text":"Wave 4A R1 (commit "},{"k":"code","text":"001ae0b6f"},{"k":"text","text":", 2026-04-17) added "},{"k":"code","text":"EmbeddingSpec"},{"k":"text","text":" to\n"},{"k":"code","text":"nika-types"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-types/src/embedding.rs"},{"k":"text","text":") as that reservation,\nper the ADR-028 forward-compat reservation policy."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"code","text":"EmbeddingSpec"},{"k":"text","text":" ships in "},{"k":"code","text":"nika-types"},{"k":"text","text":" (L0) as "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" with a\n"},{"k":"code","text":"::new()"},{"k":"text","text":" constructor, carrying the (dim, dtype, metric, model_id) tuple:"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"dim / dtype / metric"},{"k":"text","text":" — exactly what HNSW/BM25/RRF backends need to\npick index layout and distance kernel."}],[{"k":"strong","text":"model_id optional"},{"k":"text","text":" — catalog-free consumers (tests, tools) construct\na spec without materialising a provider name."}],[{"k":"strong","text":"`#[non_exhaustive]` + `new()`"},{"k":"text","text":" — additive field evolution stays\nnon-breaking by construction (INV-019 idiom); the reservation absorbs\nthe monthly landscape drift instead of chasing it."}]]},{"k":"p","inline":[{"k":"text","text":"Field shape pinned in the commit body of "},{"k":"code","text":"001ae0b6f"},{"k":"text","text":" and in the FCI-035\naddendum of\n"},{"k":"link","text":"`docs/architecture/forward-compat-invariants.md`","href":"../architecture/forward-compat-invariants.md"},{"k":"text","text":".\n"},{"k":"code","text":"EmbeddingProvider"},{"k":"text","text":" (ADR-034, L0.5) consumes the spec."}]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"No reservation — add the type when the first provider lands."},{"k":"text","text":" Rejected:\nthe Connectome consumers (index rehydration · cross-provider portability)\nwould then force a breaking L0 change mid-era; ADR-028 exists precisely\nto pay this cost early and additively."}],[{"k":"strong","text":"A wider spec (normalization · truncation · pooling fields now)."},{"k":"text","text":"\nRejected: speculative fields rot; "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" makes adding them\nwhen a real provider needs them a patch-level change."}],[{"k":"strong","text":"String-typed axes."},{"k":"text","text":" Rejected: dim/dtype/metric are closed vocabularies\nthe kernel must match on — typed enums keep the distance-kernel dispatch\ntotal."}]]},{"k":"h","depth":2,"text":"Empirical validation (why accepted now)","id":"empirical-validation-why-accepted-now"},{"k":"p","inline":[{"k":"text","text":"Three months in production shape: the type is consumed, the field set never\nneeded a change, and zero migrations were forced on dependents. The\nreservation did exactly what ADR-028 promised."}]},{"k":"h","depth":2,"text":"See also","id":"see-also"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-028 — Forward-compat reservation policy (this ADR is an instance)."}],[{"k":"text","text":"ADR-033 — L0 foundational types (lives in the same crate)."}],[{"k":"text","text":"ADR-034 — L0.5 trait expansion ("},{"k":"code","text":"EmbeddingProvider"},{"k":"text","text":" consumes "},{"k":"code","text":"EmbeddingSpec"},{"k":"text","text":")."}],[{"k":"text","text":"FCI-035 addendum — Wave 4A/4B reservation catalog."}]]},{"k":"p","inline":[{"k":"text","text":"🦋"}]}]

ADR-029

EmbeddingSpec value-type reservation (Cortex seed)

accepted · 2026-04-17 · L0 L0.5 · cites 4

ADR-029: EmbeddingSpec value-type reservation (Cortex seed) #

Accepted 2026-07-11 (operator-delegated ADR ruling): the decision has been load-bearing in code since v0.81 and the reservation held its shape for three months — a proposed status no longer described reality. This prose replaces the Phase-C stub.

Context #

The memory/Connectome era needs embedding storage whose index layout and distance kernel are decided by three axes — dim, dtype, metric — plus the model identity that produced the vector. The embedding landscape moves monthly (Matryoshka truncation; 256→3072 dims; f32/f16/bf16/i8/binary dtypes; cosine/dot/euclidean/hamming metrics), so whatever type we reserve must be able to grow fields without a breaking-change migration.

Wave 4A R1 (commit 001ae0b6f, 2026-04-17) added EmbeddingSpec to nika-types (crates/nika-types/src/embedding.rs) as that reservation, per the ADR-028 forward-compat reservation policy.

Decision #

EmbeddingSpec ships in nika-types (L0) as #[non_exhaustive] with a ::new() constructor, carrying the (dim, dtype, metric, model_id) tuple:

dim / dtype / metric — exactly what HNSW/BM25/RRF backends need to pick index layout and distance kernel.
model_id optional — catalog-free consumers (tests, tools) construct a spec without materialising a provider name.
`#[non_exhaustive]` + `new()` — additive field evolution stays non-breaking by construction (INV-019 idiom); the reservation absorbs the monthly landscape drift instead of chasing it.

Field shape pinned in the commit body of 001ae0b6f and in the FCI-035 addendum of `docs/architecture/forward-compat-invariants.md`. EmbeddingProvider (ADR-034, L0.5) consumes the spec.

Alternatives considered #

No reservation — add the type when the first provider lands. Rejected: the Connectome consumers (index rehydration · cross-provider portability) would then force a breaking L0 change mid-era; ADR-028 exists precisely to pay this cost early and additively.
A wider spec (normalization · truncation · pooling fields now). Rejected: speculative fields rot; #[non_exhaustive] makes adding them when a real provider needs them a patch-level change.
String-typed axes. Rejected: dim/dtype/metric are closed vocabularies the kernel must match on — typed enums keep the distance-kernel dispatch total.

Empirical validation (why accepted now) #

Three months in production shape: the type is consumed, the field set never needed a change, and zero migrations were forced on dependents. The reservation did exactly what ADR-028 promised.