pyric 0.0.1 → 0.1.0-alpha.7

package/dist/database/sandbox/normalize.js

@@ -0,0 +1,165 @@
+/** True for invalid Firebase keys. Mirrors `INVALID_KEY_REGEX_`
+ *  (`validation.ts:45`): `.`, `#`, `$`, `/`, `[`, `]`, control chars. */
+const INVALID_KEY_REGEX = /[\[\].#$/\u0000-\u001F\u007F]/;
+/** A valid Firebase key — non-empty string, no forbidden chars. Mirrors
+ *  `isValidKey` (`validation.ts:58`). The `.priority` / `.value` / `.sv`
+ *  metadata keys are handled by the caller before this check. */
+function isValidKey(key) {
+    return key.length !== 0 && !INVALID_KEY_REGEX.test(key);
+}
+/** True for a number RTDB rejects (NaN / ±Infinity). Mirrors
+ *  `isInvalidJSONNumber` (`util.ts`). */
+function isInvalidJSONNumber(value) {
+    return (typeof value === 'number' &&
+        (Number.isNaN(value) || value === Infinity || value === -Infinity));
+}
+/** The metadata keys RTDB exempts from key validation. */
+function isMetadataKey(key) {
+    return key === '.priority' || key === '.value' || key === '.sv';
+}
+/**
+ * Validate a value against RTDB's write rules, throwing the upstream
+ * error shape (a plain `Error`) on the first violation. Mirrors
+ * `validateFirebaseData` (`validation.ts:112-199`). `pathPrefix` is the
+ * absolute path the value is being written to — used for a prod-shaped
+ * error message.
+ */
+export function validateWrite(value, pathPrefix) {
+    validateData(value, pathPrefix, 'set');
+}
+function validateData(value, path, fnName) {
+    if (value === undefined) {
+        throw new Error(`${fnName} failed: value argument contains undefined in property '${path}'`);
+    }
+    if (typeof value === 'function') {
+        throw new Error(`${fnName} failed: value argument contains a function in property '${path}'`);
+    }
+    if (isInvalidJSONNumber(value)) {
+        throw new Error(`${fnName} failed: value argument contains ${String(value)} in property '${path}'`);
+    }
+    if (value === null || typeof value !== 'object') {
+        return;
+    }
+    if (Array.isArray(value)) {
+        // Arrays validate per-element. Holes (`undefined`) are skipped (they
+        // become absent integer keys), matching `each` over a sparse array.
+        for (let i = 0; i < value.length; i++) {
+            if (!(i in value))
+                continue;
+            const el = value[i];
+            if (el === undefined)
+                continue;
+            validateData(el, `${path}/${i}`, fnName);
+        }
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (!isMetadataKey(key) && !isValidKey(key)) {
+            throw new Error(`${fnName} failed: value argument contains an invalid key (${key}) in path ${path}. ` +
+                'Keys must be non-empty strings and can\'t contain ".", "#", "$", "/", "[", or "]"');
+        }
+        validateData(child, `${path}/${key}`, fnName);
+    }
+}
+/**
+ * Validate then normalize a resolved write value into RTDB's storage
+ * shape. Returns the storable `JsonValue` (or `null` if the value prunes
+ * to nothing — i.e. it's a delete). Mirrors `nodeFromJSON` collapse:
+ *
+ *   - arrays → integer-keyed objects, holes / null / undefined elements
+ *     dropped;
+ *   - `null` children dropped;
+ *   - empty objects (after pruning) → `null`.
+ *
+ * Leaf primitives (string / number / boolean) pass through unchanged —
+ * including at the root (DB-B13: `set(ref(db), 'hello')` is legal).
+ */
+export function normalizeWrite(value, pathPrefix) {
+    validateWrite(value, pathPrefix);
+    return normalizeNode(value);
+}
+/**
+ * Normalize a validated value into storage shape. No validation here —
+ * call {@link validateWrite} first (or use {@link normalizeWrite}).
+ * Returns `null` for a value that prunes away.
+ */
+export function normalizeNode(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'object')
+        return value;
+    // Array → integer-keyed object. Holes / null / undefined elements are
+    // dropped (upstream `each` over an array skips them).
+    if (Array.isArray(value)) {
+        const out = {};
+        for (let i = 0; i < value.length; i++) {
+            if (!(i in value))
+                continue;
+            const child = normalizeNode(value[i]);
+            if (child === null)
+                continue;
+            out[String(i)] = child;
+        }
+        return Object.keys(out).length === 0 ? null : out;
+    }
+    // Plain object → prune null children + empty subtrees.
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (key === '.sv') {
+            // Server-value wrapper that survived (shouldn't normally reach
+            // here post-sentinel-resolution) — keep verbatim.
+            out[key] = child;
+            continue;
+        }
+        const normalized = normalizeNode(child);
+        if (normalized === null)
+            continue;
+        out[key] = normalized;
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+/**
+ * Read-side array coercion. RTDB renders an integer-keyed object back as
+ * an array on `DataSnapshot.val()` when ALL keys are non-negative
+ * integers AND the max key is `< 2 * numKeys` (a density heuristic that
+ * avoids materializing a giant sparse array). Mirrors `ChildrenNode.val`
+ * (`ChildrenNode.ts:196-230`). Recurses into children.
+ *
+ * Absent integer slots become array holes filled with `null` (matching
+ * prod, where a coerced array's missing indices read back as `null`).
+ */
+export function coerceArrays(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        // Already an array (shouldn't occur in stored data, but be defensive).
+        return value.map((v) => coerceArrays(v));
+    }
+    const obj = value;
+    const keys = Object.keys(obj);
+    let allIntegerKeys = keys.length > 0;
+    let maxKey = 0;
+    for (const k of keys) {
+        if (/^(0|[1-9]\d*)$/.test(k)) {
+            maxKey = Math.max(maxKey, Number(k));
+        }
+        else {
+            allIntegerKeys = false;
+            break;
+        }
+    }
+    if (allIntegerKeys && maxKey < 2 * keys.length) {
+        const arr = [];
+        for (let i = 0; i <= maxKey; i++) {
+            const child = obj[String(i)];
+            arr[i] = child === undefined ? null : coerceArrays(child);
+        }
+        return arr;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = coerceArrays(v);
+    }
+    return out;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/database/sandbox/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/database/sandbox/normalize.ts"],"names":[],"mappings":"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"}

package/dist/database/sandbox/push-id.d.ts

@@ -0,0 +1,32 @@
+/**
+ * RTDB push-ID generator — matches Firebase's published `nextPushId`
+ * implementation exactly so a sandbox-minted key is shape-compatible
+ * with a key produced by `firebase/database`'s real `push(ref)`.
+ *
+ * Locked by oracle observation
+ * `scripts/oracle/observations/rtdb-push-autoid-format.json`:
+ * length 20, leading `-`, lexicographically monotonic when generated
+ * in quick succession.
+ *
+ * Format: 20 characters total.
+ *   - First 8 chars encode the current ms-since-epoch in base-64 using
+ *     the alphabet below (lex-sortable: ascending time = ascending key).
+ *   - Last 12 chars are random, but if two calls land in the same
+ *     millisecond the random tail is *incremented* (not regenerated)
+ *     so two adjacent calls still sort. Firebase's reference impl does
+ *     exactly this; we match it bit for bit.
+ *
+ * The alphabet is the published `PUSH_CHARS` constant: 64 characters,
+ * with `-` as the smallest and `z` as the largest under lexicographic
+ * (byte) ordering — that ordering is the whole point of the format.
+ *
+ * Reference: firebase-js-sdk `packages/database/src/core/util/NextPushId.ts`.
+ */
+/**
+ * Generate a new RTDB push ID. Deterministic across the
+ * "two pushes in the same ms" boundary: the random tail is the
+ * single-step lex-successor of the previous tail, guaranteeing
+ * `keyA < keyB` when `A` was minted before `B`.
+ */
+export declare function generatePushId(now?: number): string;
+//# sourceMappingURL=push-id.d.ts.map

package/dist/database/sandbox/push-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-id.d.ts","sourceRoot":"","sources":["../../../src/database/sandbox/push-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAgD/D"}

package/dist/database/sandbox/push-id.js

@@ -0,0 +1,82 @@
+/**
+ * RTDB push-ID generator — matches Firebase's published `nextPushId`
+ * implementation exactly so a sandbox-minted key is shape-compatible
+ * with a key produced by `firebase/database`'s real `push(ref)`.
+ *
+ * Locked by oracle observation
+ * `scripts/oracle/observations/rtdb-push-autoid-format.json`:
+ * length 20, leading `-`, lexicographically monotonic when generated
+ * in quick succession.
+ *
+ * Format: 20 characters total.
+ *   - First 8 chars encode the current ms-since-epoch in base-64 using
+ *     the alphabet below (lex-sortable: ascending time = ascending key).
+ *   - Last 12 chars are random, but if two calls land in the same
+ *     millisecond the random tail is *incremented* (not regenerated)
+ *     so two adjacent calls still sort. Firebase's reference impl does
+ *     exactly this; we match it bit for bit.
+ *
+ * The alphabet is the published `PUSH_CHARS` constant: 64 characters,
+ * with `-` as the smallest and `z` as the largest under lexicographic
+ * (byte) ordering — that ordering is the whole point of the format.
+ *
+ * Reference: firebase-js-sdk `packages/database/src/core/util/NextPushId.ts`.
+ */
+const PUSH_CHARS = '-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz';
+let lastPushTime = 0;
+const lastRandChars = new Array(12).fill(0);
+/**
+ * Generate a new RTDB push ID. Deterministic across the
+ * "two pushes in the same ms" boundary: the random tail is the
+ * single-step lex-successor of the previous tail, guaranteeing
+ * `keyA < keyB` when `A` was minted before `B`.
+ */
+export function generatePushId(now = Date.now()) {
+    const duplicateTime = now === lastPushTime;
+    lastPushTime = now;
+    // First 8 chars: ms-timestamp in base-64, lex-sortable
+    const timeStampChars = new Array(8);
+    let ts = now;
+    for (let i = 7; i >= 0; i--) {
+        timeStampChars[i] = PUSH_CHARS.charAt(ts % 64);
+        ts = Math.floor(ts / 64);
+    }
+    if (ts !== 0) {
+        // Defensive: clock past the 8-char window — won't happen until year ~2554.
+        throw new Error('RTDB push-id: timestamp overflow.');
+    }
+    let id = timeStampChars.join('');
+    if (!duplicateTime) {
+        for (let i = 0; i < 12; i++) {
+            lastRandChars[i] = Math.floor(Math.random() * 64);
+        }
+    }
+    else {
+        // Same-ms case: increment the previous tail by one lex step. Carry up
+        // from the least-significant position. Matches the published impl;
+        // ensures (rare) sub-ms repeats remain sortable.
+        let i;
+        for (i = 11; i >= 0 && lastRandChars[i] === 63; i--) {
+            lastRandChars[i] = 0;
+        }
+        if (i < 0) {
+            // 12-digit base-64 odometer wrapped within a single ms — astronomically
+            // unlikely. Fall back to a fresh random tail so the result is still
+            // *some* valid key; consumers shouldn't observe this in practice.
+            for (let j = 0; j < 12; j++) {
+                lastRandChars[j] = Math.floor(Math.random() * 64);
+            }
+        }
+        else {
+            lastRandChars[i] = (lastRandChars[i] ?? 0) + 1;
+        }
+    }
+    for (let i = 0; i < 12; i++) {
+        id += PUSH_CHARS.charAt(lastRandChars[i]);
+    }
+    if (id.length !== 20) {
+        throw new Error(`RTDB push-id: bad length ${id.length}.`);
+    }
+    return id;
+}
+//# sourceMappingURL=push-id.js.map

package/dist/database/sandbox/push-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-id.js","sourceRoot":"","sources":["../../../src/database/sandbox/push-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,UAAU,GACd,kEAAkE,CAAC;AAErE,IAAI,YAAY,GAAG,CAAC,CAAC;AACrB,MAAM,aAAa,GAAa,IAAI,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IACrD,MAAM,aAAa,GAAG,GAAG,KAAK,YAAY,CAAC;IAC3C,YAAY,GAAG,GAAG,CAAC;IAEnB,uDAAuD;IACvD,MAAM,cAAc,GAAa,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,EAAE,GAAG,GAAG,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,cAAc,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/C,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;QACb,2EAA2E;QAC3E,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEjC,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,sEAAsE;QACtE,mEAAmE;QACnE,iDAAiD;QACjD,IAAI,CAAS,CAAC;QACd,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YACpD,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACV,wEAAwE;YACxE,oEAAoE;YACpE,kEAAkE;YAClE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5B,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;aAAM,CAAC;YACN,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,EAAE,IAAI,UAAU,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAE,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,4BAA4B,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/database/sandbox/query.d.ts

@@ -0,0 +1,175 @@
+/**
+ * RTDB query pipeline — order, filter, limit over an in-memory subtree.
+ *
+ * The modular SDK's `query(ref, ...constraints)` constructs a tagged
+ * `Query` carrying a `QuerySpec`. `get(query)` / `onValue(query, cb)`
+ * feed the spec + the current tree-subtree into {@link executeQuery},
+ * which runs the documented RTDB pipeline:
+ *
+ *   1. Enumerate the children at the path (root + immediate children;
+ *      primitive values at the path are NOT eligible — `query()` only
+ *      makes sense on a collection-shaped node).
+ *   2. Order them by the active `orderBy*` constraint (default
+ *      `orderByKey` if none supplied).
+ *   3. Apply `startAt` / `startAfter` / `endAt` / `endBefore` / `equalTo`
+ *      bounds against the active ordering's comparison value.
+ *   4. Apply `limitToFirst(n)` or `limitToLast(n)` — they truncate the
+ *      result window from either end.
+ *
+ * The output is an ordered list of `{ key, value }` pairs ready for the
+ * snap-builder to expose via `snap.forEach` and `snap.val()`.
+ *
+ * Oracle-locked semantics (all observed against blockingfun):
+ *   - `startAt`/`endAt` are **inclusive**
+ *     (`rtdb-modular-orderbychild-window.json`).
+ *   - `startAfter`/`endBefore` are **exclusive**
+ *     (`rtdb-modular-startafter-endbefore-exclusive.json`).
+ *   - `equalTo(v)` returns ALL children whose ordered key === v — no
+ *     uniqueness enforced (`rtdb-modular-equalTo-filter.json`).
+ *   - `limitToFirst(n)` keeps the first n; `limitToLast(n)` keeps the
+ *     last n (post-order, pre-limit window). Locked by
+ *     `rtdb-modular-limittofirst-vs-limittolast.json`.
+ *   - `orderByKey()` sorts lexicographically by string-coerced key
+ *     (`rtdb-modular-orderbykey-window.json`).
+ *   - `orderByValue()` sorts by the child's primitive value (number
+ *     before string before boolean is RTDB's documented type order).
+ *     In prod this requires `.indexOn: ".value"` — sandbox does NOT
+ *     enforce indexes (no rules-engine integration here). Locked by
+ *     `rtdb-modular-orderbyvalue-numeric.json` (note: the prod probe
+ *     threw `Index not defined`; the sandbox returns the ordered window
+ *     directly. Tests configure default-allow rules so the sandbox
+ *     match is the semantic one — not the index-enforcement one).
+ *
+ * Note: this module deliberately does NOT model `.indexOn` rules — the
+ * sandbox is for unit-test-fast iteration where the consumer's intent
+ * is the query result, not rules conformance. Rules-engine-driven index
+ * enforcement is a deferred follow-up (would naturally hang off
+ * `RulesEvaluator` not here).
+ */
+import type { JsonValue } from './data-tree.js';
+/** Ordering selector. Stored as a discriminated union so the executor
+ *  can switch on the kind without re-parsing. */
+export type OrderBy = {
+    kind: 'child';
+    path: string;
+} | {
+    kind: 'key';
+} | {
+    kind: 'value';
+};
+/** Cursor or filter bound. `startAt`/`endAt` are inclusive; the
+ *  `*Exclusive` variants drop the boundary value. `equalTo` collapses
+ *  start + end onto the same value (and is sugar for `startAt(v) +
+ *  endAt(v)` per the SDK docs). */
+export type Bound = {
+    kind: 'startAt';
+    value: JsonValue;
+    key?: string;
+} | {
+    kind: 'startAfter';
+    value: JsonValue;
+    key?: string;
+} | {
+    kind: 'endAt';
+    value: JsonValue;
+    key?: string;
+} | {
+    kind: 'endBefore';
+    value: JsonValue;
+    key?: string;
+} | {
+    kind: 'equalTo';
+    value: JsonValue;
+    key?: string;
+};
+/** Window-size constraint. Mutually exclusive with each other (prod
+ *  rejects setting both — we don't reject here but the executor
+ *  prioritises the last one set, matching `firebase/database`). */
+export type LimitKind = 'limitToFirst' | 'limitToLast';
+/**
+ * A {@link Query} is a ref + a chain of constraints. The chain is
+ * order-independent in terms of declared shape — the executor groups
+ * constraints into {order, bounds, limit} during apply.
+ */
+export interface QuerySpec {
+    /** Active ordering. `null` means default (`orderByKey`). */
+    orderBy: OrderBy | null;
+    /** Range/equality filters. Multiple bounds compose. */
+    bounds: Bound[];
+    /** Optional limit. Last-wins if set more than once. */
+    limit: {
+        kind: LimitKind;
+        n: number;
+    } | null;
+}
+/** Empty spec — equivalent to "no constraints" (a plain ref query). */
+export declare function emptySpec(): QuerySpec;
+/**
+ * Append a constraint, returning a NEW spec. (Constraints are immutable
+ * values; the query builder threads them via free functions matching
+ * `firebase/database`'s shape.)
+ *
+ * Conflicting constraints throw, mirroring the upstream `_apply` guards
+ * (`api/Reference_impl.ts`) — DB-B5. Prod rejects: multiple `orderBy*`,
+ * a second `limitToFirst`/`limitToLast`, a second start (`startAt`/
+ * `startAfter`/`equalTo`) or end (`endAt`/`endBefore`/`equalTo`).
+ */
+export declare function applyConstraint(spec: QuerySpec, c: Constraint): QuerySpec;
+/**
+ * Internal constraint variant — produced by the public `orderBy*`,
+ * `startAt`, `limitToFirst`, ... factories and consumed by `query()`
+ * which folds them into a `QuerySpec`.
+ */
+export type Constraint = {
+    kind: 'orderBy';
+    spec: OrderBy;
+} | {
+    kind: 'bound';
+    bound: Bound;
+} | {
+    kind: 'limit';
+    limitKind: LimitKind;
+    n: number;
+};
+/**
+ * Compare two `JsonValue`s under RTDB's documented type-order rules.
+ * Locked by the upstream contract (Firebase docs: null < false < true
+ * < number < string < object). The sandbox's ordering only needs to
+ * match against same-type-or-null/undefined.
+ *
+ * Returns -1 / 0 / 1.
+ */
+export declare function compareValues(a: JsonValue, b: JsonValue): number;
+/**
+ * Compare two Firebase key names under RTDB's `nameCompare` ordering:
+ * integer-looking keys sort FIRST (numerically; ties broken by string
+ * length so `"01"` follows `"1"`), then non-integer keys sort
+ * lexicographically. Mirrors `nameCompare` (`core/util/util.ts:253-276`).
+ *
+ * This is RTDB's universal key order — it drives `orderByKey()`, the
+ * tie-break for `orderByChild`/`orderByValue`, and the `key` argument of
+ * `startAt(value, key)` / `endAt(value, key)` cursors. Plain
+ * lexicographic compare (DB-B4) put `"10"` before `"2"`.
+ */
+export declare function nameCompare(a: string, b: string): number;
+/**
+ * Extract the value the ordering uses to compare a child. For
+ * `orderByKey()` it's the key string; for `orderByValue()` the child's
+ * raw value; for `orderByChild(path)` the nested field at `path`
+ * (which may itself be missing → `null`).
+ */
+export declare function extractOrderValue(spec: OrderBy | null, key: string, value: JsonValue): JsonValue;
+/** Result row — kept minimal so the snap-builder can render it cheaply. */
+export interface QueryRow {
+    key: string;
+    value: JsonValue;
+}
+/**
+ * Run a {@link QuerySpec} against the data at a path. The caller passes
+ * the raw value at the path (a `Record<string, JsonValue>` if it's a
+ * collection, anything else → empty result).
+ *
+ * Returns an ordered, filtered, limited list of rows.
+ */
+export declare function executeQuery(pathData: JsonValue, spec: QuerySpec): QueryRow[];
+//# sourceMappingURL=query.d.ts.map

package/dist/database/sandbox/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/database/sandbox/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;iDACiD;AACjD,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;mCAGmC;AACnC,MAAM,MAAM,KAAK,GACb;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;mEAEmE;AACnE,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,aAAa,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,4DAA4D;IAC5D,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,uDAAuD;IACvD,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,uDAAuD;IACvD,KAAK,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9C;AAED,uEAAuE;AACvE,wBAAgB,SAAS,IAAI,SAAS,CAErC;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,CAAC,EAAE,UAAU,GACZ,SAAS,CAgCX;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAkBhE;AA6BD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAcxD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,GACf,SAAS,CAqBX;AAED,2EAA2E;AAC3E,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,EACnB,IAAI,EAAE,SAAS,GACd,QAAQ,EAAE,CA2CZ"}