pyric/database compatibility matrix
100% of the public API supported
59 of 59 public API
Status legend
Public API
pyric/database mirrors the public firebase/database API in the Pyric sandbox. The rows below compare its observable behaviour with Firebase.
getDatabase(ctx) builds a sandbox-target Database; frozen ctx.auth baked in
unit:modular/sandbox-target.test.ts ("getDatabase(ctx) returns a tagged Database handle")getDatabase(sandbox) builds a sandbox-live target; reads sandbox.currentUser per op
unit:modular/sandbox-target.test.ts ("reads sandbox.currentUser at op time, not at getDatabase time")ref(db, path?) returns a path-tagged DatabaseReference; default is root
unit:modular/sandbox-target.test.ts ("ref(db) returns a root ref" + "ref(db, ...) returns a path ref")child(ref, 'sub/path') composes paths; result inherits the parent's target
unit:modular/sandbox-target.test.ts ("child(ref, 'sub') composes paths")ref.parent returns the parent ref; root.parent === null
unit:modular/sandbox-target.test.ts ("ref.parent returns the parent ref; root.parent is null")ref.root returns the root ref of the same target
unit:modular/sandbox-target.test.ts ("ref.root returns the root ref")get(ref) returns a DataSnapshot-shaped object with val(), exists(), key, child(), hasChildren(), size, and toJSON(); the modular Web surface does not expose numChildren().
unit:modular/sandbox-target.test.ts (snapshot shape tests)get on an absent path resolves to { val: null, exists: false } (matches DataSnapshot.val() contract)
unit:modular/sandbox-target.test.ts ("reads return null for an absent path")set(ref, value) replaces the value at the path
unit:modular/sandbox-target.test.ts ("round-trips a primitive value" + "round-trips nested objects"); matches oracle observation packages/conformance/observations/rtdb/rtdb-set-then-get-roundtrip.json (prod observation blocked on rules; sandbox locks the contract directly)set(ref, null) deletes the subtree at the path
unit:modular/sandbox-target.test.ts ("set(ref, null) deletes the path"); matches oracle observation packages/conformance/observations/rtdb/rtdb-remove-vs-set-null.jsonremove(ref) is equivalent to set(ref, null) (same end state)
unit:modular/sandbox-target.test.ts ("remove and set(null) produce identical end-state"); matches oracle observation packages/conformance/observations/rtdb/rtdb-remove-vs-set-null.jsonupdate(ref, patch) shallow-merges top-level keys at the ref's path
unit:modular/sandbox-target.test.ts ("shallow-merges top-level keys")null value in a shallow update deletes that key
unit:modular/sandbox-target.test.ts ("null values in a shallow update delete the key")update(rootRef, { '/a/x': v1, '/b/y': v2 }) is a multi-path atomic write — all paths land or none do
unit:upstream-rtdb-probes.test.ts ("one update nulls, mutates, and displaces within a limitToFirst window") + unit:modular/sandbox-target.test.ts (atomic multipath + rules denial); matches the matrix #23 prod contractOverlapping multi-path updates (one path is a descendant of another) reject before any path is written
unit:modular/sandbox-target.test.ts ("rejects overlapping paths")update() applies when called, as set() does, so a client's writes land in call order: update(r, { x: 2 }) then set(child(r, 'x'), 3) stores 3, update then remove leaves the path empty, and a listener sees the update before update() returns (RT-1)
unit:modular/update-write-order.test.tspush(ref) mints a 20-char auto-id key starting with -, lexicographically sortable
unit:modular/sandbox-target.test.ts ("mints 20-char keys starting with \"-\"" + "sequential push keys are lex-sortable"); matches oracle observation packages/conformance/observations/rtdb/rtdb-push-autoid-format.jsonpush(ref, value) writes value at the new child path
unit:modular/sandbox-target.test.ts ("push(ref, value) writes the value at the new child path")pushKey() mints a fresh push-shaped key without writing — used by callers building multi-path updates that need the key first
unit:modular/sandbox-target.test.ts ("pushKey() mints a fresh key without writing")serverTimestamp() returns the { ".sv": "timestamp" } sentinel marker the wire encoder recognises
unit:modular/sandbox-target.test.ts ("serverTimestamp() returns the documented shape"); matches the prod wire contractserverTimestamp() resolves to a number (epoch ms) on read-back
unit:modular/sandbox-target.test.ts ("resolves to a number on read-back"); matches oracle observation packages/conformance/observations/rtdb/rtdb-servertimestamp-resolves.json (prod observation blocked on rules; sandbox locks the contract directly)serverTimestamp() sentinels resolve when nested inside multi-path update payloads
unit:modular/sandbox-target.test.ts ("resolves sentinels nested deep inside an update payload")Rules-denied write throws a plain Error (NOT a FirebaseError) with .code === 'PERMISSION_DENIED' (uppercase snake-case) and .message === 'PERMISSION_DENIED: Permission denied'
unit:modular/sandbox-target.test.ts ("rules-denied set throws a plain Error with PERMISSION_DENIED code"); matches oracle observation packages/conformance/observations/rtdb/rtdb-rules-denied-error-code.json (against digame-mas, fb-js-sdk 12.19.0). The sandbox adds an own enumerable denialContext (engine rtdb, the deciding rule, bindings and request) to the same plain Error; unit:denial-context.test.ts asserts class, name, code and message are unchanged for every denied operation, and the worker bridge test asserts served pages receive the context. (Structured evidence: rtdb-denial-context.test.ts)Rules-denied read throws the same plain-Error PERMISSION_DENIED shape as a denied write
unit:modular/sandbox-target.test.ts ("rules-denied get throws the same plain Error shape"); matches oracle observation packages/conformance/observations/rtdb/rtdb-rules-denied-error-code.json (Structured evidence: denial-context.test.ts)Rules-denied remove throws the same plain-Error PERMISSION_DENIED shape
unit:modular/sandbox-target.test.ts ("rules-denied remove throws the same plain Error shape") (Structured evidence: denial-context.test.ts)onValue(ref, cb) fires immediately on subscribe with the current value at the path
unit:modular/sandbox-target.test.ts ("fires on subscribe with the current value")onValue fires again after every write that CHANGES the value at the watched path; a write that leaves the watched subtree byte-identical (a no-change re-write, or an ancestor/descendant write that doesn't alter this path) is suppressed (DB-B8)
unit:modular/sandbox-target.test.ts ("fires after every write that touches the watched path") + unit:modular/no-change-suppression.test.ts ("re-writing the same value does NOT re-fire" + "ancestor write leaving the subtree unchanged does NOT fire") + unit:modular/negative-zero-write.test.ts (a -0 write over a stored 0 fires no value or child_changed event and stores 0, since production's JSON carries -0 as 0)onValue fires after a descendant write (the listener sees subtree changes)
unit:modular/sandbox-target.test.ts ("fires on a descendant write")onValue initial-fire for an absent path delivers val=null, exists=false (matches matrix expectation locked by oracle for sentinel/listener shape)
unit:modular/sandbox-target.test.ts ("absent path: initial fire delivers val=null, exists=false")The onValue return value is an unsubscribe function; calling it stops further fires
unit:modular/sandbox-target.test.ts ("fires after every write that touches the watched path" — checks unsubscribed listener doesn't fire on subsequent write)onChildAdded / onChildChanged / onChildRemoved / onChildMoved — plain-ref subscription surface
unit:modular/sandbox-child-events.test.ts exercises all four plain-reference child listener registrars; M41–M48 own their per-event oracle claims.onChildAdded replays each existing direct child of the parent ref on subscribe (one fire per existing key)
unit:modular/sandbox-child-events.test.ts ("replays existing direct children on subscribe — one fire per key"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-onchildadded-initial-replay.json (seeded {k1,k2,k3}, observed firedKeys: ['k1','k2','k3']).After subscribe, onChildAdded fires exactly once per new direct child write; snapshot carries {key, val} of the new child
unit:modular/sandbox-child-events.test.ts ("fires exactly once per NEW direct child after subscribe"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-onchildadded-post-subscribe.json (postSubscribeFires: 1, lastFire: {key:'k3', val:{v:3}}).onChildChanged has NO initial replay; fires once when an existing direct child's value transitions; snapshot carries the NEW value
unit:modular/sandbox-child-events.test.ts ("does NOT fire on subscribe (no initial replay)" + "fires once when an existing child transitions to a new value; snapshot carries NEW val"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-onchildchanged-fires-on-update.json (firedOnInitial: 0, firedOnUpdate: 1, lastFire: {key:'k1', val:{v:2}}).onChildChanged does NOT fire for added or removed children — those go to the other event listeners
unit:modular/sandbox-child-events.test.ts ("does NOT fire when a child is added" + "does NOT fire when a child is removed").onChildRemoved has NO initial replay; fires once when a direct child is deleted (via remove(child) or set(child, null)); snapshot carries the PRIOR (now-removed) value
unit:upstream-rtdb-probes.test.ts (parent wipe fan-out via remove(parent) / set(parent, scalar)) + unit:modular/sandbox-child-events.test.ts (single-child delete carries PRIOR val, and the removed child's own and descendants' priorities in priority and exportVal(), on a reference and a query); matches oracle rtdb-modular-onchildremoved-fires-on-delete.jsonA plain-reference onChildMoved uses Firebase's default priority index: ordinary value changes that preserve priority do not move, while each changed child's priority emits one event even if its predecessor stays the same
rtdb-modular-priority-contract captures the same one-event-per-priority-operation sequence on a plain ref and an explicit orderByPriority() query, including a priority change that retains the same predecessor; unit:modular/sandbox-child-events.test.ts separately pins no movement for an ordinary value-only change. unit:modular/priority-listeners.test.ts pins a move for each child whose own priority one parent write changes, and none for a change to a descendant's priority alone. (Structured evidence: priority-metadata-cdd.test.ts)off(ref) (no event type) removes ALL listeners at that ref — value + every child event variety
unit:modular/sandbox-child-events.test.ts ("off(ref) removes ALL listeners at the ref" + "off(ref) also removes value listeners at the same path"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-off-stops-child-fires.json (postOffFires: 0).off(ref, eventType?, callback?) variants: off(ref, 'value') / off(ref, 'child_added') / off(ref, eventType, cb) remove the targeted subset; returned-unsubscribe from onChild* is equivalent to off(ref, eventType, cb)
unit:modular/sandbox-child-events.test.ts ("off(ref, \"child_added\") removes only that event variety" + "off(ref, \"value\") removes only value listeners" + "off(ref, eventType, cb) removes only the matching callback" + "returned-unsubscribe from onChildAdded is functionally equivalent to off()").connectDatabaseEmulator(db, host, port) is a no-op on sandbox targets (the sandbox IS a local emulator)
unit:modular/sandbox-target.test.ts ("is a no-op on sandbox handles")sandbox.setRules(db, rulesJson) deploys rules to the in-process simulator; setRules(db, null) clears rules (default-allow)
unit:modular/sandbox-target.test.ts ("sandbox.setRules(db, null) clears rules"). Each rule expression of the deployed ruleset is parsed once, on its first evaluation, and later writes, multi-path updates, reads, and simulate() calls on a compiled ruleset reuse that parse; the next setRules call parses the new ruleset (unit:database/sandbox/rules-parse-count.test.ts).sandbox.setData(db, { '/path': value }) bulk-loads data, bypassing rules
unit:modular/sandbox-target.test.ts ("sandbox.setData seeds the tree (rule-bypass)")sandbox.snapshotState(db) dumps the full tree as a plain JSON object
unit:modular/sandbox-target.test.ts ("sandbox.snapshotState dumps the full tree")query(ref, ...constraints) + ordering/range constraints
unit:upstream-rtdb-probes.test.ts ("orderByChild('a/b') + limitToFirst orders by the nested path") + unit:modular/queries.test.ts + oracle observations under packages/conformance/observations/rtdb-modular/; see M49–M64 for the per-claim breakdown.runTransaction(ref, fn, options?) resolves to { committed: boolean, snapshot: DataSnapshot } for the happy path — the update fn return value is written, committed is true, and snapshot.val() reflects the committed value
unit:modular/transaction.test.ts ("resolves to { committed: boolean, snapshot } with the committed value"); matches oracle observations packages/conformance/observations/rtdb-modular/rtdb-modular-runtransaction-success.json + rtdb-modular-runtransaction-returns-committed-snapshot.json (against digame-mas, fb-js-sdk 12.19.0) (Structured evidence: rtdb-modular-runtransaction-warm-client-speculation)Returning undefined from the update fn ABORTS the transaction — resolves { committed: false, snapshot }; no write performed, no listener fan-out
unit:modular/transaction.test.ts ("returning undefined aborts — committed: false, no write" + "aborted transaction does NOT fan out to listeners"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-runtransaction-abort-undefined.json — known divergence: prod's result.snapshot.val() reflects the CLIENT's pre-fetch (often null even when the server has a value because the speculative invocation runs before the server snap arrives); the sandbox returns the actual pre-transaction value at the path (more useful in single-client harness). The agreed-upon contract callers should rely on is committed === false and unchanged server-side data, NOT the snapshot's .val() on the abort path.Cold production clients may invoke the update fn first with speculative null and then with the current seeded value; the always-warm in-process sandbox invokes it once with the current value, so abort-if-missing aborts in production and commits in pyric (RT-16)
rtdb-modular-runtransaction-current-value-arg captures two seeded-path production invocations (null, then current); unit:modular/oracle-conformance-transactions.test.ts pins the sandbox's single current-value invocation. The separate warm-client observation matches the sandbox but does not erase the cold-client contract. oracle:rtdb-modular-transaction-then-set key abortIfMissing: production aborts, pyric commits (RT-16). (Structured evidence: transaction.test.ts, capture-transaction-then-set.test.ts)The update fn arg is a defensive deep clone — mutating it does NOT corrupt the stored tree (matters for code that does current.count++; return undefined and expects abort to preserve state)
unit:modular/transaction.test.ts ("mutating the update-fn arg does NOT corrupt the stored tree") — no separate oracle row (defensive contract; prod behavior is identical because the SDK clones on the wire boundary)options.applyLocally controls whether the in-flight optimistic value fans out to onValue listeners — default true (apply locally before commit); false suppresses intermediate fires so listeners see only the committed value
unit:modular/transaction.test.ts ("applyLocally: true (default) — listener sees initial + committed value" + "applyLocally: false — listener sees only the committed value"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-runtransaction-options-applylocally.json (single-client harness: both branches produce 2 fires (initial + commit) — divergence vs prod's documented multi-client suppression would surface under contention, which the sandbox doesn't model)Rules-denied transaction rejects with a plain Error whose message === 'permission_denied' (lowercase) and NO .code field — DIFFERENT from set/get's 'PERMISSION_DENIED: Permission denied' shape with uppercase .code.
unit:modular/transaction.test.ts ("rejects with a plain Error whose message is \"permission_denied\""); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-runtransaction-on-rules-denied-path.json (against digame-mas: message: 'permission_denied', code: null, constructorName: 'Error'). The served page receives the same codeless Error through the worker protocol (packages/cli/test/serve/worker/rtdb-denial-context.test.ts). (Structured evidence: rtdb-denial-context.test.ts)Rules-denied transaction does NOT write — pre-transaction value at the path is preserved through the rejection
unit:modular/transaction.test.ts ("does not write to the path when rules deny") — locked alongside the M37e shape claim. On a served page the update function runs on a location whose read the rules deny, as in the sandbox, and the denied commit writes nothing (packages/cli/test/serve/worker/rtdb-denial-context.test.ts).Committed transaction fans out to onValue listeners on the watched path with the new value (default applyLocally behavior)
unit:modular/transaction.test.ts ("committed write fans out to onValue listeners")Divergence: two ordinary concurrent runTransaction calls are serialized by the in-process backend, so their update functions are not retried with Firebase's captured contention counts. A synchronous re-entrant conflicting write does trigger a deterministic retry.
rtdb-modular-concurrent-transforms captures invocation counts [2, 3]; unit:modular/transaction-contention-cdd.test.ts pins the sandbox's [1, 1] ordinary-concurrency boundary and separately covers its deterministic re-entrant retry seam.Identity-aware sandbox-live op routing — sign-in/sign-out via pyric/auth is observed by the next RTDB op without re-binding
unit:modular/sandbox-target.test.ts ("reads sandbox.currentUser at op time, not at getDatabase time"). An app's listeners follow its identity too: after a sign-in or sign-out they still may read, they deliver nothing, since the data is unchanged; when they may not, they are cancelled (live-auth-listeners.test.ts). A served page's listeners do the same when the host re-registers them for a sign-in or sign-out on its port (packages/cli/test/serve/worker/rtdb-auth-change-listeners.test.ts).Backend identity is per-Sandbox and per database instance name: two getDatabase(sandbox) calls on the same sandbox share data, two on different sandboxes don't, every database URL form the SDK maps to one instance name (<name>.firebaseio.com, <name>.<region>.firebasedatabase.app, ?ns=<name>) shares one tree, and a URL getDatabase(app, url) rejects throws the SDK's Error and message. For an app whose options name the project, <projectId>-default-rtdb and <projectId>, the default instance of a project created before about 2020 (https://<projectId>.firebaseio.com), both name the default instance, on any host and in ?ns=; one shared check, isDefaultDatabaseInstance, decides it for every plane
rtdb-modular-database-url-instance records the instance name and root URL the production SDK derives for each URL form, the error it throws for malformed URLs, and the <projectId>-default-rtdb default; instances.test.ts replays every recorded URL through the shared instance identity. unit:modular/database-instances-cdd.test.ts proves same-sandbox sharing and independent-sandbox isolation, and multi-instance.test.ts proves per-instance trees, rules, persistence and URL-form routing. default-instance-names.test.ts pins the shared default-instance check for both names and every URL form, and legacy-default-url.test.ts asserts an app on https://<projectId>.firebaseio.com gets the default instance's rules and data in the in-page sandbox (#1062).Sandbox refs carry a stable key (last path segment) and toString() returning sandbox://rtdb/<path>
unit:modular/oracle-conformance-reference-writes.test.ts pins the stable key and local sandbox://rtdb/<path> string boundary alongside the production URL observation.query(ref, orderByChild(p), startAt(v), endAt(w)) window is BOTH-INCLUSIVE — children whose ordered field === v or === w are included
unit:upstream-rtdb-probes.test.ts (deep orderByChild nested path) + unit:modular/queries.test.ts ("returns children whose ordered child is within [startAt, endAt] inclusive"); matches oracle rtdb-modular-orderbychild-window.jsonorderByKey() orders children by RTDB nameCompare — integer-looking keys sort numerically FIRST (so ['1','2','10'], not the lexicographic ['1','10','2']), then non-integer keys lexicographically; startAt/endAt cursors + the optional key tie-breaker use the same order (DB-B4)
unit:upstream-rtdb-probes.test.ts (INT32 overflow/underflow cursors) + unit:modular/queries.test.ts + unit:modular/name-compare.test.ts; matches oracle rtdb-modular-orderbykey-window.json and upstream core/util/util.ts:253-276Under rules without .indexOn: '.value', get() of orderByValue() + limitToFirst(N) rejects with a plain Error (no code) reading Index not defined, add ".indexOn": ".value", for path "<path>", to the rules; an onValue listener on the same query delivers the N smallest primitive values and logs the @firebase/database warning Using an unspecified index. Your data will be downloaded and filtered on the client. With the index declared, both return the window and nothing is logged
rtdb-modular-query-index-enforcement deploys indexed and unindexed locations and records get(), onValue() and REST outcomes plus client log lines for each query shape; unit:cdd/query-index-contracts.ts replays every SDK case against the sandbox under the same rules and matches the observation exactly. Oracle rtdb-modular-orderbyvalue-numeric records the same rejection message, replayed in unit:modular/oracle-conformance-queries.test.ts. (Structured evidence: queries-and-listeners.test.ts, query-and-indexon-soundness.test.ts, rtdb-listeners.test.ts)orderByChild(p) + equalTo(v) returns ALL children whose field at p === v — no uniqueness enforced
unit:modular/queries.test.ts ("returns ALL children whose ordered field === the supplied value"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-equalTo-filter.json (both 'b'-grouped children returned).equalTo with no matches returns an empty snapshot (exists() === false, size === 0)
unit:modular/queries.test.ts ("returns an empty snapshot when nothing matches")limitToFirst(N) keeps the lowest-ranked N children (post-ordering, pre-filter)
unit:modular/queries.test.ts ("limitToFirst takes the lowest-ranked window"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-limittofirst-vs-limittolast.json (firstPositions [1,2]).limitToLast(N) keeps the highest-ranked N children
unit:modular/queries.test.ts ("limitToLast takes the highest-ranked window"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-limittofirst-vs-limittolast.json (lastPositions [4,5]).limitToFirst(N) larger than the result returns the full window (no padding, no throw)
unit:modular/queries.test.ts ("limitToFirst(N) larger than the result returns the full window")startAfter(v) and endBefore(v) are EXCLUSIVE — the boundary value is dropped from the result
unit:modular/queries.test.ts ("startAfter + endBefore drop the boundary values"); matches oracle observation packages/conformance/observations/rtdb-modular/rtdb-modular-startafter-endbefore-exclusive.json (positions [3,4], cursors 2 + 5 dropped).onValue(query, cb) only fires when the windowed result changes — writes OUTSIDE the window don't re-fire the listener; writes that displace a member DO
unit:upstream-rtdb-probes.test.ts ("one update nulls, mutates, and displaces within a limitToFirst window") + unit:modular/queries.test.ts ("fires only when the windowed result changes"); matches oracle rtdb-modular-onvalue-with-query.jsononValue(query) initial fire delivers an empty window (size === 0) when the path is absent
unit:modular/queries.test.ts ("initial fire on an empty path delivers an empty window")query(query(ref, c1), c2) composes constraints — chaining folds both into one spec
unit:modular/queries.test.ts ("query(query(ref, c1), c2) composes constraints")Snapshot from a query exposes children via snap.forEach in the executor-computed order — NOT necessarily the order Object.entries(val) would yield
unit:modular/queries.test.ts ("forEach visits children in ascending order of the child key")startAt(value, key) uses key as the tie-breaker when multiple children share the same ordered value — children before key are dropped, the row at key is included (inclusive cursor)
unit:modular/queries.test.ts ("startAt with key tie-breaker drops earlier same-value children")orderByChild('p') on children missing the field treats their value as null (sorts FIRST per RTDB's type ordering)
unit:modular/queries.test.ts ("orderByChild on a missing child path treats those children as null")query on a path holding a primitive (or absent path) returns an empty snapshot — no rows to iterate
unit:modular/queries.test.ts ("query on a path with primitive value returns no rows")Write-boundary normalization (nodeFromJSON-equivalent): a value written as an array is stored as an integer-keyed object — child(ref, '1') returns the element, forEach iterates 0,1,2… (DB-B2)
unit:modular/normalization.test.ts ("array write is addressable by integer-string child key" + "forEach over an array iterates its elements"); upstream core/snap/nodeFromJSON.ts:118-128, core/snap/ChildrenNode.ts:194-230Read-side array coercion: a dense integer-keyed object renders back as an array on snap.val() (allIntegerKeys && maxKey < 2 * numKeys), with a hole at each missing index; exportVal() and toJSON() keep it an object (DB-B2, RT-6)
unit:modular/normalization.test.ts ("a dense integer-keyed object reads back as an array") and unit:modular/snapshot-serialization.test.ts (holes, export shape, #1371); packages/cli/test/serve/worker/client/rtdb-sparse-array-holes.test.ts reads the holes back on the SharedWorker plane and on the Node host under Node, whose JSON transport writes them as null; upstream core/snap/ChildrenNode.ts:196-230null children and empty objects are pruned at the write boundary — set(ref, {}) is equivalent to remove(ref); nested null collapses empty ancestors ("empty nodes don't exist") (DB-B3)
unit:modular/normalization.test.ts ("set(ref, {}) is equivalent to remove" + "null children are pruned"); upstream core/snap/nodeFromJSON.ts:78-88,122-126Write validation: an undefined payload, a non-finite number (NaN/±Infinity), or a key containing a forbidden char (., #, $, /, [, ], control chars) is rejected with a plain Error (DB-B1)
unit:modular/normalization.test.ts ("rejects an undefined payload" + "rejects an invalid key" + "rejects a non-finite number"); upstream core/util/validation.ts:45,58,112-199Conflicting query constraints throw synchronously at query(...) construction (NOT silent last-win): multiple orderBy*, a second limitToFirst/limitToLast, a second start (startAt/startAfter/equalTo) or end (endAt/endBefore/equalTo) (DB-B5)
unit:modular/constraint-conflicts.test.ts (5 cases); upstream api/Reference_impl.ts:160-165,1824-1841,1888-1905,1945-1951,2193-2206push(ref, value?) returns a ThenableReference (a DatabaseReference with .then/.catch). The key + ref are minted CLIENT-SIDE and available synchronously even when the optional value write is rules-denied; the write is deferred onto the promise, so a denial REJECTS the awaited push rather than throwing synchronously and discarding the key (DB-B7)
unit:modular/push-thenable.test.ts (4 cases); matches oracle packages/conformance/observations/rtdb/rtdb-push-autoid-format.json ("available immediately even when the subsequent server write is denied by rules") + upstream api/Reference_impl.ts:599-630DataSnapshot shape: size (getter), priority (null when absent), exportVal(), key, ref, val(), exists(), child(), hasChild(), hasChildren(), forEach(), toJSON(). It does NOT ship the legacy namespaced numChildren() method (DB-B10)
unit:modular/snapshot-shape.test.ts ("exposes size/priority/exportVal; NOT numChildren()"); matches oracle packages/conformance/observations/rtdb-modular/rtdb-modular-get-snapshot-shape.json (hasSize: true, hasNumChildren: false) + upstream api/Reference_impl.ts:288-447. Flipped masking tests: modular/queries.test.ts + modular/sandbox-target.test.ts asserted snap.numChildren() — updated to snap.size.Object-valued children are ORDER-EQUAL — the sort/range tie is broken by key (nameCompare), NOT by an invented JSON.stringify ordering; a query re-write that only reorders object keys is "no change" and doesn't re-fire (DB-B11)
unit:modular/object-order-equality.test.ts; upstream core/snap/ChildrenNode.ts:386-400A primitive at the ROOT is legal (set(ref(db), 'hello')); a subsequent child write replaces the primitive root ("writes win") (DB-B13)
unit:modular/root-primitive.test.ts (2 cases)onValue(ref, cb, { onlyOnce: true }) fires once then auto-unsubscribes (DB-B12)
unit:modular/onvalue-onlyonce.test.ts; upstream api/Reference_impl.ts:975-980Child-listener callbacks receive Firebase's previousChildName second argument, including initial replay and ordered-query movement.
rtdb-modular-child-previous-name captures initial replay plus add/change/remove/move predecessor values; replayed by unit:modular/listener-lifecycle-cdd.test.ts.Value and child listener overloads accept a cancellation callback and deliver Firebase-shaped permission errors when a listen is denied or revoked; a callbackless listener that loses auth access is terminal and does not resurrect after sign-in.
rtdb-modular-listener-cancellation captures all five registrars returning normally, asynchronous initial-denial cancellation, one revocation callback each, and the Error/PERMISSION_DENIED/message shape; replayed in unit:modular/listener-lifecycle-cdd.test.ts. (Structured evidence: denial-context.test.ts)All child-listener functions accept Query inputs; add/change/remove events respect the active query window.
unit:modular/listener-lifecycle-cdd.test.ts and unit:modular/sandbox-child-events.test.ts cover initial windows plus entering, leaving, and changing members.onChildMoved fires when an ordered child changes position and co-fires with child_changed when Firebase does, preserving the captured previousChildName sequence.
rtdb-modular-child-previous-name and the modular oracle suite replay ordered movement, co-fire behavior, and predecessor sequencing. As rtdb-modular-childchanged-cofire-with-childmoved records for a same-rank change of the ordered field, a child moves whenever its indexed value changes; unit:modular/priority-listeners.test.ts pins this for object values under orderByValue() and orderByChild(), which sort equal while differing. (Structured evidence: rtdb-modular-onchildmoved-previouschildname-sequencing, listener-lifecycle-cdd.test.ts, oracle-conformance-listeners.test.ts)Child listener overloads accept ListenOptions directly or after a cancellation callback; onlyOnce stops delivery after Firebase's captured initial/event batch.
rtdb-modular-child-listener-only-once captures all four listener families, both overload shapes, the existing-child replay batch, and one-shot post-registration delivery; replayed by unit:modular/listener-lifecycle-cdd.test.ts..validate rules are enforced on modular sandbox writes through set, atomic update, and runTransaction; a descendant validation failure rejects the operation without changing state.
unit:modular/sandbox-target.test.ts executes all three write paths against a required-child .validate rule and proves each rejects without committing state. The shared SimulateHandler behavior is production-locked by RTDB rules corpus rows #4 and #15.onDisconnect(ref) returns the Firebase-shaped five-method handle; registration methods and cancel() return acknowledged Promises
An acknowledged onDisconnect(ref).set(value) registration does not mutate server data before the client disconnects
rtdb-modular-ondisconnect-registration; sandbox registration/no-mutation test. (Structured evidence: on-disconnect.test.ts)goOffline(db) drains that client's queue once, listeners observe the disconnect write in server order, and goOnline(db) does not resurrect executed operations
rtdb-modular-ondisconnect-clean-set; sandbox clean lifecycle test. (Structured evidence: on-disconnect.test.ts)Disconnect queues support set, update, remove, exact cancellation, parent cancellation of queued descendants, and captured parent-set/child-set/child-cancel coalescing that preserves the existing canceled child
rtdb-modular-ondisconnect-operations-cancel; sandbox operation/cancellation test, including the captured parent-set + child-cancel merge result. A queued server value is a leaf, as the SDK's onDisconnect tree holds it: cancelling a path below it leaves it whole, in the sandbox (on-disconnect.test.ts) and on the served host (host/rtdb-instances.test.ts).Rules are evaluated when a disconnect operation is registered and re-evaluated when it executes; an execution-time denial leaves server state unchanged
rtdb-modular-ondisconnect-rules with successful normal-write controls in both rule phases; sandbox rules-timing test. (Structured evidence: on-disconnect.test.ts)Local lifecycle contract: disconnect queues are owned per Database client, drain on app deletion, clear without executing on sandbox reset, and are excluded from persisted RTDB snapshots
rtdb-modular#M82 assertion set in unit:database/on-disconnect.test.ts covers independent clients, app deletion, reset clearing, and snapshot exclusion; these sandbox-owned boundaries have no production oracle equivalent.OnDisconnect.setWithPriority(value, priority) writes both the value and RTDB priority metadata when the disconnect queue drains.
rtdb-modular-ondisconnect-operations-cancel captures export-format priority 7; sandbox unit:database/on-disconnect.test.ts replays the value and priority.Divergence (pending fix): clean goOffline, app deletion, playground pagehide, and best-effort MessagePort close drain queued operations, but unannounced total renderer/process loss is not guaranteed by the in-memory sandbox
rtdb-modular-ondisconnect-abrupt-exit proves Firebase executes an acknowledged registration after forced writer termination. The two-port worker integration exercises goOffline, served-app deletion, and non-persisted pagehide; browser MessagePort close delivery cannot prove total-process loss without durable host-owned leases. (Structured evidence: rtdb-integration.test.ts)Database is exported as a runtime constructor value and handles returned by getDatabase() satisfy Firebase's observable prototype and instanceof contract.
rtdb-modular-runtime-class-identity; sandbox row assertion rtdb-modular#M85 replays runtime identity. (Structured evidence: oracle-conformance-runtime-identity.test.ts)DataSnapshot is exported as a runtime constructor value and snapshots returned by reads/listeners satisfy Firebase's observable prototype and instanceof contract.
rtdb-modular-runtime-class-identity; sandbox row assertion rtdb-modular#M86 replays runtime identity. (Structured evidence: oracle-conformance-runtime-identity.test.ts)QueryConstraint is exported as a runtime constructor value and constraints returned by orderBy*, bound, and limit factories satisfy Firebase's observable prototype and instanceof contract.
rtdb-modular-runtime-class-identity; concrete constraint subclasses satisfy instanceof QueryConstraint without using the base prototype directly, replayed by row assertion rtdb-modular#M87. (Structured evidence: oracle-conformance-runtime-identity.test.ts)TransactionResult is exported as a runtime constructor value and transaction results satisfy Firebase's observable prototype, instanceof, and toJSON() contract.
rtdb-modular-runtime-class-identity; sandbox row assertion rtdb-modular#M88 replays runtime identity and toJSON(). (Structured evidence: oracle-conformance-runtime-identity.test.ts)setPriority and setWithPriority store, replace, preserve, and clear valid RTDB priority metadata; parent exportVal() and toJSON() recursively include descendant priority metadata.
rtdb-modular-priority-contract captures round-trip/export shape, update/transaction preservation, plain-set clearing, and explicit clearing; replayed by unit:modular/priority-metadata-cdd.test.ts.orderByPriority orders by Firebase priority with key tie-breaking and composes with bounds, equality, and limits; plain snapshots and unconstrained queries use the same default priority index, and invalid priority bounds throw synchronously.
rtdb-modular-priority-contract captures priority order, key tie-breaking, bounds, and limits; replayed by unit:modular/priority-metadata-cdd.test.ts.Priority changes participate in plain and explicitly ordered child movement/listener sequencing, transactions, and updates without losing metadata.
rtdb-modular-priority-contract captures priority movement, update/transaction preservation, and descendant delivery when ancestor replacement clears metadata; replayed by unit:modular/priority-metadata-cdd.test.ts and unit:modular/priority-listeners.test.ts. Disconnect priority execution is owned separately by M83.off(query) removes listeners only from the equivalent constrained query view, while off(ref) removes listeners from every query view at that path.
rtdb-modular-off-duplicate-registration captures exact constrained-query removal and all-view reference removal with independent live-listener controls; replayed by unit:modular/sandbox-child-events.test.ts.Divergence: DatabaseReference and Query equality includes database target, path, and canonical query parameters like Firebase, but toJSON() serializes the local sandbox://rtdb/... identity instead of Firebase's HTTPS database URL.
rtdb-modular-reference-shape-url captures conforming equality plus HTTPS JSON serialization; unit:modular/oracle-conformance-reference-writes.test.ts pins both the production HTTPS shape and the sandbox's sandbox:// boundary.Query constraint construction preserves Firebase's synchronous validation for limits, child paths, cursor keys, undefined/non-finite/object endpoint values, and index-specific endpoint compatibility, including the captured +Infinity and server-value priority acceptances
rtdb-modular-query-construction-validation repeats the complete validation matrix twice per run and matched across two clean production runs; unit:modular/query-validation.test.ts replays every captured field exactly./.info is read-only: set, setWithPriority, setPriority, remove, push, runTransaction and every onDisconnect write on a location under /.info throw synchronously with <method> failed = Can't modify data under /.info/, an update from the root with a .info/ key throws the invalid-key error, an update on a .info reference rejects with INVALID_PARAMETERS, and no such write changes data
rtdb-modular-info-write-validation (captured 2026-10-07) runs each write twice against production and records the timing, code and message of each failure; unit:modular/info-write-validation.test.ts replays every captured field and checks the sandbox state is unchanged. The served worker client applies the same check before it sends a write. (Structured evidence: public-operations.test.ts)getDatabase(target) — initializer
getDatabase(ctx) returns a tagged sandbox-target handle (frozen identity)
unit:modular/database-instances-cdd.test.ts asserts the returned Database carries a sandbox target.getDatabase(sandbox) returns a tagged sandbox-live handle (per-op identity)
unit:modular/database-instances-cdd.test.ts asserts the returned Database carries a sandbox-live target.Inactive canonical firebase/database imports remain the upstream package; the mirror does not create tagged production targets
unit:modular/database-instances-cdd.test.ts proves a real Firebase Database remains untagged and is rejected by the mirror.getDatabase() (no argument) — wrapped in the playground preview to supply the sandbox; a raw mirror call rejects with package-resolution guidance
packages/playground/src/components/AppPreview.tsx (slot install with bare-call wrap), packages/playground/src/lib/preview/virtual-imports-plugin.ts (alias map), and packages/playground/src/lib/preview/preview-scope.ts (type-level slot). Mirrors the getAuth / getFirestore wrap pattern. Demo fixture: packages/playground/scripts/fixtures/rtdb-set-get-roundtrip.tsx (bare getDatabase() + set/get/remove round-trip with anonymous sign-in) passes end-to-end through the bun run debug:fixtures Playwright suite. (Structured evidence: lifecycle-and-identity.test.ts)Two getDatabase(sandbox) calls share state (same underlying LocalEnvironment)
unit:modular/database-instances-cdd.test.ts writes through one handle and reads through another handle owned by the same sandbox.Handle dispatch by TARGET_SYMBOL brand — refs route to their owning target via a refToTarget WeakMap (mirror of firestore's pattern)
unit:modular/database-instances-cdd.test.ts proves references from independent sandbox targets route to independent backends.Multiple database instances
In production each database URL is its own instance, with its own data and its own rules. The in-page sandbox keeps one backend per canonical URL, so getDatabase(app, url) isolates data there, and the dev server loads each instance its own rules from firebase.json. The served worker host, in the SharedWorker and in the Node host, holds one store and one ruleset per instance.
getDatabase(app, url) (served mode)The served worker host, in the SharedWorker and in the Node host, holds one store and one ruleset per instance, and the instance name travels on every RTDB operation and listener from the page. A write to one instance is not visible on another, listeners on one instance do not fire for another's writes, each instance enforces its own rules, and one port session's Auth identity reaches every instance, including after sign-out and a forced token refresh. The default instance's URL and getDatabase(app) name one store, and so does https://<projectId>.firebaseio.com, the default instance of a project created before about 2020, which the page sends as the default instance while its references keep that URL. Rules firebase.json deploys to <projectId> or <projectId>-default-rtdb before the host knows the project move to the default instance when the first app names it; different rules for both names are refused as two rules files for one instance, with an error naming both files, and the default instance stays locked. As the SDK does, served mode returns one handle per app and URL argument, throws Database initialized multiple times for a second URL form naming an open instance, throws Can't determine Firebase Database URL with neither a URL nor a project id, reports each reference's production URL, and checks refFromURL's host. An instance firebase.json deploys no rules to is created on first use with locked rules, .read and .write false at the root as production creates a new instance; under --permissive it allows every read and write, as the default instance without rules does. Its first use logs which access applies and which database entry would deploy its rules.
rtdb-modular-multiple-instances deploys a different ruleset to genkit-idx-default-rtdb and genkit-idx-second-rtdb and records a signed-out write denied on one instance and allowed on the other, each write visible only on its own instance, and one custom-token user allowed on both under each instance's rules. Its sdk section, recorded offline from the production SDK, holds each reference URL form, the refFromURL host error, the Database initialized multiple times error, and the Can't determine Firebase Database URL error. rtdb-instances.cases.ts (run by rtdb-instances.test.ts) replays both sections through the served firebase/database entry over the shared host dispatch, and pins listener isolation, the default-URL store and the locked instance and its notice. host/rtdb-instances.test.ts pins per-instance rules ops, onDisconnect per instance, reset restoring each instance's rules, and firebase.json rules for <projectId>-default-rtdb reaching getDatabase(app) when the project id arrives with the first app. per-port-sessions.test.ts re-checks a listener on a non-default instance at sign-out and at a forced token refresh. hosted-sqlite.test.ts runs the Node host: per-instance data and rules, the data across a restart, one Auth session on both instances, and a firebase.json array loading each instance its own rules. worker-relay.test.ts pins rtdb.forInstance. oracle-conformance-runtime-identity.test.ts replays the observation's rules and handle identity on the in-page sandbox. host/rtdb-instances.test.ts, database-rules-deployment.test.ts and hosted-sqlite.test.ts pin an instance without deployed rules locked by default and open under permissive mode, with the notice each logs. host/rtdb-legacy-default-instance.test.ts pins <projectId> resolving to the default instance with the project known at startup or from the first app, late adoption of rules for either name, the refusal of different rules for both, and the hosted tools' selection; rtdb-legacy-default-served-entry.cases.ts (run by rtdb-legacy-default-served-entry.test.ts) pins the served entry sending no instance for that URL. App scenario test/apps/rtdb-legacy-default-url drives an app on https://<projectId>.firebaseio.com with a plain database.rules in the SharedWorker, in-page, on the Node host, and from a node --import @pyric/cli/register process (#1062). Under PYRIC_SANDBOX=local the register's in-process sandbox loads each instance's rules from firebase.json, a .firebaserc deploy target included: packages/pyric/test/app/register-rules.test.ts pins the loader, and the register-child.test.ts local rules case runs a real child that writes to the default instance and a target instance under each one's rules (#1120). (Structured evidence: lifecycle-and-identity.test.ts)--permissive, an instance without deployed rules allows every read and write, where production creates an instance locked; Studio's data browser reaches only the default instancegetDatabase(app, url) (served in-page fallback)The served in-page fallback keeps each URL's data separate and applies each instance the rules firebase.json deploys to it. A database opened without a URL is the project's default instance, and rules firebase.json deploys to <projectId>-default-rtdb or <projectId> reach it once the app names its project; a databaseURL of https://<projectId>.firebaseio.com opens it too, and different rules for both names lock it with an error naming both files. An instance firebase.json deploys no rules to is locked, .read and .write false at the root as production creates a new instance, or open under permissive mode as the default instance is, and its first use logs which access applies and which database entry would deploy its rules; a declared instance whose rules file is missing follows the default policy. As the SDK does, a second URL form naming an open instance throws Database initialized multiple times, and neither a URL nor a project id throws Can't determine Firebase Database URL. A ruleset the load-time check refuses is not installed for its instance, and the other instances keep theirs. Production deploys rules per instance.
packages/cli/test/serve/database-rules-deployment.test.ts deploys two rulesets to two instances and asserts each instance allows and denies its own paths, that replacing one instance's rules leaves the other's in force, that a database opened without a URL gets the default instance's rules, and that a refused ruleset names its instance while the other instance loads. Oracle rtdb-modular-multiple-instances records production enforcing a different ruleset on each of two instances of one project. CDD assertion rtdb-modular#MI2 pins the sandbox side: setRules on one URL's database leaves the other URL's rules unchanged. packages/cli/test/serve/database-rules-legacy-default-instance.test.ts asserts an app on https://<projectId>.firebaseio.com gets the default rules from each firebase.json shape with no locked <projectId> instance, and the refusal of different rules for both names. (Structured evidence: lifecycle-and-identity.test.ts)firebase.json database arrayThe dev server reads firebase.json database as firebase deploy reads it. A single object's rules deploys to <projectId>-default-rtdb. Each array entry's rules deploys to every instance .firebaserc maps its target to, else to its instance, and target wins when an entry names both. An entry with neither fails with Must supply either "target" or "instance" in database config, an entry without rules deploys nothing, and a .bolt or other non-.json rules file fails with the CLI's message. Each instance's rules pass the load-time check on their own, and a refusal names the instance and file. Editing one instance's rules file reloads only that instance. Two entries that deploy different files to one instance are refused, because the CLI deploys both at once and the configuration does not determine which ruleset production keeps. An entry for <projectId>, the default instance of a project created before about 2020, deploys to the default instance, so entries for <projectId> and <projectId>-default-rtdb are one instance. The project that names the default instance and selects .firebaserc targets resolves as the Firebase CLI resolves a command's project: an explicit project (--project, or the Vite plugin project option), then the firebase use active project of the project directory or its nearest ancestor, then the only .firebaserc alias, else projects.default; a value that names a .firebaserc alias resolves to its project id. Pyric adds PYRIC_PROJECT and the pyric.json project after the explicit project and reads no other environment variable, as the CLI reads none. Where firebase deploy fails because no project is set or the project does not map a target (Deploy target <name> not configured for project <id>), the dev server starts, logs the target, the sources tried and the ways to set the project, serves the target's instances with the default policy, and applies the target's rules once the page's app config names a project .firebaserc maps the target for.
database arraylib/database/rulesConfig.js getRulesConfig (single object to <project>-default-rtdb, target resolved through rc.requireTarget and rc.target before instance, the missing-key error), lib/rc.js requireTarget (the unmapped-target error) and resolveAlias, lib/command.js applyRC and configstoreProject (the project order: --project, the configstore activeProjects entry of the project root or its nearest ancestor, the legacy firebase key of firebase.json, a .firebaserc alias resolved to its id, the sole alias, then default), lib/configstore.js with the configstore package ($XDG_CONFIG_HOME/configstore/firebase-tools.json, else ~/.config/configstore/firebase-tools.json), lib/commands/use.js with lib/utils.js makeActiveProject (firebase use stores the alias or id keyed by project root), and lib/projectUtils.js getProjectId and needProjectId (no environment variable chooses a command's project; FIREBASE_PROJECT is read only by lib/init/features/project.js). packages/cli/test/cli/firebase-project.test.ts asserts each source in that order, alias resolution, the ancestor walk, XDG_CONFIG_HOME, and that FIREBASE_PROJECT, GCLOUD_PROJECT and GOOGLE_CLOUD_PROJECT are not read, against a temporary HOME. packages/cli/test/serve/vite-sandbox-generation.test.ts and packages/cli/test/serve/vite-plugin-project.test.ts assert the Vite plugin maps targets through PYRIC_PROJECT with functions: false and through the project option, and starts with an unresolved target carried in /__pyric/init.json. packages/cli/test/serve/worker/host/rtdb-instances.test.ts and packages/cli/test/serve/database-rules-deployment.test.ts assert the SharedWorker and Node host, and the in-page fallback, apply an unresolved target's rules when the app config names its project, and apply a later rules change to its instances. and lib/deploy/database/prepare.js (entries without rules skipped, the .bolt and unexpected-format errors). packages/cli/test/serve/database-rules-config.test.ts asserts each shape and each error, and packages/pyric/test/sandbox/internal/database-rules-config-legacy-default.test.ts an entry or a target for <projectId> deploying to the default instance and the refusal of two files for its two names. packages/cli/test/serve/sandbox-session.test.ts loads two instances, reloads only the edited instance's file and broadcasts rtdb-rules-update with its instance, and refuses to start on one instance's refused rules naming that instance and file. packages/cli/test/serve/vite-generation-rules-watch.test.ts asserts an edit to one instance's file reloads only that file. CDD assertion rtdb-modular#MI3 pins the instance the sandbox derives from a firebase.json instance name: the same name and root URL the production SDK derives from that instance's URL, as oracle rtdb-modular-database-url-instance records. (Structured evidence: lifecycle-and-identity.test.ts)pyric-admin getDatabase(app, url) / getDatabaseWithUrl(url, app)As the Admin SDK binds each database URL to its own instance, pyric-admin getDatabaseWithUrl(url, app) and getDatabase(app, url) read and write the instance the URL names, and getDatabase(app) the instance the app's databaseURL option names, else the default instance. <projectId>-default-rtdb and <projectId> (https://<projectId>.firebaseio.com) are the default instance when the app's options name the project. A bare initializeApp() reads its options from FIREBASE_CONFIG. Each instance has its own data, and one Database is returned per app sandbox and instance. Against a served host, every relayed operation and value listener names its instance, so an admin write through one instance's URL reaches clients of that instance under its rules and is absent from the default instance; a Functions trigger on a named instance fires on that instance's writes. In process, sandbox.reset() clears every instance. A URL the SDK rejects throws the SDK's error, an empty URL throws Database URL must be a valid, non-empty URL string., and refFromURL rejects a firebaseio.com URL for another instance's host.
packages/pyric-admin/test/database/get-database-with-url.test.ts writes through one instance's URL and asserts the value is absent from the default URL and getDatabase(app), that the project default URL and getDatabase(app) return one handle, that the app's databaseURL selects the instance, that sandbox.reset() clears every instance, and the URL and refFromURL errors. packages/pyric-admin/test/remote/remote-dispatch.test.ts asserts set, get, update, push, remove, once('value') and on('value') on the remote arm reach only the named instance of the worker host, and that a bare initializeApp() reads databaseURL from FIREBASE_CONFIG. packages/cli/test/serve/hosted-sqlite.test.ts runs the Node host: an admin write through getDatabaseWithUrl is readable by a signed-in client on that instance under member-only rules and denied through the default instance. packages/cli/test/functions-rtdb/child.integration.test.ts fires a trigger on a named instance and asserts the handler's write lands there. CDD assertion rtdb-modular#MI4 pins the sandbox side: getAdminDatabase(sandbox, url) keeps separate data per URL. packages/pyric-admin/test/database/legacy-default-url.test.ts asserts https://<projectId>.firebaseio.com is the default instance. (Structured evidence: lifecycle-and-identity.test.ts)database tool and pyric database <method> --instanceEvery method of the database service tool, and pyric database <method>, takes an optional instance: a bare instance name, any database URL, or default, parsed with the SDK's URL rules, so a malformed URL is refused with the message getDatabase throws. The project's <projectId>-default-rtdb, and <projectId> with its https://<projectId>.firebaseio.com URL, select the default instance, as getDatabase(app) and that URL reach one instance. A call reads and writes only the instance it names, under the held identity and that instance's own rules, on the in-process sandbox and on the Node host. An instance firebase.json does not declare and the sandbox holds no data for is refused with the instances the project has, rather than opened empty. A summary names the instance when it is not the default.
packages/cli/test/bridge/surface/methods/database/instance.test.ts runs all seven methods with each instance form against a project whose firebase.json declares two shards, and asserts the call reaches only the named tree, that default and <projectId>-default-rtdb reach the default instance, the refusal and its list, an undeclared instance the sandbox already holds, the SDK message for a malformed URL, a uid identity held to each instance's own rules, and that the MCP target router hands a hosted call the argument unchanged. packages/cli/test/cli/surface-method-runner.test.ts persists a named-instance write to the in-process state and reads it back. packages/cli/test/serve/hosted-sqlite.test.ts runs the Node host's hosted method route: a write a client port reads on that instance and not the default, the URL and default-name forms, an impersonated uid under the shard's rules, and the refusal. App scenario test/apps/rtdb-named-instance-tools drives the installed pyric database get and set --instance against a Vite hosted dev server while Chromium writes to both instances. CDD assertion rtdb-modular#MI5 pins the sandbox side: each name and URL form resolves to one instance, default to the default instance, and heldDatabaseInstances names the instances a sandbox holds. packages/cli/test/bridge/surface/database-instance-catalog-legacy-default.test.ts asserts <projectId> selects the default instance and is not listed as a named one. (Structured evidence: database-instance.test.ts, database-instance-catalog.test.ts, lifecycle-and-identity.test.ts)pyric verify --rules rtdb:<instance>=<path>The verify capture records every instance a session held: the default instance's rules, data and URL, and each named instance's active rules and data under its name, on the SharedWorker, the Node host and the in-page runtime. RTDB events name the instance they hit. pyric verify replays each instance the session used on its own: only that instance's events, into the tree the session left it with, under that instance's candidate rules, so a write to one instance is never checked against another's rules or tree. Candidate rules come from --rules rtdb=<path> for the default instance and --rules rtdb:<instance>=<path> for a named one (a name or a database URL), else from firebase.json as firebase deploy resolves it: an array entry's instance, a target that .firebaserc maps for the project, and database.rules.json when there is no database key. The project's default instance name selects the default instance, and so does <projectId> or its https://<projectId>.firebaseio.com URL. A divergence on a named instance names it. An instance the session used with no candidate rules is an error that names it, with the reason a deploy target did not resolve; rules for an instance the session never used are refused with the instances it did use.
packages/cli/test/verify/rtdb-instances.test.ts captures a session on the default instance and shard-00 and asserts each instance's rules, tree and the default URL in the capture, a now-denied on the shard alone under tightened shard rules, no drift under unchanged rules, drift in a tampered shard tree tagged with the shard, and skippedInstances for an instance without candidate rules. packages/cli/test/cli/verify-rtdb-instances.test.ts runs pyric verify over a firebase.json instance array, a deploy target resolved through .firebaserc and --project, an unresolved target, rtdb:<instance>= by name, URL and default name, an override for an unused instance, and database.rules.json with no database key. packages/cli/test/cli/verify-rtdb-legacy-default.test.ts maps rtdb:<projectId>= and its URL to the default instance and reads the default's candidate rules from a firebase.json entry for <projectId>. packages/cli/test/serve/worker/serve-init.test.ts asserts the host capture holds each named instance, and bundler.test.ts that the in-page runtime bundles the capture. App scenario test/apps/rtdb-named-instance-tools runs the installed pyric verify on the .pyric/last-session.json the Node host wrote while Chromium wrote to both instances: clean under firebase.json, now-denied on shard-00 only under stricter shard rules, and an error naming shard-00 when firebase.json deploys it no rules. CDD assertion rtdb-modular#MI6 pins the sandbox side: a replay selects one instance's events by name or URL and checks them under that instance's rules and tree. (Structured evidence: lifecycle-and-identity.test.ts)pyric assurance / pyric.assurance.target.v1Assurance campaigns (local-sandbox targets) declare named RTDB instances in rules.rtdbInstances and state.rtdbInstances, alongside the default instance. Operations name an instance (a name, URL, or default). The runner sets each instance's rules and data, executing operations on their target instance so mutations and access checks are isolated. An operation naming an instance the target does not declare is an invalid-input refusal listing the declared instances.
packages/cli/test/assurance/rtdb-instances.test.ts runs a campaign where a named-instance probe under its own relaxed rules succeeds while a default-instance probe under locked rules fails, and asserts that naming an undeclared instance throws an invalid-input refusal naming the missing instance. The pyric.assurance.campaign.v1 schema and the MCP worker protocol in packages/cli/src/bridge/surface/arguments/assurance.ts carry the instance and rtdbInstances fields. CDD assertion rtdb-modular#MI7 pins the sandbox isolation: rules and data set on a named instance are strictly isolated from the default instance, and operations are decided by their specific rules. (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)ref(db, path) / child / parent / root
ref(db, path) returns a tagged DatabaseReference carrying key, parent, root, and toString(), and synchronously rejects paths containing ., #, $, [, or ] with Firebase's captured error shape
rtdb-modular-reference-shape-url; sandbox row assertion rtdb-modular#100 replays navigation and every forbidden path character. (Structured evidence: oracle-conformance-reference-writes.test.ts)ref(db) with no path returns the root ref (key === null, parent === null)
rtdb-modular-reference-shape-url; sandbox row assertion rtdb-modular#101. (Structured evidence: oracle-conformance-reference-writes.test.ts)child(ref, 'a/b') joins a non-empty relative path, including embedded slashes, and synchronously rejects empty or forbidden-character paths with Firebase's captured error shape
rtdb-modular-reference-shape-url; sandbox row assertion rtdb-modular#102 replays embedded-path joining plus empty/invalid validation. (Structured evidence: oracle-conformance-reference-writes.test.ts)ref.parent is null at root, otherwise the parent ref
rtdb-modular-reference-shape-url; sandbox row assertion rtdb-modular#103. (Structured evidence: oracle-conformance-reference-writes.test.ts)ref.key is the final path segment, null for root
rtdb-modular-reference-shape-url; sandbox row assertion rtdb-modular#104. (Structured evidence: oracle-conformance-reference-writes.test.ts)Unknown ref (not produced by this package) → TypeError in shim ops
rtdb-modular-reference-shape-url captures a synchronous TypeError; sandbox row assertion rtdb-modular#105 matches its timing and constructor. (Structured evidence: oracle-conformance-reference-writes.test.ts)get(ref) — single read
Returns a DataSnapshot carrying .val(), .exists(), .key, .ref, .size (getter, returns child count), .hasChildren(), .hasChild(path), .forEach(cb). The legacy namespaced-SDK method .numChildren() is NOT on the modular DataSnapshot — use .size instead. Observed: hasNumChildren: false, size: 3 for a {a,b,c} object, forEachKeys: ['a','b','c'] against digame-mas, fb-js-sdk 12.19.0.
packages/conformance/observations/rtdb-modular/rtdb-modular-get-snapshot-shape.json (Structured evidence: snapshot-shape.test.ts)snap.val() returns null for a missing path (NOT a thrown error — RTDB diverges from Firestore here; getDoc returns exists()===false but get on RTDB just returns a null-val snapshot)
packages/conformance/observations/rtdb-modular/rtdb-modular-get-missing-path.json — observed threw: false, val: null, exists: false on a never-written path against digame-mas. The root of an empty database is the same case: the production SDK computes DataSnapshot.exists() as !node.isEmpty() at every path, the root included. The in-page sandbox, the served worker host and the Node host each read an empty root as val: null, exists: false, before any write and after the last child is removed. (Structured evidence: oracle-conformance-reference-writes.test.ts, rtdb-empty-root.test.ts, hosted-sqlite.test.ts)snap.exists() is false when val() === null, true otherwise
packages/conformance/observations/rtdb-modular/rtdb-modular-get-missing-path.json — observed exists: false for val: null. (Structured evidence: lifecycle-and-identity.test.ts)Round-trip: set(ref, payload) then get(ref) returns the payload (lock the basic write→read invariant)
packages/conformance/observations/rtdb/rtdb-set-then-get-roundtrip.json — the payload round-trips structurally on both sides (this row's claim holds). oracle-conformance.test.ts also asserts the key order: production returns object children in key order (the capture's roundTripEqual: false: a JSON.stringify round-trip against a non-sorted payload fails), and so does the sandbox since #1371 (RT-7).Rules-denied read throws a plain Error (NOT a FirebaseError) with code: 'PERMISSION_DENIED' (uppercase snake-case) — matches the agent-tool rows #15/#20
packages/conformance/observations/rtdb/rtdb-rules-denied-error-code.json (Structured evidence: lifecycle-and-identity.test.ts)set(ref, value) — full write
Replaces the value at the path entirely; resolves to undefined (unlike setDoc which resolves to void, RTDB's set is documented as Promise<void>)
rtdb-modular-write-return-validation captures null in JSON for the resolved undefined value; sandbox row assertion rtdb-modular#111 matches it. (Structured evidence: oracle-conformance-reference-writes.test.ts)set(ref, null) removes the path entirely — equivalent to remove(ref), subsequent get returns null-val snapshot
packages/conformance/observations/rtdb-modular/rtdb-modular-set-null-equals-remove.json — observed beforeExists: true → afterExists: false, afterVal: null after set(ref, null). (Structured evidence: public-operations.test.ts)Nested objects overwrite — set(ref, {a: 1}) after set(ref, {a: 1, b: 2}) leaves {a: 1} only, NOT a merge (RTDB set is replacement, not merge)
packages/conformance/observations/rtdb-modular/rtdb-modular-set-replaces-not-merges.json — observed final: {a: 1} with b absent after the second set. (Structured evidence: public-operations.test.ts)Primitive round-trip — numbers, strings, booleans, arrays all survive a set→get cycle
packages/conformance/observations/rtdb/rtdb-set-then-get-roundtrip.json — the payload round-trips structurally on both sides (this row's claim holds). oracle-conformance.test.ts also asserts the key order: production returns object children in key order (the capture's roundTripEqual: false: a JSON.stringify round-trip against a non-sorted payload fails), and so does the sandbox since #1371 (RT-7).Rules-denied write throws plain Error with code: 'PERMISSION_DENIED' (same shape as #110)
packages/conformance/observations/rtdb/rtdb-rules-denied-error-code.json (Structured evidence: public-operations.test.ts)On the SharedWorker and Node host planes, a write whose value, priority or update map the SDK refuses (NaN, Infinity, undefined, a function, an invalid key, an update map that is not an object) throws synchronously at the call with the SDK's text, sends nothing, and leaves stored data unchanged: set, update, push, setPriority, setWithPriority and onDisconnect().set, setWithPriority and update
validateFirebaseDataArg, validateFirebaseMergeDataArg and validatePriority in @firebase/database), recorded in the 2026-10-27 SDK hunt (RP-1, RP-6). packages/cli/src/serve/worker/client/rtdb-value-validation.ts runs those checks with their texts before a frame is sent; bridge/frame-output.ts refuses to encode an RTDB value JSON cannot carry, and the host refuses a non-object update map with the SDK's text. packages/cli/test/serve/worker/rtdb-invalid-writes.test.ts asserts each text and the unchanged data on the SharedWorker client. App scenario test/apps/node-rtdb-invalid-writes runs the client SDK under node --import @pyric/cli/register against the Node host and reads each path back with firebase-admin; on main (c706c6415) set(ref, NaN) resolved and deleted the value. CDD assertion rtdb-modular#SW1 pins the sandbox side: the in-page sandbox fails the same writes and keeps the data. (Structured evidence: scenario.ts, public-operations.test.ts)update(ref, values) — partial / multi-path update
update(ref, {a: 1, b: 2}) merges top-level keys at the ref; unspecified keys preserved (in contrast to set's replacement). A child value's .priority becomes that child's priority, for rules and in storage. update(ref, {}) and onDisconnect(ref).update({}) resolve without evaluating rules and write or queue nothing
packages/conformance/observations/rtdb-modular/rtdb-modular-update-merges-keys.json — after set({a:1,b:2}) then update({a:10}), observed final: {a:10, b:2}. The empty update follows the production SDK source (@firebase/database 1.1.3, repoUpdate and repoOnDisconnectUpdate): with no children to merge it logs "called with empty data" and completes with ok without sending anything, so no rule runs. unit:rules/rtdb/rtdb-rules-audit-regressions.test.ts resolves both under a denying .write with nothing written and an earlier queued disconnect write kept, and unit:cli/serve/worker/rtdb-empty-update.test.ts asserts the same through the SharedWorker host. The child priority follows the SDK's nodeFromJSON, which reads a child value's .priority; the same test file asserts it reaches newData.getPriority() and the stored node.Multi-path update — update(parentRef, { 'a/x': 1, 'b/y': 2 }) lands BOTH writes atomically at distinct subtrees (RTDB's most distinctive feature; this is the "fan-out" pattern)
packages/conformance/observations/rtdb-modular/rtdb-modular-update-multipath-atomic.json — observed aX: 1, bY: 2 both readable after a single update call. (Structured evidence: public-operations.test.ts)Multi-path update is atomic: if any path is denied by rules, the entire update rejects and no path is written
packages/conformance/observations/rtdb-modular/rtdb-modular-update-multipath-rules-denial.json — observed threw: true, code: 'PERMISSION_DENIED' AND okPathWrittenDespiteDenial: false (the otherwise-permitted path also rolled back). The sandbox's activity record matches: unit:sandbox/write-plane.test.ts checks that a denied update records only its denial, with no allow for the paths evaluated before it.Setting a key to null inside update removes that key — same equivalence as set(ref, null)
packages/conformance/observations/rtdb-modular/rtdb-modular-update-null-removes-key.json — after set({a:1,b:2}) then update({a:null}), observed final: {b:2} with a absent. (Structured evidence: public-operations.test.ts)Update path validation — overlapping paths (e.g. '/a' and '/a/x' in the same call) throws synchronously before any write
rtdb-modular-write-return-validation captures a synchronous ancestor-path error and unchanged terminal state; sandbox row assertion rtdb-modular#120 matches both. (Structured evidence: oracle-conformance-reference-writes.test.ts)remove(ref) — delete
Removes the value AND all children; subsequent get returns null-val snapshot
packages/conformance/observations/rtdb/rtdb-remove-vs-set-null.json (Structured evidence: public-operations.test.ts)Idempotent — remove on a path that's already absent resolves successfully (no-throw)
packages/conformance/observations/rtdb-modular/rtdb-modular-remove-idempotent.json — remove on a never-written path observed threw: false, afterExists: false. (Structured evidence: public-operations.test.ts)remove(ref) and set(ref, null) produce the same end state — locks the documented RTDB invariant
packages/conformance/observations/rtdb/rtdb-remove-vs-set-null.json (Structured evidence: public-operations.test.ts)push(ref, value?) — auto-id append
push(ref).key is a 20-char string starting with -, available synchronously (client-side mint, no server round-trip required)
packages/conformance/observations/rtdb/rtdb-push-autoid-format.json (Structured evidence: public-operations.test.ts)Sequential push calls produce monotonically-sortable keys (timestamp-prefixed for chronological ordering via orderByKey)
packages/conformance/observations/rtdb/rtdb-push-autoid-format.json (Structured evidence: public-operations.test.ts)push(ref, value) writes the value AND returns the new child ref (both behaviors in one call); push(ref) mints the ref without writing
packages/conformance/observations/rtdb-modular/rtdb-modular-push-with-value.json — await push(parent, {hello:'world'}) returned a ref with a 20-char key; subsequent get(r) returned {hello:'world'}. (Structured evidence: public-operations.test.ts)The returned ref r = push(parent, value) is usable in follow-up ops: get(r), set(r, …), remove(r)
packages/conformance/observations/rtdb-modular/rtdb-modular-push-with-value.json — observed all 4 follow-up ops succeed through the returned ref (refIsUsableForFollowupOps: true). (Structured evidence: public-operations.test.ts)onValue(ref, cb) — value-level listener
Subscribing to a path with existing data fires the listener once with the current snapshot (the "initial fire")
packages/conformance/observations/rtdb-modular/rtdb-modular-onvalue-initial-with-data.json — observed exactly 1 initial fire within ~46ms of subscribe, snapshot.val() === the seeded payload. (Structured evidence: public-operations.test.ts)Subscribing to a nonexistent path still fires the listener once — with a null-val snapshot AND exists() === false. Matches Firestore's onSnapshot-on-missing-doc semantics: prod RTDB does NOT silently skip the initial fire for empty paths.
packages/conformance/observations/rtdb-modular/rtdb-modular-onvalue-initial-no-data.json — observed 1 initial fire on a never-written path with firstFire.val: null, firstFire.exists: false (~55ms after subscribe). (Structured evidence: public-operations.test.ts)Subsequent set(ref, …) fires the listener with the new value
packages/conformance/observations/rtdb/rtdb-onvalue-fires-on-set.json — observed 1 fire per set() (1+1+1 = 3 total: initial-null, after-first-set, after-second-set). (Structured evidence: public-operations.test.ts)Unsubscribe — the returned unsubscribe function stops further fires; subsequent writes produce 0 additional fires after unsub()
packages/conformance/observations/rtdb-modular/rtdb-modular-onvalue-unsubscribe.json — observed preUnsubFires: 2, postUnsubFires: 2 (a write performed after unsub() produced 0 additional fires within a 500ms settle window). (Structured evidence: public-operations.test.ts)The returned value from onValue(ref, cb) is the unsubscribe function (NOT an object); calling it removes the listener
unit:modular/listener-lifecycle-cdd.test.ts asserts the return is a function and that invoking it stops subsequent delivery; production behavior is adjacent to oracle-backed row #131.onChildAdded / onChildChanged / onChildRemoved / onChildMoved
onChildAdded replays the existing children on subscribe — one fire per existing child key, in the default priority index with key tie-breaking (unlike onValue which fires once with the parent snapshot)
packages/conformance/observations/rtdb-modular/rtdb-modular-onchildadded-initial-replay.json — seeded {k1, k2, k3}, observed 3 initial fires with firedKeys: ['k1', 'k2', 'k3']; the default priority/key order is separately pinned by rtdb-modular-priority-contract. (Structured evidence: public-operations.test.ts)After subscribe, adding a child via push or set(child, …) fires onChildAdded exactly once for that key
packages/conformance/observations/rtdb-modular/rtdb-modular-onchildadded-post-subscribe.json — seeded {k1,k2}, observed postSubscribeFires: 1, lastFire: {key:'k3', val:{v:3}} after writing the new child. (Structured evidence: public-operations.test.ts)onChildChanged fires when an existing child's value changes; does NOT fire for added or removed children
packages/conformance/observations/rtdb-modular/rtdb-modular-onchildchanged-fires-on-update.json — observed firedOnInitial: 0, firedOnUpdate: 1, lastFire: {key:'k1', val:{v:2}} (the NEW value, not the prior). (Structured evidence: public-operations.test.ts)onChildRemoved fires when a child is deleted (via remove(child) or set(child, null)); snapshot carries the PRIOR value
packages/conformance/observations/rtdb-modular/rtdb-modular-onchildremoved-fires-on-delete.json — observed firedOnDelete: 1, removedSnapCarriesPriorValue: true (snapshot.val() was the pre-delete value). (Structured evidence: public-operations.test.ts)onChildMoved under an explicit ordered query fires when the ordered field changes, co-fires with child_changed, and supplies the captured previousChildName.
rtdb-modular-onchildmoved-with-orderby, rtdb-modular-onchildmoved-previouschildname-sequencing, and rtdb-modular-childchanged-cofire-with-childmoved are replayed by the modular oracle suite. (Structured evidence: oracle-conformance-listeners.test.ts)off(ref, eventType?, callback?) — unsubscribe variants
off(ref) removes ALL listeners at that ref (any event type, any callback)
packages/conformance/observations/rtdb-modular/rtdb-modular-off-stops-child-fires.json — after off(ref) with no eventType, a subsequent write produced postOffFires: 0 against an onChildAdded registration. (Structured evidence: public-operations.test.ts)off(ref, 'value') removes only value listeners at that ref
packages/conformance/observations/rtdb/rtdb-off-eventtype-precision.json — registered TWO value listeners + one child_added at the same ref; after off(ref, 'value') (no callback), valueListenersStopped: true (neither value cb fired on subsequent writes) AND childListenerStillFiringAfterOffValue: true (the child listener kept firing). offValueClearsAllValueListeners: true confirms the no-callback variant removes ALL value listeners at the ref. (Structured evidence: rtdb-modular-off-stops-child-fires, public-operations.test.ts)off(ref, 'value', cb) removes only the specific callback
off with the cb argument removes only the matching callback. Same probe (rtdb-onvalue-unsub-equivalence.json Case 2) confirms off(ref, 'value', cb) stops only that callback. (Structured evidence: oracle-conformance.test.ts)The returned unsubscribe function from onValue(ref, cb) is equivalent to off(ref, 'value', cb)
packages/conformance/observations/rtdb/rtdb-onvalue-unsub-equivalence.json — unsubReturnType: 'function', unsubReturnedFnStopsListener: true (the captured return value halted fires on write), offRefValueCbStopsListener: true (the same effect via off(ref, 'value', cb)), bothFormsEquivalent: true. (Structured evidence: public-operations.test.ts)off(ref, eventType, callback)When the same callback is registered more than once, each off(ref, eventType, callback) removes one registration without orphaning the others
rtdb-modular-off-duplicate-registration proves each matching off removes one registration; sandbox row assertion rtdb-modular#183 replays the full sequence. (Structured evidence: oracle-conformance-reference-writes.test.ts)query(ref, ...constraints) + ordering / bounds / limits
query(ref, orderByChild('field'), limitToFirst(N)) returns a Query whose get() resolves a snapshot containing N children ordered by field
packages/conformance/observations/rtdb-modular/rtdb-modular-query-orderbychild-limit.json — seeded 4 children with positions [3,1,4,2], observed orderedKeys: [{key:'a',pos:1}, {key:'b',pos:2}] (first 2 in ascending order). Requires .indexOn declared in rules. (Structured evidence: rtdb-modular-orderbychild-window, public-operations.test.ts)orderByKey() orders by the auto-id / numeric key
packages/conformance/observations/rtdb-modular/rtdb-modular-orderbykey-window.json — seeded {a,b,c,d,e} in shuffled insertion order, observed matchedKeys: ['b','c','d'] for orderByKey() + startAt('b') + endAt('d') (in key order). (Structured evidence: public-operations.test.ts)Under loaded rules, orderByValue() and orderByChild(path) need .indexOn: '.value' or .indexOn: '<path>' at the queried location: get() rejects with Index not defined, limited or unlimited, and a listener downloads the location, filters it locally, and logs the unspecified-index warning only when the query has a limit or a range. orderByKey() needs no index. A rules-bypassing admin handle meets the same requirement: its get() rejects and its listener warns. With no rules loaded, the sandbox requires no index
rtdb-modular-query-index-enforcement covers orderByChild and orderByValue with a limit, without a limit, and with startAt, plus orderByKey with a limit, each at an indexed and an unindexed location; unit:cdd/query-index-contracts.ts replays the get() and onValue() cases in the sandbox and matches outcomes and log lines. The served worker path delivers the same rejection and logs the warning in the page (packages/cli/test/serve/worker/client/rtdb-listeners.test.ts). Oracle rtdb-modular-admin-query-index (captured 2026-10-07) records the Admin SDK getting the same Index not defined rejection from get(), limited and unlimited, and a limited once('value') delivering the filtered window with the unspecified-index warning; unit:modular/admin-query-index.test.ts replays it on a getAdminDatabase handle. (Structured evidence: rtdb-modular-orderbyvalue-numeric, public-operations.test.ts, oracle-conformance-queries.test.ts, index-diagnostics.test.ts)equalTo(v) filters children whose ordered field === v (returns 0, 1, or multiple matches — RTDB does NOT enforce uniqueness)
packages/conformance/observations/rtdb-modular/rtdb-modular-query-equalto.json — seeded {red, blue, blue, green}, observed matchedKeys: ['k2', 'k3'] for equalTo('blue') (both blue children, none of the others). Additional probe: packages/conformance/observations/rtdb-modular/rtdb-modular-equalTo-filter.json (a..b..c groups) confirms equalTo('b') returns the two b children. (Structured evidence: public-operations.test.ts)startAt(v) is inclusive (the child whose ordered value === v is included)
packages/conformance/observations/rtdb-modular/rtdb-modular-query-startat-inclusive.json — seeded positions [1,2,3,4], observed matched: [2,3,4] for startAt(2) (cursor doc included). (Structured evidence: rtdb-modular-orderbychild-window, rtdb-modular-orderbykey-window, public-operations.test.ts)endAt(v) is inclusive
packages/conformance/observations/rtdb-modular/rtdb-modular-orderbychild-window.json — startAt(2) + endAt(4) matched positions [2,3,4] (endAt(4) included its boundary value). (Structured evidence: rtdb-modular-orderbykey-window, public-operations.test.ts)startAfter(v) is exclusive
packages/conformance/observations/rtdb-modular/rtdb-modular-startafter-endbefore-exclusive.json — startAfter(2) + endBefore(5) matched positions [3,4] (cursor 2 dropped). (Structured evidence: public-operations.test.ts)endBefore(v) is exclusive
packages/conformance/observations/rtdb-modular/rtdb-modular-startafter-endbefore-exclusive.json — same probe; cursor 5 dropped. (Structured evidence: public-operations.test.ts)limitToFirst(N) caps the result count from the start of the ordered range
packages/conformance/observations/rtdb-modular/rtdb-modular-query-orderbychild-limit.json plus packages/conformance/observations/rtdb-modular/rtdb-modular-limittofirst-vs-limittolast.json (firstPositions [1,2]). (Structured evidence: rtdb-modular-orderbyvalue-numeric, public-operations.test.ts)limitToLast(N) caps from the end
packages/conformance/observations/rtdb-modular/rtdb-modular-limittofirst-vs-limittolast.json — observed lastKeys: ['d','e'], lastPositions: [4,5] for limitToLast(2) on a 5-child collection ordered by pos. (Structured evidence: public-operations.test.ts)Listeners on a Query (onValue(q, …)) emit only the windowed snapshot — NOT the parent ref's full data
packages/conformance/observations/rtdb-modular/rtdb-modular-onvalue-with-query.json — seeded 3 children, watched first 2 by pos; observed 3 fires total: (1) initial [a,b], (2) OUTSIDE-window write to c/extra did NOT fire, (3) INSIDE-window mutation of a re-fired, (4) new child z displaced b and re-fired. Outside-window writes are silent. (Structured evidence: public-operations.test.ts)Sentinels — serverTimestamp() / increment(n)
serverTimestamp() resolves server-side to a number (epoch milliseconds) — diverges from Firestore's Timestamp instance
packages/conformance/observations/rtdb/rtdb-servertimestamp-resolves.json — observed createdAtType: 'number', createdAt: 1779075391118 (i.e. a plain JS number, NOT a Timestamp object). (Structured evidence: public-operations.test.ts)serverTimestamp() as a field value in set or update writes the {".sv": "timestamp"} sentinel; the read-back value is the resolved number
packages/conformance/observations/rtdb/rtdb-servertimestamp-resolves.json — read-back showed createdAtSentinelShape: false (sentinel resolved server-side; client sees the number, not the .sv placeholder). (Structured evidence: public-operations.test.ts)increment(n) against a missing field starts at 0 (so increment(5) lands as 5)
increment export now present): unit:modular/increment.test.ts ("increment against a missing field starts from 0"); matches oracle packages/conformance/observations/rtdb-modular/rtdb-modular-increment-from-missing.json — observed afterFirst: 5 from increment(5) against an absent count field.increment(n) against an existing numeric field adds atomically; negative deltas subtract
unit:modular/increment.test.ts ("subsequent increments accumulate (positive then negative)" + "nested inside an update patch resolves per-field"); matches oracle packages/conformance/observations/rtdb-modular/rtdb-modular-increment-from-missing.json — observed afterSecond: 8 (5+3) then afterNegative: 6 (8-2).Divergence: production interleaves concurrent increment writes from independent clients and preserves both deltas; the synchronous in-process backend applies each call before returning its promise, so a Promise.all call site is observably serialized even though its terminal value also reaches 5
rtdb-modular-concurrent-transforms uses two independent clients and captures terminal 5 after concurrent +2/+3 increments; unit:modular/transaction-contention-cdd.test.ts pins the sandbox's synchronous first-write visibility and matching terminal value without claiming that terminal equality proves contention semantics.runTransaction(ref, transactionUpdate, options?) — optimistic concurrency
Basic success — runTransaction(ref, current => (current ?? 0) + 1) resolves { committed: true, snapshot } where snapshot.val() is the new value
packages/conformance/observations/rtdb-modular/rtdb-modular-runtransaction-success.json — observed committed: true, snapVal: 1 after running current => (current ?? 0) + 1 against an empty ref. (Structured evidence: rtdb-modular-runtransaction-on-rules-denied-path, rtdb-modular-runtransaction-options-applylocally, public-operations.test.ts)Returning undefined from the update fn aborts the transaction — resolves { committed: false }, no write performed (RTDB-specific; distinct from Firestore where the only abort path is throwing)
packages/conformance/observations/rtdb-modular/rtdb-modular-runtransaction-abort-undefined.json — seeded 100 then transaction returned undefined; observed committed: false, snapVal: null, afterValOnServer: 100 (existing value preserved). (Structured evidence: public-operations.test.ts)A cold production client can call the update fn with speculative null before the current seeded value; the always-warm sandbox calls it once with the current value
rtdb-modular-runtransaction-current-value-arg captures the cold two-call sequence and rtdb-modular-runtransaction-warm-client-speculation captures the matching warm one-call case; unit:modular/oracle-conformance-transactions.test.ts pins both sides. (Structured evidence: rtdb-modular-runtransaction-options-applylocally, rtdb-modular-runtransaction-success)Concurrent contention — if another client writes between the read and write, the update fn is retried with the new current value (typically up to 25 retries by default)
rtdb-modular-concurrent-transforms captures callback counts [2, 3] across two clients; the synchronous in-process backend serializes the same ordinary calls with [1, 1], pinned by unit:modular/transaction-contention-cdd.test.ts.Result snapshot's .val() reflects the committed value (or the existing value if aborted)
packages/conformance/observations/rtdb-modular/rtdb-modular-runtransaction-success.json — observed snapVal: 1 matching the committed value. (Structured evidence: rtdb-modular-runtransaction-returns-committed-snapshot, public-operations.test.ts)goOnline / goOffline — connection control
goOffline(db) drains that client's onDisconnect queue once, but does not make the in-memory data plane unreachable; ordinary writes, listeners, and get() remain available
goOnline(db) reconnects the logical lifecycle without resurrecting drained operations; it is otherwise a no-op because the in-memory data plane never became unreachable
Transport, logging, and URL-reference exports
forceLongPolling() — accepted no-op: transport selection is not applicable to the in-process/worker sandbox (it never opens a real socket). Accepted so init code that calls it compiles + runs
forceWebSockets() — accepted no-op: transport selection is not applicable to the in-process/worker sandbox (see forceLongPolling)
enableLogging(logger?, persistent?) — accepted no-op: the sandbox has no modular-SDK-style logger to wire a level/sink into (it uses host-level console logging directly, matching pyric/firestore's setLogLevel). Accepted so init code that calls it compiles + runs
refFromURL(db, url) matches Firebase's path parsing, query ignoring, FTP-to-database normalization, fragment rejection and malformed-URL error. As the SDK does, a URL whose host is not the database's host throws Host name does not match the current database, unless the database's host is custom (any domain but firebaseio.com and firebaseio-demo.com). A sandbox database opened without a URL has no host, so its URLs are not checked.
rtdb-modular-reference-shape-url captures accepted FTP/query URLs and rejected fragments, malformed URLs, and host mismatches; unit:modular/oracle-conformance-reference-writes.test.ts replays each, and unit:modular/ref-from-url-host.test.ts pins the host check for an app's default instance, a named instance and a custom host, from hunt finding RT-12.Calls in flight when the hosted connection drops
The web hosted client talks to the Node host over one WebSocket. When that socket drops, a call the socket had already taken is in flight: the host may or may not have run it (ADR-0019 decision 7). Each row here states what becomes of such a call, against what the production Web SDK does when its own connection drops. The Node remote client (remoteSandbox(), used by node --import @pyric/cli/register) has its own socket to the host; row HD2 covers it.
Calls in flight at a hosted connection drop (web hosted client)When the web hosted client's socket drops, an RTDB write (set, update, remove, setPriority, setWithPriority, push) or get the socket had taken is sent again after the client re-attaches, ahead of any call issued later, under a new request id, and resolves on the new reply with no deadline; a late reply to the copy the dropped socket took is ignored. A write sent again may apply twice. An onDisconnect registration or cancel() the socket had taken never settles and is not sent again. A transaction commit the socket had taken rejects with Error('disconnect'), which has no code, and is not retried.
@firebase/database 1.1.3 dist/index.esm.js: onRealtimeDisconnect_ calls cancelSentTransactions_ and clears requestCBHash_, the callbacks of every sent request; restoreState_ sends the listens, then outstandingPuts_, then queued onDisconnects, then outstandingGets_ again; a sent onDisconnect lives only in requestCBHash_ (sendOnDisconnect_), so its promise never settles; and a cancelled transaction completes with new Error('disconnect'). packages/cli/test/serve/worker/hosted-reconnect-hold.test.ts drops a real loopback socket with each method in flight and asserts its outcome, the re-sent order, that a re-sent write has no deadline, and that a late reply to the old request id settles nothing. packages/cli/test/serve/worker/hosted-resume-late-reply.test.ts runs the client against the real bridge consumer session and shows the resumed client keeps its host session, so that late reply reaches the new socket. packages/cli/test/serve/worker/hosted-delivery-contract.test.ts drives set, onDisconnect().set() and runTransaction through the client functions. App scenario test/apps/rtdb-write-in-flight-at-drop drops Chromium's hosted socket against a Vite dev server with a set and an onDisconnect().set() in flight, and asserts no unhandled rejection, the set resolving after the reconnect, and its value stored (#1088). CDD assertion rtdb-modular#HD1 pins the sandbox side: the in-page sandbox has no socket, so the same calls settle in process across goOffline() and goOnline(). (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)unavailable (#1048)Calls in flight at a hosted connection drop (Node remote client)When the socket of the Node remote client's lazy handle (remoteSandbox(), which @pyric/cli/register installs) drops after it has attached, an RTDB write (set, update, remove, setPriority, setWithPriority, or a push that carries its key, as pyric-admin sends it) or get the socket had taken is sent again once the client reconnects, after its listeners are restored and ahead of any call issued later, under the new connection's request id, and resolves on the new reply with no deadline. A write sent again may apply twice. An onDisconnect registration or cancel() sent over the raw channel never settles and is not sent again. A transaction commit sent over the raw channel rejects with Error('disconnect'), which has no code, and is not retried. A push without a key fails once with unavailable, since sending it again would add a second child.
@firebase/database 1.1.3 code as row HD1 (onRealtimeDisconnect_, restoreState_, sendOnDisconnect_, cancelSentTransactions_); the package runs the same database core in Node. Pyric behavior: packages/cli/src/serve/worker/rtdb-drop-fates.ts is the per-method table both this client and the web hosted client classify a call with, and packages/cli/src/remote/index.ts releaseInFlight applies it, failing a key-less push. packages/cli/src/remote/held-calls.ts holds the calls until the next attach. packages/cli/test/remote/reconnect.test.ts stops a real loopback host with calls in flight and asserts each method's outcome, that a write or get is sent again on the restarted host under a new id and resolves on its reply, the order (restored listeners, then calls in flight, then calls issued while down), that a call sent again outlives the hold deadline, and that a returning host refusing the attach or close() fails them unsent. packages/cli/test/remote/loop-hold.test.ts asserts the release by fate and that a held call keeps a Node process alive until it settles. App scenario test/apps/node-client-host-restart runs a firebase-admin writer under node --import @pyric/cli/register, restarts the hosted Vite dev server by editing vite.config.js mid-run, and asserts every write resolves and is stored and none reports the URL as stale (#1107). CDD assertion rtdb-modular#HD2 pins the sandbox side: the in-page sandbox has no socket, so a write and a get settle in process across goOffline() and goOnline(). (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)pyric-admin DataSnapshot forEach / numChildren / hasChildren / child, and worker bridge snapshotsA node whose keys are integers keeps its children when val() renders it as an array. A pyric-admin snapshot of such a node, read in process or through the remote arm, iterates forEach over children keyed '0', '1', ... in index order, skipping indexes that hold no value, and numChildren(), hasChildren(), child('1') and hasChild('1') count and address the same children. A snapshot the worker bridge hydrates without the host's ordered entries, from child() or inside forEach, iterates an array value the same way. forEach stops when the callback returns true and returns true. Both pyric-admin arms store a write by key, as the host does, so an object whose keys are integers, written with set(), update() or push(), reads back from val() as an array when its largest key is below twice the key count, with a hole at each missing index, while exportVal() and toJSON() keep the integer keys as object keys. Null children and empty objects are dropped. For a node written without priorities, the in-process arm, the remote arm and the in-page client sandbox agree on val(), exportVal(), toJSON(), numChildren(), forEach keys and order, and child(). Both pyric-admin arms refuse a write firebase-admin refuses (undefined, a function, NaN or an infinity, an invalid key, .value beside children, an inline priority that is not a string or number, or an update() key ending in .priority whose value is not a valid priority) by throwing synchronously with firebase-admin's text, and store nothing. Both arms write a value as RTDB stores it, so a Date is dropped as firebase-admin drops it. Priorities are not modeled on the pyric-admin arms: a valid priority, inline or under an update() key ending in .priority, is accepted and dropped on both, and the in-process arm's exportVal() carries none. The remote arm's exportVal() and toJSON() return the host's export, so a priority another plane set reads back with it.
@firebase/database 1.1.3 dist/index.node.cjs.js: DataSnapshot.forEach returns false only for a leaf node and otherwise walks the node's children in priority, then nameCompare key order; hasChildren is !isLeafNode() && !isEmpty(); size is ChildrenNode.numChildren(); ChildrenNode.val renders a node as an array only when every key is an integer and the largest is below twice the key count and the call is not exporting (exportVal() and toJSON() call val(true)), leaving missing indexes as holes; validateFirebaseData and validateFirebaseMergeDataArg refuse a write synchronously. Pyric behavior: valueChildren (exported from pyric/database/internal) lists a value's children (array indexes as string keys without holes or nulls, or object keys in nameCompare order), used by packages/pyric-admin/src/database/index.ts buildSandboxSnap and packages/cli/src/serve/worker/client/rtdb-snapshots.ts makeRtdbSnapshot. Both pyric-admin arms validate a write with validateWrite before it runs or is relayed, and their shared snapshot keeps the stored value for exportVal() and toJSON() and renders val() with coerceArrays; the in-process arm stores what normalizeNode builds. These are the write-boundary normalization the in-page sandbox and the host use, exported from pyric/database/internal. packages/pyric-admin/test/database/write-validation.test.ts runs 35 refused writes on both arms and asserts the synchronous error text firebase-admin 13.10.0 throws for each, read from the SDK run offline, and that nothing is stored; it also asserts a valid priority is dropped on both arms, a Date is dropped on both, and the remote arm's exportVal() carries a priority the host set. packages/pyric/test/database/modular/write-validation-text.test.ts asserts the in-page sandbox's refusal text for set, push (naming the parent's path), setWithPriority, update, a transaction result, and onDisconnect().set() and setWithPriority(), and its keyed exportVal() and toJSON(). packages/pyric-admin/test/database/array-children.test.ts asserts a dense, sparse and nested array, each child's key, value and reference, and the early exit. packages/pyric-admin/test/database/integer-keys-parity.test.ts writes dense, sparse and over-threshold integer keys, arrays, nested mixes, null children, empty objects, update() and push() on the in-process arm, the remote arm on the real worker host, and the in-page client sandbox, and asserts the same val(), exportVal(), numChildren(), forEach keys and order, and child() on all three (#1121). packages/cli/test/serve/worker/client/rtdb-snapshots.test.ts iterates a nested and a sparse array below the top level of a worker snapshot. App scenario test/apps/node-client-host-restart reads the stored ticks back with forEach from a firebase-admin process under node --import @pyric/cli/register (#1110). CDD assertion rtdb-modular#AS1 pins the sandbox side: an array and an object with keys 0, 1, 2 written through getAdminDatabase read back as the same array, which iterates as one child per index. (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)Client SDKs in a registered server process
A server process started with node --import @pyric/cli/register and PYRIC_SANDBOX=remote, remote:<url>, 1 or true runs the client SDKs against the Node host (#1082): firebase/app, firebase/database, firebase/firestore, firebase/auth and firebase/storage resolve to @pyric/cli’s Node client, which reaches the host over its own hosted connection with the process’s own signed-in session, so the host’s rules apply as they do for any other client. Off the Node host every call fails instead of running against a private in-process sandbox, and the client services with no path to the host refuse. PYRIC_SANDBOX=local keeps the in-process sandbox. In production the client SDKs run in Node and reach the project.
getDatabase(app) in a registered server processUnder a remote register activation on the Node host, firebase/database in a server process reads and writes the host's data under its rules as the process's signed-in user: a write the rules deny for that user fails with PERMISSION_DENIED, .info/connected follows the process's connection, and an onDisconnect write runs when that connection ends. From its first RTDB call on an instance the process stays up until goOffline() on that instance or deleteApp(), as @firebase/database keeps a Node process up. When the host is not the Node host, every call fails with failed-precondition and a message naming the Node host (pyric sandbox --hosted or pyric({ hosted: true })); when no host is found, with the discovery error pyric-admin gets. No call falls back to an in-process sandbox.
test/apps/client-sdk-under-register runs the client SDKs under node --import @pyric/cli/register against a hosted Vite dev server, reads back with firebase-admin and a page, and asserts a write and a read, a denied write to another user's path, .info/connected, an onDisconnect that ran after the process exited, and that a process stays up after a write until goOffline(). node-realm.test.ts pins when the process is held. CDD assertion rtdb-modular#RS1 pins the sandbox side: rules evaluate per signed-in session, and a registry bound to the refusal opens no database handle. On main (942cb175) it failed: the calls ran against a private in-process sandbox, so an upload returned a data: URL and firebase-admin read nothing they wrote. packages/cli/test/register/node-origin.test.ts runs the served surfaces under a Node origin whose host is not the Node host, or cannot be found, and asserts every call fails, useWorker stays true, the served app entry's placeholder sandbox stays empty, and a pyric/* mirror resolved from the app refuses. mapping.test.ts pins the mapping per activation value.. (Structured evidence: register-child.test.ts, lifecycle-and-identity.test.ts)Server-rendered modules under vite dev
Modules Vite loads for server rendering under vite dev with pyric() (server.ssrLoadModule, a runnable environment, a framework’s SSR entry and loaders) get the modules a registered server process gets (#1123): the client SDKs reach the dev server’s own Node host as one signed-in SSR session per dev server process, and firebase-admin reaches it as admin. This holds with Vite’s default externalization and with ssr.noExternal. A SharedWorker dev server refuses them, naming pyric({ hosted: true }), and a server environment Vite does not run in its own process (workerd) gets a module that throws when it loads. In production these modules run the Firebase SDKs in the server’s runtime and reach the project.
getDatabase(app) in a server-rendered module under vite devOn a hosted dev server, firebase/database in a server-rendered module reads and writes the host's data under its rules as the SSR session's user: a write the rules deny for that user fails with PERMISSION_DENIED. ssrLoadModule, the environment runner and every ssr.noExternal setting share one app and one session. Closing the dev server lets the process go, so a process that created the server through Vite's API ends on its own, though RTDB would otherwise hold it until goOffline(). On a SharedWorker dev server every call fails with failed-precondition and a message naming pyric({ hosted: true }). No call reaches production or an in-process sandbox.
test/apps/vite-ssr-client-sdk writes and reads the SSR user's own path, is denied another user's, reads the writes back with firebase-admin in SSR and in a process on the host, repeats it with ssr.noExternal ['firebase'] and true, refuses on a SharedWorker dev server, and creates a dev server through Vite's API that ends on its own after SSR used RTDB. On main (ba2c0bf0a) the scenario failed: SSR sign-in rejected with auth/network-request-failed from the network guard, and the RTDB, Firestore and Storage writes did not settle, because the imports loaded the real SDK. vite-module-swap.test.ts pins the routing per specifier, AI mode and environment (Vite 5's ssr option, a runnable environment, a non-runnable one), vite-ssr-activation.test.ts the host, the restart hand-over and the SharedWorker refusal, and vite-plugin-firestore.test.ts runs Vite with firebase installed, so it takes the externalized path. CDD assertion rtdb-modular#RS2 pins the sandbox side. node-realm.test.ts pins the release when the in-process host ends. (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)initializeServerApp) is unsupportedfirebase-admin/database in a server-rendered module under vite devOn a hosted dev server, firebase-admin in a server-rendered module resolves to pyric-admin bound to the dev server's host, as a firebase-admin process on the host is: a bare initializeApp() connects to it, reads bypass the rules, and the writes of browsers and SSR sessions are visible. On a SharedWorker dev server its first call fails with failed-precondition and a message naming pyric({ hosted: true }), without dialing.
test/apps/vite-ssr-client-sdk reads a path the rules let only the SSR user read, and a browser's write, with firebase-admin in SSR through both loaders and with each externalization setting, and gets the refusal on a SharedWorker dev server. On main (ba2c0bf0a) firebase-admin in SSR was the real SDK. ambient-init.test.ts pins that a bare initializeApp() binds the in-process activation's sandbox when PYRIC_SANDBOX is unset, and that the variable wins when set. CDD assertion rtdb-modular#RS3 pins the sandbox side. (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)Behavior checked against production captures
Each row cites a production capture from the SDK behavior hunt. A bug row states production’s behavior and pyric’s; its test holds both answers until the fix lands.
runTransaction(ref, fn) followed at once by set(ref, value)On a cold production client the set overtakes the transaction, which rejects with Error('set'); pyric commits it. A warm client commits in both. RT-15.
oracle:rtdb-modular-transaction-then-set keys cold and warm (both clients were cold) and oracle:rtdb-modular-transaction-then-set-warm. (Structured evidence: capture-transaction-then-set.test.ts)runTransaction then set on the served planesOn the served planes the transaction reruns on the set's value and commits on top (101); production keeps the set's 100. RP-4.
Event order for one remote multi-path updateProduction fires deeper paths first and child events (removed, added, moved, changed) before value; the in-page sandbox fires value first, parents first, in registration order. RT-2, RT-3.
oracle:rtdb-modular-remote-update-event-order key log. (Structured evidence: capture-remote-update-event-order.test.ts)setPriority(ref) and child_changedProduction fires child_changed on the parent's listeners for a priority-only change. Pyric fires none, on every plane. RT-4.
oracle:rtdb-modular-remote-update-event-order (R changed a and Q changed a after setPriority). (Structured evidence: capture-remote-update-event-order.test.ts, rtdb-remote-update-event-order.test.ts)child_moved on a query with no orderByProduction fires child_moved for a priority change on a query with no orderBy (L moved a). The in-page sandbox fires none; the served planes match production. RT-5, part of #138.
oracle:rtdb-modular-remote-update-event-order. (Structured evidence: capture-remote-update-event-order.test.ts)Object.keys(snapshot.val())Production and pyric order val() keys by priority, then key, on a ref and a query snapshot. RT-7, fixed in #1371.
oracle:rtdb-modular-remote-update-event-order key valKeys, replayed in page and on the served planes; packages/pyric/test/database/modular/snapshot-serialization.test.ts adds priorities and nested values. (Structured evidence: capture-remote-update-event-order.test.ts, rtdb-remote-update-event-order.test.ts)Event order for one remote update on the served planesProduction delivers one write's events deepest path first, child events before value. On the SharedWorker and Node host planes they arrive listener by listener in registration order. RP-5.
orderByPriority with endAt or endBefore and limitToLast over children with no priorityProduction and pyric give the same keys: z for endAt("1","A") with limitToLast(1), b,z for endBefore("1") with limitToLast(2), 1,10,A,a,b,z with no limit, and a,b,z for the endAt(2) limitToLast(3) control. The capture refuted hunt finding RT-17.
oracle:rtdb-modular-priority-window-limit-to-last. (Structured evidence: capture-priority-window-limit-to-last.test.ts)onValue(query) and a grandchild's priority changeProduction fires a value event on every listener above a grandchild whose priority changes, orderByKey queries included. Pyric's query listeners miss it on every plane, though plain ref listeners get it. RP-8 (differential seed 7395).
oracle:rtdb-modular-grandchild-priority-query-value. (Structured evidence: capture-grandchild-priority-query-value.test.ts)Current gaps
Documented divergences
Known differences between Pyric and production Firebase. Each remains tracked as a non-conforming row.
Cold production clients may invoke the update fn first with speculative null and then with the current seeded value; the always-warm in-process sandbox invokes it once with the current value, so abort-if-missing aborts in production and commits in pyric (RT-16)
rtdb-modular-runtransaction-current-value-arg captures two seeded-path production invocations (null, then current); unit:modular/oracle-conformance-transactions.test.ts pins the sandbox's single current-value invocation. The separate warm-client observation matches the sandbox but does not erase the cold-client contract. oracle:rtdb-modular-transaction-then-set key abortIfMissing: production aborts, pyric commits (RT-16). (Structured evidence: transaction.test.ts, capture-transaction-then-set.test.ts)**Divergence:** two ordinary concurrent runTransaction calls are serialized by the in-process backend, so their update functions are not retried with Firebase's captured contention counts. A synchronous re-entrant conflicting write does trigger a deterministic retry.
rtdb-modular-concurrent-transforms captures invocation counts [2, 3]; unit:modular/transaction-contention-cdd.test.ts pins the sandbox's [1, 1] ordinary-concurrency boundary and separately covers its deterministic re-entrant retry seam.**Divergence (pending fix):** clean goOffline, app deletion, playground pagehide, and best-effort MessagePort close drain queued operations, but unannounced total renderer/process loss is not guaranteed by the in-memory sandbox
rtdb-modular-ondisconnect-abrupt-exit proves Firebase executes an acknowledged registration after forced writer termination. The two-port worker integration exercises goOffline, served-app deletion, and non-persisted pagehide; browser MessagePort close delivery cannot prove total-process loss without durable host-owned leases. (Structured evidence: rtdb-integration.test.ts)**Divergence:** DatabaseReference and Query equality includes database target, path, and canonical query parameters like Firebase, but toJSON() serializes the local sandbox://rtdb/... identity instead of Firebase's HTTPS database URL.
rtdb-modular-reference-shape-url captures conforming equality plus HTTPS JSON serialization; unit:modular/oracle-conformance-reference-writes.test.ts pins both the production HTTPS shape and the sandbox's sandbox:// boundary.**Divergence:** production interleaves concurrent increment writes from independent clients and preserves both deltas; the synchronous in-process backend applies each call before returning its promise, so a Promise.all call site is observably serialized even though its terminal value also reaches 5
rtdb-modular-concurrent-transforms uses two independent clients and captures terminal 5 after concurrent +2/+3 increments; unit:modular/transaction-contention-cdd.test.ts pins the sandbox's synchronous first-write visibility and matching terminal value without claiming that terminal equality proves contention semantics.A cold production client can call the update fn with speculative null before the current seeded value; the always-warm sandbox calls it once with the current value
rtdb-modular-runtransaction-current-value-arg captures the cold two-call sequence and rtdb-modular-runtransaction-warm-client-speculation captures the matching warm one-call case; unit:modular/oracle-conformance-transactions.test.ts pins both sides. (Structured evidence: rtdb-modular-runtransaction-options-applylocally, rtdb-modular-runtransaction-success)Concurrent contention — if another client writes between the read and write, the update fn is retried with the new current value (typically up to 25 retries by default)
rtdb-modular-concurrent-transforms captures callback counts [2, 3] across two clients; the synchronous in-process backend serializes the same ordinary calls with [1, 1], pinned by unit:modular/transaction-contention-cdd.test.ts.goOffline(db) drains that client's onDisconnect queue once, but does not make the in-memory data plane unreachable; ordinary writes, listeners, and get() remain available
goOnline(db) reconnects the logical lifecycle without resurrecting drained operations; it is otherwise a no-op because the in-memory data plane never became unreachable
forceLongPolling() — accepted no-op: transport selection is not applicable to the in-process/worker sandbox (it never opens a real socket). Accepted so init code that calls it compiles + runs
forceWebSockets() — accepted no-op: transport selection is not applicable to the in-process/worker sandbox (see forceLongPolling)
enableLogging(logger?, persistent?) — accepted no-op: the sandbox has no modular-SDK-style logger to wire a level/sink into (it uses host-level console logging directly, matching pyric/firestore's setLogLevel). Accepted so init code that calls it compiles + runs
getDatabase(app) in a registered server processUnder a remote register activation on the Node host, firebase/database in a server process reads and writes the host's data under its rules as the process's signed-in user: a write the rules deny for that user fails with PERMISSION_DENIED, .info/connected follows the process's connection, and an onDisconnect write runs when that connection ends. From its first RTDB call on an instance the process stays up until goOffline() on that instance or deleteApp(), as @firebase/database keeps a Node process up. When the host is not the Node host, every call fails with failed-precondition and a message naming the Node host (pyric sandbox --hosted or pyric({ hosted: true })); when no host is found, with the discovery error pyric-admin gets. No call falls back to an in-process sandbox.
test/apps/client-sdk-under-register runs the client SDKs under node --import @pyric/cli/register against a hosted Vite dev server, reads back with firebase-admin and a page, and asserts a write and a read, a denied write to another user's path, .info/connected, an onDisconnect that ran after the process exited, and that a process stays up after a write until goOffline(). node-realm.test.ts pins when the process is held. CDD assertion rtdb-modular#RS1 pins the sandbox side: rules evaluate per signed-in session, and a registry bound to the refusal opens no database handle. On main (942cb175) it failed: the calls ran against a private in-process sandbox, so an upload returned a data: URL and firebase-admin read nothing they wrote. packages/cli/test/register/node-origin.test.ts runs the served surfaces under a Node origin whose host is not the Node host, or cannot be found, and asserts every call fails, useWorker stays true, the served app entry's placeholder sandbox stays empty, and a pyric/* mirror resolved from the app refuses. mapping.test.ts pins the mapping per activation value.. (Structured evidence: register-child.test.ts, lifecycle-and-identity.test.ts)getDatabase(app) in a server-rendered module under vite devOn a hosted dev server, firebase/database in a server-rendered module reads and writes the host's data under its rules as the SSR session's user: a write the rules deny for that user fails with PERMISSION_DENIED. ssrLoadModule, the environment runner and every ssr.noExternal setting share one app and one session. Closing the dev server lets the process go, so a process that created the server through Vite's API ends on its own, though RTDB would otherwise hold it until goOffline(). On a SharedWorker dev server every call fails with failed-precondition and a message naming pyric({ hosted: true }). No call reaches production or an in-process sandbox.
test/apps/vite-ssr-client-sdk writes and reads the SSR user's own path, is denied another user's, reads the writes back with firebase-admin in SSR and in a process on the host, repeats it with ssr.noExternal ['firebase'] and true, refuses on a SharedWorker dev server, and creates a dev server through Vite's API that ends on its own after SSR used RTDB. On main (ba2c0bf0a) the scenario failed: SSR sign-in rejected with auth/network-request-failed from the network guard, and the RTDB, Firestore and Storage writes did not settle, because the imports loaded the real SDK. vite-module-swap.test.ts pins the routing per specifier, AI mode and environment (Vite 5's ssr option, a runnable environment, a non-runnable one), vite-ssr-activation.test.ts the host, the restart hand-over and the SharedWorker refusal, and vite-plugin-firestore.test.ts runs Vite with firebase installed, so it takes the externalized path. CDD assertion rtdb-modular#RS2 pins the sandbox side. node-realm.test.ts pins the release when the in-process host ends. (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)firebase-admin/database in a server-rendered module under vite devOn a hosted dev server, firebase-admin in a server-rendered module resolves to pyric-admin bound to the dev server's host, as a firebase-admin process on the host is: a bare initializeApp() connects to it, reads bypass the rules, and the writes of browsers and SSR sessions are visible. On a SharedWorker dev server its first call fails with failed-precondition and a message naming pyric({ hosted: true }), without dialing.
test/apps/vite-ssr-client-sdk reads a path the rules let only the SSR user read, and a browser's write, with firebase-admin in SSR through both loaders and with each externalization setting, and gets the refusal on a SharedWorker dev server. On main (ba2c0bf0a) firebase-admin in SSR was the real SDK. ambient-init.test.ts pins that a bare initializeApp() binds the in-process activation's sandbox when PYRIC_SANDBOX is unset, and that the variable wins when set. CDD assertion rtdb-modular#RS3 pins the sandbox side. (Structured evidence: scenario.ts, lifecycle-and-identity.test.ts)Bugs
Behavior that should match production Firebase but currently does not.
runTransaction(ref, fn) followed at once by set(ref, value)On a cold production client the set overtakes the transaction, which rejects with Error('set'); pyric commits it. A warm client commits in both. RT-15.
oracle:rtdb-modular-transaction-then-set keys cold and warm (both clients were cold) and oracle:rtdb-modular-transaction-then-set-warm. (Structured evidence: capture-transaction-then-set.test.ts)runTransaction then set on the served planesOn the served planes the transaction reruns on the set's value and commits on top (101); production keeps the set's 100. RP-4.
Event order for one remote multi-path updateProduction fires deeper paths first and child events (removed, added, moved, changed) before value; the in-page sandbox fires value first, parents first, in registration order. RT-2, RT-3.
oracle:rtdb-modular-remote-update-event-order key log. (Structured evidence: capture-remote-update-event-order.test.ts)setPriority(ref) and child_changedProduction fires child_changed on the parent's listeners for a priority-only change. Pyric fires none, on every plane. RT-4.
oracle:rtdb-modular-remote-update-event-order (R changed a and Q changed a after setPriority). (Structured evidence: capture-remote-update-event-order.test.ts, rtdb-remote-update-event-order.test.ts)child_moved on a query with no orderByProduction fires child_moved for a priority change on a query with no orderBy (L moved a). The in-page sandbox fires none; the served planes match production. RT-5, part of #138.
oracle:rtdb-modular-remote-update-event-order. (Structured evidence: capture-remote-update-event-order.test.ts)Event order for one remote update on the served planesProduction delivers one write's events deepest path first, child events before value. On the SharedWorker and Node host planes they arrive listener by listener in registration order. RP-5.
onValue(query) and a grandchild's priority changeProduction fires a value event on every listener above a grandchild whose priority changes, orderByKey queries included. Pyric's query listeners miss it on every plane, though plain ref listeners get it. RP-8 (differential seed 7395).
oracle:rtdb-modular-grandchild-priority-query-value. (Structured evidence: capture-grandchild-priority-query-value.test.ts)