pyric 0.0.1 → 0.1.0-alpha.7

package/dist/database/sandbox/query.js

@@ -0,0 +1,269 @@
+/** Empty spec — equivalent to "no constraints" (a plain ref query). */
+export function emptySpec() {
+    return { orderBy: null, bounds: [], limit: null };
+}
+/** Whether the spec already has a lower-bound (start) constraint. A
+ *  `startAt`/`startAfter`/`equalTo` all set the start. */
+function specHasStart(spec) {
+    return spec.bounds.some((b) => b.kind === 'startAt' || b.kind === 'startAfter' || b.kind === 'equalTo');
+}
+/** Whether the spec already has an upper-bound (end) constraint. A
+ *  `endAt`/`endBefore`/`equalTo` all set the end. */
+function specHasEnd(spec) {
+    return spec.bounds.some((b) => b.kind === 'endAt' || b.kind === 'endBefore' || b.kind === 'equalTo');
+}
+/**
+ * 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 function applyConstraint(spec, c) {
+    switch (c.kind) {
+        case 'orderBy':
+            if (spec.orderBy !== null) {
+                throw new Error("You can't combine multiple orderBy calls.");
+            }
+            return { ...spec, orderBy: c.spec };
+        case 'bound': {
+            const setsStart = c.bound.kind === 'startAt' || c.bound.kind === 'startAfter' || c.bound.kind === 'equalTo';
+            const setsEnd = c.bound.kind === 'endAt' || c.bound.kind === 'endBefore' || c.bound.kind === 'equalTo';
+            if (setsStart && specHasStart(spec)) {
+                throw new Error(`${c.bound.kind}: Starting point was already set (by another call to startAt, startAfter, or equalTo).`);
+            }
+            if (setsEnd && specHasEnd(spec)) {
+                throw new Error(`${c.bound.kind}: Ending point was already set (by another call to endAt, endBefore, or equalTo).`);
+            }
+            return { ...spec, bounds: [...spec.bounds, c.bound] };
+        }
+        case 'limit':
+            if (spec.limit !== null) {
+                throw new Error(`${c.limitKind}: Limit was already set (by another call to limitToFirst or limitToLast).`);
+            }
+            return { ...spec, limit: { kind: c.limitKind, n: c.n } };
+    }
+}
+/**
+ * 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 function compareValues(a, b) {
+    if (a === b)
+        return 0;
+    // null sorts first.
+    if (a === null)
+        return -1;
+    if (b === null)
+        return 1;
+    const ta = typeofRank(a);
+    const tb = typeofRank(b);
+    if (ta !== tb)
+        return ta - tb;
+    // Same type — value comparison.
+    if (typeof a === 'number' && typeof b === 'number')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === 'boolean' && typeof b === 'boolean')
+        return a === b ? 0 : a ? 1 : -1;
+    if (typeof a === 'string' && typeof b === 'string')
+        return a < b ? -1 : a > b ? 1 : 0;
+    // Objects/arrays are "greater" than primitives, but two object-valued
+    // children are ORDER-EQUAL under RTDB's model — the tie is broken by
+    // key, NOT by an invented JSON-string ordering (DB-B11; mirrors
+    // `ChildrenNode.ts:386-400` where ChildrenNodes compare equal). Return
+    // 0 so the caller's key tie-break takes over.
+    return 0;
+}
+function typeofRank(v) {
+    // null = 0; boolean = 1; number = 2; string = 3; object/array = 4.
+    if (v === null)
+        return 0;
+    if (typeof v === 'boolean')
+        return 1;
+    if (typeof v === 'number')
+        return 2;
+    if (typeof v === 'string')
+        return 3;
+    return 4;
+}
+/** Used to test for integer-looking strings. Mirrors `INTEGER_REGEXP_`
+ *  (`core/util/util.ts:496`). */
+const INTEGER_REGEXP = /^-?(0*)\d{1,10}$/;
+const INTEGER_32_MIN = -2147483648;
+const INTEGER_32_MAX = 2147483647;
+/** If the string is a 32-bit integer, return it; else `null`. Mirrors
+ *  `tryParseInt` (`core/util/util.ts:511-520`). */
+function tryParseInt(str) {
+    if (INTEGER_REGEXP.test(str)) {
+        const intVal = Number(str);
+        if (intVal >= INTEGER_32_MIN && intVal <= INTEGER_32_MAX) {
+            return intVal;
+        }
+    }
+    return null;
+}
+/**
+ * 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 function nameCompare(a, b) {
+    if (a === b)
+        return 0;
+    const aAsInt = tryParseInt(a);
+    const bAsInt = tryParseInt(b);
+    if (aAsInt !== null) {
+        if (bAsInt !== null) {
+            return aAsInt - bAsInt === 0 ? a.length - b.length : aAsInt - bAsInt;
+        }
+        // Integer keys sort before non-integer keys.
+        return -1;
+    }
+    else if (bAsInt !== null) {
+        return 1;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * 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 function extractOrderValue(spec, key, value) {
+    const o = spec ?? { kind: 'key' };
+    switch (o.kind) {
+        case 'key':
+            return key;
+        case 'value':
+            return value;
+        case 'child': {
+            if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+                return null;
+            }
+            // Path may be a slash-separated dotted path (`'profile/name'`).
+            const segs = o.path.split('/').filter((s) => s.length > 0);
+            let cur = value;
+            for (const s of segs) {
+                if (cur === null || typeof cur !== 'object' || Array.isArray(cur))
+                    return null;
+                cur = cur[s] ?? null;
+            }
+            return cur;
+        }
+    }
+}
+/**
+ * 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 function executeQuery(pathData, spec) {
+    // Non-collection input → no rows. RTDB's `query()` on a primitive
+    // path returns an empty snapshot.
+    if (pathData === null || typeof pathData !== 'object' || Array.isArray(pathData)) {
+        return [];
+    }
+    const obj = pathData;
+    // Enumerate immediate children only — RTDB's query model is one-level.
+    let rows = Object.entries(obj).map(([key, value]) => ({ key, value }));
+    // ─── 1. Order ─────────────────────────────────────────────────────
+    const orderingByKey = (spec.orderBy ?? { kind: 'key' }).kind === 'key';
+    rows.sort((a, b) => {
+        if (orderingByKey) {
+            // `orderByKey` compares keys under RTDB's nameCompare directly
+            // (numeric-keys-first) — there's no separate tie-break.
+            return nameCompare(a.key, b.key);
+        }
+        const va = extractOrderValue(spec.orderBy, a.key, a.value);
+        const vb = extractOrderValue(spec.orderBy, b.key, b.value);
+        const cmp = compareValues(va, vb);
+        if (cmp !== 0)
+            return cmp;
+        // Tie-break by key under nameCompare (RTDB's documented behavior —
+        // orderByChild / orderByValue ties break by key, numeric-first).
+        return nameCompare(a.key, b.key);
+    });
+    // ─── 2. Bounds ────────────────────────────────────────────────────
+    for (const b of spec.bounds) {
+        rows = rows.filter((row) => boundMatches(b, row, spec.orderBy));
+    }
+    // ─── 3. Limit ─────────────────────────────────────────────────────
+    if (spec.limit) {
+        const n = spec.limit.n;
+        if (spec.limit.kind === 'limitToFirst') {
+            rows = rows.slice(0, n);
+        }
+        else {
+            rows = n >= rows.length ? rows : rows.slice(rows.length - n);
+        }
+    }
+    return rows;
+}
+/**
+ * Does `row` pass the bound `b` under the active ordering?
+ *
+ * The bound's `value` is compared against the row's `extractOrderValue`.
+ * The optional `key` arg (for `startAt(value, key)`) is a tie-breaker
+ * for matching rows whose ordered-value equals `value` — the row passes
+ * only if its key is also at-or-past the supplied key.
+ */
+function boundMatches(b, row, orderBy) {
+    const orderingByKey = (orderBy ?? { kind: 'key' }).kind === 'key';
+    // Under `orderByKey`, the bound's `value` IS the comparison key and is
+    // compared with nameCompare (numeric-first), NOT the value type-order.
+    // Under value/child ordering, compare the ordered value, then break
+    // ties on the key with nameCompare.
+    const cmp = orderingByKey
+        ? nameCompare(row.key, String(b.value))
+        : compareValues(extractOrderValue(orderBy, row.key, row.value), b.value);
+    const keyCmp = (other) => nameCompare(row.key, other);
+    switch (b.kind) {
+        case 'startAt':
+            if (cmp > 0)
+                return true;
+            if (cmp < 0)
+                return false;
+            // Equal: defer to optional key tie-breaker.
+            return b.key === undefined || keyCmp(b.key) >= 0;
+        case 'startAfter':
+            if (cmp > 0)
+                return true;
+            if (cmp < 0)
+                return false;
+            // Equal: row passes only if key strictly past the tie-breaker.
+            return b.key === undefined ? false : keyCmp(b.key) > 0;
+        case 'endAt':
+            if (cmp < 0)
+                return true;
+            if (cmp > 0)
+                return false;
+            return b.key === undefined || keyCmp(b.key) <= 0;
+        case 'endBefore':
+            if (cmp < 0)
+                return true;
+            if (cmp > 0)
+                return false;
+            return b.key === undefined ? false : keyCmp(b.key) < 0;
+        case 'equalTo':
+            if (cmp !== 0)
+                return false;
+            return b.key === undefined || keyCmp(b.key) === 0;
+    }
+}
+//# sourceMappingURL=query.js.map

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

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

package/dist/database/sandbox/rules-eval.d.ts

@@ -0,0 +1,69 @@
+import type { AuthState } from 'pyric/sandbox';
+/**
+ * Plain-Error denial constructor. Matches the oracle observation: the
+ * thrown value's `.name === 'Error'`, `.constructor.name === 'Error'`,
+ * `.code === 'PERMISSION_DENIED'`, `.message === 'PERMISSION_DENIED: Permission denied'`.
+ *
+ * Using a one-off constructor instead of a subclass keeps
+ * `error.constructor.name === 'Error'` — which is what the live
+ * `firebase/database` SDK does. A `class PermissionDeniedError extends Error`
+ * would leak its name and break the oracle's shape claim.
+ */
+export declare function permissionDenied(): Error;
+/**
+ * Wrapper around the existing `SimulateHandler` that:
+ *   - parses freshly-deployed rules JSON into an IR (cached per
+ *     `RulesEvaluator` instance);
+ *   - exposes a `check(op, path, auth, mockData?, newData?)` that
+ *     returns `'allow' | 'deny' | 'no-rule'`.
+ *
+ * `'no-rule'` is treated as deny by callers in the user-mode path,
+ * matching RTDB's implicit-deny default ("nothing matched → no
+ * permission"). The wrapper itself stays neutral so admin-mode callers
+ * (which bypass rules entirely) can use a different fold.
+ */
+export type RuleCheck = 'allow' | 'deny' | 'no-rule';
+export interface RuleEvaluationDetails {
+    check: RuleCheck;
+    reasons: string[];
+    matchedPath?: string;
+    matchedRule?: string;
+    reason?: string;
+    pathVariableBindings?: Record<string, string>;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface EvalContext {
+    /** Identity for `request.auth`. `null` is anonymous. */
+    auth: AuthState;
+    /** Snapshot the rules engine sees as `data` / `root.child(...)`.
+     *  Pass the current tree (or a relevant subtree); the simulator
+     *  walks via path-relative lookups. */
+    mockData: Record<string, unknown>;
+    /** Proposed value at `path` for write/validate ops. Ignored for read. */
+    newData?: unknown;
+}
+export declare class RulesEvaluator {
+    private ir;
+    private readonly handler;
+    /** Replace the deployed rules. `null` clears (sandbox returns to
+     *  default-allow). */
+    setRules(rulesJson: {
+        rules: Record<string, unknown>;
+    } | null): void;
+    /** True when rules have been deployed via `setRules`. */
+    hasRules(): boolean;
+    /**
+     * Evaluate one op. Default-allow when no rules are loaded.
+     *
+     * Errors from the underlying simulator (grammar mismatches, etc.)
+     * surface as `'no-rule'` — they're treated as deny by user-mode
+     * callers, which is the safe default for "we couldn't decide". The
+     * simulator already returns success-shaped results for true/false
+     * outcomes; failures here mean we genuinely can't reason about the
+     * rule.
+     */
+    check(operation: 'read' | 'write' | 'validate', path: string, ctx: EvalContext): RuleCheck;
+    evaluate(operation: 'read' | 'write' | 'validate', path: string, ctx: EvalContext): RuleEvaluationDetails;
+}
+//# sourceMappingURL=rules-eval.d.ts.map

package/dist/database/sandbox/rules-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-eval.d.ts","sourceRoot":"","sources":["../../../src/database/sandbox/rules-eval.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,KAAK,CAIxC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,IAAI,EAAE,SAAS,CAAC;IAChB;;2CAEuC;IACvC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAuB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD;0BACsB;IACtB,QAAQ,CAAC,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,GAAG,IAAI;IAUpE,yDAAyD;IACzD,QAAQ,IAAI,OAAO;IAInB;;;;;;;;;OASG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,EACxC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,WAAW,GACf,SAAS;IAIZ,QAAQ,CACN,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,EACxC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,WAAW,GACf,qBAAqB;CAqDzB"}

package/dist/database/sandbox/rules-eval.js

@@ -0,0 +1,124 @@
+/**
+ * RTDB rules evaluation — adapter from the modular SDK's sandbox
+ * backend to `@pyric/rtdb`'s existing simulator.
+ *
+ * The hard part of an RTDB sandbox is the rules engine; the package
+ * already ships one (`SimulateHandler` + the Ohm grammar). This module
+ * is the thin glue that lets a path-based read / write op consult that
+ * engine without the modular backend needing to know about IR shapes.
+ *
+ * Permission semantics mirror the empirical oracle observations
+ * (`rtdb-rules-denied-error-code.json`):
+ *   - On denial: throw a plain `Error` (NOT a `FirebaseError`).
+ *   - `.code === 'PERMISSION_DENIED'` (uppercase snake-case — distinct
+ *     from Firestore's lowercase `'permission-denied'`).
+ *   - `.message === 'PERMISSION_DENIED: Permission denied'`.
+ *
+ * Default-allow stance: if no rules have been deployed, every operation
+ * is permitted. Matches the live RTDB default for projects whose rules
+ * have never been written (the console's "Start in test mode" template
+ * is `{ ".read": "auth != null", ".write": "auth != null" }`; an
+ * unconfigured DB allows everything until rules deploy).
+ */
+import { RtdbMapper } from '../mapper.js';
+import { SimulateHandler } from '../simulation/handler.js';
+/**
+ * Plain-Error denial constructor. Matches the oracle observation: the
+ * thrown value's `.name === 'Error'`, `.constructor.name === 'Error'`,
+ * `.code === 'PERMISSION_DENIED'`, `.message === 'PERMISSION_DENIED: Permission denied'`.
+ *
+ * Using a one-off constructor instead of a subclass keeps
+ * `error.constructor.name === 'Error'` — which is what the live
+ * `firebase/database` SDK does. A `class PermissionDeniedError extends Error`
+ * would leak its name and break the oracle's shape claim.
+ */
+export function permissionDenied() {
+    const err = new Error('PERMISSION_DENIED: Permission denied');
+    err.code = 'PERMISSION_DENIED';
+    return err;
+}
+export class RulesEvaluator {
+    ir = null;
+    handler = new SimulateHandler();
+    /** Replace the deployed rules. `null` clears (sandbox returns to
+     *  default-allow). */
+    setRules(rulesJson) {
+        if (rulesJson === null) {
+            this.ir = null;
+            return;
+        }
+        // shallowData is irrelevant here — used only by the IR for crawl
+        // metadata. Pass null so we don't synthesize fake-exists flags.
+        this.ir = RtdbMapper.mapToIR(rulesJson, null, 'sandbox://rtdb');
+    }
+    /** True when rules have been deployed via `setRules`. */
+    hasRules() {
+        return this.ir !== null;
+    }
+    /**
+     * Evaluate one op. Default-allow when no rules are loaded.
+     *
+     * Errors from the underlying simulator (grammar mismatches, etc.)
+     * surface as `'no-rule'` — they're treated as deny by user-mode
+     * callers, which is the safe default for "we couldn't decide". The
+     * simulator already returns success-shaped results for true/false
+     * outcomes; failures here mean we genuinely can't reason about the
+     * rule.
+     */
+    check(operation, path, ctx) {
+        return this.evaluate(operation, path, ctx).check;
+    }
+    evaluate(operation, path, ctx) {
+        if (this.ir === null) {
+            return {
+                check: 'allow',
+                reasons: ['No RTDB rules loaded; default allow.'],
+            };
+        }
+        // The simulator's SimulationInputSchema requires `auth` to be
+        // either `null` or `{ uid: string, token: Record<string, unknown> }` —
+        // `token` is mandatory, not optional. `AuthState` from
+        // `pyric/sandbox` makes `token` optional. Normalise here so an
+        // auth identity without custom claims (`{ uid: 'alice' }`) still
+        // satisfies the schema and the rule sees `auth.token = {}`.
+        const normalisedAuth = ctx.auth === null
+            ? null
+            : { uid: ctx.auth.uid, token: ctx.auth.token ?? {} };
+        const result = this.handler.execute(this.ir, {
+            operation,
+            path: path === '/' ? '/' : path,
+            auth: normalisedAuth,
+            mockData: ctx.mockData,
+            newData: ctx.newData,
+        });
+        if (!result.success) {
+            if (result.error.code === 'NO_MATCHING_RULE') {
+                return {
+                    check: 'no-rule',
+                    reasons: [result.error.message],
+                    errorCode: result.error.code,
+                    errorMessage: result.error.message,
+                };
+            }
+            // INVALID_INPUT / IR_NOT_GENERATED / EVALUATION_ERROR — treat as
+            // no-rule (user-mode callers fold to deny).
+            return {
+                check: 'no-rule',
+                reasons: [result.error.message],
+                errorCode: result.error.code,
+                errorMessage: result.error.message,
+            };
+        }
+        return {
+            check: result.data.allowed ? 'allow' : 'deny',
+            reasons: [
+                `${result.data.matchedPath} ${operation} ${result.data.allowed ? 'ALLOW' : 'DENY'}: ${result.data.reason}`,
+            ],
+            matchedPath: result.data.matchedPath,
+            matchedRule: result.data.matchedRule,
+            reason: result.data.reason,
+            pathVariableBindings: result.data.pathVariableBindings,
+        };
+    }
+}
+//# sourceMappingURL=rules-eval.js.map

package/dist/database/sandbox/rules-eval.js.map

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

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

@@ -0,0 +1,71 @@
+/**
+ * RTDB-side write sentinels.
+ *
+ * Production `firebase/database` ships exactly one server-side sentinel
+ * for ordinary writes: `serverTimestamp()` returns the shape
+ * `{ ".sv": "timestamp" }`. The wire serializer recognises that marker
+ * and the server stamps `Date.now()` (epoch ms) into the field. On
+ * read-back the client never sees the marker — only the resolved
+ * number. Oracle observation
+ * `scripts/oracle/observations/rtdb-servertimestamp-resolves.json`
+ * confirms the shape.
+ *
+ * Sandbox match: we recognise the same `{ ".sv": "timestamp" }` marker
+ * and resolve it at write time. The marker shape is the cross-target
+ * contract — agent code that writes a value built by
+ * `import { serverTimestamp } from 'pyric/database'` produces the same
+ * literal on either backend.
+ */
+export interface ServerTimestampSentinel {
+    '.sv': 'timestamp';
+}
+/**
+ * The `increment(delta)` sentinel — `{ ".sv": { "increment": delta } }`.
+ * Resolves to `current + delta` server-side, starting from `0` when the
+ * field is absent or non-numeric. Mirrors upstream
+ * `api/ServerValue.ts:38-44` + oracle
+ * `rtdb-modular-increment-from-missing.json` (`startsFromZero: true`).
+ */
+export interface IncrementSentinel {
+    '.sv': {
+        increment: number;
+    };
+}
+/** True when `v` is the `{ ".sv": "timestamp" }` server-timestamp marker. */
+export declare function isServerTimestampSentinel(v: unknown): v is ServerTimestampSentinel;
+/** True when `v` is the `{ ".sv": { increment: n } }` increment marker. */
+export declare function isIncrementSentinel(v: unknown): v is IncrementSentinel;
+/**
+ * Walk the value tree, replacing every server-side sentinel:
+ *   - `serverTimestamp()` → `now` (epoch ms).
+ *   - `increment(delta)` → `current + delta` at the corresponding path
+ *     (`0` when the current value is absent / non-numeric — DB-GAP).
+ *
+ * Returns a fresh tree — input is left untouched. `current` is the value
+ * presently stored at the SAME path as `value`; it's walked in parallel
+ * so each nested `increment` resolves against its own field's prior
+ * value. Pass `undefined`/`null` when there's nothing stored.
+ *
+ * Used by the sandbox backend at every write boundary (`set`, `update`,
+ * `push`). Multi-path `update({ '/a': sentinel, '/b': { nested: sentinel } })`
+ * is handled by the caller calling this per-path with that path's prior
+ * value.
+ */
+export declare function resolveSentinels(value: unknown, now: number, current?: unknown): unknown;
+/**
+ * Factory used by the modular SDK's `serverTimestamp()` export. Returns
+ * the same `{ ".sv": "timestamp" }` shape `firebase/database` emits so
+ * the prod target's wire encoder accepts it unchanged.
+ */
+export declare function serverTimestampSentinel(): ServerTimestampSentinel;
+/**
+ * Factory used by the modular SDK's `increment(delta)` export. Returns
+ * the same `{ ".sv": { increment: delta } }` shape `firebase/database`
+ * emits so the prod target's wire encoder accepts it unchanged.
+ */
+export declare function incrementSentinel(delta: number): IncrementSentinel;
+/** Debug-only — for assertions/tests. */
+export declare const SENTINEL_DEBUG: {
+    SERVER_TIMESTAMP_MARKER: string;
+};
+//# sourceMappingURL=sentinels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sentinels.d.ts","sourceRoot":"","sources":["../../../src/database/sandbox/sentinels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9B;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,uBAAuB,CAIlF;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,iBAAiB,CAQtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAsBxF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,uBAAuB,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAElE;AAED,yCAAyC;AACzC,eAAO,MAAM,cAAc;;CAA8B,CAAC"}

package/dist/database/sandbox/sentinels.js

@@ -0,0 +1,92 @@
+/**
+ * RTDB-side write sentinels.
+ *
+ * Production `firebase/database` ships exactly one server-side sentinel
+ * for ordinary writes: `serverTimestamp()` returns the shape
+ * `{ ".sv": "timestamp" }`. The wire serializer recognises that marker
+ * and the server stamps `Date.now()` (epoch ms) into the field. On
+ * read-back the client never sees the marker — only the resolved
+ * number. Oracle observation
+ * `scripts/oracle/observations/rtdb-servertimestamp-resolves.json`
+ * confirms the shape.
+ *
+ * Sandbox match: we recognise the same `{ ".sv": "timestamp" }` marker
+ * and resolve it at write time. The marker shape is the cross-target
+ * contract — agent code that writes a value built by
+ * `import { serverTimestamp } from 'pyric/database'` produces the same
+ * literal on either backend.
+ */
+const SERVER_TIMESTAMP_MARKER = '{".sv":"timestamp"}';
+/** True when `v` is the `{ ".sv": "timestamp" }` server-timestamp marker. */
+export function isServerTimestampSentinel(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const obj = v;
+    return obj['.sv'] === 'timestamp';
+}
+/** True when `v` is the `{ ".sv": { increment: n } }` increment marker. */
+export function isIncrementSentinel(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const sv = v['.sv'];
+    return (sv !== null &&
+        typeof sv === 'object' &&
+        typeof sv.increment === 'number');
+}
+/**
+ * Walk the value tree, replacing every server-side sentinel:
+ *   - `serverTimestamp()` → `now` (epoch ms).
+ *   - `increment(delta)` → `current + delta` at the corresponding path
+ *     (`0` when the current value is absent / non-numeric — DB-GAP).
+ *
+ * Returns a fresh tree — input is left untouched. `current` is the value
+ * presently stored at the SAME path as `value`; it's walked in parallel
+ * so each nested `increment` resolves against its own field's prior
+ * value. Pass `undefined`/`null` when there's nothing stored.
+ *
+ * Used by the sandbox backend at every write boundary (`set`, `update`,
+ * `push`). Multi-path `update({ '/a': sentinel, '/b': { nested: sentinel } })`
+ * is handled by the caller calling this per-path with that path's prior
+ * value.
+ */
+export function resolveSentinels(value, now, current) {
+    if (isServerTimestampSentinel(value))
+        return now;
+    if (isIncrementSentinel(value)) {
+        const delta = value['.sv'].increment;
+        const base = typeof current === 'number' ? current : 0;
+        return base + delta;
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((v, i) => resolveSentinels(v, now, Array.isArray(current) ? current[i] : undefined));
+    }
+    const curObj = current !== null && typeof current === 'object' && !Array.isArray(current)
+        ? current
+        : undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = resolveSentinels(v, now, curObj ? curObj[k] : undefined);
+    }
+    return out;
+}
+/**
+ * Factory used by the modular SDK's `serverTimestamp()` export. Returns
+ * the same `{ ".sv": "timestamp" }` shape `firebase/database` emits so
+ * the prod target's wire encoder accepts it unchanged.
+ */
+export function serverTimestampSentinel() {
+    return { '.sv': 'timestamp' };
+}
+/**
+ * Factory used by the modular SDK's `increment(delta)` export. Returns
+ * the same `{ ".sv": { increment: delta } }` shape `firebase/database`
+ * emits so the prod target's wire encoder accepts it unchanged.
+ */
+export function incrementSentinel(delta) {
+    return { '.sv': { increment: delta } };
+}
+/** Debug-only — for assertions/tests. */
+export const SENTINEL_DEBUG = { SERVER_TIMESTAMP_MARKER };
+//# sourceMappingURL=sentinels.js.map