{"row":{"id":"ADR-124","title":"one typed oracle facade: the CLI verb, the MCP tool and the session read the same audit","file":"adr-124-one-oracle-facade.md","status":"accepted","date":"2026-09-03","cites":4,"supersedes":[],"superseded_by":[],"layers":["L4"],"tags":["architecture","oracle","mcp","check"],"room":true},"pin":{"release_tag":"v0.118.7","commit":"f3a31a6ee00766e4b010379c535bca994631d637"}}

[{"k":"h","depth":1,"text":"ADR-124: one typed oracle facade","id":"adr-124-one-typed-oracle-facade"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The static audit had two machine doors and two implementations. The CLI\nverb ("},{"k":"code","text":"nika check --json"},{"k":"text","text":") judged through "},{"k":"code","text":"check_composed"},{"k":"text","text":" with a\nfilesystem reader, folded skills, drift, the access plan, pricing, the\nbudget and the engine identity, and judged a templated "},{"k":"code","text":"model:"},{"k":"text","text":" by its\ndeclared default. The MCP tool ("},{"k":"code","text":"nika_check"},{"k":"text","text":") judged through the pure\n"},{"k":"code","text":"check"},{"k":"text","text":", carried its own "},{"k":"code","text":"model_crosscheck"},{"k":"text","text":" (a hand-written twin of the\nCLI's rung that did not know templated seats), its own verdict prose and\nits own explain ladder, and its "},{"k":"code","text":"fix: true"},{"k":"text","text":" walked the repair ladder\nWITHOUT the CLI's prepass (a bare "},{"k":"code","text":"exec:"},{"k":"text","text":" scalar · a "},{"k":"code","text":"needs:"},{"k":"text","text":" list) while\nits description claimed « the same ladder ». Census D of the one-door\narc counted the drift: the two lanes agreed on five keys and disagreed\non twelve, and the pack's oracle law (pack 12 §9) reads:"}]},{"k":"quote","inline":[{"k":"text","text":"Direct capability result ≈ CLI machine projection ≈ MCP tool semantic\nresult, for the same input. Projection formatting can differ. Semantic\nverdict must not."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"`nika_cli_host::oracle` is the ONE audit."},{"k":"text","text":" "},{"k":"code","text":"audit_source"},{"k":"text","text":" parses,\njudges (composed when a reader is given · child-blind when it is not,\nand the verdict SAYS which), resolves the frozen access plan\n(ADR-122), folds the MODELS rung (resolution · thinking · capacity ·\nthe templated-default law), the skills, the four layered verdicts\n(ADR-123) and the risk grade into a typed "},{"k":"code","text":"Audit"},{"k":"text","text":". "},{"k":"code","text":"audit_json"},{"k":"text","text":"\nprojects the ONE verdict object every machine lane emits."}],[{"k":"strong","text":"The CLI verb and the MCP tool are projections of that `Audit`."},{"k":"text","text":"\n"},{"k":"code","text":"check --json"},{"k":"text","text":" is "},{"k":"code","text":"audit_json"},{"k":"text","text":" plus the CLI's own decorations (the\nambient budget it can see from its cwd, the engine identity). The\nMCP "},{"k":"code","text":"nika_check"},{"k":"text","text":" result is "},{"k":"code","text":"audit_json"},{"k":"text","text":" plus "},{"k":"code","text":"next_actions"},{"k":"text","text":"; its\ngreen text is rendered from the same "},{"k":"code","text":"Audit"},{"k":"text","text":". "},{"k":"code","text":"model_crosscheck"},{"k":"text","text":" is\ndeleted. The MCP lane reads "},{"k":"code","text":"composition_judged: false"},{"k":"text","text":" (it has no\nfilesystem) instead of claiming a composed workflow clean."}],[{"k":"strong","text":"One repair ladder."},{"k":"text","text":" The prepass ("},{"k":"code","text":"apply_prepass"},{"k":"text","text":": the bare "},{"k":"code","text":"exec:"},{"k":"text","text":"\nscalar · the "},{"k":"code","text":"needs:"},{"k":"text","text":" list) moves beside the ladder in\n"},{"k":"code","text":"nika_cli_host::fix_ladder"},{"k":"text","text":"; the MCP "},{"k":"code","text":"fix: true"},{"k":"text","text":" runs it first, so\n« the same ladder » is true."}],[{"k":"strong","text":"One explain ladder."},{"k":"text","text":" "},{"k":"code","text":"nika_cli_host::explain::explain(code)"},{"k":"text","text":" is\nthe four-rung ladder (hint kinds · the registry · the spec rows · the\nnamespaces); the CLI renders it with its theme, the MCP tool returns\nit verbatim."}],[{"k":"strong","text":"The plugin's teaching surface is derived, never typed."},{"k":"text","text":" A test\npins every example slug the engine-owned plugin teaches to\n"},{"k":"code","text":"nika_pack::example_slugs()"},{"k":"text","text":"; the six dead slugs it taught are gone."}],[{"k":"strong","text":"The oracle stays read-only"},{"k":"text","text":" (pack 12 §6 · #1303's wall). It learns\nRUN READY (the four verdicts ride the MCP payload — presence on THIS\nmachine, never a dial) but never gains an execution verb."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"An agent through the oracle and an operator at the CLI read the same\nverdict for the same bytes; a divergence is a failing test, not a\ngauntlet finding."}],[{"k":"text","text":"Proof: "},{"k":"code","text":"crates/nika-cli/tests/oracle_parity_e2e.rs"},{"k":"text","text":" drives the three\ndoors on the same fixtures (a clean file · a dirty file · a\nhallucinated model · a templated default · a capacity cap · a\nnative-first exec under strict) and compares the semantic keys\n("},{"k":"code","text":"clean"},{"k":"text","text":" · "},{"k":"code","text":"findings[].code"},{"k":"text","text":" · "},{"k":"code","text":"models_resolve"},{"k":"text","text":" · "},{"k":"code","text":"model_findings"},{"k":"text","text":" ·\n"},{"k":"code","text":"models_catalog_warnings"},{"k":"text","text":" · "},{"k":"code","text":"verdicts"},{"k":"text","text":" · "},{"k":"code","text":"risk_grade"},{"k":"text","text":" · "},{"k":"code","text":"paid_ready"},{"k":"text","text":");\nthe MCP door is driven over the real stdio transport. The host's\nfacade tests · the MCP repair tests now assert the prepass · the\nplugin slug test."}],[{"k":"code","text":"REPORT_VERSION"},{"k":"text","text":" stays 1: every key is additive ("},{"k":"code","text":"composition_judged"},{"k":"text","text":"\n· "},{"k":"code","text":"next_actions"},{"k":"text","text":" on the CLI lane · "},{"k":"code","text":"verdicts"},{"k":"text","text":" and "},{"k":"code","text":"access_plan"},{"k":"text","text":" on the\nMCP lane)."}]]},{"k":"h","depth":2,"text":"Amendments","id":"amendments"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Wave 3.b (the W3 gauntlet · 2026-09-03): the oracle's clean answer\nnames the child workflows it did not read ("},{"k":"code","text":"judged.children"},{"k":"text","text":" · a prose\nline on the clean lane), "},{"k":"code","text":"verbose: true"},{"k":"text","text":" returns the verdict object on\na clean answer, and "},{"k":"code","text":"next_actions"},{"k":"text","text":" name "},{"k":"code","text":"nika_explain"},{"k":"text","text":" — the door an\nagent without a shell can open."}]]},{"k":"h","depth":2,"text":"Follow-ups","id":"follow-ups"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The session (wave 4) grounds itself on the facade directly — the\ncapability registry path of pack 12 §3, never a JSON-RPC round trip."}],[{"k":"text","text":"The LSP diagnostics lane folds the same "},{"k":"code","text":"Audit"},{"k":"text","text":"."}]]}]

ADR-124

one typed oracle facade: the CLI verb, the MCP tool and the session read the same audit

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

ADR-124: one typed oracle facade #

Context #

The static audit had two machine doors and two implementations. The CLI verb (nika check --json) judged through check_composed with a filesystem reader, folded skills, drift, the access plan, pricing, the budget and the engine identity, and judged a templated model: by its declared default. The MCP tool (nika_check) judged through the pure check, carried its own model_crosscheck (a hand-written twin of the CLI's rung that did not know templated seats), its own verdict prose and its own explain ladder, and its fix: true walked the repair ladder WITHOUT the CLI's prepass (a bare exec: scalar · a needs: list) while its description claimed « the same ladder ». Census D of the one-door arc counted the drift: the two lanes agreed on five keys and disagreed on twelve, and the pack's oracle law (pack 12 §9) reads:

Direct capability result ≈ CLI machine projection ≈ MCP tool semantic result, for the same input. Projection formatting can differ. Semantic verdict must not.

Decision #

`nika_cli_host::oracle` is the ONE audit. audit_source parses, judges (composed when a reader is given · child-blind when it is not, and the verdict SAYS which), resolves the frozen access plan (ADR-122), folds the MODELS rung (resolution · thinking · capacity · the templated-default law), the skills, the four layered verdicts (ADR-123) and the risk grade into a typed Audit. audit_json projects the ONE verdict object every machine lane emits.
The CLI verb and the MCP tool are projections of that `Audit`. check --json is audit_json plus the CLI's own decorations (the ambient budget it can see from its cwd, the engine identity). The MCP nika_check result is audit_json plus next_actions; its green text is rendered from the same Audit. model_crosscheck is deleted. The MCP lane reads composition_judged: false (it has no filesystem) instead of claiming a composed workflow clean.
One repair ladder. The prepass (apply_prepass: the bare exec: scalar · the needs: list) moves beside the ladder in nika_cli_host::fix_ladder; the MCP fix: true runs it first, so « the same ladder » is true.
One explain ladder. nika_cli_host::explain::explain(code) is the four-rung ladder (hint kinds · the registry · the spec rows · the namespaces); the CLI renders it with its theme, the MCP tool returns it verbatim.
The plugin's teaching surface is derived, never typed. A test pins every example slug the engine-owned plugin teaches to nika_pack::example_slugs(); the six dead slugs it taught are gone.
The oracle stays read-only (pack 12 §6 · #1303's wall). It learns RUN READY (the four verdicts ride the MCP payload — presence on THIS machine, never a dial) but never gains an execution verb.

Consequences #

An agent through the oracle and an operator at the CLI read the same verdict for the same bytes; a divergence is a failing test, not a gauntlet finding.
Proof: crates/nika-cli/tests/oracle_parity_e2e.rs drives the three doors on the same fixtures (a clean file · a dirty file · a hallucinated model · a templated default · a capacity cap · a native-first exec under strict) and compares the semantic keys (clean · findings[].code · models_resolve · model_findings · models_catalog_warnings · verdicts · risk_grade · paid_ready); the MCP door is driven over the real stdio transport. The host's facade tests · the MCP repair tests now assert the prepass · the plugin slug test.
REPORT_VERSION stays 1: every key is additive (composition_judged · next_actions on the CLI lane · verdicts and access_plan on the MCP lane).

Amendments #

Wave 3.b (the W3 gauntlet · 2026-09-03): the oracle's clean answer names the child workflows it did not read (judged.children · a prose line on the clean lane), verbose: true returns the verdict object on a clean answer, and next_actions name nika_explain — the door an agent without a shell can open.

Follow-ups #

The session (wave 4) grounds itself on the facade directly — the capability registry path of pack 12 §3, never a JSON-RPC round trip.
The LSP diagnostics lane folds the same Audit.

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

Every decision, with its status This one in the repo