@quereus/store 4.9.0 → 4.11.0

package/dist/src/common/serialization.js

@@ -4,62 +4,134 @@
  * Uses extended JSON format that preserves SQL value types:
  * - bigint: { "$bigint": "12345678901234567890" }
  * - Uint8Array: { "$blob": "base64..." }
- * - JSON objects with marker-colliding keys: { "$json": { "$bigint": "not-a-bigint" } }
  * - Other types: Native JSON representation
+ *
+ * JSON/object values whose own keys collide with a marker name are escaped on
+ * write by prefixing one extra `$` (`$bigint` -> `$$bigint`, `$$blob` ->
+ * `$$$blob`) and unescaped on read. Escaping happens per key at any depth, so
+ * a marker-shaped object can never be confused with a real marker no matter
+ * how deeply it is nested.
+ *
+ * Escaping (not wrapping) is required because `JSON.parse` invokes the reviver
+ * bottom-up: an enclosing `{"$json": ...}` wrapper is visited *after* the value
+ * it was meant to protect, so the inner object would already have been decoded
+ * (or thrown) before the wrapper could suppress it.
  */
 const BIGINT_MARKER = '$bigint';
 const BLOB_MARKER = '$blob';
+/** Legacy write-side wrapper; still unwrapped on read for rows written before key escaping. */
 const JSON_MARKER = '$json';
+/** A user key that would collide with a marker, or with an escaped marker key. */
+const COLLIDING_KEY = /^\$+(?:bigint|blob|json)$/;
+/** An escaped user key produced by `escapeKey` — one `$` more than a colliding key. */
+const ESCAPED_KEY = /^\$\$+(?:bigint|blob|json)$/;
+const DOLLAR_CHAR_CODE = 36;
 // TextEncoder is stateless and reusable — hoist one instance rather than
 // allocating a fresh encoder on every serialize call.
 const textEncoder = new TextEncoder();
+// TextDecoder is likewise stateless per non-streaming decode() call, so one
+// instance can be shared safely across concurrent scans.
+const decoder = new TextDecoder();
+/**
+ * True if the decoded JSON text could need reviving — either a marker object
+ * emitted by `replacer` or a key escaped by `escapeMarkerKeys`.
+ *
+ * Markers are single-key objects, so they always serialize with the literal
+ * `{"$` sigil. Escaped keys always start with `$$` but may sit at any position
+ * in their object, so they only guarantee the `"$$` sigil. Both are preceded by
+ * a quote, so a single `"$` scan rules out the overwhelmingly common case in
+ * one pass; the narrower checks then run only for text that already contains a
+ * quoted `$`, keeping ordinary values like `"$125.00 fee"` off the slow path.
+ *
+ * Centralized so a future fourth marker type can't add a new marker shape
+ * while forgetting this gate.
+ *
+ * NOTE: a row that does contain a marker (any bigint or blob column) is scanned
+ * up to three times before its reviver runs. Measured neutral against the
+ * unconditional-reviver baseline on such rows; if very wide rows or large blobs
+ * ever make these scans show up in a profile, fold the three passes into one
+ * hand-rolled character scan.
+ */
+function needsReviver(json) {
+    if (!json.includes('"$'))
+        return false;
+    return json.includes('{"$') || json.includes('"$$');
+}
 /**
  * Serialize a row to a byte array for storage.
  */
 export function serializeRow(row) {
-    // Pre-process row elements to handle JSON objects with marker-colliding keys
-    const safeRow = row.map(wrapJsonIfNeeded);
-    const json = JSON.stringify(safeRow, replacer);
+    const json = JSON.stringify(row, replacer);
     return textEncoder.encode(json);
 }
 /**
  * Deserialize a byte array back to a row.
  */
 export function deserializeRow(buffer) {
-    const json = new TextDecoder().decode(buffer);
-    return JSON.parse(json, reviver);
+    const json = decoder.decode(buffer);
+    // NOTE: accepted tradeoff — the reviver gate infers from the decoded text rather than a
+    // write-time flag byte. A flag would save ~0.11 µs/row over this scan (measured) but needs
+    // a stored-format version + migration; not worth it on its own. Revisit only if the row
+    // codec is being opened anyway — a binary/columnar format subsumes this entirely.
+    return JSON.parse(json, needsReviver(json) ? reviver : undefined);
 }
 /**
  * Serialize a single SQL value to a byte array.
  */
 export function serializeValue(value) {
-    const safe = wrapJsonIfNeeded(value);
-    const json = JSON.stringify(safe, replacer);
+    const json = JSON.stringify(value, replacer);
     return textEncoder.encode(json);
 }
 /**
  * Deserialize a byte array back to a SQL value.
  */
 export function deserializeValue(buffer) {
-    const json = new TextDecoder().decode(buffer);
-    return JSON.parse(json, reviver);
+    const json = decoder.decode(buffer);
+    return JSON.parse(json, needsReviver(json) ? reviver : undefined);
+}
+/** True if `key` needs escaping (or unescaping) — cheap `$` test before the regex. */
+function isCollidingKey(key) {
+    return key.charCodeAt(0) === DOLLAR_CHAR_CODE && COLLIDING_KEY.test(key);
+}
+/** True if `key` was produced by escaping a colliding key. */
+function isEscapedKey(key) {
+    return key.charCodeAt(0) === DOLLAR_CHAR_CODE && ESCAPED_KEY.test(key);
 }
 /**
- * Wraps a JSON object in a $json marker if it contains keys that
- * would collide with our bigint/blob markers during deserialization.
+ * Rebuilds `obj` with each own key passed through `rename`.
+ *
+ * Built via `Object.fromEntries` rather than assignment because a JSON value
+ * may legitimately carry an own `__proto__` key; `copy[key] = value` would
+ * invoke the prototype setter, silently dropping the key and re-pointing the
+ * object's prototype. `fromEntries` defines own properties instead.
  */
-function wrapJsonIfNeeded(value) {
-    if (typeof value !== 'object' || value === null || value instanceof Uint8Array) {
-        return value;
-    }
-    // It's a JSON object or array stored as a SqlValue
-    if (!Array.isArray(value) && (BIGINT_MARKER in value || BLOB_MARKER in value)) {
-        return { [JSON_MARKER]: value };
-    }
-    return value;
+function rekey(obj, rename) {
+    return Object.fromEntries(Object.keys(obj).map(key => [rename(key), obj[key]]));
+}
+/**
+ * Rewrites marker-colliding keys of a plain object so no user data can ever
+ * present the shape of a marker. Returns the original object untouched when
+ * nothing collides, so the common case allocates nothing.
+ *
+ * Only the object's own keys are rewritten — nested objects are reached by
+ * `JSON.stringify`, which applies `replacer` top-down to every member.
+ */
+function escapeMarkerKeys(obj) {
+    if (!Object.keys(obj).some(isCollidingKey))
+        return obj;
+    return rekey(obj, key => (isCollidingKey(key) ? `$${key}` : key));
+}
+/** Inverse of `escapeMarkerKeys`; likewise returns the original object when nothing was escaped. */
+function unescapeMarkerKeys(obj) {
+    if (!Object.keys(obj).some(isEscapedKey))
+        return obj;
+    return rekey(obj, key => (isEscapedKey(key) ? key.slice(1) : key));
 }
 /**
  * JSON replacer function for SQL values.
+ *
+ * `JSON.stringify` calls this top-down for every member, which is what lets the
+ * key escaping reach arbitrary nesting depth without a separate pre-walk.
  */
 function replacer(_key, value) {
     if (typeof value === 'bigint') {
@@ -68,24 +140,35 @@ function replacer(_key, value) {
     if (value instanceof Uint8Array) {
         return { [BLOB_MARKER]: uint8ArrayToBase64(value) };
     }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return escapeMarkerKeys(value);
+    }
     return value;
 }
 /**
  * JSON reviver function for SQL values.
+ *
+ * Markers are matched only in their exact single-key form; escaping guarantees
+ * that shape is unreachable from user data, so no ambiguity remains.
  */
 function reviver(_key, value) {
     if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
         const obj = value;
-        // Unwrap $json marker first (before checking for $bigint/$blob)
-        if (JSON_MARKER in obj && Object.keys(obj).length === 1) {
-            return obj[JSON_MARKER];
-        }
-        if (BIGINT_MARKER in obj && typeof obj[BIGINT_MARKER] === 'string') {
-            return BigInt(obj[BIGINT_MARKER]);
-        }
-        if (BLOB_MARKER in obj && typeof obj[BLOB_MARKER] === 'string') {
-            return base64ToUint8Array(obj[BLOB_MARKER]);
+        const keys = Object.keys(obj);
+        if (keys.length === 1) {
+            const [key] = keys;
+            if (key === BIGINT_MARKER && typeof obj[BIGINT_MARKER] === 'string') {
+                return BigInt(obj[BIGINT_MARKER]);
+            }
+            if (key === BLOB_MARKER && typeof obj[BLOB_MARKER] === 'string') {
+                return base64ToUint8Array(obj[BLOB_MARKER]);
+            }
+            // Legacy wrapper from before key escaping; user data now escapes `$json`.
+            if (key === JSON_MARKER) {
+                return obj[JSON_MARKER];
+            }
         }
+        return unescapeMarkerKeys(obj);
     }
     return value;
 }
@@ -132,6 +215,6 @@ export function serializeStats(stats) {
  * Deserialize table statistics.
  */
 export function deserializeStats(buffer) {
-    return JSON.parse(new TextDecoder().decode(buffer));
+    return JSON.parse(decoder.decode(buffer));
 }
 //# sourceMappingURL=serialization.js.map

package/dist/src/common/serialization.js.map

@@ -1 +1 @@
-{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../../../src/common/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,aAAa,GAAG,SAAS,CAAC;AAChC,MAAM,WAAW,GAAG,OAAO,CAAC;AAC5B,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B,yEAAyE;AACzE,sDAAsD;AACtD,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,GAAQ;IACnC,6EAA6E;IAC7E,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC/C,OAAO,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAQ,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5C,OAAO,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAa,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAAe;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAC/E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,mDAAmD;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,KAAK,IAAI,WAAW,IAAI,KAAK,CAAC,EAAE,CAAC;QAC9E,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;IAC/C,CAAC;IAED,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;IACtD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAS,OAAO,CAAC,IAAY,EAAE,KAAc;IAC3C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,MAAM,GAAG,GAAG,KAAgC,CAAC;QAE7C,gEAAgE;QAChE,IAAI,WAAW,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,OAAO,GAAG,CAAC,WAAW,CAAC,CAAC;QAC1B,CAAC;QAED,IAAI,aAAa,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnE,OAAO,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC/D,OAAO,kBAAkB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,KAAiB;IAC3C,uCAAuC;IACvC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,mBAAmB;IACnB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,MAAc;IACxC,uCAAuC;IACvC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,mBAAmB;IACnB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAcD;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAiB;IAC9C,OAAO,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAe,CAAC;AACpE,CAAC"}
+{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../../../src/common/serialization.ts"],"names":[],"mappings":"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"}

package/dist/src/testing/index.d.ts

@@ -6,7 +6,11 @@
  *   - {@link runKVStoreConformance} — the {@link KVStore} contract (all backends);
  *   - {@link runKVProviderConformance} — the provider-level atomic multi-store commit
  *     ({@link KVStoreProvider.beginAtomicBatch}), for the backends that have one.
+ *
+ * {@link assertBoundedIterate} is the bounded-iteration tier's core assertion, exported
+ * standalone so a spec can drive it directly (including against a store double built to
+ * fail it — a guard nobody has watched fail is not a guard).
  */
-export { runKVStoreConformance, type KVBackend } from './kv-conformance.js';
+export { runKVStoreConformance, assertBoundedIterate, type KVBackend, type ReadMeter } from './kv-conformance.js';
 export { runKVProviderConformance, type KVProviderBackend } from './kv-provider-conformance.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,qBAAqB,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAClH,OAAO,EAAE,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/src/testing/index.js

@@ -6,7 +6,11 @@
  *   - {@link runKVStoreConformance} — the {@link KVStore} contract (all backends);
  *   - {@link runKVProviderConformance} — the provider-level atomic multi-store commit
  *     ({@link KVStoreProvider.beginAtomicBatch}), for the backends that have one.
+ *
+ * {@link assertBoundedIterate} is the bounded-iteration tier's core assertion, exported
+ * standalone so a spec can drive it directly (including against a store double built to
+ * fail it — a guard nobody has watched fail is not a guard).
  */
-export { runKVStoreConformance } from './kv-conformance.js';
+export { runKVStoreConformance, assertBoundedIterate } from './kv-conformance.js';
 export { runKVProviderConformance } from './kv-provider-conformance.js';
 //# sourceMappingURL=index.js.map

package/dist/src/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,qBAAqB,EAAkB,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAA0B,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAkC,MAAM,qBAAqB,CAAC;AAClH,OAAO,EAAE,wBAAwB,EAA0B,MAAM,8BAA8B,CAAC"}

package/dist/src/testing/kv-conformance.d.ts

@@ -5,8 +5,8 @@
  * contract (not against any single backend), invoked once per backend. Each backend
  * supplies only a small {@link KVBackend} adapter (how to open / reopen / tear down);
  * this file supplies every assertion. A behavior that drifts on one backend then
- * fails the suite instead of silently diverging across the three interchangeable
- * stores (in-memory, LevelDB, IndexedDB).
+ * fails the suite instead of silently diverging across the interchangeable stores
+ * (in-memory, LevelDB, IndexedDB, React Native LevelDB, NativeScript SQLite).
  *
  * Deps are deliberately minimal so this file can be compiled into `@quereus/store`'s
  * normal `src` build without dragging a test framework into the shipped package:
@@ -21,7 +21,29 @@
  * store, so the memory backend is tested against the contract as honestly as the
  * others.
  */
-import type { KVStore } from '../common/kv-store.js';
+import type { KVStore, IterateOptions } from '../common/kv-store.js';
+/**
+ * Read instrumentation for the bounded-iteration tier.
+ *
+ * The battery only ever holds a {@link KVStore}; it cannot see what a backend reads
+ * underneath. A backend supplies this by wrapping whatever its store reads FROM — the
+ * level handle, the SQL driver, the IDB cursor — in its own adapter's closure.
+ */
+export interface ReadMeter {
+    /**
+     * Entries read from backing storage so far — monotonically increasing over the
+     * adapter's lifetime. Callers take a baseline and measure the delta, so this never
+     * needs an explicit reset.
+     */
+    entriesRead(): number;
+    /**
+     * How many entries this backend may read ahead of one yield — its batch size.
+     * `abstract-level` awaits `next()` once per entry, so 1; IndexedDB pages 256.
+     * Count what the meter actually observes, including any extra probe read the
+     * implementation takes to discover a batch is full.
+     */
+    maxReadAhead: number;
+}
 /**
  * Per-backend lifecycle adapter. The suite drives its own per-test lifecycle and
  * calls {@link makeBackend} fresh for every test, so state never leaks between tests.
@@ -37,7 +59,34 @@ export interface KVBackend {
     reopen?(): Promise<KVStore>;
     /** Release everything open()/reopen() created (close handles, rm temp dir / delete db). */
     teardown(): Promise<void>;
+    /**
+     * Optional read instrumentation for the bounded-iteration tier. Omit it and that
+     * tier's METERED cases are not registered for this backend (its unmetered cases —
+     * break and throw mid-iteration — still run). See {@link ReadMeter}.
+     */
+    readMeter?: ReadMeter;
 }
+/**
+ * Assert that `store.iterate(options)` reads a BOUNDED amount from backing storage:
+ * consume `take` entries, then stop, and check the meter.
+ *
+ * The allowance is `take + maxReadAhead - 1`: a backend that reads one entry per yield
+ * reads exactly `take`, and one that pages reads at most `take` rounded up past a batch
+ * boundary. Crucially the allowance does NOT grow with the size of the range, so a
+ * backend that materializes the whole range fails however large the range is — which is
+ * the property the bounded-iteration tier exists to pin. Passing `take` = the whole range
+ * pins the other half of the contract, that total work is linear: a backend paging by
+ * `limit`/`offset` reads a bounded FIRST batch but O(n²) overall.
+ *
+ * Exported standalone so a spec can drive it against a deliberately-buffering store
+ * double and prove it rejects (see `bounded-iterate.spec.ts`).
+ *
+ * @param store - The store under test.
+ * @param meter - Read instrumentation for whatever `store` reads from.
+ * @param options - Iterate options. The range must hold at least `take` entries.
+ * @param take - Entries to consume before stopping. Default 1 (prefix-and-stop).
+ */
+export declare function assertBoundedIterate(store: KVStore, meter: ReadMeter, options?: IterateOptions, take?: number): Promise<void>;
 /**
  * Register the full KVStore conformance battery under `describe(name)`. Call once per
  * backend. `makeBackend` is invoked fresh for every test (so no state leaks); it is

package/dist/src/testing/kv-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kv-conformance.d.ts","sourceRoot":"","sources":["../../../src/testing/kv-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,uBAAuB,CAAC;AAarE;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,2FAA2F;IAC3F,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAkED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,GAAG,IAAI,CA+XtF"}
+{"version":3,"file":"kv-conformance.d.ts","sourceRoot":"","sources":["../../../src/testing/kv-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAarE;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB;;;;OAIG;IACH,WAAW,IAAI,MAAM,CAAC;IACtB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,2FAA2F;IAC3F,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACzC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,cAAc,EACxB,IAAI,GAAE,MAAU,GACd,OAAO,CAAC,IAAI,CAAC,CAqBf;AAuED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,GAAG,IAAI,CAgftF"}

package/dist/src/testing/kv-conformance.js

@@ -5,8 +5,8 @@
  * contract (not against any single backend), invoked once per backend. Each backend
  * supplies only a small {@link KVBackend} adapter (how to open / reopen / tear down);
  * this file supplies every assertion. A behavior that drifts on one backend then
- * fails the suite instead of silently diverging across the three interchangeable
- * stores (in-memory, LevelDB, IndexedDB).
+ * fails the suite instead of silently diverging across the interchangeable stores
+ * (in-memory, LevelDB, IndexedDB, React Native LevelDB, NativeScript SQLite).
  *
  * Deps are deliberately minimal so this file can be compiled into `@quereus/store`'s
  * normal `src` build without dragging a test framework into the shipped package:
@@ -25,6 +25,43 @@ import assert from 'node:assert/strict';
 import { compareBytes } from '../common/bytes.js';
 import { encodeCompositeKey } from '../common/encoding.js';
 import { assertBytes, b, u8 } from './kv-assert.js';
+/**
+ * Assert that `store.iterate(options)` reads a BOUNDED amount from backing storage:
+ * consume `take` entries, then stop, and check the meter.
+ *
+ * The allowance is `take + maxReadAhead - 1`: a backend that reads one entry per yield
+ * reads exactly `take`, and one that pages reads at most `take` rounded up past a batch
+ * boundary. Crucially the allowance does NOT grow with the size of the range, so a
+ * backend that materializes the whole range fails however large the range is — which is
+ * the property the bounded-iteration tier exists to pin. Passing `take` = the whole range
+ * pins the other half of the contract, that total work is linear: a backend paging by
+ * `limit`/`offset` reads a bounded FIRST batch but O(n²) overall.
+ *
+ * Exported standalone so a spec can drive it against a deliberately-buffering store
+ * double and prove it rejects (see `bounded-iterate.spec.ts`).
+ *
+ * @param store - The store under test.
+ * @param meter - Read instrumentation for whatever `store` reads from.
+ * @param options - Iterate options. The range must hold at least `take` entries.
+ * @param take - Entries to consume before stopping. Default 1 (prefix-and-stop).
+ */
+export async function assertBoundedIterate(store, meter, options, take = 1) {
+    assert.ok(take >= 1, `assertBoundedIterate: take must be >= 1, got ${take}`);
+    const baseline = meter.entriesRead();
+    let consumed = 0;
+    for await (const _entry of store.iterate(options)) {
+        if (++consumed >= take)
+            break;
+    }
+    const read = meter.entriesRead() - baseline;
+    // Guards against a vacuous pass: a store that yields nothing reads nothing, and a
+    // meter wired to the wrong thing reports zero however the store behaves.
+    assert.strictEqual(consumed, take, `expected to consume ${take} entries before stopping, got ${consumed} — the range is too small to measure`);
+    assert.ok(read >= 1, 'the read meter counted nothing — it is not wired to what this store reads from');
+    const allowed = take + meter.maxReadAhead - 1;
+    assert.ok(read <= allowed, `bounded iteration: consuming ${take} entr${take === 1 ? 'y' : 'ies'} read ${read} from backing storage, ` +
+        `allowance is ${allowed} (take + maxReadAhead - 1, maxReadAhead=${meter.maxReadAhead})`);
+}
 // ============================================================================
 // Assertion + iteration helpers
 // ============================================================================
@@ -44,6 +81,10 @@ async function seed1to5(store) {
     for (let i = 1; i <= 5; i++)
         await store.put(b(i), b(i * 10));
 }
+/** 2-byte big-endian key for the large-range tiers (0..65535) — byte order matches key order. */
+const enc = (n) => b((n >> 8) & 0xff, n & 0xff);
+/** Inverse of {@link enc}. */
+const dec = (k) => (k[0] << 8) | k[1];
 // ============================================================================
 // Tier 6 golden vector — cross-backend byte-ordering agreement
 // ============================================================================
@@ -88,8 +129,11 @@ const key1 = (v) => encodeCompositeKey([v]);
  */
 export function runKVStoreConformance(name, makeBackend) {
     // Probe (no open()/teardown() — the factory only builds the adapter object) to
-    // learn whether this backend persists across a reopen.
-    const supportsReopen = typeof makeBackend().reopen === 'function';
+    // learn whether this backend persists across a reopen, and whether it can report
+    // what it reads from backing storage.
+    const probe = makeBackend();
+    const supportsReopen = typeof probe.reopen === 'function';
+    const supportsReadMeter = probe.readMeter !== undefined;
     describe(name, () => {
         let backend;
         let store;
@@ -249,12 +293,13 @@ export function runKVStoreConformance(name, makeBackend) {
         // ------------------------------------------------------------------
         describe('tier 3: streaming iteration across a batch boundary', () => {
             const COUNT = 306; // > 256 so iteration crosses at least one IndexedDB page boundary
-            const enc = (n) => b((n >> 8) & 0xff, n & 0xff); // 2-byte big-endian
-            const dec = (k) => (k[0] << 8) | k[1];
             beforeEach(async () => {
+                // Value = key. Values must be UNIQUE across the whole fixture (not `i & 0xff`,
+                // which repeats every 256 entries) so the pairing case below can catch a
+                // backend that misaligns keys against values by a whole page.
                 const batch = store.batch();
                 for (let i = 0; i < COUNT; i++)
-                    batch.put(enc(i), b(i & 0xff));
+                    batch.put(enc(i), enc(i));
                 await batch.write();
             });
             it('streams every entry once, ascending, while awaiting an unrelated get each step', async () => {
@@ -269,6 +314,36 @@ export function runKVStoreConformance(name, makeBackend) {
                 for (let i = 0; i < COUNT; i++)
                     assert.strictEqual(seen[i], i, `entry ${i}`);
             });
+            it('pairs every value with its own key across the batch boundary', async () => {
+                // A backend that reads keys and values as two separate bulk requests (IndexedDB's
+                // getAllKeys + getAll) could zip them out of step and hand back real-looking rows
+                // filed under the wrong keys. Values are unique here, so any misalignment shows.
+                let seen = 0;
+                for await (const entry of store.iterate()) {
+                    assert.strictEqual(dec(entry.value), dec(entry.key), `entry ${dec(entry.key)} came back carrying value ${dec(entry.value)}`);
+                    seen++;
+                }
+                assert.strictEqual(seen, COUNT);
+            });
+            it('mutating yielded keys/values mid-iteration does not perturb resumption', async () => {
+                // A paged backend derives the next page's resume edge from the last key of this
+                // page. If it captures that edge AFTER handing the entry to the consumer, a
+                // consumer scribbling on the key moves where the next page starts — skipping or
+                // repeating entries. Tier 2 pins the single-page version of the read-buffer
+                // contract; this is the version that crosses a page boundary.
+                const seen = [];
+                for await (const entry of store.iterate()) {
+                    seen.push(dec(entry.key));
+                    entry.key.fill(0xff);
+                    entry.value.fill(0xff);
+                }
+                assert.strictEqual(seen.length, COUNT, 'every entry must be seen exactly once');
+                for (let i = 0; i < COUNT; i++)
+                    assert.strictEqual(seen[i], i, `entry ${i}`);
+                // ...and the scribbles must not have reached the store's own buffers.
+                assertBytes(await store.get(enc(0)), enc(0));
+                assertBytes(await store.get(enc(COUNT - 1)), enc(COUNT - 1));
+            });
             it('honors reverse across the batch boundary', async () => {
                 const seen = [];
                 for await (const entry of store.iterate({ reverse: true }))
@@ -431,6 +506,76 @@ export function runKVStoreConformance(name, makeBackend) {
                 assertBytes(await store.get(key1(5n)), b(2));
             });
         });
+        // ------------------------------------------------------------------
+        // Tier 7 — bounded iteration (see KVStore.iterate's contract)
+        //
+        // The unmetered cases run everywhere: they pin that abandoning an iteration
+        // releases whatever the backend held. The metered cases need the adapter to
+        // supply a ReadMeter, because a KVStore handle cannot see its own reads.
+        // ------------------------------------------------------------------
+        describe('tier 7: bounded iteration', () => {
+            it('breaking out mid-iteration leaves the store usable and closeable', async () => {
+                await seed1to5(store);
+                let seen = 0;
+                for await (const _entry of store.iterate()) {
+                    seen++;
+                    break;
+                }
+                assert.strictEqual(seen, 1);
+                // An iterator/transaction left open by the abandoned scan would wedge these.
+                assertBytes(await store.get(b(3)), b(30));
+                assert.deepStrictEqual(await keysOf(store), [b(1), b(2), b(3), b(4), b(5)]);
+                await store.close(); // must resolve, not hang on an unreleased handle
+            });
+            it('an exception thrown from the loop body propagates and leaves the store usable', async () => {
+                await seed1to5(store);
+                await assert.rejects(async () => {
+                    for await (const _entry of store.iterate()) {
+                        throw new Error('consumer boom');
+                    }
+                }, /consumer boom/);
+                assertBytes(await store.get(b(3)), b(30));
+                assert.deepStrictEqual(await keysOf(store), [b(1), b(2), b(3), b(4), b(5)]);
+            });
+            if (supportsReadMeter) {
+                describe('metered: reads stay bounded regardless of range size', () => {
+                    let meter;
+                    let count;
+                    beforeEach(async () => {
+                        meter = backend.readMeter;
+                        // Big enough that a backend materializing the range blows the allowance
+                        // by orders of magnitude, whatever its batch size is. Several batches
+                        // deep, so the full-drain case below actually exercises resumption.
+                        count = Math.max(3 * meter.maxReadAhead, 512);
+                        const batch = store.batch();
+                        for (let i = 0; i < count; i++)
+                            batch.put(enc(i), b(i & 0xff));
+                        await batch.write();
+                    });
+                    it('an unbounded iterate stopped after one entry reads at most one batch', async () => {
+                        await assertBoundedIterate(store, meter);
+                    });
+                    it('the same holds in reverse', async () => {
+                        await assertBoundedIterate(store, meter, { reverse: true });
+                    });
+                    it('a small limit costs the limit, not the range', async () => {
+                        // NOTE: on a backend whose batch is much larger than 5 this case adds
+                        // little over the unbounded one — the allowance is dominated by
+                        // maxReadAhead, so it cannot tell "pushed the limit down" from "read a
+                        // whole batch". It is exact for a one-entry-per-yield backend. If a
+                        // backend ever needs its limit pushdown pinned specifically, assert on
+                        // a limit LARGER than its batch instead of adding slack here.
+                        await assertBoundedIterate(store, meter, { limit: 5 }, 5);
+                    });
+                    it('draining the whole range costs about one read per entry', async () => {
+                        // Prefix cases above cannot see a backend that pages by re-reading from
+                        // the start and discarding a growing prefix (`limit`/`offset` paging):
+                        // its FIRST batch is bounded, and only the total goes quadratic.
+                        await assertBoundedIterate(store, meter, undefined, count);
+                    });
+                });
+            }
+        });
     });
 }
 //# sourceMappingURL=kv-conformance.js.map