{"row":{"id":"ADR-031","title":"RecallQuery.tenant reservation (multi-tenant keyspace seed)","file":"adr-031-recall-query-tenant-keyspace.md","status":"accepted","date":"2026-04-17","cites":6,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5"],"tags":["l0","cortex","multi-tenant","tenant-id"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-031: RecallQuery.tenant reservation (multi-tenant keyspace seed)","id":"adr-031-recallquerytenant-reservation-multi-tenant-keyspace-seed"},{"k":"p","inline":[{"k":"text","text":"Status flipped "},{"k":"code","text":"proposed → accepted"},{"k":"text","text":" 2026-07-12 under the merged-code\nrule (the #474 ADR ruling): the decision is load-bearing in shipped\ncode — "},{"k":"code","text":"RecallQuery.tenant"},{"k":"text","text":" exists, is mandatory, and every recall\nscope flows through it. The prose documents what IS, including where\nthe shipped shape deliberately hardened beyond the original seed."}]},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Wave 4A R3 (commit "},{"k":"code","text":"41e8a1467"},{"k":"text","text":", 2026-04-17) reserved a tenant keyspace\non "},{"k":"code","text":"RecallQuery"},{"k":"text","text":" so multi-tenant recall can ship later without a\nbreaking change (ADR-028 reservation policy). The reservation exists so\nthat a v0.8x consumer compiled against a single-tenant world keeps\nworking the day a multi-tenant host arrives — and so that cross-tenant\nreads are structurally impossible rather than policy-forbidden."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"RecallQuery"},{"k":"text","text":" carries "},{"k":"code","text":"pub tenant: TenantId"},{"k":"text","text":"\n("},{"k":"code","text":"nika-kernel-ai/src/memory.rs"},{"k":"text","text":" — re-exported through "},{"k":"code","text":"nika-kernel"},{"k":"text","text":")\n— "},{"k":"strong","text":"mandatory, not `Option`"},{"k":"text","text":". The original seed sketched\n"},{"k":"code","text":"Option<TenantId>"},{"k":"text","text":" with "},{"k":"code","text":"None"},{"k":"text","text":" = default; the shipped shape hardened:\nan optional tenant invites every store impl to invent its own "},{"k":"code","text":"None"},{"k":"text","text":"\npolicy, which is exactly how cross-tenant leaks are born. Instead:"},{"k":"text","text":"- `RecallQuery::new(…)` scopes to `TenantId::default_tenant()` —\n  single-tenant deployments use it and never think about the field;\n- `RecallQuery::scoped(tenant, …)` is the multi-tenant constructor;\n- every recall MUST scope by the field (the struct doc states the\n  contract; store impls return only same-tenant frames)."}],[{"k":"text","text":"The struct is "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" with constructor discipline\n(FCI invariant #19), so later filters (the "},{"k":"code","text":"observed_after/_before"},{"k":"text","text":"\ntemporal pair rode in on the same shape) land without a major."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"`Option<TenantId>`, `None` = default tenant"},{"k":"text","text":" (the seed's sketch) —\nrejected at hardening: per-impl "},{"k":"code","text":"None"},{"k":"text","text":" policies are the leak vector;\na mandatory field with a defaulting constructor gives the same\nsingle-tenant ergonomics with ONE policy instead of N."}],[{"k":"strong","text":"Tenant as a store-construction parameter only"},{"k":"text","text":" — rejected: it\nforces one store instance per tenant (hosts want pooled stores) and\nremoves the per-query audit trail."}],[{"k":"strong","text":"No reservation until multi-tenant ships"},{"k":"text","text":" — rejected per ADR-028:\nadding a mandatory field to a serialized, cross-layer query type\nlater is the breaking change the policy exists to prevent."}]]},{"k":"h","depth":2,"text":"Empirical validation (what makes this \"merged code\")","id":"empirical-validation-what-makes-this-merged-code"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-kernel-ai/src/memory.rs"},{"k":"text","text":" — the field with its mandatory-scope\ncontract in the struct docs, "},{"k":"code","text":"new()"},{"k":"text","text":" defaulting to\n"},{"k":"code","text":"TenantId::default_tenant()"},{"k":"text","text":" (line 113), "},{"k":"code","text":"scoped()"},{"k":"text","text":" for multi-tenant\nhosts (line 119)."}],[{"k":"code","text":"TenantId"},{"k":"text","text":" lives beside the provider types (ADR-033's family) and\nserializes with the query."}],[{"k":"text","text":"The mock kernel exercises the same shape — recall tests construct\nqueries through the defaulting constructor."}]]},{"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-030 — "},{"k":"code","text":"MemoryFrameRef.trust"},{"k":"text","text":" (the sibling Wave 4A reservation —\ntrust gates what a recall may spotlight; tenant gates what it may see)."}],[{"k":"text","text":"ADR-033 — "},{"k":"code","text":"TenantId"},{"k":"text","text":" newtype + "},{"k":"code","text":"default_tenant()"},{"k":"text","text":"."}],[{"k":"text","text":"ADR-034 — "},{"k":"code","text":"MemoryStore::recall"},{"k":"text","text":" signature (tenant flows through)."}],[{"k":"text","text":"FCI-035 addendum — Wave 4A/4B reservation catalog."}]]},{"k":"p","inline":[{"k":"text","text":"🦋"}]}]

ADR-031

RecallQuery.tenant reservation (multi-tenant keyspace seed)

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

ADR-031: RecallQuery.tenant reservation (multi-tenant keyspace seed) #

Status flipped proposed → accepted 2026-07-12 under the merged-code rule (the #474 ADR ruling): the decision is load-bearing in shipped code — RecallQuery.tenant exists, is mandatory, and every recall scope flows through it. The prose documents what IS, including where the shipped shape deliberately hardened beyond the original seed.

Context #

Wave 4A R3 (commit 41e8a1467, 2026-04-17) reserved a tenant keyspace on RecallQuery so multi-tenant recall can ship later without a breaking change (ADR-028 reservation policy). The reservation exists so that a v0.8x consumer compiled against a single-tenant world keeps working the day a multi-tenant host arrives — and so that cross-tenant reads are structurally impossible rather than policy-forbidden.

Decision #

RecallQuery carries pub tenant: TenantId (nika-kernel-ai/src/memory.rs — re-exported through nika-kernel) — mandatory, not `Option`. The original seed sketched Option<TenantId> with None = default; the shipped shape hardened: an optional tenant invites every store impl to invent its own None policy, which is exactly how cross-tenant leaks are born. Instead:- `RecallQuery::new(…)` scopes to `TenantId::default_tenant()` — single-tenant deployments use it and never think about the field; - `RecallQuery::scoped(tenant, …)` is the multi-tenant constructor; - every recall MUST scope by the field (the struct doc states the contract; store impls return only same-tenant frames).
The struct is #[non_exhaustive] with constructor discipline (FCI invariant #19), so later filters (the observed_after/_before temporal pair rode in on the same shape) land without a major.

Alternatives considered #

`Option<TenantId>`, `None` = default tenant (the seed's sketch) — rejected at hardening: per-impl None policies are the leak vector; a mandatory field with a defaulting constructor gives the same single-tenant ergonomics with ONE policy instead of N.
Tenant as a store-construction parameter only — rejected: it forces one store instance per tenant (hosts want pooled stores) and removes the per-query audit trail.
No reservation until multi-tenant ships — rejected per ADR-028: adding a mandatory field to a serialized, cross-layer query type later is the breaking change the policy exists to prevent.

Empirical validation (what makes this "merged code") #

nika-kernel-ai/src/memory.rs — the field with its mandatory-scope contract in the struct docs, new() defaulting to TenantId::default_tenant() (line 113), scoped() for multi-tenant hosts (line 119).
TenantId lives beside the provider types (ADR-033's family) and serializes with the query.
The mock kernel exercises the same shape — recall tests construct queries through the defaulting constructor.