{"row":{"id":"ADR-088","title":"nika:cost + records + dag_info + threads → nika:inspect · introspection Rams collapse","file":"adr-088-nika-inspect-introspection-collapse.md","status":"accepted","date":"2026-05-27","cites":9,"supersedes":[],"superseded_by":[],"layers":["L0"],"tags":["nika-catalog","nika-schema","stdlib","builtins"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-088 · 4 introspection builtins → nika:inspect","id":"adr-088--4-introspection-builtins--nikainspect"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Operator-led Rams audit 2026-05-27 of the canonical builtin set\nidentified the 4 introspection primitives as a Rams collapse candidate ·"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika:cost"},{"k":"text","text":" → "},{"k":"code","text":"{ total_usd, by_task, by_provider }"},{"k":"text","text":" · workflow cost"}],[{"k":"code","text":"nika:records"},{"k":"text","text":" → "},{"k":"code","text":"{ tasks: [{ id, status, duration_ms, ... }] }"},{"k":"text","text":" · execution record"}],[{"k":"code","text":"nika:dag_info"},{"k":"text","text":" → "},{"k":"code","text":"{ nodes, edges, waves }"},{"k":"text","text":" · DAG topology"}],[{"k":"code","text":"nika:threads"},{"k":"text","text":" → "},{"k":"code","text":"{ active, queued, completed }"},{"k":"text","text":" · task-pool state"}]]},{"k":"p","inline":[{"k":"text","text":"All 4 are PURE trust · pure-compute queries of own workflow state · same\nsemantic family. The split into 4 separate builtins was historical\n(one-per-return-shape) not structural. ADR-088 unifies them into a\nsingle view-discriminated "},{"k":"code","text":"nika:inspect"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"This is the 4th and most ambitious Rams collapse in the operator-led\nsweep · completes the « one super-powerful builtin · multi-mode args »\nsymmetry across 5 distinct domains."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"code","text":"nika:cost"},{"k":"text","text":" · "},{"k":"code","text":"nika:records"},{"k":"text","text":" · "},{"k":"code","text":"nika:dag_info"},{"k":"text","text":" · "},{"k":"code","text":"nika:threads"},{"k":"text","text":" removed ·\n"},{"k":"code","text":"nika:inspect"},{"k":"text","text":" adopted as unified introspection builtin with "},{"k":"code","text":"view:"},{"k":"text","text":"\nenum discriminator."}]},{"k":"h","depth":3,"text":"`nika:inspect` surface","id":"nikainspect-surface"},{"k":"code","lang":"yaml","text":"invoke:\n  tool: \"nika:inspect\"\n  args:\n    view: cost                     # REQUIRED · enum · cost | records | dag_info | threads"},{"k":"h","depth":3,"text":"Per-view return shapes","id":"per-view-return-shapes"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"view: cost"},{"k":"text","text":" → "},{"k":"code","text":"{ total_usd, by_task, by_provider }"},{"k":"text","text":" (sleep equivalent of legacy "},{"k":"code","text":"nika:cost"},{"k":"text","text":")"}],[{"k":"code","text":"view: records"},{"k":"text","text":" → "},{"k":"code","text":"{ tasks: [{ id, status, duration_ms, ... }] }"},{"k":"text","text":" (legacy "},{"k":"code","text":"nika:records"},{"k":"text","text":")"}],[{"k":"code","text":"view: dag_info"},{"k":"text","text":" → "},{"k":"code","text":"{ nodes, edges, waves }"},{"k":"text","text":" (legacy "},{"k":"code","text":"nika:dag_info"},{"k":"text","text":")"}],[{"k":"code","text":"view: threads"},{"k":"text","text":" → "},{"k":"code","text":"{ active, queued, completed }"},{"k":"text","text":" · advisory (legacy "},{"k":"code","text":"nika:threads"},{"k":"text","text":")"}]]},{"k":"h","depth":3,"text":"Validation","id":"validation"},{"k":"p","inline":[{"k":"text","text":"Parse-time check · "},{"k":"code","text":"view:"},{"k":"text","text":" MUST be one of the 4 canonical enum values.\nEngine returns "},{"k":"code","text":"NIKA-BUILTIN-INSPECT-001"},{"k":"text","text":" if "},{"k":"code","text":"view:"},{"k":"text","text":" value not in the\ncanonical set."}]},{"k":"h","depth":3,"text":"Engine catalog mutation","id":"engine-catalog-mutation"},{"k":"p","inline":[{"k":"code","text":"nika-catalog::ALL_BUILTINS"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"DELETE 4 entries · "},{"k":"code","text":"Builtin { name: \"cost\", category: Introspection }"},{"k":"text","text":" ·\n"},{"k":"code","text":"Builtin { name: \"records\", category: Introspection }"},{"k":"text","text":" ·\n"},{"k":"code","text":"Builtin { name: \"dag_info\", category: Introspection }"},{"k":"text","text":" ·\n"},{"k":"code","text":"Builtin { name: \"threads\", category: Introspection }"}],[{"k":"text","text":"INSERT 1 entry (alphabetical · between "},{"k":"code","text":"hash"},{"k":"text","text":" and "},{"k":"code","text":"jq"},{"k":"text","text":" · "},{"k":"code","text":"h-a-s"},{"k":"text","text":" <\n"},{"k":"code","text":"i-n-s"},{"k":"text","text":" < "},{"k":"code","text":"j-q"},{"k":"text","text":" verified) · "},{"k":"code","text":"Builtin { name: \"inspect\", category: Introspection }"}]]},{"k":"p","inline":[{"k":"text","text":"Sort invariant preserved. Total · 25 → "},{"k":"strong","text":"22"},{"k":"text","text":". Introspection category ·\n4 → "},{"k":"strong","text":"1"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"Engine trust.rs mutation","id":"engine-trustrs-mutation"},{"k":"p","inline":[{"k":"code","text":"TRUST_PURE_BUILTINS"},{"k":"text","text":" list ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"DELETE "},{"k":"code","text":"\"nika:cost\""},{"k":"text","text":" + "},{"k":"code","text":"\"nika:records\""},{"k":"text","text":" + "},{"k":"code","text":"\"nika:dag_info\""},{"k":"text","text":" + "},{"k":"code","text":"\"nika:threads\""}],[{"k":"text","text":"INSERT "},{"k":"code","text":"\"nika:inspect\""}]]},{"k":"p","inline":[{"k":"text","text":"Trust class unchanged (all 4 were PURE · inspect stays PURE · pure-\ncompute query of own workflow state · no I/O · no flow change · output\ntrust = TRUSTED always). Total PURE · 13 → "},{"k":"strong","text":"10"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"Engine codegen.rs mutation (ADR-085 no-drift gate)","id":"engine-codegenrs-mutation-adr-085-no-drift-gate"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"enum_excludes_legacy_post_d_n6"},{"k":"text","text":" · ADD all 4 to legacy exclusion list\n(8 → "},{"k":"strong","text":"12"},{"k":"text","text":" legacy names guarded)."}],[{"k":"code","text":"enum_includes_canonical_anchors"},{"k":"text","text":" · "},{"k":"code","text":"\"nika:cost\""},{"k":"text","text":" → "},{"k":"code","text":"\"nika:inspect\""},{"k":"text","text":"\n(the canonical-anchor sentinel for Introspection category)."}],[{"k":"code","text":"enum_has_25_entries"},{"k":"text","text":" → "},{"k":"code","text":"enum_has_22_entries"},{"k":"text","text":"."}]]},{"k":"h","depth":3,"text":"Engine catalog test mutations","id":"engine-catalog-test-mutations"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"builtin_count"},{"k":"text","text":" · 25 → 22"}],[{"k":"code","text":"category_counts"},{"k":"text","text":" · Introspection 4 → 1 · total 22"}],[{"k":"code","text":"find_known_builtins"},{"k":"text","text":" · "},{"k":"code","text":"\"cost\""},{"k":"text","text":" → "},{"k":"code","text":"\"inspect\""},{"k":"text","text":" sentinel"}],[{"k":"code","text":"is_known_builtin_works"},{"k":"text","text":" · "},{"k":"code","text":"\"inspect\""},{"k":"text","text":" is the canonical · 4 legacy\nadded to negative-assertion list"}]]},{"k":"h","depth":3,"text":"Spec mutation (companion · nika/spec submodule `8437909`)","id":"spec-mutation-companion--nikaspec-submodule-8437909"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika/spec/stdlib/builtins-v0.1.md"},{"k":"text","text":" · §0 + §1 Introspection count 25\n→ 22 · 4 → 1 · §3 Introspection section DELETE 4 subsections · ADD\ninspect subsection with "},{"k":"code","text":"view:"},{"k":"text","text":" enum + per-view return shapes + 1\nNIKA-BUILTIN-INSPECT-001 error code."}],[{"k":"code","text":"nika/spec/schemas/workflow.schema.json"},{"k":"text","text":" · invoke.tool oneOf nika\nbranch enum · DELETE 4 entries · ADD 1 · 25 → 22 · description\nIntrospection 4 → 1."}],[{"k":"code","text":"nika/spec/spec/06-stdlib-contract.md"},{"k":"text","text":" · enumeration + total updated\n· 4-into-1 inspect collapse cited per ADR-088."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Symmetry signal COMPLETE · 5 layers"},{"k":"text","text":" · « one super-powerful builtin\n· multi-mode args » canonical pattern now realized at 5 distinct\ndomains · HTTP (fetch+extract · 8 modes) · data transform (jq ·\nsubsumes ~13) · format conversion (convert · 4 formats × 3 directions)\n· temporal control (wait · 2 modes) · introspection (inspect · 4 views).\nThe Rams sweep is structurally complete · cookbook authors + LSP\nconsumers get fully consistent cognitive surface across all 5 domains."}],[{"k":"strong","text":"Trust class preserved"},{"k":"text","text":" · all 4 were PURE · inspect stays PURE ·\nzero security regression."}],[{"k":"strong","text":"No-drift gate auto-validates"},{"k":"text","text":" · ADR-085 codegen.rs test\n"},{"k":"code","text":"enum_matches_catalog_one_to_one"},{"k":"text","text":" AUTO-detects spec ↔ engine parity\nvia "},{"k":"code","text":"nika_builtin_tool_enum_schema()"},{"k":"text","text":" reading ALL_BUILTINS at call time."}],[{"k":"strong","text":"Workflow.schema.json LSP-completion ENRICHED"},{"k":"text","text":" · 4 → 1 builtin\nreduces autocomplete surface AND focuses the prompt on the "},{"k":"code","text":"view:"},{"k":"text","text":"\ndiscriminator (the actual operator decision point) · cleaner LSP UX\nthan 4 sibling completions with similar names."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Return-shape heterogeneity"},{"k":"text","text":" · the 4 views have semantically\ndistinct return shapes (cost = numeric metrics · records = list ·\ndag_info = graph · threads = pool counts) · workflow.schema.json\nmodels this as untyped output (operator-side handles per-view) ·\ncould ratchet to "},{"k":"code","text":"oneOf"},{"k":"text","text":" per view in a future ADR if LSP UX feedback\nsignals need typed return."},{"k":"text","text":"- Mitigation · per-view return shapes documented inline in spec §3\n  so authors know what to expect.\n- Mitigation · the canonical fetch+extract precedent has the same\n  return-shape heterogeneity across its 8 modes · workflow author\n  pattern is well-established."}],[{"k":"strong","text":"Public API breaking"},{"k":"text","text":" · existing workflows using "},{"k":"code","text":"tool: nika:cost"},{"k":"text","text":"\n(or records · dag_info · threads) fail against the spec-22 closed\nenum + "},{"k":"code","text":"is_known_builtin"},{"k":"text","text":" returns false for all 4. Acceptable per\nADR-002 (amended D-2026-06-20-N1 · real semver toward 1.0 · pre-1.0\nbreakage OK · NUKE-LEGACY · git is the archive · zero deprecation alias)."},{"k":"text","text":"- Mitigation · spec is pre-v1.0 GA · breakage cost ≈ 0 today.\n- Mitigation · trust.rs `legacy_builtins_unknown_post_d_n6` extends\n  with all 4 · fail-closed regression guard."}],[{"k":"strong","text":"NIKA-BUILTIN-INSPECT-001 new error code"},{"k":"text","text":" · documented in spec\nerror namespace · engine impl gates on L2 nika-builtin admission."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Tests · +4 net new legacy guards"},{"k":"text","text":" in trust.rs + +4 in codegen.rs\n· existing conformance tests stay GREEN (renamed counts asserted)."}],[{"k":"strong","text":"L0 layer constraint preserved"},{"k":"text","text":" · pure data + pure test mutation ·\nzero L0 violation."}],[{"k":"strong","text":"TTL graph projection"},{"k":"text","text":" · monorepo "},{"k":"code","text":"nika-language-v1.ttl"},{"k":"text","text":" updates ·\n4 sets of 4 refs (cost · records · dag_info · threads) → 4 refs\n(inspect · instance + family + raises + invokedBy) · count 25 → 22\nin family list. Per ADR-087 precedent · session B's nika-spec-graph-\nparity vector auto-syncs."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"A · Keep 4 atomic introspection builtins","id":"a--keep-4-atomic-introspection-builtins"},{"k":"p","inline":[{"k":"text","text":"REJECTED · the symmetry argument · 4-of-5 Rams collapses landed (jq ·\nconvert · wait + this) · the 5th uncollapsed (introspection) breaks\nthe canonical pattern's structural completeness · cookbook authors\nface inconsistent surface."}]},{"k":"h","depth":3,"text":"B · `view:` enum but keep 4 wrappers as syntactic sugar","id":"b--view-enum-but-keep-4-wrappers-as-syntactic-sugar"},{"k":"p","inline":[{"k":"text","text":"REJECTED · violates « less but better » · syntactic sugar accumulates\nback to N builtin slots · the discriminator IS the canonical API · no\nceremony needed."}]},{"k":"h","depth":3,"text":"C · Typed `oneOf` return shape per view","id":"c--typed-oneof-return-shape-per-view"},{"k":"p","inline":[{"k":"text","text":"DEFERRED to future ADR if LSP UX signal arrives. Per "},{"k":"code","text":"nika:fetch"},{"k":"text","text":"\nprecedent (8 modes · untyped return per spec · still successful) ·\nuntyped is acceptable v0.1. Trigger gate · operator-side incident\nOR LSP UX feedback citing \"missed completion for inspect view X\nreturn field Y\"."}]},{"k":"h","depth":2,"text":"Gate verification","id":"gate-verification"},{"k":"p","inline":[{"k":"text","text":"Per ADR-084/086/087 precedent ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ Gate 2 TDD · trust.rs + codegen.rs tests updated · catalog tests\nupdated · 226 nika-catalog + 205 nika-schema lib tests GREEN."}],[{"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-catalog -p nika-schema"},{"k":"text","text":"\n0 warnings."}],[{"k":"text","text":"✅ Gate 12 ATOMIC · single engine commit + single monorepo bump."}],[{"k":"code","text":"cargo fmt --check"},{"k":"text","text":" GREEN."}],[{"k":"code","text":"cargo deny check"},{"k":"text","text":" ok (no new deps)."}],[{"k":"text","text":"Gates 1 / 5 / 6 / 7 / 9 / 10 / 11 · N/A for data refactor."}]]},{"k":"h","depth":2,"text":"Rams sweep · COMPLETE state post-ADR-088","id":"rams-sweep--complete-state-post-adr-088"},{"k":"code","lang":"text","text":"RAMS COLLAPSE ARC (2026-05-27)         BEFORE   AFTER   NET     ADR\n────────────────────────                ──────   ─────   ───     ───\ncsv_to_json → convert                   1        1       0       086\nsleep + wait_until → wait               2        1       -1      087\ncost+records+dag_info+threads → inspect 4        1       -3      088\n                                                          ────\nCumulative builtin count                26       22      -4"},{"k":"p","inline":[{"k":"text","text":"5 layers now canonically consolidated · HTTP (fetch+extract) · data\ntransform (jq) · format conversion (convert) · temporal control (wait) ·\nintrospection (inspect). Symmetry signal STRUCTURALLY COMPLETE."}]},{"k":"h","depth":2,"text":"Optional future Rams ratchets (LOCK-031 trigger-gated)","id":"optional-future-rams-ratchets-lock-031-trigger-gated"},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"ADR-089 · `nika:json_diff` jq-subsume feasibility"},{"k":"text","text":" · jq CAN\nexpress diff but loses RFC-6902 Patch output format. Trigger ·\ncookbook adoption of jq-diff recipe + operator preference signal."}],[{"k":"strong","text":"Crate-level Rams audit"},{"k":"text","text":" · 4 candidate domains identified\ninternally (insta + expect-test consolidation · YAML triumvirate\naudit · jiff date pre-decision · hash family canonical). Trigger ·\nratchet candidates accumulate ≥3 cross-product signals."}]]},{"k":"p","inline":[{"k":"text","text":"When ADR-089 + selected crate Rams land · 22 → ~21 + workspace dep\nhygiene improvements. Same "},{"k":"code","text":"nika: v1"},{"k":"text","text":" envelope · real-semver-toward-1.0 discipline (ADR-002 · amended D-2026-06-20-N1)."}]},{"k":"h","depth":2,"text":"Companion artefacts","id":"companion-artefacts"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-catalog/src/data/builtins.rs"},{"k":"text","text":" · ALL_BUILTINS · DELETE 4 ·\nINSERT 1 · 25 → 22 · test counts adjusted."}],[{"k":"code","text":"nika-catalog/src/types/builtin.rs"},{"k":"text","text":" · BuiltinCategory Introspection\ndoc-comment refreshed (1 builtin · view-discriminated)."}],[{"k":"code","text":"nika-catalog/src/lib.rs"},{"k":"text","text":" · "},{"k":"code","text":"all_builtins_non_empty"},{"k":"text","text":" test 25 → 22."}],[{"k":"code","text":"nika-schema/src/trust.rs"},{"k":"text","text":" · TRUST_PURE_BUILTINS · DELETE 4 +\nINSERT 1 (13 → 10) · legacy exclusion test extended +4 · total\nassertion 25 → 22."}],[{"k":"code","text":"nika-schema/src/codegen.rs"},{"k":"text","text":" · "},{"k":"code","text":"enum_has_25_entries"},{"k":"text","text":" → "},{"k":"code","text":"_22_entries"},{"k":"text","text":"\n· "},{"k":"code","text":"enum_includes_canonical_anchors"},{"k":"text","text":" cost → inspect ·\n"},{"k":"code","text":"enum_excludes_legacy_post_d_n6"},{"k":"text","text":" extended +4."}],[{"k":"code","text":"nika/spec/stdlib/builtins-v0.1.md"},{"k":"text","text":" (submodule "},{"k":"code","text":"8437909"},{"k":"text","text":") · 4\nintrospection sections deleted · inspect section added · counts\nupdated."}],[{"k":"code","text":"nika/spec/schemas/workflow.schema.json"},{"k":"text","text":" (same submodule commit) ·\ninvoke.tool oneOf nika branch enum 25 → 22."}],[{"k":"code","text":"nika/spec/spec/06-stdlib-contract.md"},{"k":"text","text":" (same submodule commit) ·\nenumeration + total updated."}]]},{"k":"h","depth":2,"text":"References","id":"references"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-087 · sleep + wait_until → wait (prerequisite · same Rams sweep)"}],[{"k":"text","text":"ADR-086 · csv_to_json → convert (prerequisite · same Rams sweep)"}],[{"k":"text","text":"ADR-085 · spec workflow.schema.json oneOf bridge (no-drift gate)"}],[{"k":"text","text":"ADR-084 · nika-catalog reconciliation to spec 26 (foundation)"}],[{"k":"text","text":"ADR-082 · envelope "},{"k":"code","text":"nika: v1"},{"k":"text","text":" single-version-marker"}],[{"k":"text","text":"Internal · LOCK-031 trigger-gated discipline (no infra behind locked\ngate · ADR-089 + crate Rams audit deferred)"}],[{"k":"text","text":"Internal · cross-source-validation §2.6 Signal 7 (verify-the-auditor)"}],[{"k":"text","text":"Internal · no-legacy-no-back-compat Class 2 (git is the archive)"}]]},{"k":"p","inline":[{"k":"text","text":"🦋"}]}]

ADR-088

nika:cost + records + dag_info + threads → nika:inspect · introspection Rams collapse

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

ADR-088 · 4 introspection builtins → nika:inspect #

Context #

Operator-led Rams audit 2026-05-27 of the canonical builtin set identified the 4 introspection primitives as a Rams collapse candidate ·

nika:cost → { total_usd, by_task, by_provider } · workflow cost
nika:records → { tasks: [{ id, status, duration_ms, ... }] } · execution record
nika:dag_info → { nodes, edges, waves } · DAG topology
nika:threads → { active, queued, completed } · task-pool state

All 4 are PURE trust · pure-compute queries of own workflow state · same semantic family. The split into 4 separate builtins was historical (one-per-return-shape) not structural. ADR-088 unifies them into a single view-discriminated nika:inspect.

This is the 4th and most ambitious Rams collapse in the operator-led sweep · completes the « one super-powerful builtin · multi-mode args » symmetry across 5 distinct domains.

Decision #

nika:cost · nika:records · nika:dag_info · nika:threads removed · nika:inspect adopted as unified introspection builtin with view: enum discriminator.

`nika:inspect` surface #

yaml

1◆invoke:2  tool: "nika:inspect"3  args:4    view: cost                     # REQUIRED · enum · cost | records | dag_info | threads

Per-view return shapes #

view: cost → { total_usd, by_task, by_provider } (sleep equivalent of legacy nika:cost)
view: records → { tasks: [{ id, status, duration_ms, ... }] } (legacy nika:records)
view: dag_info → { nodes, edges, waves } (legacy nika:dag_info)
view: threads → { active, queued, completed } · advisory (legacy nika:threads)

Validation #

Parse-time check · view: MUST be one of the 4 canonical enum values. Engine returns NIKA-BUILTIN-INSPECT-001 if view: value not in the canonical set.

Engine catalog mutation #

nika-catalog::ALL_BUILTINS ·

DELETE 4 entries · Builtin { name: "cost", category: Introspection } · Builtin { name: "records", category: Introspection } · Builtin { name: "dag_info", category: Introspection } · Builtin { name: "threads", category: Introspection }
INSERT 1 entry (alphabetical · between hash and jq · h-a-s < i-n-s < j-q verified) · Builtin { name: "inspect", category: Introspection }

Sort invariant preserved. Total · 25 → 22. Introspection category · 4 → 1.

Engine trust.rs mutation #

TRUST_PURE_BUILTINS list ·

DELETE "nika:cost" + "nika:records" + "nika:dag_info" + "nika:threads"
INSERT "nika:inspect"

Trust class unchanged (all 4 were PURE · inspect stays PURE · pure- compute query of own workflow state · no I/O · no flow change · output trust = TRUSTED always). Total PURE · 13 → 10.

Engine codegen.rs mutation (ADR-085 no-drift gate) #

enum_excludes_legacy_post_d_n6 · ADD all 4 to legacy exclusion list (8 → 12 legacy names guarded).
enum_includes_canonical_anchors · "nika:cost" → "nika:inspect" (the canonical-anchor sentinel for Introspection category).
enum_has_25_entries → enum_has_22_entries.

Engine catalog test mutations #

builtin_count · 25 → 22
category_counts · Introspection 4 → 1 · total 22
find_known_builtins · "cost" → "inspect" sentinel
is_known_builtin_works · "inspect" is the canonical · 4 legacy added to negative-assertion list

Spec mutation (companion · nika/spec submodule `8437909`) #

nika/spec/stdlib/builtins-v0.1.md · §0 + §1 Introspection count 25 → 22 · 4 → 1 · §3 Introspection section DELETE 4 subsections · ADD inspect subsection with view: enum + per-view return shapes + 1 NIKA-BUILTIN-INSPECT-001 error code.
nika/spec/schemas/workflow.schema.json · invoke.tool oneOf nika branch enum · DELETE 4 entries · ADD 1 · 25 → 22 · description Introspection 4 → 1.
nika/spec/spec/06-stdlib-contract.md · enumeration + total updated · 4-into-1 inspect collapse cited per ADR-088.

Consequences #

Positive #

Symmetry signal COMPLETE · 5 layers · « one super-powerful builtin · multi-mode args » canonical pattern now realized at 5 distinct domains · HTTP (fetch+extract · 8 modes) · data transform (jq · subsumes ~13) · format conversion (convert · 4 formats × 3 directions) · temporal control (wait · 2 modes) · introspection (inspect · 4 views). The Rams sweep is structurally complete · cookbook authors + LSP consumers get fully consistent cognitive surface across all 5 domains.
Trust class preserved · all 4 were PURE · inspect stays PURE · zero security regression.
No-drift gate auto-validates · ADR-085 codegen.rs test enum_matches_catalog_one_to_one AUTO-detects spec ↔ engine parity via nika_builtin_tool_enum_schema() reading ALL_BUILTINS at call time.
Workflow.schema.json LSP-completion ENRICHED · 4 → 1 builtin reduces autocomplete surface AND focuses the prompt on the view: discriminator (the actual operator decision point) · cleaner LSP UX than 4 sibling completions with similar names.

Negative #

Return-shape heterogeneity · the 4 views have semantically distinct return shapes (cost = numeric metrics · records = list · dag_info = graph · threads = pool counts) · workflow.schema.json models this as untyped output (operator-side handles per-view) · could ratchet to oneOf per view in a future ADR if LSP UX feedback signals need typed return.- Mitigation · per-view return shapes documented inline in spec §3 so authors know what to expect. - Mitigation · the canonical fetch+extract precedent has the same return-shape heterogeneity across its 8 modes · workflow author pattern is well-established.
Public API breaking · existing workflows using tool: nika:cost (or records · dag_info · threads) fail against the spec-22 closed enum + is_known_builtin returns false for all 4. Acceptable per ADR-002 (amended D-2026-06-20-N1 · real semver toward 1.0 · pre-1.0 breakage OK · NUKE-LEGACY · git is the archive · zero deprecation alias).- Mitigation · spec is pre-v1.0 GA · breakage cost ≈ 0 today. - Mitigation · trust.rs `legacy_builtins_unknown_post_d_n6` extends with all 4 · fail-closed regression guard.
NIKA-BUILTIN-INSPECT-001 new error code · documented in spec error namespace · engine impl gates on L2 nika-builtin admission.

Neutral #

Tests · +4 net new legacy guards in trust.rs + +4 in codegen.rs · existing conformance tests stay GREEN (renamed counts asserted).
L0 layer constraint preserved · pure data + pure test mutation · zero L0 violation.
TTL graph projection · monorepo nika-language-v1.ttl updates · 4 sets of 4 refs (cost · records · dag_info · threads) → 4 refs (inspect · instance + family + raises + invokedBy) · count 25 → 22 in family list. Per ADR-087 precedent · session B's nika-spec-graph- parity vector auto-syncs.

Alternatives considered #

A · Keep 4 atomic introspection builtins #

REJECTED · the symmetry argument · 4-of-5 Rams collapses landed (jq · convert · wait + this) · the 5th uncollapsed (introspection) breaks the canonical pattern's structural completeness · cookbook authors face inconsistent surface.

B · `view:` enum but keep 4 wrappers as syntactic sugar #

REJECTED · violates « less but better » · syntactic sugar accumulates back to N builtin slots · the discriminator IS the canonical API · no ceremony needed.

C · Typed `oneOf` return shape per view #

DEFERRED to future ADR if LSP UX signal arrives. Per nika:fetch precedent (8 modes · untyped return per spec · still successful) · untyped is acceptable v0.1. Trigger gate · operator-side incident OR LSP UX feedback citing "missed completion for inspect view X return field Y".

Gate verification #

Per ADR-084/086/087 precedent ·

✅ Gate 2 TDD · trust.rs + codegen.rs tests updated · catalog tests updated · 226 nika-catalog + 205 nika-schema lib tests GREEN.
✅ 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-catalog -p nika-schema 0 warnings.
✅ Gate 12 ATOMIC · single engine commit + single monorepo bump.
cargo fmt --check GREEN.
cargo deny check ok (no new deps).
Gates 1 / 5 / 6 / 7 / 9 / 10 / 11 · N/A for data refactor.

Rams sweep · COMPLETE state post-ADR-088 #

text

1RAMS COLLAPSE ARC (2026-05-27)         BEFORE   AFTER   NET     ADR2────────────────────────                ──────   ─────   ───     ───3csv_to_json → convert                   1        1       0       0864sleep + wait_until → wait               2        1       -1      0875cost+records+dag_info+threads → inspect 4        1       -3      0886                                                          ────7Cumulative builtin count                26       22      -4

5 layers now canonically consolidated · HTTP (fetch+extract) · data transform (jq) · format conversion (convert) · temporal control (wait) · introspection (inspect). Symmetry signal STRUCTURALLY COMPLETE.

Optional future Rams ratchets (LOCK-031 trigger-gated) #

ADR-089 · `nika:json_diff` jq-subsume feasibility · jq CAN express diff but loses RFC-6902 Patch output format. Trigger · cookbook adoption of jq-diff recipe + operator preference signal.
Crate-level Rams audit · 4 candidate domains identified internally (insta + expect-test consolidation · YAML triumvirate audit · jiff date pre-decision · hash family canonical). Trigger · ratchet candidates accumulate ≥3 cross-product signals.

When ADR-089 + selected crate Rams land · 22 → ~21 + workspace dep hygiene improvements. Same nika: v1 envelope · real-semver-toward-1.0 discipline (ADR-002 · amended D-2026-06-20-N1).

Companion artefacts #

nika-catalog/src/data/builtins.rs · ALL_BUILTINS · DELETE 4 · INSERT 1 · 25 → 22 · test counts adjusted.
nika-catalog/src/types/builtin.rs · BuiltinCategory Introspection doc-comment refreshed (1 builtin · view-discriminated).
nika-catalog/src/lib.rs · all_builtins_non_empty test 25 → 22.
nika-schema/src/trust.rs · TRUST_PURE_BUILTINS · DELETE 4 + INSERT 1 (13 → 10) · legacy exclusion test extended +4 · total assertion 25 → 22.
nika-schema/src/codegen.rs · enum_has_25_entries → _22_entries · enum_includes_canonical_anchors cost → inspect · enum_excludes_legacy_post_d_n6 extended +4.
nika/spec/stdlib/builtins-v0.1.md (submodule 8437909) · 4 introspection sections deleted · inspect section added · counts updated.
nika/spec/schemas/workflow.schema.json (same submodule commit) · invoke.tool oneOf nika branch enum 25 → 22.
nika/spec/spec/06-stdlib-contract.md (same submodule commit) · enumeration + total updated.

References #

ADR-087 · sleep + wait_until → wait (prerequisite · same Rams sweep)
ADR-086 · csv_to_json → convert (prerequisite · same Rams sweep)
ADR-085 · spec workflow.schema.json oneOf bridge (no-drift gate)
ADR-084 · nika-catalog reconciliation to spec 26 (foundation)
ADR-082 · envelope nika: v1 single-version-marker
Internal · LOCK-031 trigger-gated discipline (no infra behind locked gate · ADR-089 + crate Rams audit deferred)
Internal · cross-source-validation §2.6 Signal 7 (verify-the-auditor)
Internal · no-legacy-no-back-compat Class 2 (git is the archive)

🦋

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

Every decision, with its status This one in the repo