{"row":{"id":"ADR-089","title":"nika:json_diff jq-subsume feasibility · REJECTED · keep RFC-6902 Patch as canonical output format","file":"adr-089-json-diff-jq-subsume-rejected.md","status":"rejected","date":"2026-05-27","cites":5,"supersedes":[],"superseded_by":[],"layers":[],"tags":["nika-catalog","stdlib","builtins","rams"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-089 · `nika:json_diff` jq-subsume feasibility · REJECTED","id":"adr-089--nikajson_diff-jq-subsume-feasibility--rejected"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Operator-led Rams audit 2026-05-27 of the canonical 22-builtin set\n(post-ADR-086/087/088 collapses) identified "},{"k":"code","text":"nika:json_diff"},{"k":"text","text":" as one of\nthe residual data builtins · question to answer · « can jq subsume\njson_diff like it subsumed map/filter/group_by/json_merge? »"}]},{"k":"p","inline":[{"k":"text","text":"This is the same Rams test that drove the 42 → 22 cascade · the\ncanonical razor « a nika:builtin is justified SSI NOT expressible in\njq+CEL+Schema · IS the logic behind the D-N6 collapse 42→26 + ADR-086\ncsv_to_json cut + ADR-088 4-introspection collapse »."}]},{"k":"p","inline":[{"k":"text","text":"Per Internal · cross-source-validation §2.6 Signal 3 · single-source jq\nresearch insufficient · this ADR documents the primary-source\nverification (jq capability matrix) and the disposition."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"REJECTED · keep `nika:json_diff` as canonical builtin emitting RFC-6902\nJSON Patch."}]},{"k":"h","depth":3,"text":"Rationale · what jq CAN do","id":"rationale--what-jq-can-do"},{"k":"p","inline":[{"k":"text","text":"jq is Turing-equivalent for JSON transformation. A recursive walk over\ntwo documents to find differences IS expressible · the rough shape ·"}]},{"k":"code","lang":"jq","text":"# Compare two documents at \u0024base and \u0024patch · recursive · produces\n# {path, base, patch} tuples for each difference (one possible shape)\ndef diff(\u0024base; \u0024patch; path):\n  if (\u0024base | type) == \"object\" and (\u0024patch | type) == \"object\" then\n    ((\u0024base | keys) + (\u0024patch | keys) | unique)[] as \u0024k |\n    diff(\u0024base[\u0024k]; \u0024patch[\u0024k]; path + [\u0024k])\n  elif \u0024base != \u0024patch then\n    { path: path, before: \u0024base, after: \u0024patch }\n  else empty end ;\n\ndiff(.[0]; .[1]; [])"},{"k":"p","inline":[{"k":"text","text":"Capability-wise · jq CAN walk + compare + emit difference tuples. The\ntest « is NOT expressible in jq+CEL+Schema » FAILS at the capability\nlayer for ARBITRARY difference reporting."}]},{"k":"h","depth":3,"text":"Rationale · what jq CANNOT do (the actual cut)","id":"rationale--what-jq-cannot-do-the-actual-cut"},{"k":"p","inline":[{"k":"text","text":"The justification for "},{"k":"code","text":"nika:json_diff"},{"k":"text","text":" is NOT « jq can't diff » · it's\n"},{"k":"strong","text":"« jq cannot emit RFC-6902 JSON Patch (the canonical interop format) »"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"RFC 6902 is the canonical IETF standard for JSON document diffs ·\nshape ·"}]},{"k":"code","lang":"json","text":"[\n  { \"op\": \"replace\", \"path\": \"/foo/bar\", \"value\": 42 },\n  { \"op\": \"add\",     \"path\": \"/baz\",     \"value\": \"new\" },\n  { \"op\": \"remove\",  \"path\": \"/qux\" }\n]"},{"k":"p","inline":[{"k":"text","text":"The 6 operations ("},{"k":"code","text":"add"},{"k":"text","text":" · "},{"k":"code","text":"remove"},{"k":"text","text":" · "},{"k":"code","text":"replace"},{"k":"text","text":" · "},{"k":"code","text":"move"},{"k":"text","text":" · "},{"k":"code","text":"copy"},{"k":"text","text":" · "},{"k":"code","text":"test"},{"k":"text","text":")\nhave semantic rules · particularly ·"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"replace"},{"k":"text","text":" vs "},{"k":"code","text":"add"},{"k":"text","text":" discrimination · based on key existence in the\nbase · jq doesn't track « did this key exist in the original document »\nin a way that survives the recursive walk"}],[{"k":"code","text":"remove"},{"k":"text","text":" requires the absence in patch (jq can express absence-of-key\nvia "},{"k":"code","text":"has"},{"k":"text","text":" but threading it through nested recursion is verbose · ~30+\nlines of jq for a correctness-equivalent emitter)"}],[{"k":"code","text":"move"},{"k":"text","text":" + "},{"k":"code","text":"copy"},{"k":"text","text":" require structural pattern detection (was this\nadd+remove pair semantically a move?) · jq has no notion of « detect\nthis pair as one logical operation »"}],[{"k":"code","text":"test"},{"k":"text","text":" is a runtime assertion semantic · belongs to the consumer"}]]},{"k":"p","inline":[{"k":"text","text":"A 30+ line jq diff emitter that gets RFC 6902 SEMANTICS right is ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Not « less but better »"},{"k":"text","text":" · longer than the 22-builtin emit shape it\nwould replace · violates Rams 10 spirit"}],[{"k":"strong","text":"Cookbook anti-pattern"},{"k":"text","text":" · Internal · the « one obvious way »\nvalidator canon (D-N9/N10) requires authors to NOT memorize 30-line\njq programs · prefer the canonical builtin"}],[{"k":"strong","text":"Interop loss"},{"k":"text","text":" · the RFC 6902 output format is the contract\ndownstream tools (JSON Patch apply libraries · OpenAPI diff tooling ·\nGraphQL change-set encoders) expect. Emitting a custom\n"},{"k":"code","text":"{path, before, after}"},{"k":"text","text":" shape via jq breaks interop · forces every\nconsumer to write a translator"}]]},{"k":"h","depth":3,"text":"The other 4 introspection razor sister tests","id":"the-other-4-introspection-razor-sister-tests"},{"k":"p","inline":[{"k":"text","text":"Same razor applied to ADR-086/087/088 · those COLLAPSED because the\ncollapsed forms WERE strictly better (Rams 10) ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-086 "},{"k":"code","text":"csv_to_json → convert"},{"k":"text","text":" · was 1 narrow direction · convert\nexposes 4 formats × 3 directions = 12 capabilities · strictly more\npower · same surface"}],[{"k":"text","text":"ADR-087 "},{"k":"code","text":"sleep + wait_until → wait"},{"k":"text","text":" · the two former builtins were\nartificially split by mode (relative vs absolute) · unified mode arg\nIS the « one obvious way »"}],[{"k":"text","text":"ADR-088 "},{"k":"code","text":"4 introspection → inspect view:"},{"k":"text","text":" · the 4 were artificially\nsplit by query-shape · unified view-discriminator IS the « one\nobvious way »"}]]},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"json_diff"},{"k":"text","text":" case is different · the alternative (« express via\njq ») would be "},{"k":"strong","text":"LESS obvious"},{"k":"text","text":" (30+ lines vs 1 builtin call) AND\n"},{"k":"strong","text":"LESS interoperable"},{"k":"text","text":" (custom diff shape vs RFC 6902 standard). Rams\ntest FAILS in both directions."}]},{"k":"h","depth":2,"text":"Disposition","id":"disposition"},{"k":"p","inline":[{"k":"strong","text":"KEEP `nika:json_diff` as canonical builtin"},{"k":"text","text":" ·"}]},{"k":"code","lang":"yaml","text":"diff:\n  invoke:\n    tool: \"nika:json_diff\"\n    args:\n      base: \u0024{{ vars.original }}\n      patch: \u0024{{ vars.modified }}\n  # output · RFC 6902 JSON Patch array"},{"k":"p","inline":[{"k":"text","text":"Output shape · canonical RFC 6902 "},{"k":"code","text":"Patch"},{"k":"text","text":" array per IETF spec ·\ndownstream-interop-clean."}]},{"k":"p","inline":[{"k":"text","text":"Canonical 22-builtin count UNCHANGED post this ADR · the 5-layer Rams\nsymmetry (fetch+extract · jq · convert · wait · inspect) holds ·\n"},{"k":"code","text":"json_diff"},{"k":"text","text":" stands as the « jq can't diff to a canonical format »\nexception · same shape as "},{"k":"code","text":"json_merge_patch"},{"k":"text","text":" (RFC 7396 null-delete · jq\ncan't) · same shape as "},{"k":"code","text":"validate"},{"k":"text","text":" (JSON Schema · jq is not a\nvalidator)."}]},{"k":"h","depth":2,"text":"Future revisit triggers (LOCK-031 strict)","id":"future-revisit-triggers-lock-031-strict"},{"k":"p","inline":[{"k":"text","text":"Per Internal · round-1-ship-pattern §6 LOCK-031 spirit · documented triggers\nthat COULD reopen this disposition ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Trigger · What it would mean · Likelihood"}],[{"k":"text","text":"Cookbook adopts a `jq '... diff ...'` recipe with ≥3 successful invocations · Authors prefer jq-form over builtin · razor shifts · LOW · 30+ line jq programs are off-doctrine"}],[{"k":"text","text":"RFC 6902 deprecated by IETF · Output-format interop argument weakens · NEAR-ZERO · RFC is stable since 2013 · widely deployed"}],[{"k":"text","text":"jaq ships an `--rfc6902` flag or canonical `diff` filter · jq becomes the canonical RFC 6902 emitter · LOW · would require upstream jaq change"}],[{"k":"text","text":"Operator-explicit `« cut json_diff »` signal · The ultimate trigger · same shape as ADR-086 · OPEN"}]]},{"k":"p","inline":[{"k":"text","text":"Per Internal · cross-source-validation §2.6 Signal 3 · this ADR is the\ncanonical anti-promotion gate · any future « should we cut json_diff? »\ndiscussion routes here."}]},{"k":"h","depth":2,"text":"Cross-source verification (per §2.6 Signal 3 + §2.7.1 cascade-completeness)","id":"cross-source-verification-per-26-signal-3--271-cascade-completeness"},{"k":"p","inline":[{"k":"text","text":"Primary-source verified 2026-05-27 ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"jaq source"},{"k":"text","text":" · "},{"k":"code","text":"jaq/jaq-json/src/lib.rs"},{"k":"text","text":" · NO native "},{"k":"code","text":"diff"},{"k":"text","text":" or\n"},{"k":"code","text":"rfc6902"},{"k":"text","text":" filter. The capability is expressible (Turing-equivalent)\nBUT no canonical output-format emitter shipped."}],[{"k":"strong","text":"jq manual"},{"k":"text","text":" · "},{"k":"code","text":"jq-1.7.1"},{"k":"text","text":" manual at "},{"k":"link","text":"https://jqlang.org/manual/","href":"https://jqlang.org/manual/"},{"k":"text","text":" ·\nno "},{"k":"code","text":"diff"},{"k":"text","text":" builtin · no RFC 6902 support in stdlib."}],[{"k":"strong","text":"RFC 6902"},{"k":"text","text":" · IETF spec stable since 2013 · 6 ops canonical ·\nwidely supported by JSON Patch libraries (e.g. "},{"k":"code","text":"serde_json_patch"},{"k":"text","text":"\nin Rust ecosystem)."}],[{"k":"strong","text":"Cookbook signal"},{"k":"text","text":" · NIKA_COOKBOOK-v0.1.md · zero recipes that\nexpress diff-via-jq · the « one obvious way » authoring contract\nwould reject 30+ line jq programs."}]]},{"k":"p","inline":[{"k":"text","text":"Bucket A (already canon) · "},{"k":"code","text":"nika:json_diff"},{"k":"text","text":" was a D-N5 KEEP · this ADR\nformalizes the KEEP rationale."}]},{"k":"h","depth":2,"text":"Cohérent","id":"cohrent"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-082 "},{"k":"code","text":"nika: v1"},{"k":"text","text":" envelope · 22 builtins canonical · ADR-089 holds count"}],[{"k":"text","text":"ADR-084 catalog-spec reconciliation · "},{"k":"code","text":"json_diff"},{"k":"text","text":" stays in catalog"}],[{"k":"text","text":"ADR-085 schemars codegen · "},{"k":"code","text":"json_diff"},{"k":"text","text":" enum variant stays"}],[{"k":"text","text":"ADR-086/087/088 · 5-layer Rams symmetry · "},{"k":"code","text":"json_diff"},{"k":"text","text":" is the canonical\nexception that proves the « jq can't do everything » rule"}],[{"k":"text","text":"Per Internal · cross-source-validation §2.6 Signal 3 verification"}],[{"k":"text","text":"Per Internal · cognitive-design-canon P4 cognitive load · 1-line\nbuiltin call beats 30-line jq program"}]]},{"k":"h","depth":2,"text":"Update log","id":"update-log"},{"k":"code","lang":"text","text":"2026-05-27  v1.0 — Initial ADR · disposition REJECTED (keep nika:json_diff)\n              · Trigger · operator Rams audit 2026-05-27 evening · post\n                ADR-086/087/088 5-layer symmetry close · « can jq subsume\n                json_diff like jq subsumed json_merge? »\n              · Verification · primary-source jaq + jq + RFC 6902 IETF\n                · capability YES (Turing-equivalent walk) · output-format\n                interop NO (no canonical RFC 6902 emitter)\n              · Decision · keep `nika:json_diff` · 30+ line jq programs\n                violate Rams 10 less-but-better · violate cookbook one-\n                obvious-way contract · break RFC 6902 interop\n              · Canonical 22-builtin count UNCHANGED · 5-layer Rams\n                symmetry (fetch+extract · jq · convert · wait · inspect)\n                holds · json_diff stands as the « jq can't diff to a\n                canonical format » exception\n              · Future revisit triggers documented per LOCK-031 spirit ·\n                cookbook signal · RFC deprecation · jaq native diff filter ·\n                operator explicit cut\n              · Cohérent ADR-082 envelope + ADR-084/085/086/087/088 +\n                Internal · cross-source-validation §2.6 + cognitive-design\n                P4 + one-obvious-way validator canon D-N9/N10\n              · 5 raisons coherence ✅✅✅✅✅"}]

ADR-089

nika:json_diff jq-subsume feasibility · REJECTED · keep RFC-6902 Patch as canonical output format

rejected · 2026-05-27 · cites 5

ADR-089 · `nika:json_diff` jq-subsume feasibility · REJECTED #

Context #

Operator-led Rams audit 2026-05-27 of the canonical 22-builtin set (post-ADR-086/087/088 collapses) identified nika:json_diff as one of the residual data builtins · question to answer · « can jq subsume json_diff like it subsumed map/filter/group_by/json_merge? »

This is the same Rams test that drove the 42 → 22 cascade · the canonical razor « a nika:builtin is justified SSI NOT expressible in jq+CEL+Schema · IS the logic behind the D-N6 collapse 42→26 + ADR-086 csv_to_json cut + ADR-088 4-introspection collapse ».

Per Internal · cross-source-validation §2.6 Signal 3 · single-source jq research insufficient · this ADR documents the primary-source verification (jq capability matrix) and the disposition.

Decision #

REJECTED · keep `nika:json_diff` as canonical builtin emitting RFC-6902 JSON Patch.

Rationale · what jq CAN do #

jq is Turing-equivalent for JSON transformation. A recursive walk over two documents to find differences IS expressible · the rough shape ·

1# Compare two documents at $base and $patch · recursive · produces2# {path, base, patch} tuples for each difference (one possible shape)3def diff($base; $patch; path):4  if ($base | type) == "object" and ($patch | type) == "object" then5    (($base | keys) + ($patch | keys) | unique)[] as $k |6    diff($base[$k]; $patch[$k]; path + [$k])7  elif $base != $patch then8    { path: path, before: $base, after: $patch }9  else empty end ;1011diff(.[0]; .[1]; [])

Capability-wise · jq CAN walk + compare + emit difference tuples. The test « is NOT expressible in jq+CEL+Schema » FAILS at the capability layer for ARBITRARY difference reporting.

Rationale · what jq CANNOT do (the actual cut) #

The justification for nika:json_diff is NOT « jq can't diff » · it's « jq cannot emit RFC-6902 JSON Patch (the canonical interop format) ».

RFC 6902 is the canonical IETF standard for JSON document diffs · shape ·

json

1[2  { "op": "replace", "path": "/foo/bar", "value": 42 },3  { "op": "add",     "path": "/baz",     "value": "new" },4  { "op": "remove",  "path": "/qux" }5]

The 6 operations (add · remove · replace · move · copy · test) have semantic rules · particularly ·

replace vs add discrimination · based on key existence in the base · jq doesn't track « did this key exist in the original document » in a way that survives the recursive walk
remove requires the absence in patch (jq can express absence-of-key via has but threading it through nested recursion is verbose · ~30+ lines of jq for a correctness-equivalent emitter)
move + copy require structural pattern detection (was this add+remove pair semantically a move?) · jq has no notion of « detect this pair as one logical operation »
test is a runtime assertion semantic · belongs to the consumer

A 30+ line jq diff emitter that gets RFC 6902 SEMANTICS right is ·

Not « less but better » · longer than the 22-builtin emit shape it would replace · violates Rams 10 spirit
Cookbook anti-pattern · Internal · the « one obvious way » validator canon (D-N9/N10) requires authors to NOT memorize 30-line jq programs · prefer the canonical builtin
Interop loss · the RFC 6902 output format is the contract downstream tools (JSON Patch apply libraries · OpenAPI diff tooling · GraphQL change-set encoders) expect. Emitting a custom {path, before, after} shape via jq breaks interop · forces every consumer to write a translator

The other 4 introspection razor sister tests #

Same razor applied to ADR-086/087/088 · those COLLAPSED because the collapsed forms WERE strictly better (Rams 10) ·

ADR-086 csv_to_json → convert · was 1 narrow direction · convert exposes 4 formats × 3 directions = 12 capabilities · strictly more power · same surface
ADR-087 sleep + wait_until → wait · the two former builtins were artificially split by mode (relative vs absolute) · unified mode arg IS the « one obvious way »
ADR-088 4 introspection → inspect view: · the 4 were artificially split by query-shape · unified view-discriminator IS the « one obvious way »

The json_diff case is different · the alternative (« express via jq ») would be LESS obvious (30+ lines vs 1 builtin call) AND LESS interoperable (custom diff shape vs RFC 6902 standard). Rams test FAILS in both directions.

Disposition #

KEEP `nika:json_diff` as canonical builtin ·

yaml

1diff:2  ◆invoke:3    tool: "nika:json_diff"4    args:5      base: ${{ vars.original }}6      patch: ${{ vars.modified }}7  # output · RFC 6902 JSON Patch array

Output shape · canonical RFC 6902 Patch array per IETF spec · downstream-interop-clean.

Canonical 22-builtin count UNCHANGED post this ADR · the 5-layer Rams symmetry (fetch+extract · jq · convert · wait · inspect) holds · json_diff stands as the « jq can't diff to a canonical format » exception · same shape as json_merge_patch (RFC 7396 null-delete · jq can't) · same shape as validate (JSON Schema · jq is not a validator).

Future revisit triggers (LOCK-031 strict) #

Per Internal · round-1-ship-pattern §6 LOCK-031 spirit · documented triggers that COULD reopen this disposition ·

Trigger · What it would mean · Likelihood
Cookbook adopts a `jq '... diff ...'` recipe with ≥3 successful invocations · Authors prefer jq-form over builtin · razor shifts · LOW · 30+ line jq programs are off-doctrine
RFC 6902 deprecated by IETF · Output-format interop argument weakens · NEAR-ZERO · RFC is stable since 2013 · widely deployed
jaq ships an `--rfc6902` flag or canonical `diff` filter · jq becomes the canonical RFC 6902 emitter · LOW · would require upstream jaq change
Operator-explicit `« cut json_diff »` signal · The ultimate trigger · same shape as ADR-086 · OPEN

Per Internal · cross-source-validation §2.6 Signal 3 · this ADR is the canonical anti-promotion gate · any future « should we cut json_diff? » discussion routes here.

Cross-source verification (per §2.6 Signal 3 + §2.7.1 cascade-completeness) #

Primary-source verified 2026-05-27 ·

jaq source · jaq/jaq-json/src/lib.rs · NO native diff or rfc6902 filter. The capability is expressible (Turing-equivalent) BUT no canonical output-format emitter shipped.
jq manual · jq-1.7.1 manual at https://jqlang.org/manual/ · no diff builtin · no RFC 6902 support in stdlib.
RFC 6902 · IETF spec stable since 2013 · 6 ops canonical · widely supported by JSON Patch libraries (e.g. serde_json_patch in Rust ecosystem).
Cookbook signal · NIKA_COOKBOOK-v0.1.md · zero recipes that express diff-via-jq · the « one obvious way » authoring contract would reject 30+ line jq programs.

Bucket A (already canon) · nika:json_diff was a D-N5 KEEP · this ADR formalizes the KEEP rationale.

Cohérent #

ADR-082 nika: v1 envelope · 22 builtins canonical · ADR-089 holds count
ADR-084 catalog-spec reconciliation · json_diff stays in catalog
ADR-085 schemars codegen · json_diff enum variant stays
ADR-086/087/088 · 5-layer Rams symmetry · json_diff is the canonical exception that proves the « jq can't do everything » rule
Per Internal · cross-source-validation §2.6 Signal 3 verification
Per Internal · cognitive-design-canon P4 cognitive load · 1-line builtin call beats 30-line jq program

Update log #

text

12026-05-27  v1.0 — Initial ADR · disposition REJECTED (keep nika:json_diff)2              · Trigger · operator Rams audit 2026-05-27 evening · post3                ADR-086/087/088 5-layer symmetry close · « can jq subsume4                json_diff like jq subsumed json_merge? »5              · Verification · primary-source jaq + jq + RFC 6902 IETF6                · capability YES (Turing-equivalent walk) · output-format7                interop NO (no canonical RFC 6902 emitter)8              · Decision · keep `nika:json_diff` · 30+ line jq programs9                violate Rams 10 less-but-better · violate cookbook one-10                obvious-way contract · break RFC 6902 interop11              · Canonical 22-builtin count UNCHANGED · 5-layer Rams12                symmetry (fetch+extract · jq · convert · wait · inspect)13                holds · json_diff stands as the « jq can't diff to a14                canonical format » exception15              · Future revisit triggers documented per LOCK-031 spirit ·16                cookbook signal · RFC deprecation · jaq native diff filter ·17                operator explicit cut18              · Cohérent ADR-082 envelope + ADR-084/085/086/087/088 +19                Internal · cross-source-validation §2.6 + cognitive-design20                P4 + one-obvious-way validator canon D-N9/N1021              · 5 raisons coherence ✅✅✅✅✅

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

Every decision, with its status This one in the repo