@fraczak/k 7.2.0 → 8.1.0

package/repl.mjs

@@ -21,7 +21,7 @@ if (typeof globalThis !== "undefined") {
   globalThis.isVariant = isVariant;
   globalThis.patternFromFilter = patternFromFilter;
 }
-import { prettyCode } from "./pretty.mjs";
+import { prettyCode, prettyFilter } from "./pretty.mjs";
 import {
   compileObject,
   compileLibrary,
@@ -32,7 +32,11 @@ import {
   loadLibrary,
   prettyRelation
 } from "./object.mjs";
-import { propertyListToFilter, valueToK, valueWithEnvelopeToK } from "./codecs/runtime/show-value.mjs";
+import {
+  propertyListToFilter,
+  valueToK,
+  valueWithEnvelopeToK
+} from "./codecs/runtime/show-value.mjs";
 import {
   codecNames,
   codeHashToPattern,
@@ -48,7 +52,7 @@ import {
 
 const NAME_RE = /^[a-zA-Z0-9_+-][a-zA-Z0-9_?!+-]*$/;
 const COMMAND_NAMES = [
-  "help", "rel",
+  "help", "rel", "pattern", "pat", "patterns", "pats",
   "codecs", "rels", "codec", "input", "reset", "klib", "ko", "load",
   "engine", "wasm", "pkir", "js", "limit",
   "quit", "exit"
@@ -87,6 +91,7 @@ function createState(options = {}) {
     rels: {},
     relAliases: {},
     typeAliases: {},
+    patterns: {},
     codecs: {},
     loadedFiles: new Set(),
     pendingInput: null,
@@ -106,6 +111,7 @@ function stateLibrary(state) {
     codes: state.codes,
     rels: state.rels,
     relAlias: state.relAliases,
+    patterns: state.patterns,
     meta: state.meta,
     main: null
   };
@@ -227,6 +233,11 @@ function mergeLibrary(state, lib, source = "<load>", options = {}) {
   const loadAliases = options.loadAliases ?? true;
   state.codes = { ...state.codes, ...(lib.codes || {}) };
   state.rels = { ...state.rels, ...(lib.rels || {}) };
+  state.patterns = {
+    ...state.patterns,
+    ...(lib.patterns || lib.sourceDefs?.patterns ||
+      lib.defs?.patterns || {})
+  };
   mergeMeta(state, lib.meta);
 
   if (loadAliases) {
@@ -310,6 +321,7 @@ function savedLibrary(state) {
     rels,
     relAlias: state.relAliases,
     compileStats: { sccs: [], sccCount: 0 },
+    patterns: state.patterns || {},
     meta: Object.fromEntries(
       Object.entries(meta).filter(([hash]) => storedHashes.has(hash))
     ),
@@ -320,7 +332,10 @@ function savedLibrary(state) {
 function executableObject(state, mainExpression) {
   const main = (mainExpression || state.lastMain || "").trim();
   if (!main) {
-    throw new Error(":ko file expr requires a main expression unless one has already been evaluated or defined");
+    throw new Error(
+      ":ko file expr requires a main expression unless one has " +
+      "already been evaluated or defined"
+    );
   }
 
   restoreCodes(state);
@@ -328,7 +343,8 @@ function executableObject(state, mainExpression) {
   try {
     return compileObject([preamble, main].filter(Boolean).join("\n"), {
       source: "<repl>",
-      libraries: [stateLibrary(state)]
+      libraries: [stateLibrary(state)],
+      patterns: state.patterns
     });
   } catch (error) {
     throw remapError(error, preambleLineCount(preamble));
@@ -343,11 +359,72 @@ function resolveRel(state, name) {
 }
 
 function listAliases(aliases) {
-  const entries = Object.entries(aliases).sort(([a], [b]) => a.localeCompare(b));
+  const entries = Object.entries(aliases).sort(([a], [b]) =>
+    a.localeCompare(b)
+  );
   if (entries.length === 0) return "(none)";
   return entries.map(([name, hash]) => `${name} = ${hash}`).join("\n");
 }
 
+function resolvePatternCanonicalName(state, name, pat) {
+  if (!state || !pat) return null;
+  if (pat._canonical) return pat._canonical;
+  const params = pat.params || [];
+  const source = `? ${name}[${params.join(", ")}]`;
+  try {
+    restoreCodes(state);
+    const annotated = annotate(source, {
+      libraries: [stateLibrary(state)],
+      patterns: state.patterns
+    });
+    const mainRel = annotated.rels.__main__;
+    if (
+      mainRel?.typePatternGraph &&
+      mainRel?.def?.patterns?.[0] != null
+    ) {
+      const rootId = mainRel.typePatternGraph.find(
+        mainRel.def.patterns[0]
+      );
+      const propList = patternToPropertyList(
+        exportPatternGraph(mainRel.typePatternGraph, rootId)
+      );
+      const codeHash = closedPatternToCodeHash(propList);
+      if (codeHash) {
+        state.codes = codes.dump();
+        pat._canonical = codeHash;
+        return codeHash;
+      }
+    }
+    const relHash = annotated.relAlias?.__main__ || null;
+    if (relHash) {
+      pat._canonical = relHash;
+      return relHash;
+    }
+  } catch {
+    restoreCodes(state);
+    return null;
+  }
+  return null;
+}
+
+function prettyPattern(name, pat, state = null) {
+  const params = (pat?.params || []).join(", ");
+  const filterStr = pat?.filter ? prettyFilter(pat.filter) : "()";
+  const canonical = resolvePatternCanonicalName(state, name, pat);
+  const suffix = canonical ? `  -- ${canonical}` : "";
+  return `${name}[${params}] = ${filterStr};${suffix}`;
+}
+
+function listPatterns(patterns) {
+  const entries = Object.entries(patterns || {}).sort(([a], [b]) =>
+    a.localeCompare(b)
+  );
+  if (entries.length === 0) return "(none)";
+  return entries
+    .map(([name, pat]) => `${name}[${(pat?.params || []).join(", ")}]`)
+    .join("\n");
+}
+
 function formatCodecOutput(output) {
   if (typeof Buffer !== "undefined" && Buffer.isBuffer(output)) return output.toString("utf8");
   if (typeof Uint8Array !== "undefined" && output instanceof Uint8Array) return new TextDecoder().decode(output);
@@ -644,9 +721,16 @@ function resolveTypeExpressionHash(state, rawType) {
   ].filter(Boolean).join("\n");
 
   try {
-    const annotated = annotate(source, { libraries: [stateLibrary(state)] });
+    const annotated = annotate(source, {
+      libraries: [stateLibrary(state)],
+      patterns: state.patterns
+    });
     const hash = annotated.representatives[INPUT_TYPE_NAME];
-    if (!hash) throw new Error(":input type expression did not produce a code hash");
+    if (!hash) {
+      throw new Error(
+        ":input type expression did not produce a code hash"
+      );
+    }
     state.codes = codes.dump();
     return hash;
   } catch (error) {
@@ -672,7 +756,10 @@ function resolvePatternExpression(state, patternExpr) {
     patternExpr
   ].filter(Boolean).join("\n");
   try {
-    const annotated = annotate(source, { libraries: [stateLibrary(state)] });
+    const annotated = annotate(source, {
+      libraries: [stateLibrary(state)],
+      patterns: state.patterns
+    });
     const mainRel = annotated.rels.__main__;
     if (!mainRel || !mainRel.typePatternGraph) {
       throw new Error(`Invalid pattern expression '${patternExpr}'`);
@@ -771,6 +858,25 @@ function completeCommandArgument(line, state) {
   const argStart = 1 + firstSpace + 1;
   const arg = line.slice(argStart);
 
+  if (command === "pattern" || command === "pat") {
+    const trimmed = arg.trimStart();
+    const leadingWhitespace = arg.length - trimmed.length;
+    const prefix = line.slice(0, argStart + leadingWhitespace);
+    const names = Object.keys(state.patterns || {}).sort();
+    const matches = names
+      .filter((name) => name.startsWith(trimmed))
+      .map((name) => `${prefix}${name}`);
+    if (trimmed.startsWith("@")) {
+      for (const [name, p] of Object.entries(state.patterns || {})) {
+        const hash = resolvePatternCanonicalName(state, name, p);
+        if (hash && hash.startsWith(trimmed)) {
+          matches.push(`${prefix}${hash}`);
+        }
+      }
+    }
+    return [matches, line];
+  }
+
   if (command === "codec" || command === "codecs") {
     return completeCodecCommand(line, argStart, arg, state);
   }
@@ -877,7 +983,10 @@ function resolveKFilePath(filePath) {
     if (fs.existsSync(strippedEx)) return strippedEx;
   } catch {}
   try {
-    const fromRepoStripped = path.resolve(path.dirname(fileURLToPath(import.meta.url)), strippedEx);
+    const fromRepoStripped = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      strippedEx
+    );
     if (fs.existsSync(fromRepoStripped)) return fromRepoStripped;
   } catch {}
   return filePath;
@@ -908,7 +1017,8 @@ function loadSourceOrKlib(state, targetPath, options = {}) {
     const fullSource = [preamble, source].filter(Boolean).join("\n");
     const compileOptions = {
       source: targetPath,
-      libraries: [stateLibrary(state)]
+      libraries: [stateLibrary(state)],
+      patterns: state.patterns
     };
     try {
       const lib = compileWithOptionalIdentity(fullSource, compileOptions);
@@ -972,15 +1082,29 @@ function compileSnippetArtifacts(source, state, sourceName = "<repl>") {
   const fullSource = [preamble, source].filter(Boolean).join("\n");
   const options = {
     source: sourceName,
-    libraries: [stateLibrary(state)]
+    libraries: [stateLibrary(state)],
+    patterns: state.patterns
   };
   try {
     const lib = compileWithOptionalIdentity(fullSource, options);
-    const { relAlias, meta } = libraryOriginsFromSource(source, fullSource, lib, options);
+    const { relAlias, meta } = libraryOriginsFromSource(
+      source,
+      fullSource,
+      lib,
+      options
+    );
     const annotated = annotateWithOptionalIdentity(fullSource, options);
     return {
       annotated,
-      lib: { ...lib, relAlias, meta },
+      lib: {
+        ...lib,
+        relAlias,
+        meta,
+        patterns: {
+          ...(state.patterns || {}),
+          ...(annotated.sourceDefs?.patterns || {})
+        }
+      },
       lineOffset: preambleLineCount(preamble)
     };
   } catch (error) {
@@ -1233,14 +1357,49 @@ async function evaluateCommand(line, state) {
     case "rel": {
       if (!arg) throw new Error(`${usagePrefix}rel requires a relation name`);
       if (arg.includes("=")) {
-        throw new Error("Relation definitions use syntax: name = relExpr; Use :rel <name> to show a relation definition");
+        throw new Error(
+          "Relation definitions use syntax: name = relExpr; " +
+          "Use :rel <name> to show a relation definition"
+        );
       }
       const { hash, rel } = resolveRel(state, arg);
       if (!rel) throw new Error(`Unknown relation '${arg}'`);
-      return [`${arg} = ${prettyRelation(rel, displayAliases(state), state.relAliases)};  -- ${hash}`];
+      const prettyRelStr = prettyRelation(
+        rel,
+        displayAliases(state),
+        state.relAliases
+      );
+      return [`${arg} = ${prettyRelStr};  -- ${hash}`];
     }
     case "rels":
       return [listAliases(state.relAliases)];
+    case "pattern":
+    case "pat": {
+      if (!arg) {
+        throw new Error(`${usagePrefix}pattern requires a pattern name`);
+      }
+      const rawName = arg.trim();
+      let patternName = rawName.replace(/\[.*\]$/, "").trim();
+      let pat = state.patterns?.[patternName];
+      if (!pat && patternName.startsWith("@")) {
+        for (const [name, p] of Object.entries(state.patterns || {})) {
+          if (
+            resolvePatternCanonicalName(state, name, p) === patternName
+          ) {
+            patternName = name;
+            pat = p;
+            break;
+          }
+        }
+      }
+      if (!pat) {
+        throw new Error(`Unknown pattern '${rawName}'`);
+      }
+      return [prettyPattern(patternName, pat, state)];
+    }
+    case "patterns":
+    case "pats":
+      return [listPatterns(state.patterns)];
     case "codec":
     case "codecs":
       return loadCodec(arg, state);
@@ -1333,19 +1492,23 @@ function helpText() {
     ":engine [wasm|pkir|js]   display or switch evaluation engine",
     ":rel name            show relation definition",
     ":rels                list relation aliases",
+    ":pattern name        show named pattern definition (alias :pat)",
+    ":patterns            list defined named patterns (alias :pats)",
     ":limit [num|none]    set maximum characters for value output",
-    ":codec load file     load a codec module from file (e.g. :codec load codecs/int.mjs)",
+    ":codec load file     load a codec module from file",
     ":codec unload name   unload a registered codec",
     ":codec list          list loaded codecs (or simply :codecs)",
-    ":input <codec.mjs> [text]  parse input using specified codec",
-    ":load [--no-alias] file",
-    "                     load .k source or .klib",
+    ":input <codec> [txt] parse input using specified codec",
+    ":load [--no-alias] f load .k source or .klib",
     ":klib file           export state as a library",
     ":ko file expr        export executable .ko using expr as main",
     ":reset               clear state",
     ":help                show this help",
     "",
-    "Raw k input is compiled as a snippet on top of the current state.",
+    "Raw k input:",
+    "  name = expr;             define relation alias",
+    "  name[P1, ...] = filter;  define named pattern template",
+    "  ? name[...]              evaluate named pattern filter",
     "A line ending with ';' plus only spaces closes the snippet.",
     "Use '\\' to force continuation."
   ].join("\n");
@@ -1553,5 +1716,8 @@ export {
   formatDuration,
   codecNames,
   ensureEnveloped,
-  patternFromFilter
+  patternFromFilter,
+  prettyPattern,
+  resolvePatternCanonicalName,
+  listPatterns
 };

package/scripts/build-repl-html.mjs

@@ -78,8 +78,14 @@ if (fs.existsSync(coreKPath)) {
   vfsFiles["core.k"] = fs.readFileSync(coreKPath, "utf8");
 }
 
-// Add verified k-code files: arithmetics.k, ieee.k, poly.k, karatsuba-mult.k
-const verifiedExamples = ["arithmetics.k", "ieee.k", "poly.k", "karatsuba-mult.k"];
+// Add verified k-code files
+const verifiedExamples = [
+  "arithmetics.k",
+  "ieee.k",
+  "poly.k",
+  "karatsuba-mult.k",
+  "djson.k"
+];
 const examplesDir = path.join(projectRoot, "Examples");
 for (const filename of verifiedExamples) {
   const fullPath = path.join(examplesDir, filename);
@@ -645,6 +651,12 @@ const htmlContent = `<!DOCTYPE html>
       text-overflow: ellipsis;
       white-space: nowrap;
       flex: 1;
+      min-width: 0;
+    }
+
+    .k-btn-copy {
+      flex-shrink: 0;
+      margin-left: auto;
     }
 
     .k-tree-section-body {
@@ -1681,6 +1693,7 @@ const htmlContent = `<!DOCTYPE html>
               <option value="ieee.k">ieee.k</option>
               <option value="poly.k">poly.k</option>
               <option value="karatsuba-mult.k">karatsuba-mult.k</option>
+              <option value="djson.k">djson.k</option>
             </optgroup>
             <optgroup label="Quick Expressions">
               <option value="expr:{} | ok">{} | ok</option>
@@ -1700,9 +1713,11 @@ const htmlContent = `<!DOCTYPE html>
               <option value="expr::codec load int.mjs">:codec load int.mjs</option>
               <option value="expr::codec load utf8.mjs">:codec load utf8.mjs</option>
               <option value="expr::codec load json.mjs">:codec load json.mjs</option>
+              <option value="expr::codec load djson.mjs">:codec load djson.mjs</option>
               <option value="expr::codec load ieee.mjs">:codec load ieee.mjs</option>
               <option value="expr::codec load unit.mjs">:codec load unit.mjs</option>
               <option value="expr::input json.mjs {&quot;a&quot;:12,&quot;b&quot;:&quot;hello&quot;}">:input json.mjs {"a":12,"b":"hello"}</option>
+              <option value="expr::input djson.mjs {&quot;a&quot;:12,&quot;b&quot;:&quot;hello&quot;}">:input djson.mjs {"a":12,"b":"hello"}</option>
               <option value="expr::input int.mjs [0,1,2]">:input int.mjs [0,1,2]</option>
             </optgroup>
           </select>
@@ -1837,6 +1852,16 @@ const htmlContent = `<!DOCTYPE html>
                   <td><code>name = relExpr;</code></td>
                   <td><b>Relation Alias:</b> Defines a local alias for a relation expression.<br><i>e.g.</i> <code>swap = { . y x, . x y };</code></td>
                 </tr>
+                <tr>
+                  <td><code>name[P1, ..., Pn] = filter;</code></td>
+                  <td>
+                    <b>Named Pattern Template:</b> Defines a reusable
+                    pattern template.<br>
+                    <i>e.g.</i><br>
+                    <code>bit[] = &lt; {} 0, {} 1 &gt;;</code> or<br>
+                    <code>list[X] = &lt; {} nil, ... &gt; = Y;</code>
+                  </td>
+                </tr>
               </tbody>
             </table>
 
@@ -1872,8 +1897,15 @@ const htmlContent = `<!DOCTYPE html>
                   <td><b>Variant Constructor:</b> Wraps document into variant <code>tag</code></td>
                 </tr>
                 <tr>
-                  <td><code>? filterExpr</code></td>
-                  <td><b>Pattern Filter:</b> Asserts input matches pattern; acts as partial identity and inductive termination witness (<i>e.g.</i> <code>?&lt; {} true, {} false &gt;</code>)</td>
+                  <td>
+                    <code>? filterExpr</code> /
+                    <code>? name[...]</code>
+                  </td>
+                  <td>
+                    <b>Pattern Filter:</b> Asserts input matches pattern;
+                    acts as partial identity and inductive witness
+                    (<i>e.g.</i> <code>? list[X]</code>)
+                  </td>
                 </tr>
                 <tr>
                   <td><code>name</code> / <code>@hash</code></td>
@@ -1888,6 +1920,20 @@ const htmlContent = `<!DOCTYPE html>
             <table class="help-table">
               <tr><td><code>:engine [wasm|pkir|js]</code></td><td>Display or switch evaluation engine (<code>wasm</code>, <code>pkir</code>, or <code>js</code>)</td></tr>
               <tr><td><code>:load &lt;file&gt;</code></td><td>Load a <code>.k</code> source or <code>.klib</code> library into current state</td></tr>
+              <tr>
+                <td><code>:pattern &lt;name&gt;</code></td>
+                <td>
+                  Display definition of named pattern
+                  <code>&lt;name&gt;</code> (alias <code>:pat</code>)
+                </td>
+              </tr>
+              <tr>
+                <td><code>:patterns</code></td>
+                <td>
+                  List defined named pattern templates
+                  (alias <code>:pats</code>)
+                </td>
+              </tr>
               <tr><td><code>:rel &lt;name&gt;</code></td><td>Display definition of relation <code>&lt;name&gt;</code></td></tr>
               <tr><td><code>:rels</code></td><td>List all relation aliases</td></tr>
               <tr><td><code>:codecs</code></td><td>List all loaded format codecs</td></tr>
@@ -1908,6 +1954,14 @@ const htmlContent = `<!DOCTYPE html>
               <li><code>not = &lt; / true | false, / false | true &gt;;</code> &mdash; Polymorphic negation via branch projections and ordered choice</li>
               <li><code>{} | true not</code> &mdash; Compose constant relation <code>{} | true</code> with <code>not</code> (evaluates to <code>{} | false</code>)</li>
               <li><code>bool? = ?&lt; {} true, {} false &gt;;</code> &mdash; Define a boolean pattern filter relation</li>
+              <li>
+                <code>bit[] = &lt; {} 0, {} 1 &gt;;</code>
+                &mdash; Define a 0-arity bit pattern
+              </li>
+              <li>
+                <code>? list[bool[]]</code>
+                &mdash; Instantiated pattern filter matching booleans
+              </li>
               <li><code>not = bool? ?X &lt; / true | false, {} | true &gt; ?X;</code> &mdash; Filtered boolean negation: guarded by <code>bool?</code>, defaulting to <code>{} | true</code></li>
               <li><code>swap = { . y x, . x y };</code> &mdash; Define a product field-swapping relation</li>
               <li><code>{ {} | ok x, {} | nil y } swap</code> &mdash; Construct a product and pass it through <code>swap</code></li>

package/scripts/run-tests.mjs

@@ -32,12 +32,22 @@ 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"]],
   ["tests/test-hash-normalization.mjs", node, ["tests/test-hash-normalization.mjs"]],
   ["tests/test-structural-values.mjs", node, ["tests/test-structural-values.mjs"]],
   ["tests/test-codecs.mjs", node, ["tests/test-codecs.mjs"]],
+  [
+    "tests/test-djson-methods.mjs",
+    node,
+    ["tests/test-djson-methods.mjs"]
+  ],
   ["tests/test-deep-wire-value.mjs", node, ["tests/test-deep-wire-value.mjs"]],
   ["tests/test-k-object.mjs", node, ["tests/test-k-object.mjs"]],
   ["tests/test-kir.mjs", node, ["tests/test-kir.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/test-codecs.mjs

@@ -314,11 +314,11 @@ console.log("8. Verifying fast string decoding & bounded rendering...");
   );
 }
 
-// 9. DJSON Singleton Pattern Invariant & Round-Trip
-console.log("9. Verifying DJSON singleton pattern invariant...");
+// 9. DJSON Singleton Pattern Invariants & Round-Trip
+console.log("9. Verifying DJSON singleton pattern invariants...");
 {
   assert(Array.isArray(DjsonCodec.DJSON_PATTERN));
-  assert.equal(DjsonCodec.DJSON_PATTERN.length, 29);
+  assert.equal(DjsonCodec.DJSON_PATTERN.length, 27);
 
   const samples = [
     null,
@@ -332,21 +332,34 @@ console.log("9. Verifying DJSON singleton pattern invariant...");
     { key: "value", nested: [1, 2, { deep: true }] }
   ];
 
-  for (const sample of samples) {
-    const jsonStr = JSON.stringify(sample);
-    const enveloped = DjsonCodec.parse(jsonStr);
-    assert.strictEqual(
-      enveloped.pattern,
-      DjsonCodec.DJSON_PATTERN,
-      "Every DJSON value must share the exact singleton pattern"
-    );
-    const wire = SDK.encodeToWire(enveloped, enveloped.pattern);
-    const decoded = SDK.decodeWire(wire);
-    const restored = DjsonCodec.print(decoded.value);
+  for (const [label, codec, pat, relPath] of [
+    ["djson", DjsonCodec, DjsonCodec.DJSON_PATTERN, "codecs/djson.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(restored),
-      sample,
-      `DJSON round-trip mismatch for: ${jsonStr}`
+      JSON.parse(printRes.stdout.toString("utf8")),
+      JSON.parse(cliSample)
     );
   }
 }