@fraczak/k 7.1.0 → 8.0.0

package/scripts/run-tests.mjs

@@ -32,6 +32,11 @@ const derivationTests = fs.readdirSync(path.join(root, "tests/code-derivation"))
 
 const tests = [
   ["tests/test.mjs", node, ["tests/test.mjs"]],
+  [
+    "tests/test-named-patterns.mjs",
+    node,
+    ["tests/test-named-patterns.mjs"]
+  ],
   ...derivationTests,
   ["tests/test-fingerprint.mjs", node, ["tests/test-fingerprint.mjs"]],
   ["tests/test-hash-fuzz.mjs", node, ["tests/test-hash-fuzz.mjs"]],

package/symbol-table.mjs

@@ -93,6 +93,7 @@ function union(rels) {
 class SymbolTable {
   constructor() {
     this.rels = {}; // name -> {def: rel_exp}
+    this.patterns = {}; // name -> {params: string[], filter: filter_ast}
     this.codes = {
       [unitCode]: {
         code: "product",
@@ -109,12 +110,29 @@ class SymbolTable {
   }
 
   add_rel(name, rel) {
-    if (this.rels[name] != undefined)
-      console.error(`SymbolTable: rel '${name}' is redefined (lines ${rel.start?.line}:${rel.start?.column}...${rel.end?.line}:${rel.end?.column})`);
+    if (this.rels[name] != undefined) {
+      console.error(
+        `SymbolTable: rel '${name}' is redefined ` +
+        `(lines ${rel.start?.line}:${rel.start?.column}...` +
+        `${rel.end?.line}:${rel.end?.column})`
+      );
+    }
 
     this.rels[name] = {def: rel};
   }
 
+  add_pattern(name, params, filter) {
+    if (this.patterns[name] != undefined) {
+      console.error(
+        `SymbolTable: pattern '${name}' is redefined ` +
+        `(lines ${filter.start?.line}:${filter.start?.column}...` +
+        `${filter.end?.line}:${filter.end?.column})`
+      );
+    }
+
+    this.patterns[name] = { params, filter };
+  }
+
   add_code(name, code) {
     this.codes[name] = code;
   }

package/tests/bench-djson-tries.mjs

@@ -0,0 +1,340 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { createState, evaluateInput } from "../repl.mjs";
+import * as djsonCodec from "../codecs/djson.mjs";
+import btrieCodec, { indexToBitPath } from "../codecs/djson-btrie.mjs";
+import ptrieCodec from "../codecs/djson-ptrie.mjs";
+import {
+  compileWasmArtifactFromObject,
+  instantiateWasmArtifact,
+  writeValueToArena
+} from "../backends/wasm/src/wasm.mjs";
+import {
+  compileCaseExecutable,
+  prepareRelation,
+  runExecutableMainBench,
+  wireInput
+} from "../backends/llvm/tests/perf-support.mjs";
+
+const llvmCacheDir = fs.mkdtempSync(
+  path.join(os.tmpdir(), "k-djson-bench-")
+);
+
+console.log("=== 1. Codec Round-Trip Verification ===");
+const sampleJson = {
+  name: "Alice",
+  age: 30,
+  active: true,
+  nothing: null,
+  scores: [10, 20, 30, 40, 50],
+  nested: { a: 1, ab: 2, abc: 3, abd: 4, z: 99 }
+};
+const sampleStr = JSON.stringify(sampleJson);
+
+for (const [label, c, pat] of [
+  ["djson (cons-list)", djsonCodec, djsonCodec.DJSON_PATTERN],
+  ["djson-btrie (bit-trie)", btrieCodec, btrieCodec.pattern],
+  ["djson-ptrie (radix-trie)", ptrieCodec, ptrieCodec.pattern]
+]) {
+  const kVal = c.parse(sampleStr);
+  const roundTrip = JSON.parse(c.print(kVal));
+  assert.deepStrictEqual(
+    roundTrip,
+    sampleJson,
+    `${label} round-trip failed`
+  );
+  console.log(
+    `  [OK] ${label.padEnd(26)} pattern nodes: ${pat.length}`
+  );
+}
+
+function indexToKLiteral(idx) {
+  const bits = indexToBitPath(idx);
+  const tags = bits.slice().reverse().map((b) => `|${b}`).join("");
+  return `({}|_${tags})`;
+}
+
+async function setupBenchmarkState(kFile, benchSnippet) {
+  const st = createState({ engine: "wasm" });
+  await evaluateInput(`:load ${kFile}`, st);
+  await evaluateInput(benchSnippet, st);
+  return st;
+}
+
+async function benchRelationOnInput({
+  state,
+  relName,
+  kInput,
+  codec,
+  expectedJson,
+  calls = 1000
+}) {
+  const wire = wireInput(kInput, codec.pattern);
+  const wireBytes = wire.inputWire.length;
+  const prepared = prepareRelation(state, relName);
+
+  // 1. Wasm Compilation & Execution
+  const tWasmComp0 = performance.now();
+  const wasmBytes = await compileWasmArtifactFromObject(prepared.object, {
+    relation: prepared.relationName,
+    inputEnvelopePattern: wire.inputPattern,
+    usePKIR: false
+  });
+  const runner = await instantiateWasmArtifact(wasmBytes);
+  const wasmCompileMs = performance.now() - tWasmComp0;
+
+  // Verify output once
+  const outVal = runner.executeValue(kInput);
+  assert(outVal !== undefined, `${relName} Wasm returned undefined`);
+  assert.deepStrictEqual(
+    JSON.parse(codec.print(outVal)),
+    expectedJson,
+    `Wasm output mismatch for ${relName}`
+  );
+
+  // Write input once to arena, then loop N calls resetting arena mark
+  const ptrIn = writeValueToArena(
+    runner.exports,
+    kInput,
+    runner.inputPattern,
+    0,
+    new Map(),
+    runner.tags,
+    runner.metadata.inputPattern
+  );
+  const mark = runner.exports.arena_mark();
+  const entryFn = runner.exports[runner.metadata.entry];
+
+  // Warmup
+  for (let i = 0; i < 20; i++) {
+    runner.exports.arena_reset(mark);
+    entryFn(ptrIn);
+  }
+
+  const tWasmExec0 = performance.now();
+  for (let i = 0; i < calls; i++) {
+    runner.exports.arena_reset(mark);
+    entryFn(ptrIn);
+  }
+  const wasmExecNsPerCall =
+    ((performance.now() - tWasmExec0) * 1e6) / calls;
+
+  // 2. LLVM Compilation & Execution (-O3)
+  const tLlvmComp0 = performance.now();
+  const exePath = compileCaseExecutable({
+    object: prepared.object,
+    relationName: prepared.relationName,
+    relHash: prepared.relHash,
+    inputPattern: wire.inputPattern,
+    cacheDir: llvmCacheDir,
+    sourceLabel: relName,
+    runtimeMode: "fast",
+    clangOpt: "-O3",
+    usePKIR: false
+  });
+  const llvmCompileMs = performance.now() - tLlvmComp0;
+  const llvmRes = await runExecutableMainBench(
+    exePath,
+    wire.inputWire,
+    calls
+  );
+
+  return {
+    wireBytes,
+    wasmBytes: wasmBytes.length,
+    wasmCompileMs,
+    wasmExecNsPerCall,
+    llvmCompileMs,
+    llvmExecNsPerCall: llvmRes.perCallNs
+  };
+}
+
+const SCHEMAS = [
+  {
+    name: "djson (cons)",
+    kFile: "Examples/djson.k",
+    codec: { ...djsonCodec, pattern: djsonCodec.DJSON_PATTERN },
+    dotExpr:
+      "bench_dot = json? { " +
+      "/list /cons .car /string key, " +
+      "/list /cons .cdr /cons .car /object object } dot json?;"
+  },
+  {
+    name: "djson-btrie",
+    kFile: "Examples/djson-btrie.k",
+    codec: btrieCodec,
+    dotExpr:
+      "bench_dot = json? { " +
+      "{ 0 index, /list list } nth /string key, " +
+      "{ 1 index, /list list } nth /object object } dot json?;"
+  },
+  {
+    name: "djson-ptrie",
+    kFile: "Examples/djson-ptrie.k",
+    codec: ptrieCodec,
+    dotExpr:
+      "bench_dot = json? { " +
+      "{ 0 index, /list list } nth /string key, " +
+      "{ 1 index, /list list } nth /object object } dot json?;"
+  }
+];
+
+console.log(
+  "\n=== 2A. Object Lookup (`dot`) — " +
+  "Shared-Prefix Keys (Wasm vs LLVM -O3) ==="
+);
+for (const numKeys of [10, 100, 500]) {
+  const obj = {};
+  for (let i = 0; i < numKeys; i++) {
+    const k = `field_prefix_${String(i).padStart(4, "0")}`;
+    obj[k] = i * 10;
+  }
+  const targetKey =
+    `field_prefix_${String(numKeys - 1).padStart(4, "0")}`;
+  const expectedVal = (numKeys - 1) * 10;
+  const inputJsonStr = JSON.stringify([targetKey, obj]);
+
+  console.log(
+    `\n--- Object with ${numKeys} shared-prefix keys ` +
+    `(querying '${targetKey}') ---`
+  );
+  console.log(
+    "Schema          | Wire (B) | Wasm (B) | " +
+    "Wasm Comp | LLVM Comp | Wasm (ns/call) | LLVM (ns/call)"
+  );
+  console.log(
+    "----------------+----------+----------+-" +
+    "----------+-----------+----------------+---------------"
+  );
+
+  for (const s of SCHEMAS) {
+    const st = await setupBenchmarkState(s.kFile, s.dotExpr);
+    const kInput = s.codec.parse(inputJsonStr);
+    const res = await benchRelationOnInput({
+      state: st,
+      relName: "bench_dot",
+      kInput,
+      codec: s.codec,
+      expectedJson: expectedVal,
+      calls: 1000
+    });
+    console.log(
+      `${s.name.padEnd(15)} | ${String(res.wireBytes).padStart(8)} | ` +
+      `${String(res.wasmBytes).padStart(8)} | ` +
+      `${res.wasmCompileMs.toFixed(0).padStart(7)}ms | ` +
+      `${res.llvmCompileMs.toFixed(0).padStart(7)}ms | ` +
+      `${res.wasmExecNsPerCall.toFixed(0).padStart(14)} | ` +
+      `${res.llvmExecNsPerCall.toFixed(0).padStart(14)}`
+    );
+  }
+}
+
+console.log(
+  "\n=== 2B. Object Lookup (`dot`) — " +
+  "Distinct/Varied Keys (Wasm vs LLVM -O3) ==="
+);
+const WORDS = [
+  "account", "balance", "category", "database", "endpoint",
+  "filename", "geometry", "hostname", "identity", "journal",
+  "keyboard", "language", "metadata", "network", "operator",
+  "password", "quantity", "resource", "security", "template",
+  "username", "validate", "workflow", "x509cert", "yearbook", "zoneinfo"
+];
+for (const numKeys of [10, 100, 500]) {
+  const obj = {};
+  for (let i = 0; i < numKeys; i++) {
+    const w1 = WORDS[i % WORDS.length];
+    const w2 = WORDS[Math.floor(i / WORDS.length) % WORDS.length];
+    const k = `${w1}_${i}_${w2}_attr`;
+    obj[k] = i * 10;
+  }
+  const targetKey = Object.keys(obj).sort().at(-1);
+  const expectedVal = obj[targetKey];
+  const inputJsonStr = JSON.stringify([targetKey, obj]);
+
+  console.log(
+    `\n--- Object with ${numKeys} varied keys ` +
+    `(querying '${targetKey}') ---`
+  );
+  console.log(
+    "Schema          | Wire (B) | Wasm (B) | " +
+    "Wasm Comp | LLVM Comp | Wasm (ns/call) | LLVM (ns/call)"
+  );
+  console.log(
+    "----------------+----------+----------+-" +
+    "----------+-----------+----------------+---------------"
+  );
+
+  for (const s of SCHEMAS) {
+    const st = await setupBenchmarkState(s.kFile, s.dotExpr);
+    const kInput = s.codec.parse(inputJsonStr);
+    const res = await benchRelationOnInput({
+      state: st,
+      relName: "bench_dot",
+      kInput,
+      codec: s.codec,
+      expectedJson: expectedVal,
+      calls: 1000
+    });
+    console.log(
+      `${s.name.padEnd(15)} | ${String(res.wireBytes).padStart(8)} | ` +
+      `${String(res.wasmBytes).padStart(8)} | ` +
+      `${res.wasmCompileMs.toFixed(0).padStart(7)}ms | ` +
+      `${res.llvmCompileMs.toFixed(0).padStart(7)}ms | ` +
+      `${res.wasmExecNsPerCall.toFixed(0).padStart(14)} | ` +
+      `${res.llvmExecNsPerCall.toFixed(0).padStart(14)}`
+    );
+  }
+}
+
+console.log(
+  "\n=== 3. List Element Lookup (`nth`) Benchmark (Wasm vs LLVM -O3) ==="
+);
+for (const len of [10, 100, 500]) {
+  const arr = Array.from({ length: len }, (_, i) => i * 3);
+  const targetIdx = len - 1;
+  const expectedVal = targetIdx * 3;
+  const inputJsonStr = JSON.stringify(arr);
+  const idxLit = indexToKLiteral(targetIdx);
+  const nthExpr =
+    `bench_nth = json? { ${idxLit} index, /list list } nth json?;`;
+
+  console.log(
+    `\n--- Array with ${len} elements ` +
+    `(querying index ${targetIdx}) ---`
+  );
+  console.log(
+    "Schema          | Wire (B) | Wasm (B) | " +
+    "Wasm Comp | LLVM Comp | Wasm (ns/call) | LLVM (ns/call)"
+  );
+  console.log(
+    "----------------+----------+----------+-" +
+    "----------+-----------+----------------+---------------"
+  );
+
+  for (const s of SCHEMAS) {
+    const st = await setupBenchmarkState(s.kFile, nthExpr);
+    const kInput = s.codec.parse(inputJsonStr);
+    const res = await benchRelationOnInput({
+      state: st,
+      relName: "bench_nth",
+      kInput,
+      codec: s.codec,
+      expectedJson: expectedVal,
+      calls: 1000
+    });
+    console.log(
+      `${s.name.padEnd(15)} | ${String(res.wireBytes).padStart(8)} | ` +
+      `${String(res.wasmBytes).padStart(8)} | ` +
+      `${res.wasmCompileMs.toFixed(0).padStart(7)}ms | ` +
+      `${res.llvmCompileMs.toFixed(0).padStart(7)}ms | ` +
+      `${res.wasmExecNsPerCall.toFixed(0).padStart(14)} | ` +
+      `${res.llvmExecNsPerCall.toFixed(0).padStart(14)}`
+    );
+  }
+}
+
+fs.rmSync(llvmCacheDir, { recursive: true, force: true });

package/tests/test-codecs.mjs

@@ -8,10 +8,17 @@ import { fileURLToPath } from "node:url";
 import * as SDK from "../codecs/runtime/codec-sdk.mjs";
 import * as IntCodec from "../codecs/int.mjs";
 import * as JsonCodec from "../codecs/json.mjs";
+import * as DjsonCodec from "../codecs/djson.mjs";
+import * as DjsonBtrieCodec from "../codecs/djson-btrie.mjs";
+import * as DjsonPtrieCodec from "../codecs/djson-ptrie.mjs";
 import * as Utf8Codec from "../codecs/utf8.mjs";
 import * as Utf16Codec from "../codecs/utf16.mjs";
 import * as IeeeCodec from "../codecs/ieee.mjs";
 import * as UnitCodec from "../codecs/unit.mjs";
+import {
+  valueToK,
+  valueWithEnvelopeToK
+} from "../codecs/runtime/show-value.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -49,6 +56,17 @@ console.log("2. Verifying in-memory parse -> enveloped value (P, v)...");
 for (const [name, codec, sampleInput] of [
   ["int.mjs", IntCodec, "42"],
   ["json.mjs", JsonCodec, '{"x": 1}'],
+  ["djson.mjs", DjsonCodec, '{"x": 1, "arr": [true, null, "hi"]}'],
+  [
+    "djson-btrie.mjs",
+    DjsonBtrieCodec,
+    '{"x": 1, "arr": [true, null, "hi"]}'
+  ],
+  [
+    "djson-ptrie.mjs",
+    DjsonPtrieCodec,
+    '{"x": 1, "arr": [true, null, "hi"]}'
+  ],
   ["utf8.mjs", Utf8Codec, "hello"],
   ["utf16.mjs", Utf16Codec, "hello"],
   ["ieee.mjs", IeeeCodec, "3.14"],
@@ -68,6 +86,9 @@ console.log("3. Verifying CLI --help flag...");
 for (const relPath of [
   "codecs/int.mjs",
   "codecs/json.mjs",
+  "codecs/djson.mjs",
+  "codecs/djson-btrie.mjs",
+  "codecs/djson-ptrie.mjs",
   "codecs/utf8.mjs",
   "codecs/utf16.mjs",
   "codecs/ieee.mjs",
@@ -111,6 +132,24 @@ console.log("4. Verifying CLI --parse and --print pipelines...");
   assert.deepEqual(JSON.parse(printRes.stdout.toString("utf8")), JSON.parse(jsonInput));
 }
 
+// djson.mjs: dynamic JSON AST with singleton pattern
+{
+  const djsonInput = JSON.stringify({
+    name: "k",
+    count: 42.5,
+    tags: ["fast", "typed"],
+    meta: { active: true, extra: null }
+  });
+  const parseRes = runCLI("codecs/djson.mjs", ["--parse"], djsonInput);
+  assert.equal(parseRes.status, 0);
+  const printRes = runCLI("codecs/djson.mjs", ["--print"], parseRes.stdout);
+  assert.equal(printRes.status, 0);
+  assert.deepEqual(
+    JSON.parse(printRes.stdout.toString("utf8")),
+    JSON.parse(djsonInput)
+  );
+}
+
 // utf8.mjs: unicode text
 {
   const utf8Input = "Hello 🌍, ąęćłó! \nSecond line.";
@@ -183,4 +222,176 @@ console.log("6. Verifying pattern derivation via k type system (patternFromFilte
   assert.throws(() => SDK.patternFromFilter(".field"), /Main expression must be a filter or a type name/);
 }
 
+// 7. Lazy Prefix-Free Wire Decoding
+console.log("7. Verifying lazy prefix-free wire decoding...");
+{
+  assert.equal(typeof SDK.decodeWireLazy, "function");
+
+  // Lazy decoding should instantiate root in sub-millisecond time
+  const sampleStr = "a".repeat(20000);
+  const parsedStr = Utf8Codec.parse(sampleStr);
+  const wireStr = SDK.encodeToWire(parsedStr, parsedStr.pattern);
+
+  const t0 = performance.now();
+  const decodedLazy = SDK.decodeWire(wireStr);
+  const constructMs = performance.now() - t0;
+  assert(
+    constructMs < 50,
+    `Lazy decode took ${constructMs}ms (expected <50ms)`
+  );
+  assert.equal(decodedLazy.value.tag, "cons");
+
+  // On-demand traversal through print()
+  const printedStr = Utf8Codec.print(decodedLazy.value);
+  assert.equal(printedStr, sampleStr);
+
+  // Lazy list of integers
+  const ints = Array.from({ length: 5000 }, (_, i) => i).join(",");
+  const sampleList = `[${ints}]`;
+  const parsedList = IntCodec.parse(sampleList);
+  const wireList = SDK.encodeToWire(parsedList, parsedList.pattern);
+  const decodedList = SDK.decodeWireLazy(wireList);
+  assert.equal(IntCodec.print(decodedList.value), sampleList);
+
+  // Verify stack-safe toJSON on deep variant chains
+  let deepVal = SDK.Value.product({});
+  for (let i = 0; i < 15000; i++) {
+    deepVal = SDK.Value.variant("step", deepVal);
+  }
+  const json = deepVal.toJSON();
+  assert(json && typeof json === "object");
+}
+
+// 8. High-Speed Direct Bitstream String Decoding & Bounded Rendering
+console.log("8. Verifying fast string decoding & bounded rendering...");
+{
+  const testStrings = [
+    "hello world",
+    "Zażółć gęślą jaźń",
+    "Unicode: 🚀🎉 𝒦-lang π ≈ 3.14159",
+    "a".repeat(50000),
+    ""
+  ];
+
+  for (const s of testStrings) {
+    const parsed = Utf8Codec.parse(s);
+    const wire = SDK.encodeToWire(parsed, parsed.pattern);
+    const decoded = SDK.decodeWire(wire);
+    const restored = Utf8Codec.print(decoded.value);
+    assert.equal(
+      restored,
+      s,
+      `String round-trip failed for "${s.slice(0, 20)}..."`
+    );
+  }
+
+  // Fast decoding performance: 50,000 ASCII chars in < 500ms
+  const bigAscii = "x".repeat(50000);
+  const bigParsed = Utf8Codec.parse(bigAscii);
+  const bigWire = SDK.encodeToWire(bigParsed, bigParsed.pattern);
+  const tStart = performance.now();
+  const bigDecoded = SDK.decodeWire(bigWire);
+  const bigRestored = Utf8Codec.print(bigDecoded.value);
+  const elapsed = performance.now() - tStart;
+  assert.equal(bigRestored.length, 50000);
+  assert(
+    elapsed < 500,
+    `Fast string decoding took ${elapsed}ms (expected < 500ms)`
+  );
+
+  // Bounded rendering: valueToK with limit
+  let deepVal = SDK.Value.product({});
+  for (let i = 0; i < 1000; i++) {
+    deepVal = SDK.Value.variant("item", deepVal);
+  }
+  const preview = valueToK(deepVal, 30);
+  assert(preview.endsWith("..."), "Output should end with '...'");
+  assert(preview.length <= 35, "Preview length should stay bounded");
+
+  // valueWithEnvelopeToK with limit
+  const enveloped = SDK.withPattern(deepVal, [["any", []]]);
+  const envPreview = valueWithEnvelopeToK(enveloped, 30);
+  assert(envPreview.includes("..."), "Preview should contain '...'");
+
+  // Ensure early termination: evaluating deep chain with limit 20
+  let hugeVal = SDK.Value.product({});
+  for (let i = 0; i < 50000; i++) {
+    hugeVal = SDK.Value.variant("v", hugeVal);
+  }
+  const tEarly0 = performance.now();
+  const earlyPreview = valueToK(hugeVal, 20);
+  const tEarlyElapsed = performance.now() - tEarly0;
+  assert(earlyPreview.endsWith("..."));
+  assert(
+    tEarlyElapsed < 50,
+    `Early termination took ${tEarlyElapsed}ms (expected < 50ms)`
+  );
+}
+
+// 9. DJSON Family Singleton Pattern Invariants & Round-Trip
+console.log("9. Verifying DJSON family singleton pattern invariants...");
+{
+  assert(Array.isArray(DjsonCodec.DJSON_PATTERN));
+  assert.equal(DjsonCodec.DJSON_PATTERN.length, 29);
+  assert(Array.isArray(DjsonBtrieCodec.DJSON_BTRIE_PATTERN));
+  assert.equal(DjsonBtrieCodec.DJSON_BTRIE_PATTERN.length, 27);
+  assert(Array.isArray(DjsonPtrieCodec.DJSON_PTRIE_PATTERN));
+  assert.equal(DjsonPtrieCodec.DJSON_PTRIE_PATTERN.length, 33);
+
+  const samples = [
+    null,
+    true,
+    false,
+    123.456,
+    "Hello world!",
+    [],
+    [1, "text", false, null],
+    {},
+    { key: "value", nested: [1, 2, { deep: true }] }
+  ];
+
+  for (const [label, codec, pat, relPath] of [
+    ["djson", DjsonCodec, DjsonCodec.DJSON_PATTERN, "codecs/djson.mjs"],
+    [
+      "djson-btrie",
+      DjsonBtrieCodec,
+      DjsonBtrieCodec.DJSON_BTRIE_PATTERN,
+      "codecs/djson-btrie.mjs"
+    ],
+    [
+      "djson-ptrie",
+      DjsonPtrieCodec,
+      DjsonPtrieCodec.DJSON_PTRIE_PATTERN,
+      "codecs/djson-ptrie.mjs"
+    ]
+  ]) {
+    for (const sample of samples) {
+      const jsonStr = JSON.stringify(sample);
+      const enveloped = codec.parse(jsonStr);
+      assert.strictEqual(
+        enveloped.pattern,
+        pat,
+        `Every ${label} value must share the exact singleton pattern`
+      );
+      const wire = SDK.encodeToWire(enveloped, enveloped.pattern);
+      const decoded = SDK.decodeWire(wire);
+      const restored = codec.print(decoded.value);
+      assert.deepEqual(
+        JSON.parse(restored),
+        sample,
+        `${label} round-trip mismatch for: ${jsonStr}`
+      );
+    }
+    const cliSample = JSON.stringify({ a: 1, b: [true, "ok"] });
+    const parseRes = runCLI(relPath, ["--parse"], cliSample);
+    assert.equal(parseRes.status, 0);
+    const printRes = runCLI(relPath, ["--print"], parseRes.stdout);
+    assert.equal(printRes.status, 0);
+    assert.deepEqual(
+      JSON.parse(printRes.stdout.toString("utf8")),
+      JSON.parse(cliSample)
+    );
+  }
+}
+
 console.log("OK - All codec tests passed.");