{"row":{"id":"ADR-125","title":"the native session is a grounded host runtime over the installed engine, never a workflow","file":"adr-125-native-session-runtime.md","status":"accepted","date":"2026-09-03","cites":8,"supersedes":[],"superseded_by":[],"layers":["L4"],"tags":["architecture","session","grounding","intelligence"],"room":true},"pin":{"release_tag":"v0.118.7","commit":"f3a31a6ee00766e4b010379c535bca994631d637"}}

[{"k":"h","depth":1,"text":"ADR-125: the native session is a grounded host runtime, never a workflow","id":"adr-125-the-native-session-is-a-grounded-host-runtime-never-a-workflow"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Bare "},{"k":"code","text":"nika"},{"k":"text","text":" opened a concierge card on every stream, and a hidden\n"},{"k":"code","text":"nika thread"},{"k":"text","text":" opened a conversation that was a proof of reuse and not a\nproduct: a hardcoded vendor model ("},{"k":"code","text":"xai/grok-4"},{"k":"text","text":"), a plaintext history\nfolded into one prompt, a temporary "},{"k":"code","text":"agent:"},{"k":"text","text":" workflow written to "},{"k":"code","text":"/tmp"},{"k":"text","text":"\nper turn with "},{"k":"code","text":"tools: []"},{"k":"text","text":" and "},{"k":"code","text":"permits: {}"},{"k":"text","text":", no grounding, no trace, no\nguard. The pack's failure transcript showed the consequence: asked to\nauthor a workflow, the model invented a JSON workflow language, confused\nNika with n8n, and finally claimed it did not know Nika. The one-door\npack's law: the native session must make that class of failure\nstructurally difficult, and it must be subject to Nika's own\ndata-boundary discipline before any workflow exists."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"A new L4 crate, `nika-session`, is the runtime."},{"k":"text","text":" It owns the\nconversation and nothing the engine already owns: the grammar, the\ncatalogs, the codes, the checker, the runtime and the project file\ngrammar are queried, never mirrored (the crate depends laterally on\n"},{"k":"code","text":"nika-cli-host"},{"k":"text","text":" for the ONE probe and the ONE oracle facade, ADR-124's\nprecedent)."}],[{"k":"strong","text":"The session observes the project once"},{"k":"text","text":" ("},{"k":"code","text":"ProjectSnapshot"},{"k":"text","text":": the\nproven root — the git root, else the working directory — the project\nfile and its ceiling, the workflows the ONE walker lists with the\nchecker's verdicts, honest about truncation)."}],[{"k":"strong","text":"The human chooses the intelligence"},{"k":"text","text":" on the first run, in the\natelier order and in human words (an AI app they already have · an\nAPI · a local engine · none); the choice is kept at\n"},{"k":"code","text":"~/.nika/session-intelligence.json"},{"k":"text","text":", shared by every install channel.\nThe census is deterministic (presence, never a dial, never a value).\nAn explicit choice this machine cannot serve is refused with its fix\nand never replaced. Each path names its data locus before the first\nturn."}],[{"k":"strong","text":"The reasoner is ONE inference over the chosen path"},{"k":"text","text":" — the same\ninfer-grade seat adapter "},{"k":"code","text":"nika run"},{"k":"text","text":" dispatches through, the same\nprovider registry and one-shot infer verb a workflow's "},{"k":"code","text":"infer:"},{"k":"text","text":"\nrides, or none. Never a temporary workflow, never a trace for a chat\nturn, never a hidden shell."}],[{"k":"strong","text":"The context broker hands the model a minimal typed bundle"},{"k":"text","text":": the\nidentity core (six laws) and the language digest, the snapshot's\ncompact facts, the snippets the HUMAN named (only "},{"k":"code","text":".nika.yaml"},{"k":"text","text":" and\n"},{"k":"code","text":"nika.yaml"},{"k":"text","text":", only inside the root, bounded, obvious secrets redacted\nwith the kinds recorded), the diagnostics, the recent dialogue. The\nenvironment is never injected. The model does not decide its own read\nboundary."}],[{"k":"strong","text":"Nika facts are answered by the engine before any model is asked"},{"k":"text","text":":\nthe workflows, the builtins, the providers, a workflow's verdict\nthrough the facade, a code through the explain ladder, a shape\nthrough the ONE router. A session without conversational intelligence\nstill answers them."}],[{"k":"strong","text":"Every reply is read by the hallucination guard"},{"k":"text","text":" before a human\nsees it: a "},{"k":"code","text":"nika:<builtin>"},{"k":"text","text":", a "},{"k":"code","text":"<provider>/<model>"},{"k":"text","text":", a "},{"k":"code","text":"NIKA-…"},{"k":"text","text":" code,\nan "},{"k":"code","text":"mcp:<server>"},{"k":"text","text":", a "},{"k":"code","text":"nika <verb>"},{"k":"text","text":" or a top-level workflow field the\nengine does not carry is corrected under the reply; a claim of\nignorance about Nika is corrected too. Nothing invented is presented\nas real."}],[{"k":"strong","text":"One door."},{"k":"text","text":" Bare "},{"k":"code","text":"nika"},{"k":"text","text":" on an interactive terminal enters the\nsession; a pipe keeps the deterministic concierge (exit 0). "},{"k":"code","text":"nika thread"},{"k":"text","text":" is deleted in the same change, with no alias."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The session is a product surface with a data boundary, not a chatbot\nover a workflow: what leaves the machine is the bundle, and the human\nread where it goes before typing."}],[{"k":"text","text":"Proof: the crate's tests (a turn writes nothing · the reasoner\nreceives only the bundle, redacted, never the environment · the\nseven inventions of the pack's adversarial corpus corrected · the\nunserved choice refused with its fix · the facts without any model ·\nthe preference round trip · the first screen in the atelier order);\n"},{"k":"code","text":"session_pty.rs"},{"k":"text","text":" on the real binary (the pipe is the concierge, the\nTTY is the session, the first run asks once, the kept choice never\nasks again, "},{"k":"code","text":"nika thread"},{"k":"text","text":" is the parser's own refusal)."}],[{"k":"text","text":"The concierge's "},{"k":"code","text":"nika thread"},{"k":"text","text":" teaching and the "},{"k":"code","text":"RunVerdict"},{"k":"text","text":" fields the\nthread alone read are gone (zero legacy)."}]]},{"k":"h","depth":2,"text":"Follow-ups","id":"follow-ups"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Wave 5: project changes authored from the session (preview → consent\n→ apply → the real check), run attachment, the human gate returning\nto the session as a pending decision."}],[{"k":"text","text":"The intelligence changed in-session ("},{"k":"code","text":"/intelligence"},{"k":"text","text":" re-asks)."}],[{"k":"text","text":"The language digest generated from the canon at build time."}]]}]

ADR-125

the native session is a grounded host runtime over the installed engine, never a workflow

accepted · 2026-09-03 · L4 · cites 8

ADR-125: the native session is a grounded host runtime, never a workflow #

Context #

Bare nika opened a concierge card on every stream, and a hidden nika thread opened a conversation that was a proof of reuse and not a product: a hardcoded vendor model (xai/grok-4), a plaintext history folded into one prompt, a temporary agent: workflow written to /tmp per turn with tools: [] and permits: {}, no grounding, no trace, no guard. The pack's failure transcript showed the consequence: asked to author a workflow, the model invented a JSON workflow language, confused Nika with n8n, and finally claimed it did not know Nika. The one-door pack's law: the native session must make that class of failure structurally difficult, and it must be subject to Nika's own data-boundary discipline before any workflow exists.

Decision #

A new L4 crate, `nika-session`, is the runtime. It owns the conversation and nothing the engine already owns: the grammar, the catalogs, the codes, the checker, the runtime and the project file grammar are queried, never mirrored (the crate depends laterally on nika-cli-host for the ONE probe and the ONE oracle facade, ADR-124's precedent).
The session observes the project once (ProjectSnapshot: the proven root — the git root, else the working directory — the project file and its ceiling, the workflows the ONE walker lists with the checker's verdicts, honest about truncation).
The human chooses the intelligence on the first run, in the atelier order and in human words (an AI app they already have · an API · a local engine · none); the choice is kept at ~/.nika/session-intelligence.json, shared by every install channel. The census is deterministic (presence, never a dial, never a value). An explicit choice this machine cannot serve is refused with its fix and never replaced. Each path names its data locus before the first turn.
The reasoner is ONE inference over the chosen path — the same infer-grade seat adapter nika run dispatches through, the same provider registry and one-shot infer verb a workflow's infer: rides, or none. Never a temporary workflow, never a trace for a chat turn, never a hidden shell.
The context broker hands the model a minimal typed bundle: the identity core (six laws) and the language digest, the snapshot's compact facts, the snippets the HUMAN named (only .nika.yaml and nika.yaml, only inside the root, bounded, obvious secrets redacted with the kinds recorded), the diagnostics, the recent dialogue. The environment is never injected. The model does not decide its own read boundary.
Nika facts are answered by the engine before any model is asked: the workflows, the builtins, the providers, a workflow's verdict through the facade, a code through the explain ladder, a shape through the ONE router. A session without conversational intelligence still answers them.
Every reply is read by the hallucination guard before a human sees it: a nika:<builtin>, a <provider>/<model>, a NIKA-… code, an mcp:<server>, a nika <verb> or a top-level workflow field the engine does not carry is corrected under the reply; a claim of ignorance about Nika is corrected too. Nothing invented is presented as real.
One door. Bare nika on an interactive terminal enters the session; a pipe keeps the deterministic concierge (exit 0). nika thread is deleted in the same change, with no alias.

Consequences #

The session is a product surface with a data boundary, not a chatbot over a workflow: what leaves the machine is the bundle, and the human read where it goes before typing.
Proof: the crate's tests (a turn writes nothing · the reasoner receives only the bundle, redacted, never the environment · the seven inventions of the pack's adversarial corpus corrected · the unserved choice refused with its fix · the facts without any model · the preference round trip · the first screen in the atelier order); session_pty.rs on the real binary (the pipe is the concierge, the TTY is the session, the first run asks once, the kept choice never asks again, nika thread is the parser's own refusal).
The concierge's nika thread teaching and the RunVerdict fields the thread alone read are gone (zero legacy).

Follow-ups #

Wave 5: project changes authored from the session (preview → consent → apply → the real check), run attachment, the human gate returning to the session as a pending decision.
The intelligence changed in-session (/intelligence re-asks).
The language digest generated from the canon at build time.

read at v0.118.7 · the decision record ships with the engine

Every decision, with its status This one in the repo