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

package/src/database/internal/query-projection.ts

@@ -0,0 +1,333 @@
+import type { JsonValue } from '../sandbox/data-tree.js';
+
+/** Ordering selector. Stored as a discriminated union so the executor
+ *  can switch on the kind without re-parsing. */
+export type OrderBy =
+  | { kind: 'child'; path: string }
+  | { kind: 'key' }
+  | { kind: 'priority' }
+  | { kind: 'value' };
+
+export type Priority = string | number | null;
+
+/** Cursor or filter bound. `startAt`/`endAt` are inclusive; the
+ *  `*Exclusive` variants drop the boundary value. `equalTo` collapses
+ *  start + end onto the same value (and is sugar for `startAt(v) +
+ *  endAt(v)` per the SDK docs). */
+export type Bound =
+  | { kind: 'startAt'; value: JsonValue; key?: string }
+  | { kind: 'startAfter'; value: JsonValue; key?: string }
+  | { kind: 'endAt'; value: JsonValue; key?: string }
+  | { kind: 'endBefore'; value: JsonValue; key?: string }
+  | { kind: 'equalTo'; value: JsonValue; key?: string };
+
+/** Window-size constraint. Mutually exclusive with each other (prod
+ *  rejects setting both — we don't reject here but the executor
+ *  prioritises the last one set, matching `firebase/database`). */
+export type LimitKind = 'limitToFirst' | 'limitToLast';
+
+/**
+ * A {@link Query} is a ref + a chain of constraints. The chain is
+ * order-independent in terms of declared shape — the executor groups
+ * constraints into {order, bounds, limit} during apply.
+ */
+export interface QuerySpec {
+  /** Active ordering. `null` means Firebase's default priority index. */
+  orderBy: OrderBy | null;
+  /** Range/equality filters. Multiple bounds compose. */
+  bounds: Bound[];
+  /** Optional limit. Last-wins if set more than once. */
+  limit: { kind: LimitKind; n: number } | null;
+}
+
+/**
+ * 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: JsonValue, b: JsonValue): number {
+  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: JsonValue): number {
+  // 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: string): number | null {
+  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: string, b: string): number {
+  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: OrderBy | null,
+  key: string,
+  value: JsonValue,
+  priority: Priority = null,
+): JsonValue {
+  const o = spec ?? { kind: 'priority' as const };
+  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: JsonValue = value;
+      for (const s of segs) {
+        const hasNoDescendant = cur === null || typeof cur !== 'object' || Array.isArray(cur);
+        if (hasNoDescendant) return null;
+        cur = (cur as Record<string, JsonValue>)[s] ?? null;
+      }
+      return cur;
+    }
+  }
+}
+
+/** Result row — kept minimal so the snap-builder can render it cheaply. */
+export interface QueryRow {
+  key: string;
+  value: JsonValue;
+  priority: Priority;
+}
+
+/**
+ * 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: JsonValue,
+  spec: QuerySpec,
+  priorityForKey: (key: string) => Priority = () => null,
+): QueryRow[] {
+  // 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 as Record<string, JsonValue>;
+  // Enumerate immediate children only — RTDB's query model is one-level.
+  let rows: QueryRow[] = 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: Bound, row: QueryRow, orderBy: OrderBy | null): boolean {
+  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: number;
+  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: string): number => 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;
+    }
+  }
+}

package/src/database/internal.ts

@@ -3,3 +3,5 @@ export {
   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';

package/src/database/listeners.ts

@@ -1,10 +1,13 @@
+import { sdkActivity, type SdkActivityHandle } from '../sandbox/internal/sdk-activity.js';
+import { beginDatabaseActivity } from './sdk-activity.js';
 import type { AuthState } from 'pyric/sandbox';
 import { ListenerRegistry, type ListenerRegistration } from './listener-registry.js';
-import type { JsonValue } from './sandbox/data-tree.js';
+import { jsonValuesEqual, type JsonValue } from './sandbox/data-tree.js';
 import { authFor, targetOf, type Target } from './routing.js';
 import { isDefaultQuerySpec, isQuery, queryIdentifier } from './query-shape.js';
-import type { QueryRow } from './sandbox/query.js';
+import { executeQuery, type QueryRow } from './internal/query-projection.js';
 import type { DataSnapshot, DatabaseReference, ListenOptions, Query, Unsubscribe } from './types.js';
+import type { ListenerAttribution } from '../sandbox/attribution/listener-owners.js';
 import { child } from './references.js';
 import { buildSandboxQuerySnap, buildSandboxSnapFromRaw } from './snapshots.js';
 
@@ -51,6 +54,24 @@ function subscribeWithLiveAuth(
   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: ListenOptions | undefined): ListenerAttribution | undefined {
+  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: ListenOptions | undefined): ListenOptions | undefined {
+  return attributionOf(options);
+}
+
 function queryScope(r: DatabaseReference | Query): string {
   return queryIdentifier(r._spec);
 }
@@ -78,7 +99,65 @@ export function onValue(
   cancelCallbackOrOptions?: ((error: Error) => void) | ListenOptions,
   options?: ListenOptions,
 ): Unsubscribe {
-  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: DataSnapshot): void => { activity.delivered(snap); cb(snap); };
+  try {
+    return sdkActivity.registering(activity, () => onValueInternal(r, next, cancelCallbackOrOptions, options, cb, lifecycle));
+  } catch (error) { activity.fail(); throw error; }
+}
+
+function observeConnectionMetadata(
+  query: Query,
+  callback: (snapshot: DataSnapshot) => void,
+  registryCallback: (snapshot: DataSnapshot) => void,
+  activity: SdkActivityHandle,
+): Unsubscribe {
+  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: Unsubscribe = () => {};
+  let release: Unsubscribe | undefined;
+  let previousRows: QueryRow[] | undefined;
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    stopObserving();
+    release?.();
+    listenerRegistry.removeExact(target, reference._path, 'value', registryCallback, registration, scope);
+    activity.close();
+  };
+  const registration: ListenerRegistration = { 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: DataSnapshot;
+    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(
@@ -87,17 +166,17 @@ function onValueInternal(
   cancelCallbackOrOptions: ((error: Error) => void) | ListenOptions | undefined,
   options: ListenOptions | undefined,
   registryCallback: (snap: DataSnapshot) => void,
+  activity: SdkActivityHandle,
 ): Unsubscribe {
-  const cancelCallback = typeof cancelCallbackOrOptions === 'function'
-    ? cancelCallbackOrOptions
-    : undefined;
-  const listenOptions = typeof cancelCallbackOrOptions === 'function'
-    ? options
-    : cancelCallbackOrOptions;
+  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: Unsubscribe | null = null;
     let fired = false;
     const onceCb = (snap: DataSnapshot): void => {
@@ -106,22 +185,35 @@ function onValueInternal(
       // `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) unsub();
-    return fired ? () => {} : unsub;
+    if (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 as object)) {
-    const q = r as Query;
-    const target = targetOf(q.ref as unknown as object);
+  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: { val: JsonValue; key: string | null; rows?: QueryRow[] }): void => {
       const rows = raw.rows ?? [];
@@ -138,33 +230,40 @@ function onValueInternal(
     // controls, so a page's `onValue` stays on the rule-gated path below.
     let registration: ListenerRegistration | undefined;
     const unregister = (): void => {
-      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(
+    let subscribed: Unsubscribe;
+    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,
-          cancelCallback,
-          onCanceled,
+          reportsCancel ? (error) => { activity.fail(); cancelCallback(error); } : undefined,
+          () => { activity.fail(); onCanceled(); },
+          attributionOf(listenOptions),
         ),
         unregister,
       );
-    const unsub = target.admin
-      ? () => { unregister(); subscribed(); }
-      : subscribed;
+    }
+    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 as DatabaseReference;
-  const target = targetOf(ref0 as unknown as object);
+  const ref0 = reference;
+  const target = targetOf(ref0);
+  const isAdmin = target.admin === true;
   const wrapper = (raw: { val: JsonValue; key: string | null }): void => {
     const snap = buildSandboxSnapFromRaw(target, ref0, raw.val);
     try {
@@ -176,25 +275,31 @@ function onValueInternal(
   };
   let registration: ListenerRegistration | undefined;
   const unregister = (): void => {
-    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(
+  let subscribed: Unsubscribe;
+  if (isAdmin) {
+    subscribed = target.backend.adminOnValue(ref0._path, wrapper);
+  } else {
+    subscribed = subscribeWithLiveAuth(
       target,
       (auth, onCanceled) => target.backend.onValue(
         auth,
         ref0._path,
         wrapper,
         undefined,
-        cancelCallback,
-        onCanceled,
+        reportsCancel ? (error) => { activity.fail(); cancelCallback(error); } : undefined,
+        () => { activity.fail(); onCanceled(); },
+        attributionOf(listenOptions),
       ),
       unregister,
     );
-  const unsub = target.admin
-    ? () => { unregister(); subscribed(); }
-    : subscribed;
+  }
+  let unsub = subscribed;
+  if (isAdmin) unsub = () => { unregister(); subscribed(); };
   registration = { unsubscribe: unsub };
   listenerRegistry.add(target, ref0._path, 'value', registryCallback, registration);
   return unsub;
@@ -304,13 +409,24 @@ function subscribeChild(
   cancelCallbackOrOptions?: ((error: Error) => void) | ListenOptions,
   options?: ListenOptions,
 ): Unsubscribe {
+  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: typeof cb, cancel: ((error: Error) => void) | undefined): Unsubscribe => {
+    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;
   const listenOptions = typeof cancelCallbackOrOptions === 'function'
     ? options
     : cancelCallbackOrOptions;
-  if (!listenOptions?.onlyOnce) return onChildEvent(r, event, cb, cancelCallback);
+  if (!listenOptions?.onlyOnce) return attach(cb, cancelCallback);
 
   if (event === 'child_added') {
     let attaching = true;
@@ -327,7 +443,7 @@ function subscribeChild(
       unsubscribe();
       cb(snap, previousChildName);
     };
-    unsubscribe = onChildEvent(r, event, wrapped, cancelCallback, cb);
+    unsubscribe = attach(wrapped, cancelCallback);
     attaching = false;
     if (initial.length > 0) {
       stopped = true;
@@ -354,7 +470,7 @@ function subscribeChild(
     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) unsubscribe();
@@ -389,8 +505,9 @@ function onChildEvent(
   r: DatabaseReference | Query,
   event: ChildEvent,
   cb: (snap: DataSnapshot, previousChildName: string | null) => void,
-  cancelCallback?: (error: Error) => void,
-  registryCallback = cb,
+  cancelCallback: ((error: Error) => void) | undefined,
+  registryCallback: typeof cb,
+  activity: SdkActivityHandle,
 ): Unsubscribe {
   // Unwrap a Query into its base ref + spec; a plain ref has no spec.
   const isQ = isQuery(r as object);
@@ -417,6 +534,7 @@ function onChildEvent(
   };
   let registration: ListenerRegistration | undefined;
   const unregister = (): void => {
+    activity.close();
     if (registration) {
       listenerRegistry.removeExact(target, baseRef._path, event, registryCallback, registration, scope);
     }
@@ -430,7 +548,7 @@ function onChildEvent(
       wrapper,
       spec,
       cancelCallback,
-      onCanceled,
+      () => { activity.fail(); onCanceled(); },
     ),
     unregister,
   );