pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/dist/database/internal/query-projection.js

@@ -0,0 +1,293 @@
+/**
+ * Compare two `JsonValue`s under RTDB's documented type-order rules.
+ * Locked by the upstream contract (Firebase docs: null < false < true
+ * < number < string < object). The sandbox's ordering only needs to
+ * match against same-type-or-null/undefined.
+ *
+ * Returns -1 / 0 / 1.
+ */
+export function compareValues(a, b) {
+    const areEqual = a === b;
+    if (areEqual)
+        return 0;
+    // null sorts first.
+    const isLeftNull = a === null;
+    if (isLeftNull)
+        return -1;
+    const isRightNull = b === null;
+    if (isRightNull)
+        return 1;
+    const ta = typeofRank(a);
+    const tb = typeofRank(b);
+    const haveDifferentTypes = ta !== tb;
+    if (haveDifferentTypes)
+        return ta - tb;
+    // Same type — value comparison.
+    const areNumbers = typeof a === 'number' && typeof b === 'number';
+    if (areNumbers) {
+        const isLower = a < b;
+        if (isLower)
+            return -1;
+        const isHigher = a > b;
+        return isHigher ? 1 : 0;
+    }
+    const areBooleans = typeof a === 'boolean' && typeof b === 'boolean';
+    if (areBooleans) {
+        const isLeftTrue = a === true;
+        return isLeftTrue ? 1 : -1;
+    }
+    const areStrings = typeof a === 'string' && typeof b === 'string';
+    if (areStrings) {
+        const isLower = a < b;
+        if (isLower)
+            return -1;
+        const isHigher = a > b;
+        return isHigher ? 1 : 0;
+    }
+    // Objects/arrays are "greater" than primitives, but two object-valued
+    // children are ORDER-EQUAL under RTDB's model — the tie is broken by
+    // key, NOT by an invented JSON-string ordering (DB-B11; mirrors
+    // `ChildrenNode.ts:386-400` where ChildrenNodes compare equal). Return
+    // 0 so the caller's key tie-break takes over.
+    return 0;
+}
+function typeofRank(v) {
+    // null = 0; boolean = 1; number = 2; string = 3; object/array = 4.
+    const isNull = v === null;
+    if (isNull)
+        return 0;
+    const isBoolean = typeof v === 'boolean';
+    if (isBoolean)
+        return 1;
+    const isNumber = typeof v === 'number';
+    if (isNumber)
+        return 2;
+    const isString = typeof v === 'string';
+    if (isString)
+        return 3;
+    return 4;
+}
+/** Used to test for integer-looking strings. Mirrors `INTEGER_REGEXP_`
+ *  (`core/util/util.ts:496`). */
+const INTEGER_REGEXP = /^-?(0*)\d{1,10}$/;
+const INTEGER_32_MIN = -2147483648;
+const INTEGER_32_MAX = 2147483647;
+/** If the string is a 32-bit integer, return it; else `null`. Mirrors
+ *  `tryParseInt` (`core/util/util.ts:511-520`). */
+function tryParseInt(str) {
+    const looksLikeInteger = INTEGER_REGEXP.test(str);
+    if (looksLikeInteger) {
+        const intVal = Number(str);
+        const fitsIntegerKeyRange = intVal >= INTEGER_32_MIN && intVal <= INTEGER_32_MAX;
+        if (fitsIntegerKeyRange) {
+            return intVal;
+        }
+    }
+    return null;
+}
+/**
+ * Compare two Firebase key names under RTDB's `nameCompare` ordering:
+ * integer-looking keys sort FIRST (numerically; ties broken by string
+ * length so `"01"` follows `"1"`), then non-integer keys sort
+ * lexicographically. Mirrors `nameCompare` (`core/util/util.ts:253-276`).
+ *
+ * This is RTDB's universal key order — it drives `orderByKey()`, the
+ * tie-break for `orderByChild`/`orderByValue`, and the `key` argument of
+ * `startAt(value, key)` / `endAt(value, key)` cursors. Plain
+ * lexicographic compare (DB-B4) put `"10"` before `"2"`.
+ */
+export function nameCompare(a, b) {
+    const areEqual = a === b;
+    if (areEqual)
+        return 0;
+    const aAsInt = tryParseInt(a);
+    const bAsInt = tryParseInt(b);
+    const isLeftInteger = aAsInt !== null;
+    const isRightInteger = bAsInt !== null;
+    if (isLeftInteger) {
+        if (isRightInteger) {
+            const difference = aAsInt - bAsInt;
+            const haveSameInteger = difference === 0;
+            return haveSameInteger ? a.length - b.length : difference;
+        }
+        // Integer keys sort before non-integer keys.
+        return -1;
+    }
+    else if (isRightInteger) {
+        return 1;
+    }
+    const comesBefore = a < b;
+    return comesBefore ? -1 : 1;
+}
+/**
+ * Extract the value the ordering uses to compare a child. For
+ * `orderByKey()` it's the key string; for `orderByValue()` the child's
+ * raw value; for `orderByChild(path)` the nested field at `path`
+ * (which may itself be missing → `null`).
+ */
+export function extractOrderValue(spec, key, value, priority = null) {
+    const o = spec ?? { kind: 'priority' };
+    switch (o.kind) {
+        case 'key':
+            return key;
+        case 'value':
+            return value;
+        case 'priority':
+            return priority;
+        case 'child': {
+            const hasNoChildren = value === null || typeof value !== 'object' || Array.isArray(value);
+            if (hasNoChildren) {
+                return null;
+            }
+            // Path may be a slash-separated dotted path (`'profile/name'`).
+            const segs = o.path.split('/').filter((s) => s.length > 0);
+            let cur = value;
+            for (const s of segs) {
+                const hasNoDescendant = cur === null || typeof cur !== 'object' || Array.isArray(cur);
+                if (hasNoDescendant)
+                    return null;
+                cur = cur[s] ?? null;
+            }
+            return cur;
+        }
+    }
+}
+/**
+ * Run a {@link QuerySpec} against the data at a path. The caller passes
+ * the raw value at the path (a `Record<string, JsonValue>` if it's a
+ * collection, anything else → empty result).
+ *
+ * Returns an ordered, filtered, limited list of rows.
+ */
+export function executeQuery(pathData, spec, priorityForKey = () => null) {
+    // Scalar inputs have no child rows. Snapshot callers handle scalar values.
+    const hasNoChildren = pathData === null || typeof pathData !== 'object' || Array.isArray(pathData);
+    if (hasNoChildren) {
+        return [];
+    }
+    const obj = pathData;
+    // Enumerate immediate children only — RTDB's query model is one-level.
+    let rows = Object.entries(obj).map(([key, value]) => ({
+        key,
+        value,
+        priority: priorityForKey(key),
+    }));
+    // ─── 1. Order ─────────────────────────────────────────────────────
+    const orderingByKey = spec.orderBy?.kind === 'key';
+    rows.sort((a, b) => {
+        if (orderingByKey) {
+            // `orderByKey` compares keys under RTDB's nameCompare directly
+            // (numeric-keys-first) — there's no separate tie-break.
+            return nameCompare(a.key, b.key);
+        }
+        const va = extractOrderValue(spec.orderBy, a.key, a.value, a.priority);
+        const vb = extractOrderValue(spec.orderBy, b.key, b.value, b.priority);
+        const cmp = compareValues(va, vb);
+        const haveDifferentOrderValues = cmp !== 0;
+        if (haveDifferentOrderValues)
+            return cmp;
+        // Tie-break by key under nameCompare (RTDB's documented behavior —
+        // orderByChild / orderByValue ties break by key, numeric-first).
+        return nameCompare(a.key, b.key);
+    });
+    // ─── 2. Bounds ────────────────────────────────────────────────────
+    for (const b of spec.bounds) {
+        rows = rows.filter((row) => boundMatches(b, row, spec.orderBy));
+    }
+    // ─── 3. Limit ─────────────────────────────────────────────────────
+    const limit = spec.limit;
+    const hasLimit = limit !== null;
+    if (hasLimit) {
+        const n = limit.n;
+        const takesFirst = limit.kind === 'limitToFirst';
+        if (takesFirst) {
+            rows = rows.slice(0, n);
+        }
+        else {
+            const includesAllRows = n >= rows.length;
+            if (includesAllRows)
+                return rows;
+            rows = rows.slice(rows.length - n);
+        }
+    }
+    return rows;
+}
+/**
+ * Does `row` pass the bound `b` under the active ordering?
+ *
+ * The bound's `value` is compared against the row's `extractOrderValue`.
+ * The optional `key` arg (for `startAt(value, key)`) is a tie-breaker
+ * for matching rows whose ordered-value equals `value` — the row passes
+ * only if its key is also at-or-past the supplied key.
+ */
+function boundMatches(b, row, orderBy) {
+    const orderingByKey = orderBy?.kind === 'key';
+    // Under `orderByKey`, the bound's `value` IS the comparison key and is
+    // compared with nameCompare (numeric-first), NOT the value type-order.
+    // Under value/child ordering, compare the ordered value, then break
+    // ties on the key with nameCompare.
+    let cmp;
+    if (orderingByKey) {
+        cmp = nameCompare(row.key, String(b.value));
+    }
+    else {
+        const orderValue = extractOrderValue(orderBy, row.key, row.value, row.priority);
+        cmp = compareValues(orderValue, b.value);
+    }
+    const keyCmp = (other) => nameCompare(row.key, other);
+    const isAfter = cmp > 0;
+    const isBefore = cmp < 0;
+    const differsFromBound = cmp !== 0;
+    switch (b.kind) {
+        case 'startAt': {
+            if (isAfter)
+                return true;
+            if (isBefore)
+                return false;
+            // Equal: defer to optional key tie-breaker.
+            const boundaryKey = b.key;
+            const hasNoBoundaryKey = boundaryKey === undefined;
+            return hasNoBoundaryKey || keyCmp(boundaryKey) >= 0;
+        }
+        case 'startAfter': {
+            if (isAfter)
+                return true;
+            if (isBefore)
+                return false;
+            // Equal: row passes only if key strictly past the tie-breaker.
+            const boundaryKey = b.key;
+            const hasNoBoundaryKey = boundaryKey === undefined;
+            if (hasNoBoundaryKey)
+                return false;
+            return keyCmp(boundaryKey) > 0;
+        }
+        case 'endAt': {
+            if (isBefore)
+                return true;
+            if (isAfter)
+                return false;
+            const boundaryKey = b.key;
+            const hasNoBoundaryKey = boundaryKey === undefined;
+            return hasNoBoundaryKey || keyCmp(boundaryKey) <= 0;
+        }
+        case 'endBefore': {
+            if (isBefore)
+                return true;
+            if (isAfter)
+                return false;
+            const boundaryKey = b.key;
+            const hasNoBoundaryKey = boundaryKey === undefined;
+            if (hasNoBoundaryKey)
+                return false;
+            return keyCmp(boundaryKey) < 0;
+        }
+        case 'equalTo': {
+            if (differsFromBound)
+                return false;
+            const boundaryKey = b.key;
+            const hasNoBoundaryKey = boundaryKey === undefined;
+            return hasNoBoundaryKey || keyCmp(boundaryKey) === 0;
+        }
+    }
+}
+//# sourceMappingURL=query-projection.js.map

package/dist/database/internal/query-projection.js.map

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

package/dist/database/internal.d.ts

@@ -1,3 +1,5 @@
 export { DisconnectOperationQueue, type DisconnectOperation, } from './disconnect-operation-queue.js';
 export { queryIdentifier } from './query-shape.js';
+export { executeQuery } from './internal/query-projection.js';
+export { canonicalizeDatabaseUrl } from './sandbox/backend-for.js';
 //# sourceMappingURL=internal.d.ts.map

package/dist/database/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/database/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,mBAAmB,GACzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/database/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,mBAAmB,GACzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/database/internal.js

@@ -1,3 +1,5 @@
 export { DisconnectOperationQueue, } from './disconnect-operation-queue.js';
 export { queryIdentifier } from './query-shape.js';
+export { executeQuery } from './internal/query-projection.js';
+export { canonicalizeDatabaseUrl } from './sandbox/backend-for.js';
 //# sourceMappingURL=internal.js.map

package/dist/database/internal.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/database/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAEzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/database/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAEzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/database/listeners.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../src/database/listeners.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAmDrG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,EAChC,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAyHD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED,KAAK,UAAU,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC;AAgJpF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CACjB,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,EAChC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GACtC,IAAI,CASN"}
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../src/database/listeners.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAsErG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,EAChC,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CASb;AAsMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,EAClE,uBAAuB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,aAAa,EAClE,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAEb;AAED,KAAK,UAAU,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC;AA6JpF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CACjB,CAAC,EAAE,iBAAiB,GAAG,KAAK,EAC5B,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,EAChC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GACtC,IAAI,CASN"}

package/dist/database/listeners.js

@@ -1,6 +1,10 @@
+import { sdkActivity } from '../sandbox/internal/sdk-activity.js';
+import { beginDatabaseActivity } from './sdk-activity.js';
 import { ListenerRegistry } from './listener-registry.js';
+import { jsonValuesEqual } from './sandbox/data-tree.js';
 import { authFor, targetOf } from './routing.js';
 import { isDefaultQuerySpec, isQuery, queryIdentifier } from './query-shape.js';
+import { executeQuery } from './internal/query-projection.js';
 import { child } from './references.js';
 import { buildSandboxQuerySnap, buildSandboxSnapFromRaw } from './snapshots.js';
 // ─── Listeners (Tier 2) ──────────────────────────────────────────────
@@ -42,6 +46,24 @@ function subscribeWithLiveAuth(target, subscribe, onTerminal) {
     release = target.kind === 'sandbox-live' ? target.own?.(stop) : undefined;
     return stop;
 }
+/**
+ * The attribution a listen call carries, or `undefined` when it carries none.
+ * The backend takes both inputs as one argument.
+ */
+function attributionOf(options) {
+    if (options === undefined)
+        return undefined;
+    if (options.owner === undefined && options.owners === undefined)
+        return undefined;
+    return { owner: options.owner, owners: options.owners };
+}
+/**
+ * The listen options a recursive `onlyOnce` subscribe should keep: the
+ * attribution, never `onlyOnce` itself, which the outer call already honored.
+ */
+function ownerOnlyOptions(options) {
+    return attributionOf(options);
+}
 function queryScope(r) {
     return queryIdentifier(r._spec);
 }
@@ -63,19 +85,81 @@ function queryScope(r) {
  * one, the sandbox preserves its legacy synchronous throw.
  */
 export function onValue(r, cb, cancelCallbackOrOptions, options) {
-    return onValueInternal(r, cb, cancelCallbackOrOptions, options, cb);
+    const listenOptions = typeof cancelCallbackOrOptions === 'function' ? options : cancelCallbackOrOptions;
+    const activity = beginDatabaseActivity(r, 'onValue', 'subscription', attributionOf(listenOptions));
+    // onlyOnce may detach before invoking a captured initial callback.
+    const lifecycle = listenOptions?.onlyOnce ? { ...activity, close: () => queueMicrotask(() => activity.close()) } : activity;
+    const next = (snap) => { activity.delivered(snap); cb(snap); };
+    try {
+        return sdkActivity.registering(activity, () => onValueInternal(r, next, cancelCallbackOrOptions, options, cb, lifecycle));
+    }
+    catch (error) {
+        activity.fail();
+        throw error;
+    }
 }
-function onValueInternal(r, cb, cancelCallbackOrOptions, options, registryCallback) {
-    const cancelCallback = typeof cancelCallbackOrOptions === 'function'
-        ? cancelCallbackOrOptions
-        : undefined;
-    const listenOptions = typeof cancelCallbackOrOptions === 'function'
-        ? options
-        : cancelCallbackOrOptions;
+function observeConnectionMetadata(query, callback, registryCallback, activity) {
+    const reference = query.ref;
+    const target = targetOf(reference);
+    const isMetadataRoot = reference._path === '/.info';
+    const scope = queryScope(query);
+    const hasConstraints = !isDefaultQuerySpec(query._spec);
+    let stopped = false;
+    let stopObserving = () => { };
+    let release;
+    let previousRows;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        stopObserving();
+        release?.();
+        listenerRegistry.removeExact(target, reference._path, 'value', registryCallback, registration, scope);
+        activity.close();
+    };
+    const registration = { unsubscribe: stop };
+    listenerRegistry.add(target, reference._path, 'value', registryCallback, registration, scope);
+    const hasAppLifetime = target.kind === 'sandbox-live';
+    if (hasAppLifetime)
+        release = target.own?.(stop);
+    stopObserving = target.connection.observeConnection((connected) => {
+        if (stopped)
+            return;
+        const value = isMetadataRoot ? { connected, serverTimeOffset: 0 } : connected;
+        const filtersChildren = isMetadataRoot && hasConstraints;
+        let snapshot;
+        if (filtersChildren) {
+            const rows = executeQuery(value, query._spec);
+            const isUnchangedSelection = jsonValuesEqual(previousRows, rows);
+            if (isUnchangedSelection)
+                return;
+            previousRows = rows;
+            snapshot = buildSandboxQuerySnap(target, reference, rows);
+        }
+        else {
+            snapshot = buildSandboxSnapFromRaw(target, reference, value);
+        }
+        try {
+            callback(snapshot);
+        }
+        catch {
+            // Match ordinary RTDB listener isolation.
+        }
+    });
+    if (stopped)
+        stopObserving();
+    return stop;
+}
+function onValueInternal(r, cb, cancelCallbackOrOptions, options, registryCallback, activity) {
+    const hasCancelCallback = typeof cancelCallbackOrOptions === 'function';
+    const cancelCallback = hasCancelCallback ? cancelCallbackOrOptions : undefined;
+    const reportsCancel = cancelCallback !== undefined;
+    const listenOptions = hasCancelCallback ? options : cancelCallbackOrOptions;
     // `onlyOnce` (DB-B12): wrap the callback so it unsubscribes itself
     // after the first fire. The unsub is filled in once the real
     // subscription is created below.
-    if (listenOptions?.onlyOnce) {
+    const isOnce = listenOptions?.onlyOnce === true;
+    if (isOnce) {
         let unsub = null;
         let fired = false;
         const onceCb = (snap) => {
@@ -85,24 +169,37 @@ function onValueInternal(r, cb, cancelCallbackOrOptions, options, registryCallba
             // `unsub` may not be assigned yet if the initial fire is
             // synchronous (the backend fires during subscribe, before
             // `onValue` returns). The post-subscribe check below covers it.
-            if (unsub)
-                unsub();
+            const currentUnsubscribe = unsub;
+            const hasUnsubscribe = currentUnsubscribe !== null;
+            if (hasUnsubscribe)
+                currentUnsubscribe();
             cb(snap);
         };
-        unsub = onValueInternal(r, onceCb, cancelCallback, undefined, registryCallback);
+        unsub = onValueInternal(r, onceCb, cancelCallback, ownerOnlyOptions(listenOptions), registryCallback, activity);
         // Synchronous initial fire: `onceCb` ran before `unsub` was set, so
         // remove the now-stale listener here.
-        if (fired)
+        if (fired) {
             unsub();
-        return fired ? () => { } : unsub;
+            return () => { };
+        }
+        return unsub;
     }
+    const reference = r.ref;
+    const isConnectionValue = reference._path === '/.info/connected';
+    const isMetadataRoot = reference._path === '/.info';
+    const hasDefaultQuery = isDefaultQuerySpec(r._spec);
+    const observesConnection = isMetadataRoot || (hasDefaultQuery && isConnectionValue);
+    if (observesConnection)
+        return observeConnectionMetadata(r, cb, registryCallback, activity);
     // Query branch — fire only when the windowed result changes.
     // Locked by oracle observation `rtdb-modular-onvalue-with-query.json`:
     // a write OUTSIDE the window does NOT re-fire the listener; a write
     // INSIDE or one that displaces a member DOES.
-    if (isQuery(r)) {
+    const isQueryTarget = isQuery(r);
+    if (isQueryTarget) {
         const q = r;
         const target = targetOf(q.ref);
+        const isAdmin = target.admin === true;
         const scope = queryScope(q);
         const deliver = (raw) => {
             const rows = raw.rows ?? [];
@@ -120,22 +217,30 @@ function onValueInternal(r, cb, cancelCallbackOrOptions, options, registryCallba
         // controls, so a page's `onValue` stays on the rule-gated path below.
         let registration;
         const unregister = () => {
-            if (registration) {
-                listenerRegistry.removeExact(target, q.ref._path, 'value', registryCallback, registration, scope);
+            activity.close();
+            const currentRegistration = registration;
+            const hasRegistration = currentRegistration !== undefined;
+            if (hasRegistration) {
+                listenerRegistry.removeExact(target, q.ref._path, 'value', registryCallback, currentRegistration, scope);
             }
         };
-        const subscribed = target.admin
-            ? target.backend.adminOnValue(q.ref._path, deliver, q._spec)
-            : subscribeWithLiveAuth(target, (auth, onCanceled) => target.backend.onValue(auth, q.ref._path, deliver, q._spec, cancelCallback, onCanceled), unregister);
-        const unsub = target.admin
-            ? () => { unregister(); subscribed(); }
-            : subscribed;
+        let subscribed;
+        if (isAdmin) {
+            subscribed = target.backend.adminOnValue(q.ref._path, deliver, q._spec);
+        }
+        else {
+            subscribed = subscribeWithLiveAuth(target, (auth, onCanceled) => target.backend.onValue(auth, q.ref._path, deliver, q._spec, reportsCancel ? (error) => { activity.fail(); cancelCallback(error); } : undefined, () => { activity.fail(); onCanceled(); }, attributionOf(listenOptions)), unregister);
+        }
+        let unsub = subscribed;
+        if (isAdmin)
+            unsub = () => { unregister(); subscribed(); };
         registration = { unsubscribe: unsub };
         listenerRegistry.add(target, q.ref._path, 'value', registryCallback, registration, scope);
         return unsub;
     }
-    const ref0 = r;
+    const ref0 = reference;
     const target = targetOf(ref0);
+    const isAdmin = target.admin === true;
     const wrapper = (raw) => {
         const snap = buildSandboxSnapFromRaw(target, ref0, raw.val);
         try {
@@ -148,15 +253,22 @@ function onValueInternal(r, cb, cancelCallbackOrOptions, options, registryCallba
     };
     let registration;
     const unregister = () => {
-        if (registration)
-            listenerRegistry.removeExact(target, ref0._path, 'value', registryCallback, registration);
+        activity.close();
+        const currentRegistration = registration;
+        const hasRegistration = currentRegistration !== undefined;
+        if (hasRegistration)
+            listenerRegistry.removeExact(target, ref0._path, 'value', registryCallback, currentRegistration);
     };
-    const subscribed = target.admin
-        ? target.backend.adminOnValue(ref0._path, wrapper)
-        : subscribeWithLiveAuth(target, (auth, onCanceled) => target.backend.onValue(auth, ref0._path, wrapper, undefined, cancelCallback, onCanceled), unregister);
-    const unsub = target.admin
-        ? () => { unregister(); subscribed(); }
-        : subscribed;
+    let subscribed;
+    if (isAdmin) {
+        subscribed = target.backend.adminOnValue(ref0._path, wrapper);
+    }
+    else {
+        subscribed = subscribeWithLiveAuth(target, (auth, onCanceled) => target.backend.onValue(auth, ref0._path, wrapper, undefined, reportsCancel ? (error) => { activity.fail(); cancelCallback(error); } : undefined, () => { activity.fail(); onCanceled(); }, attributionOf(listenOptions)), unregister);
+    }
+    let unsub = subscribed;
+    if (isAdmin)
+        unsub = () => { unregister(); subscribed(); };
     registration = { unsubscribe: unsub };
     listenerRegistry.add(target, ref0._path, 'value', registryCallback, registration);
     return unsub;
@@ -233,6 +345,21 @@ export function onChildMoved(r, cb, cancelCallbackOrOptions, options) {
     return subscribeChild(r, 'child_moved', cb, cancelCallbackOrOptions, options);
 }
 function subscribeChild(r, event, cb, cancelCallbackOrOptions, options) {
+    const registryCallback = cb;
+    const requestedOptions = typeof cancelCallbackOrOptions === 'function' ? options : cancelCallbackOrOptions;
+    const method = { child_added: 'onChildAdded', child_changed: 'onChildChanged', child_removed: 'onChildRemoved', child_moved: 'onChildMoved' }[event];
+    const activity = beginDatabaseActivity(r, method, 'subscription', attributionOf(requestedOptions));
+    const lifecycle = requestedOptions?.onlyOnce ? { ...activity, close: () => queueMicrotask(() => activity.close()) } : activity;
+    cb = (snap, previous) => { activity.delivered(snap); registryCallback(snap, previous); };
+    const attach = (next, cancel) => {
+        try {
+            return sdkActivity.registering(activity, () => onChildEvent(r, event, next, cancel ? (error) => { activity.fail(); cancel(error); } : undefined, registryCallback, lifecycle));
+        }
+        catch (error) {
+            activity.fail();
+            throw error;
+        }
+    };
     const cancelCallback = typeof cancelCallbackOrOptions === 'function'
         ? cancelCallbackOrOptions
         : undefined;
@@ -240,7 +367,7 @@ function subscribeChild(r, event, cb, cancelCallbackOrOptions, options) {
         ? options
         : cancelCallbackOrOptions;
     if (!listenOptions?.onlyOnce)
-        return onChildEvent(r, event, cb, cancelCallback);
+        return attach(cb, cancelCallback);
     if (event === 'child_added') {
         let attaching = true;
         const initial = [];
@@ -257,7 +384,7 @@ function subscribeChild(r, event, cb, cancelCallbackOrOptions, options) {
             unsubscribe();
             cb(snap, previousChildName);
         };
-        unsubscribe = onChildEvent(r, event, wrapped, cancelCallback, cb);
+        unsubscribe = attach(wrapped, cancelCallback);
         attaching = false;
         if (initial.length > 0) {
             stopped = true;
@@ -285,7 +412,7 @@ function subscribeChild(r, event, cb, cancelCallbackOrOptions, options) {
         unsubscribe?.();
         cb(snap, event === 'child_removed' ? null : previousChildName);
     };
-    unsubscribe = onChildEvent(r, event, once, cancelCallback, cb);
+    unsubscribe = attach(once, cancelCallback);
     // Initial child_added delivery is synchronous, before `unsubscribe` is
     // assigned. Remove the registration after attachment in that case.
     if (fired)
@@ -309,7 +436,7 @@ function cancelSubscriptions(target, path, event, scope) {
  * `child_removed`, an in-window value change fires `child_changed`. (Note
  * `child_moved` fires when the query's active ordered value changes.)
  */
-function onChildEvent(r, event, cb, cancelCallback, registryCallback = cb) {
+function onChildEvent(r, event, cb, cancelCallback, registryCallback, activity) {
     // Unwrap a Query into its base ref + spec; a plain ref has no spec.
     const isQ = isQuery(r);
     const baseRef = isQ ? r.ref : r;
@@ -332,11 +459,12 @@ function onChildEvent(r, event, cb, cancelCallback, registryCallback = cb) {
     };
     let registration;
     const unregister = () => {
+        activity.close();
         if (registration) {
             listenerRegistry.removeExact(target, baseRef._path, event, registryCallback, registration, scope);
         }
     };
-    const unsub = subscribeWithLiveAuth(target, (auth, onCanceled) => target.backend.onChild(auth, event, baseRef._path, wrapper, spec, cancelCallback, onCanceled), unregister);
+    const unsub = subscribeWithLiveAuth(target, (auth, onCanceled) => target.backend.onChild(auth, event, baseRef._path, wrapper, spec, cancelCallback, () => { activity.fail(); onCanceled(); }), unregister);
     registration = { unsubscribe: unsub };
     listenerRegistry.add(target, baseRef._path, event, registryCallback, registration, scope);
     return unsub;