{"row":{"id":"ADR-085","title":"spec/workflow.schema.json invoke.tool oneOf · interim hand-derived bridge to engine schemars codegen","file":"adr-085-spec-schema-oneof-bridge-to-schemars-codegen.md","status":"accepted","date":"2026-05-27","cites":7,"supersedes":[],"superseded_by":[],"layers":["L0"],"tags":["nika-schema","nika-catalog","spec","json-schema"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-085 · spec workflow.schema.json oneOf · bridge to schemars codegen","id":"adr-085--spec-workflowschemajson-oneof--bridge-to-schemars-codegen"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"code","text":"nika/spec/schemas/workflow.schema.json"},{"k":"text","text":" ships the structural contract\nfor "},{"k":"code","text":"nika: v1"},{"k":"text","text":" workflow documents · consumed by JSON-Schema-aware tools\n(IDE plugins · yaml-language-server · CI validators · 3rd-party\nauthoring tooling)."}]},{"k":"p","inline":[{"k":"text","text":"Pre-this-ADR · the "},{"k":"code","text":"invoke.tool"},{"k":"text","text":" field was a permissive regex pattern ·"}]},{"k":"code","lang":"json","text":"\"tool\": {\n  \"type\": \"string\",\n  \"pattern\": \"^(nika|mcp):[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)*\u0024\"\n}"},{"k":"p","inline":[{"k":"text","text":"This permits ANY "},{"k":"code","text":"nika:<name>"},{"k":"text","text":" string. yaml-language-server (the canonical\nLSP backbone for VS Code · IntelliJ · Neovim) "},{"k":"strong","text":"cannot autocomplete from\nregex patterns"},{"k":"text","text":" · only from closed "},{"k":"code","text":"enum"},{"k":"text","text":" arrays per JSON-Schema 2020-12\nspec. The cookbook author writes "},{"k":"code","text":"tool: nika:"},{"k":"text","text":" and gets ZERO completion\nsuggestions · friction the new-author surface absorbs disproportionately."}]},{"k":"p","inline":[{"k":"text","text":"The G1 LSP-readiness research (per "},{"k":"code","text":"nika-lsp-readiness-design-v0.1"},{"k":"text","text":" ·\nD-2026-05-27-N2) established the central theorem · « one obvious way »\n(D-2026-05-22-N6 stdlib-collapse 42→26) IS « LSP-perfect » (closed\nfinite enumerable set) · they're the same property at different layers.\nThe catalog reconciliation (ADR-084) closed the engine-side · this ADR\ncloses the spec-side."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"code","text":"nika/spec/schemas/workflow.schema.json"},{"k":"text","text":" "},{"k":"code","text":"invoke.tool"},{"k":"text","text":" field splits from\nthe single regex pattern into a "},{"k":"code","text":"oneOf"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"nika branch"},{"k":"text","text":" · CLOSED enum of 26 canonical builtins (sorted\nalphabetically from "},{"k":"code","text":"nika/spec/stdlib/builtins-v0.1.md"},{"k":"text","text":" ·\n"},{"k":"code","text":"nika:assert"},{"k":"text","text":" · "},{"k":"code","text":"nika:cost"},{"k":"text","text":" · ... · "},{"k":"code","text":"nika:write"},{"k":"text","text":"). Enables\nyaml-language-server LSP-perfect autocomplete for any cookbook author."}],[{"k":"strong","text":"mcp branch"},{"k":"text","text":" · KEEPS the open regex pattern ("},{"k":"code","text":"^mcp:[a-z][a-z0-9_]* (/[a-z][a-z0-9_]*)*\u0024"},{"k":"text","text":") · MCP tool surface is external + plugin-dynamic ·\nclosed-enum is structurally impossible (each MCP server publishes its\nown dynamic catalog at runtime)."}]]},{"k":"p","inline":[{"k":"text","text":"Engine companion · "},{"k":"code","text":"nika-schema::codegen::nika_builtin_tool_enum_schema()"},{"k":"text","text":"\nemits the same enum "},{"k":"strong","text":"derived from"},{"k":"text","text":" "},{"k":"code","text":"nika_catalog::ALL_BUILTINS"},{"k":"text","text":" at\ncall time · the no-drift gate (spec hand-derived → engine catalog\ncanonical) is enforced by "},{"k":"code","text":"nika-schema/src/codegen.rs::tests:: enum_matches_catalog_one_to_one"},{"k":"text","text":"."}]},{"k":"h","depth":2,"text":"Why interim hand-derived (NOT engine-codegen output today)","id":"why-interim-hand-derived-not-engine-codegen-output-today"},{"k":"p","inline":[{"k":"text","text":"Per LOCK-031 trigger-gate discipline (no infra behind a locked gate)"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"scope-shrink (canon NOW · code DEFER per consumer signal) ·"}]]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"LSP value is operator-immediate"},{"k":"text","text":" · the hand-derived oneOf gives\nyaml-language-server consumers 100% of the LSP-completion value\nTODAY · zero engine-ship dependency · zero schemars adoption ·\nzero "},{"k":"code","text":"nika-schema-codegen"},{"k":"text","text":" xtask required."}],[{"k":"strong","text":"Schemars adoption requires nika-schema parser maturation"},{"k":"text","text":" · the\nfull G1 ratchet ("},{"k":"code","text":"WorkflowDocument"},{"k":"text","text":" Rust type with "},{"k":"code","text":"#[derive(JsonSchema)]"},{"k":"text","text":"+ `#[schemars(schema_with = ...)]` on the `tool` field) requires\nthe WIP nika-schema parser scaffolding to reach a complete\n`WorkflowDocument` shape · today nika-schema ships parser + raw + types\nmodules but the canonical document-level type is still maturing."}],[{"k":"strong","text":"The bridge is the right shape"},{"k":"text","text":" · per the schema file header comment\n(« INTERIM hand-derived schema · prose spec is the single source of\ntruth · regenerate + diff against engine "},{"k":"code","text":"nika-schema"},{"k":"text","text":" at GA ») · the\ndecision was always to hand-derive then codegen · this ADR locks the\ntransition mechanic."}]]},{"k":"h","depth":2,"text":"Future ratchet (trigger-gated)","id":"future-ratchet-trigger-gated"},{"k":"p","inline":[{"k":"text","text":"The full schemars-adoption G1 codegen (the « next ADR-086 » slot) ships\nwhen ALL of these trigger gates clear ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"nika-schema parser maturity"},{"k":"text","text":" · "},{"k":"code","text":"WorkflowDocument"},{"k":"text","text":" is the canonical\ndocument-level Rust type · all sub-types ("},{"k":"code","text":"Task"},{"k":"text","text":" · "},{"k":"code","text":"Verb"},{"k":"text","text":" · "},{"k":"code","text":"Invoke"},{"k":"text","text":" ·\n"},{"k":"code","text":"Agent"},{"k":"text","text":" · etc.) admitted into the public surface."}],[{"k":"strong","text":"Cookbook `\u0024schema` modeline adoption"},{"k":"text","text":" · ≥1 example in\n"},{"k":"code","text":"nika/spec/examples/"},{"k":"text","text":" carries "},{"k":"code","text":"# yaml-language-server: \u0024schema=..."},{"k":"text","text":"\npointing to "},{"k":"code","text":"workflow.schema.json"},{"k":"text","text":" · proving the LSP-consumer path\nis live."}],[{"k":"strong","text":"LSP UX feedback signal"},{"k":"text","text":" · ≥1 explicit operator-side incident OR\nfeature request citing « completion missed builtin X » OR\n« workflow schema autocomplete is the killer feature »."}],[{"k":"strong","text":"schemars 1.0 in workspace.dependencies"},{"k":"text","text":" · today absent · added\nonly when the full "},{"k":"code","text":"WorkflowDocument"},{"k":"text","text":" derive is shippable."}]]},{"k":"p","inline":[{"k":"text","text":"When all 4 clear · the future ADR-086 (or ADR-085 extension) authors ·"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-schema-codegen/"},{"k":"text","text":" xtask binary (or "},{"k":"code","text":"cargo run --bin nika-schema-codegen"},{"k":"text","text":") that emits "},{"k":"code","text":"workflow.schema.json"},{"k":"text","text":" from\n"},{"k":"code","text":"schema_for!(WorkflowDocument)"},{"k":"text","text":"."}],[{"k":"code","text":"nika-schema::codegen::nika_builtin_tool_enum_schema"},{"k":"text","text":" becomes the\n"},{"k":"code","text":"schema_with"},{"k":"text","text":" adapter consumed by schemars during the derive."}],[{"k":"text","text":"The hand-derived "},{"k":"code","text":"nika/spec/schemas/workflow.schema.json"},{"k":"text","text":" becomes a\nCHECK-IN CODEGEN OUTPUT (regenerable + diff-able · per Diamond Rule 7\nhallucination forbidden + Self-Evolving Olympus PILLAR 1 projection-\nby-default)."}],[{"k":"text","text":"Hygiene vector "},{"k":"code","text":"check-spec-schema-codegen-parity"},{"k":"text","text":" (P1/fail) verifies\nspec/schemas/workflow.schema.json matches the engine codegen output\nat commit time · structural no-drift gate."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"LSP value lands now"},{"k":"text","text":" · yaml-language-server autocompletes the 26\nbuiltins · zero engine dependency · operator wins immediately."}],[{"k":"strong","text":"No-drift property structural at engine layer"},{"k":"text","text":" ·\n"},{"k":"code","text":"nika_builtin_tool_enum_schema()"},{"k":"text","text":" reads "},{"k":"code","text":"ALL_BUILTINS"},{"k":"text","text":" at call time ·\ncatalog mutations propagate automatically · the 8 conformance tests\nin "},{"k":"code","text":"codegen.rs"},{"k":"text","text":" enforce parity (26 entries · alphabetically sorted ·\nprefixed "},{"k":"code","text":"nika:"},{"k":"text","text":" · matches catalog · includes canonical anchors ·\nexcludes legacy post-D-N6)."}],[{"k":"strong","text":"Bridge is publicly documented"},{"k":"text","text":" · the schema file header + this ADR"},{"k":"text","text":"+ `nika-schema::codegen` module doc all cross-reference the future\nratchet · no surprise transition when ADR-086 ships."}],[{"k":"strong","text":"Symbol seam established"},{"k":"text","text":" · "},{"k":"code","text":"pub fn nika_builtin_tool_enum_schema"},{"k":"text","text":"\nis the seam future schemars adoption plugs into ("},{"k":"code","text":"schema_with"},{"k":"text","text":"\nattribute target) · the migration is mechanical when triggered."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Spec ↔ engine sync is manual today"},{"k":"text","text":" · if "},{"k":"code","text":"ALL_BUILTINS"},{"k":"text","text":" mutates\n(e.g. spec adds 27th builtin via a future D-lock) · the spec schema's\nhand-derived enum must be regenerated manually · the engine no-drift\ntest catches the catalog side but NOT the schema-file side until the\nfuture hygiene vector ships."},{"k":"text","text":"- Mitigation · spec changes to builtins are extremely rare (governed\n  by D-locks per `nika/spec/stdlib/builtins-v0.1.md` § Promotion\n  criteria · the canon is « one obvious way » per D-N6).\n- Mitigation · `nika-schema::codegen::nika_builtin_tool_enum_schema`\n  PRINTS the canonical JSON-Schema fragment a maintainer can paste\n  into the spec schema (zero invention · just copy)."}],[{"k":"strong","text":"Schemars dep deferred"},{"k":"text","text":" · the full G1 codegen ratchet ships only\nwhen nika-schema parser matures + LSP UX signal · this is intentional\nscope-shrink, not weakness."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"L0 layer constraint preserved"},{"k":"text","text":" · "},{"k":"code","text":"codegen.rs"},{"k":"text","text":" is pure-Rust ·\nzero I/O · zero async · "},{"k":"code","text":"serde_json"},{"k":"text","text":" already in nika-schema deps ·\nno new crate · no L0 violation."}],[{"k":"strong","text":"Tests · +8 net new"},{"k":"text","text":" in "},{"k":"code","text":"nika-schema/src/codegen.rs::tests"},{"k":"text","text":" ·\nenum_has_26_entries · enum_alphabetically_sorted · enum_all_prefixed_with_nika ·\nenum_matches_catalog_one_to_one · schema_is_string_type · schema_has_description ·\nenum_includes_canonical_anchors · enum_excludes_legacy_post_d_n6."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"A · Generate workflow.schema.json from schemars NOW","id":"a--generate-workflowschemajson-from-schemars-now"},{"k":"p","inline":[{"k":"text","text":"REJECTED · requires "},{"k":"code","text":"WorkflowDocument"},{"k":"text","text":" Rust type maturation (nika-schema\nWIP) · scope creep + premature surface lock · LSP value lands without\nthis · scope-shrink discipline applies."}]},{"k":"h","depth":3,"text":"B · Keep regex pattern · accept zero LSP completion","id":"b--keep-regex-pattern--accept-zero-lsp-completion"},{"k":"p","inline":[{"k":"text","text":"REJECTED · the LSP-perfection theorem (D-2026-05-27-N2) established that\n« one obvious way » + closed-enum-schema = SAME PROPERTY · this ADR\nmaterializes the property at the spec surface."}]},{"k":"h","depth":3,"text":"C · Generate the schema fragment in a build.rs at engine build time","id":"c--generate-the-schema-fragment-in-a-buildrs-at-engine-build-time"},{"k":"p","inline":[{"k":"text","text":"REJECTED · engine build artifacts don't propagate to the spec submodule ·\nthe spec is a separate distribution · build.rs would be invisible to\nexternal schema consumers. The future codegen xtask (ADR-086) writes\nthe file at the spec submodule path · explicit + checked-in."}]},{"k":"h","depth":2,"text":"Gate verification","id":"gate-verification"},{"k":"p","inline":[{"k":"text","text":"This is a refactor of admitted-crate data + types (not a new crate\nadmission) · the ADR-003 12-gate ceremony reduces to applicable gates ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ Gate 2 TDD · 8 new conformance tests in "},{"k":"code","text":"codegen.rs"},{"k":"text","text":" · the no-drift\ngate ("},{"k":"code","text":"enum_matches_catalog_one_to_one"},{"k":"text","text":") is the canonical seam."}],[{"k":"text","text":"✅ Gate 3 IMPL · "},{"k":"code","text":"cargo check --workspace"},{"k":"text","text":" GREEN."}],[{"k":"text","text":"✅ Gate 4 CLIPPY · "},{"k":"code","text":"cargo clippy --workspace --all-targets -- -D warnings"},{"k":"text","text":" 0 warnings."}],[{"k":"text","text":"✅ Gate 8 DOCS · "},{"k":"code","text":"cargo doc --no-deps -p nika-schema"},{"k":"text","text":" 0 warnings."}],[{"k":"text","text":"✅ Gate 12 ATOMIC · single engine commit."}],[{"k":"code","text":"cargo fmt --check"},{"k":"text","text":" GREEN."}],[{"k":"code","text":"cargo deny check"},{"k":"text","text":" advisories+bans+licenses+sources ok."}],[{"k":"text","text":"Gates 1 / 5 / 6 / 7 / 9 / 10 / 11 · N/A for data refactor."}]]},{"k":"h","depth":2,"text":"Companion artefacts","id":"companion-artefacts"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-schema/src/codegen.rs"},{"k":"text","text":" · "},{"k":"code","text":"pub fn nika_builtin_tool_enum_schema"},{"k":"text","text":"+ 8 conformance tests · the engine-side no-drift gate."}],[{"k":"code","text":"nika-schema/src/lib.rs"},{"k":"text","text":" · module registration + re-export."}],[{"k":"code","text":"nika/spec/schemas/workflow.schema.json"},{"k":"text","text":" (separate submodule commit\n· invoke.tool oneOf · 26-builtin closed enum)."}],[{"k":"text","text":"Internal G1 design + closure artefacts in private monorepo (cited by\nD-id only · audit trail preserved at the source-of-truth surface)."}]]},{"k":"h","depth":2,"text":"References","id":"references"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-084 · nika-catalog reconciliation to spec 26 (prerequisite)"}],[{"k":"text","text":"ADR-082 · envelope "},{"k":"code","text":"nika: v1"},{"k":"text","text":" single-version-marker"}],[{"k":"code","text":"nika/spec/stdlib/builtins-v0.1.md"},{"k":"text","text":" · the canonical 26 source-of-truth"}],[{"k":"text","text":"Internal · D-2026-05-27-N2 LSP-perfection theorem (private blueprint)"}],[{"k":"text","text":"Internal · LOCK-031 trigger-gate discipline (private doctrine)"}],[{"k":"text","text":"Internal · scope-shrink discipline (canon NOW · code DEFER)"}],[{"k":"text","text":"Internal · cross-source-validation §2.6 Signal 7 (verify-the-auditor)"}]]},{"k":"p","inline":[{"k":"text","text":"🦋"}]}]

ADR-085

spec/workflow.schema.json invoke.tool oneOf · interim hand-derived bridge to engine schemars codegen

accepted · 2026-05-27 · L0 · cites 7

ADR-085 · spec workflow.schema.json oneOf · bridge to schemars codegen #

Context #

nika/spec/schemas/workflow.schema.json ships the structural contract for nika: v1 workflow documents · consumed by JSON-Schema-aware tools (IDE plugins · yaml-language-server · CI validators · 3rd-party authoring tooling).

Pre-this-ADR · the invoke.tool field was a permissive regex pattern ·

json

1"tool": {2  "type": "string",3  "pattern": "^(nika|mcp):[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)*$"4}

This permits ANY nika:<name> string. yaml-language-server (the canonical LSP backbone for VS Code · IntelliJ · Neovim) cannot autocomplete from regex patterns · only from closed enum arrays per JSON-Schema 2020-12 spec. The cookbook author writes tool: nika: and gets ZERO completion suggestions · friction the new-author surface absorbs disproportionately.

The G1 LSP-readiness research (per nika-lsp-readiness-design-v0.1 · D-2026-05-27-N2) established the central theorem · « one obvious way » (D-2026-05-22-N6 stdlib-collapse 42→26) IS « LSP-perfect » (closed finite enumerable set) · they're the same property at different layers. The catalog reconciliation (ADR-084) closed the engine-side · this ADR closes the spec-side.

Decision #

nika/spec/schemas/workflow.schema.json invoke.tool field splits from the single regex pattern into a oneOf ·

nika branch · CLOSED enum of 26 canonical builtins (sorted alphabetically from nika/spec/stdlib/builtins-v0.1.md · nika:assert · nika:cost · ... · nika:write). Enables yaml-language-server LSP-perfect autocomplete for any cookbook author.
mcp branch · KEEPS the open regex pattern (^mcp:[a-z][a-z0-9_]* (/[a-z][a-z0-9_]*)*$) · MCP tool surface is external + plugin-dynamic · closed-enum is structurally impossible (each MCP server publishes its own dynamic catalog at runtime).

Engine companion · nika-schema::codegen::nika_builtin_tool_enum_schema() emits the same enum derived from nika_catalog::ALL_BUILTINS at call time · the no-drift gate (spec hand-derived → engine catalog canonical) is enforced by nika-schema/src/codegen.rs::tests:: enum_matches_catalog_one_to_one.

Why interim hand-derived (NOT engine-codegen output today) #

Per LOCK-031 trigger-gate discipline (no infra behind a locked gate)

scope-shrink (canon NOW · code DEFER per consumer signal) ·

LSP value is operator-immediate · the hand-derived oneOf gives yaml-language-server consumers 100% of the LSP-completion value TODAY · zero engine-ship dependency · zero schemars adoption · zero nika-schema-codegen xtask required.
Schemars adoption requires nika-schema parser maturation · the full G1 ratchet (WorkflowDocument Rust type with #[derive(JsonSchema)]+ `#[schemars(schema_with = ...)]` on the `tool` field) requires the WIP nika-schema parser scaffolding to reach a complete `WorkflowDocument` shape · today nika-schema ships parser + raw + types modules but the canonical document-level type is still maturing.
The bridge is the right shape · per the schema file header comment (« INTERIM hand-derived schema · prose spec is the single source of truth · regenerate + diff against engine nika-schema at GA ») · the decision was always to hand-derive then codegen · this ADR locks the transition mechanic.

Future ratchet (trigger-gated) #

The full schemars-adoption G1 codegen (the « next ADR-086 » slot) ships when ALL of these trigger gates clear ·

nika-schema parser maturity · WorkflowDocument is the canonical document-level Rust type · all sub-types (Task · Verb · Invoke · Agent · etc.) admitted into the public surface.
Cookbook `$schema` modeline adoption · ≥1 example in nika/spec/examples/ carries # yaml-language-server: $schema=... pointing to workflow.schema.json · proving the LSP-consumer path is live.
LSP UX feedback signal · ≥1 explicit operator-side incident OR feature request citing « completion missed builtin X » OR « workflow schema autocomplete is the killer feature ».
schemars 1.0 in workspace.dependencies · today absent · added only when the full WorkflowDocument derive is shippable.

When all 4 clear · the future ADR-086 (or ADR-085 extension) authors ·

crates/nika-schema-codegen/ xtask binary (or cargo run --bin nika-schema-codegen) that emits workflow.schema.json from schema_for!(WorkflowDocument).
nika-schema::codegen::nika_builtin_tool_enum_schema becomes the schema_with adapter consumed by schemars during the derive.
The hand-derived nika/spec/schemas/workflow.schema.json becomes a CHECK-IN CODEGEN OUTPUT (regenerable + diff-able · per Diamond Rule 7 hallucination forbidden + Self-Evolving Olympus PILLAR 1 projection- by-default).
Hygiene vector check-spec-schema-codegen-parity (P1/fail) verifies spec/schemas/workflow.schema.json matches the engine codegen output at commit time · structural no-drift gate.

Consequences #

Positive #

LSP value lands now · yaml-language-server autocompletes the 26 builtins · zero engine dependency · operator wins immediately.
No-drift property structural at engine layer · nika_builtin_tool_enum_schema() reads ALL_BUILTINS at call time · catalog mutations propagate automatically · the 8 conformance tests in codegen.rs enforce parity (26 entries · alphabetically sorted · prefixed nika: · matches catalog · includes canonical anchors · excludes legacy post-D-N6).
Bridge is publicly documented · the schema file header + this ADR+ `nika-schema::codegen` module doc all cross-reference the future ratchet · no surprise transition when ADR-086 ships.
Symbol seam established · pub fn nika_builtin_tool_enum_schema is the seam future schemars adoption plugs into (schema_with attribute target) · the migration is mechanical when triggered.

Negative #

Spec ↔ engine sync is manual today · if ALL_BUILTINS mutates (e.g. spec adds 27th builtin via a future D-lock) · the spec schema's hand-derived enum must be regenerated manually · the engine no-drift test catches the catalog side but NOT the schema-file side until the future hygiene vector ships.- Mitigation · spec changes to builtins are extremely rare (governed by D-locks per `nika/spec/stdlib/builtins-v0.1.md` § Promotion criteria · the canon is « one obvious way » per D-N6). - Mitigation · `nika-schema::codegen::nika_builtin_tool_enum_schema` PRINTS the canonical JSON-Schema fragment a maintainer can paste into the spec schema (zero invention · just copy).
Schemars dep deferred · the full G1 codegen ratchet ships only when nika-schema parser matures + LSP UX signal · this is intentional scope-shrink, not weakness.

Neutral #

L0 layer constraint preserved · codegen.rs is pure-Rust · zero I/O · zero async · serde_json already in nika-schema deps · no new crate · no L0 violation.
Tests · +8 net new in nika-schema/src/codegen.rs::tests · enum_has_26_entries · enum_alphabetically_sorted · enum_all_prefixed_with_nika · enum_matches_catalog_one_to_one · schema_is_string_type · schema_has_description · enum_includes_canonical_anchors · enum_excludes_legacy_post_d_n6.

Alternatives considered #

A · Generate workflow.schema.json from schemars NOW #

REJECTED · requires WorkflowDocument Rust type maturation (nika-schema WIP) · scope creep + premature surface lock · LSP value lands without this · scope-shrink discipline applies.

B · Keep regex pattern · accept zero LSP completion #

REJECTED · the LSP-perfection theorem (D-2026-05-27-N2) established that « one obvious way » + closed-enum-schema = SAME PROPERTY · this ADR materializes the property at the spec surface.

C · Generate the schema fragment in a build.rs at engine build time #

REJECTED · engine build artifacts don't propagate to the spec submodule · the spec is a separate distribution · build.rs would be invisible to external schema consumers. The future codegen xtask (ADR-086) writes the file at the spec submodule path · explicit + checked-in.

Gate verification #

This is a refactor of admitted-crate data + types (not a new crate admission) · the ADR-003 12-gate ceremony reduces to applicable gates ·

✅ Gate 2 TDD · 8 new conformance tests in codegen.rs · the no-drift gate (enum_matches_catalog_one_to_one) is the canonical seam.
✅ Gate 3 IMPL · cargo check --workspace GREEN.
✅ Gate 4 CLIPPY · cargo clippy --workspace --all-targets -- -D warnings 0 warnings.
✅ Gate 8 DOCS · cargo doc --no-deps -p nika-schema 0 warnings.
✅ Gate 12 ATOMIC · single engine commit.
cargo fmt --check GREEN.
cargo deny check advisories+bans+licenses+sources ok.
Gates 1 / 5 / 6 / 7 / 9 / 10 / 11 · N/A for data refactor.

Companion artefacts #

nika-schema/src/codegen.rs · pub fn nika_builtin_tool_enum_schema+ 8 conformance tests · the engine-side no-drift gate.
nika-schema/src/lib.rs · module registration + re-export.
nika/spec/schemas/workflow.schema.json (separate submodule commit · invoke.tool oneOf · 26-builtin closed enum).
Internal G1 design + closure artefacts in private monorepo (cited by D-id only · audit trail preserved at the source-of-truth surface).

References #

ADR-084 · nika-catalog reconciliation to spec 26 (prerequisite)
ADR-082 · envelope nika: v1 single-version-marker
nika/spec/stdlib/builtins-v0.1.md · the canonical 26 source-of-truth
Internal · D-2026-05-27-N2 LSP-perfection theorem (private blueprint)
Internal · LOCK-031 trigger-gate discipline (private doctrine)
Internal · scope-shrink discipline (canon NOW · code DEFER)
Internal · cross-source-validation §2.6 Signal 7 (verify-the-auditor)

🦋

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

Every decision, with its status This one in the repo