diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fa31d998..a745f407 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -191,6 +191,92 @@ jobs:
         run: |
           docker run --rm --volume $(pwd):/note-c/ --workdir /note-c/ --entrypoint ./scripts/run_unit_tests.sh ghcr.io/blues/note_c_ci:latest --mem-check --low-mem --single-precision
 
+  run_layout_matrix_unit_tests:
+    # The historical J layout is the default; NOTE_C_STORAGE_OPTIMIZATION packs
+    # keys and short string values into the node's own allocation. Both layouts
+    # are shipped, so both must stay green.
+    #
+    # Precision is crossed in because it is not independent of layout: JNUMBER
+    # is a float under NOTE_C_SINGLE_PRECISION, which changes the size and tail
+    # padding of the inline region the packed layout carves its storage out of.
+    # A defect confined to one cell of this matrix is otherwise easy to miss.
+    #
+    # Low memory is crossed in as an independent axis too, because it changes
+    # which code compiles at all.
+    #
+    # Between this matrix and the two standalone jobs, all eight cells of
+    # {layout} x {precision} x {low-mem} are built and run: default/double is
+    # run_unit_tests, default/low-mem/single is run_low_mem_unit_tests, and the
+    # remaining six are below.
+    runs-on: ubuntu-latest
+    if: ${{ always() }}
+    needs: [build_ci_docker_image]
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: default layout, single precision
+            flags: --single-precision
+          - name: storage optimization, default precision
+            flags: --storage-optimization
+          - name: storage optimization, single precision
+            flags: --storage-optimization --single-precision
+          - name: storage optimization, low memory, single precision
+            flags: --storage-optimization --low-mem --single-precision
+          - name: default layout, low memory, double precision
+            flags: --low-mem
+          - name: storage optimization, low memory, double precision
+            flags: --storage-optimization --low-mem
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Load CI Docker image
+        # Only load the Docker image artifact if build_ci_docker_image actually
+        # ran (e.g. it wasn't skipped and was successful).
+        if: ${{ needs.build_ci_docker_image.result == 'success' }}
+        uses: ./.github/actions/load-ci-image
+
+      - name: Run tests (${{ matrix.name }})
+        run: |
+          docker run --rm --volume $(pwd):/note-c/ --workdir /note-c/ --entrypoint ./scripts/run_unit_tests.sh ghcr.io/blues/note_c_ci:latest --mem-check ${{ matrix.flags }}
+
+  run_j_layout_ab_comparison:
+    # Proves the two layouts render byte-identically, and publishes the memory
+    # difference in the job log.
+    #
+    # Run at both precisions. JNUMBER is a float under NOTE_C_SINGLE_PRECISION,
+    # which removes the historical layout's tail padding on its own: sizeof(J)
+    # is 40 in BOTH layouts there, so the saving is materially smaller and comes
+    # entirely from inline packing. Publishing only the double-precision table
+    # would overstate the win for single-precision targets.
+    runs-on: ubuntu-latest
+    if: ${{ always() }}
+    needs: [build_ci_docker_image]
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: double precision
+            flags: ""
+          - name: single precision
+            flags: --single-precision
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Load CI Docker image
+        if: ${{ needs.build_ci_docker_image.result == 'success' }}
+        uses: ./.github/actions/load-ci-image
+
+      - name: Compare default and storage-optimized J layouts (${{ matrix.name }})
+        run: |
+          docker run --rm --volume $(pwd):/note-c/ --workdir /note-c/ --entrypoint ./scripts/run_ab_layout_comparison.sh ghcr.io/blues/note_c_ci:latest ${{ matrix.flags }}
+
   run_astyle:
     runs-on: ubuntu-latest
     if: ${{ always() }}
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 9be6e6f4..0b95bc1e 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -35,7 +35,7 @@ Use this file to understand what the architecture is meant to be. Use `source-re
 - `n_serial.c`: serial transport implementation and chunked newline-framed serial transmit/receive behavior.
 - `n_i2c.c`: I2C transport implementation and chunked newline-framed I2C transmit/receive behavior.
 - `n_hooks.c`: global function-pointer hook registry, active-interface dispatch, and invocation of platform hooks for memory, time, mutexes, debug output, and transports.
-- `n_cjson.c`, `n_cjson.h`, `n_cjson_helpers.c`: bundled JSON representation and helper APIs.
+- `n_cjson.c`, `n_cjson.h`, `n_cjson_helpers.c`: bundled JSON representation and helper APIs. The `J` node has two compile-time storage layouts; see "JSON node storage" below.
 - `n_helpers.c`, `n_str.c`, `n_printf.c`, `n_atof.c`, `n_ftoa.c`, `n_b64.c`, `n_cobs.c`, `n_md5.c`, `n_const.c`, `n_ua.c`: portability helpers, encoding, formatting, constants, and utility behavior.
 - `test/`: unit tests and mocks for protecting SDK behavior without requiring real hardware.
 - `scripts/`: local automation for checks, documentation, and release support.
@@ -68,6 +68,17 @@ Applications normally build requests as `J` objects, send them through `NoteRequ
 
 Transport and platform behavior is supplied through hooks so the same core code can run on microcontrollers, embedded Linux, tests, and other C/C++ environments. Serial and I2C transports move raw newline-framed bytes through hook dispatch. Binary payload helpers, not the transport implementations, own COBS framing and MD5 verification.
 
+## JSON Node Storage
+
+`J` has two storage layouts, selected at compile time. Both produce byte-identical JSON and expose the same API; they differ only in how a node's key and string value are allocated.
+
+- **Historical layout (default).** A node is 48 bytes on a 32-bit target. A member's key and its string value each occupy their own heap allocation, so `"key":"value"` costs three allocations.
+- **`NOTE_C_STORAGE_OPTIMIZATION`.** A node is 40 bytes, and a member's key and short string value are carved out of the node's own allocation, so the same member costs one allocation. The bytes occupied by `valueint` and `valuenumber` — which a `JString`/`JRaw` node never uses — hold that content, and a `objlen` member records the node's allocation size. Over a representative corpus this removes roughly 38% of allocations and 26% of the heap a parsed document holds.
+
+Ownership is expressed by four `type` flags: `JIsReference` and `JStringIsConst` (pre-existing, unchanged meanings), plus `JValueInline` and `JKeyInline`, which are only set under the optimization and record that a pointer addresses the node's own allocation. Every mutation of `valuestring` and `string` routes through storage helpers in `n_cjson.c`, so the layout-conditional code stays confined to those helpers; the parser, printer, and public API are layout-agnostic.
+
+The optimization is **off by default**, deferred pending a planned external beta of the historical layout, and because it changes the public representation of `J`: `sizeof(J)` changes, member offsets move, `type` narrows from `int` to `uint16_t`, `objlen` is added, and on a string node `valueint`/`valuenumber` may hold character data. note-c is always compiled from source as part of the customer solution, so the requirement is that every translation unit seeing `J` uses the same setting — the note-c sources and the customer sources alike. The CMake option propagates `PUBLIC` to enforce that, exactly as `NOTE_C_SINGLE_PRECISION` does. See `docs/architecture/decisions/0002-j-node-storage-layout.md`.
+
 ## Public Contracts
 
 The main compatibility contracts are:
@@ -77,7 +88,8 @@ The main compatibility contracts are:
 - Request/response ownership semantics for public transaction APIs.
 - Hook signatures for serial, I2C, memory, mutex, time, and debug output.
 - Notecard request/response semantics and timeout/retry behavior.
-- Build configuration behavior for low-memory, single-precision, user-agent, CRC, and portability-helper variants.
+- Build configuration behavior for low-memory, single-precision, storage-optimization, user-agent, CRC, and portability-helper variants.
+- The in-memory representation of `J` itself, which downstream code reads directly. `NOTE_C_STORAGE_OPTIMIZATION` changes that representation and is therefore opt-in; see "JSON node storage".
 - Version constants and release expectations documented in `README.md`.
 
 Breaking changes to these contracts require deliberate versioning, migration notes, and architecture documentation updates.
@@ -88,6 +100,8 @@ Breaking changes to these contracts require deliberate versioning, migration not
 
 Build configuration is part of the portability model. CMake detects platform `strlcpy`/`strlcat` support and only includes bundled `n_str.c` helpers when needed. Low-memory builds disable user-agent support and request CRC paths, omit `n_ua.c`, use compact error/log constants, and reduce allocation chunk size.
 
+Two CMake options change the public representation rather than only behavior, and are propagated `PUBLIC` so every translation unit that sees `J` agrees: `NOTE_C_SINGLE_PRECISION` (which changes the width of `JNUMBER`) and `NOTE_C_STORAGE_OPTIMIZATION` (which changes the layout of `J`). note-c is always compiled from source as part of the consuming solution, so this is a single-build consistency requirement.
+
 ## Runtime Model
 
 At runtime, host code initializes the relevant hooks, constructs Notecard requests, and calls `note-c` APIs. `note-c` serializes requests, sends bytes through the selected hook-backed transport, parses responses, and returns JSON objects or status to the caller.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2803711f..5877464c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -24,6 +24,13 @@ option(NOTE_NODEBUG "Build the library without debug information." OFF)
 option(NOTE_C_NO_LIBC "Audit libc dependencies by linking the note_c test/audit library without libc, generating errors for any undefined symbols." OFF)
 option(NOTE_C_SHOW_MALLOC "Build the library with flags required to log memory usage." OFF)
 option(NOTE_C_SINGLE_PRECISION "Use single precision for JSON floating point numbers." OFF)
+# Opt in to the packed J layout, which carves a member's key and short string
+# value out of the node's own allocation instead of giving each its own heap
+# block. The historical layout is the default. Like NOTE_C_SINGLE_PRECISION this
+# changes sizeof(J), so it is propagated PUBLIC and must match between the
+# library and every consumer. See docs/architecture/decisions/
+# 0002-j-node-storage-layout.md.
+option(NOTE_C_STORAGE_OPTIMIZATION "Pack J keys and short string values into the node's own allocation (smaller, fewer allocations; changes the public J representation)." OFF)
 option(NOTE_C_HEARTBEAT_CALLBACK "Enable heartbeat callback support." OFF)
 
 # NOTE_C_NO_LIBC is a link-time undefined-symbol audit (see
@@ -103,6 +110,9 @@ function(note_c_configure_common target)
     if(NOTE_C_SINGLE_PRECISION)
         target_compile_definitions(${target} PUBLIC NOTE_C_SINGLE_PRECISION)
     endif()
+    if(NOTE_C_STORAGE_OPTIMIZATION)
+        target_compile_definitions(${target} PUBLIC NOTE_C_STORAGE_OPTIMIZATION)
+    endif()
     if(NOTE_C_HEARTBEAT_CALLBACK)
         target_compile_definitions(${target} PUBLIC NOTE_C_HEARTBEAT_CALLBACK)
     endif()
diff --git a/docs/architecture/architecture.html b/docs/architecture/architecture.html
index 8c7e1dcd..f55305ef 100644
--- a/docs/architecture/architecture.html
+++ b/docs/architecture/architecture.html
@@ -928,7 +928,7 @@ <h2>Nodes</h2>
     </aside>
   </main>
 
-  <script type="application/json" id="source-research-projection">{"schemaVersion":"2.0","name":"note-c source-research architecture projection","repository":"blues/note-c","purpose":"Portable C SDK for communicating with a Blues Notecard over serial or I2C.","lastReviewed":"2026-06-30","viewArtifacts":{"humanMap":"docs/architecture/architecture.html","narrative":"ARCHITECTURE.md","sourceResearchIndex":"source-research/research-index.md","sourceResearchGraph":"source-research/inventory/dependency-graph.json","sourceResearchClaims":"source-research/inventory/claims-ledger.json"},"principles":["Keep the core SDK platform-neutral.","Put platform-specific behavior behind hooks or adapter libraries.","Treat note.h and hook signatures as compatibility contracts.","Use source-research/inventory/*.json for structured source-backed dependency and claim evidence.","Keep the Markdown architecture docs, traversal view, and source-research artifacts consistent when architecture-relevant code changes land."],"legend":[{"label":"Consumers","description":"Apps, adapters","kinds":["consumer"]},{"label":"Public contract","description":"Compatibility surface","kinds":["contract"]},{"label":"Portable core","description":"Request, JSON, helpers","kinds":["core"]},{"label":"Transports","description":"Serial and I2C","kinds":["transport"]},{"label":"Hooks","description":"Platform boundary","kinds":["hook"]},{"label":"External","description":"Bus, Notecard, Notehub","kinds":["external"]},{"label":"Tests","description":"Unit test coverage","kinds":["test"]}],"layers":[{"id":"consumers","name":"Consumers and adapters","role":"Applications, platform SDKs, and tests that call note-c."},{"id":"api","name":"Public contract","role":"The API and hook surface downstream code depends on."},{"id":"core","name":"Portable core","role":"Request lifecycle, JSON, helpers, binary codecs, and utility behavior."},{"id":"transport","name":"Transport and hooks","role":"Transport selection, chunking, and platform callback boundaries."},{"id":"external","name":"Hardware and cloud boundary","role":"Physical bus, Notecard, and Notehub reached by the Notecard."}],"nodes":[{"id":"apps","layer":"consumers","name":"Applications","kind":"consumer","paths":[],"summary":"User firmware or host apps that build requests and consume responses.","contracts":["Calls public APIs in note.h"]},{"id":"adapters","layer":"consumers","name":"Adapter SDKs","kind":"consumer","paths":[],"summary":"Platform integrations such as note-arduino, note-zephyr, note-espidf, and POSIX integrations.","contracts":["Own platform setup and hook implementations"]},{"id":"tests","layer":"consumers","name":"Unit Tests","kind":"test","paths":["test/"],"summary":"Mock-backed tests for JSON, request flow, hooks, transports, helpers, and edge cases.","contracts":["Protects behavior without hardware"]},{"id":"api","layer":"api","name":"note.h Public API","kind":"contract","paths":["note.h"],"summary":"Public functions, typedefs, constants, version metadata, request helpers, and hook signatures.","contracts":["Compatibility boundary","Breaking changes require versioning and migration notes"]},{"id":"request","layer":"core","name":"Request Core","kind":"core","paths":["n_request.c","n_lib.h"],"summary":"Creates, serializes, sends, retries, parses, and releases Notecard transactions while preserving public request ownership boundaries.","contracts":["Consuming wrappers delete request objects","NoteTransaction leaves request ownership with caller","NoteRequestResponseJSON uses caller-owned raw strings","Coordinates active interface"]},{"id":"json","layer":"core","name":"JSON Model","kind":"core","paths":["n_cjson.c","n_cjson.h","n_cjson_helpers.c"],"summary":"Bundled JSON object model and helper APIs used by callers and internals.","contracts":["J object semantics","Allocation ownership"]},{"id":"helpers","layer":"core","name":"High-level Helpers","kind":"core","paths":["n_helpers.c"],"summary":"Convenience APIs for common Notecard operations plus binary payload helpers that own COBS framing, raw chunk transfer, and MD5 verification.","contracts":["Builds JSON requests on top of public request APIs","Binary helpers own COBS and MD5 behavior","High-level helpers rely on request ownership contracts"]},{"id":"utilities","layer":"core","name":"Portable Utilities","kind":"core","paths":["n_str.c","n_printf.c","n_atof.c","n_ftoa.c","n_b64.c","n_cobs.c","n_md5.c","n_const.c","n_ua.c"],"summary":"String, number, formatting, encoding, hashing, constants, user-agent, and build-variant portability support.","contracts":["No platform runtime assumptions","strlcpy/strlcat helpers are conditionally included","Low-memory builds can omit user-agent and CRC paths"]},{"id":"hooks","layer":"transport","name":"Platform Hooks","kind":"hook","paths":["n_hooks.c"],"summary":"Global function-pointer registry for memory, time, mutex, debug, transaction, serial, I2C, JSON transaction callbacks, and active-interface dispatch.","contracts":["Platform boundary","Hook signatures are public contracts","Hook pointers are caller-owned global state","Mutex protection is optional and not universal"]},{"id":"serial","layer":"transport","name":"Serial Transport","kind":"transport","paths":["n_serial.c"],"summary":"Serial transaction, reset, receive, transmit, CRLF normalization, and chunked newline-framed byte movement.","contracts":["Uses serial hooks","Protects byte-level request/response flow","Does not own COBS or MD5 framing"]},{"id":"i2c","layer":"transport","name":"I2C Transport","kind":"transport","paths":["n_i2c.c"],"summary":"I2C transaction, reset, query length, receive, transmit, MTU, and chunked newline-framed byte movement.","contracts":["Uses I2C hooks","Owns I2C timing and chunking behavior","Does not own COBS or MD5 framing"]},{"id":"bus","layer":"external","name":"Platform Bus","kind":"external","paths":[],"summary":"UART, USB serial, I2C, or test doubles supplied by the host platform.","contracts":["Implemented outside note-c"]},{"id":"notecard","layer":"external","name":"Notecard","kind":"external","paths":[],"summary":"Device that accepts JSON requests and returns JSON responses.","contracts":["Serial or I2C protocol boundary"]},{"id":"notehub","layer":"external","name":"Notehub","kind":"external","paths":[],"summary":"Cloud service reached by the Notecard; note-c does not communicate with Notehub directly.","contracts":["Indirect dependency only"]}],"edges":[{"from":"apps","to":"api","label":"calls"},{"from":"adapters","to":"api","label":"wraps"},{"from":"tests","to":"api","label":"exercises"},{"from":"api","to":"request","label":"request APIs"},{"from":"api","to":"json","label":"J helpers"},{"from":"api","to":"hooks","label":"hook registration"},{"from":"helpers","to":"request","label":"builds requests"},{"from":"request","to":"json","label":"serialize/parse"},{"from":"request","to":"hooks","label":"active interface"},{"from":"request","to":"serial","label":"serial path"},{"from":"request","to":"i2c","label":"I2C path"},{"from":"serial","to":"hooks","label":"serial callbacks"},{"from":"i2c","to":"hooks","label":"I2C callbacks"},{"from":"hooks","to":"bus","label":"platform calls"},{"from":"bus","to":"notecard","label":"bytes"},{"from":"notecard","to":"notehub","label":"syncs"},{"from":"tests","to":"hooks","label":"mocks"},{"from":"tests","to":"serial","label":"transport tests"},{"from":"tests","to":"i2c","label":"transport tests"},{"from":"utilities","to":"request","label":"support"},{"from":"utilities","to":"json","label":"support"}],"hotspots":[{"id":"public-api","title":"Public API and hook compatibility","nodes":["api","hooks"],"description":"The stable SDK surface that applications and adapter libraries compile against, including public request helpers and platform hook signatures.","updateRule":"Update docs and consider versioning whenever note.h contracts change."},{"id":"transaction-flow","title":"Request lifecycle","nodes":["request","json","serial","i2c"],"description":"The path a Notecard transaction follows as requests are built, serialized, sent over an active transport, parsed, returned to callers, and released according to public ownership contracts.","updateRule":"Update docs when timeout, retry, serialization, parsing, memory ownership, raw JSON string, or active-interface behavior changes."},{"id":"transport-boundary","title":"Transport and platform boundary","nodes":["serial","i2c","hooks","bus"],"description":"The byte-level boundary between portable note-c transport code and host-provided UART, USB serial, I2C, or test-double implementations; binary COBS/MD5 behavior belongs to helper code above this boundary.","updateRule":"Update docs when byte framing, chunking, MTU, reset, hook invocation, COBS ownership, or MD5 verification semantics change."},{"id":"adapter-impact","title":"Adapter impact","nodes":["adapters","api","hooks"],"description":"The parts of note-c most likely to require coordinated changes in downstream platform SDKs and integration layers.","updateRule":"Update docs when note-arduino, note-zephyr, note-espidf, POSIX, or other adapters need coordinated changes."}],"updateTriggers":["Changes to note.h public APIs, typedefs, constants, or hook signatures.","Changes to request lifecycle, timeout, retry, memory ownership, or response handling.","Changes to serial/I2C framing, chunking, transmit, receive, reset, or MTU behavior.","Changes to JSON representation or helper semantics.","Changes to adapter expectations, build/test strategy, release strategy, or versioning.","Changes to request ownership, raw JSON string transaction behavior, or response lifetime semantics.","Changes to low-memory, single-precision, user-agent, CRC, or portability-helper build variants."],"filesToUpdateTogether":["ARCHITECTURE.md","docs/architecture/architecture.html","source-research/ when source-derived behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims change","docs/architecture/decisions/*.md when a durable design decision changes"],"projectionSource":"source-research/","projectionNote":"Component-level traversal projection for architecture review. Canonical structured source evidence lives in source-research/inventory/*.json.","sourceResearch":{"researchState":"complete","recommendedState":"complete","sourceNodes":585,"dependencyEdges":1342,"finalizedClaims":29,"claimsTotal":29,"validation":"Run source-first-repo-research validate_research.py source-research before relying on updated artifacts."}}</script>
+  <script type="application/json" id="source-research-projection">{"schemaVersion":"2.0","name":"note-c source-research architecture projection","repository":"blues/note-c","purpose":"Portable C SDK for communicating with a Blues Notecard over serial or I2C.","lastReviewed":"2026-08-04","viewArtifacts":{"humanMap":"docs/architecture/architecture.html","narrative":"ARCHITECTURE.md","sourceResearchIndex":"source-research/research-index.md","sourceResearchGraph":"source-research/inventory/dependency-graph.json","sourceResearchClaims":"source-research/inventory/claims-ledger.json"},"principles":["Keep the core SDK platform-neutral.","Put platform-specific behavior behind hooks or adapter libraries.","Treat note.h and hook signatures as compatibility contracts.","Use source-research/inventory/*.json for structured source-backed dependency and claim evidence.","Keep the Markdown architecture docs, traversal view, and source-research artifacts consistent when architecture-relevant code changes land."],"legend":[{"label":"Consumers","description":"Apps, adapters","kinds":["consumer"]},{"label":"Public contract","description":"Compatibility surface","kinds":["contract"]},{"label":"Portable core","description":"Request, JSON, helpers","kinds":["core"]},{"label":"Transports","description":"Serial and I2C","kinds":["transport"]},{"label":"Hooks","description":"Platform boundary","kinds":["hook"]},{"label":"External","description":"Bus, Notecard, Notehub","kinds":["external"]},{"label":"Tests","description":"Unit test coverage","kinds":["test"]}],"layers":[{"id":"consumers","name":"Consumers and adapters","role":"Applications, platform SDKs, and tests that call note-c."},{"id":"api","name":"Public contract","role":"The API and hook surface downstream code depends on."},{"id":"core","name":"Portable core","role":"Request lifecycle, JSON, helpers, binary codecs, and utility behavior."},{"id":"transport","name":"Transport and hooks","role":"Transport selection, chunking, and platform callback boundaries."},{"id":"external","name":"Hardware and cloud boundary","role":"Physical bus, Notecard, and Notehub reached by the Notecard."}],"nodes":[{"id":"apps","layer":"consumers","name":"Applications","kind":"consumer","paths":[],"summary":"User firmware or host apps that build requests and consume responses.","contracts":["Calls public APIs in note.h"]},{"id":"adapters","layer":"consumers","name":"Adapter SDKs","kind":"consumer","paths":[],"summary":"Platform integrations such as note-arduino, note-zephyr, note-espidf, and POSIX integrations.","contracts":["Own platform setup and hook implementations"]},{"id":"tests","layer":"consumers","name":"Unit Tests","kind":"test","paths":["test/"],"summary":"Mock-backed tests for JSON, request flow, hooks, transports, helpers, and edge cases.","contracts":["Protects behavior without hardware"]},{"id":"api","layer":"api","name":"note.h Public API","kind":"contract","paths":["note.h"],"summary":"Public functions, typedefs, constants, version metadata, request helpers, and hook signatures.","contracts":["Compatibility boundary","Breaking changes require versioning and migration notes","NOTE_C_SINGLE_PRECISION and NOTE_C_STORAGE_OPTIMIZATION change the public representation and are propagated PUBLIC so all translation units agree"]},{"id":"request","layer":"core","name":"Request Core","kind":"core","paths":["n_request.c","n_lib.h"],"summary":"Creates, serializes, sends, retries, parses, and releases Notecard transactions while preserving public request ownership boundaries.","contracts":["Consuming wrappers delete request objects","NoteTransaction leaves request ownership with caller","NoteRequestResponseJSON uses caller-owned raw strings","Coordinates active interface"]},{"id":"json","layer":"core","name":"JSON Model","kind":"core","paths":["n_cjson.c","n_cjson.h","n_cjson_helpers.c"],"summary":"Bundled JSON object model and helper APIs used by callers and internals. The J node has two compile-time storage layouts: the historical one (default) and a memory-optimized packed layout selected by NOTE_C_STORAGE_OPTIMIZATION.","contracts":["J object semantics","Allocation ownership","The in-memory representation of J is itself a compatibility contract; downstream code reads its members directly","Both layouts must render byte-identical JSON"]},{"id":"helpers","layer":"core","name":"High-level Helpers","kind":"core","paths":["n_helpers.c"],"summary":"Convenience APIs for common Notecard operations plus binary payload helpers that own COBS framing, raw chunk transfer, and MD5 verification.","contracts":["Builds JSON requests on top of public request APIs","Binary helpers own COBS and MD5 behavior","High-level helpers rely on request ownership contracts"]},{"id":"utilities","layer":"core","name":"Portable Utilities","kind":"core","paths":["n_str.c","n_printf.c","n_atof.c","n_ftoa.c","n_b64.c","n_cobs.c","n_md5.c","n_const.c","n_ua.c"],"summary":"String, number, formatting, encoding, hashing, constants, user-agent, and build-variant portability support.","contracts":["No platform runtime assumptions","strlcpy/strlcat helpers are conditionally included","Low-memory builds can omit user-agent and CRC paths"]},{"id":"hooks","layer":"transport","name":"Platform Hooks","kind":"hook","paths":["n_hooks.c"],"summary":"Global function-pointer registry for memory, time, mutex, debug, transaction, serial, I2C, JSON transaction callbacks, and active-interface dispatch.","contracts":["Platform boundary","Hook signatures are public contracts","Hook pointers are caller-owned global state","Mutex protection is optional and not universal"]},{"id":"serial","layer":"transport","name":"Serial Transport","kind":"transport","paths":["n_serial.c"],"summary":"Serial transaction, reset, receive, transmit, CRLF normalization, and chunked newline-framed byte movement.","contracts":["Uses serial hooks","Protects byte-level request/response flow","Does not own COBS or MD5 framing"]},{"id":"i2c","layer":"transport","name":"I2C Transport","kind":"transport","paths":["n_i2c.c"],"summary":"I2C transaction, reset, query length, receive, transmit, MTU, and chunked newline-framed byte movement.","contracts":["Uses I2C hooks","Owns I2C timing and chunking behavior","Does not own COBS or MD5 framing"]},{"id":"bus","layer":"external","name":"Platform Bus","kind":"external","paths":[],"summary":"UART, USB serial, I2C, or test doubles supplied by the host platform.","contracts":["Implemented outside note-c"]},{"id":"notecard","layer":"external","name":"Notecard","kind":"external","paths":[],"summary":"Device that accepts JSON requests and returns JSON responses.","contracts":["Serial or I2C protocol boundary"]},{"id":"notehub","layer":"external","name":"Notehub","kind":"external","paths":[],"summary":"Cloud service reached by the Notecard; note-c does not communicate with Notehub directly.","contracts":["Indirect dependency only"]}],"edges":[{"from":"apps","to":"api","label":"calls"},{"from":"adapters","to":"api","label":"wraps"},{"from":"tests","to":"api","label":"exercises"},{"from":"api","to":"request","label":"request APIs"},{"from":"api","to":"json","label":"J helpers"},{"from":"api","to":"hooks","label":"hook registration"},{"from":"helpers","to":"request","label":"builds requests"},{"from":"request","to":"json","label":"serialize/parse"},{"from":"request","to":"hooks","label":"active interface"},{"from":"request","to":"serial","label":"serial path"},{"from":"request","to":"i2c","label":"I2C path"},{"from":"serial","to":"hooks","label":"serial callbacks"},{"from":"i2c","to":"hooks","label":"I2C callbacks"},{"from":"hooks","to":"bus","label":"platform calls"},{"from":"bus","to":"notecard","label":"bytes"},{"from":"notecard","to":"notehub","label":"syncs"},{"from":"tests","to":"hooks","label":"mocks"},{"from":"tests","to":"serial","label":"transport tests"},{"from":"tests","to":"i2c","label":"transport tests"},{"from":"utilities","to":"request","label":"support"},{"from":"utilities","to":"json","label":"support"}],"hotspots":[{"id":"public-api","title":"Public API and hook compatibility","nodes":["api","hooks"],"description":"The stable SDK surface that applications and adapter libraries compile against, including public request helpers and platform hook signatures.","updateRule":"Update docs and consider versioning whenever note.h contracts change."},{"id":"transaction-flow","title":"Request lifecycle","nodes":["request","json","serial","i2c"],"description":"The path a Notecard transaction follows as requests are built, serialized, sent over an active transport, parsed, returned to callers, and released according to public ownership contracts.","updateRule":"Update docs when timeout, retry, serialization, parsing, memory ownership, raw JSON string, or active-interface behavior changes."},{"id":"transport-boundary","title":"Transport and platform boundary","nodes":["serial","i2c","hooks","bus"],"description":"The byte-level boundary between portable note-c transport code and host-provided UART, USB serial, I2C, or test-double implementations; binary COBS/MD5 behavior belongs to helper code above this boundary.","updateRule":"Update docs when byte framing, chunking, MTU, reset, hook invocation, COBS ownership, or MD5 verification semantics change."},{"id":"adapter-impact","title":"Adapter impact","nodes":["adapters","api","hooks"],"description":"The parts of note-c most likely to require coordinated changes in downstream platform SDKs and integration layers.","updateRule":"Update docs when note-arduino, note-zephyr, note-espidf, POSIX, or other adapters need coordinated changes."},{"id":"json-representation","title":"J node representation","nodes":["json","api","adapters"],"description":"The in-memory layout of J, which downstream code reads directly. NOTE_C_STORAGE_OPTIMIZATION selects a packed layout that removes roughly 38% of allocations and 26% of heap, at the cost of changing source-visible field behavior; it is off by default. Layout-conditional code is confined to the storage helpers in n_cjson.c.","updateRule":"Update docs and the ADR whenever J's members, size, ownership flags, or default layout change."}],"updateTriggers":["Changes to note.h public APIs, typedefs, constants, or hook signatures.","Changes to request lifecycle, timeout, retry, memory ownership, or response handling.","Changes to serial/I2C framing, chunking, transmit, receive, reset, or MTU behavior.","Changes to JSON representation or helper semantics, including the storage layout of J and its ownership flags.","Changes to adapter expectations, build/test strategy, release strategy, or versioning.","Changes to request ownership, raw JSON string transaction behavior, or response lifetime semantics.","Changes to low-memory, single-precision, storage-optimization, user-agent, CRC, or portability-helper build variants."],"filesToUpdateTogether":["ARCHITECTURE.md","docs/architecture/architecture.html","source-research/ when source-derived behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims change","docs/architecture/decisions/*.md when a durable design decision changes"],"projectionSource":"source-research/","projectionNote":"Component-level traversal projection for architecture review. Canonical structured source evidence lives in source-research/inventory/*.json.","sourceResearch":{"researchState":"complete","recommendedState":"complete","sourceNodes":591,"dependencyEdges":1342,"finalizedClaims":29,"claimsTotal":29,"validation":"Run source-first-repo-research validate_research.py source-research before relying on updated artifacts."}}</script>
   <script>
     const architecture = JSON.parse(document.getElementById("source-research-projection").textContent);
     const nodeById = new Map(architecture.nodes.map(node => [node.id, node]));
diff --git a/docs/architecture/decisions/0002-j-node-storage-layout.md b/docs/architecture/decisions/0002-j-node-storage-layout.md
new file mode 100644
index 00000000..26475644
--- /dev/null
+++ b/docs/architecture/decisions/0002-j-node-storage-layout.md
@@ -0,0 +1,42 @@
+# 0002: Offer a Memory-Optimized `J` Storage Layout as an Opt-In Compile-Time Variant
+
+## Status
+
+Proposed
+
+## Context
+
+`J` is note-c's JSON node and the SDK's dominant consumer of heap. On a 32-bit target the node is 48 bytes, and an object member such as `"key":"value"` costs three separate heap allocations: the node, the key, and the value string. Once per-chunk allocator overhead is included, a parsed document occupies roughly 8–9× the size of its JSON text.
+
+That ratio is a real constraint on Notecard hosts with tens of kilobytes of RAM. Measurements across two production applications showed the same pattern at scale: one held 592 allocations and 17.6 KB for its working set, another 2,898 allocations and 91.6 KB.
+
+Two properties of the existing node make a substantial reduction available:
+
+- `JINTEGER` and `JNUMBER` require 8-byte alignment even where pointers are 4 bytes, so the historical member order wastes 8 bytes per node to padding.
+- A `JString` or `JRaw` node never uses `valueint` or `valuenumber`, leaving 16 bytes per string node inert.
+
+The obstacle is not feasibility but compatibility. `J` is a public type whose members downstream code reads directly, across several adapter repositories (`note-arduino`, `note-zephyr`, `note-espidf`, POSIX integrations). Every consumer is rebuilt from source, so the risk is not binary mismatch but source-visible behavior change: a recompiled consumer that reads `valueint` on a string node, or relies on the size or offsets of `J`, sees something different.
+
+## Decision
+
+Implement the optimized representation, and gate it behind `NOTE_C_STORAGE_OPTIMIZATION`, **off by default**.
+
+The optimized layout reorders members to eliminate padding (48 → 40 bytes) and reuses the bytes of `valueint`/`valuenumber` in a string node to hold the value and then the key inline, extending the node's allocation only as far as the content requires. An added `objlen` member records the node's allocation size; content that would exceed `J_MAX_PACKED_ALLOC` falls back to heap storage, which keeps `objlen` representable. Ownership gains two flags, `JValueInline` and `JKeyInline`, that record where a pointer points rather than inferring it later by comparing pointers — a comparison that is undefined in C when the operands address different objects.
+
+The default stays historical for this release cycle because of a planned external beta of that layout, and because the optimized layout is source-visibly different: it changes `sizeof(J)`, moves nearly every member offset, narrows `type` from `int` to `uint16_t`, adds a member, and — most consequentially — makes `valueint` and `valuenumber` hold character data on string nodes where they historically held zero. Any recompiled consumer that touches those fields directly can observe the difference.
+
+Promoting the optimization to the default is scoped as a separate decision, deferred by the maintainer until after a planned external beta test of the historical layout. That beta needs to exercise the representation already in the field, so the optimization stays opt-in for this release cycle regardless of its technical readiness. The later decision rests on the source-visible field behavior described above, whatever the beta surfaces, and validation against the adapter repositories.
+
+## Consequences
+
+Applications that are memory-constrained can opt in and recover roughly 38% of allocations and 26% of heap, at the cost of rebuilding every consumer with the flag set. Applications that are not constrained are unaffected and unexposed.
+
+Two layouts must both be maintained and tested. CI covers `{default, optimized} × {double, single precision}`, plus an A/B job that proves both render byte-identical JSON. The layout-conditional code is deliberately confined to a small set of storage helpers in `n_cjson.c` so the parser, printer and public API remain layout-agnostic; that containment is a maintenance requirement, not an incidental property.
+
+Under memory pressure the optimized setters abandon a write rather than overwrite packed key and value bytes in place, since the latter produced a silently altered document that still parsed. Losing the update instead is consistent with the surrounding API: `JAddItemToObject`, `JAddItemToObjectCS` and `JAddItemToArray` all return `void` and have always dropped an item silently when an allocation fails, leaving the caller's pointer dangling into freed storage. Making allocation failure detectable is a question about that whole API surface, not about this layout.
+
+Because both layouts share one rewritten parser and printer, a cross-layout comparison cannot detect a regression common to both. Rendering is therefore also compared against goldens generated from a pristine build of the base revision (`scripts/generate_corpus_golden.sh`). That check found two pre-existing printer defects that the A/B could not see, including one that emitted invalid JSON for strings containing more than one escaped control character.
+
+Every translation unit that sees `J` must be built with the same setting. CMake's `PUBLIC` propagation enforces this; other build systems must set the option for both the note-c sources and the consuming sources. This is a single-build consistency requirement, since note-c is always compiled from source as part of the consuming solution.
+
+Two public macros, `JSetIntValue` and `JSetNumberValue`, become function calls, because as macros they wrote node bytes directly from the caller's translation unit — bytes the optimized layout may be using for packed content. Their observable behavior is preserved and pinned against a pristine build: the NULL branch still yields the unconverted operand, the value operand is still evaluated exactly once, and a fractional operand still truncates into `valueint` while surviving in `valuenumber`. Two divergences are deliberate — out-of-range conversion saturates instead of being undefined, and `JSetIntValue` evaluates a side-effecting `object` expression twice rather than three times.
diff --git a/n_cjson.c b/n_cjson.c
index 2b0c0a6a..087c281b 100644
--- a/n_cjson.c
+++ b/n_cjson.c
@@ -190,17 +190,507 @@ N_CJSON_PUBLIC(void) JFree(void *p)
     _Free(p);
 }
 
-/* Internal constructor. */
-NOTE_C_STATIC J *_jNew_Item(void)
+NOTE_C_STATIC void *_cast_away_const(const void *string);
+NOTE_C_STATIC J *_j_new_keyed(int type, const char *name, const char *strval);
+
+/* ---------------------------------------------------------------------------
+ * Node storage
+ *
+ * Every mutation of the two owned pointers -- item->valuestring and
+ * item->string -- goes through the helpers below, so the rules about where
+ * content lives and who frees it exist in exactly one place.
+ *
+ * Ownership is expressed by four type flags:
+ *
+ *   JIsReference    -> valuestring is borrowed from the caller (and, for the
+ *                      reference constructors, so is child). Do not free.
+ *   JValueInline    -> valuestring points into this node's own allocation.
+ *                      Do not free; it goes away with the node.
+ *   JStringIsConst  -> string (the key) is not separately allocated, so do not
+ *                      free it. Historical flag, historical meaning.
+ *   JKeyInline      -> string (the key) points into this node's own allocation,
+ *                      as opposed to a caller-owned buffer. Implies
+ *                      JStringIsConst, never set without it.
+ *
+ * The last two look redundant and are not. JStringIsConst answers "may I free
+ * this?", which is all the free path needs. JKeyInline answers "is this inside
+ * me?", which the packing code needs -- and which cannot be recovered later by
+ * comparing the key pointer against the node address, because comparing
+ * pointers into two different objects is undefined in C long before it could
+ * yield an answer. The one flag that both cases share would force exactly that
+ * comparison, so the two are kept apart and set together at the single point
+ * where a key is placed.
+ *
+ * PACKED LAYOUT. The trailing sizeof(JINTEGER)+sizeof(JNUMBER) bytes of the
+ * struct are the numeric members, which a JString/JRaw item never uses, so for
+ * those items that region doubles as inline character storage and the
+ * allocation is extended past the struct only as far as the content needs:
+ *
+ *     string item : [ ...struct... | value NUL | key NUL ]
+ *                   inline region starts at J_INLINE_OFF (= sizeof(J) - 16)
+ *     other item  : [ ...struct... ][ key NUL ]
+ *                   key starts at sizeof(J); the numeric members are in use
+ *
+ * Inline storage is an optimization, never a mode. A setter that no longer
+ * fits, or that needs the numeric members back, moves the affected content out
+ * to the heap first (_j_unpack_numeric_region below). The J address is stable
+ * across all of it; only pointers and flags change.
+ * ------------------------------------------------------------------------- */
+
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+
+/* True for the two item types whose value is a character string. Only these
+ * lend their numeric bytes out, so this is only referenced by the packing
+ * helpers below. */
+NOTE_C_STATIC bool _j_is_string_type(const J * const item)
 {
-    J* node = (J*)_Malloc(sizeof(J));
+    int t = item->type & 0xFF;
+    return (t == JString) || (t == JRaw);
+}
+
+/* The node's inline character storage: the bytes that valueint and valuenumber
+ * occupy. See the long comment on those members in n_cjson.h -- conceptually
+ * they are a union with a char buffer, spelled out in code because the union
+ * form is not portable to the compilers this library targets.
+ *
+ * Both bounds are DERIVED with offsetof rather than assumed. Writing
+ * `sizeof(J) - (sizeof(JINTEGER) + sizeof(JNUMBER))` would silently be wrong
+ * the moment the struct gained a member after valuenumber, or trailing padding,
+ * and the mistake would be an aliasing bug rather than a compile error. */
+#define J_INLINE_OFF  offsetof(J, valueint)
+#define J_INLINE_SIZE (sizeof(J) - J_INLINE_OFF)
+
+/* Compile-time guard on the property the inline region depends on: valueint and
+ * valuenumber are contiguous and are the LAST members, so the bytes from
+ * offsetof(J, valueint) to the end of the allocation belong to nothing else.
+ *
+ * The second clause allows for trailing alignment padding, which is bounded by
+ * the struct's alignment (JINTEGER's) -- with NOTE_C_SINGLE_PRECISION, JNUMBER
+ * is a float and the struct carries 4 bytes of padding -- while still failing
+ * if a member were added after valuenumber and grew the struct. It cannot catch a member that fits entirely inside existing
+ * padding, so: DO NOT DECLARE ANYTHING AFTER valuenumber.
+ *
+ * (A negative-width array rather than _Static_assert, so this does not impose
+ * C11 on a consumer compiling at an older default.) */
+typedef char _j_numeric_pair_is_contiguous[
+    (offsetof(J, valuenumber) == offsetof(J, valueint) + sizeof(JINTEGER)) ? 1 : -1];
+typedef char _j_numeric_pair_is_last[
+    (sizeof(J) - offsetof(J, valuenumber) - sizeof(JNUMBER) < sizeof(JINTEGER)) ? 1 : -1];
+
+/* Byte offset of `p` within this node's allocation.
+ *
+ * ONLY call this when a flag already establishes that `p` points into this
+ * node -- JValueInline for the value, JKeyInline for the key. Pointer
+ * subtraction, like relational comparison, is defined only for two pointers
+ * into the same object; the flags are what make that true here. Nothing in this
+ * file infers ownership BY comparing pointers, because the pointer being tested
+ * would routinely be a string literal or an unrelated heap block, and the
+ * comparison itself would be undefined before it could produce an answer. */
+NOTE_C_STATIC size_t _j_inline_offset_of(const J * const item, const char *p)
+{
+    return (size_t)(p - (const char *)item);
+}
+
+/* True if `p` lies within the struct proper, i.e. it would be destroyed by a
+ * write to the numeric members. Same precondition as above. */
+NOTE_C_STATIC bool _j_within_struct(const J * const item, const char *p)
+{
+    return (p != NULL) && (_j_inline_offset_of(item, p) < sizeof(J));
+}
+
+/* Byte offset at which this node's key would be stored inline. Whether there is
+ * actually room there is _j_key_inline_avail()'s question, not this one's.
+ *
+ * For a string item the key follows the value inside the inline region. For any
+ * other item the numeric members are live, so the key can only go past the
+ * struct. */
+NOTE_C_STATIC size_t _j_key_inline_offset(const J * const item)
+{
+    if (!_j_is_string_type(item)) {
+        return sizeof(J);
+    }
+    /* A setter has stored numbers here. Reclaiming the region for a short key
+     * would silently destroy them, so the key can only go past the struct. */
+    if (item->type & JNumericLive) {
+        return sizeof(J);
+    }
+    if ((item->type & JValueInline) && (item->valuestring != NULL)) {
+        return _j_inline_offset_of(item, item->valuestring) + strlen(item->valuestring) + 1;
+    }
+    /* No inline value, so the whole inline region is available. */
+    return J_INLINE_OFF;
+}
+
+/* Bytes available for an inline key at that offset. */
+NOTE_C_STATIC size_t _j_key_inline_avail(const J * const item)
+{
+    size_t off = _j_key_inline_offset(item);
+    return (item->objlen > off) ? ((size_t)item->objlen - off) : 0;
+}
+
+/* The allocation size a node needs to hold this content inline.
+ *
+ * Returns sizeof(J) -- i.e. "store it all on the heap" -- when the content
+ * would push the node past J_MAX_PACKED_ALLOC, which is what keeps objlen
+ * representable. */
+NOTE_C_STATIC size_t _j_alloc_size(Jbool isString, size_t vlen, size_t klen)
+{
+    size_t need;
+
+    /* Reject the operands before adding them. Summing first and testing the
+     * result afterwards would be wrong: on a 32-bit target a caller-supplied
+     * string near SIZE_MAX makes the sum wrap to a small value that then passes
+     * the bound check, and the node would be allocated far too small. */
+    if ((vlen > J_MAX_PACKED_ALLOC) || (klen > J_MAX_PACKED_ALLOC)) {
+        return sizeof(J);
+    }
+
+    if (isString) {
+        need = J_INLINE_OFF + vlen + klen;
+    } else {
+        need = sizeof(J) + klen;
+    }
+    if (need < sizeof(J)) {
+        need = sizeof(J);
+    }
+    if (need > J_MAX_PACKED_ALLOC) {
+        return sizeof(J);
+    }
+
+    return need;
+}
+
+/* Move any content that lives within the struct proper out to the heap, so the
+ * numeric members can be written without destroying it.
+ *
+ * Returns false if that could not be done, having changed nothing that the
+ * caller must undo. The caller MUST then abandon the write: the content is
+ * still sitting in the bytes the numeric members occupy, and overwriting it
+ * would destroy it.
+ *
+ * An earlier revision treated this as best-effort and cleared the pointer when
+ * the copy could not be allocated, on the theory that losing a key beats
+ * dangling into storage about to be overwritten. Both are true and both are
+ * wrong. Under memory pressure `JSetNumberValue(item, 1.5)` on a packed member
+ * silently rendered `{"temp":"hot"}` as `{"":""}` -- the key renamed to empty,
+ * the value blanked, and the result still parses, so nothing downstream can
+ * detect it. For a Notecard host that means quietly shipping a malformed field
+ * to Notehub. The historical layout cannot do this at all: its setters never
+ * touch the key.
+ *
+ * Refusing the write preserves document content, which is the only outcome here
+ * that cannot corrupt a document. Note the precise guarantee: content is
+ * preserved and the node stays consistent, NOT that it is byte-for-byte
+ * untouched -- a value copy that succeeded before a failing key copy has
+ * already moved to the heap.
+ *
+ * Losing the update itself is ordinary note-c behavior under memory pressure:
+ * JAddItemToObject and its siblings return void and have always dropped an
+ * item silently when an allocation fails. Corrupting a document that then
+ * still parses is what was new, and what this prevents. */
+NOTE_C_STATIC bool _j_unpack_numeric_region(J * const item)
+{
+    if ((item->type & JValueInline) && _j_within_struct(item, item->valuestring)) {
+        char *copy = (char *)_j_strdup((const unsigned char *)item->valuestring);
+        if (copy == NULL) {
+            return false;
+        }
+        item->valuestring = copy;
+        item->type &= ~JValueInline;
+    }
+    /* JKeyInline, not JStringIsConst: a caller-owned key must be left exactly
+     * where it is, and is not ours to copy or free. Only a key inside this
+     * node's allocation is at risk from the numeric write, and only that case
+     * makes the offset test below meaningful. */
+    if ((item->type & JKeyInline) && _j_within_struct(item, item->string)) {
+        char *copy = (char *)_j_strdup((const unsigned char *)item->string);
+        if (copy == NULL) {
+            /* The value may already have moved to the heap above. That is a
+             * perfectly good state -- heap value, inline key -- and nothing has
+             * been lost, so there is nothing to roll back. */
+            return false;
+        }
+        item->string = copy;
+        item->type &= ~(JKeyInline | JStringIsConst);
+    }
+
+    return true;
+}
+
+#endif /* NOTE_C_STORAGE_OPTIMIZATION */
+
+/* True when valueint/valuenumber hold the numbers they appear to hold.
+ *
+ * This is the exact inverse of the work _j_unpack_numeric_region() would have
+ * to do, which is what makes it correct by construction: if nothing needs
+ * moving out of the numeric region, nothing is living there.
+ *
+ * The question is NOT answerable from the node's base type, and an earlier
+ * revision that assumed it was introduced a real regression. `JSetIntValue` has
+ * always been able to write numeric state onto a JString node without changing
+ * its type, and that state was observable through JIntValue, JNumberValue,
+ * direct field access and JDuplicate. Guarding those on "is it a string type"
+ * made a string node's numbers unreadable even in the default layout, where the
+ * members are never overlaid and the historical behavior was never at risk.
+ *
+ * In the default layout this is unconditionally true, so the historical
+ * behavior is restored exactly. */
+bool _jNumericIsLive(const J * const item)
+{
+    if (item == NULL) {
+        return false;
+    }
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+    /* Only string types ever lend their numeric bytes out; for every other type
+     * the members are unconditionally numeric. */
+    if (_j_is_string_type(item)) {
+        return (item->type & JNumericLive) != 0;
+    }
+#endif
+    return true;
+}
+
+/* Internal constructor.
+ *
+ * `alloc` is the total size to allocate, from _j_alloc_size(). The unpacked
+ * build ignores it and always allocates sizeof(J), which lets every caller
+ * request packing unconditionally. */
+NOTE_C_STATIC J *_j_new_item_sized(size_t alloc)
+{
+#ifndef NOTE_C_STORAGE_OPTIMIZATION
+    (void)alloc;
+    J *node = (J *)_Malloc(sizeof(J));
+#else
+    J *node = (J *)_Malloc(alloc);
+#endif
     if (node) {
         memset(node, '\0', sizeof(J));
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+        node->objlen = (uint16_t)alloc;
+#endif
     }
 
     return node;
 }
 
+NOTE_C_STATIC J *_jNew_Item(void)
+{
+    return _j_new_item_sized(sizeof(J));
+}
+
+/* Assign the item's base type without disturbing the ownership flags.
+ *
+ * The parse functions each assign item->type wholesale once they know what they
+ * parsed; a wholesale assignment would clear the flags describing where the
+ * key and value already live, and make JDelete() free an interior pointer. */
+NOTE_C_STATIC void _j_set_type(J * const item, int type)
+{
+    item->type = (uint16_t)(type | (item->type & (JIsReference | JStringIsConst | JValueInline | JKeyInline | JNumericLive)));
+}
+
+/* Release whatever the node separately owns, per the flags. */
+NOTE_C_STATIC void _j_release_strings(J * const item)
+{
+    if (!(item->type & (JIsReference | JValueInline)) && (item->valuestring != NULL)) {
+        _Free(item->valuestring);
+    }
+    if (!(item->type & JStringIsConst) && (item->string != NULL)) {
+        _Free(item->string);
+    }
+}
+
+/* Total allocation a constructor should request for an item that will hold a
+ * value string of `vlen` bytes (including NUL) and a key of `klen` bytes
+ * (including NUL, or 0 for none). */
+NOTE_C_STATIC size_t _j_size_for(Jbool isString, size_t vlen, size_t klen)
+{
+#ifndef NOTE_C_STORAGE_OPTIMIZATION
+    (void)isString;
+    (void)vlen;
+    (void)klen;
+    return sizeof(J);
+#else
+    return _j_alloc_size(isString, vlen, klen);
+#endif
+}
+
+/* Install a value string of `len` bytes including the NUL, preferring this
+ * node's inline region. Returns the writable buffer, or NULL on failure. The
+ * caller fills it, NUL included. */
+NOTE_C_STATIC char *_j_valuestring_reserve(J * const item, size_t len, Jbool allowInline)
+{
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+    /* Refuse the inline region if the key is already parked in it: the value
+     * always starts at J_INLINE_OFF, so writing it would run over a key stored
+     * behind it. Unreachable through today's call paths -- the parser reserves
+     * the value slot before placing the key -- but the check costs nothing and
+     * makes the helper safe to call in any order. */
+    if (allowInline
+            && _j_is_string_type(item)
+            && !(item->type & JNumericLive)
+            && ((size_t)item->objlen >= J_INLINE_OFF + len)
+            && !((item->type & JKeyInline)
+                 && (_j_inline_offset_of(item, item->string) < J_INLINE_OFF + len))) {
+        /* Releasing an old heap value first, since we are about to stop
+         * pointing at it. */
+        if (!(item->type & (JIsReference | JValueInline)) && (item->valuestring != NULL)) {
+            _Free(item->valuestring);
+        }
+        item->valuestring = (char *)item + J_INLINE_OFF;
+        item->type |= JValueInline;
+        item->type &= ~JIsReference;
+        return item->valuestring;
+    }
+#else
+    (void)allowInline;
+#endif
+    {
+        char *heap = (char *)_Malloc(len);
+        if (heap == NULL) {
+            return NULL;
+        }
+        if (!(item->type & (JIsReference | JValueInline)) && (item->valuestring != NULL)) {
+            _Free(item->valuestring);
+        }
+        item->valuestring = heap;
+        item->type &= ~(JValueInline | JIsReference);
+        return heap;
+    }
+}
+
+/* Copy `s` in as the value string. */
+NOTE_C_STATIC Jbool _j_valuestring_set(J * const item, const char *s, Jbool allowInline)
+{
+    size_t len;
+    char *dest;
+
+    if (s == NULL) {
+        return false;
+    }
+    len = strlen(s) + 1;
+    dest = _j_valuestring_reserve(item, len, allowInline);
+    if (dest == NULL) {
+        return false;
+    }
+    memcpy(dest, s, len);
+
+    return true;
+}
+
+/* Install `key` as the node's member key.
+ *
+ * `constant` means the caller guarantees the key outlives the node, so it is
+ * borrowed rather than copied (JAddItemToObjectCS). Otherwise the key is stored
+ * in this node's remaining inline room when it fits, and on the heap when it
+ * does not.
+ *
+ * ALIASING: `key` may be the node's own current key -- the documented
+ * "move a member, keep its name" idiom does exactly that:
+ *
+ *     J *m = JDetachItemFromObject(src, name);
+ *     JAddItemToObject(dst, JGetItemName(m), m);
+ *
+ * so the old key is never released before the replacement is in hand. */
+NOTE_C_STATIC Jbool _j_key_set(J * const item, const char *key, Jbool constant)
+{
+    char *oldKey;
+    int oldFlags;
+
+    if (key == NULL) {
+        return false;
+    }
+
+    /* The caller handed back the key we already hold. */
+    if (key == item->string) {
+        return true;
+    }
+
+    /* NOTE: `key` may still ALIAS storage this node owns without being equal to
+     * it. The documented "move a member, keep its name" idiom makes that easy to
+     * reach with an interior pointer:
+     *
+     *     J *m = JDetachItemFromObject(src, name);
+     *     JAddItemToObject(dst, JGetItemName(m) + 1, m);
+     *
+     * Under NOTE_C_STORAGE_OPTIMIZATION the key may live in the node's own
+     * allocation, so the destination computed below can overlap `key`. Hence
+     * memmove rather than memcpy on the inline path; the heap path reads `key`
+     * in full via _j_strdup before anything is released, so it is already safe. */
+
+    oldKey = item->string;
+    oldFlags = item->type;
+
+    if (constant) {
+        /* Borrowed from the caller: not ours to free, and NOT inside the node. */
+        item->string = (char *)_cast_away_const(key);
+        item->type |= JStringIsConst;
+        item->type &= ~JKeyInline;
+    } else {
+        char *dest = NULL;
+
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+        size_t klen = strlen(key) + 1;
+        if (klen <= _j_key_inline_avail(item)) {
+            dest = (char *)item + _j_key_inline_offset(item);
+            /* memmove, not memcpy: see the aliasing note above. Overlapping
+             * memcpy is undefined, and this case is reachable from public API. */
+            memmove(dest, key, klen);
+            item->string = dest;
+            item->type |= (JStringIsConst | JKeyInline);
+        }
+#endif
+        if (dest == NULL) {
+            char *copy = (char *)_j_strdup((const unsigned char *)key);
+            if (copy == NULL) {
+                return false;
+            }
+            item->string = copy;
+            item->type &= ~(JStringIsConst | JKeyInline);
+        }
+    }
+
+    /* Release the old key only now, and only if it is not the storage we just
+     * wrote into. */
+    if (!(oldFlags & JStringIsConst) && (oldKey != NULL) && (oldKey != item->string)) {
+        _Free(oldKey);
+    }
+
+    return true;
+}
+
+/* Reserve inline storage for a key of `len` bytes including the NUL, for a
+ * constructor that sized the node for it. Returns the writable buffer.
+ *
+ * The unpacked build hands back a heap block instead, so the parser's code path
+ * is identical in both builds. Returns NULL on allocation failure. */
+NOTE_C_STATIC char *_j_key_storage(J * const item, size_t len, size_t inlineOffset)
+{
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+    /* `inlineOffset` is where the caller has decided the key belongs, computed
+     * from the lengths it RESERVED rather than from current contents. That
+     * distinction matters: the parser reserves the value slot before the value
+     * has been decoded, so at this moment the value is still a zero-length
+     * placeholder and deriving the key's offset from strlen(valuestring) would
+     * park the key on top of the bytes the value is about to occupy. */
+    if ((inlineOffset != 0) && ((size_t)item->objlen >= inlineOffset + len)) {
+        item->string = (char *)item + inlineOffset;
+        item->type |= (JStringIsConst | JKeyInline);
+        return item->string;
+    }
+#else
+    (void)inlineOffset;
+#endif
+    {
+        char *heap = (char *)_Malloc(len);
+        if (heap == NULL) {
+            return NULL;
+        }
+        item->string = heap;
+        item->type &= ~(JStringIsConst | JKeyInline);
+        return heap;
+    }
+}
+
 /*!
  @brief Free a `J` object.
 
@@ -214,12 +704,7 @@ N_CJSON_PUBLIC(void) JDelete(J *item)
         if (!(item->type & JIsReference) && (item->child != NULL)) {
             JDelete(item->child);
         }
-        if (!(item->type & JIsReference) && (item->valuestring != NULL)) {
-            _Free(item->valuestring);
-        }
-        if (!(item->type & JStringIsConst) && (item->string != NULL)) {
-            _Free(item->string);
-        }
+        _j_release_strings(item);
         _Free(item);
         item = next;
     }
@@ -314,12 +799,29 @@ NOTE_C_STATIC Jbool _parse_number(J * const item, parse_buffer * const input_buf
         item->valueint = JAtoI((const char*)number_c_string);
     }
 
-    item->type = JNumber;
+    _j_set_type(item, JNumber);
 
     input_buffer->offset += (size_t)(after_end - number_c_string);
     return true;
 }
 
+/* Convert a JNUMBER to a JINTEGER, saturating rather than invoking the
+ * undefined behavior a plain out-of-range float-to-integer cast would.
+ *
+ * The limits are cast to JNUMBER before comparison because JINTEGER_MAX is not
+ * exactly representable as a double, and newer AppleClang rejects the implicit
+ * conversion under -Werror. */
+NOTE_C_STATIC JINTEGER _j_saturate_to_integer(JNUMBER number)
+{
+    if (number >= (JNUMBER)JINTEGER_MAX) {
+        return JINTEGER_MAX;
+    }
+    if (number <= (JNUMBER)JINTEGER_MIN) {
+        return JINTEGER_MIN;
+    }
+    return (JINTEGER)number;
+}
+
 /* don't ask me, but the original JSetNumberValue returns an integer or JNUMBER */
 N_CJSON_PUBLIC(JNUMBER) JSetNumberHelper(J *object, JNUMBER number)
 {
@@ -327,20 +829,78 @@ N_CJSON_PUBLIC(JNUMBER) JSetNumberHelper(J *object, JNUMBER number)
         return number;
     }
 
-    // Saturate valueint in the case of overflow.
-    // Cast integer limits to JNUMBER: INT64_MAX is not exactly representable as
-    // double, and newer AppleClang rejects the implicit conversion under -Werror.
-    if (number >= (JNUMBER)JINTEGER_MAX) {
-        object->valueint = JINTEGER_MAX;
-    } else if (number <= (JNUMBER)JINTEGER_MIN) {
-        object->valueint = JINTEGER_MIN;
-    } else {
-        object->valueint = (JINTEGER)number;
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+    /* The numeric members double as inline character storage, so anything
+     * living there has to move to the heap before they are written. This is why
+     * JSetNumberValue is a function and not a macro: a macro expanding to
+     * `(object)->valuenumber = ...` in the caller's translation unit could not
+     * do this, and would silently destroy a packed key or value.
+     *
+     * If the evacuation cannot allocate, refuse the write. Proceeding would
+     * overwrite the key and value in place, which parses cleanly afterwards and
+     * so cannot be detected downstream; preserving the existing content cannot
+     * corrupt a document. Same shape as the NULL-object path above: the operand
+     * comes back and the numeric members are not written. */
+    if (!_j_unpack_numeric_region(object)) {
+        return number;
     }
+    /* Record that these bytes now hold numbers. Without it the region looks
+     * unoccupied and _j_key_set() would reclaim it for a short key, silently
+     * overwriting what is about to be written; and a reference copied from this
+     * node could not tell numbers from packed characters. Only meaningful for a
+     * string type -- for anything else the members are always numeric -- but it
+     * is cheaper to set unconditionally than to branch. */
+    object->type |= JNumericLive;
+#endif
+
+    // Saturate valueint in the case of overflow.
+    object->valueint = _j_saturate_to_integer(number);
 
     return object->valuenumber = number;
 }
 
+/* Assign an integer value, propagating it to valuenumber so the two stay in
+ * step. Backs the JSetIntValue macro.
+ *
+ * The parameter is JNUMBER, not JINTEGER, and that is load-bearing. The
+ * historical macro was
+ *
+ *     ((object) ? (object)->valueint = (object)->valuenumber = (number) : (number))
+ *
+ * which parses as `valueint = (valuenumber = number)`, so BOTH members received
+ * the operand in its original arithmetic form. JSetIntValue(item, 1.5) left
+ * valueint == 1 and valuenumber == 1.5. Declaring this parameter JINTEGER would
+ * truncate at the call site and store 1 in both, silently changing a public
+ * contract; taking JNUMBER reproduces the old result exactly.
+ *
+ * The operand is also evaluated exactly once, as it was before. The old macro
+ * repeated `object` three times but never repeated `number`, so a value
+ * expression with side effects behaves as it always has.
+ *
+ * One divergence is intentional. The macro's implicit JNUMBER-to-JINTEGER
+ * conversion is undefined when the value is out of JINTEGER's range; this
+ * saturates instead, as JSetNumberHelper() already did. Every input for which
+ * the macro was defined yields the same result. */
+N_CJSON_PUBLIC(JINTEGER) JSetIntHelper(J *object, JNUMBER number)
+{
+    if (object == NULL) {
+        return _j_saturate_to_integer(number);
+    }
+
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+    /* See JSetNumberHelper(): free the numeric members of any inline content,
+     * and refuse the write rather than overwrite it if that is not possible. */
+    if (!_j_unpack_numeric_region(object)) {
+        return _j_saturate_to_integer(number);
+    }
+    object->type |= JNumericLive;   /* see JSetNumberHelper() */
+#endif
+
+    object->valuenumber = number;
+
+    return object->valueint = _j_saturate_to_integer(number);
+}
+
 typedef struct {
     unsigned char *buffer;
     size_t length;
@@ -605,56 +1165,64 @@ NOTE_C_STATIC unsigned char _utf16_literal_to_utf8(const unsigned char * const i
 }
 
 /* Parse the input text into an unescaped cinput, and populate item. */
-NOTE_C_STATIC Jbool _parse_string(J * const item, parse_buffer * const input_buffer)
+/* Measure the JSON string token at the current offset without consuming it.
+ *
+ * On success *maxLen receives an upper bound on the decoded length INCLUDING the
+ * terminating NUL (escapes only ever shrink), and *tokenEnd points at the
+ * closing quote. Split out of _parse_string() so that _parse_object() can size a
+ * node and its inline key in a single allocation before the node exists. */
+NOTE_C_STATIC Jbool _j_parse_string_measure(parse_buffer * const input_buffer,
+        size_t *maxLen,
+        const unsigned char **tokenEnd)
 {
-    // This is a static function that is only called internally, and we are
-    // guaranteed that item is not NULL. `cppcheck` is not able to infer this
-    // from the code, because we are using a macro, NOTE_C_STATIC, to remove
-    // the static keyword in the public header during testing.
+    const unsigned char *input_end = NULL;
+    size_t skipped_bytes = 0;
 
-    // cppcheck-suppress ctunullpointer
-    // cppcheck-suppress nullPointerRedundantCheck
-    const unsigned char *input_pointer = buffer_at_offset(input_buffer) + 1;
-    // cppcheck-suppress nullPointerRedundantCheck
-    const unsigned char *input_end = buffer_at_offset(input_buffer) + 1;
-    unsigned char *output_pointer = NULL;
-    unsigned char *output = NULL;
-
-    /* not a string */
-    // cppcheck-suppress nullPointerRedundantCheck
-    if (buffer_at_offset(input_buffer)[0] != '\"') {
-        goto fail;
+    if ((input_buffer == NULL) || (input_buffer->content == NULL)) {
+        return false;
+    }
+    if (cannot_access_at_index(input_buffer, 0) || (buffer_at_offset(input_buffer)[0] != '\"')) {
+        return false;
     }
 
-    {
-        /* calculate approximate size of the output (overestimate) */
-        size_t allocation_length = 0;
-        size_t skipped_bytes = 0;
-        while (((size_t)(input_end - input_buffer->content) < input_buffer->length) && (*input_end != '\"')) {
-            /* is escape sequence */
-            if (input_end[0] == '\\') {
-                if ((size_t)(input_end + 1 - input_buffer->content) >= input_buffer->length) {
-                    /* prevent buffer overflow when last input character is a backslash */
-                    goto fail;
-                }
-                skipped_bytes++;
-                input_end++;
+    input_end = buffer_at_offset(input_buffer) + 1;
+    while (((size_t)(input_end - input_buffer->content) < input_buffer->length) && (*input_end != '\"')) {
+        /* is escape sequence */
+        if (input_end[0] == '\\') {
+            if ((size_t)(input_end + 1 - input_buffer->content) >= input_buffer->length) {
+                /* prevent buffer overflow when last input character is a backslash */
+                return false;
             }
+            skipped_bytes++;
             input_end++;
         }
-        if (((size_t)(input_end - input_buffer->content) >= input_buffer->length) || (*input_end != '\"')) {
-            goto fail; /* string ended unexpectedly */
-        }
-
-        /* This is at most how much we need for the output */
-        allocation_length = (size_t) (input_end - buffer_at_offset(input_buffer)) - skipped_bytes;
-        output = (unsigned char*)_Malloc(allocation_length + 1);  // trailing '\0'
-        if (output == NULL) {
-            goto fail; /* allocation failure */
-        }
+        input_end++;
+    }
+    if (((size_t)(input_end - input_buffer->content) >= input_buffer->length) || (*input_end != '\"')) {
+        return false; /* string ended unexpectedly */
     }
 
-    output_pointer = output;
+    /* The span runs from the opening quote to the closing quote, so the decoded
+     * content is at most (span - 1 - escapes) bytes; adding one for the NUL
+     * gives (span - escapes). Counting the opening quote as content here would
+     * over-reserve by a byte, which is harmless for correctness but pushes a
+     * 15-character string just past the inline capacity. */
+    *maxLen = (size_t)(input_end - buffer_at_offset(input_buffer)) - skipped_bytes;
+    *tokenEnd = input_end;
+
+    return true;
+}
+
+/* Decode the measured token into `output`, which must have room for the
+ * measured length. Writes the terminating NUL and advances the input past the
+ * closing quote. */
+NOTE_C_STATIC Jbool _j_parse_string_decode(parse_buffer * const input_buffer,
+        const unsigned char * const input_end,
+        unsigned char * const output)
+{
+    const unsigned char *input_pointer = buffer_at_offset(input_buffer) + 1;
+    unsigned char *output_pointer = output;
+
     /* loop through the string literal */
     while (input_pointer < input_end) {
         if (*input_pointer != '\\') {
@@ -708,19 +1276,12 @@ NOTE_C_STATIC Jbool _parse_string(J * const item, parse_buffer * const input_buf
     /* zero terminate the output */
     *output_pointer = '\0';
 
-    item->type = JString;
-    item->valuestring = (char*)output;
-
     input_buffer->offset = (size_t) (input_end - input_buffer->content);
     input_buffer->offset++;
 
     return true;
 
 fail:
-    if (output != NULL) {
-        _Free(output);
-    }
-
     if (input_pointer != NULL) {
         input_buffer->offset = (size_t)(input_pointer - input_buffer->content);
     }
@@ -728,6 +1289,41 @@ NOTE_C_STATIC Jbool _parse_string(J * const item, parse_buffer * const input_buf
     return false;
 }
 
+/* Parse the string at the current offset into item->valuestring. */
+NOTE_C_STATIC Jbool _parse_string(J * const item, parse_buffer * const input_buffer)
+{
+    const unsigned char *input_end = NULL;
+    size_t maxLen = 0;
+    char *output = NULL;
+
+    if (!_j_parse_string_measure(input_buffer, &maxLen, &input_end)) {
+        return false;
+    }
+
+    /* Set the type before reserving, so the inline-storage heuristics see the
+     * node's final type. */
+    _j_set_type(item, JString);
+
+    output = _j_valuestring_reserve(item, maxLen, true);
+    if (output == NULL) {
+        return false;
+    }
+
+    if (!_j_parse_string_decode(input_buffer, input_end, (unsigned char *)output)) {
+        /* Release whatever the reserve just installed, so the caller's cleanup
+         * does not see a half-built value. Uses the same ownership predicate as
+         * _j_release_strings(), so an interior pointer is never freed. */
+        if (!(item->type & (JIsReference | JValueInline))) {
+            _Free(item->valuestring);
+        }
+        item->valuestring = NULL;
+        item->type &= ~JValueInline;
+        return false;
+    }
+
+    return true;
+}
+
 /* Convert a 16-bit number to 4 hex digits, null-terminating it */
 void _n_htoa16(uint16_t n, unsigned char *p)
 {
@@ -845,7 +1441,14 @@ NOTE_C_STATIC Jbool _print_string_ptr(const unsigned char * const input, printbu
                 /* escape and print as unicode codepoint */
                 *output_pointer++ = 'u';
                 _n_htoa16(*input_pointer, output_pointer);
-                output_pointer += 4;
+                /* _n_htoa16() writes 4 hex digits plus a NUL without advancing
+                 * output_pointer, and the enclosing for loop supplies a further
+                 * increment, so advancing by 3 here makes a \uXXXX escape
+                 * consume exactly the 6 bytes that escape_characters budgets
+                 * for it above. This was += 4, which over-advanced by one per
+                 * escape: it overran the output reservation and left a stray
+                 * NUL that truncated the document. */
+                output_pointer += 3;
                 break;
             }
         }
@@ -1142,19 +1745,19 @@ NOTE_C_STATIC Jbool _parse_value(J * const item, parse_buffer * const input_buff
     /* parse the different types of values */
     /* null */
     if (can_read(input_buffer, 4) && (strncmp((const char*)buffer_at_offset(input_buffer), c_null, c_null_len) == 0)) {
-        item->type = JNULL;
+        _j_set_type(item, JNULL);
         input_buffer->offset += 4;
         return true;
     }
     /* false */
     if (can_read(input_buffer, 5) && (strncmp((const char*)buffer_at_offset(input_buffer), c_false, c_false_len) == 0)) {
-        item->type = JFalse;
+        _j_set_type(item, JFalse);
         input_buffer->offset += 5;
         return true;
     }
     /* true */
     if (can_read(input_buffer, 4) && (strncmp((const char*)buffer_at_offset(input_buffer), c_true, c_true_len) == 0)) {
-        item->type = JTrue;
+        _j_set_type(item, JTrue);
         item->valueint = 1;
         input_buffer->offset += 4;
         return true;
@@ -1326,7 +1929,7 @@ NOTE_C_STATIC Jbool _parse_array(J * const item, parse_buffer * const input_buff
 success:
     input_buffer->depth--;
 
-    item->type = JArray;
+    _j_set_type(item, JArray);
     item->child = head;
 
     input_buffer->offset++;
@@ -1441,11 +2044,70 @@ NOTE_C_STATIC Jbool _parse_object(J * const item, parse_buffer * const input_buf
 
     /* loop through the comma separated array elements */
     do {
-        /* allocate next item */
-        J *new_item = _jNew_Item();
+        J *new_item = NULL;
+        const unsigned char *keyEnd = NULL;
+        size_t keyMax = 0;
+        size_t valMax = 0;
+        Jbool valueIsString = false;
+
+        /* Measure the key BEFORE allocating the node, then look ahead at the
+         * value, so the node, its key AND a short string value can all be
+         * carved out of a single allocation. Both measurements are upper bounds
+         * (escape sequences only shrink), so content containing escapes
+         * over-reserves by a few bytes -- still strictly better than the extra
+         * heap blocks it replaces. */
+        // _buffer_skip_whitespace() will verify the input_buffer is not NULL at
+        // the new offset.
+        // cppcheck-suppress nullPointerRedundantCheck
+        input_buffer->offset++;
+        _buffer_skip_whitespace(input_buffer);
+        if (!_j_parse_string_measure(input_buffer, &keyMax, &keyEnd)) {
+            goto fail; /* failed to parse name */
+        }
+
+        /* Look ahead past the ':' for the value. Only its FIRST byte is needed
+         * to know whether it is a string, and if it is, it can be measured
+         * without consuming anything. The input offset is restored either way. */
+        {
+            // cppcheck cannot infer that input_buffer is non-NULL here, because
+            // NOTE_C_STATIC removes the static keyword during test builds. Same
+            // suppressions as the rest of this function.
+            // cppcheck-suppress nullPointerRedundantCheck
+            size_t savedOffset = input_buffer->offset;
+            // cppcheck-suppress nullPointerRedundantCheck
+            size_t afterKey = (size_t)(keyEnd - input_buffer->content) + 1;
+            const unsigned char *valEnd = NULL;
+
+            // cppcheck-suppress nullPointerRedundantCheck
+            input_buffer->offset = afterKey;
+            _buffer_skip_whitespace(input_buffer);
+            if (can_access_at_index(input_buffer, 0)
+                    && (buffer_at_offset(input_buffer)[0] == ':')) {
+                input_buffer->offset++;
+                _buffer_skip_whitespace(input_buffer);
+                if (can_access_at_index(input_buffer, 0)
+                        && (buffer_at_offset(input_buffer)[0] == '\"')) {
+                    if (_j_parse_string_measure(input_buffer, &valMax, &valEnd)) {
+                        valueIsString = true;
+                    } else {
+                        valMax = 0;
+                    }
+                }
+            }
+            // cppcheck-suppress nullPointerRedundantCheck
+            input_buffer->offset = savedOffset;
+        }
+
+        /* allocate next item, sized for its key and (if a string) its value */
+        new_item = _j_new_item_sized(_j_size_for(valueIsString, valMax, keyMax));
         if (new_item == NULL) {
             goto fail; /* allocation failure */
         }
+        if (valueIsString) {
+            /* Declare the type now so the storage helpers place the key after
+             * the value inside the inline region rather than past the struct. */
+            _j_set_type(new_item, JString);
+        }
 
         /* attach next item to list */
         if (head == NULL) {
@@ -1458,21 +2120,42 @@ NOTE_C_STATIC Jbool _parse_object(J * const item, parse_buffer * const input_buf
             current_item = new_item;
         }
 
-        /* parse the name of the child */
-        // _buffer_skip_whitespace() will verify the input_buffer is not NULL at
-        // the new offset.
-        // cppcheck-suppress nullPointerRedundantCheck
-        input_buffer->offset++;
-        _buffer_skip_whitespace(input_buffer);
-        if (!_parse_string(current_item, input_buffer)) {
-            goto fail; /* faile to parse name */
+        /* Reserve the value slot first when the value is a string, so the key
+         * lands after it inside the same allocation. The value bytes are filled
+         * in later by _parse_value; only the placement is decided here. */
+        if (valueIsString) {
+            if (_j_valuestring_reserve(current_item, valMax, true) == NULL) {
+                goto fail; /* allocation failure */
+            }
+            /* Keep the reserved region a valid empty string until it is filled,
+             * so an early failure cannot leave unterminated bytes behind. */
+            current_item->valuestring[0] = '\0';
+        }
+
+        /* Decode the key straight into the node's own storage. In the unpacked
+         * build _j_key_storage() hands back a heap block instead, so this loop
+         * is identical in both builds.
+         *
+         * The key follows the RESERVED value slot for a string member, and the
+         * struct for anything else (whose numeric members are live). */
+        {
+            size_t keyOffset;
+            char *keyDest;
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+            keyOffset = valueIsString ? (J_INLINE_OFF + valMax) : sizeof(J);
+#else
+            keyOffset = 0;
+#endif
+            keyDest = _j_key_storage(current_item, keyMax, keyOffset);
+            if (keyDest == NULL) {
+                goto fail; /* allocation failure */
+            }
+            if (!_j_parse_string_decode(input_buffer, keyEnd, (unsigned char *)keyDest)) {
+                goto fail; /* failed to parse name */
+            }
         }
         _buffer_skip_whitespace(input_buffer);
 
-        /* swap valuestring and string, because we parsed the name */
-        current_item->string = current_item->valuestring;
-        current_item->valuestring = NULL;
-
         if (cannot_access_at_index(input_buffer, 0) || (buffer_at_offset(input_buffer)[0] != ':')) {
             goto fail; /* invalid object */
         }
@@ -1493,7 +2176,7 @@ NOTE_C_STATIC Jbool _parse_object(J * const item, parse_buffer * const input_buf
 success:
     input_buffer->depth--;
 
-    item->type = JObject;
+    _j_set_type(item, JObject);
     item->child = head;
 
     input_buffer->offset++;
@@ -1549,31 +2232,15 @@ NOTE_C_STATIC Jbool _print_object(const J * const item, printbuffer * const outp
     output_buffer->offset += length;
 
     while (current_item) {
-        if (output_buffer->format) {
-            size_t i;
-#if (PRINT_TAB_CHARS == 0)
-            int needed = output_buffer->depth;
-#else
-            int needed = output_buffer->depth * PRINT_TAB_CHARS;
-#endif
-            output_pointer = _ensure(output_buffer, needed);
-            if (output_pointer == NULL) {
-                return false;
-            }
-            for (i = 0; i < output_buffer->depth; i++) {
-#if (PRINT_TAB_CHARS == 0)
-                *output_pointer++ = '\t';
-                output_buffer_offset++;
-#else
-                for (int tc=0; tc<PRINT_TAB_CHARS; tc++) {
-                    *output_pointer++ = ' ';
-                    output_buffer->offset++;
-                }
-#endif
-            }
-        }
 
-        /* See if it should be eliminated becase of omitempty */
+        /* See if it should be eliminated because of omitempty.
+         *
+         * This must be decided BEFORE any indentation is emitted. Emitting the
+         * indentation first left orphaned whitespace behind for every elided
+         * member -- {"a":0} rendered as "{\n    }" -- and consumed buffer the
+         * caller never budgeted for. It also meant formatted omit-empty output
+         * was not a fixed point: re-printing a re-parsed document produced
+         * different whitespace. */
         bool omit = false;
         if (output_buffer->omitempty) {
             int type = JGetItemType(current_item);
@@ -1583,6 +2250,30 @@ NOTE_C_STATIC Jbool _print_object(const J * const item, printbuffer * const outp
         /* print item only if not omitted */
         if (!omit) {
 
+            if (output_buffer->format) {
+                size_t i;
+#if (PRINT_TAB_CHARS == 0)
+                size_t needed = output_buffer->depth;
+#else
+                size_t needed = output_buffer->depth * PRINT_TAB_CHARS;
+#endif
+                output_pointer = _ensure(output_buffer, needed);
+                if (output_pointer == NULL) {
+                    return false;
+                }
+                for (i = 0; i < output_buffer->depth; i++) {
+#if (PRINT_TAB_CHARS == 0)
+                    *output_pointer++ = '\t';
+                    output_buffer->offset++;
+#else
+                    for (int tc=0; tc<PRINT_TAB_CHARS; tc++) {
+                        *output_pointer++ = ' ';
+                        output_buffer->offset++;
+                    }
+#endif
+                }
+            }
+
             /* print key */
             if (!_print_string_ptr((unsigned char*)current_item->string, output_buffer)) {
                 return false;
@@ -1781,6 +2472,29 @@ NOTE_C_STATIC J *_create_reference(const J *item)
     reference->string = NULL;
     reference->type |= JIsReference;
     reference->next = reference->prev = NULL;
+    /* The key was just dropped, so no key-ownership flag may survive the copy.
+     * JStringIsConst on a NULL key is merely inert, but JKeyInline would be an
+     * active lie -- it asserts that reference->string addresses THIS node. */
+    reference->type &= ~(JStringIsConst | JKeyInline);
+#ifdef NOTE_C_STORAGE_OPTIMIZATION
+    /* The memcpy above copied the SOURCE's packing state into a node that has
+     * its own, smaller allocation. Left uncorrected, objlen would claim this
+     * node is as large as the source, and JValueInline would claim a
+     * valuestring pointing into the SOURCE lies inside THIS node -- from which
+     * _j_key_inline_offset() would compute a key offset relative to the wrong
+     * allocation, and _j_key_set() would then write the key at that offset.
+     * Reset both to describe the reference itself: its own allocation is
+     * exactly sizeof(J), and its value string is borrowed, which is what
+     * JIsReference above already records. */
+    reference->objlen = (uint16_t)sizeof(J);
+    reference->type &= ~JValueInline;
+#endif
+    /* NOTE: this is a shallow copy, so if the source's value string lives in the
+     * source's own allocation the reference points into it. That is the same
+     * borrowed-pointer relationship the unpacked build has with the source's
+     * separate heap block -- in both layouts a reference must not outlive the
+     * item it references. JIsReference is set below, so the reference never
+     * frees it either way. */
     return reference;
 }
 
@@ -1838,32 +2552,14 @@ NOTE_C_STATIC void* _cast_away_const(const void* string)
 
 NOTE_C_STATIC Jbool _add_item_to_object(J * const object, const char * const string, J * const item, const Jbool constant_key)
 {
-    char *new_key = NULL;
-    int new_type = JInvalid;
-
     if ((object == NULL) || (string == NULL) || (item == NULL)) {
         return false;
     }
 
-    if (constant_key) {
-        new_key = (char*)_cast_away_const(string);
-        new_type = item->type | JStringIsConst;
-    } else {
-        new_key = (char*)_j_strdup((const unsigned char*)string);
-        if (new_key == NULL) {
-            return false;
-        }
-
-        new_type = item->type & ~JStringIsConst;
-    }
-
-    if (!(item->type & JStringIsConst) && (item->string != NULL)) {
-        _Free(item->string);
+    if (!_j_key_set(item, string, constant_key)) {
+        return false;
     }
 
-    item->string = new_key;
-    item->type = new_type;
-
     return _add_item_to_array(object, item);
 }
 
@@ -1912,13 +2608,39 @@ N_CJSON_PUBLIC(void) JAddItemReferenceToObject(J *object, const char *string, J
     }
 }
 
+/* Create an item sized to hold `name` as an inline key, and `strval` as an
+ * inline value when the type is a string type.
+ *
+ * The JAdd<T>ToObject helpers know the key at the moment they construct the
+ * item, so unlike the generic JAddItemToObject path they can reserve room for
+ * it. Without this a JAddNumberToObject() key always needed its own heap block,
+ * because JCreateNumber() allocates exactly sizeof(J) and a node can never grow
+ * afterwards -- its address has already been handed to the caller. */
+NOTE_C_STATIC J *_j_new_keyed(int type, const char *name, const char *strval)
+{
+    size_t klen = (name != NULL) ? strlen(name) + 1 : 0;
+    size_t vlen = (strval != NULL) ? strlen(strval) + 1 : 0;
+    Jbool isString = (type == JString) || (type == JRaw);
+    J *item = _j_new_item_sized(_j_size_for(isString, vlen, klen));
+
+    if (item != NULL) {
+        item->type = (uint16_t)type;
+        if (isString && !_j_valuestring_set(item, strval, true)) {
+            JDelete(item);
+            return NULL;
+        }
+    }
+
+    return item;
+}
+
 N_CJSON_PUBLIC(J*) JAddTrueToObject(J * const object, const char * const name)
 {
     if (object == NULL) {
         return NULL;
     }
 
-    J *true_item = JCreateTrue();
+    J *true_item = _j_new_keyed(JTrue, name, NULL);
     if (_add_item_to_object(object, name, true_item, false)) {
         return true_item;
     }
@@ -1933,7 +2655,7 @@ N_CJSON_PUBLIC(J*) JAddFalseToObject(J * const object, const char * const name)
         return NULL;
     }
 
-    J *false_item = JCreateFalse();
+    J *false_item = _j_new_keyed(JFalse, name, NULL);
     if (_add_item_to_object(object, name, false_item, false)) {
         return false_item;
     }
@@ -1957,7 +2679,7 @@ N_CJSON_PUBLIC(J*) JAddBoolToObject(J * const object, const char * const name, c
         return NULL;
     }
 
-    J *bool_item = JCreateBool(boolean);
+    J *bool_item = _j_new_keyed(boolean ? JTrue : JFalse, name, NULL);
     if (_add_item_to_object(object, name, bool_item, false)) {
         return bool_item;
     }
@@ -1981,7 +2703,10 @@ N_CJSON_PUBLIC(J*) JAddNumberToObject(J * const object, const char * const name,
         return NULL;
     }
 
-    J *number_item = JCreateNumber(number);
+    J *number_item = _j_new_keyed(JNumber, name, NULL);
+    if (number_item != NULL) {
+        JSetNumberHelper(number_item, number);
+    }
     if (_add_item_to_object(object, name, number_item, false)) {
         return number_item;
     }
@@ -1996,7 +2721,17 @@ N_CJSON_PUBLIC(J*) JAddIntToObject(J * const object, const char * const name, co
         return NULL;
     }
 
-    J *integer_item = JCreateInteger(integer);
+    J *integer_item = _j_new_keyed(JNumber, name, NULL);
+    if (integer_item != NULL) {
+        /* Assign valueint DIRECTLY from the JINTEGER, exactly as
+         * JCreateInteger() does. Routing this through JSetIntHelper() would
+         * pass the value as a JNUMBER, and under NOTE_C_SINGLE_PRECISION that
+         * is a float: a Unix timestamp, which is exact in an int32 but not in a
+         * float, comes back rounded. The node is a fresh JNumber, so nothing is
+         * packed in the numeric region and the fields can be written as-is. */
+        integer_item->valuenumber = (JNUMBER)integer;
+        integer_item->valueint = integer;
+    }
     if (_add_item_to_object(object, name, integer_item, false)) {
         return integer_item;
     }
@@ -2020,7 +2755,7 @@ N_CJSON_PUBLIC(J*) JAddStringToObject(J * const object, const char * const name,
         return NULL;
     }
 
-    J *string_item = JCreateString(string);
+    J *string_item = _j_new_keyed(JString, name, string);
     if (_add_item_to_object(object, name, string_item, false)) {
         return string_item;
     }
@@ -2035,7 +2770,7 @@ N_CJSON_PUBLIC(J*) JAddRawToObject(J * const object, const char * const name, co
         return NULL;
     }
 
-    J *raw_item = JCreateRaw(raw);
+    J *raw_item = _j_new_keyed(JRaw, name, raw);
     if (_add_item_to_object(object, name, raw_item, false)) {
         return raw_item;
     }
@@ -2058,7 +2793,7 @@ N_CJSON_PUBLIC(J*) JAddObjectToObject(J * const object, const char * const name)
         return NULL;
     }
 
-    J *object_item = JCreateObject();
+    J *object_item = _j_new_keyed(JObject, name, NULL);
     if (_add_item_to_object(object, name, object_item, false)) {
         return object_item;
     }
@@ -2081,7 +2816,7 @@ N_CJSON_PUBLIC(J*) JAddArrayToObject(J * const object, const char * const name)
         return NULL;
     }
 
-    J *array = JCreateArray();
+    J *array = _j_new_keyed(JArray, name, NULL);
     if (_add_item_to_object(object, name, array, false)) {
         return array;
     }
@@ -2265,17 +3000,10 @@ NOTE_C_STATIC Jbool _replace_item_in_object(J *object, const char *string, J *re
         return false;
     }
 
-    char *new_key = (char*)_j_strdup((const unsigned char*)string);
-    if (new_key == NULL) {
-        return false;
-    }
-
     /* replace the name in the replacement */
-    if (!(replacement->type & JStringIsConst) && (replacement->string != NULL)) {
-        _Free(replacement->string);
+    if (!_j_key_set(replacement, string, false)) {
+        return false;
     }
-    replacement->string = new_key;
-    replacement->type &= ~JStringIsConst;
 
     JReplaceItemViaPointer(object, existing, replacement);
 
@@ -2365,11 +3093,20 @@ N_CJSON_PUBLIC(J *) JCreateInteger(JINTEGER integer)
 
 N_CJSON_PUBLIC(J *) JCreateString(const char *string)
 {
-    J *item = _jNew_Item();
-    if(item) {
+    J *item;
+    size_t len;
+
+    if (string == NULL) {
+        return NULL;
+    }
+
+    /* Reserve trailing room up front for a value too long to inline, so the
+     * string lands in the node's own allocation instead of a second block. */
+    len = strlen(string) + 1;
+    item = _j_new_item_sized(_j_size_for(true, len, 0));
+    if (item) {
         item->type = JString;
-        item->valuestring = (char*)_j_strdup((const unsigned char*)string);
-        if(!item->valuestring) {
+        if (!_j_valuestring_set(item, string, true)) {
             JDelete(item);
             return NULL;
         }
@@ -2425,11 +3162,18 @@ N_CJSON_PUBLIC(J *) JCreateArrayReference(const J *child)
 
 N_CJSON_PUBLIC(J *) JCreateRaw(const char *raw)
 {
-    J *item = _jNew_Item();
+    J *item;
+    size_t len;
+
+    if (raw == NULL) {
+        return NULL;
+    }
+
+    len = strlen(raw) + 1;
+    item = _j_new_item_sized(_j_size_for(true, len, 0));
     if(item) {
         item->type = JRaw;
-        item->valuestring = (char*)_j_strdup((const unsigned char*)raw);
-        if(!item->valuestring) {
+        if (!_j_valuestring_set(item, raw, true)) {
             JDelete(item);
             return NULL;
         }
@@ -2564,24 +3308,50 @@ N_CJSON_PUBLIC(J *) JDuplicate(const J *item, Jbool recurse)
     if (!item) {
         goto fail;
     }
-    /* Create new item */
-    newitem = _jNew_Item();
+    /* Create new item, reserving room for a value string too long to inline so
+     * the duplicate packs exactly as a freshly constructed node would. */
+    newitem = _j_new_item_sized(
+                  _j_size_for(item->valuestring != NULL,
+                              item->valuestring != NULL ? strlen(item->valuestring) + 1 : 0,
+                              item->string != NULL ? strlen(item->string) + 1 : 0));
     if (!newitem) {
         goto fail;
     }
-    /* Copy over all vars */
-    newitem->type = item->type & (~JIsReference);
-    newitem->valueint = item->valueint;
-    newitem->valuenumber = item->valuenumber;
+    /* Copy over all vars.
+     *
+     * Guarded on whether the source's numeric members currently hold numbers,
+     * not on its base type. A JString node can carry live numeric state -- a
+     * setter writes it without changing the type -- and the historical
+     * JDuplicate copied it. Keying this on the type silently dropped it, in the
+     * default layout too. When the source is lending those bytes to an inline
+     * value or key there is no number to copy, and the value is reinstated
+     * below anyway. */
+    newitem->type = (uint16_t)(item->type & ~(JIsReference | JStringIsConst | JValueInline | JKeyInline));
+    if (_jNumericIsLive(item)) {
+        newitem->valueint = item->valueint;
+        newitem->valuenumber = item->valuenumber;
+    }
     if (item->valuestring) {
-        newitem->valuestring = (char*)_j_strdup((unsigned char*)item->valuestring);
-        if (!newitem->valuestring) {
+        /* Inline the copy only if the SOURCE's value was inline. A string
+         * node whose value has been evacuated to the heap has live numeric
+         * members -- that is what a setter leaves behind -- and those share
+         * bytes with the inline region. Inlining here would overwrite the
+         * numbers copied just above with the value's characters, which is
+         * how the duplicate ended up with a garbage valueint. Preserving
+         * the source's arrangement keeps both, and costs nothing: a source
+         * whose value is inline still produces an inline copy. */
+        if (!_j_valuestring_set(newitem, item->valuestring,
+                                (item->type & JValueInline) != 0)) {
             goto fail;
         }
     }
     if (item->string) {
-        newitem->string = (item->type&JStringIsConst) ? item->string : (char*)_j_strdup((unsigned char*)item->string);
-        if (!newitem->string) {
+        /* Always materialize an independent key rather than sharing the
+         * source's pointer when JStringIsConst is set. That flag also covers
+         * keys living inside the SOURCE node's allocation (JKeyInline), so
+         * sharing would leave the duplicate dangling once the source is freed.
+         * This mirrors what this function has always done for valuestring. */
+        if (!_j_key_set(newitem, item->string, false)) {
             goto fail;
         }
     }
diff --git a/n_cjson.h b/n_cjson.h
index 6e85e958..f929d261 100644
--- a/n_cjson.h
+++ b/n_cjson.h
@@ -54,6 +54,7 @@ extern "C"
 #define N_CJSON_VERSION_PATCH 7
 
 #include <stddef.h>
+#include <stdint.h>   /* uint16_t, for the packed J layout */
 
 /* J Types: */
 #define JInvalid (0)
@@ -67,14 +68,112 @@ extern "C"
 #define JRaw    (1 << 7) /* raw json */
 
 #define JIsReference 256
+/* Set when valuestring points into this node's own allocation, so JDelete must
+ * not free it separately. Distinct from JIsReference, which also governs whether
+ * JDelete recurses into child. */
+#define JValueInline 1024
+
+/* Largest total allocation a single packed node may have.
+ *
+ * A node records its own allocation size in `objlen`, a uint16_t, so the packing
+ * logic can tell how much inline room is left after a mutation. A node whose key
+ * and value would push it past this bound keeps both on the heap and is
+ * allocated at exactly sizeof(J), which bounds objlen by construction. A string
+ * that large needs its own allocation regardless. */
+#define J_MAX_PACKED_ALLOC 50000
 #define JStringIsConst 512
 
+/* Set when `string` (the key) points into this node's own allocation, as
+ * opposed to a caller-owned buffer. Always accompanied by JStringIsConst, which
+ * keeps its historical "do not free the key" meaning; this says WHERE the key
+ * lives, which JStringIsConst alone cannot distinguish.
+ *
+ * The distinction is not cosmetic. Deciding "is this key inside my allocation?"
+ * by comparing `item->string` against the node's address is only meaningful
+ * when both pointers are already known to address the same object -- relational
+ * comparison of pointers into different objects is undefined in C, and a
+ * caller-owned key is very often a string literal in a different segment
+ * entirely. Recording the answer at the moment the key is placed, when it is
+ * known for free, removes the question.
+ *
+ * Only ever set under NOTE_C_STORAGE_OPTIMIZATION; the historical layout never
+ * stores a key inside the node. Defined unconditionally so the shared code that
+ * masks flags does not need a conditional. */
+#define JKeyInline 2048
+
+/* Set when valueint/valuenumber on a JString or JRaw node genuinely hold
+ * numbers, because a setter put them there.
+ *
+ * A string node's numeric bytes are normally lending themselves to inline
+ * content, but `JSetIntValue`/`JSetNumberValue` have always been able to write
+ * numbers onto a string node without changing its type. Both states exist and
+ * the base type cannot tell them apart, so the fact is recorded here.
+ *
+ * Inferring it instead -- "no inline pointer currently occupies the region,
+ * therefore it holds numbers" -- is unsound in both directions, and an earlier
+ * revision was wrong in both:
+ *
+ *   FALSE POSITIVE. _create_reference() copies a source node's bytes verbatim
+ *   and then clears the inline ownership flags, because the reference borrows
+ *   rather than owns. The copied CHARACTERS remain in the numeric region with
+ *   no flag pointing at them, so a reference to JCreateString("abc") reported
+ *   JIntValue() == 6513249 -- the bytes of "abc" read as an integer.
+ *
+ *   DESTRUCTION. After a setter evacuates the region and writes a number, the
+ *   region looks unoccupied again, so _j_key_set() would reclaim it for a short
+ *   key and silently overwrite the number that was just stored.
+ *
+ * With the fact recorded, the region is off limits to inline placement while
+ * the flag is set, and the accessors read it only while it is set.
+ *
+ * Only ever set under NOTE_C_STORAGE_OPTIMIZATION. In the historical layout the
+ * members are never overlaid, so nothing needs recording -- and setting a new
+ * bit there would change the value a consumer reads from `item->type`. */
+#define JNumericLive 4096
+
+/* NOTE_C_STORAGE_OPTIMIZATION selects the memory-optimized `J` storage model.
+ *
+ * By default `J` has the historical layout: a 48-byte node on a 32-bit target,
+ * whose key and string value always live in separate heap allocations. Defining
+ * NOTE_C_STORAGE_OPTIMIZATION, or setting the CMake option of the same name,
+ * selects a 40-byte node that carves an object member's key and short string
+ * value out of the node's own allocation, so a short string member costs one
+ * allocation instead of three.
+ *
+ * Both produce byte-identical JSON. On a representative corpus the optimization
+ * removes roughly 38% of the allocations and 26% of the heap a parsed document
+ * holds at double precision, and 38%/16% at single precision, where a float
+ * JNUMBER already removes the historical layout's tail padding.
+ *
+ * IMPORTANT: this changes sizeof(J) AND the offset and width of nearly every
+ * member. Every translation unit that sees `J` must be compiled with the same
+ * setting -- the note-c sources and the consumer's sources alike -- exactly as
+ * NOTE_C_SINGLE_PRECISION must be. The CMake option propagates it PUBLIC for
+ * that reason. See docs/architecture/decisions/0002-j-node-storage-layout.md
+ * for the full contract, including the fields whose observable content
+ * changes. */
+
 /*!
  @brief The core JSON object type used by note-c.
 
  When using note-c, treat this struct as opaque. You should never have to work
  directly with its members.
+
+ A note on two long-standing member names, which are NOT being renamed because
+ `J` is a public type and downstream code reads these fields directly:
+
+ - `string` is the object member KEY, never a value. It is NULL for array
+   elements and for a root item. `JGetItemName()` is the accessor.
+ - `valuestring` is the value, for `JString` and `JRaw` items.
+ - The flag guarding `string` is spelled `JStringIsConst`, but what it actually
+   means is "the key is not separately allocated, so do not free it". Read it as
+   JKeyIsConst.
  */
+#ifndef NOTE_C_STORAGE_OPTIMIZATION
+
+/* The historical layout, and the default. Every member keeps the offset, width
+ * and meaning it has had since note-c 2.x, and a key or string value always
+ * occupies its own heap allocation. */
 typedef struct J {
     /* next/prev allow you to walk array/object chains. Alternatively, use GetArraySize/GetArrayItem/GetObjectItem */
     struct J *next;
@@ -95,6 +194,110 @@ typedef struct J {
     char *string;
 } J;
 
+#else /* NOTE_C_STORAGE_OPTIMIZATION */
+
+typedef struct J {
+    /* MEMBER ORDER IS LOAD-BEARING. JINTEGER and JNUMBER require 8-byte
+     * alignment even where pointers are 4 bytes, so placing them last lets the
+     * six 4-byte members pack into offsets 0..23 and the struct end exactly on
+     * 40. Any other order costs 8 bytes of padding.
+     *
+     * INLINE STORAGE. valueint and valuenumber are meaningless for a JString or
+     * JRaw item, so for those items the bytes they occupy hold the value string
+     * and then the key instead, and the allocation is extended past the struct
+     * only as far as the content needs:
+     *
+     *   string item : alloc = MAX(sizeof(J), offsetof(J, valueint)
+     *                                        + strlen(value)+1 + strlen(key)+1)
+     *                 laid out [value NUL][key NUL] from offsetof(J, valueint)
+     *   other item  : alloc = sizeof(J) + strlen(key)+1
+     *                 laid out [key NUL] from sizeof(J)
+     *
+     * So a short string member -- node, key and value together -- is ONE
+     * allocation. Inline storage is an optimization, never a mode: any content
+     * may live inline or in its own block, JValueInline and JStringIsConst say
+     * which, and a setter that no longer fits or that needs the numeric members
+     * back moves the affected content out to the heap first. The address of the
+     * J itself never changes. */
+
+    /* next/prev allow you to walk array/object chains. Alternatively, use GetArraySize/GetArrayItem/GetObjectItem */
+    struct J *next;
+    struct J *prev;
+    /* An array or object item will have a child pointer pointing to a chain of the items in the array/object. */
+    struct J *child;
+
+    /* The item's string, if type==JString and type == JRaw. May point into this
+     * node's own allocation (JValueInline), at a caller-owned buffer
+     * (JIsReference), or at a separate heap block (neither flag). */
+    char *valuestring;
+    /* The item's name string, if this item is the child of, or is in the list of subitems of an object.
+     * May point into this node's own allocation or at a caller-owned buffer
+     * (JStringIsConst either way), or at a separate heap block. */
+    char *string;
+
+    /* The type of the item, as above. Narrowed from int to uint16_t: the base
+     * types occupy 8 bits and the three flags reach 1024, so 16 bits is ample. */
+    uint16_t type;
+    /* Total bytes allocated for this node, including any inline storage past
+     * the struct. Bounded by J_MAX_PACKED_ALLOC so it always fits. */
+    uint16_t objlen;
+
+    /* ===================================================================
+     * THE NUMERIC PAIR IS ALSO THE INLINE CHARACTER BUFFER. READ THIS.
+     * ===================================================================
+     *
+     * For a JString or JRaw item these two members are meaningless, so the
+     * bytes they occupy are used to hold the item's value string and then its
+     * key. Conceptually the declaration is this union:
+     *
+     *     union {
+     *         char kvbuf[sizeof(JINTEGER) + sizeof(JNUMBER)];
+     *         struct {
+     *             JINTEGER valueint;
+     *             JNUMBER  valuenumber;
+     *         };
+     *     };
+     *
+     * It is NOT written that way, deliberately. An anonymous struct inside a
+     * union is standard only from C11; in C89, C99 and every C++ standard it is
+     * a compiler extension, and under -pedantic-errors it is a hard error
+     * rather than a warning. note-c pins no C standard, compiles with
+     * -Wpedantic, and is parsed by C++ consumers such as note-arduino, so the
+     * union form would make the header unbuildable on toolchains this library
+     * is expected to work on. The members are therefore declared plainly and
+     * the overlay is expressed in code instead.
+     *
+     * The overlay is addressed as (char *)item + offsetof(J, valueint), never
+     * as sizeof(J) minus a constant, so nothing depends on these members
+     * happening to be last. n_cjson.c carries a compile-time assertion that
+     * they are contiguous and do run to the end of the struct; a reorder that
+     * broke either property fails the build rather than corrupting nodes.
+     *
+     * Byte layout of a node on a 32-bit target (sizeof(J) == 40):
+     *
+     *     offset  0   4    8      12           16      20    22    24    32  40
+     *            +----+----+------+------------+-------+-----+-----+-----+----+
+     *            |next|prev|child |valuestring |string |type |objln|valueint |
+     *            |    |    |      |            |       |     |     |valuenum |
+     *            +----+----+------+------------+-------+-----+-----+-----+----+
+     *     JString item:                                       [value\0][key\0]
+     *                                                         ^ offsetof(valueint)
+     *                                                         ...extending past 40
+     *                                                         if the two need more
+     *     other item:  valueint/valuenumber live here          [key\0] from 40 on
+     *
+     * The two are never used at once: kvbuf bytes are only written when the
+     * item is a string type, and valueint/valuenumber are only read when it is
+     * not. _j_is_string_type() gates that internally; JIntValue() and
+     * JNumberValue() enforce it for callers. Accessing the bytes through a char
+     * pointer is explicitly permitted by the aliasing rules of both C and C++.
+     */
+    JINTEGER valueint;
+    JNUMBER valuenumber;
+} J;
+
+#endif /* NOTE_C_STORAGE_OPTIMIZATION */
+
 typedef struct JHooks {
     void *(*malloc_fn)(size_t sz);
     void (*free_fn)(void *ptr);
@@ -310,13 +513,55 @@ N_CJSON_PUBLIC(J*) JAddArrayToObject(J * const object, const char * const name);
 #define JConvertToJSONString JPrintUnformatted
 #define JConvertFromJSONString JParse
 
-/* When assigning an integer value, it needs to be propagated to valuenumber too. */
-#define JSetIntValue(object, number) ((object) ? (object)->valueint = (object)->valuenumber = (number) : (number))
-/* helper for the JSetNumberValue macro */
+/* Assign an item's numeric value.
+ *
+ * Both macro names are retained and both keep their historical behavior: the
+ * value is written to valueint AND valuenumber, `number` is evaluated exactly
+ * once, and a NULL object is a no-op that returns the operand. The macros now
+ * expand to a call rather than to an assignment reaching into the struct.
+ *
+ * The outer conditional is retained deliberately, even though both helpers
+ * handle a NULL object themselves. It is what preserves the NULL branch's
+ * VALUE and TYPE: historically that branch was the unconverted `(number)`
+ * operand, so `JSetIntValue(NULL, 1.5)` yielded 1.5 as a double. Calling a
+ * helper unconditionally would yield 1 as a JINTEGER -- and under
+ * NOTE_C_SINGLE_PRECISION would round the operand through a float on the way
+ * out. Letting the conditional pick the common type reproduces both exactly.
+ *
+ * JSetNumberValue was already a call. JSetIntValue was
+ *
+ *     ((object) ? (object)->valueint = (object)->valuenumber = (number) : (number))
+ *
+ * which wrote two members directly from the caller's translation unit. Under
+ * NOTE_C_STORAGE_OPTIMIZATION those bytes may hold a packed key or string
+ * value, so writing them from outside the library would corrupt the node with
+ * no way for the library to intervene. Routing through a function lets the
+ * library evacuate that content first.
+ *
+ * `object` is evaluated TWICE: once by the conditional, once by the call. The
+ * historical JSetIntValue evaluated it three times, so that is a change from
+ * three to two; the historical JSetNumberValue already evaluated it twice, so
+ * it is unchanged. `number` was never repeated and still is not.
+ *
+ * JSetIntHelper takes JNUMBER on purpose. The old macro parsed as
+ * `valueint = (valuenumber = number)`, so both members saw the operand in its
+ * original arithmetic form: JSetIntValue(item, 1.5) left valueint == 1 and
+ * valuenumber == 1.5. A JINTEGER parameter would truncate at the call site and
+ * store 1 in both.
+ *
+ * Both propagate to the sibling member, because valueint and valuenumber must
+ * stay in step: valueint carries integers that valuenumber cannot represent
+ * exactly (the parser converts the original text with JAtoI, so values beyond
+ * 2^53 are exact in valueint and lossy in valuenumber), and _print_number
+ * compares the two to decide integer-vs-float rendering. */
 N_CJSON_PUBLIC(JNUMBER) JSetNumberHelper(J *object, JNUMBER number);
-#define JSetNumberValue(object, number) ((object != NULL) ? JSetNumberHelper(object, (JNUMBER)number) : (number))
+N_CJSON_PUBLIC(JINTEGER) JSetIntHelper(J *object, JNUMBER number);
+#define JSetIntValue(object, number) ((object) ? JSetIntHelper((object), (JNUMBER)(number)) : (number))
+#define JSetNumberValue(object, number) ((object) ? JSetNumberHelper((object), (JNUMBER)(number)) : (number))
 
-/* Macro for iterating over an array or object */
+/* Macro for iterating over an array or object. These read child/next rather
+ * than writing a member, so unlike the setters above they carry no aliasing or
+ * storage-layout hazard, and a for-loop cannot be expressed as a function. */
 #define JArrayForEach(element, array) for(element = (array != NULL) ? (array)->child : NULL; element != NULL; element = element->next)
 // Iterate over the fields of an object
 #define JObjectForEach(element, array) JArrayForEach(element, array)
diff --git a/n_cjson_helpers.c b/n_cjson_helpers.c
index 1c744188..cb8835bb 100644
--- a/n_cjson_helpers.c
+++ b/n_cjson_helpers.c
@@ -90,7 +90,18 @@ char *JStringValue(J *item)
 
 JNUMBER JNumberValue(J *item)
 {
-    if (item == NULL) {
+    // Guarded on whether the numeric members currently hold numbers, NOT on the
+    // node's base type. Under NOTE_C_STORAGE_OPTIMIZATION a JString/JRaw node
+    // may be lending those bytes to an inline value or key, and reading them as
+    // a number would return character data.
+    //
+    // But a string node whose content is on the heap has genuinely live numeric
+    // members, and JSetIntValue/JSetNumberValue have always been able to put
+    // numbers there without changing the node's type. Keying this on the type
+    // made that state unreadable -- including in the default layout, where
+    // nothing is ever overlaid. _jNumericIsLive() is unconditionally true
+    // there, so the historical behavior is exact.
+    if (!_jNumericIsLive(item)) {
         return 0.0;
     }
     return item->valuenumber;
@@ -113,7 +124,8 @@ JNUMBER JGetNumber(J *json, const char *field)
 
 JINTEGER JIntValue(J *item)
 {
-    if (item == NULL) {
+    // See JNumberValue() above.
+    if (!_jNumericIsLive(item)) {
         return 0;
     }
     return item->valueint;
diff --git a/n_lib.h b/n_lib.h
index 618cc8e1..4dcd473d 100644
--- a/n_lib.h
+++ b/n_lib.h
@@ -117,6 +117,17 @@ extern uint32_t cardTransactionTimeoutOverrideSecs;
 #define NOTE_DISABLE_USER_AGENT
 #endif // NOTE_C_LOW_MEM
 
+// JSON node storage
+//
+// True when this node's valueint/valuenumber hold the numbers they appear to
+// hold, rather than packed character data. Always true in the default layout;
+// under NOTE_C_STORAGE_OPTIMIZATION it is false only while an inline value or
+// key is actually occupying those bytes. Callers outside n_cjson.c need it
+// because the answer is not derivable from the node's base type: a JString node
+// whose value has been evacuated to the heap has live numeric members, which is
+// exactly what JSetIntValue/JSetNumberValue leave behind.
+bool _jNumericIsLive(const J * const item);
+
 // Transactions
 void _noteResumeTransactionDebug(void);
 void _noteSuspendTransactionDebug(void);
diff --git a/note.h b/note.h
index 11d9a80f..37d0f14b 100644
--- a/note.h
+++ b/note.h
@@ -630,6 +630,8 @@ void NoteSetFnNoteMutex(mutexFn lockFn, mutexFn unlockFn);
        interested in that particular function pointer.
  */
 void NoteGetFnNoteMutex(mutexFn *lockFn, mutexFn *unlockFn);
+
+
 /*!
  @brief Set the default system functions (memory allocation, delay, timing).
 
@@ -1437,6 +1439,16 @@ int JGetItemType(J *item);
  @returns The base type code.
  */
 int JBaseItemType(int type);
+/* The object member key, as a mutable `char *` that is NULL when the item has
+ * no key.
+ *
+ * Left as a direct member read, unlike the JSetValue macros. Those had to
+ * become calls because they WRITE bytes that NOTE_C_STORAGE_OPTIMIZATION may be
+ * using for packed storage; this only READS a pointer member that means the
+ * same thing and holds the same value in either layout. Routing it through
+ * JGetItemName() would change the result type to `const char *` and substitute
+ * "" for NULL, breaking `char *name = JGetObjectItemName(item);` and every
+ * caller that tests the result against NULL. */
 #define JGetObjectItemName(j) (j->string)
 
 // Helper functions for apps that wish to limit their C library dependencies
diff --git a/scripts/generate_corpus_golden.sh b/scripts/generate_corpus_golden.sh
new file mode 100755
index 00000000..ceabc3a3
--- /dev/null
+++ b/scripts/generate_corpus_golden.sh
@@ -0,0 +1,144 @@
+#!/bin/bash
+#
+# Record what the HISTORICAL implementation renders for every corpus document,
+# and check the result in as test/data/.
+#
+# WHY THIS EXISTS. The layout suite builds the library twice and diffs the two
+# runs. That proves the two layouts agree with EACH OTHER -- it cannot prove
+# either agrees with the note-c that shipped, because both builds run the same
+# rewritten parser, printer and setters. Any regression they share is invisible
+# to a comparison between them.
+#
+# So the reference has to come from outside the working tree. This script
+# extracts a pristine `git archive HEAD` (or any revision named on the command
+# line), compiles the corpus against THAT source, and records its output. The
+# layout suite then compares against the recorded file, which is a claim about
+# the released behavior rather than about the rewrite's self-consistency.
+#
+# The generator deliberately links nothing from the working tree except
+# test/include/j_corpus.hpp, which is why that header is kept free of Catch2 and
+# of anything newer than the public API.
+#
+# Usage: scripts/generate_corpus_golden.sh [revision]     (default: HEAD)
+#
+set -euo pipefail
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+ROOT_DIR="$SCRIPT_DIR/.."
+cd "$ROOT_DIR"
+
+REV="${1:-HEAD}"
+OUT_DIR="$ROOT_DIR/test/data"
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+REV_SHA=$(git rev-parse --short "$REV")
+echo "==> extracting $REV ($REV_SHA)"
+git archive "$REV" | tar -x -C "$WORK"
+
+# The corpus header comes from the WORKING TREE, the library from the archive.
+cp test/include/j_corpus.hpp "$WORK/"
+
+cat > "$WORK/gen.cpp" <<'EOF'
+// Renders every (document, mode) pair and writes one TSV row each.
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "j_corpus.hpp"
+
+using namespace jlayout;
+
+int main(int argc, char **argv)
+{
+    if (argc < 2) {
+        fprintf(stderr, "usage: gen <output>\n");
+        return 2;
+    }
+    FILE *f = fopen(argv[1], "w");
+    if (f == NULL) {
+        return 2;
+    }
+
+    NoteSetFn(malloc, free, NULL, NULL);
+
+    fprintf(f, "# Rendered by the historical note-c implementation.\n");
+    fprintf(f, "# Regenerate with scripts/generate_corpus_golden.sh -- do not hand-edit.\n");
+    fprintf(f, "# revision\t%s\n", getenv("GOLDEN_REV") ? getenv("GOLDEN_REV") : "?");
+    fprintf(f, "# precision\t%s\n",
+#ifdef NOTE_C_SINGLE_PRECISION
+            "single"
+#else
+            "double"
+#endif
+           );
+    fprintf(f, "#doc\tmode\toutput\n");
+
+    const std::vector<Doc> &docs = corpus();
+    const std::vector<Mode> &ms = modes();
+    for (size_t d = 0; d < docs.size(); ++d) {
+        J *parsed = JParse(docs[d].json);
+        if (parsed == NULL) {
+            fprintf(stderr, "FATAL: %s did not parse\n", docs[d].name);
+            return 1;
+        }
+        for (size_t m = 0; m < ms.size(); ++m) {
+            char *out = (char *)_print(parsed, ms[m].format, ms[m].omitempty);
+            if (out == NULL) {
+                fprintf(stderr, "FATAL: %s/%s did not print\n", docs[d].name, ms[m].name);
+                return 1;
+            }
+            // Escape so one row stays one line.
+            fprintf(f, "%s\t%s\t", docs[d].name, ms[m].name);
+            for (const char *p = out; *p; ++p) {
+                if (*p == '\n') {
+                    fputs("\\n", f);
+                } else if (*p == '\t') {
+                    fputs("\\t", f);
+                } else if (*p == '\\') {
+                    fputs("\\\\", f);
+                } else {
+                    fputc(*p, f);
+                }
+            }
+            fputc('\n', f);
+            JFree(out);
+        }
+        JDelete(parsed);
+    }
+
+    fclose(f);
+    return 0;
+}
+EOF
+
+# n_str.c only compiles when the platform lacks strlcpy/strlcat, and we define
+# both below, exactly as CMakeLists.txt decides.
+SRC=$(cd "$WORK" && ls n_*.c | grep -v '^n_str\.c$' | tr '\n' ' ')
+mkdir -p "$OUT_DIR"
+
+build_one() {
+    local label="$1" out="$2" extra="${3:-}"
+    echo "==> building generator against $REV_SHA ($label)"
+    # The library is compiled as C and the generator as C++, exactly as the
+    # CMake test build does. NOTE_C_TEST empties NOTE_C_STATIC so the generator
+    # can reach _print, which is the same entry point the layout suite renders
+    # through.
+    (cd "$WORK" \
+        && rm -f ./*.o \
+        && cc -std=c99 -O1 -I. -DNOTE_C_TEST -DHAVE_STRLCPY -DHAVE_STRLCAT $extra \
+              -c $SRC \
+        && c++ -std=c++14 -O1 -I. -DNOTE_C_TEST -DHAVE_STRLCPY -DHAVE_STRLCAT $extra \
+               gen.cpp ./*.o -o gen) > "$WORK/build.log" 2>&1 || {
+        echo "generator build failed:"; grep -m10 "error:" "$WORK/build.log"; exit 1;
+    }
+    echo "==> recording $label -> $out"
+    GOLDEN_REV="$REV_SHA" "$WORK/gen" "$out"
+    echo "    $(grep -vc '^#' "$out") rows"
+}
+
+build_one "default precision" "$OUT_DIR/corpus_golden.tsv"
+build_one "single precision"  "$OUT_DIR/corpus_golden_single.tsv" "-DNOTE_C_SINGLE_PRECISION"
+
+echo
+echo "Goldens written to test/data/. Review the diff before committing:"
+echo "    git diff --stat test/data/"
diff --git a/scripts/run_ab_layout_comparison.sh b/scripts/run_ab_layout_comparison.sh
new file mode 100755
index 00000000..6ef80be4
--- /dev/null
+++ b/scripts/run_ab_layout_comparison.sh
@@ -0,0 +1,191 @@
+#!/bin/bash
+#
+# Build the JLayout suite in both J layouts, prove they render identically, and
+# tabulate the memory difference.
+#
+# The historical layout is the default; NOTE_C_STORAGE_OPTIMIZATION selects the
+# packed one. Because `J` is a single type selected at compile time, the two
+# layouts cannot coexist in one binary, so the A/B comparison spans two builds:
+#
+#   - The output column of every (document, mode) row must be byte-identical.
+#     Any difference is a correctness failure, not a tuning result.
+#   - The allocation and byte columns are the measurement.
+#
+# Precision is crossed in because it is not independent of layout. JNUMBER is a
+# float under NOTE_C_SINGLE_PRECISION, which shrinks the historical node too --
+# on a 32-bit target sizeof(J) is 40 in BOTH layouts there, so the member
+# reorder contributes nothing and the entire win comes from inline packing.
+# Reporting one set of numbers without saying which precision produced them
+# overstates the saving for single-precision targets.
+#
+# Usage: scripts/run_ab_layout_comparison.sh [--keep] [--single-precision]
+#
+set -euo pipefail
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+ROOT_DIR="$SCRIPT_DIR/.."
+cd "$ROOT_DIR"
+
+KEEP=0
+SINGLE=0
+for arg in "$@"; do
+    case "$arg" in
+        --keep) KEEP=1 ;;
+        --single-precision) SINGLE=1 ;;
+        *) echo "unknown argument: $arg" >&2; exit 2 ;;
+    esac
+done
+
+PRECISION_LABEL="double"
+PRECISION_OPT=OFF
+if [[ $SINGLE -eq 1 ]]; then
+    PRECISION_LABEL="single"
+    PRECISION_OPT=ON
+fi
+
+PACKED_BUILD="$ROOT_DIR/build-ab-packed"
+UNPACKED_BUILD="$ROOT_DIR/build-ab-unpacked"
+PACKED_REPORT="$ROOT_DIR/build-ab-packed.tsv"
+UNPACKED_REPORT="$ROOT_DIR/build-ab-unpacked.tsv"
+
+cleanup() {
+    if [[ $KEEP -eq 0 ]]; then
+        rm -rf "$PACKED_BUILD" "$UNPACKED_BUILD"
+    fi
+}
+trap cleanup EXIT
+
+build_and_run() {
+    local dir="$1" report="$2" optimized="$3" label="$4"
+    echo "==> building $label"
+    # Use the CMake option, not raw CMAKE_C_FLAGS, so this exercises the same
+    # PUBLIC propagation path a real consumer gets.
+    cmake -B "$dir" -DNOTE_C_BUILD_TESTS:BOOL=ON \
+        -DNOTE_C_STORAGE_OPTIMIZATION:BOOL="$optimized" \
+        -DNOTE_C_SINGLE_PRECISION:BOOL="$PRECISION_OPT" > /dev/null
+    cmake --build "$dir" --target JLayout_test -- -j > /dev/null
+    echo "==> running $label"
+    J_LAYOUT_REPORT="$report" "$dir/test/JLayout_test"
+}
+
+echo "==> precision: $PRECISION_LABEL"
+build_and_run "$PACKED_BUILD"   "$PACKED_REPORT"   ON  "packed (NOTE_C_STORAGE_OPTIMIZATION)"
+build_and_run "$UNPACKED_BUILD" "$UNPACKED_REPORT" OFF "historical layout (default)"
+
+echo
+echo "==> verifying both layouts render identically"
+if diff <(grep -v '^#\|^@' "$PACKED_REPORT"   | cut -f1,2,11) \
+        <(grep -v '^#\|^@' "$UNPACKED_REPORT" | cut -f1,2,11) > /dev/null; then
+    echo "    OK: every document renders byte-for-byte the same in both layouts"
+else
+    echo "    FAIL: the layouts disagree on rendered output:"
+    diff <(grep -v '^#\|^@' "$PACKED_REPORT"   | cut -f1,2,11) \
+         <(grep -v '^#\|^@' "$UNPACKED_REPORT" | cut -f1,2,11) | head -40
+    exit 1
+fi
+
+echo
+J_AB_PRECISION="$PRECISION_LABEL" python3 - "$PACKED_REPORT" "$UNPACKED_REPORT" <<'PYEOF'
+import os, sys
+
+def load(path):
+    rows, meta = {}, {}
+    for line in open(path):
+        line = line.rstrip("\n")
+        if line.startswith("#"):
+            if "sizeof_J=" in line:
+                for tok in line.lstrip("# ").split():
+                    if "=" in tok:
+                        k, v = tok.split("=", 1)
+                        meta[k] = v
+            continue
+        if line.startswith("@"):
+            continue
+        f = line.split("\t")
+        # allocs, hostbytes, nodes, textlen, raw32, dlmalloc, freertos, nano
+        rows[(f[0], f[1])] = tuple(int(x) for x in f[2:10])
+    return rows, meta
+
+pk, pm = load(sys.argv[1])
+uk, um = load(sys.argv[2])
+
+docs = [d for (d, m) in sorted(uk) if m == "compact"]
+
+def col(rows, d, i):
+    return rows[(d, "compact")][i]
+
+ALLOCS, HOSTB, NODES, TEXT, RAW32, DL, RTOS, NANO = range(8)
+
+print("=" * 108)
+PRECISION = os.environ.get("J_AB_PRECISION", "double")
+print(f"J LAYOUT A/B  --  heap held by a parsed document, 32-bit target, {PRECISION} precision")
+print("=" * 108)
+print("Allocator models (all 32-bit):")
+print("  raw       bytes as requested; no allocator overhead at all")
+print("  dlmalloc  newlib full malloc: 4B chunk header, 8B align, 16B minimum")
+print("  heap_4    FreeRTOS heap_4: 8B BlockLink_t header, 8B align")
+print("  nano      newlib nano-malloc: 4B header, 8B align, 8B minimum")
+print()
+hdr = (f"{'document':<22}{'text':>5}{'node':>5}{'alloc':>6}"
+       f"{'raw u':>8}{'raw p':>7}{'':>5}"
+       f"{'dlm u':>8}{'dlm p':>7}{'save':>6}"
+       f"{'rtos u':>8}{'rtos p':>7}{'save':>6}"
+       f"{'nano u':>8}{'nano p':>7}{'save':>6}")
+print(hdr)
+print("-" * 108)
+
+tot = {k: [0, 0] for k in ("raw", "dl", "rtos", "nano", "alloc")}
+ttext = 0
+for d in docs:
+    ttext += col(uk, d, TEXT)
+    vals = {}
+    for key, idx in (("raw", RAW32), ("dl", DL), ("rtos", RTOS), ("nano", NANO)):
+        u, p = col(uk, d, idx), col(pk, d, idx)
+        tot[key][0] += u
+        tot[key][1] += p
+        vals[key] = (u, p, (100.0 * (u - p) / u) if u else 0.0)
+    tot["alloc"][0] += col(uk, d, ALLOCS)
+    tot["alloc"][1] += col(pk, d, ALLOCS)
+    print(f"{d:<22}{col(uk,d,TEXT):>5}{col(uk,d,NODES):>5}"
+          f"{col(uk,d,ALLOCS):>3}/{col(pk,d,ALLOCS):<2}"
+          f"{vals['raw'][0]:>8}{vals['raw'][1]:>7}{'':>5}"
+          f"{vals['dl'][0]:>8}{vals['dl'][1]:>7}{vals['dl'][2]:>5.0f}%"
+          f"{vals['rtos'][0]:>8}{vals['rtos'][1]:>7}{vals['rtos'][2]:>5.0f}%"
+          f"{vals['nano'][0]:>8}{vals['nano'][1]:>7}{vals['nano'][2]:>5.0f}%")
+
+print("-" * 108)
+def pct(k):
+    u, p = tot[k]
+    return (100.0 * (u - p) / u) if u else 0.0
+print(f"{'TOTAL':<22}{ttext:>5}{'':>5}"
+      f"{tot['alloc'][0]:>3}/{tot['alloc'][1]:<2}"
+      f"{tot['raw'][0]:>8}{tot['raw'][1]:>7}{'':>5}"
+      f"{tot['dl'][0]:>8}{tot['dl'][1]:>7}{pct('dl'):>5.0f}%"
+      f"{tot['rtos'][0]:>8}{tot['rtos'][1]:>7}{pct('rtos'):>5.0f}%"
+      f"{tot['nano'][0]:>8}{tot['nano'][1]:>7}{pct('nano'):>5.0f}%")
+print()
+print("=" * 108)
+print(f"SUMMARY (32-bit target, {PRECISION} precision)")
+print("=" * 108)
+SZ = ("48", "40") if PRECISION == "double" else ("40", "40")
+print(f"  sizeof(J):        historical {SZ[0]}  ->  optimized {SZ[1]}")
+if PRECISION != "double":
+    print("                    (identical: a float JNUMBER already removes the")
+    print("                     padding, so the whole saving here comes from")
+    print("                     inline packing rather than the member reorder)")
+au, ap = tot["alloc"]
+print(f"  allocations:      {au:>6}  ->  {ap:>6}   ({100.0*(au-ap)/au:.0f}% fewer)")
+for label, key in (("raw (no overhead)", "raw"), ("newlib dlmalloc", "dl"),
+                   ("FreeRTOS heap_4", "rtos"), ("newlib nano-malloc", "nano")):
+    u, p = tot[key]
+    print(f"  {label:<18}{u:>6}  ->  {p:>6}   ({100.0*(u-p)/u:.0f}% smaller)"
+          f"   [{u/ttext:.1f}x -> {p/ttext:.1f}x the JSON text]")
+print()
+print("  The raw column is the floor. A real allocator's per-chunk header and")
+print("  rounding amplify the win, because the packed layout removes whole")
+print("  allocations rather than just shrinking them.")
+PYEOF
+
+if [[ $KEEP -eq 0 ]]; then
+    rm -f "$PACKED_REPORT" "$UNPACKED_REPORT"
+fi
diff --git a/scripts/run_unit_tests.sh b/scripts/run_unit_tests.sh
index 3bf0ef68..ec17159c 100755
--- a/scripts/run_unit_tests.sh
+++ b/scripts/run_unit_tests.sh
@@ -4,6 +4,7 @@ COVERAGE=0
 HEARTBEAT_CALLBACK=0
 MEM_CHECK=0
 LOW_MEM=0
+STORAGE_OPTIMIZATION=0
 NO_DEBUG=0
 SHOW_MALLOC=0
 SINGLE_PRECISION=0
@@ -15,6 +16,7 @@ while [[ "$#" -gt 0 ]]; do
         --coverage) COVERAGE=1 ;;
         --heartbeat-callback) HEARTBEAT_CALLBACK=1 ;;
         --low-mem) LOW_MEM=1 ;;
+        --storage-optimization) STORAGE_OPTIMIZATION=1 ;;
         --mem-check) MEM_CHECK=1 ;;
         --no-debug) NO_DEBUG=1 ;;
         --show-malloc) SHOW_MALLOC=1 ;;
@@ -49,6 +51,9 @@ fi
 if [[ $LOW_MEM -eq 1 ]]; then
     CMAKE_OPTIONS="${CMAKE_OPTIONS} -DNOTE_C_LOW_MEM:BOOL=ON"
 fi
+if [[ $STORAGE_OPTIMIZATION -eq 1 ]]; then
+    CMAKE_OPTIONS="${CMAKE_OPTIONS} -DNOTE_C_STORAGE_OPTIMIZATION:BOOL=ON"
+fi
 if [[ $MEM_CHECK -eq 1 ]]; then
     CMAKE_OPTIONS="${CMAKE_OPTIONS} -DNOTE_C_MEM_CHECK:BOOL=ON"
     CTEST_OPTIONS="${CTEST_OPTIONS} -T memcheck"
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index cd306621..b79eb108 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -47,6 +47,11 @@ macro(add_test TEST_NAME)
         PRIVATE -Og
         PRIVATE -ggdb
     )
+    # Where the checked-in goldens live, so a test can read them at runtime
+    # without depending on the working directory ctest happens to use.
+    target_compile_definitions(${TEST_NAME}
+        PRIVATE J_TEST_DATA_DIR="${CMAKE_CURRENT_SOURCE_DIR}/data"
+    )
     if(APPLE)
         # Allow test fakes (FFF) to interpose symbols from the note_c dylib
         target_link_options(${TEST_NAME} PRIVATE -Wl,-flat_namespace)
@@ -112,9 +117,25 @@ add_test(JIsExactString_test)
 add_test(JIsNullString_test)
 add_test(JIsPresent_test)
 add_test(JItoA_test)
+add_test(JLayout_test)
 add_test(JNtoA_test)
 add_test(JNumberValue_test)
 add_test(JPrintUnformatted_test)
+add_test(JPublicApiCompat_test)
+add_test(JReferenceAndFailure_test)
+
+# note-c is a C library, but every test above is a C++ translation unit, so the
+# public J macros would otherwise never be compiled as C. This adds a C source
+# to the compatibility test that exercises them, with -Werror so that binding a
+# const-qualified result to `char *` -- a hard error in C++ but only a warning
+# in C -- fails the build here too.
+target_sources(JPublicApiCompat_test
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/j_public_api_compat_c.c
+)
+set_source_files_properties(
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/j_public_api_compat_c.c
+    PROPERTIES COMPILE_OPTIONS "-Wall;-Wextra;-Werror"
+)
 add_test(JSON_number_handling_test)
 add_test(JStringValue_test)
 add_test(JType_test)
diff --git a/test/README.md b/test/README.md
index 8ecfc4c4..e60d2f90 100644
--- a/test/README.md
+++ b/test/README.md
@@ -113,6 +113,27 @@ basic behavior.
     Some platforms (like AVR) do not provide a 64-bit double precision type.
     On such platforms, `double` is typically implemented as `float`.
 
+- `--storage-optimization`
+
+    Builds and runs the unit-tests with the `NOTE_C_STORAGE_OPTIMIZATION` flag
+    present, selecting the memory-optimized `J` layout. By default `J` uses the
+    historical layout, in which a node is 48 bytes on a 32-bit target and a
+    member's key and string value each take their own heap allocation. With this
+    flag the node is 40 bytes and short keys and values are packed into the
+    node's own allocation, so a short string member costs one allocation instead
+    of three.
+
+    Both layouts are shipped and both must stay green. They must produce
+    byte-identical JSON; `scripts/run_ab_layout_comparison.sh` builds both,
+    proves the outputs match, and tabulates the memory difference. The
+    specification is in
+    `docs/architecture/decisions/0002-j-node-storage-layout.md`.
+
+    > _**NOTE:** this flag changes `sizeof(J)` and the offset of nearly every
+    member, so it must be set identically for the library and for every consumer
+    that includes `note.h` — exactly as `NOTE_C_SINGLE_PRECISION` must be. The
+    CMake option propagates it `PUBLIC` for that reason._
+
 - `--verbose`
 
     Provides comprehensive build logs to assist in test debugging.
@@ -153,6 +174,11 @@ each memory allocation and free (Default: `OFF`).
 - `-DNOTE_C_SINGLE_PRECISION:BOOL=ON`: Runs the unit-tests over code compiled
 with the `NOTE_C_SINGLE_PRECISION` flag enabled. All doubles are treated as
 single precision, which is commonplace on many MCUs (Default: `OFF`).
+- `-DNOTE_C_STORAGE_OPTIMIZATION:BOOL=ON`: Runs the unit-tests over code
+compiled with the `NOTE_C_STORAGE_OPTIMIZATION` flag enabled, selecting the
+memory-optimized `J` layout described above. Like `NOTE_C_SINGLE_PRECISION`
+this changes `sizeof(J)`, so it is propagated `PUBLIC` and must match between
+the library and every consumer (Default: `OFF`).
 - `-DCMAKE_VERBOSE_MAKEFILE:BOOL=ON --log-level=VERBOSE`: Increase the verbosity
 of the build system (Default: `OFF`).
 
diff --git a/test/data/corpus_golden.tsv b/test/data/corpus_golden.tsv
new file mode 100644
index 00000000..534801d7
--- /dev/null
+++ b/test/data/corpus_golden.tsv
@@ -0,0 +1,205 @@
+# Rendered by the historical note-c implementation.
+# Regenerate with scripts/generate_corpus_golden.sh -- do not hand-edit.
+# revision	9a12cfc
+# precision	double
+#doc	mode	output
+null	compact	null
+null	compact-omitempty	null
+null	formatted	null
+null	formatted-omitempty	null
+true	compact	true
+true	compact-omitempty	true
+true	formatted	true
+true	formatted-omitempty	true
+false	compact	false
+false	compact-omitempty	false
+false	formatted	false
+false	formatted-omitempty	false
+zero	compact	0
+zero	compact-omitempty	0
+zero	formatted	0
+zero	formatted-omitempty	0
+negative-int	compact	-12345
+negative-int	compact-omitempty	-12345
+negative-int	formatted	-12345
+negative-int	formatted-omitempty	-12345
+big-int-exact	compact	9007199254740993
+big-int-exact	compact-omitempty	9007199254740993
+big-int-exact	formatted	9007199254740993
+big-int-exact	formatted-omitempty	9007199254740993
+huge-int	compact	1234567890123456789
+huge-int	compact-omitempty	1234567890123456789
+huge-int	formatted	1234567890123456789
+huge-int	formatted-omitempty	1234567890123456789
+fraction	compact	3.25
+fraction	compact-omitempty	3.25
+fraction	formatted	3.25
+fraction	formatted-omitempty	3.25
+negative-fraction	compact	-0.125
+negative-fraction	compact-omitempty	-0.125
+negative-fraction	formatted	-0.125
+negative-fraction	formatted-omitempty	-0.125
+exp-small	compact	1.5e-07
+exp-small	compact-omitempty	1.5e-07
+exp-small	formatted	1.5e-07
+exp-small	formatted-omitempty	1.5e-07
+string-short	compact	"hi"
+string-short	compact-omitempty	"hi"
+string-short	formatted	"hi"
+string-short	formatted-omitempty	"hi"
+string-empty	compact	""
+string-empty	compact-omitempty	""
+string-empty	formatted	""
+string-empty	formatted-omitempty	""
+val-len-14	compact	"abcdefghijklmn"
+val-len-14	compact-omitempty	"abcdefghijklmn"
+val-len-14	formatted	"abcdefghijklmn"
+val-len-14	formatted-omitempty	"abcdefghijklmn"
+val-len-15	compact	"abcdefghijklmno"
+val-len-15	compact-omitempty	"abcdefghijklmno"
+val-len-15	formatted	"abcdefghijklmno"
+val-len-15	formatted-omitempty	"abcdefghijklmno"
+val-len-16	compact	"abcdefghijklmnop"
+val-len-16	compact-omitempty	"abcdefghijklmnop"
+val-len-16	formatted	"abcdefghijklmnop"
+val-len-16	formatted-omitempty	"abcdefghijklmnop"
+val-len-17	compact	"abcdefghijklmnopq"
+val-len-17	compact-omitempty	"abcdefghijklmnopq"
+val-len-17	formatted	"abcdefghijklmnopq"
+val-len-17	formatted-omitempty	"abcdefghijklmnopq"
+val-len-31	compact	"abcdefghijklmnopqrstuvwxyz01234"
+val-len-31	compact-omitempty	"abcdefghijklmnopqrstuvwxyz01234"
+val-len-31	formatted	"abcdefghijklmnopqrstuvwxyz01234"
+val-len-31	formatted-omitempty	"abcdefghijklmnopqrstuvwxyz01234"
+key-len-14	compact	{"abcdefghijklmn":1}
+key-len-14	compact-omitempty	{"abcdefghijklmn":1}
+key-len-14	formatted	{\n    "abcdefghijklmn": 1\n}
+key-len-14	formatted-omitempty	{\n    "abcdefghijklmn": 1\n}
+key-len-15	compact	{"abcdefghijklmno":1}
+key-len-15	compact-omitempty	{"abcdefghijklmno":1}
+key-len-15	formatted	{\n    "abcdefghijklmno": 1\n}
+key-len-15	formatted-omitempty	{\n    "abcdefghijklmno": 1\n}
+key-len-16	compact	{"abcdefghijklmnop":1}
+key-len-16	compact-omitempty	{"abcdefghijklmnop":1}
+key-len-16	formatted	{\n    "abcdefghijklmnop": 1\n}
+key-len-16	formatted-omitempty	{\n    "abcdefghijklmnop": 1\n}
+key-len-17	compact	{"abcdefghijklmnopq":1}
+key-len-17	compact-omitempty	{"abcdefghijklmnopq":1}
+key-len-17	formatted	{\n    "abcdefghijklmnopq": 1\n}
+key-len-17	formatted-omitempty	{\n    "abcdefghijklmnopq": 1\n}
+key-and-val-boundary	compact	{"abcdefghijklmno":"abcdefghijklmno"}
+key-and-val-boundary	compact-omitempty	{"abcdefghijklmno":"abcdefghijklmno"}
+key-and-val-boundary	formatted	{\n    "abcdefghijklmno": "abcdefghijklmno"\n}
+key-and-val-boundary	formatted-omitempty	{\n    "abcdefghijklmno": "abcdefghijklmno"\n}
+escapes-short	compact	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-short	compact-omitempty	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-short	formatted	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-short	formatted-omitempty	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-control	compact	"\\u0001
+escapes-control	compact-omitempty	"\\u0001
+escapes-control	formatted	"\\u0001
+escapes-control	formatted-omitempty	"\\u0001
+escapes-mixed	compact	"a\\u0001
+escapes-mixed	compact-omitempty	"a\\u0001
+escapes-mixed	formatted	"a\\u0001
+escapes-mixed	formatted-omitempty	"a\\u0001
+escaped-key	compact	{"a\\u0001:"v"}
+escaped-key	compact-omitempty	{"a\\u0001:"v"}
+escaped-key	formatted	{\n    "a\\u0001: "v"\n}
+escaped-key	formatted-omitempty	{\n    "a\\u0001: "v"\n}
+escaped-key-quote	compact	{"q\\"k":"w"}
+escaped-key-quote	compact-omitempty	{"q\\"k":"w"}
+escaped-key-quote	formatted	{\n    "q\\"k": "w"\n}
+escaped-key-quote	formatted-omitempty	{\n    "q\\"k": "w"\n}
+utf8-value	compact	"é€"
+utf8-value	compact-omitempty	"é€"
+utf8-value	formatted	"é€"
+utf8-value	formatted-omitempty	"é€"
+empty-object	compact	{}
+empty-object	compact-omitempty	{}
+empty-object	formatted	{\n}
+empty-object	formatted-omitempty	{\n}
+empty-array	compact	[]
+empty-array	compact-omitempty	[]
+empty-array	formatted	[]
+empty-array	formatted-omitempty	[]
+flat-array	compact	[1,2,3]
+flat-array	compact-omitempty	[1,2,3]
+flat-array	formatted	[1, 2, 3]
+flat-array	formatted-omitempty	[1, 2, 3]
+mixed-array	compact	[1,"two",false,3.25,null,{},[]]
+mixed-array	compact-omitempty	[1,"two",false,3.25,null,{},[]]
+mixed-array	formatted	[1, "two", false, 3.25, null, {\n    }, []]
+mixed-array	formatted-omitempty	[1, "two", false, 3.25, null, {\n    }, []]
+simple-object	compact	{"a":"b"}
+simple-object	compact-omitempty	{"a":"b"}
+simple-object	formatted	{\n    "a": "b"\n}
+simple-object	formatted-omitempty	{\n    "a": "b"\n}
+nested-object	compact	{"a":{"b":{"c":1}}}
+nested-object	compact-omitempty	{"a":{"b":{"c":1}}}
+nested-object	formatted	{\n    "a": {\n        "b": {\n            "c": 1\n        }\n    }\n}
+nested-object	formatted-omitempty	{\n    "a": {\n        "b": {\n            "c": 1\n        }\n    }\n}
+object-of-arrays	compact	{"a":[1,[2,[3]]],"b":[]}
+object-of-arrays	compact-omitempty	{"a":[1,[2,[3]]],"b":[]}
+object-of-arrays	formatted	{\n    "a": [1, [2, [3]]],\n    "b": []\n}
+object-of-arrays	formatted-omitempty	{\n    "a": [1, [2, [3]]],\n    "b": []\n}
+array-of-objects	compact	[{"a":1},{"b":2}]
+array-of-objects	compact-omitempty	[{"a":1},{"b":2}]
+array-of-objects	formatted	[{\n        "a": 1\n    }, {\n        "b": 2\n    }]
+array-of-objects	formatted-omitempty	[{\n        "a": 1\n    }, {\n        "b": 2\n    }]
+all-falsy	compact	{"a":0,"b":false,"c":""}
+all-falsy	compact-omitempty	{}
+all-falsy	formatted	{\n    "a": 0,\n    "b": false,\n    "c": ""\n}
+all-falsy	formatted-omitempty	{\n            }
+falsy-around	compact	{"a":0,"b":1,"c":0}
+falsy-around	compact-omitempty	{"b":1}
+falsy-around	formatted	{\n    "a": 0,\n    "b": 1,\n    "c": 0\n}
+falsy-around	formatted-omitempty	{\n        "b": 1\n    }
+falsy-array	compact	[0,false,"",1]
+falsy-array	compact-omitempty	[0,false,"",1]
+falsy-array	formatted	[0, false, "", 1]
+falsy-array	formatted-omitempty	[0, false, "", 1]
+nested-falsy	compact	{"outer":{"a":0,"b":2,"c":false},"keep":1,"drop":0}
+nested-falsy	compact-omitempty	{"outer":{"b":2},"keep":1}
+nested-falsy	formatted	{\n    "outer": {\n        "a": 0,\n        "b": 2,\n        "c": false\n    },\n    "keep": 1,\n    "drop": 0\n}
+nested-falsy	formatted-omitempty	{\n    "outer": {\n                "b": 2\n            },\n    "keep": 1\n    }
+note-add	compact	{"req":"note.add","file":"sensors.qo","sync":true,"body":{"temp":22.5,"humid":48.2,"volts":3.31,"count":17}}
+note-add	compact-omitempty	{"req":"note.add","file":"sensors.qo","sync":true,"body":{"temp":22.5,"humid":48.2,"volts":3.31,"count":17}}
+note-add	formatted	{\n    "req": "note.add",\n    "file": "sensors.qo",\n    "sync": true,\n    "body": {\n        "temp": 22.5,\n        "humid": 48.2,\n        "volts": 3.31,\n        "count": 17\n    }\n}
+note-add	formatted-omitempty	{\n    "req": "note.add",\n    "file": "sensors.qo",\n    "sync": true,\n    "body": {\n        "temp": 22.5,\n        "humid": 48.2,\n        "volts": 3.31,\n        "count": 17\n    }\n}
+env-vars	compact	{"body":{"a":"1","b":"2","c":"3","d":"4","e":"5","f":"6","g":"7","h":"8"}}
+env-vars	compact-omitempty	{"body":{"a":"1","b":"2","c":"3","d":"4","e":"5","f":"6","g":"7","h":"8"}}
+env-vars	formatted	{\n    "body": {\n        "a": "1",\n        "b": "2",\n        "c": "3",\n        "d": "4",\n        "e": "5",\n        "f": "6",\n        "g": "7",\n        "h": "8"\n    }\n}
+env-vars	formatted-omitempty	{\n    "body": {\n        "a": "1",\n        "b": "2",\n        "c": "3",\n        "d": "4",\n        "e": "5",\n        "f": "6",\n        "g": "7",\n        "h": "8"\n    }\n}
+note-changes	compact	{"notes":{"a1":{"body":{"t":1}},"a2":{"body":{"t":2}},"a3":{"body":{"t":3}}}}
+note-changes	compact-omitempty	{"notes":{"a1":{"body":{"t":1}},"a2":{"body":{"t":2}},"a3":{"body":{"t":3}}}}
+note-changes	formatted	{\n    "notes": {\n        "a1": {\n            "body": {\n                "t": 1\n            }\n        },\n        "a2": {\n            "body": {\n                "t": 2\n            }\n        },\n        "a3": {\n            "body": {\n                "t": 3\n            }\n        }\n    }\n}
+note-changes	formatted-omitempty	{\n    "notes": {\n        "a1": {\n            "body": {\n                "t": 1\n            }\n        },\n        "a2": {\n            "body": {\n                "t": 2\n            }\n        },\n        "a3": {\n            "body": {\n                "t": 3\n            }\n        }\n    }\n}
+card-status	compact	{"status":"{normal}","usb":true,"storage":8,"time":1598479763,"connected":true}
+card-status	compact-omitempty	{"status":"{normal}","usb":true,"storage":8,"time":1598479763,"connected":true}
+card-status	formatted	{\n    "status": "{normal}",\n    "usb": true,\n    "storage": 8,\n    "time": 1598479763,\n    "connected": true\n}
+card-status	formatted-omitempty	{\n    "status": "{normal}",\n    "usb": true,\n    "storage": 8,\n    "time": 1598479763,\n    "connected": true\n}
+web-post	compact	{"req":"web.post","route":"weather","name":"/current","body":{"lat":42.36,"lon":-71.06},"content":"application/json"}
+web-post	compact-omitempty	{"req":"web.post","route":"weather","name":"/current","body":{"lat":42.36,"lon":-71.06},"content":"application/json"}
+web-post	formatted	{\n    "req": "web.post",\n    "route": "weather",\n    "name": "/current",\n    "body": {\n        "lat": 42.36,\n        "lon": -71.06\n    },\n    "content": "application/json"\n}
+web-post	formatted-omitempty	{\n    "req": "web.post",\n    "route": "weather",\n    "name": "/current",\n    "body": {\n        "lat": 42.36,\n        "lon": -71.06\n    },\n    "content": "application/json"\n}
+long-string-value	compact	{"body":{"msg":"this string is definitely longer than sixteen characters and forces the overflow path"}}
+long-string-value	compact-omitempty	{"body":{"msg":"this string is definitely longer than sixteen characters and forces the overflow path"}}
+long-string-value	formatted	{\n    "body": {\n        "msg": "this string is definitely longer than sixteen characters and forces the overflow path"\n    }\n}
+long-string-value	formatted-omitempty	{\n    "body": {\n        "msg": "this string is definitely longer than sixteen characters and forces the overflow path"\n    }\n}
+many-members	compact	{"k00":0,"k01":1,"k02":2,"k03":3,"k04":4,"k05":5,"k06":6,"k07":7,"k08":8,"k09":9,"k10":10,"k11":11}
+many-members	compact-omitempty	{"k01":1,"k02":2,"k03":3,"k04":4,"k05":5,"k06":6,"k07":7,"k08":8,"k09":9,"k10":10,"k11":11}
+many-members	formatted	{\n    "k00": 0,\n    "k01": 1,\n    "k02": 2,\n    "k03": 3,\n    "k04": 4,\n    "k05": 5,\n    "k06": 6,\n    "k07": 7,\n    "k08": 8,\n    "k09": 9,\n    "k10": 10,\n    "k11": 11\n}
+many-members	formatted-omitempty	{\n        "k01": 1,\n    "k02": 2,\n    "k03": 3,\n    "k04": 4,\n    "k05": 5,\n    "k06": 6,\n    "k07": 7,\n    "k08": 8,\n    "k09": 9,\n    "k10": 10,\n    "k11": 11\n}
+deep-nesting	compact	[[[[[[[[[[1]]]]]]]]]]
+deep-nesting	compact-omitempty	[[[[[[[[[[1]]]]]]]]]]
+deep-nesting	formatted	[[[[[[[[[[1]]]]]]]]]]
+deep-nesting	formatted-omitempty	[[[[[[[[[[1]]]]]]]]]]
+number-array-20	compact	{"data":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}
+number-array-20	compact-omitempty	{"data":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}
+number-array-20	formatted	{\n    "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]\n}
+number-array-20	formatted-omitempty	{\n    "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]\n}
+string-array	compact	["alpha","beta","gamma","delta","epsilon"]
+string-array	compact-omitempty	["alpha","beta","gamma","delta","epsilon"]
+string-array	formatted	["alpha", "beta", "gamma", "delta", "epsilon"]
+string-array	formatted-omitempty	["alpha", "beta", "gamma", "delta", "epsilon"]
diff --git a/test/data/corpus_golden_single.tsv b/test/data/corpus_golden_single.tsv
new file mode 100644
index 00000000..2f15ac64
--- /dev/null
+++ b/test/data/corpus_golden_single.tsv
@@ -0,0 +1,205 @@
+# Rendered by the historical note-c implementation.
+# Regenerate with scripts/generate_corpus_golden.sh -- do not hand-edit.
+# revision	9a12cfc
+# precision	single
+#doc	mode	output
+null	compact	null
+null	compact-omitempty	null
+null	formatted	null
+null	formatted-omitempty	null
+true	compact	true
+true	compact-omitempty	true
+true	formatted	true
+true	formatted-omitempty	true
+false	compact	false
+false	compact-omitempty	false
+false	formatted	false
+false	formatted-omitempty	false
+zero	compact	0
+zero	compact-omitempty	0
+zero	formatted	0
+zero	formatted-omitempty	0
+negative-int	compact	-12345
+negative-int	compact-omitempty	-12345
+negative-int	formatted	-12345
+negative-int	formatted-omitempty	-12345
+big-int-exact	compact	9007199254740993
+big-int-exact	compact-omitempty	9007199254740993
+big-int-exact	formatted	9007199254740993
+big-int-exact	formatted-omitempty	9007199254740993
+huge-int	compact	1234567890123456789
+huge-int	compact-omitempty	1234567890123456789
+huge-int	formatted	1234567890123456789
+huge-int	formatted-omitempty	1234567890123456789
+fraction	compact	3.249999996747776
+fraction	compact-omitempty	3.249999996747776
+fraction	formatted	3.249999996747776
+fraction	formatted-omitempty	3.249999996747776
+negative-fraction	compact	-0.1250000034070528
+negative-fraction	compact-omitempty	-0.1250000034070528
+negative-fraction	formatted	-0.1250000034070528
+negative-fraction	formatted-omitempty	-0.1250000034070528
+exp-small	compact	1.500000228376576e-07
+exp-small	compact-omitempty	1.500000228376576e-07
+exp-small	formatted	1.500000228376576e-07
+exp-small	formatted-omitempty	1.500000228376576e-07
+string-short	compact	"hi"
+string-short	compact-omitempty	"hi"
+string-short	formatted	"hi"
+string-short	formatted-omitempty	"hi"
+string-empty	compact	""
+string-empty	compact-omitempty	""
+string-empty	formatted	""
+string-empty	formatted-omitempty	""
+val-len-14	compact	"abcdefghijklmn"
+val-len-14	compact-omitempty	"abcdefghijklmn"
+val-len-14	formatted	"abcdefghijklmn"
+val-len-14	formatted-omitempty	"abcdefghijklmn"
+val-len-15	compact	"abcdefghijklmno"
+val-len-15	compact-omitempty	"abcdefghijklmno"
+val-len-15	formatted	"abcdefghijklmno"
+val-len-15	formatted-omitempty	"abcdefghijklmno"
+val-len-16	compact	"abcdefghijklmnop"
+val-len-16	compact-omitempty	"abcdefghijklmnop"
+val-len-16	formatted	"abcdefghijklmnop"
+val-len-16	formatted-omitempty	"abcdefghijklmnop"
+val-len-17	compact	"abcdefghijklmnopq"
+val-len-17	compact-omitempty	"abcdefghijklmnopq"
+val-len-17	formatted	"abcdefghijklmnopq"
+val-len-17	formatted-omitempty	"abcdefghijklmnopq"
+val-len-31	compact	"abcdefghijklmnopqrstuvwxyz01234"
+val-len-31	compact-omitempty	"abcdefghijklmnopqrstuvwxyz01234"
+val-len-31	formatted	"abcdefghijklmnopqrstuvwxyz01234"
+val-len-31	formatted-omitempty	"abcdefghijklmnopqrstuvwxyz01234"
+key-len-14	compact	{"abcdefghijklmn":1}
+key-len-14	compact-omitempty	{"abcdefghijklmn":1}
+key-len-14	formatted	{\n    "abcdefghijklmn": 1\n}
+key-len-14	formatted-omitempty	{\n    "abcdefghijklmn": 1\n}
+key-len-15	compact	{"abcdefghijklmno":1}
+key-len-15	compact-omitempty	{"abcdefghijklmno":1}
+key-len-15	formatted	{\n    "abcdefghijklmno": 1\n}
+key-len-15	formatted-omitempty	{\n    "abcdefghijklmno": 1\n}
+key-len-16	compact	{"abcdefghijklmnop":1}
+key-len-16	compact-omitempty	{"abcdefghijklmnop":1}
+key-len-16	formatted	{\n    "abcdefghijklmnop": 1\n}
+key-len-16	formatted-omitempty	{\n    "abcdefghijklmnop": 1\n}
+key-len-17	compact	{"abcdefghijklmnopq":1}
+key-len-17	compact-omitempty	{"abcdefghijklmnopq":1}
+key-len-17	formatted	{\n    "abcdefghijklmnopq": 1\n}
+key-len-17	formatted-omitempty	{\n    "abcdefghijklmnopq": 1\n}
+key-and-val-boundary	compact	{"abcdefghijklmno":"abcdefghijklmno"}
+key-and-val-boundary	compact-omitempty	{"abcdefghijklmno":"abcdefghijklmno"}
+key-and-val-boundary	formatted	{\n    "abcdefghijklmno": "abcdefghijklmno"\n}
+key-and-val-boundary	formatted-omitempty	{\n    "abcdefghijklmno": "abcdefghijklmno"\n}
+escapes-short	compact	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-short	compact-omitempty	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-short	formatted	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-short	formatted-omitempty	"q\\"w\\\\e\\nr\\tt\\b\\f\\r"
+escapes-control	compact	"\\u0001
+escapes-control	compact-omitempty	"\\u0001
+escapes-control	formatted	"\\u0001
+escapes-control	formatted-omitempty	"\\u0001
+escapes-mixed	compact	"a\\u0001
+escapes-mixed	compact-omitempty	"a\\u0001
+escapes-mixed	formatted	"a\\u0001
+escapes-mixed	formatted-omitempty	"a\\u0001
+escaped-key	compact	{"a\\u0001:"v"}
+escaped-key	compact-omitempty	{"a\\u0001:"v"}
+escaped-key	formatted	{\n    "a\\u0001: "v"\n}
+escaped-key	formatted-omitempty	{\n    "a\\u0001: "v"\n}
+escaped-key-quote	compact	{"q\\"k":"w"}
+escaped-key-quote	compact-omitempty	{"q\\"k":"w"}
+escaped-key-quote	formatted	{\n    "q\\"k": "w"\n}
+escaped-key-quote	formatted-omitempty	{\n    "q\\"k": "w"\n}
+utf8-value	compact	"é€"
+utf8-value	compact-omitempty	"é€"
+utf8-value	formatted	"é€"
+utf8-value	formatted-omitempty	"é€"
+empty-object	compact	{}
+empty-object	compact-omitempty	{}
+empty-object	formatted	{\n}
+empty-object	formatted-omitempty	{\n}
+empty-array	compact	[]
+empty-array	compact-omitempty	[]
+empty-array	formatted	[]
+empty-array	formatted-omitempty	[]
+flat-array	compact	[1,2,3]
+flat-array	compact-omitempty	[1,2,3]
+flat-array	formatted	[1, 2, 3]
+flat-array	formatted-omitempty	[1, 2, 3]
+mixed-array	compact	[1,"two",false,3.249999996747776,null,{},[]]
+mixed-array	compact-omitempty	[1,"two",false,3.249999996747776,null,{},[]]
+mixed-array	formatted	[1, "two", false, 3.249999996747776, null, {\n    }, []]
+mixed-array	formatted-omitempty	[1, "two", false, 3.249999996747776, null, {\n    }, []]
+simple-object	compact	{"a":"b"}
+simple-object	compact-omitempty	{"a":"b"}
+simple-object	formatted	{\n    "a": "b"\n}
+simple-object	formatted-omitempty	{\n    "a": "b"\n}
+nested-object	compact	{"a":{"b":{"c":1}}}
+nested-object	compact-omitempty	{"a":{"b":{"c":1}}}
+nested-object	formatted	{\n    "a": {\n        "b": {\n            "c": 1\n        }\n    }\n}
+nested-object	formatted-omitempty	{\n    "a": {\n        "b": {\n            "c": 1\n        }\n    }\n}
+object-of-arrays	compact	{"a":[1,[2,[3]]],"b":[]}
+object-of-arrays	compact-omitempty	{"a":[1,[2,[3]]],"b":[]}
+object-of-arrays	formatted	{\n    "a": [1, [2, [3]]],\n    "b": []\n}
+object-of-arrays	formatted-omitempty	{\n    "a": [1, [2, [3]]],\n    "b": []\n}
+array-of-objects	compact	[{"a":1},{"b":2}]
+array-of-objects	compact-omitempty	[{"a":1},{"b":2}]
+array-of-objects	formatted	[{\n        "a": 1\n    }, {\n        "b": 2\n    }]
+array-of-objects	formatted-omitempty	[{\n        "a": 1\n    }, {\n        "b": 2\n    }]
+all-falsy	compact	{"a":0,"b":false,"c":""}
+all-falsy	compact-omitempty	{}
+all-falsy	formatted	{\n    "a": 0,\n    "b": false,\n    "c": ""\n}
+all-falsy	formatted-omitempty	{\n            }
+falsy-around	compact	{"a":0,"b":1,"c":0}
+falsy-around	compact-omitempty	{"b":1}
+falsy-around	formatted	{\n    "a": 0,\n    "b": 1,\n    "c": 0\n}
+falsy-around	formatted-omitempty	{\n        "b": 1\n    }
+falsy-array	compact	[0,false,"",1]
+falsy-array	compact-omitempty	[0,false,"",1]
+falsy-array	formatted	[0, false, "", 1]
+falsy-array	formatted-omitempty	[0, false, "", 1]
+nested-falsy	compact	{"outer":{"a":0,"b":2,"c":false},"keep":1,"drop":0}
+nested-falsy	compact-omitempty	{"outer":{"b":2},"keep":1}
+nested-falsy	formatted	{\n    "outer": {\n        "a": 0,\n        "b": 2,\n        "c": false\n    },\n    "keep": 1,\n    "drop": 0\n}
+nested-falsy	formatted-omitempty	{\n    "outer": {\n                "b": 2\n            },\n    "keep": 1\n    }
+note-add	compact	{"req":"note.add","file":"sensors.qo","sync":true,"body":{"temp":22.50000000188416,"humid":48.2000007725056,"volts":3.309999934898176,"count":17}}
+note-add	compact-omitempty	{"req":"note.add","file":"sensors.qo","sync":true,"body":{"temp":22.50000000188416,"humid":48.2000007725056,"volts":3.309999934898176,"count":17}}
+note-add	formatted	{\n    "req": "note.add",\n    "file": "sensors.qo",\n    "sync": true,\n    "body": {\n        "temp": 22.50000000188416,\n        "humid": 48.2000007725056,\n        "volts": 3.309999934898176,\n        "count": 17\n    }\n}
+note-add	formatted-omitempty	{\n    "req": "note.add",\n    "file": "sensors.qo",\n    "sync": true,\n    "body": {\n        "temp": 22.50000000188416,\n        "humid": 48.2000007725056,\n        "volts": 3.309999934898176,\n        "count": 17\n    }\n}
+env-vars	compact	{"body":{"a":"1","b":"2","c":"3","d":"4","e":"5","f":"6","g":"7","h":"8"}}
+env-vars	compact-omitempty	{"body":{"a":"1","b":"2","c":"3","d":"4","e":"5","f":"6","g":"7","h":"8"}}
+env-vars	formatted	{\n    "body": {\n        "a": "1",\n        "b": "2",\n        "c": "3",\n        "d": "4",\n        "e": "5",\n        "f": "6",\n        "g": "7",\n        "h": "8"\n    }\n}
+env-vars	formatted-omitempty	{\n    "body": {\n        "a": "1",\n        "b": "2",\n        "c": "3",\n        "d": "4",\n        "e": "5",\n        "f": "6",\n        "g": "7",\n        "h": "8"\n    }\n}
+note-changes	compact	{"notes":{"a1":{"body":{"t":1}},"a2":{"body":{"t":2}},"a3":{"body":{"t":3}}}}
+note-changes	compact-omitempty	{"notes":{"a1":{"body":{"t":1}},"a2":{"body":{"t":2}},"a3":{"body":{"t":3}}}}
+note-changes	formatted	{\n    "notes": {\n        "a1": {\n            "body": {\n                "t": 1\n            }\n        },\n        "a2": {\n            "body": {\n                "t": 2\n            }\n        },\n        "a3": {\n            "body": {\n                "t": 3\n            }\n        }\n    }\n}
+note-changes	formatted-omitempty	{\n    "notes": {\n        "a1": {\n            "body": {\n                "t": 1\n            }\n        },\n        "a2": {\n            "body": {\n                "t": 2\n            }\n        },\n        "a3": {\n            "body": {\n                "t": 3\n            }\n        }\n    }\n}
+card-status	compact	{"status":"{normal}","usb":true,"storage":8,"time":1598479763,"connected":true}
+card-status	compact-omitempty	{"status":"{normal}","usb":true,"storage":8,"time":1598479763,"connected":true}
+card-status	formatted	{\n    "status": "{normal}",\n    "usb": true,\n    "storage": 8,\n    "time": 1598479763,\n    "connected": true\n}
+card-status	formatted-omitempty	{\n    "status": "{normal}",\n    "usb": true,\n    "storage": 8,\n    "time": 1598479763,\n    "connected": true\n}
+web-post	compact	{"req":"web.post","route":"weather","name":"/current","body":{"lat":42.36000059359232,"lon":-71.05999755788288},"content":"application/json"}
+web-post	compact-omitempty	{"req":"web.post","route":"weather","name":"/current","body":{"lat":42.36000059359232,"lon":-71.05999755788288},"content":"application/json"}
+web-post	formatted	{\n    "req": "web.post",\n    "route": "weather",\n    "name": "/current",\n    "body": {\n        "lat": 42.36000059359232,\n        "lon": -71.05999755788288\n    },\n    "content": "application/json"\n}
+web-post	formatted-omitempty	{\n    "req": "web.post",\n    "route": "weather",\n    "name": "/current",\n    "body": {\n        "lat": 42.36000059359232,\n        "lon": -71.05999755788288\n    },\n    "content": "application/json"\n}
+long-string-value	compact	{"body":{"msg":"this string is definitely longer than sixteen characters and forces the overflow path"}}
+long-string-value	compact-omitempty	{"body":{"msg":"this string is definitely longer than sixteen characters and forces the overflow path"}}
+long-string-value	formatted	{\n    "body": {\n        "msg": "this string is definitely longer than sixteen characters and forces the overflow path"\n    }\n}
+long-string-value	formatted-omitempty	{\n    "body": {\n        "msg": "this string is definitely longer than sixteen characters and forces the overflow path"\n    }\n}
+many-members	compact	{"k00":0,"k01":1,"k02":2,"k03":3,"k04":4,"k05":5,"k06":6,"k07":7,"k08":8,"k09":9,"k10":10,"k11":11}
+many-members	compact-omitempty	{"k01":1,"k02":2,"k03":3,"k04":4,"k05":5,"k06":6,"k07":7,"k08":8,"k09":9,"k10":10,"k11":11}
+many-members	formatted	{\n    "k00": 0,\n    "k01": 1,\n    "k02": 2,\n    "k03": 3,\n    "k04": 4,\n    "k05": 5,\n    "k06": 6,\n    "k07": 7,\n    "k08": 8,\n    "k09": 9,\n    "k10": 10,\n    "k11": 11\n}
+many-members	formatted-omitempty	{\n        "k01": 1,\n    "k02": 2,\n    "k03": 3,\n    "k04": 4,\n    "k05": 5,\n    "k06": 6,\n    "k07": 7,\n    "k08": 8,\n    "k09": 9,\n    "k10": 10,\n    "k11": 11\n}
+deep-nesting	compact	[[[[[[[[[[1]]]]]]]]]]
+deep-nesting	compact-omitempty	[[[[[[[[[[1]]]]]]]]]]
+deep-nesting	formatted	[[[[[[[[[[1]]]]]]]]]]
+deep-nesting	formatted-omitempty	[[[[[[[[[[1]]]]]]]]]]
+number-array-20	compact	{"data":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}
+number-array-20	compact-omitempty	{"data":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}
+number-array-20	formatted	{\n    "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]\n}
+number-array-20	formatted-omitempty	{\n    "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]\n}
+string-array	compact	["alpha","beta","gamma","delta","epsilon"]
+string-array	compact-omitempty	["alpha","beta","gamma","delta","epsilon"]
+string-array	formatted	["alpha", "beta", "gamma", "delta", "epsilon"]
+string-array	formatted-omitempty	["alpha", "beta", "gamma", "delta", "epsilon"]
diff --git a/test/include/j_corpus.hpp b/test/include/j_corpus.hpp
new file mode 100644
index 00000000..db8bf8e0
--- /dev/null
+++ b/test/include/j_corpus.hpp
@@ -0,0 +1,178 @@
+/*!
+ * @file j_corpus.hpp
+ *
+ * The document corpus and render modes, factored out of
+ * j_layout_test_support.hpp so they can be compiled against a PRISTINE
+ * historical build of the library.
+ *
+ * That is the whole reason this file is separate. An A/B between two builds of
+ * the same rewritten parser and printer cannot detect a regression that both
+ * builds share, so scripts/generate_corpus_golden.sh compiles this corpus
+ * against `git archive HEAD` and records what the historical implementation
+ * renders. The result is checked in as test/data/, and the layout suite
+ * compares against it. Nothing here may depend on Catch2 or on anything newer
+ * than the public note-c API, or that generator stops building.
+ *
+ * Written by the Blues Inc. team.
+ *
+ * Copyright (c) 2025 Blues Inc. MIT License. Use of this source code is
+ * governed by licenses granted by the copyright holder including that found in
+ * the
+ * <a href="https://github.com/blues/note-c/blob/master/LICENSE">LICENSE</a>
+ * file.
+ *
+ */
+
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "n_lib.h"
+
+namespace jlayout
+{
+
+// ---------------------------------------------------------------------------
+// Corpus
+// ---------------------------------------------------------------------------
+
+struct Doc {
+    const char *name;
+    const char *json;
+    // True when the document contains a number that does not survive a
+    // text->float->text round trip under NOTE_C_SINGLE_PRECISION. This is a
+    // pre-existing property of note-c's numeric conversion, identical in both
+    // J layouts, so those documents are exempted from the idempotence,
+    // structural-equality and digest checks in single-precision builds only.
+    bool lossyUnderSinglePrecision;
+};
+
+// True when this build cannot round-trip the document's numbers.
+inline bool numbersAreLossy(const Doc &d)
+{
+#ifdef NOTE_C_SINGLE_PRECISION
+    return d.lossyUnderSinglePrecision;
+#else
+    (void)d;
+    return false;
+#endif
+}
+
+// Dozens of documents spanning every _print_value arm, both sides of the inline
+// capacity boundary, key/value escape handling, deep and wide shapes, and the
+// falsy shapes that drive omitempty.
+inline const std::vector<Doc> &corpus()
+{
+    static const std::vector<Doc> docs = {
+        // --- scalars at the root ---
+        { "null", "null", false },
+        { "true", "true", false },
+        { "false", "false", false },
+        { "zero", "0", false },
+        { "negative-int", "-12345", false },
+        { "big-int-exact", "9007199254740993", true },
+        { "huge-int", "1234567890123456789", true },
+        { "fraction", "3.25", true },
+        { "negative-fraction", "-0.125", true },
+        { "exp-small", "1.5e-7", true },
+        { "string-short", "\"hi\"", false },
+        { "string-empty", "\"\"", false },
+
+        // --- inline capacity boundary (J_INLINE_CAP is 16 including NUL) ---
+        { "val-len-14", "\"abcdefghijklmn\"", false },
+        { "val-len-15", "\"abcdefghijklmno\"", false },
+        { "val-len-16", "\"abcdefghijklmnop\"", false },
+        { "val-len-17", "\"abcdefghijklmnopq\"", false },
+        { "val-len-31", "\"abcdefghijklmnopqrstuvwxyz01234\"", false },
+        { "key-len-14", "{\"abcdefghijklmn\":1}", false },
+        { "key-len-15", "{\"abcdefghijklmno\":1}", false },
+        { "key-len-16", "{\"abcdefghijklmnop\":1}", false },
+        { "key-len-17", "{\"abcdefghijklmnopq\":1}", false },
+        { "key-and-val-boundary", "{\"abcdefghijklmno\":\"abcdefghijklmno\"}", false },
+
+        // --- escapes, in values and in keys ---
+        { "escapes-short", "\"q\\\"w\\\\e\\nr\\tt\\b\\f\\r\"", false },
+        { "escapes-control", "\"\\u0001\\u0002\\u0003\"", false },
+        { "escapes-mixed", "\"a\\u0001b\\u0002c\"", false },
+        { "escaped-key", "{\"a\\u0001b\":\"v\"}", false },
+        { "escaped-key-quote", "{\"q\\\"k\":\"w\"}", false },
+        { "utf8-value", "\"\\u00e9\\u20ac\"", false },
+
+        // --- containers ---
+        { "empty-object", "{}", false },
+        { "empty-array", "[]", false },
+        { "flat-array", "[1,2,3]", false },
+        { "mixed-array", "[1,\"two\",false,3.25,null,{},[]]", true },
+        { "simple-object", "{\"a\":\"b\"}", false },
+        { "nested-object", "{\"a\":{\"b\":{\"c\":1}}}", false },
+        { "object-of-arrays", "{\"a\":[1,[2,[3]]],\"b\":[]}", false },
+        { "array-of-objects", "[{\"a\":1},{\"b\":2}]", false },
+
+        // --- omitempty-relevant shapes ---
+        { "all-falsy", "{\"a\":0,\"b\":false,\"c\":\"\"}", false },
+        { "falsy-around", "{\"a\":0,\"b\":1,\"c\":0}", false },
+        { "falsy-array", "[0,false,\"\",1]", false },
+        { "nested-falsy", "{\"outer\":{\"a\":0,\"b\":2,\"c\":false},\"keep\":1,\"drop\":0}", false },
+
+        // --- realistic Notecard traffic ---
+        {
+            "note-add", "{\"req\":\"note.add\",\"file\":\"sensors.qo\",\"sync\":true,"
+            "\"body\":{\"temp\":22.5,\"humid\":48.2,\"volts\":3.31,\"count\":17}}",
+            true
+        },
+        {
+            "env-vars", "{\"body\":{\"a\":\"1\",\"b\":\"2\",\"c\":\"3\",\"d\":\"4\","
+            "\"e\":\"5\",\"f\":\"6\",\"g\":\"7\",\"h\":\"8\"}}",
+            false
+        },
+        {
+            "note-changes", "{\"notes\":{\"a1\":{\"body\":{\"t\":1}},"
+            "\"a2\":{\"body\":{\"t\":2}},\"a3\":{\"body\":{\"t\":3}}}}",
+            false
+        },
+        {
+            "card-status", "{\"status\":\"{normal}\",\"usb\":true,\"storage\":8,"
+            "\"time\":1598479763,\"connected\":true}",
+            true
+        },
+        {
+            "web-post", "{\"req\":\"web.post\",\"route\":\"weather\",\"name\":\"/current\","
+            "\"body\":{\"lat\":42.36,\"lon\":-71.06},\"content\":\"application/json\"}",
+            true
+        },
+        {
+            "long-string-value", "{\"body\":{\"msg\":\"this string is definitely longer "
+            "than sixteen characters and forces the overflow path\"}}",
+            false
+        },
+        {
+            "many-members", "{\"k00\":0,\"k01\":1,\"k02\":2,\"k03\":3,\"k04\":4,\"k05\":5,"
+            "\"k06\":6,\"k07\":7,\"k08\":8,\"k09\":9,\"k10\":10,\"k11\":11}",
+            false
+        },
+        { "deep-nesting", "[[[[[[[[[[1]]]]]]]]]]", false },
+        { "number-array-20", "{\"data\":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}", false },
+        { "string-array", "[\"alpha\",\"beta\",\"gamma\",\"delta\",\"epsilon\"]", false },
+    };
+    return docs;
+}
+
+struct Mode {
+    const char *name;
+    Jbool format;
+    Jbool omitempty;
+};
+
+inline const std::vector<Mode> &modes()
+{
+    static const std::vector<Mode> m = {
+        { "compact", false, false },
+        { "compact-omitempty", false, true },
+        { "formatted", true, false },
+        { "formatted-omitempty", true, true },
+    };
+    return m;
+}
+
+}
diff --git a/test/include/j_layout_test_support.hpp b/test/include/j_layout_test_support.hpp
new file mode 100644
index 00000000..492ae72f
--- /dev/null
+++ b/test/include/j_layout_test_support.hpp
@@ -0,0 +1,662 @@
+/*!
+ * @file j_layout_test_support.hpp
+ *
+ * Shared machinery for validating the packed `J` layout against the historical
+ * unpacked one.
+ *
+ * The two layouts cannot coexist in one binary -- `J` is a single type, selected
+ * at compile time by NOTE_C_STORAGE_OPTIMIZATION -- so the A/B comparison is done by
+ * building this suite twice and comparing the two runs:
+ *
+ *   1. Every test asserts layout-INDEPENDENT invariants, so each build stands on
+ *      its own: parse/print round trips, structural equality, ownership, and no
+ *      leaked allocations.
+ *   2. Every test also records, per corpus document, the exact printed output
+ *      and the exact heap cost. Those records are written to a report file, and
+ *      scripts/run_ab_layout_comparison.sh diffs the two builds' reports. The
+ *      output columns must be byte-identical; the memory columns are the
+ *      measurement.
+ *   3. A digest over every printed output is asserted in-test against a single
+ *      constant, so a build that silently changes rendering fails immediately
+ *      rather than waiting for the cross-build diff.
+ *
+ * Written by the Blues Inc. team.
+ *
+ * Copyright (c) 2025 Blues Inc. MIT License. Use of this source code is
+ * governed by licenses granted by the copyright holder including that found in
+ * the
+ * <a href="https://github.com/blues/note-c/blob/master/LICENSE">LICENSE</a>
+ * file.
+ *
+ */
+
+#pragma once
+
+#include <catch2/catch_test_macros.hpp>
+
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <string>
+#include <vector>
+
+#include "n_lib.h"
+
+// The corpus and render modes live in their own header so the golden
+// generator can compile them against a pristine historical build; see
+// scripts/generate_corpus_golden.sh.
+#include "j_corpus.hpp"
+
+namespace jlayout
+{
+
+// Defined below; declared here because the chunk models need it.
+inline bool isPackedLayout();
+
+// ---------------------------------------------------------------------------
+// Allocator instrumentation
+// ---------------------------------------------------------------------------
+
+struct Stats {
+    size_t mallocCalls;
+    size_t freeCalls;
+    size_t bytesRequested;
+    size_t liveBytes;
+    size_t liveBlocks;
+};
+
+inline Stats &stats()
+{
+    static Stats s = { 0, 0, 0, 0, 0 };
+    return s;
+}
+
+// Live-block registry, so leaks and net heap cost can both be measured exactly.
+inline std::vector<std::pair<void *, size_t> > &blocks()
+{
+    static std::vector<std::pair<void *, size_t> > b;
+    return b;
+}
+
+// Allocation-failure injection.
+//
+// `failAtCall` is the 1-based ordinal of the malloc that should return NULL;
+// zero disables injection. Counting ordinals rather than sizes lets a test walk
+// every allocation an operation makes and assert that failing at each one in
+// turn leaves nothing leaked and nothing dangling -- the paths that are
+// otherwise never taken, and where a half-built node is most likely to escape.
+struct FailInjector {
+    size_t failAtCall;   // 1-based; 0 = never fail
+    size_t callsSeen;    // attempts, including the one that was refused
+    bool   fired;
+};
+
+inline FailInjector &failInjector()
+{
+    static FailInjector f = { 0, 0, false };
+    return f;
+}
+
+inline void failAllocationAt(size_t oneBasedOrdinal)
+{
+    FailInjector &f = failInjector();
+    f.failAtCall = oneBasedOrdinal;
+    f.callsSeen = 0;
+    f.fired = false;
+}
+
+inline void stopFailingAllocations()
+{
+    failAllocationAt(0);
+}
+
+inline void *trackedMalloc(size_t size)
+{
+    FailInjector &f = failInjector();
+    ++f.callsSeen;
+    if ((f.failAtCall != 0) && (f.callsSeen == f.failAtCall)) {
+        f.fired = true;
+        return NULL;
+    }
+
+    void *p = malloc(size);
+    if (p != NULL) {
+        Stats &s = stats();
+        ++s.mallocCalls;
+        s.bytesRequested += size;
+        s.liveBytes += size;
+        ++s.liveBlocks;
+        blocks().push_back(std::make_pair(p, size));
+    }
+    return p;
+}
+
+inline void trackedFree(void *ptr)
+{
+    if (ptr == NULL) {
+        return;
+    }
+    Stats &s = stats();
+    ++s.freeCalls;
+    std::vector<std::pair<void *, size_t> > &b = blocks();
+    for (size_t i = b.size(); i-- > 0;) {
+        if (b[i].first == ptr) {
+            s.liveBytes -= b[i].second;
+            --s.liveBlocks;
+            b.erase(b.begin() + static_cast<long>(i));
+            break;
+        }
+    }
+    free(ptr);
+}
+
+// Install the instrumented allocator and start from a clean slate.
+//
+// Catch2 re-enters a SCENARIO body once per leaf section, and a REQUIRE that
+// fires aborts the case without running its cleanup, so the live-block registry
+// must be reset per entry. Otherwise one failure cascades into spurious leak
+// reports in every later scenario.
+inline void installTrackedAllocator()
+{
+    NoteSetFn(trackedMalloc, trackedFree, NULL, NULL);
+    stopFailingAllocations();
+    Stats &s = stats();
+    s.mallocCalls = 0;
+    s.freeCalls = 0;
+    s.bytesRequested = 0;
+    s.liveBytes = 0;
+    s.liveBlocks = 0;
+    blocks().clear();
+}
+
+inline void resetStats()
+{
+    Stats &s = stats();
+    s.mallocCalls = 0;
+    s.freeCalls = 0;
+    s.bytesRequested = 0;
+    // liveBytes/liveBlocks intentionally NOT reset: they track outstanding
+    // allocations across a whole test so leaks are visible.
+}
+
+// True if `p` lies inside the block that starts at `base` and is `len` long.
+inline bool within(const void *p, const void *base, size_t len)
+{
+    const char *cp = static_cast<const char *>(p);
+    const char *cb = static_cast<const char *>(base);
+    return (cp >= cb) && (cp < cb + len);
+}
+
+// Size of the tracked allocation containing `p`, or 0 if `p` is not inside one.
+inline size_t owningBlockSize(const void *p)
+{
+    const std::vector<std::pair<void *, size_t> > &b = blocks();
+    for (size_t i = b.size(); i-- > 0;) {
+        if (within(p, b[i].first, b[i].second)) {
+            return b[i].second;
+        }
+    }
+    return 0;
+}
+
+// True if `p` points inside the same allocation that `node` starts.
+inline bool insideNodeAllocation(const J *node, const void *p)
+{
+    if (p == NULL) {
+        return false;
+    }
+    const std::vector<std::pair<void *, size_t> > &b = blocks();
+    for (size_t i = b.size(); i-- > 0;) {
+        if (b[i].first == static_cast<const void *>(node)) {
+            return within(p, b[i].first, b[i].second);
+        }
+    }
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// Real-allocator chunk models
+//
+// Bytes REQUESTED understates what a document actually costs. Every allocation
+// on a real target also carries a per-chunk header and is rounded up to the
+// allocator's alignment, and small requests are floored at a minimum chunk. The
+// models below are the two allocators a Cortex-M Notecard host is most likely to
+// be running. Both are 32-bit.
+// ---------------------------------------------------------------------------
+
+// sizeof(J) on the 32-bit target, per layout. The host build is 64-bit, so
+// every node allocation is shrunk by the difference before the chunk model is
+// applied. Nothing else in a node's allocation is word-size dependent: the
+// trailing key/value bytes are plain byte counts.
+// The target sizes depend on JNUMBER's width as well as the layout. With a
+// double, the historical node is 48 and the packed one 40. With
+// NOTE_C_SINGLE_PRECISION, JNUMBER is a float, which removes the historical
+// layout's tail padding on its own: BOTH layouts are 40 there, so the member
+// reorder contributes nothing and the entire saving comes from inline packing.
+//
+// Hardcoding 48/40 unconditionally would overstate the single-precision win by
+// attributing 8 bytes per node to a change that did not happen. Verified by
+// cross-compiling for Cortex-M4: 48 / 40 / 40 / 40 across the four cells.
+enum {
+    J_SIZE_HOST = sizeof(J),
+#ifdef NOTE_C_SINGLE_PRECISION
+    J_SIZE_TARGET_PACKED = 40,
+    J_SIZE_TARGET_UNPACKED = 40
+#else
+    J_SIZE_TARGET_PACKED = 40,
+    J_SIZE_TARGET_UNPACKED = 48
+#endif
+};
+
+// newlib / dlmalloc: 4-byte in-use chunk header, 8-byte alignment, 16-byte
+// minimum chunk. This is what arm-none-eabi-newlib's full malloc does.
+inline size_t chunkDlmalloc(size_t n)
+{
+    size_t c = (n + 4 + 7) & ~(size_t)7;
+    return c < 16 ? 16 : c;
+}
+
+// FreeRTOS heap_4: an 8-byte BlockLink_t is prepended and the whole thing is
+// rounded to portBYTE_ALIGNMENT (8).
+inline size_t chunkFreeRtosHeap4(size_t n)
+{
+    size_t c = (n + 8 + 7) & ~(size_t)7;
+    return c < 16 ? 16 : c;
+}
+
+// newlib nano-malloc (--specs=nano.specs), common on small Cortex-M parts:
+// 4-byte size field, 8-byte alignment, 8-byte minimum.
+inline size_t chunkNanoMalloc(size_t n)
+{
+    size_t c = (n + 4 + 7) & ~(size_t)7;
+    return c < 8 ? 8 : c;
+}
+
+struct ChunkTotals {
+    size_t raw;        // bytes as requested, 32-bit sizes
+    size_t dlmalloc;
+    size_t freertos;
+    size_t nano;
+};
+
+// Walk the live blocks, translate node allocations to their 32-bit size, and
+// total them under each model. `nodePtrs` identifies which blocks are nodes.
+inline ChunkTotals chunkTotals(const std::vector<const void *> &nodePtrs)
+{
+    const size_t shrink = (size_t)J_SIZE_HOST -
+                          (isPackedLayout() ? (size_t)J_SIZE_TARGET_PACKED
+                           : (size_t)J_SIZE_TARGET_UNPACKED);
+    ChunkTotals t = { 0, 0, 0, 0 };
+    const std::vector<std::pair<void *, size_t> > &b = blocks();
+    for (size_t i = 0; i < b.size(); ++i) {
+        size_t sz = b[i].second;
+        bool isNode = false;
+        for (size_t k = 0; k < nodePtrs.size(); ++k) {
+            if (nodePtrs[k] == b[i].first) {
+                isNode = true;
+                break;
+            }
+        }
+        if (isNode) {
+            sz -= shrink;
+        }
+        t.raw += sz;
+        t.dlmalloc += chunkDlmalloc(sz);
+        t.freertos += chunkFreeRtosHeap4(sz);
+        t.nano += chunkNanoMalloc(sz);
+    }
+    return t;
+}
+
+// ---------------------------------------------------------------------------
+// Which layout is this build?
+// ---------------------------------------------------------------------------
+
+inline const char *layoutName()
+{
+#ifndef NOTE_C_STORAGE_OPTIMIZATION
+    return "unpacked";
+#else
+    return "packed";
+#endif
+}
+
+inline bool isPacked()
+{
+#ifndef NOTE_C_STORAGE_OPTIMIZATION
+    return false;
+#else
+    return true;
+#endif
+}
+
+inline bool isPackedLayout()
+{
+    return isPacked();
+}
+
+// Total bytes allocated for a node. The packed layout records this in objlen;
+// the unpacked layout has no such member and every node is exactly sizeof(J).
+// Wrapping it keeps the tests free of #ifdefs -- isPacked() is a runtime test,
+// so an unguarded item->objlen would still have to COMPILE in both builds.
+inline size_t nodeAllocSize(const J *item)
+{
+#ifndef NOTE_C_STORAGE_OPTIMIZATION
+    (void)item;
+    return sizeof(J);
+#else
+    return item->objlen;
+#endif
+}
+
+
+// ---------------------------------------------------------------------------
+// Historical goldens
+//
+// What the SHIPPED implementation renders for each (document, mode), recorded
+// by scripts/generate_corpus_golden.sh from a pristine `git archive` of the
+// base revision and checked in under test/data/.
+//
+// This is the only check in the suite that looks outside the working tree. The
+// cross-layout diff and the digest below both compare the rewrite against
+// itself: they catch a change that affects ONE layout, and are blind to one
+// that affects both. Comparing against a recording of the released behavior is
+// what closes that gap.
+// ---------------------------------------------------------------------------
+
+typedef std::vector<std::pair<std::string, std::string> > GoldenRows;
+
+// Undo the escaping the generator applies so each row stays one line.
+inline std::string goldenUnescape(const std::string &in)
+{
+    std::string out;
+    out.reserve(in.size());
+    for (size_t i = 0; i < in.size(); ++i) {
+        if ((in[i] == '\\') && ((i + 1) < in.size())) {
+            switch (in[i + 1]) {
+            case 'n':
+                out += '\n';
+                ++i;
+                continue;
+            case 't':
+                out += '\t';
+                ++i;
+                continue;
+            case '\\':
+                out += '\\';
+                ++i;
+                continue;
+            default:
+                break;
+            }
+        }
+        out += in[i];
+    }
+    return out;
+}
+
+// Keyed by "doc\tmode". Empty if the file is missing, which the caller must
+// treat as a failure rather than a pass -- a golden that silently disappears
+// would otherwise turn this check into a no-op.
+inline const GoldenRows &goldens()
+{
+    static GoldenRows rows;
+    static bool loaded = false;
+    if (loaded) {
+        return rows;
+    }
+    loaded = true;
+
+#ifdef NOTE_C_SINGLE_PRECISION
+    const char *file = J_TEST_DATA_DIR "/corpus_golden_single.tsv";
+#else
+    const char *file = J_TEST_DATA_DIR "/corpus_golden.tsv";
+#endif
+    FILE *f = fopen(file, "r");
+    if (f == NULL) {
+        return rows;
+    }
+
+    std::string line;
+    int c;
+    while ((c = fgetc(f)) != EOF) {
+        if (c != '\n') {
+            line += (char)c;
+            continue;
+        }
+        if (!line.empty() && (line[0] != '#')) {
+            size_t t1 = line.find('\t');
+            size_t t2 = (t1 == std::string::npos) ? std::string::npos : line.find('\t', t1 + 1);
+            if (t2 != std::string::npos) {
+                rows.push_back(std::make_pair(line.substr(0, t2),
+                                              goldenUnescape(line.substr(t2 + 1))));
+            }
+        }
+        line.clear();
+    }
+    fclose(f);
+    return rows;
+}
+
+// The recorded rendering for a (document, mode), or NULL if there is none.
+inline const std::string *goldenFor(const char *doc, const char *mode)
+{
+    const std::string key = std::string(doc) + "\t" + mode;
+    const GoldenRows &rows = goldens();
+    for (size_t i = 0; i < rows.size(); ++i) {
+        if (rows[i].first == key) {
+            return &rows[i].second;
+        }
+    }
+    return NULL;
+}
+
+// ---------------------------------------------------------------------------
+// Deliberate deviations from the historical output
+//
+// Two printer bugs were fixed alongside the layout work, so a handful of
+// documents legitimately render differently than the recorded goldens. Each one
+// is listed here with its reason, and the suite asserts that the row STILL
+// differs -- so if a fix is ever reverted, the exception fails rather than
+// quietly starting to match again.
+//
+// Nothing gets added to this table to make a test pass. A new entry is a claim
+// that the shipped implementation was wrong, and needs the evidence to match.
+// ---------------------------------------------------------------------------
+
+struct GoldenException {
+    const char *doc;
+    const char *mode;    // NULL matches every mode
+    bool historicalOutputIsInvalidJson;
+    const char *why;
+};
+
+inline const std::vector<GoldenException> &goldenExceptions()
+{
+    static const std::vector<GoldenException> e = {
+        // _print_string_ptr advanced the output pointer by 4 after writing the
+        // 'u' and four hex digits of a \uXXXX escape, i.e. one byte short of
+        // the five it had emitted. Every escape after the first therefore
+        // overwrote the one before it and the string was left unterminated.
+        // The historical output for these is not merely different, it is not
+        // JSON: it fails to reparse.
+        {
+            "escapes-control", NULL, true,
+            "historical _print_string_ptr truncated after the first \\uXXXX escape"
+        },
+        {
+            "escapes-mixed", NULL, true,
+            "historical _print_string_ptr truncated after the first \\uXXXX escape"
+        },
+        {
+            "escaped-key", NULL, true,
+            "historical _print_string_ptr truncated after the first \\uXXXX escape"
+        },
+
+        // _print_object emitted a member's indentation before deciding whether
+        // omitempty elided that member, leaving orphaned whitespace and a
+        // rendering that was not a fixed point under reparse-and-reprint. Only
+        // the formatted+omitempty mode indents, so only it is affected.
+        {
+            "all-falsy", "formatted-omitempty", false,
+            "historical _print_object indented members that omitempty then elided"
+        },
+        {
+            "falsy-around", "formatted-omitempty", false,
+            "historical _print_object indented members that omitempty then elided"
+        },
+        {
+            "nested-falsy", "formatted-omitempty", false,
+            "historical _print_object indented members that omitempty then elided"
+        },
+        {
+            "many-members", "formatted-omitempty", false,
+            "historical _print_object indented members that omitempty then elided"
+        },
+    };
+    return e;
+}
+
+inline const GoldenException *goldenExceptionFor(const char *doc, const char *mode)
+{
+    const std::vector<GoldenException> &e = goldenExceptions();
+    for (size_t i = 0; i < e.size(); ++i) {
+        if ((strcmp(e[i].doc, doc) == 0)
+                && ((e[i].mode == NULL) || (strcmp(e[i].mode, mode) == 0))) {
+            return &e[i];
+        }
+    }
+    return NULL;
+}
+
+// ---------------------------------------------------------------------------
+// Output digest
+//
+// FNV-1a over every byte every corpus document renders to, in a fixed order.
+// One constant that both builds must agree on, so a rendering change fails the
+// build that caused it instead of only showing up in a cross-build diff.
+// ---------------------------------------------------------------------------
+
+inline uint64_t fnv1a(uint64_t h, const char *s)
+{
+    while (*s) {
+        h ^= (unsigned char)*s++;
+        h *= 1099511628211ULL;
+    }
+    return h;
+}
+
+inline uint64_t fnv1aSeed()
+{
+    return 1469598103934665603ULL;
+}
+
+// The digest both layouts must produce. Overridable from the build so the value
+// can be regenerated deliberately when the corpus changes.
+#ifndef J_LAYOUT_EXPECTED_DIGEST
+#ifdef NOTE_C_SINGLE_PRECISION
+#define J_LAYOUT_EXPECTED_DIGEST 13861798192606499111ULL
+#else
+#define J_LAYOUT_EXPECTED_DIGEST 17055881978828097657ULL
+#endif
+#endif
+
+// ---------------------------------------------------------------------------
+// Report file
+//
+// One tab-separated row per (document, mode). The A/B script diffs the output
+// column across builds and tabulates the memory columns.
+// ---------------------------------------------------------------------------
+
+class Report
+{
+public:
+    Report()
+    {
+        const char *path = getenv("J_LAYOUT_REPORT");
+        if (path != NULL) {
+            f = fopen(path, "w");
+        }
+        if (f != NULL) {
+            fprintf(f, "# layout=%s sizeof_J=%zu\n", layoutName(), sizeof(J));
+            fprintf(f, "#doc\tmode\tallocs\tbytes\tnodes\ttextlen\traw32\tdlmalloc\tfreertos\tnano\toutput\n");
+        }
+    }
+    ~Report()
+    {
+        if (f != NULL) {
+            fclose(f);
+        }
+    }
+
+    void row(const char *doc, const char *mode, size_t allocs, size_t bytes,
+             size_t nodes, const ChunkTotals &t, const char *output)
+    {
+        if (f == NULL) {
+            return;
+        }
+        fprintf(f, "%s\t%s\t%zu\t%zu\t%zu\t%zu\t%zu\t%zu\t%zu\t%zu\t",
+                doc, mode, allocs, bytes, nodes, strlen(output),
+                t.raw, t.dlmalloc, t.freertos, t.nano);
+        for (const char *p = output; *p; ++p) {
+            /* keep the row on one line and byte-exact */
+            if (*p == '\n') {
+                fputs("\\n", f);
+            } else if (*p == '\t') {
+                fputs("\\t", f);
+            } else if (*p == '\\') {
+                fputs("\\\\", f);
+            } else {
+                fputc(*p, f);
+            }
+        }
+        fputc('\n', f);
+        fflush(f);   /* so a crash still leaves a usable partial report */
+    }
+
+    void summary(const char *key, size_t value)
+    {
+        if (f != NULL) {
+            fprintf(f, "@%s\t%zu\n", key, value);
+        }
+    }
+
+private:
+    FILE *f = NULL;
+};
+
+inline Report &report()
+{
+    static Report r;
+    return r;
+}
+
+// ---------------------------------------------------------------------------
+// Tree walking
+// ---------------------------------------------------------------------------
+
+inline void collectNodes(const J *j, std::vector<const void *> &out)
+{
+    for (; j != NULL; j = j->next) {
+        out.push_back((const void *)j);
+        if (j->child != NULL) {
+            collectNodes(j->child, out);
+        }
+    }
+}
+
+inline size_t countNodes(const J *j)
+{
+    size_t n = 0;
+    for (; j != NULL; j = j->next) {
+        ++n;
+        if (j->child != NULL) {
+            n += countNodes(j->child);
+        }
+    }
+    return n;
+}
+
+} // namespace jlayout
diff --git a/test/src/JLayout_test.cpp b/test/src/JLayout_test.cpp
new file mode 100644
index 00000000..6ae545b5
--- /dev/null
+++ b/test/src/JLayout_test.cpp
@@ -0,0 +1,1014 @@
+/*!
+ * @file JLayout_test.cpp
+ *
+ * Validates the packed `J` layout (NOTE_C_STORAGE_OPTIMIZATION) against the
+ * historical one, which is the default. Every assertion here holds in BOTH
+ * builds: the layout difference must be invisible to every observable behavior.
+ * See test/include/j_layout_test_support.hpp for how the A/B comparison is
+ * wired, and docs/architecture/decisions/0002-j-node-storage-layout.md for
+ * the specification.
+ *
+ * Written by the Blues Inc. team.
+ *
+ * Copyright (c) 2025 Blues Inc. MIT License. Use of this source code is
+ * governed by licenses granted by the copyright holder including that found in
+ * the
+ * <a href="https://github.com/blues/note-c/blob/master/LICENSE">LICENSE</a>
+ * file.
+ *
+ */
+
+#include <catch2/catch_test_macros.hpp>
+
+#include <cstddef>   // offsetof, for the layout-derived size expectations
+
+#include "j_layout_test_support.hpp"
+
+using namespace jlayout;
+
+namespace
+{
+
+// Deep structural comparison that does not rely on printing, so a print bug
+// cannot mask a tree bug. Compares type, key, value, and child/sibling shape.
+bool sameTree(const J *a, const J *b)
+{
+    while (true) {
+        if ((a == NULL) != (b == NULL)) {
+            return false;
+        }
+        if (a == NULL) {
+            return true;
+        }
+        if ((a->type & 0xFF) != (b->type & 0xFF)) {
+            return false;
+        }
+        if ((a->string == NULL) != (b->string == NULL)) {
+            return false;
+        }
+        if (a->string && strcmp(a->string, b->string) != 0) {
+            return false;
+        }
+        if ((a->valuestring == NULL) != (b->valuestring == NULL)) {
+            return false;
+        }
+        if (a->valuestring && strcmp(a->valuestring, b->valuestring) != 0) {
+            return false;
+        }
+        if ((a->type & 0xFF) == JNumber) {
+            if (a->valueint != b->valueint) {
+                return false;
+            }
+            if (a->valuenumber != b->valuenumber) {
+                return false;
+            }
+        }
+        if (!sameTree(a->child, b->child)) {
+            return false;
+        }
+        a = a->next;
+        b = b->next;
+    }
+}
+
+SCENARIO("J layout: every corpus document round-trips and its cost is recorded")
+{
+    installTrackedAllocator();
+
+    uint64_t digest = fnv1aSeed();
+    size_t totalAllocs = 0;
+    size_t totalBytes = 0;
+    size_t totalNodes = 0;
+
+    for (const Doc &doc : corpus()) {
+        for (const Mode &mode : modes()) {
+            // Measure the cost of holding this document in memory: parse with a
+            // clean counter, then read the live totals before tearing down.
+            resetStats();
+            const size_t liveBytesBefore = stats().liveBytes;
+            const size_t liveBlocksBefore = stats().liveBlocks;
+
+            J *parsed = JParse(doc.json);
+            REQUIRE(parsed != NULL);
+
+            const size_t heldBytes = stats().liveBytes - liveBytesBefore;
+            const size_t heldBlocks = stats().liveBlocks - liveBlocksBefore;
+            const size_t nodes = countNodes(parsed);
+            std::vector<const void *> nodePtrs;
+            collectNodes(parsed, nodePtrs);
+            const ChunkTotals chunks = chunkTotals(nodePtrs);
+
+            char *printed = (char *)_print(parsed, mode.format, mode.omitempty);
+            REQUIRE(printed != NULL);
+
+            // 0. The output must match what the SHIPPED implementation
+            //    rendered. Everything else in this suite compares the rewrite
+            //    against itself -- across layouts, or against a digest computed
+            //    from its own output -- and so cannot see a regression that
+            //    both layouts share. This row comes from a pristine
+            //    `git archive` build recorded by
+            //    scripts/generate_corpus_golden.sh.
+            {
+                const std::string *golden = goldenFor(doc.name, mode.name);
+                INFO("golden lookup for " << doc.name << "/" << mode.name);
+                REQUIRE(golden != NULL);   // a missing golden is a failure,
+                // never a silently skipped check
+
+                const GoldenException *ex = goldenExceptionFor(doc.name, mode.name);
+                if (ex == NULL) {
+                    CHECK(*golden == printed);
+                } else {
+                    INFO("deliberate deviation: " << ex->why);
+                    // Still different, so reverting the fix fails here rather
+                    // than silently re-matching the historical output.
+                    CHECK(*golden != printed);
+                    if (ex->historicalOutputIsInvalidJson) {
+                        // The strongest form of the claim: what shipped could
+                        // not be reparsed, and what we emit now can.
+                        J *historical = JParse(golden->c_str());
+                        CHECK(historical == NULL);
+                        JDelete(historical);
+                    }
+                }
+            }
+
+            // 1. The output must be valid JSON.
+            J *reparsed = JParse(printed);
+            REQUIRE(reparsed != NULL);
+
+            // 2. Printing the reparsed tree must reproduce the text exactly.
+            //    This catches damage that would still parse.
+            //
+            //    Skipped only for documents whose numbers cannot survive a
+            //    text->float->text round trip in a NOTE_C_SINGLE_PRECISION
+            //    build. That is pre-existing numeric-conversion behavior,
+            //    identical in both layouts.
+            //
+            //    formatted+omitempty IS checked here. It used not to be a fixed
+            //    point, because _print_object emitted a member's indentation
+            //    before deciding whether omitempty elided it; that is fixed.
+            char *reprinted = (char *)_print(reparsed, mode.format, mode.omitempty);
+            REQUIRE(reprinted != NULL);
+            const bool lossy = numbersAreLossy(doc);
+            if (!lossy) {
+                CHECK(std::string(reprinted) == printed);
+            }
+
+            // 3. For the non-omitempty modes the reparsed tree must be
+            //    structurally identical to the original. (omitempty renders a
+            //    strict subset, so the trees legitimately differ there.)
+            if (!mode.omitempty && !lossy) {
+                CHECK(sameTree(parsed, reparsed));
+            }
+
+            // 4. JDuplicate must produce an independent, equal tree. This is the
+            //    path where a shared inline key would dangle.
+            J *dup = JDuplicate(parsed, true);
+            REQUIRE(dup != NULL);
+            CHECK(sameTree(parsed, dup));
+            char *dupPrinted = (char *)_print(dup, mode.format, mode.omitempty);
+            REQUIRE(dupPrinted != NULL);
+            CHECK(std::string(dupPrinted) == printed);
+            // Free the original FIRST, then use the duplicate: if the duplicate
+            // had borrowed storage from the original, this reads freed memory
+            // and the sanitizer build catches it.
+            JDelete(parsed);
+            parsed = NULL;
+            CHECK(std::string(dupPrinted) == printed);
+            char *dupAgain = (char *)_print(dup, mode.format, mode.omitempty);
+            REQUIRE(dupAgain != NULL);
+            CHECK(std::string(dupAgain) == printed);
+
+            if (!lossy) {
+                digest = fnv1a(digest, doc.name);
+                digest = fnv1a(digest, mode.name);
+                digest = fnv1a(digest, printed);
+            }
+
+            totalAllocs += heldBlocks;
+            totalBytes += heldBytes;
+            totalNodes += nodes;
+
+            report().row(doc.name, mode.name, heldBlocks, heldBytes, nodes, chunks, printed);
+
+            JFree(dupAgain);
+            JFree(dupPrinted);
+            JDelete(dup);
+            JFree(reprinted);
+            JDelete(reparsed);
+            JFree(printed);
+        }
+    }
+
+    report().summary("total_allocs", totalAllocs);
+    report().summary("total_bytes", totalBytes);
+    report().summary("total_nodes", totalNodes);
+    report().summary("sizeof_J", sizeof(J));
+
+    // Nothing may outlive the loop.
+    THEN("No allocation leaks across the whole corpus") {
+        CHECK(stats().liveBlocks == 0);
+        CHECK(stats().liveBytes == 0);
+    }
+
+    // A single constant both builds must agree on. If this fires, the two
+    // layouts have diverged in what they render and the cross-build diff will
+    // say exactly where.
+    THEN("The rendering digest matches the layout-independent expectation") {
+        INFO("layout=" << layoutName() << " sizeof(J)=" << sizeof(J)
+             << " digest=" << digest << "ULL");
+        CHECK(digest == J_LAYOUT_EXPECTED_DIGEST);
+    }
+
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+SCENARIO("J layout: ownership and inline storage invariants")
+{
+    installTrackedAllocator();
+
+    GIVEN("A parsed object whose key and value are both short") {
+        J *obj = JParse("{\"k\":\"v\"}");
+        REQUIRE(obj != NULL);
+        J *member = obj->child;
+        REQUIRE(member != NULL);
+
+        THEN("The key and value read back correctly regardless of where they live") {
+            CHECK(std::string(member->string) == "k");
+            CHECK(std::string(member->valuestring) == "v");
+        }
+
+        THEN("The packed build stores BOTH the key and the value in the node") {
+            if (isPacked()) {
+                // The parser measures the key, looks ahead to measure a string
+                // value, and sizes one allocation for the node plus both. A
+                // short string member therefore costs exactly one allocation.
+                CHECK(insideNodeAllocation(member, member->string));
+                CHECK(insideNodeAllocation(member, member->valuestring));
+                CHECK((member->type & JStringIsConst) != 0);
+                CHECK((member->type & JValueInline) != 0);
+                // Value first, then key, both inside the numeric-member region.
+                CHECK(member->valuestring < member->string);
+            } else {
+                CHECK_FALSE(insideNodeAllocation(member, member->string));
+                CHECK_FALSE(insideNodeAllocation(member, member->valuestring));
+                CHECK((member->type & JStringIsConst) == 0);
+                CHECK((member->type & JValueInline) == 0);
+            }
+        }
+
+        THEN("The whole member costs one allocation in the packed build") {
+            // {"k":"v"} is a root object node plus one member node. Packed:
+            // two allocations total. Unpacked: two nodes plus a key block plus
+            // a value block.
+            CHECK(stats().liveBlocks == (isPacked() ? 2u : 4u));
+        }
+
+        JDelete(obj);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A string built with JCreateString") {
+        resetStats();
+        J *item = JCreateString("packed into the node");
+        REQUIRE(item != NULL);
+
+        THEN("The packed build holds the value in the node's own allocation") {
+            CHECK(std::string(item->valuestring) == "packed into the node");
+            if (isPacked()) {
+                CHECK(insideNodeAllocation(item, item->valuestring));
+                CHECK((item->type & JValueInline) != 0);
+                CHECK(stats().mallocCalls == 1);   // node+value in ONE block
+            } else {
+                CHECK_FALSE(insideNodeAllocation(item, item->valuestring));
+                CHECK((item->type & JValueInline) == 0);
+                CHECK(stats().mallocCalls == 2);   // node, then value
+            }
+        }
+
+        JDelete(item);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A node whose number pair is written after it was given a key") {
+        // The numeric pair IS the inline character buffer -- see the comment on
+        // those members in n_cjson.h -- so writing a number to a node that is
+        // currently holding a packed key or value has to evacuate that content
+        // first. JSetNumberValue and JSetIntValue are function calls precisely
+        // so the library gets the chance; the historical macros wrote the
+        // members directly from the caller's translation unit and would have
+        // destroyed the key. This pins the evacuation.
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        J *sub = JCreateObject();
+        REQUIRE(sub != NULL);
+        JAddItemToObject(root, "key", sub);
+        JSetNumberValue(sub, 72623859790382864.0);
+
+        THEN("The key is intact") {
+            char *out = JPrintUnformatted(root);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"key\":{}}");
+            JFree(out);
+        }
+
+        JDelete(root);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A member moved between objects while keeping its own name") {
+        // Regression guard: the documented idiom passes the node's own key back
+        // in, so a key setter that frees before copying is a use-after-free.
+        J *a = JCreateObject();
+        J *b = JCreateObject();
+        J *c = JCreateObject();
+        REQUIRE(a != NULL);
+        REQUIRE(b != NULL);
+        REQUIRE(c != NULL);
+        JAddItemToObject(a, "member", JCreateObject());
+
+        J *d1 = JDetachItemFromObject(a, "member");
+        REQUIRE(d1 != NULL);
+        JAddItemToObject(b, JGetItemName(d1), d1);
+        J *d2 = JDetachItemFromObject(b, "member");
+        REQUIRE(d2 != NULL);
+        JAddItemToObject(c, JGetItemName(d2), d2);
+
+        THEN("The name survives every move") {
+            char *out = JPrintUnformatted(c);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"member\":{}}");
+            JFree(out);
+        }
+
+        JDelete(a);
+        JDelete(b);
+        JDelete(c);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A parsed object whose value exceeds the inline capacity") {
+        J *obj = JParse("{\"k\":\"0123456789abcdefghijklmnop\"}");
+        REQUIRE(obj != NULL);
+        J *member = obj->child;
+        REQUIRE(member != NULL);
+
+        THEN("The value still reads back correctly") {
+            CHECK(std::string(member->valuestring) == "0123456789abcdefghijklmnop");
+        }
+
+        JDelete(obj);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A number whose key would otherwise fit inline") {
+        // This node is a number, so valueint and valuenumber are LIVE and the
+        // inline region is not available: the key can only go in bytes past
+        // the struct. This is the case that would corrupt a key if the inline
+        // heuristic were too eager.
+        J *obj = JParse("{\"count\":1234567890123456789}");
+        REQUIRE(obj != NULL);
+        J *member = obj->child;
+        REQUIRE(member != NULL);
+
+        THEN("Both the key and the full-precision integer survive") {
+            CHECK(std::string(member->string) == "count");
+            CHECK(member->valueint == 1234567890123456789LL);
+            CHECK(JIntValue(member) == 1234567890123456789LL);
+        }
+
+        JDelete(obj);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A programmatically built object using the generic add") {
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        J *body = JCreateObject();
+        REQUIRE(body != NULL);
+
+        // The idiom that forbids relocating the node on add: the caller keeps
+        // using `body` afterwards.
+        JAddItemToObject(root, "body", body);
+        // An integer, so the expectation holds under NOTE_C_SINGLE_PRECISION too.
+        JAddNumberToObject(body, "temp", 22);
+        JAddStringToObject(body, "unit", "C");
+
+        THEN("The retained pointer is still valid and the tree is correct") {
+            char *out = JPrintUnformatted(root);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"body\":{\"temp\":22,\"unit\":\"C\"}}");
+            JFree(out);
+        }
+
+        JDelete(root);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("An item whose key is replaced after creation") {
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        JAddStringToObject(root, "short", "v");
+
+        WHEN("The member is replaced with a much longer key") {
+            J *repl = JCreateString("w");
+            REQUIRE(repl != NULL);
+            JReplaceItemInObject(root, "short", repl);
+
+            THEN("The object reflects the replacement without leaking") {
+                char *out = JPrintUnformatted(root);
+                REQUIRE(out != NULL);
+                CHECK(std::string(out) == "{\"short\":\"w\"}");
+                JFree(out);
+            }
+        }
+
+        JDelete(root);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A constant key added with JAddItemToObjectCS") {
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        static const char kKey[] = "constant";
+        JAddItemToObjectCS(root, kKey, JCreateNumber(1));
+
+        THEN("The key is borrowed, not copied, and is not freed") {
+            REQUIRE(root->child != NULL);
+            CHECK(root->child->string == kKey);
+            CHECK((root->child->type & JStringIsConst) != 0);
+        }
+
+        JDelete(root);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("A string item created from a caller-owned heap buffer") {
+        // JCreateStringValue ADOPTS the pointer -- JAddBinaryToObject relies on
+        // JDelete freeing it -- so it must never be inlined or borrowed.
+        char *owned = (char *)JMalloc(8);
+        REQUIRE(owned != NULL);
+        strcpy(owned, "adopted");
+        J *item = JCreateStringValue(owned);
+        REQUIRE(item != NULL);
+
+        THEN("The node points at the caller's buffer and takes ownership") {
+            CHECK(item->valuestring == owned);
+            CHECK((item->type & JIsReference) == 0);
+        }
+
+        JDelete(item);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("Detaching a member and re-adding it under a different key") {
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        JAddStringToObject(root, "first", "value");
+        J *detached = JDetachItemFromObject(root, "first");
+        REQUIRE(detached != NULL);
+
+        J *other = JCreateObject();
+        REQUIRE(other != NULL);
+        JAddItemToObject(other, "second", detached);
+
+        THEN("The new key wins and the old inline key is harmlessly abandoned") {
+            char *out = JPrintUnformatted(other);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"second\":\"value\"}");
+            JFree(out);
+        }
+
+        JDelete(root);
+        JDelete(other);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+SCENARIO("Formatted omit-empty output carries no orphaned indentation")
+{
+    installTrackedAllocator();
+
+    // Regression guard: _print_object used to emit a member's indentation
+    // before deciding whether omitempty elided it, so every elided member left
+    // whitespace behind and consumed buffer the caller had not budgeted for.
+    struct Case {
+        const char *json;
+        const char *expected;
+    };
+    static const Case cases[] = {
+        { "{\"a\":0}",                              "{\n}" },
+        { "{\"a\":0,\"b\":1,\"c\":0}",              "{\n    \"b\": 1\n}" },
+        { "{\"a\":false,\"b\":\"\",\"c\":\"x\"}",    "{\n    \"c\": \"x\"\n}" },
+        { "{\"o\":{\"a\":0,\"b\":2},\"k\":1,\"d\":0}", "{\n    \"o\": {\n        \"b\": 2\n    },\n    \"k\": 1\n}" },
+    };
+
+    for (size_t i = 0; i < sizeof(cases) / sizeof(cases[0]); ++i) {
+        J *j = JParse(cases[i].json);
+        REQUIRE(j != NULL);
+
+        WHEN(std::string("rendering ") + cases[i].json) {
+            char *out = (char *)_print(j, true, true);
+            REQUIRE(out != NULL);
+
+            THEN("No whitespace is emitted for an elided member") {
+                CHECK(std::string(out) == cases[i].expected);
+            }
+            THEN("The rendering is a fixed point under reparse and reprint") {
+                J *re = JParse(out);
+                REQUIRE(re != NULL);
+                char *again = (char *)_print(re, true, true);
+                REQUIRE(again != NULL);
+                CHECK(std::string(again) == out);
+                JFree(again);
+                JDelete(re);
+            }
+
+            JFree(out);
+        }
+
+        JDelete(j);
+    }
+
+    CHECK(stats().liveBlocks == 0);
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+SCENARIO("Numeric setters are functions, not member-poking macros")
+{
+    installTrackedAllocator();
+
+    GIVEN("An integer too large for a double") {
+        J *n = JCreateNumber(0);
+        REQUIRE(n != NULL);
+        JINTEGER ret = JSetIntValue(n, 9007199254740993LL);
+
+        THEN("It rounds through the double exactly as the historical macro did") {
+            // The historical macro expanded to
+            //   valueint = valuenumber = number
+            // which parses as valueint = (valuenumber = number), so the operand
+            // reached valueint only AFTER a trip through JNUMBER: 2^53+1 comes
+            // back as 2^53.
+            //
+            // Assigning valueint straight from a JINTEGER parameter would keep
+            // the extra bit, which is arguably better -- and is exactly why this
+            // test exists. That change also truncates a FRACTIONAL operand at
+            // the call site, silently turning JSetIntValue(n, 1.5) into
+            // valuenumber == 1 where it had always been 1.5. The two behaviors
+            // are the same one-line decision, so the historical rounding is
+            // pinned here rather than improved on.
+            //
+            // Verified against a pristine `git archive HEAD` build, which
+            // produces 9007199254740992 for all three of these.
+            CHECK(ret == 9007199254740992LL);
+            CHECK(n->valueint == 9007199254740992LL);
+            CHECK(JIntValue(n) == 9007199254740992LL);
+        }
+        THEN("valuenumber is still kept in step") {
+            CHECK(n->valuenumber == (JNUMBER)9007199254740993LL);
+        }
+
+        JDelete(n);
+    }
+
+    GIVEN("A fractional setter argument") {
+        J *n = JCreateNumber(0);
+        REQUIRE(n != NULL);
+        JSetIntValue(n, 1.5);
+
+        THEN("valueint truncates and valuenumber keeps the fraction") {
+            // The other half of the same decision. See above.
+            CHECK(n->valueint == 1);
+            CHECK(n->valuenumber == (JNUMBER)1.5);
+        }
+
+        JDelete(n);
+    }
+
+    GIVEN("A setter argument with a side effect") {
+        J *n = JCreateNumber(0);
+        REQUIRE(n != NULL);
+        int calls = 0;
+        JSetIntValue(n, ++calls);
+
+        THEN("It is evaluated exactly once") {
+            CHECK(calls == 1);
+        }
+
+        JDelete(n);
+    }
+
+    GIVEN("A NULL item") {
+        THEN("Both setters remain NULL-safe and return the value") {
+            CHECK(JSetIntValue((J *)NULL, 7) == 7);
+            CHECK(JSetNumberValue((J *)NULL, 7.5) == 7.5);
+        }
+    }
+
+    GIVEN("An object member") {
+        J *o = JCreateObject();
+        REQUIRE(o != NULL);
+        REQUIRE(JAddNumberToObject(o, "field", 1) != NULL);
+
+        THEN("JGetObjectItemName reports the key without touching the struct") {
+            CHECK(std::string(JGetObjectItemName(o->child)) == "field");
+        }
+
+        JDelete(o);
+    }
+
+    CHECK(stats().liveBlocks == 0);
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+SCENARIO("Re-keying an item with its own key is never a use-after-free")
+{
+    installTrackedAllocator();
+
+    // Both add paths must tolerate `key` aliasing the node's current key. This
+    // is the documented "move a member, keep its name" idiom, and it was a
+    // use-after-free on master through JAddItemToObjectCS.
+    struct Path {
+        const char *name;
+        bool constantKey;
+    };
+    static const Path paths[] = {
+        { "JAddItemToObject", false },
+        { "JAddItemToObjectCS", true },
+    };
+
+    for (size_t i = 0; i < sizeof(paths) / sizeof(paths[0]); ++i) {
+        WHEN(std::string("moving a member via ") + paths[i].name) {
+            J *a = JCreateObject();
+            J *b = JCreateObject();
+            J *c = JCreateObject();
+            REQUIRE(a != NULL);
+            REQUIRE(b != NULL);
+            REQUIRE(c != NULL);
+            REQUIRE(JAddStringToObject(a, "member", "v") != NULL);
+
+            // Three hops, because the storage class of the key can differ on
+            // each pass and only some passes take the aliasing branch.
+            J *cur = JDetachItemFromObject(a, "member");
+            REQUIRE(cur != NULL);
+            for (int hop = 0; hop < 3; ++hop) {
+                J *dst = (hop % 2) ? c : b;
+                if (paths[i].constantKey) {
+                    JAddItemToObjectCS(dst, JGetItemName(cur), cur);
+                } else {
+                    JAddItemToObject(dst, JGetItemName(cur), cur);
+                }
+                cur = JDetachItemFromObject(dst, "member");
+                REQUIRE(cur != NULL);
+            }
+
+            THEN("The key survives every hop intact") {
+                CHECK(std::string(JGetItemName(cur)) == "member");
+                CHECK(std::string(cur->valuestring) == "v");
+            }
+
+            JDelete(cur);
+            JDelete(a);
+            JDelete(b);
+            JDelete(c);
+        }
+    }
+
+    CHECK(stats().liveBlocks == 0);
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+SCENARIO("The packing actually happens")
+{
+    installTrackedAllocator();
+
+    // These assert the OPTIMIZATION, not just correctness. Everything else in
+    // this file passes just as happily with packing disabled, so without these
+    // the layout could silently stop packing and no test would notice.
+    // Mutation-checked: each case below fails if the corresponding mechanism is
+    // removed.
+
+    struct Case {
+        const char *what;
+        const char *json;
+        size_t packedAllocs;      // parse path
+        size_t unpackedAllocs;
+        // Each member's key and value length, INCLUDING the NUL. Every member
+        // in a given case has the same shape. The expected node size is derived
+        // from these rather than hardcoded, because the size of the inline
+        // region is not the same on every ABI: JINTEGER is 8-byte aligned on
+        // ARM and x86-64 but only 4-byte aligned on i386, so the same layout
+        // yields a different sizeof(J) and a different amount of room before
+        // the struct ends. Hardcoding "fits in sizeof(J)" passed everywhere the
+        // region is 16 bytes and failed on 32-bit Linux, where it is 12.
+        bool   memberIsString;
+        size_t memberKeyLen;
+        size_t memberValLen;
+    };
+    static const Case parsed[] = {
+        // node+key+value in ONE allocation. Fails if the parser's value
+        // lookahead is removed, or if _j_alloc_size stops using the inline
+        // region as the string base.
+        { "short string member",   "{\"a\":\"b\"}",            2, 4,  true,  2,  2 },
+        { "empty string value",    "{\"a\":\"\"}",             2, 4,  true,  2,  1 },
+        { "realistic member",      "{\"aqi_level\":\"good\"}",  2, 4,  true, 10,  5 },
+        // node+key in one allocation; the number occupies the inline region.
+        { "number member",         "{\"temperature\":22.5}",   2, 3,  false, 12,  0 },
+        // three members, each self-contained.
+        { "three string members",  "{\"a\":\"\",\"b\":\"\",\"c\":\"\"}", 4, 10, true,  2,  1 },
+    };
+
+    for (size_t i = 0; i < sizeof(parsed) / sizeof(parsed[0]); ++i) {
+        WHEN(std::string("parsing ") + parsed[i].what) {
+            resetStats();
+            const size_t before = stats().liveBlocks;
+            J *j = JParse(parsed[i].json);
+            REQUIRE(j != NULL);
+            const size_t used = stats().liveBlocks - before;
+
+            THEN("It costs exactly the expected number of allocations") {
+                CHECK(used == (isPacked() ? parsed[i].packedAllocs
+                               : parsed[i].unpackedAllocs));
+            }
+
+            THEN("Each node is exactly the size its content requires") {
+                // Counting allocations is not enough: a layout that packs into
+                // an over-sized node makes the same number of allocations and
+                // costs more memory. This pins the exact allocation formula.
+                //
+                // A string member's content starts at the inline region and the
+                // node grows only if it overflows the struct; a number member
+                // keeps its numeric fields, so its key always extends past the
+                // struct by exactly its own length.
+                if (isPacked()) {
+                    const size_t inlineOff = offsetof(J, valueint);
+                    size_t expected;
+                    if (parsed[i].memberIsString) {
+                        expected = inlineOff + parsed[i].memberValLen
+                                   + parsed[i].memberKeyLen;
+                        if (expected < sizeof(J)) {
+                            expected = sizeof(J);
+                        }
+                    } else {
+                        expected = sizeof(J) + parsed[i].memberKeyLen;
+                    }
+                    for (J *n = j->child; n != NULL; n = n->next) {
+                        INFO("sizeof(J)=" << sizeof(J)
+                             << " inline region=" << (sizeof(J) - inlineOff));
+                        CHECK(nodeAllocSize(n) == expected);
+                    }
+                }
+            }
+
+            JDelete(j);
+        }
+    }
+
+    // Construction path: every JAdd<T>ToObject sizes its node for the key.
+    // Fails if _j_new_keyed stops passing the key length.
+    WHEN("building members with the JAdd*ToObject helpers") {
+        struct Built {
+            const char *what;
+            size_t packed;
+            size_t unpacked;
+        };
+        resetStats();
+        size_t before = stats().liveBlocks;
+        J *o1 = JCreateObject();
+        JAddNumberToObject(o1, "temperature", 22.5);
+        size_t numberCost = stats().liveBlocks - before;
+
+        before = stats().liveBlocks;
+        J *o2 = JCreateObject();
+        JAddBoolToObject(o2, "charging", true);
+        size_t boolCost = stats().liveBlocks - before;
+
+        before = stats().liveBlocks;
+        J *o3 = JCreateObject();
+        JAddStringToObject(o3, "aqi_level", "good");
+        size_t stringCost = stats().liveBlocks - before;
+
+        THEN("The key is carved out of the node rather than allocated") {
+            // object node + member node, and nothing else, when packed.
+            CHECK(numberCost == (isPacked() ? 2u : 3u));
+            CHECK(boolCost   == (isPacked() ? 2u : 3u));
+            CHECK(stringCost == (isPacked() ? 2u : 4u));
+        }
+
+        JDelete(o1);
+        JDelete(o2);
+        JDelete(o3);
+    }
+
+    // The numeric setters must evict inline content before writing the numeric
+    // members. Fails if _j_unpack_numeric_region becomes a no-op. This uses a
+    // STRING node, whose key and value both live in the numeric region -- the
+    // earlier regression guard used an object node, whose key lives past the
+    // struct and is therefore never at risk.
+    WHEN("writing a number over a string node whose key and value are inline") {
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        J *m = JAddStringToObject(root, "thekey", "thevalue");
+        REQUIRE(m != NULL);
+        if (isPacked()) {
+            REQUIRE(insideNodeAllocation(m, m->string));
+            REQUIRE(insideNodeAllocation(m, m->valuestring));
+        }
+
+        JSetNumberValue(m, 7.5);
+
+        THEN("The key survives the write") {
+            CHECK(std::string(JGetItemName(m)) == "thekey");
+        }
+        THEN("The value survives the write") {
+            CHECK(std::string(m->valuestring) == "thevalue");
+        }
+        THEN("The object still renders correctly") {
+            char *out = JPrintUnformatted(root);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"thekey\":\"thevalue\"}");
+            JFree(out);
+        }
+
+        JDelete(root);
+    }
+
+    // A reference node must not inherit the source's packing state. Fails if
+    // _create_reference stops resetting objlen/JValueInline: the key offset is
+    // then computed by subtracting pointers into two different allocations.
+    WHEN("adding a reference to a string node that has an inline value") {
+        for (int i = 0; i < 200; ++i) {
+            J *src = JCreateString("a string value");
+            REQUIRE(src != NULL);
+            J *obj = JCreateObject();
+            REQUIRE(obj != NULL);
+            JAddItemReferenceToObject(obj, "akey", src);
+
+            if (isPacked()) {
+                REQUIRE(obj->child != NULL);
+                // The reference describes its own allocation, not the source's.
+                CHECK(nodeAllocSize(obj->child) == sizeof(J));
+                CHECK((obj->child->type & JValueInline) == 0);
+            }
+
+            char *out = JPrintUnformatted(obj);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"akey\":\"a string value\"}");
+            JFree(out);
+            JDelete(obj);
+            JDelete(src);
+        }
+    }
+
+    // The allocation cap must hold: a node that would exceed it falls back to
+    // heap storage rather than truncating objlen. Fails if the cap is removed.
+    WHEN("a value is far larger than the allocation cap") {
+        std::string huge(60000, 'x');
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        J *m = JAddStringToObject(root, "k", huge.c_str());
+        REQUIRE(m != NULL);
+
+        THEN("The value is intact and stored outside the node") {
+            CHECK(std::string(m->valuestring) == huge);
+            CHECK_FALSE(insideNodeAllocation(m, m->valuestring));
+            if (isPacked()) {
+                // The node must fall all the way back to a bare struct. Merely
+                // checking objlen <= J_MAX_PACKED_ALLOC would pass for a node
+                // that packed 60 KB inline, which is exactly what removing the
+                // cap does.
+                CHECK(nodeAllocSize(m) == sizeof(J));
+            }
+        }
+
+        JDelete(root);
+    }
+
+    // The cap must also catch a node whose key and value are each individually
+    // under the limit but whose SUM is over it. The operand guard alone does
+    // not cover this, and an unbounded sum truncates when stored in objlen.
+    WHEN("a key and a value are each under the cap but sum over it") {
+        std::string bigKey(40000, 'k');
+        std::string bigVal(40000, 'v');
+        J *root = JCreateObject();
+        REQUIRE(root != NULL);
+        J *m = JAddStringToObject(root, bigKey.c_str(), bigVal.c_str());
+        REQUIRE(m != NULL);
+
+        THEN("The node falls back to a bare struct with both on the heap") {
+            CHECK(std::string(m->valuestring) == bigVal);
+            CHECK(std::string(JGetItemName(m)) == bigKey);
+            if (isPacked()) {
+                CHECK(nodeAllocSize(m) == sizeof(J));
+            }
+        }
+
+        JDelete(root);
+    }
+
+    // Re-keying an item with its OWN key, where that key is on the heap rather
+    // than inline. This is the shape the historical use-after-free needed: a
+    // key short enough to be re-keyed but long enough not to fit in the node.
+    // With an inline key the release is skipped and the hazard never arises,
+    // which is why the earlier scenario could not reach it.
+    WHEN("re-keying an item whose key is heap-allocated") {
+        std::string longKey(64, 'k');
+        J *a = JCreateObject();
+        J *b = JCreateObject();
+        REQUIRE(a != NULL);
+        REQUIRE(b != NULL);
+        // The GENERIC add, not JAddStringToObject: the latter sizes the node
+        // for its key, so even a 64-char key would land inline and the heap
+        // path would never be exercised. Here the node already exists at
+        // exactly sizeof(J), leaving no room for a key this long.
+        JAddItemToObject(a, longKey.c_str(), JCreateString("v"));
+
+        J *m = JDetachItemFromObject(a, longKey.c_str());
+        REQUIRE(m != NULL);
+        if (isPacked()) {
+            REQUIRE_FALSE(insideNodeAllocation(m, m->string));   // heap key
+        }
+
+        // Hand the node its own key back, through both add paths.
+        JAddItemToObject(b, JGetItemName(m), m);
+        J *m2 = JDetachItemFromObject(b, longKey.c_str());
+        REQUIRE(m2 != NULL);
+        JAddItemToObjectCS(b, JGetItemName(m2), m2);
+
+        THEN("The key is intact") {
+            CHECK(std::string(JGetItemName(m2)) == longKey);
+            char *out = JPrintUnformatted(b);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"" + longKey + "\":\"v\"}");
+            JFree(out);
+        }
+
+        JDelete(a);
+        JDelete(b);
+    }
+
+    CHECK(stats().liveBlocks == 0);
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+SCENARIO("J layout: key and value length sweep across the inline boundary")
+{
+    installTrackedAllocator();
+
+    // Walk every key length and every value length from 0 to well past the
+    // 16-byte inline capacity, in both the parsed and the programmatic path.
+    for (size_t keyLen = 1; keyLen <= 24; ++keyLen) {
+        for (size_t valLen = 0; valLen <= 24; ++valLen) {
+            std::string key(keyLen, 'k');
+            std::string val(valLen, 'v');
+            std::string json = "{\"" + key + "\":\"" + val + "\"}";
+
+            J *parsed = JParse(json.c_str());
+            REQUIRE(parsed != NULL);
+            J *member = parsed->child;
+            REQUIRE(member != NULL);
+            CHECK(std::string(member->string) == key);
+            CHECK(std::string(member->valuestring) == val);
+
+            char *out = JPrintUnformatted(parsed);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == json);
+            JFree(out);
+
+            // Same shape built programmatically, which takes a different
+            // storage path for the key.
+            J *built = JCreateObject();
+            REQUIRE(built != NULL);
+            REQUIRE(JAddStringToObject(built, key.c_str(), val.c_str()) != NULL);
+            char *builtOut = JPrintUnformatted(built);
+            REQUIRE(builtOut != NULL);
+            CHECK(std::string(builtOut) == json);
+            JFree(builtOut);
+
+            // And via the generic add of a pre-built item, which is the path
+            // that cannot pack the key at construction time.
+            J *generic = JCreateObject();
+            REQUIRE(generic != NULL);
+            JAddItemToObject(generic, key.c_str(), JCreateString(val.c_str()));
+            char *genericOut = JPrintUnformatted(generic);
+            REQUIRE(genericOut != NULL);
+            CHECK(std::string(genericOut) == json);
+            JFree(genericOut);
+
+            JDelete(parsed);
+            JDelete(built);
+            JDelete(generic);
+        }
+    }
+
+    THEN("The sweep leaks nothing") {
+        CHECK(stats().liveBlocks == 0);
+        CHECK(stats().liveBytes == 0);
+    }
+
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+}
diff --git a/test/src/JPublicApiCompat_test.cpp b/test/src/JPublicApiCompat_test.cpp
new file mode 100644
index 00000000..9a8b2193
--- /dev/null
+++ b/test/src/JPublicApiCompat_test.cpp
@@ -0,0 +1,629 @@
+/*!
+ * @file JPublicApiCompat_test.cpp
+ *
+ * Pins the observable behavior of the public `J` macros that were converted to
+ * function calls when NOTE_C_STORAGE_OPTIMIZATION was introduced.
+ *
+ * Converting a macro to a call is a silent source and behavior change unless
+ * every property callers could have depended on is reproduced: the result type,
+ * the result value, how many times each operand is evaluated, and the treatment
+ * of NULL. The expectations here were captured by running the same program
+ * against a pristine `git archive HEAD` build of the historical implementation,
+ * not derived from the current code -- an A/B between two builds of a rewrite
+ * cannot detect a change that both builds share.
+ *
+ * Every assertion holds in BOTH layouts. The file is C++ on purpose: it is also
+ * the compile-time guard on the signatures. In C, handing a `const char *` to a
+ * `char *` is a warning; in C++ it is ill-formed, so a regression that
+ * re-qualified JGetObjectItemName's result would fail this build outright.
+ *
+ * Written by the Blues Inc. team.
+ *
+ * Copyright (c) 2025 Blues Inc. MIT License. Use of this source code is
+ * governed by licenses granted by the copyright holder including that found in
+ * the
+ * <a href="https://github.com/blues/note-c/blob/master/LICENSE">LICENSE</a>
+ * file.
+ *
+ */
+
+#include <catch2/catch_test_macros.hpp>
+
+#include "n_lib.h"
+
+// The C half of this check, compiled as C with -Werror. See
+// test/src/j_public_api_compat_c.c for why a C++ translation unit alone is not
+// sufficient to pin these contracts.
+extern "C" int jPublicApiCompatC(void);
+
+namespace
+{
+
+// Counts how many times the value operand of a setter macro is evaluated.
+int operandEvaluations = 0;
+
+JNUMBER countedOperand(JNUMBER value)
+{
+    ++operandEvaluations;
+    return value;
+}
+
+// Counts how many times the object operand is evaluated. The historical
+// JSetIntValue macro named it three times; the current conditional-plus-call
+// form names it exactly twice, once in the test and once in the call.
+// JSetNumberValue already named it twice and is unchanged.
+int objectEvaluations = 0;
+
+J *countedObject(J *item)
+{
+    ++objectEvaluations;
+    return item;
+}
+
+SCENARIO("Public API compatibility: JSetIntValue")
+{
+    NoteSetFnDefault(malloc, free, NULL, NULL);
+
+    // The historical macro was
+    //     ((object) ? (object)->valueint = (object)->valuenumber = (number) : (number))
+    // which parses as `valueint = (valuenumber = number)`. Both members
+    // therefore saw the operand in its ORIGINAL arithmetic form, so a
+    // fractional operand landed truncated in valueint and intact in
+    // valuenumber. This is the property a JINTEGER parameter would destroy.
+    SECTION("A fractional operand truncates into valueint and survives in valuenumber") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        JSetIntValue(item, 1.5);
+        CHECK(item->valueint == 1);
+        CHECK(item->valuenumber == (JNUMBER)1.5);
+
+        // Truncation is toward zero, as a C conversion, not a floor.
+        JSetIntValue(item, -2.5);
+        CHECK(item->valueint == -2);
+        CHECK(item->valuenumber == (JNUMBER)-2.5);
+
+        JDelete(item);
+    }
+
+    SECTION("An integral operand lands in both members") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        JSetIntValue(item, 42);
+        CHECK(item->valueint == 42);
+        CHECK(item->valuenumber == (JNUMBER)42);
+
+        JSetIntValue(item, -42);
+        CHECK(item->valueint == -42);
+        CHECK(item->valuenumber == (JNUMBER)-42);
+
+        JDelete(item);
+    }
+
+    SECTION("An unsigned operand is not sign-mangled") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        // Exactly representable as both float and double, and past INT32_MAX,
+        // so a stray 32-bit intermediate would show up here.
+        JSetIntValue(item, 4000000000u);
+        CHECK(item->valueint == 4000000000LL);
+
+        JDelete(item);
+    }
+
+    SECTION("An out-of-range operand saturates rather than being undefined") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        // The historical macro's implicit JNUMBER-to-JINTEGER conversion was
+        // undefined here. Saturating matches JSetNumberValue, which has always
+        // done this, and is the one deliberate divergence: it only affects
+        // inputs for which the old macro had no defined result.
+        JSetIntValue(item, (JNUMBER)1e30);
+        CHECK(item->valueint == JINTEGER_MAX);
+
+        JSetIntValue(item, (JNUMBER)-1e30);
+        CHECK(item->valueint == JINTEGER_MIN);
+
+        JDelete(item);
+    }
+
+    SECTION("A NULL object is a no-op that returns the operand UNCONVERTED") {
+        // The historical macro short-circuited on NULL and yielded `(number)`
+        // itself -- not the helper's return type. So the NULL branch keeps the
+        // operand's value AND its type: 1.5 stays 1.5, as a double.
+        //
+        // Calling the helper unconditionally would yield 1 as a JINTEGER, and
+        // under NOTE_C_SINGLE_PRECISION would round the operand through a float
+        // on the way out. Verified against a pristine `git archive HEAD` build.
+        CHECK(JSetIntValue((J *)NULL, 42) == 42);
+        CHECK(JSetIntValue((J *)NULL, 1.5) == 1.5);
+        CHECK(JSetNumberValue((J *)NULL, 4.5) == 4.5);
+
+        // A value that is not exactly representable as a float, so a stray
+        // conversion through JNUMBER shows up here in a single-precision build.
+        CHECK(JSetIntValue((J *)NULL, 16777217.0) == 16777217.0);
+        CHECK(JSetNumberValue((J *)NULL, 16777217.0) == 16777217.0);
+    }
+
+    SECTION("The value operand is evaluated exactly once") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        operandEvaluations = 0;
+        JSetIntValue(item, countedOperand(7.25));
+        CHECK(operandEvaluations == 1);
+        CHECK(item->valueint == 7);
+        CHECK(item->valuenumber == (JNUMBER)7.25);
+
+        // Including on the NULL path, where the old macro took the other
+        // branch of the conditional but still evaluated `number` just once --
+        // and yielded it unconverted, so 7.25 rather than 7.
+        operandEvaluations = 0;
+        CHECK(JSetIntValue((J *)NULL, countedOperand(7.25)) == 7.25);
+        CHECK(operandEvaluations == 1);
+
+        JDelete(item);
+    }
+
+    SECTION("A side effect in the object operand is not lost") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        objectEvaluations = 0;
+        JSetIntValue(countedObject(item), 9);
+        CHECK(objectEvaluations == 2);      // was 3 historically
+        CHECK(item->valueint == 9);
+
+        objectEvaluations = 0;
+        JSetNumberValue(countedObject(item), 4.5);
+        CHECK(objectEvaluations == 2);      // unchanged from historical
+        CHECK(item->valuenumber == (JNUMBER)4.5);
+
+        JDelete(item);
+    }
+
+    SECTION("Setting a numeric value over a string item is safe") {
+        // Under NOTE_C_STORAGE_OPTIMIZATION the bytes of valueint and
+        // valuenumber may currently hold this item's packed value and key, so
+        // the setter has to evacuate them before writing. Nothing about that is
+        // visible from here except that the key survives and nothing leaks.
+        J *object = JCreateObject();
+        REQUIRE(object != NULL);
+        REQUIRE(JAddStringToObject(object, "key", "a string value") != NULL);
+
+        J *item = JGetObjectItem(object, "key");
+        REQUIRE(item != NULL);
+
+        JSetIntValue(item, 123);
+        CHECK(item->valueint == 123);
+        CHECK(strcmp(JGetItemName(item), "key") == 0);
+
+        JDelete(object);
+    }
+}
+
+SCENARIO("Public API compatibility: JSetNumberValue")
+{
+    NoteSetFnDefault(malloc, free, NULL, NULL);
+
+    SECTION("The value lands in both members") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        JSetNumberValue(item, 1.5);
+        CHECK(item->valuenumber == (JNUMBER)1.5);
+        CHECK(item->valueint == 1);
+
+        JDelete(item);
+    }
+
+    SECTION("An out-of-range value saturates valueint") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        JSetNumberValue(item, (JNUMBER)1e30);
+        CHECK(item->valueint == JINTEGER_MAX);
+        CHECK(item->valuenumber == (JNUMBER)1e30);
+
+        JSetNumberValue(item, (JNUMBER)-1e30);
+        CHECK(item->valueint == JINTEGER_MIN);
+
+        JDelete(item);
+    }
+
+    SECTION("A NULL object is a no-op that returns the operand") {
+        CHECK(JSetNumberValue((J *)NULL, 4.5) == (JNUMBER)4.5);
+    }
+
+    SECTION("The value operand is evaluated exactly once") {
+        J *item = JCreateNumber(0);
+        REQUIRE(item != NULL);
+
+        operandEvaluations = 0;
+        JSetNumberValue(item, countedOperand(3.5));
+        CHECK(operandEvaluations == 1);
+        CHECK(item->valuenumber == (JNUMBER)3.5);
+
+        JDelete(item);
+    }
+
+    SECTION("Setting a numeric value over a string item is safe") {
+        J *object = JCreateObject();
+        REQUIRE(object != NULL);
+        REQUIRE(JAddStringToObject(object, "key", "a string value") != NULL);
+
+        J *item = JGetObjectItem(object, "key");
+        REQUIRE(item != NULL);
+
+        JSetNumberValue(item, 1.25);
+        CHECK(item->valuenumber == (JNUMBER)1.25);
+        CHECK(strcmp(JGetItemName(item), "key") == 0);
+
+        JDelete(object);
+    }
+}
+
+SCENARIO("Public API compatibility: the same contracts hold when compiled as C")
+{
+    NoteSetFnDefault(malloc, free, NULL, NULL);
+
+    // Most of this check is the fact that j_public_api_compat_c.c COMPILED at
+    // all: it binds JGetObjectItemName's result to a mutable char*, assigns
+    // through it, and takes its address, each of which stops compiling if the
+    // macro is re-qualified or turned into a function call. The runtime call
+    // below covers the value contracts from a C translation unit as well, in
+    // case C and C++ ever diverge in argument promotion or macro expansion.
+    SECTION("The C translation unit agrees") {
+        CHECK(jPublicApiCompatC() == 0);
+    }
+}
+
+SCENARIO("Public API compatibility: numeric state on a string node")
+{
+    NoteSetFnDefault(malloc, free, NULL, NULL);
+
+    // JSetIntValue/JSetNumberValue have always written the numeric members
+    // WITHOUT changing the node's base type, so a JString or JRaw node can
+    // carry numeric state. It was observable through the accessors, through
+    // direct field access, and through JDuplicate.
+    //
+    // An earlier revision guarded JIntValue/JNumberValue/JDuplicate on "is this
+    // a string type", because under NOTE_C_STORAGE_OPTIMIZATION those bytes may
+    // be lending themselves to an inline value or key. That was too blunt: it
+    // made the state unreadable even in the DEFAULT layout, where nothing is
+    // ever overlaid. The guard is now on whether the members actually hold
+    // numbers right now, which is unconditionally true in the default layout.
+    //
+    // Reference values captured from a pristine `git archive HEAD` build:
+    //   fields=123/123.5  accessors=123/123.5  copy=123/123.5
+
+    GIVEN("a string node with a number written onto it") {
+        J *item = JCreateString("abc");
+        REQUIRE(item != NULL);
+        JSetIntValue(item, 123.5);
+
+        THEN("the fields hold it") {
+            CHECK(item->valueint == 123);
+            CHECK(item->valuenumber == (JNUMBER)123.5);
+        }
+        THEN("the accessors report it") {
+            CHECK(JIntValue(item) == 123);
+            CHECK(JNumberValue(item) == (JNUMBER)123.5);
+        }
+        THEN("the string value is untouched") {
+            CHECK(strcmp(JStringValue(item), "abc") == 0);
+        }
+        THEN("a duplicate carries it") {
+            J *copy = JDuplicate(item, false);
+            REQUIRE(copy != NULL);
+            CHECK(copy->valueint == 123);
+            CHECK(copy->valuenumber == (JNUMBER)123.5);
+            CHECK(strcmp(JStringValue(copy), "abc") == 0);
+            JDelete(copy);
+        }
+
+        JDelete(item);
+    }
+
+    GIVEN("a raw node with a number written onto it") {
+        J *item = JCreateRaw("{\"x\":1}");
+        REQUIRE(item != NULL);
+        JSetNumberValue(item, 7.25);
+
+        THEN("the accessors report it and the raw text survives") {
+            CHECK(JNumberValue(item) == (JNUMBER)7.25);
+            CHECK(JIntValue(item) == 7);
+            CHECK(strcmp(item->valuestring, "{\"x\":1}") == 0);
+        }
+
+        JDelete(item);
+    }
+
+    GIVEN("a string node that has NOT had a number written onto it") {
+        // Here the numeric members may genuinely be holding packed characters,
+        // so the accessors must report zero rather than character data.
+        J *object = JCreateObject();
+        REQUIRE(object != NULL);
+        REQUIRE(JAddStringToObject(object, "k", "packed") != NULL);
+        J *item = JGetObjectItem(object, "k");
+        REQUIRE(item != NULL);
+
+        THEN("the accessors report zero, never packed bytes") {
+            CHECK(JIntValue(item) == 0);
+            CHECK(JNumberValue(item) == 0.0);
+        }
+        THEN("re-keying after a setter keeps both the key and the number") {
+            JSetIntValue(item, 55);
+            CHECK(JIntValue(item) == 55);
+            J *moved = JDetachItemFromObject(object, "k");
+            REQUIRE(moved != NULL);
+            J *dest = JCreateObject();
+            REQUIRE(dest != NULL);
+            JAddItemToObject(dest, "a-much-longer-replacement-key", moved);
+            CHECK(strcmp(JGetItemName(moved), "a-much-longer-replacement-key") == 0);
+            CHECK(JIntValue(moved) == 55);
+            JDelete(dest);
+        }
+
+        JDelete(object);
+    }
+}
+
+SCENARIO("Public API compatibility: numeric state survives copying, re-keying and referencing")
+{
+    NoteSetFnDefault(malloc, free, NULL, NULL);
+
+    // Whether a string node's numeric bytes hold NUMBERS or packed CHARACTERS
+    // cannot be inferred from "is an inline pointer currently aimed at them",
+    // and an earlier revision that inferred it was wrong in both directions:
+    //
+    //   FALSE POSITIVE. _create_reference() copies a node's bytes verbatim and
+    //   then clears the inline flags, since a reference borrows rather than
+    //   owns. The copied CHARACTERS stayed in the numeric region unreferenced,
+    //   so a reference to JCreateString("abc") reported JIntValue() == 6513249
+    //   -- the bytes of "abc" read as an integer.
+    //
+    //   DESTRUCTION. After a setter evacuated the region and wrote a number,
+    //   the region looked free again, so _j_key_set() reclaimed it for a SHORT
+    //   replacement key and overwrote the number. A long key does not reach
+    //   this path, which is why the earlier re-key test missed it.
+    //
+    // JNumericLive records the fact instead. Reference values from a pristine
+    // `git archive HEAD` build:
+    //   duplicate accessor=55   rekey accessor=55   reference source=0/0 ref=0/0
+
+    GIVEN("a packed string member with a number written onto it") {
+        J *owner = JCreateObject();
+        REQUIRE(owner != NULL);
+        J *item = JAddStringToObject(owner, "k", "packed");
+        REQUIRE(item != NULL);
+        JSetIntValue(item, 55);
+        REQUIRE(JIntValue(item) == 55);
+
+        THEN("a duplicate keeps the number, the key and the string") {
+            J *copy = JDuplicate(item, false);
+            REQUIRE(copy != NULL);
+            CHECK(JIntValue(copy) == 55);
+            REQUIRE(JGetItemName(copy) != NULL);
+            CHECK(strcmp(JGetItemName(copy), "k") == 0);
+            CHECK(strcmp(JStringValue(copy), "packed") == 0);
+            JDelete(copy);
+        }
+
+        THEN("a SHORT replacement key does not reclaim the number's bytes") {
+            J *moved = JDetachItemFromObject(owner, "k");
+            REQUIRE(moved != NULL);
+            J *dest = JCreateObject();
+            REQUIRE(dest != NULL);
+            JAddItemToObject(dest, "x", moved);
+            CHECK(JIntValue(moved) == 55);
+            REQUIRE(JGetItemName(moved) != NULL);
+            CHECK(strcmp(JGetItemName(moved), "x") == 0);
+            CHECK(strcmp(JStringValue(moved), "packed") == 0);
+            JDelete(dest);
+        }
+
+        THEN("replacement keys of every length across the inline boundary are safe") {
+            for (size_t len = 1; len <= 24; ++len) {
+                J *o2 = JCreateObject();
+                REQUIRE(o2 != NULL);
+                J *m2 = JAddStringToObject(o2, "k", "packed");
+                REQUIRE(m2 != NULL);
+                JSetIntValue(m2, 55);
+                m2 = JDetachItemFromObject(o2, "k");
+                REQUIRE(m2 != NULL);
+
+                std::string key(len, 'q');
+                J *d2 = JCreateObject();
+                REQUIRE(d2 != NULL);
+                JAddItemToObject(d2, key.c_str(), m2);
+
+                INFO("replacement key length = " << len);
+                CHECK(JIntValue(m2) == 55);
+                CHECK(strcmp(JGetItemName(m2), key.c_str()) == 0);
+                CHECK(strcmp(JStringValue(m2), "packed") == 0);
+
+                JDelete(d2);
+                JDelete(o2);
+            }
+        }
+
+        JDelete(owner);
+    }
+
+    GIVEN("a reference to an untouched packed string") {
+        J *source = JCreateString("abc");
+        REQUIRE(source != NULL);
+        J *references = JCreateArray();
+        REQUIRE(references != NULL);
+        JAddItemReferenceToArray(references, source);
+        J *reference = JGetArrayItem(references, 0);
+        REQUIRE(reference != NULL);
+
+        THEN("neither the source nor the reference fabricates a number") {
+            // The characters of "abc" occupy the numeric region of the source,
+            // and _create_reference copied them into the reference.
+            CHECK(JIntValue(source) == 0);
+            CHECK(JNumberValue(source) == 0.0);
+            CHECK(JIntValue(reference) == 0);
+            CHECK(JNumberValue(reference) == 0.0);
+        }
+        THEN("the reference still renders as the string") {
+            CHECK(strcmp(JStringValue(reference), "abc") == 0);
+        }
+
+        JDelete(references);
+        JDelete(source);
+    }
+
+    GIVEN("a reference to a string node that DOES hold a number") {
+        J *owner = JCreateObject();
+        REQUIRE(owner != NULL);
+        J *source = JAddStringToObject(owner, "k", "packed");
+        REQUIRE(source != NULL);
+        JSetIntValue(source, 55);
+
+        J *references = JCreateArray();
+        REQUIRE(references != NULL);
+        JAddItemReferenceToArray(references, source);
+        J *reference = JGetArrayItem(references, 0);
+        REQUIRE(reference != NULL);
+
+        THEN("the reference reports the same number as the source") {
+            CHECK(JIntValue(source) == 55);
+            CHECK(JIntValue(reference) == 55);
+        }
+
+        JDelete(references);
+        JDelete(owner);
+    }
+}
+
+SCENARIO("Public API compatibility: a key that aliases the one already held")
+{
+    NoteSetFnDefault(malloc, free, NULL, NULL);
+
+    // The documented "move a member, keep its name" idiom hands a node its own
+    // key back. An interior pointer into that key is just as reachable, and
+    // under NOTE_C_STORAGE_OPTIMIZATION the key may live in the node's own
+    // allocation -- so the destination the new key is copied to can OVERLAP the
+    // source. That was an ASan-confirmed memcpy-param-overlap; it is a memmove
+    // now. Exercised across the inline boundary so both storage classes are hit.
+    const char *base = "a-long-key-past-the-inline-region";
+
+    SECTION("exact alias") {
+        J *src = JCreateObject();
+        REQUIRE(src != NULL);
+        J *item = JAddNumberToObject(src, base, 1);
+        REQUIRE(item != NULL);
+        item = JDetachItemFromObject(src, base);
+        REQUIRE(item != NULL);
+        J *dst = JCreateObject();
+        REQUIRE(dst != NULL);
+        JAddItemToObject(dst, JGetItemName(item), item);
+        CHECK(strcmp(JGetItemName(item), base) == 0);
+        JDelete(dst);
+        JDelete(src);
+    }
+
+    SECTION("prefix-shifted aliases across the inline boundary") {
+        for (size_t skip = 1; skip <= 20; ++skip) {
+            J *src = JCreateObject();
+            REQUIRE(src != NULL);
+            J *item = JAddNumberToObject(src, base, 1);
+            REQUIRE(item != NULL);
+            item = JDetachItemFromObject(src, base);
+            REQUIRE(item != NULL);
+
+            J *dst = JCreateObject();
+            REQUIRE(dst != NULL);
+            JAddItemToObject(dst, JGetItemName(item) + skip, item);
+
+            INFO("skip = " << skip);
+            CHECK(strcmp(JGetItemName(item), base + skip) == 0);
+            CHECK(JIntValue(item) == 1);
+
+            JDelete(dst);
+            JDelete(src);
+        }
+    }
+
+    SECTION("alias of a short inline key") {
+        J *src = JCreateObject();
+        REQUIRE(src != NULL);
+        J *item = JAddStringToObject(src, "abcd", "v");
+        REQUIRE(item != NULL);
+        item = JDetachItemFromObject(src, "abcd");
+        REQUIRE(item != NULL);
+        J *dst = JCreateObject();
+        REQUIRE(dst != NULL);
+        JAddItemToObject(dst, JGetItemName(item) + 1, item);
+        CHECK(strcmp(JGetItemName(item), "bcd") == 0);
+        CHECK(strcmp(JStringValue(item), "v") == 0);
+        JDelete(dst);
+        JDelete(src);
+    }
+}
+
+SCENARIO("Public API compatibility: JGetObjectItemName")
+{
+    NoteSetFnDefault(malloc, free, NULL, NULL);
+
+    SECTION("An item with no key yields NULL, not the empty string") {
+        // JGetItemName() substitutes "" for a missing key. This macro must not,
+        // or every historical `if (JGetObjectItemName(x) != NULL)` silently
+        // inverts.
+        J *array = JCreateArray();
+        REQUIRE(array != NULL);
+        JAddItemToArray(array, JCreateNumber(1));
+        REQUIRE(array->child != NULL);
+
+        CHECK(JGetObjectItemName(array->child) == NULL);
+        CHECK(JGetObjectItemName(array) == NULL);
+
+        JDelete(array);
+    }
+
+    SECTION("An item with a key yields the key") {
+        J *object = JCreateObject();
+        REQUIRE(object != NULL);
+        REQUIRE(JAddNumberToObject(object, "key", 1) != NULL);
+
+        CHECK(strcmp(JGetObjectItemName(object->child), "key") == 0);
+
+        JDelete(object);
+    }
+
+    SECTION("The result is a mutable char* lvalue") {
+        J *object = JCreateObject();
+        REQUIRE(object != NULL);
+        REQUIRE(JAddNumberToObject(object, "key", 1) != NULL);
+
+        J *item = object->child;
+
+        // Binding to `char *` is the compile-time assertion; in C++ this line
+        // does not compile at all if the result is re-qualified as const.
+        char *name = JGetObjectItemName(item);
+        REQUIRE(name != NULL);
+        CHECK(strcmp(name, "key") == 0);
+
+        // Taking its address proves it is still an lvalue -- the historical
+        // macro expanded to a member access, so `JGetObjectItemName(x) = p`
+        // was legal. Assigning through it here would orphan the old key, so
+        // the address is taken and discarded rather than written.
+        char **slot = &JGetObjectItemName(item);
+        CHECK(*slot == name);
+
+        // Writing THROUGH the pointer was also legal, and remains so in both
+        // layouts even when the key is packed into the node's own allocation.
+        name[0] = 'K';
+        CHECK(strcmp(JGetItemName(item), "Key") == 0);
+
+        JDelete(object);
+    }
+}
+
+}
diff --git a/test/src/JReferenceAndFailure_test.cpp b/test/src/JReferenceAndFailure_test.cpp
new file mode 100644
index 00000000..8414a71c
--- /dev/null
+++ b/test/src/JReferenceAndFailure_test.cpp
@@ -0,0 +1,638 @@
+/*!
+ * @file JReferenceAndFailure_test.cpp
+ *
+ * Covers the two areas the packed-layout work left thinnest: reference nodes,
+ * and what happens when the allocator says no.
+ *
+ * REFERENCES. `_create_reference` builds a node by memcpy'ing a source node
+ * into a fresh sizeof(J) allocation. Under NOTE_C_STORAGE_OPTIMIZATION a source
+ * node may be LARGER than sizeof(J) and may carry pointers into its own
+ * allocation, so the copy has to be corrected or the reference ends up claiming
+ * storage it does not own. A real heap-buffer-overflow of exactly this shape
+ * reached review, and it reproduced through nothing more exotic than
+ * JAddObjectToObject followed by JAddItemReferenceToObject. Every referent
+ * shape and every legal deletion order is therefore enumerated here rather than
+ * spot-checked.
+ *
+ * ALLOCATION FAILURE. A parse, duplication or setter that fails partway is the
+ * least-travelled path in the library and the easiest place for a half-built
+ * node to escape. Each operation below is run once per allocation it makes,
+ * failing that allocation and no other, and checked for leaks each time.
+ *
+ * Every assertion holds in both layouts.
+ *
+ * Written by the Blues Inc. team.
+ *
+ * Copyright (c) 2025 Blues Inc. MIT License. Use of this source code is
+ * governed by licenses granted by the copyright holder including that found in
+ * the
+ * <a href="https://github.com/blues/note-c/blob/master/LICENSE">LICENSE</a>
+ * file.
+ *
+ */
+
+#include <catch2/catch_test_macros.hpp>
+
+#include <string>
+#include <vector>
+
+#include "j_layout_test_support.hpp"
+
+using namespace jlayout;
+
+namespace
+{
+
+// A referent shape, built fresh for each case.
+//
+// `keyed` is the property that made the original bug reachable: an item created
+// through JAddXToObject carries a key, and under the storage optimization that
+// key may live in trailing bytes of the item's own allocation, making the node
+// bigger than sizeof(J).
+struct Referent {
+    const char *name;
+    bool keyed;
+    // Builds the referent inside `owner` (keyed) or standalone (unkeyed).
+    J *(*build)(J *owner);
+};
+
+J *buildNumber(J *owner)
+{
+    return owner ? JAddNumberToObject(owner, "source-key", 42)
+           : JCreateNumber(42);
+}
+
+J *buildObject(J *owner)
+{
+    return owner ? JAddObjectToObject(owner, "source-key") : JCreateObject();
+}
+
+J *buildArray(J *owner)
+{
+    J *a = owner ? JAddArrayToObject(owner, "source-key") : JCreateArray();
+    if (a != NULL) {
+        JAddItemToArray(a, JCreateNumber(1));
+    }
+    return a;
+}
+
+J *buildShortString(J *owner)
+{
+    // Short enough to pack into the node's inline region alongside its key.
+    return owner ? JAddStringToObject(owner, "source-key", "abc")
+           : JCreateString("abc");
+}
+
+J *buildLongString(J *owner)
+{
+    // Far too long to inline, so valuestring is a separate heap block. A
+    // reference must borrow that pointer without ever freeing it.
+    static const char *kLong =
+        "a value long enough that it cannot possibly be packed into the node "
+        "itself, forcing valuestring onto the heap where the reference will "
+        "borrow rather than own it";
+    return owner ? JAddStringToObject(owner, "source-key", kLong)
+           : JCreateString(kLong);
+}
+
+J *buildBool(J *owner)
+{
+    return owner ? JAddBoolToObject(owner, "source-key", true) : JCreateBool(true);
+}
+
+const std::vector<Referent> &referents()
+{
+    static const std::vector<Referent> r = {
+        { "number",       true,  buildNumber },
+        { "object",       true,  buildObject },
+        { "array",        true,  buildArray },
+        { "short string", true,  buildShortString },
+        { "long string",  true,  buildLongString },
+        { "bool",         true,  buildBool },
+        { "unkeyed number",       false, buildNumber },
+        { "unkeyed short string", false, buildShortString },
+        { "unkeyed long string",  false, buildLongString },
+    };
+    return r;
+}
+
+SCENARIO("Reference nodes describe their own allocation, not the referent's")
+{
+    for (size_t i = 0; i < referents().size(); ++i) {
+        const Referent &r = referents()[i];
+
+        GIVEN(std::string("a reference to a ") + r.name) {
+            installTrackedAllocator();
+
+            J *owner = NULL;
+            J *referent = NULL;
+            if (r.keyed) {
+                owner = JCreateObject();
+                REQUIRE(owner != NULL);
+                referent = r.build(owner);
+            } else {
+                referent = r.build(NULL);
+            }
+            REQUIRE(referent != NULL);
+
+            J *destination = JCreateObject();
+            REQUIRE(destination != NULL);
+
+            // The exact sequence that overflowed the reference's allocation:
+            // the key is installed AFTER the struct copy, using whatever
+            // trailing capacity the node claims to have.
+            JAddItemReferenceToObject(destination, "x", referent);
+            REQUIRE(destination->child != NULL);
+
+            J *reference = JGetObjectItem(destination, "x");
+            REQUIRE(reference != NULL);
+
+            // Catch2 re-enters this GIVEN once per leaf THEN, so EVERY leaf has
+            // to free the fixture. The deletion-order sections below do that as
+            // the thing they are testing; the inspect-only sections call this.
+            // Missing it leaks the fixture once per section -- invisible to the
+            // tracked allocator (which resets per entry) but caught by valgrind.
+            auto releaseFixture = [&]() {
+                JDelete(destination);
+                JDelete(r.keyed ? owner : referent);
+                CHECK(stats().liveBlocks == 0);
+            };
+
+            THEN("the reference's key is inside the reference, never the referent") {
+                REQUIRE(JGetItemName(reference) != NULL);
+                CHECK(strcmp(JGetItemName(reference), "x") == 0);
+                CHECK(!insideNodeAllocation(referent, JGetItemName(reference)));
+                releaseFixture();
+            }
+
+            THEN("the reference claims no more storage than it allocated") {
+                // The bug was objlen surviving the memcpy, so the reference
+                // believed it was as large as its (larger) source.
+                CHECK(nodeAllocSize(reference) <= nodeAllocSize(referent));
+                CHECK(nodeAllocSize(reference) == sizeof(J));
+                releaseFixture();
+            }
+
+            THEN("the referent is untouched") {
+                if (r.keyed) {
+                    REQUIRE(JGetItemName(referent) != NULL);
+                    CHECK(strcmp(JGetItemName(referent), "source-key") == 0);
+                }
+                if (JIsString(referent)) {
+                    CHECK(strcmp(JStringValue(referent), JStringValue(reference)) == 0);
+                }
+                releaseFixture();
+            }
+
+            // Deletion order is the whole point: a reference must not free
+            // anything the referent owns, and the referent must remain
+            // independently valid whichever side goes first.
+            THEN("deleting the destination first leaves the referent intact") {
+                JDelete(destination);
+                if (r.keyed) {
+                    CHECK(strcmp(JGetItemName(referent), "source-key") == 0);
+                }
+                if (JIsString(referent)) {
+                    CHECK(strlen(JStringValue(referent)) > 0);
+                }
+                char *out = JPrintUnformatted(r.keyed ? owner : referent);
+                CHECK(out != NULL);
+                JFree(out);
+                JDelete(r.keyed ? owner : referent);
+                CHECK(stats().liveBlocks == 0);
+            }
+
+            THEN("deleting the referent first leaves the destination freeable") {
+                JDelete(r.keyed ? owner : referent);
+                JDelete(destination);
+                CHECK(stats().liveBlocks == 0);
+            }
+
+            THEN("rendering the reference matches rendering the referent") {
+                char *viaRef = JPrintUnformatted(reference);
+                char *direct = JPrintUnformatted(referent);
+                REQUIRE(viaRef != NULL);
+                REQUIRE(direct != NULL);
+                CHECK(std::string(viaRef) == std::string(direct));
+                JFree(viaRef);
+                JFree(direct);
+
+                JDelete(destination);
+                JDelete(r.keyed ? owner : referent);
+                CHECK(stats().liveBlocks == 0);
+            }
+        }
+    }
+}
+
+SCENARIO("Array references behave the same as object references")
+{
+    for (size_t i = 0; i < referents().size(); ++i) {
+        const Referent &r = referents()[i];
+
+        GIVEN(std::string("an array reference to a ") + r.name) {
+            installTrackedAllocator();
+
+            J *owner = NULL;
+            J *referent = NULL;
+            if (r.keyed) {
+                owner = JCreateObject();
+                REQUIRE(owner != NULL);
+                referent = r.build(owner);
+            } else {
+                referent = r.build(NULL);
+            }
+            REQUIRE(referent != NULL);
+
+            J *destination = JCreateArray();
+            REQUIRE(destination != NULL);
+            JAddItemReferenceToArray(destination, referent);
+            REQUIRE(destination->child != NULL);
+
+            J *reference = JGetArrayItem(destination, 0);
+            REQUIRE(reference != NULL);
+
+            // Catch2 re-enters this GIVEN once per leaf THEN, so EVERY leaf has
+            // to free the fixture. The deletion-order sections below do that as
+            // the thing they are testing; the inspect-only sections call this.
+            // Missing it leaks the fixture once per section -- invisible to the
+            // tracked allocator (which resets per entry) but caught by valgrind.
+            auto releaseFixture = [&]() {
+                JDelete(destination);
+                JDelete(r.keyed ? owner : referent);
+                CHECK(stats().liveBlocks == 0);
+            };
+
+            THEN("an array reference carries no key") {
+                CHECK(reference->string == NULL);
+                releaseFixture();
+            }
+
+            THEN("the reference claims only its own allocation") {
+                CHECK(nodeAllocSize(reference) == sizeof(J));
+                releaseFixture();
+            }
+
+            THEN("either deletion order is clean") {
+                JDelete(destination);
+                JDelete(r.keyed ? owner : referent);
+                CHECK(stats().liveBlocks == 0);
+            }
+
+            THEN("the reverse deletion order is clean too") {
+                JDelete(r.keyed ? owner : referent);
+                JDelete(destination);
+                CHECK(stats().liveBlocks == 0);
+            }
+        }
+    }
+}
+
+SCENARIO("A reference survives being re-keyed and duplicated")
+{
+    installTrackedAllocator();
+
+    // Re-keying is where the overflow actually landed: _j_key_set writes into
+    // the trailing capacity the node claims. Walk key lengths across the inline
+    // boundary so a node that mis-reported its capacity is caught.
+    GIVEN("a reference to a keyed short-string member") {
+        J *owner = JCreateObject();
+        REQUIRE(owner != NULL);
+        J *referent = JAddStringToObject(owner, "source-key", "abc");
+        REQUIRE(referent != NULL);
+
+        for (size_t len = 1; len <= 40; ++len) {
+            std::string key(len, 'k');
+            J *destination = JCreateObject();
+            REQUIRE(destination != NULL);
+            JAddItemReferenceToObject(destination, key.c_str(), referent);
+            REQUIRE(destination->child != NULL);
+
+            J *reference = JGetObjectItem(destination, key.c_str());
+            REQUIRE(reference != NULL);
+            CHECK(strcmp(JGetItemName(reference), key.c_str()) == 0);
+            // The referent's own key must not have been trampled by a write
+            // that ran past the reference's allocation.
+            CHECK(strcmp(JGetItemName(referent), "source-key") == 0);
+            CHECK(strcmp(JStringValue(referent), "abc") == 0);
+
+            JDelete(destination);
+        }
+
+        JDelete(owner);
+        CHECK(stats().liveBlocks == 0);
+    }
+
+    GIVEN("a duplicated reference") {
+        J *owner = JCreateObject();
+        REQUIRE(owner != NULL);
+        J *referent = JAddStringToObject(owner, "source-key", "abc");
+        REQUIRE(referent != NULL);
+
+        J *destination = JCreateObject();
+        REQUIRE(destination != NULL);
+        JAddItemReferenceToObject(destination, "x", referent);
+        REQUIRE(destination->child != NULL);
+
+        // The duplicate must own everything outright, so it has to outlive the
+        // source it was copied from.
+        J *copy = JDuplicate(destination, true);
+        REQUIRE(copy != NULL);
+
+        JDelete(destination);
+        JDelete(owner);
+
+        THEN("the duplicate is independent of both") {
+            char *out = JPrintUnformatted(copy);
+            REQUIRE(out != NULL);
+            CHECK(std::string(out) == "{\"x\":\"abc\"}");
+            JFree(out);
+        }
+
+        JDelete(copy);
+        CHECK(stats().liveBlocks == 0);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Allocation failure
+// ---------------------------------------------------------------------------
+
+// Runs `op` once per allocation it makes, failing exactly one allocation each
+// time, and requires that nothing leaks on any of those paths.
+//
+// The number of allocations is discovered by running the operation once with no
+// injection, so this stays correct as the layout changes how many allocations
+// an operation needs.
+template <typename Op>
+void forEachAllocationFailure(const char *what, Op op)
+{
+    installTrackedAllocator();
+    op();
+    const size_t total = stats().mallocCalls;
+    REQUIRE(total > 0);
+    REQUIRE(stats().liveBlocks == 0);
+
+    for (size_t ordinal = 1; ordinal <= total; ++ordinal) {
+        installTrackedAllocator();
+        failAllocationAt(ordinal);
+        op();
+        stopFailingAllocations();
+
+        INFO(what << ": failing allocation " << ordinal << " of " << total);
+        CHECK(stats().liveBlocks == 0);
+    }
+    installTrackedAllocator();
+}
+
+SCENARIO("Allocation failure at any point leaks nothing")
+{
+    // Representative parses: keys and values on both sides of the inline
+    // boundary, nesting, arrays, escapes, and numbers.
+    const char *documents[] = {
+        "{\"a\":\"\"}",
+        "{\"a\":1}",
+        "{\"key\":\"value\"}",
+        "{\"a\":\"abc\",\"b\":\"defghijklmnopqrstuvwxyz0123456789\"}",
+        "{\"outer\":{\"inner\":[1,2,3],\"s\":\"x\"}}",
+        "[\"\\u00e9\",\"\\ud83d\\ude00\",\"tab\\there\"]",
+        "{\"n\":-1.5e3,\"big\":9007199254740993,\"t\":true,\"z\":null}",
+    };
+
+    for (size_t d = 0; d < sizeof(documents) / sizeof(documents[0]); ++d) {
+        const char *json = documents[d];
+
+        GIVEN(std::string("parsing ") + json) {
+            forEachAllocationFailure(json, [json]() {
+                J *j = JParse(json);
+                JDelete(j);
+            });
+        }
+
+        GIVEN(std::string("parse, duplicate and print of ") + json) {
+            forEachAllocationFailure(json, [json]() {
+                J *j = JParse(json);
+                if (j != NULL) {
+                    J *copy = JDuplicate(j, true);
+                    char *out = JPrintUnformatted(copy);
+                    JFree(out);
+                    JDelete(copy);
+                }
+                JDelete(j);
+            });
+        }
+    }
+
+    GIVEN("setter evacuation of packed content") {
+        // Overwriting a packed string member with a number forces the key and
+        // value out of the numeric region. That evacuation allocates, and the
+        // library documents it as best-effort: the content may be dropped, but
+        // the node must stay consistent and nothing may leak.
+        forEachAllocationFailure("setter evacuation", []() {
+            J *o = JCreateObject();
+            if (o != NULL) {
+                JAddStringToObject(o, "key", "packed value");
+                J *item = JGetObjectItem(o, "key");
+                if (item != NULL) {
+                    JSetIntValue(item, 7);
+                    JSetNumberValue(item, 1.5);
+                }
+                char *out = JPrintUnformatted(o);
+                JFree(out);
+            }
+            JDelete(o);
+        });
+    }
+
+    GIVEN("reference creation and re-keying") {
+        forEachAllocationFailure("reference creation", []() {
+            J *owner = JCreateObject();
+            J *referent = (owner != NULL) ? JAddStringToObject(owner, "source-key", "abc") : NULL;
+            J *destination = JCreateObject();
+            if ((referent != NULL) && (destination != NULL)) {
+                JAddItemReferenceToObject(destination, "x", referent);
+            }
+            JDelete(destination);
+            JDelete(owner);
+        });
+    }
+
+    GIVEN("adding members one at a time") {
+        forEachAllocationFailure("object construction", []() {
+            J *o = JCreateObject();
+            if (o != NULL) {
+                JAddStringToObject(o, "s", "short");
+                JAddStringToObject(o, "long-key-past-the-inline-region", "a longer value");
+                JAddNumberToObject(o, "n", 1.5);
+                JAddBoolToObject(o, "b", true);
+                J *arr = JAddArrayToObject(o, "a");
+                if (arr != NULL) {
+                    JAddItemToArray(arr, JCreateString("elem"));
+                }
+            }
+            JDelete(o);
+        });
+    }
+}
+
+SCENARIO("A setter that cannot evacuate packed content refuses rather than corrupts")
+{
+    // Under NOTE_C_STORAGE_OPTIMIZATION a short member's key and value live in
+    // the bytes valueint/valuenumber occupy, so a numeric setter has to move
+    // them to the heap before writing. When that allocation fails there are
+    // only two options, and only one of them is safe.
+    //
+    // An earlier revision cleared the pointers and carried on. That rendered
+    // {"temp":"hot"} as {"":""} -- key renamed to empty, value blanked -- and
+    // the result still PARSES, so nothing downstream can detect it. On a
+    // Notecard host under memory pressure that means quietly shipping a
+    // malformed field to Notehub. The historical layout cannot do this at all,
+    // because its setters never touch the key.
+    //
+    // So the setter now abandons the write and preserves document content.
+    // Losing the update is ordinary note-c behavior under memory pressure --
+    // JAddItemToObject and its siblings return void and have always dropped an
+    // item silently on allocation failure. Corrupting a document that then
+    // still parses is what was new.
+    //
+    // This test is written to pass in both layouts: in the historical one there
+    // is nothing to evacuate and the set simply succeeds, so the assertion is
+    // that the KEY AND VALUE SURVIVE, not that the set was skipped.
+
+    GIVEN("a packed short member and an allocator that refuses everything") {
+        installTrackedAllocator();
+
+        J *object = JCreateObject();
+        REQUIRE(object != NULL);
+        REQUIRE(JAddStringToObject(object, "temp", "hot") != NULL);
+        J *item = JGetObjectItem(object, "temp");
+        REQUIRE(item != NULL);
+
+        WHEN("a number is set over it with no memory available") {
+            // Fail from the very next allocation onward.
+            failAllocationAt(1);
+            JSetNumberValue(item, 1.5);
+            stopFailingAllocations();
+
+            THEN("the key and value are intact, not silently emptied") {
+                REQUIRE(JGetItemName(item) != NULL);
+                CHECK(strcmp(JGetItemName(item), "temp") == 0);
+
+                char *out = JPrintUnformatted(object);
+                REQUIRE(out != NULL);
+                CHECK(std::string(out) == "{\"temp\":\"hot\"}");
+                JFree(out);
+            }
+        }
+
+        WHEN("an integer is set over it with no memory available") {
+            failAllocationAt(1);
+            JSetIntValue(item, 7);
+            stopFailingAllocations();
+
+            THEN("the key and value are intact") {
+                REQUIRE(JGetItemName(item) != NULL);
+                CHECK(strcmp(JGetItemName(item), "temp") == 0);
+
+                char *out = JPrintUnformatted(object);
+                REQUIRE(out != NULL);
+                CHECK(std::string(out) == "{\"temp\":\"hot\"}");
+                JFree(out);
+            }
+        }
+
+        WHEN("memory is available") {
+            THEN("the set applies normally and the key still survives") {
+                JSetNumberValue(item, 1.5);
+                REQUIRE(JGetItemName(item) != NULL);
+                CHECK(strcmp(JGetItemName(item), "temp") == 0);
+                CHECK(item->valuenumber == (JNUMBER)1.5);
+            }
+        }
+
+        JDelete(object);
+        CHECK(stats().liveBlocks == 0);
+    }
+}
+
+SCENARIO("Malformed input is rejected without leaking")
+{
+    // Truncations and structural errors, including several that fail AFTER a
+    // node has been linked into a parent's child list -- the case where a
+    // partially built tree has to be unwound rather than simply discarded.
+    const char *malformed[] = {
+        "",                          "{",
+        "}",                         "[",
+        "]",                         "{\"a\"",
+        "{\"a\":",                   "{\"a\":}",
+        "{\"a\":1",                  "{\"a\":1,}",
+        "{\"a\":1,",                 "{\"a\":1 \"b\":2}",
+        "{\"a\" 1}",                 "{a:1}",
+        "{'a':1}",                   "{\"a\":1}}",
+        "[1,]",                      "[1 2]",
+        "[1,,2]",                    "[",
+        "{\"unterminated\":\"str",   "{\"unterminated key",
+        "\"bare string",             "{\"a\":\"\\\"}",
+        "{\"a\":\"\\q\"}",           "{\"a\":\"\\u\"}",
+        "{\"a\":\"\\u00\"}",         "{\"a\":\"\\uZZZZ\"}",
+        "{\"a\":\"\\ud83d\"}",       "{\"a\":\"\\ud83d\\u0041\"}",
+        "{\"a\":\"\\udc00\"}",       "{\"a\":01}",
+        "{\"a\":1.2.3}",             "{\"a\":+1}",
+        "{\"a\":.5}",                "{\"a\":1e}",
+        "{\"a\":tru}",               "{\"a\":nul}",
+        "{\"a\":Infinity}",          "{\"good\":1,\"bad\":}",
+        "{\"good\":1,\"nested\":{\"deeper\":[1,2,}}",
+        "[{\"a\":1},{\"b\":}]",
+    };
+
+    installTrackedAllocator();
+
+    for (size_t i = 0; i < sizeof(malformed) / sizeof(malformed[0]); ++i) {
+        const char *json = malformed[i];
+
+        WHEN(std::string("parsing malformed input: ") + json) {
+            installTrackedAllocator();
+            J *j = JParse(json);
+
+            THEN("nothing is leaked, whether or not it parsed") {
+                // A few of these are accepted by this parser (it is lenient in
+                // places). Either answer is fine; what must hold is that the
+                // heap comes back clean.
+                JDelete(j);
+                INFO("input: " << json);
+                CHECK(stats().liveBlocks == 0);
+            }
+        }
+    }
+
+    // The same inputs, with every allocation failing in turn: an error path
+    // reached while ANOTHER error path is unwinding.
+    for (size_t i = 0; i < sizeof(malformed) / sizeof(malformed[0]); ++i) {
+        const char *json = malformed[i];
+        if (strlen(json) < 6) {
+            continue;   // too short to allocate anything interesting
+        }
+
+        WHEN(std::string("parsing ") + json + " under allocation failure") {
+            installTrackedAllocator();
+            J *probe = JParse(json);
+            const size_t total = stats().mallocCalls;
+            JDelete(probe);
+
+            for (size_t ordinal = 1; ordinal <= total; ++ordinal) {
+                installTrackedAllocator();
+                failAllocationAt(ordinal);
+                J *j = JParse(json);
+                stopFailingAllocations();
+                JDelete(j);
+                INFO("input: " << json << ", failing allocation " << ordinal);
+                CHECK(stats().liveBlocks == 0);
+            }
+            installTrackedAllocator();
+        }
+    }
+
+    NoteSetFn(malloc, free, NULL, NULL);
+}
+
+}
diff --git a/test/src/NoteRequestResponseJSON_test.cpp b/test/src/NoteRequestResponseJSON_test.cpp
index da3ee6ce..0177b198 100644
--- a/test/src/NoteRequestResponseJSON_test.cpp
+++ b/test/src/NoteRequestResponseJSON_test.cpp
@@ -491,10 +491,24 @@ SCENARIO("NoteRequestResponseJSON")
 
             AND_GIVEN("_Malloc fails to allocate rspJSON") {
                 NoteMalloc_fake.custom_fake = [](size_t size) -> void * {
-                    // Allow the first seventeen calls to malloc to succeed for
-                    // JParse(6), JCreateObject(9) and JPrintUnformatted(2), but
-                    // fail the eighteenth call.
-                    if (NoteMalloc_fake.call_count > 17)
+                    // Fail the allocation of rspJSON itself, identified by its
+                    // SIZE rather than by a fixed call ordinal.
+                    //
+                    // An ordinal cannot work here: the number of allocations
+                    // that precede this one depends on the J storage layout,
+                    // and NOTE_C_STORAGE_OPTIMIZATION makes fewer of them. The
+                    // previous "fail the eighteenth call" never fired in that
+                    // build, so the case silently stopped testing anything and
+                    // NoteRequestResponseJSON returned a non-NULL result that
+                    // the assertion below then rejected.
+                    //
+                    // The size is that of the rendered error document, which is
+                    // layout-independent because both layouts print identical
+                    // JSON. _errDoc builds it from the transaction error and
+                    // the request's id, both fixed by this scenario.
+                    const size_t rspJSONAllocSize =
+                        sizeof("{\"err\":\"an error occurred\",\"src\":\"note-c\",\"id\":917}") + 1;
+                    if (size == rspJSONAllocSize)
                     {
                         return NULL;
                     }
diff --git a/test/src/j_public_api_compat_c.c b/test/src/j_public_api_compat_c.c
new file mode 100644
index 00000000..a8682620
--- /dev/null
+++ b/test/src/j_public_api_compat_c.c
@@ -0,0 +1,148 @@
+/*!
+ * @file j_public_api_compat_c.c
+ *
+ * The C half of the public-macro compatibility check.
+ *
+ * note-c is a C library, but every test in this suite is a C++ translation
+ * unit, so until this file existed the public `J` macros were never once
+ * compiled as C. That matters for the macros converted to function calls
+ * alongside NOTE_C_STORAGE_OPTIMIZATION: C and C++ disagree about exactly the
+ * properties those conversions put at risk.
+ *
+ *   - Binding a `const char *` to a `char *` is a hard error in C++ but only a
+ *     warning in C, so the C++ test alone would catch a re-qualified
+ *     JGetObjectItemName only on compilers configured to treat that warning as
+ *     an error. This file is compiled with -Werror to close that.
+ *   - Assigning through, or taking the address of, a macro result requires it
+ *     to be an lvalue. A macro that became a function call stops being one.
+ *     That is a hard error in both languages, and is checked here without
+ *     relying on any warning setting at all.
+ *
+ * Everything below is either a compile-time construct or a cheap runtime
+ * self-check invoked from JPublicApiCompat_test.cpp. The compile-time parts are
+ * the point: if they stop compiling, the build fails, which is the assertion.
+ *
+ * Written by the Blues Inc. team.
+ *
+ * Copyright (c) 2025 Blues Inc. MIT License. Use of this source code is
+ * governed by licenses granted by the copyright holder including that found in
+ * the
+ * <a href="https://github.com/blues/note-c/blob/master/LICENSE">LICENSE</a>
+ * file.
+ *
+ */
+
+#include <stdlib.h>
+#include <string.h>
+
+#include "note.h"
+
+/* Failure bits returned by jPublicApiCompatC(). Zero means every check held. */
+#define JCOMPAT_C_OK                    0
+#define JCOMPAT_C_KEYLESS_NOT_NULL      (1 << 0)
+#define JCOMPAT_C_KEY_WRONG             (1 << 1)
+#define JCOMPAT_C_SETINT_FRACTION_LOST  (1 << 2)
+#define JCOMPAT_C_SETNUMBER_WRONG       (1 << 3)
+#define JCOMPAT_C_NULL_NOT_PASSTHROUGH  (1 << 4)
+#define JCOMPAT_C_ALLOC_FAILED          (1 << 5)
+
+/* COMPILE-TIME CHECK 1: the result of JGetObjectItemName is a mutable `char *`.
+ *
+ * Written as a function so the conversion is checked at every call, and so a
+ * `const char *` result is a -Wdiscarded-qualifiers error under the -Werror
+ * this file is compiled with. */
+static char *jCompatBindsToMutableCharPointer(J *item)
+{
+    char *name = JGetObjectItemName(item);
+    return name;
+}
+
+/* COMPILE-TIME CHECK 2: it is still an LVALUE.
+ *
+ * The historical macro expanded to a member access, so `JGetObjectItemName(x)`
+ * could be assigned to and have its address taken. Neither compiles if the
+ * macro becomes a function call, in C or C++, regardless of warning flags.
+ *
+ * The assignment is a self-assignment so nothing is corrupted and no key is
+ * orphaned; only its well-formedness is being tested. */
+static char **jCompatResultIsAnLvalue(J *item)
+{
+    JGetObjectItemName(item) = JGetObjectItemName(item);
+    return &JGetObjectItemName(item);
+}
+
+/* Runtime half: the observable contracts, checked from C rather than C++ in
+ * case the two ever diverge in argument promotion or macro expansion. */
+int jPublicApiCompatC(void)
+{
+    int result = JCOMPAT_C_OK;
+    J *object = NULL;
+    J *array = NULL;
+    J *item = NULL;
+    char **slot = NULL;
+
+    /* A keyless item yields NULL, not "". */
+    array = JCreateArray();
+    if (array == NULL) {
+        return JCOMPAT_C_ALLOC_FAILED;
+    }
+    JAddItemToArray(array, JCreateNumber(1));
+    if (array->child == NULL) {
+        JDelete(array);
+        return JCOMPAT_C_ALLOC_FAILED;
+    }
+    if (JGetObjectItemName(array->child) != NULL) {
+        result |= JCOMPAT_C_KEYLESS_NOT_NULL;
+    }
+    JDelete(array);
+
+    object = JCreateObject();
+    if (object == NULL) {
+        return result | JCOMPAT_C_ALLOC_FAILED;
+    }
+    if (JAddNumberToObject(object, "key", 1) == NULL) {
+        JDelete(object);
+        return result | JCOMPAT_C_ALLOC_FAILED;
+    }
+    item = object->child;
+
+    if ((JGetObjectItemName(item) == NULL)
+            || (strcmp(JGetObjectItemName(item), "key") != 0)) {
+        result |= JCOMPAT_C_KEY_WRONG;
+    }
+
+    /* Exercise the two compile-time checks so they cannot be optimized away as
+     * unreferenced statics, and so the lvalue self-assignment actually runs. */
+    if (jCompatBindsToMutableCharPointer(item) == NULL) {
+        result |= JCOMPAT_C_KEY_WRONG;
+    }
+    slot = jCompatResultIsAnLvalue(item);
+    if ((slot == NULL) || (*slot != JGetObjectItemName(item))) {
+        result |= JCOMPAT_C_KEY_WRONG;
+    }
+
+    /* The historical macro parsed as valueint = (valuenumber = number), so a
+     * fractional operand truncated into valueint and survived in valuenumber.
+     * A JINTEGER parameter on the helper would store 1 in both. */
+    JSetIntValue(item, 1.5);
+    if ((item->valueint != 1) || (item->valuenumber != (JNUMBER)1.5)) {
+        result |= JCOMPAT_C_SETINT_FRACTION_LOST;
+    }
+
+    JSetNumberValue(item, 2.5);
+    if ((item->valuenumber != (JNUMBER)2.5) || (item->valueint != 2)) {
+        result |= JCOMPAT_C_SETNUMBER_WRONG;
+    }
+
+    JDelete(object);
+
+    /* A NULL object is a no-op that yields the operand. */
+    if (JSetIntValue((J *)NULL, 42) != 42) {
+        result |= JCOMPAT_C_NULL_NOT_PASSTHROUGH;
+    }
+    if (JSetNumberValue((J *)NULL, 4.5) != (JNUMBER)4.5) {
+        result |= JCOMPAT_C_NULL_NOT_PASSTHROUGH;
+    }
+
+    return result;
+}