@fraczak/k 7.1.0 → 8.0.0

package/CHANGELOG.md

@@ -5,6 +5,90 @@ All notable changes to this project will be documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.0.0] — 2026-10-20 — Named Patterns, Type Schemes & Trie Codecs
+
+### Language & Type System
+
+- **Named Patterns & Parameterized Schemes (`named-patterns.mjs`)**:
+  - Introduced first-class syntax for closed named patterns:
+    `byte[] = { bit 0, bit 1, ... };` and `bool[] = < bit false, ... >;`.
+  - Added parameterized type schemes with explicit type variables:
+    `list[X] = < X head, (list[X]) tail >;` and
+    `pair[A, B] = { A first, B second };`.
+  - Implemented monomorphic expansion with cycle detection and sharing.
+  - Full object file support: `.ko` and `.klib` payloads serialize and
+    deserialize named pattern tables alongside relations.
+
+- **Standard Library & Examples Refactoring**:
+  - Adopted named patterns throughout `core.k` (`bit[]`, `byte[]`,
+    `pair[A, B]`, `either[A, B]`, `option[X]`).
+  - Refactored `Examples/*.k` (`djson.k`, `arithmetics.k`, `bnat.k`,
+    `nat.k`, `code.k`, `karatsuba-mult.k`, `poly.k`, `vhdl_to_k.k`)
+    for clarity and conciseness using named patterns.
+
+### Dynamic JSON Codecs
+
+- **Bit-Trie Codec (`codecs/djson-btrie.mjs`, `k-djson-btrie`)**:
+  - Added binary bit-trie dynamic JSON codec with variable-length
+    bit prefixing for compact wire encodings.
+  - Accompanied by formal K specification in `Examples/djson-btrie.k`.
+
+- **Packed Nibble-Trie Codec (`codecs/djson-ptrie.mjs`)**:
+  - Added packed 4-bit nibble trie codec (`k-djson-ptrie`) for
+    optimized traversal.
+  - Accompanied by formal K specification in `Examples/djson-ptrie.k`.
+
+- **JSON Approaches Comparison & Benchmarks**:
+  - Added comparative architecture and benchmark documentation in
+    `DOCS/JSON_APPROACHES_COMPARISON.md`.
+  - Added benchmark suite in `scripts/perf-djson.mjs` and
+    `tests/bench-djson-tries.mjs`.
+
+### Interactive REPL & Tooling
+
+- **Pattern Inspection & Persistence in REPL**:
+  - Added `:patterns` / `:pat` commands to inspect loaded patterns.
+  - Display canonical type code / relation hashes:
+    `name[] = ...  -- @hash`.
+  - Added pattern lookup by `@hash` (`:pattern @hash`, `:pat @hash`).
+  - Tab-completion support for pattern names and canonical `@hashes`.
+  - Full pattern persistence across REPL sessions via `.klib` files.
+
+---
+
+## [7.2.0] — 2026-10-17 — Dynamic JSON Codec (djson) & Lazy Wire Decoding
+
+### Features & Performance Improvements
+
+- **Universal Dynamic JSON Codec (`codecs/djson.mjs`, `k-djson`)**:
+  - Added a standalone dynamic JSON codec (`djson.mjs` / `k-djson`)
+    based on a single 29-node recursive pattern `JSON = < number,
+    string, bool, null, list, object >`, where arrays are encoded as
+    arbitrary-length `cons`/`nil` lists and objects as `cons`/`nil`
+    lists of `{ key, val }` pairs.
+  - Kept the existing schema-specializing `json.mjs` (`k-json`) as an
+    alternative record-oriented JSON codec.
+  - Integrated `djson.mjs` into the CLI, REPL, and Web REPL (`repl.html`
+    VFS).
+
+- **Lazy Prefix-Free Wire Decoding & Fast Bitstream I/O**:
+  - Implemented lazy wire decoding (`LazyGeneralProduct` and
+    `LazyGeneralVariant`) with precomputed fixed-width bit sizes and
+    static field offsets on pattern graphs.
+  - Optimized bitstream reading/writing (`BitReader` / `BitWriter`) with
+    word-level operations, pre-encoded closed pattern bytes, and direct
+    bitstream-to-codepoint UTF-8 string decoding without intermediate
+    AST allocations.
+
+- **Stack-Safe & Bounded Value Rendering**:
+  - Converted `valueToK`, `valueWithEnvelopeToK`, and wire serialization
+    to iterative stack-safe algorithms with early character truncation
+    (`maxChars`).
+  - Added `:limit [num|none]` command and `--limit=<num>` CLI flag in
+    `repl.mjs` (default: `4096` chars) and bounded DOM tree previews in
+    `repl.html`.
+  - Handled broken pipe (`EPIPE`) cleanly across codec CLI entrypoints.
+
 ## [7.1.0] — 2026-10-16 — Polymorphic K IR (PKIR) & CLI Standardization
 
 ### Features & Architecture Improvements
@@ -407,6 +491,21 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+[8.0.0]: https://github.com/fraczak/k/releases/tag/v8.0.0
+[7.2.0]: https://github.com/fraczak/k/releases/tag/v7.2.0
+[7.1.0]: https://github.com/fraczak/k/releases/tag/v7.1.0
+[7.0.2]: https://github.com/fraczak/k/releases/tag/v7.0.2
+[7.0.1]: https://github.com/fraczak/k/releases/tag/v7.0.1
+[7.0.0]: https://github.com/fraczak/k/releases/tag/v7.0.0
+[6.10.6]: https://github.com/fraczak/k/releases/tag/v6.10.6
+[6.10.5]: https://github.com/fraczak/k/releases/tag/v6.10.5
+[6.10.4]: https://github.com/fraczak/k/releases/tag/v6.10.4
+[6.10.3]: https://github.com/fraczak/k/releases/tag/v6.10.3
+[6.10.2]: https://github.com/fraczak/k/releases/tag/v6.10.2
+[6.10.1]: https://github.com/fraczak/k/releases/tag/v6.10.1
+[6.10.0]: https://github.com/fraczak/k/releases/tag/v6.10.0
+[6.9.0]: https://github.com/fraczak/k/releases/tag/v6.9.0
+[6.5.0]: https://github.com/fraczak/k/releases/tag/v6.5.0
 [6.2.3]: https://github.com/fraczak/k/releases/tag/v6.2.3
 [6.1.0]: https://github.com/fraczak/k/releases/tag/v6.1.0
 [6.0.0]: https://github.com/fraczak/k/releases/tag/v6.0.0

package/DOCS/BIG_PICTURE.md

@@ -69,21 +69,24 @@ states, so any two structurally equivalent schemas yield identical canonical tex
 
 ### Filters
 
-A _filter_ is a syntactic expression `?schema` that acts as a partial identity
-relation on values conforming to `schema`. If the input value matches the
-schema, it passes through unchanged; otherwise, the relation is undefined.
+A _filter_ is a syntactic expression `?schema` that acts as a partial
+identity relation on values conforming to `schema`. If the input value
+matches the schema, it passes through unchanged; otherwise, the
+relation is undefined.
 
-In recursive relations, filters also serve as **inductive termination witnesses**,
-ensuring type and contract derivation converges.
+In recursive relations, filters also serve as **inductive termination
+witnesses**, ensuring type and contract derivation converges.
 
 In general, a filter schema is defined by:
 
 ```bnf
 filter ::= name | '{' filter_label_list '}'
    | '<' filter_label_list '>' | '(' filter_label_list ')'
+   | name '[' filter_args ']'
    | filter '=' name
 filter_label_list ::= /* empty */ | '...'
    | ( filter label ',' ) * filter label
+filter_args ::= /* empty */ | ( filter ',' ) * filter
 ```
 
 Examples:
@@ -92,10 +95,54 @@ Examples:
   X                 -- unconstrained schema variable
   ( ... )           -- unconstrained schema
   { ... }           -- any product schema
-  ( X x, X y )      -- any product schema with two fields of the same schema X
-  < X x, ... > = X  -- a recursive variant schema X with variant x of schema X
+  { X x, X y }      -- product with two fields of the same schema X
+  < X x, ... > = X  -- recursive variant X with variant x of schema X
+  list[int[]]       -- instantiated named pattern
 ```
 
+### Named Patterns and Parameterized Schemas
+
+k supports reusable, parameterized regular tree grammar templates via
+square-bracket syntax `name[...]`:
+
+```k
+name[ P1, P2, ... Pn ] = filter;
+```
+
+For 0-arity templates, empty brackets `[]` are used:
+
+```k
+bit[]  = < {} 0, {} 1 >;
+bits[] = < {} _, B 0, B 1 > = B;
+byte[] = {
+  bit[] 0, bit[] 1, bit[] 2, bit[] 3,
+  bit[] 4, bit[] 5, bit[] 6, bit[] 7
+};
+```
+
+Parameterized templates introduce external ports:
+
+```k
+list[X] = < {} nil, { X car, Y cdr } cons > = Y;
+pair[A, B] = { A first, B second };
+```
+
+Callers instantiate templates using `? name[...]`:
+
+```k
+list? = ? list[bits[]];
+```
+
+Or directly inside relation parameter guards:
+
+```k
+add = ?{ nat[] = N x, ... } < ... >;
+```
+
+Template expansion is purely structural and static: internal knots
+(`= Y`) are scoped locally and alpha-renamed, and template calls form an
+acyclic dependency DAG, preventing non-regular divergence.
+
 ### Partial functions
 
 A _partial function_ is a function that is not defined for every value

package/DOCS/CODECS.md

@@ -141,6 +141,50 @@ printf 'yes\n' | ./codecs/yesno.mjs --parse | ./codecs/yesno.mjs --print
 # Output: yes
 ```
 
+## Built-in Codecs
+
+The `codecs/` directory provides the following standard codecs:
+
+- **`int.mjs` (`k-int`)**: Decimal integers and bracketed integer lists
+  (e.g. `42`, `-15`, `[1, 2, 3]`) mapped to signed binary bit trees and
+  `cons`/`nil` lists.
+- **`ieee.mjs` (`k-ieee`)**: IEEE 754 64-bit floating-point numbers
+  (`sign`, `exponent`, `fraction`).
+- **`utf8.mjs` (`k-utf8`) & `utf16.mjs` (`k-utf16`)**: Unicode strings
+  encoded as `cons`/`nil` code-point lists (`str` in `core.k`).
+- **`unit.mjs` (`k-unit`)**: The unit value `{}`.
+- **`json.mjs` (`k-json`) — Schema-Specializing JSON**:
+  Derives a document-specific pattern for each JSON value:
+  - JSON objects map directly to products `{ field: val, ... }`.
+  - JSON arrays map to indexed products `{ "0": a0, "1": a1, ... }`.
+  - Ideal for record-oriented projection (e.g. `.user .name`).
+- **`djson.mjs` (`k-djson`) — Universal Dynamic JSON (Cons-List)**:
+  Maps every JSON document to a single universal recursive named pattern
+  `djson[]`:
+  ```k
+  djson[] = <
+    float64 number,
+    str string,
+    < {} true, {} false > bool,
+    {} null,
+    < {} nil, { J car, L cdr } cons > = L list,
+    < {} nil, { { str key, J val } car, O cdr } cons > = O object
+  > = J;
+  ```
+  Because every JSON value shares the exact same static 29-node pattern,
+  a `k` relation can be compiled once against `djson[]` and process
+  arbitrary JSON documents of any shape or array/object length.
+- **`djson-btrie.mjs` (`k-djson-btrie`) — Binary Bit-Trie Dynamic JSON**:
+  Replaces the linear `list` and `object` cons-lists with a unified
+  27-node binary bit-trie (`TRIE`). Array indices (`bits?`) and string
+  keys are stored along MSB-to-LSB bit paths, enabling $O(|K|)$ lookup
+  (`dot` and `nth` in `Examples/djson-btrie.k`) via direct `.0`/`.1`
+  projections with zero character-equality checks.
+- **`djson-ptrie.mjs` (`k-djson-ptrie`) — Patricia/Radix Dynamic JSON**:
+  Models `list` and `object` as path-compressed radix tries (`trie-array`
+  style) with `prefix` and $O(1)$ subtree `size` (`list_size` and
+  `obj_size` in `Examples/djson-ptrie.k`).
+
 ## Testing a Codec
 
 For CLI codecs, test both directions in a pipeline:
@@ -174,8 +218,9 @@ npm test
 ## Web REPL (VFS) Bundling
 
 When `repl.html` is generated (`npm run build:repl-html`):
-- Codecs (`int.mjs`, `json.mjs`, `utf8.mjs`, `unit.mjs`, `ieee.mjs`) are
-  bundled into 100% self-contained ES modules with zero imports.
+- Codecs (`int.mjs`, `json.mjs`, `djson.mjs`, `djson-btrie.mjs`,
+  `djson-ptrie.mjs`, `utf8.mjs`, `unit.mjs`, `ieee.mjs`) are bundled into
+  100% self-contained ES modules with zero imports.
 - `runCodecCLI` is shimmed as a no-op, and `Value` helpers are directly
   inlined.
 - In the browser, the VFS serves these self-contained modules directly to

package/DOCS/CODEC_ARCHITECTURE.md

@@ -192,11 +192,16 @@ runCodecCLI(import.meta.url, { parse, print, doc });
    pathToFileURL(process.argv[1]).href`). If imported as a module or
    running in a browser, it is a no-op.
 2. **Flag Parsing**: Handles `--parse`, `--print`, and `-h` / `--help`.
-3. **Stream Piping**:
+3. **Stream Piping & Lazy Wire Decoding**:
    - For `--parse`: reads `stdin` to string, calls `parse(text)`, encodes
      enveloped value `(P, v)` to binary wire format on `stdout`.
-   - For `--print`: decodes wire format from `stdin` into `(P, v)`, calls
-     `print(value)`, writes formatted text to `stdout`.
+   - For `--print`: lazily decodes the wire format from `stdin` into
+     bitstream-backed `Value` proxies (`LazyGeneralProduct`,
+     `LazyGeneralVariant`) with precomputed fixed-width bit sizes and
+     static field offsets, calls `print(value)`, and writes formatted text
+     to `stdout`.
+   - Cleanly exits on `EPIPE` when piped into downstream consumers like
+     `head`.
 
 ---
 
@@ -207,7 +212,10 @@ To make `codecs/` intuitive and self-contained:
 ```text
 codecs/
 ├── int.mjs                    # Integer & list codec
-├── json.mjs                   # JSON codec
+├── json.mjs                   # JSON codec (schema-specializing)
+├── djson.mjs                  # Dynamic JSON codec (cons-list)
+├── djson-btrie.mjs            # Dynamic JSON codec (binary bit-trie)
+├── djson-ptrie.mjs            # Dynamic JSON codec (Patricia/radix trie)
 ├── utf8.mjs                   # UTF-8 string codec
 ├── utf16.mjs                  # UTF-16 string codec
 ├── ieee.mjs                   # IEEE 754 float codec
@@ -236,7 +244,8 @@ In the browser REPL (`repl.html`):
   imports**.
 - **No Runtime Files in VFS**: `codecs/runtime/*` is not included in the
   browser VFS. The VFS only contains verified, self-contained user-facing
-  files (`int.mjs`, `json.mjs`, `utf8.mjs`, `unit.mjs`, `ieee.mjs`).
+  files (`int.mjs`, `json.mjs`, `djson.mjs`, `djson-btrie.mjs`,
+  `djson-ptrie.mjs`, `utf8.mjs`, `unit.mjs`, `ieee.mjs`).
 - **Native Browser Loading**: In `repl-codecs.mjs`, the browser reads the
   codec source from VFS, wraps it in a Blob, and invokes native `await
   import(blobUrl)`. No regex manipulation, import stripping, or global

package/DOCS/DICTIONARY.md

@@ -67,11 +67,20 @@ schema registry; its `@hash` is a fixed-width indexing digest.
 
 ### Filter
 
-A `filter` is an expression `?schema` that constrains the input payload to a
-schema and otherwise behaves like identity.
+A `filter` is an expression `?schema` that constrains the input payload
+to a schema and otherwise behaves like identity.
 
-In recursive relations, filters also serve as **inductive termination witnesses**,
-ensuring contract derivation converges.
+In recursive relations, filters also serve as **inductive termination
+witnesses**, ensuring contract derivation converges.
+
+### Named Pattern
+
+A `named pattern` is a parameterized regular tree grammar template
+defined using square-bracket syntax (`name[P1, ..., Pn] = filter;`).
+Named patterns declare external input ports in their parameter list
+and may contain internal unification variables and cycle knots
+(`= KnotName`). They are expanded statically without recursive
+divergence, compiling into canonical schema automata nodes.
 
 ### Canonical Content-Addressed Hash (`@hash`)
 

package/DOCS/FILE_FORMATS.md

@@ -97,8 +97,9 @@ flowchart TD
 ### What It Is
 `.k` files contain the high-level, human-readable source code of the
 `k` language. A `.k` file defines:
-- **Algebraic Data Types:** Products (`{ field1 label1, field2 label2 }`)
-  and tagged unions (`< tag1 arm1, tag2 arm2 >`).
+- **Algebraic Schemas & Named Patterns:** Products (`{ ... }`),
+  tagged unions (`< ... >`), and reusable parameterized pattern
+  templates (`name[...] = filter;`).
 - **Relations:** First-order partial functions composed via sequence,
   union, projection, or product construction.
 - **Top-level Expressions:** Computations evaluated when the file is run

package/DOCS/JSON_APPROACHES_COMPARISON.md

@@ -0,0 +1,306 @@
+# Comparison of JSON Approaches in k
+
+This document compares the four JSON codec and schema implementations in
+the **k** repository:
+
+1. **Schema-Specializing JSON** (`json`):
+   [`codecs/json.mjs`][json-mjs]
+2. **Dynamic Cons-List JSON** (`djson`):
+   [`codecs/djson.mjs`][djson-mjs] & [`Examples/djson.k`][djson-k]
+3. **Dynamic Binary Bit-Trie JSON** (`djson-btrie`):
+   [`codecs/djson-btrie.mjs`][djson-btrie-mjs] &
+   [`Examples/djson-btrie.k`][djson-btrie-k]
+4. **Dynamic Patricia/Radix Trie JSON** (`djson-ptrie`):
+   [`codecs/djson-ptrie.mjs`][djson-ptrie-mjs] &
+   [`Examples/djson-ptrie.k`][djson-ptrie-k]
+
+[json-mjs]: file:///home/wojtek/gits/K/k/codecs/json.mjs
+[djson-mjs]: file:///home/wojtek/gits/K/k/codecs/djson.mjs
+[djson-k]: file:///home/wojtek/gits/K/k/Examples/djson.k
+[djson-btrie-mjs]: file:///home/wojtek/gits/K/k/codecs/djson-btrie.mjs
+[djson-btrie-k]: file:///home/wojtek/gits/K/k/Examples/djson-btrie.k
+[djson-ptrie-mjs]: file:///home/wojtek/gits/K/k/codecs/djson-ptrie.mjs
+[djson-ptrie-k]: file:///home/wojtek/gits/K/k/Examples/djson-ptrie.k
+
+---
+
+## 1. Architectural Motivation
+
+In **k**, all values are algebraic data types classified by closed type
+patterns. External formats like JSON can be embedded into **k** via two
+fundamentally distinct strategies:
+
+### Static Schema Specialization (`json`)
+- Infers a concrete closed pattern specialized to the exact shape and
+  field names of each input JSON document.
+- Objects become concrete labeled products `{ "name": Str, "age": Num }`.
+- Lists become homogeneous or heterogeneous tuples/cons-lists.
+- **Advantage**: Zero interpretive overhead for known static schemas;
+  direct field projection in compiled code.
+- **Limitation**: The pattern is dynamic and grows unboundedly with the
+  document. Cannot write universal JSON transformation relations (like a
+  generic JSON query engine or REPL printer) under a single fixed closed
+  pattern.
+
+### Dynamic Uniform JSON (`djson*` family)
+- Defines a single, fixed closed pattern `json?` once for all valid JSON
+  values. Any arbitrary JSON document parses into an injection of this
+  universal pattern.
+- Allows authoring universal helper relations in `k`:
+  - `dot: {key, object} -> val`
+  - `has_key?: {key, object} -> ()`
+  - `nth: {index, list} -> val`
+  - `obj_size: object -> bits?`
+  - `list_size: list -> bits?`
+  - `remove: {key, object} -> object`
+  - `put: {key, val, object} -> object`
+- Compiles once to Wasm or LLVM `-O3` binaries that execute over any
+  input JSON document without recompilation.
+
+---
+
+## 2. Structural Schema Comparison
+
+| Dimension | `djson` (Cons) | `djson-btrie` | `djson-ptrie` |
+| :--- | :--- | :--- | :--- |
+| **Nodes** | 29 | 27 | 33 |
+| **Numbers** | float64 | float64 | float64 |
+| **Strings** | Cons-list | Cons-list | Cons-list |
+| **Lists** | Cons-list | Bit-trie | Patricia trie |
+| **Objects** | Sorted cons | Bit-trie | Radix trie |
+| **Node** | `{car, cdr}` | `{val, 0, 1}` | `{pfx, sz, val, d}` |
+| **Indexing**| $O(N)$ linear | $O(\log N)$ | $O(\log N)$ |
+| **Lookup** | $O(K \cdot L)$ | $O(L \cdot 8)$ | $O(L)$ radix |
+| **Size** | $O(N)$ walk | $O(N)$ walk | **$O(1)$** field |
+
+### Schema Definitions
+
+#### Dynamic Cons-List (`djson`)
+```k
+LIST = < {} nil, { JSON car, LIST cdr } cons >;
+ENTRY = { Str key, JSON val };
+OBJECT = < {} nil, { ENTRY car, OBJECT cdr } cons >;
+```
+
+#### Dynamic Binary Bit-Trie (`djson-btrie`)
+```k
+TRIE = <
+  {} nil,
+  { < {} nil, JSON val > val, TRIE 0, TRIE 1 } trie
+>;
+LIST = TRIE;
+OBJECT = TRIE;
+```
+
+#### Dynamic Patricia/Radix Trie (`djson-ptrie`)
+```k
+LIST = <
+  {} nil,
+  {
+    BITS prefix,
+    BITS size,
+    < {} nil, JSON val > val,
+    LIST 0,
+    LIST 1
+  } trie
+>;
+DICT = < {} nil, { { CHAR char, OBJECT trie } car, DICT cdr } cons >;
+OBJECT = <
+  {} nil,
+  { Str prefix, BITS size, < {} nil, JSON val > val, DICT dict } trie
+>;
+```
+
+---
+
+## 3. Algorithmic Mechanics
+
+### 3.1 Object Key Lookup (`dot`)
+- **`djson`**: Iterates through a linked list of `{key, val}` pairs.
+  On each entry, performs character-by-character string equality
+  `eq_string?`. For $N$ entries with key length $L$, worst-case time is
+  $O(N \cdot L)$.
+- **`djson-btrie`**: Uses `step_char` to walk 8 to 24 bits directly down
+  the binary trie per character. Because character bits are decoded
+  destructively into branch selectors without allocating `bits?` nodes,
+  it executes with **zero heap allocations** in compiled LLVM code.
+- **`djson-ptrie`**: Matches the query key against the node's `prefix`
+  run using `match_str_prefix`. If the prefix matches, it looks up the
+  next branching character in a small local `dict` cons-list.
+  Non-branching paths of arbitrary length are traversed in one step.
+
+### 3.2 Key Membership (`has_key?`)
+- **Hit**: All three navigate to the target key.
+- **Miss**:
+  - `djson` scans all $N$ entries to the end of the cons-list.
+  - `djson-btrie` and `djson-ptrie` terminate immediately as soon as a bit
+    or character branch is missing, achieving sub-microsecond rejection
+    even on large documents.
+
+### 3.3 Array Indexing (`nth`)
+- **`djson`**: Decodes a `bits?` natural number with `dec_nat` and walks
+  cons cells one by one ($O(I)$).
+- **`djson-btrie`**: Dispatches directly on the bits of the index from
+  most-significant to least-significant bit ($O(\log I)$).
+- **`djson-ptrie`**: Compares the remaining index bits against the
+  node's `prefix: BITS` in chunks, descending along compressed paths
+  ($O(\log I)$).
+
+### 3.4 Subtree Cardinality (`obj_size`, `list_size`)
+- **`djson` & `djson-btrie`**: Must recursively traverse the entire cons
+  list or bit-trie, adding 1 for each present entry using binary addition
+  (`inc_nat`). Complexity is $O(N \log N)$.
+- **`djson-ptrie`**: Stores a precomputed binary natural number
+  `size: BITS` at every node. Size queries are simple $O(1)$ field
+  projections (`ptrie_obj? < /nil 0, /trie .size >`). In LLVM `-O3`, this
+  executes in **5 nanoseconds**, independent of document size.
+
+### 3.5 Functional Updates (`remove`, `put`)
+- **`djson`**: Copies the cons spine until the modified entry ($O(N)$).
+- **`djson-btrie`**: Rebuilds the bit path down to the leaf. `put` uses
+  `str_to_bits` to construct the bit path, while `remove` clears `.val` to
+  `nil` along the path.
+- **`djson-ptrie`**:
+  - `remove` checks `has_key?`, decrements `size` with `dec_nat` along
+    the path, and clears `.val` to `nil`.
+  - `put` uses `split_str_prefix` to find the common prefix between the
+    new key and existing node. If prefixes diverge, it splits the node
+    into a shared parent with a 2-entry branch dictionary in $O(L)$ time.
+
+---
+
+## 4. Empirical Benchmark Results
+
+Measured with `npm run perf:djson` on Linux x86_64 across sizes
+$N \in \{10, 100, 500\}$.
+
+### 4.1 Wire Representation Sizes
+
+#### Shared-Prefix Objects (`{"field_prefix_0000": 0, ...}`)
+- **$N = 10$** (Raw: 230 B):
+  - `djson`: 1,029 B (4.47x)
+  - `djson-btrie`: **913 B (3.97x)**
+  - `djson-ptrie`: 1,032 B (4.49x)
+  - `json` (Spec): 370 B (1.61x)
+- **$N = 100$** (Raw: 2,750 B):
+  - `djson`: 3,365 B (1.22x)
+  - `djson-btrie`: **2,096 B (0.76x)**
+  - `djson-ptrie`: 2,367 B (0.86x)
+  - `json` (Spec): 1,529 B (0.56x)
+- **$N = 500$** (Raw: 14,750 B):
+  - `djson`: 14,357 B (0.97x)
+  - `djson-btrie`: **7,370 B (0.50x)**
+  - `djson-ptrie`: 8,241 B (0.56x)
+  - `json` (Spec): 7,229 B (0.49x)
+
+#### Varied-Key Objects (`{"account_0_account_attr": 0, ...}`)
+- **$N = 10$** (Raw: 270 B):
+  - `djson`: **1,114 B (4.13x)**
+  - `djson-btrie`: 1,460 B (5.41x)
+  - `djson-ptrie`: 1,236 B (4.58x)
+  - `json` (Spec): 496 B (1.84x)
+- **$N = 100$** (Raw: 3,120 B):
+  - `djson`: 4,987 B (1.60x)
+  - `djson-btrie`: 6,729 B (2.16x)
+  - `djson-ptrie`: **4,309 B (1.38x)**
+  - `json` (Spec): 4,460 B (1.43x)
+- **$N = 500$** (Raw: 16,598 B):
+  - `djson`: 22,581 B (1.36x)
+  - `djson-btrie`: 28,478 B (1.72x)
+  - `djson-ptrie`: **17,036 B (1.03x)**
+  - `json` (Spec): 22,104 B (1.33x)
+
+#### Homogeneous Number Arrays (`[0, 3, 6, ...]`)
+- **$N = 10$** (Raw: 27 B):
+  - `djson`: 880 B (32.6x)
+  - `djson-btrie`: **878 B (32.5x)**
+  - `djson-ptrie`: 999 B (37.0x)
+- **$N = 100$** (Raw: 363 B):
+  - `djson`: **1,645 B (4.53x)**
+  - `djson-btrie`: 1,666 B (4.59x)
+  - `djson-ptrie`: 1,877 B (5.17x)
+- **$N = 500$** (Raw: 2,129 B):
+  - `djson`: **5,045 B (2.37x)**
+  - `djson-btrie`: 5,166 B (2.43x)
+  - `djson-ptrie`: 5,776 B (2.71x)
+
+---
+
+### 4.2 Execution Latency Across Backends ($N=500$)
+
+#### Object Lookup (`dot` on last key of 500-key object)
+- **Shared-Prefix Keys**:
+  - `djson`: Wasm $580.4\ \mu\text{s}$, LLVM $23.6\ \mu\text{s}$
+  - `djson-btrie`: Wasm $7.4\ \mu\text{s}$, LLVM **$2.4\ \mu\text{s}$**
+  - `djson-ptrie`: Wasm $11.1\ \mu\text{s}$, LLVM $5.1\ \mu\text{s}$
+- **Varied Keys**:
+  - `djson`: Wasm $26.8\ \mu\text{s}$, LLVM $4.2\ \mu\text{s}$
+  - `djson-btrie`: Wasm $10.9\ \mu\text{s}$, LLVM **$3.1\ \mu\text{s}$**
+  - `djson-ptrie`: Wasm $10.8\ \mu\text{s}$, LLVM $4.4\ \mu\text{s}$
+
+#### Key Membership Filter (`has_key?` miss on nonexistent key)
+- `djson`: Wasm $63.9\ \mu\text{s}$, LLVM $1,168\ \text{ns}$
+- `djson-btrie`: Wasm $1,022\ \text{ns}$, LLVM **$466\ \text{ns}$**
+- `djson-ptrie`: Wasm $1,908\ \text{ns}$, LLVM $1,228\ \text{ns}$
+
+#### Array Element Lookup (`nth` on index 499 of 500 elements)
+- `djson`:
+  kVM $10.74\ \text{ms}$, Wasm $97.2\ \mu\text{s}$,
+  LLVM $100.7\ \mu\text{s}$
+- `djson-btrie`:
+  kVM $26.0\ \mu\text{s}$, Wasm $733\ \text{ns}$,
+  LLVM **$114\ \text{ns}$** (**881x speedup**)
+- `djson-ptrie`:
+  kVM $35.7\ \mu\text{s}$, Wasm $1,267\ \text{ns}$,
+  LLVM $371\ \text{ns}$ (**271x speedup**)
+
+#### Cardinality Queries (`obj_size` for $N=500$)
+- `djson`:
+  kVM $13.57\ \text{ms}$, Wasm $89.2\ \mu\text{s}$,
+  LLVM $127.4\ \mu\text{s}$
+- `djson-btrie`:
+  kVM $210.88\ \text{ms}$, Wasm $3.02\ \text{ms}$,
+  LLVM $8.06\ \text{ms}$
+- `djson-ptrie`:
+  kVM $2,054\ \text{ns}$, Wasm $172\ \text{ns}$,
+  LLVM **$5\ \text{ns}$** (**26,106x speedup**)
+
+#### Object Key Updates ($N=500$)
+- **`remove`**:
+  - `djson`: LLVM $79.6\ \mu\text{s}$
+  - `djson-btrie`: LLVM **$9.5\ \mu\text{s}$** (8.4x speedup)
+  - `djson-ptrie`: LLVM $13.3\ \mu\text{s}$ (6.0x speedup)
+- **`put`**:
+  - `djson`: LLVM $50.8\ \mu\text{s}$
+  - `djson-btrie`: LLVM $12.6\ \mu\text{s}$ (4.0x speedup)
+  - `djson-ptrie`: LLVM **$3.9\ \mu\text{s}$** (13.1x speedup)
+
+---
+
+## 5. Trade-off Analysis & Recommendation Matrix
+
+| Feature | `json` | `djson` | `btrie` | `ptrie` |
+| :--- | :---: | :---: | :---: | :---: |
+| **Universal Pattern** | ❌ No | ✅ 29 | ✅ 27 | ✅ 33 |
+| **REPL Inspection** | Native | Cons | Bit-tree | Radix |
+| **Shared Prefix Wire**| Small | Med | **Small** | Small |
+| **Varied Keys Wire** | Large | Med | Large | **Small** |
+| **Array ($N=500$)** | Direct | $100\ \mu\text{s}$ | **114ns**| 371ns |
+| **Dot ($N=500$)** | Direct | $23.6\ \mu\text{s}$| **2.4µs**| 5.1µs |
+| **Put ($N=500$)** | N/A | $50.8\ \mu\text{s}$| 12.6µs | **3.9µs**|
+| **Size ($N=500$)** | N/A | $127\ \mu\text{s}$ | 8.1ms | **5ns** |
+
+### Recommendations
+1. **Choose `djson-ptrie` for general-purpose dynamic JSON**:
+   It achieves the best wire compression on real-world varied keys
+   (1.03x of raw JSON), provides instant $O(1)$ cardinality queries
+   (5 ns in LLVM), and delivers the fastest updates (`put` in 3.9 µs).
+2. **Choose `djson-btrie` for extreme lookup throughput on shared keys**:
+   Destructive bit-walking in `dot` avoids all node allocation,
+   achieving the lowest lookup latency (2.4 µs in LLVM).
+3. **Keep `djson` for simple, lightweight tooling**:
+   Simple cons-list structure is human-readable in REPL raw outputs and
+   has minimal code complexity for small payloads ($N < 50$).
+4. **Choose `json` when document schema is fixed at compile time**:
+   Avoids all dynamic dictionary lookups in exchange for a
+   document-specialized pattern.