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

package/src/database/sandbox/transactions.ts

@@ -60,50 +60,18 @@ export class Transactions {
       return { committed: false, val: current, key };
     }
 
-    const now = Date.now();
+    const now = this.state.clock.now();
     const resolved = normalizeWrite(
       resolveSentinels(proposed, now, current) as JsonValue,
       path === '/' ? '' : path,
     );
-    if (applyLocally) {
-      const priorRoot = this.state.tree.snapshot();
-      const priorPriorities = Object.fromEntries(this.state.priorities.entries());
-      const currentPriority = this.state.priorities.get(path);
-      const childPriors = this.children.snapshotParents();
-      this.state.tree.write(path, resolved);
-      this.state.priorities.replace(path, currentPriority);
-      this.values.fanOut([path]);
-      this.children.fanOut(childPriors);
-      const at = Date.now();
-      const evaluation = this.state.rules.evaluate('write', path === '/' ? '/' : path, {
-        auth, mockData: priorRoot as Record<string, unknown>, newData: resolved,
-      });
-      if (evaluation.check !== 'allow') {
-        this.state.events.operation(auth, 'transaction', path, denyResultFor(evaluation.check), evaluation, {
-          at, durationMs: Date.now() - at, origin: 'transaction',
-          request: { data: proposed, resourceData: proposed },
-          resourceBefore: { data: current, exists: current !== null },
-          resourceAfter: { data: resolved, exists: resolved !== null },
-          groupId, groupKind: 'transaction',
-        });
-        const rollbackChildPriors = this.children.snapshotParents();
-        this.state.tree.restore(priorRoot);
-        this.state.priorities.restore(priorPriorities);
-        this.values.fanOut([path]);
-        this.children.fanOut(rollbackChildPriors);
-        throw transactionPermissionDenied();
-      }
-      this.recordCommit(auth, path, proposed, current, resolved, groupId, now, at, true, evaluation);
-      return { committed: true, val: resolved, key };
-    }
-
-    const at = Date.now();
-    const evaluation = this.state.rules.evaluate('write', path === '/' ? '/' : path, {
+    const at = this.state.clock.now();
+    const evaluation = this.state.rules.evaluate('write', path, {
       auth, mockData: this.state.tree.snapshot() as Record<string, unknown>, newData: resolved,
     });
     if (evaluation.check !== 'allow') {
       this.state.events.operation(auth, 'transaction', path, denyResultFor(evaluation.check), evaluation, {
-        at, durationMs: Date.now() - at, origin: 'transaction',
+        at, durationMs: this.state.clock.now() - at, origin: 'transaction',
         request: { data: proposed, resourceData: proposed },
         resourceBefore: { data: current, exists: current !== null },
         resourceAfter: { data: resolved, exists: resolved !== null },
@@ -111,8 +79,18 @@ export class Transactions {
       });
       throw transactionPermissionDenied();
     }
+    if (applyLocally) {
+      const currentPriority = this.state.priorities.get(path);
+      const childPriors = this.children.snapshotParents();
+      this.state.tree.write(path, resolved);
+      this.state.priorities.replace(path, resolved === null ? null : currentPriority);
+      this.values.fanOut([path]);
+      this.children.fanOut(childPriors);
+      this.recordCommit(auth, path, proposed, current, resolved, groupId, now, at, true, evaluation);
+      return { committed: true, val: resolved, key };
+    }
     this.state.events.operation(auth, 'transaction', path, 'allow', evaluation, {
-      at, durationMs: Date.now() - at, origin: 'transaction',
+      at, durationMs: this.state.clock.now() - at, origin: 'transaction',
       request: { data: proposed, resourceData: proposed },
       resourceBefore: { data: current, exists: current !== null },
       resourceAfter: { data: resolved, exists: resolved !== null },
@@ -121,7 +99,7 @@ export class Transactions {
     const priority = this.state.priorities.get(path);
     const childPriors = this.children.snapshotParents();
     this.state.tree.write(path, resolved);
-    this.state.priorities.replace(path, priority);
+    this.state.priorities.replace(path, resolved === null ? null : priority);
     this.state.mutations.mark(path);
     this.values.fanOut([path]);
     this.children.fanOut(childPriors);
@@ -136,7 +114,7 @@ export class Transactions {
     evaluation: ReturnType<BackendState['rules']['evaluate']>,
   ): void {
     this.state.events.operation(auth, 'transaction', path, 'allow', evaluation, {
-      at, durationMs: Date.now() - at, origin: 'transaction',
+      at, durationMs: this.state.clock.now() - at, origin: 'transaction',
       request: { data: proposed, resourceData: proposed },
       resourceBefore: { data: current, exists: current !== null },
       resourceAfter: { data: resolved, exists: resolved !== null },

package/src/database/sandbox/value-listeners.ts

@@ -1,4 +1,10 @@
 import type { AuthState } from 'pyric/sandbox';
+import type { ListenerOwner } from '../../sandbox/types/events.js';
+import { recordEffectRegions } from '../../sandbox/attribution/effect-regions.js';
+import {
+  listenerAttachOwners,
+  type ListenerAttribution,
+} from '../../sandbox/attribution/listener-owners.js';
 import { jsonValuesEqual, joinPath, pathSegments, type JsonValue } from './data-tree.js';
 import type { BackendState } from './backend-state.js';
 import type { ValueListener, ValueListenerSnapshot } from './listener-types.js';
@@ -38,11 +44,14 @@ export class ValueListeners {
     query?: QuerySpec,
     cancelCallback?: (error: Error) => void,
     onCanceled?: () => void,
+    attribution?: ListenerAttribution,
   ): () => void {
-    const at = Date.now();
+    const at = this.state.clock.now();
     const evaluation = this.state.rules.evaluate('read', path === '/' ? '/' : path, {
+      indexMethod: 'listen',
       auth,
       mockData: this.state.tree.snapshot() as Record<string, unknown>,
+      querySpec: query,
     });
     if (evaluation.check !== 'allow') {
       let requestVal: { query: unknown } | undefined = undefined;
@@ -50,7 +59,7 @@ export class ValueListeners {
         requestVal = { query };
       }
       this.state.events.operation(auth, 'listen', path, denyResultFor(evaluation.check), evaluation, {
-        at, durationMs: Date.now() - at, request: requestVal, origin: 'listener',
+        at, durationMs: this.state.clock.now() - at, request: requestVal, origin: 'listener',
       });
       const rulesObj = {
         engine: 'rtdb' as const,
@@ -79,12 +88,12 @@ export class ValueListeners {
     }
     return this.attach(auth, path, cb, query, {
       origin: 'listener', result: 'allow', evaluation, at,
-    }, cancelCallback, onCanceled);
+    }, cancelCallback, onCanceled, attribution);
   }
 
   adminOnValue(path: string, cb: (snap: ValueListenerSnapshot) => void, query?: QuerySpec): () => void {
     return this.attach(null, path, cb, query, {
-      origin: 'admin', result: 'not-applicable', evaluation: undefined, at: Date.now(),
+      origin: 'admin', result: 'not-applicable', evaluation: undefined, at: this.state.clock.now(),
     });
   }
 
@@ -101,16 +110,22 @@ export class ValueListeners {
     },
     cancelCallback?: (error: Error) => void,
     onCanceled?: () => void,
+    attribution?: ListenerAttribution,
   ): () => void {
     const id = this.state.events.nextListenerId();
+    const attachOwners = listenerAttachOwners(attribution?.owner, attribution?.owners);
     this.state.events.operation(auth, 'listen', path, provenance.result, provenance.evaluation, {
-      at: provenance.at, durationMs: Date.now() - provenance.at,
+      at: provenance.at, durationMs: this.state.clock.now() - provenance.at,
       request: query ? { query } : undefined, origin: provenance.origin,
     });
-    const listener: ValueListener = { id, auth, cb, path, query, cancelCallback, onCanceled };
+    const listener: ValueListener = {
+      id, auth, cb, path, query, cancelCallback, onCanceled, admin: provenance.origin === 'admin', owners: attachOwners,
+    };
     this.state.valueListeners.add(listener);
     this.state.events.listener('attach', listener, auth, {
       event: 'value', result: 'allow', detail: query ? { query } : undefined,
+      ...(query ? { query } : {}),
+      owners: attachOwners,
     });
     if (query) {
       const rows = executeQuery(this.state.tree.read(path), query, this.state.priorities.forChild(path));
@@ -193,19 +208,32 @@ export class ValueListeners {
     return segments.length === 0 ? null : segments[segments.length - 1]!;
   }
 
+  /**
+   * Deliver to a subscribed listener. The callback runs before the delivery
+   * event is emitted so the event can carry the regions the callback touched;
+   * the callback itself sees the same snapshot, in the same order, at the
+   * same moment it always did.
+   */
   private deliver(listener: ValueListener, snapshot: ValueListenerSnapshot, detail: Record<string, unknown>): void {
+    let thrown: unknown;
+    let caught = false;
+    const regions = recordEffectRegions(() => {
+      try {
+        listener.cb(snapshot);
+      } catch (error) {
+        thrown = error;
+        caught = true;
+      }
+    });
     this.state.events.listener('delivery', listener, listener.auth, {
       event: 'value', size: snapshot.rows?.length ?? (snapshot.exists ? 1 : 0),
-      sample: snapshot.val, detail,
+      sample: snapshot.val, detail, owners: ownersFor(regions),
+    });
+    if (!caught) return;
+    this.state.events.listener('errored', listener, listener.auth, {
+      event: 'value', result: 'error',
+      error: { message: thrown instanceof Error ? thrown.message : String(thrown) }, detail,
     });
-    try {
-      listener.cb(snapshot);
-    } catch (error) {
-      this.state.events.listener('errored', listener, listener.auth, {
-        event: 'value', result: 'error',
-        error: { message: error instanceof Error ? error.message : String(error) }, detail,
-      });
-    }
   }
 
   private deliverInitial(
@@ -213,21 +241,36 @@ export class ValueListeners {
     snapshot: ValueListenerSnapshot,
     detail: Record<string, unknown>,
   ): void {
-    try {
-      listener.cb(snapshot);
+    let thrown: unknown;
+    let caught = false;
+    const regions = recordEffectRegions(() => {
+      try {
+        listener.cb(snapshot);
+      } catch (error) {
+        thrown = error;
+        caught = true;
+      }
+    });
+    if (!caught) {
       this.state.events.listener('delivery', listener, listener.auth, {
         event: 'value', size: snapshot.rows?.length ?? (snapshot.exists ? 1 : 0),
-        sample: snapshot.val, detail,
-      });
-    } catch (error) {
-      this.state.events.listener('errored', listener, listener.auth, {
-        event: 'value', result: 'error',
-        error: { message: error instanceof Error ? error.message : String(error) }, detail,
+        sample: snapshot.val, detail, owners: ownersFor(regions),
       });
+      return;
     }
+    this.state.events.listener('errored', listener, listener.auth, {
+      event: 'value', result: 'error',
+      error: { message: thrown instanceof Error ? thrown.message : String(thrown) }, detail,
+    });
   }
 }
 
+/** Wrap one optional owner as the event's owner array, or omit it. */
+export function ownersFor(owner: ListenerOwner | undefined): ListenerOwner[] | undefined {
+  if (owner === undefined) return undefined;
+  return [owner];
+}
+
 function pathsTouch(listenerPath: string, touchedPath: string): boolean {
   if (listenerPath === touchedPath || listenerPath === '/') return true;
   const listenerPrefix = `${listenerPath}/`;

package/src/database/sandbox/write-plane.ts

@@ -33,7 +33,7 @@ export class WritePlane {
     this.state.priorities.clear();
     for (const [path, value] of Object.entries(seed)) {
       this.state.tree.write(path, normalizeWrite(
-        resolveSentinels(value, Date.now()) as JsonValue, path === '/' ? '' : path,
+        resolveSentinels(value, this.state.clock.now()) as JsonValue, path === '/' ? '' : path,
       ));
     }
     this.state.mutations.mark('/');
@@ -74,6 +74,7 @@ export class WritePlane {
   adminGet(path: string): JsonValue {
     const value = this.state.tree.read(path);
     this.state.events.operation(null, 'get', path, 'not-applicable', undefined, {
+      at: this.state.clock.now(),
       origin: 'admin', resourceBefore: { data: value, exists: value !== null },
     });
     return value;
@@ -82,6 +83,7 @@ export class WritePlane {
   adminGetQuery(path: string, spec: QuerySpec): QueryRow[] {
     const rows = executeQuery(this.state.tree.read(path), spec, this.state.priorities.forChild(path));
     this.state.events.operation(null, 'get', path, 'not-applicable', undefined, {
+      at: this.state.clock.now(),
       origin: 'admin', request: { query: spec },
       resourceBefore: { data: rowsToVal(rows), exists: rows.length > 0 },
     });
@@ -99,13 +101,14 @@ export class WritePlane {
     prioritySupplied = true,
   ): void {
     validatePriority(priority);
-    const now = Date.now();
+    const now = this.state.clock.now();
     const before = this.state.tree.read(path);
     const resolved = normalizeWrite(
       resolveSentinels(value, now, before) as JsonValue, path === '/' ? '' : path,
     );
     const method = resolved === null ? 'remove' : 'set';
     this.state.events.operation(null, method, path, 'not-applicable', undefined, {
+      at: now,
       origin: 'admin', request: { data: value, resourceData: value },
       resourceBefore: { data: before, exists: before !== null },
       resourceAfter: { data: resolved, exists: resolved !== null },
@@ -129,11 +132,12 @@ export class WritePlane {
   }
 
   adminUpdate(path: string, patch: Record<string, JsonValue>): void {
-    const now = Date.now();
+    const now = this.state.clock.now();
     const before = this.state.tree.read(path);
     const expanded = this.resolvePatch(path, patch, now);
     const multiPath = Object.keys(patch).some((key) => key.includes('/'));
     this.state.events.operation(null, 'update', path, 'not-applicable', undefined, {
+      at: now,
       origin: 'admin', request: { data: patch, resourceData: patch },
       resourceBefore: { data: before, exists: before !== null },
       detail: multiPath
@@ -164,35 +168,35 @@ export class WritePlane {
   }
 
   get(auth: AuthState, path: string): JsonValue {
-    const at = Date.now();
+    const at = this.state.clock.now();
     const value = this.state.tree.read(path);
     const evaluation = this.readEvaluation(auth, path);
     if (evaluation.check !== 'allow') {
       this.state.events.operation(auth, 'get', path, denyResultFor(evaluation.check), evaluation, {
-        at, durationMs: Date.now() - at,
+        at, durationMs: this.state.clock.now() - at,
         resourceBefore: { data: value, exists: value !== null },
       });
       throw permissionDenied();
     }
     this.state.events.operation(auth, 'get', path, 'allow', evaluation, {
-      at, durationMs: Date.now() - at,
+      at, durationMs: this.state.clock.now() - at,
       resourceBefore: { data: value, exists: value !== null },
     });
     return this.state.tree.read(path);
   }
 
   getQuery(auth: AuthState, path: string, spec: QuerySpec): QueryRow[] {
-    const at = Date.now();
-    const evaluation = this.readEvaluation(auth, path);
+    const at = this.state.clock.now();
+    const evaluation = this.readEvaluation(auth, path, spec);
     if (evaluation.check !== 'allow') {
       this.state.events.operation(auth, 'get', path, denyResultFor(evaluation.check), evaluation, {
-        at, durationMs: Date.now() - at, request: { query: spec },
+        at, durationMs: this.state.clock.now() - at, request: { query: spec },
       });
       throw permissionDenied();
     }
     const rows = executeQuery(this.state.tree.read(path), spec, this.state.priorities.forChild(path));
     this.state.events.operation(auth, 'get', path, 'allow', evaluation, {
-      at, durationMs: Date.now() - at, request: { query: spec },
+      at, durationMs: this.state.clock.now() - at, request: { query: spec },
       resourceBefore: { data: rowsToVal(rows), exists: rows.length > 0 },
     });
     return rows;
@@ -217,7 +221,7 @@ export class WritePlane {
 
   validateSet(auth: AuthState, path: string, value: unknown): void {
     const resolved = normalizeWrite(
-      resolveSentinels(value, Date.now(), this.state.tree.read(path)) as JsonValue,
+      resolveSentinels(value, this.state.clock.now(), this.state.tree.read(path)) as JsonValue,
       path === '/' ? '' : path,
     );
     if (this.writeEvaluation(auth, path, resolved).check !== 'allow') throw permissionDenied();
@@ -228,7 +232,7 @@ export class WritePlane {
     const updates = Object.entries(patch).map(([key, value]) => {
       const absolute = joinPath([...pathSegments(path), ...pathSegments(key)]);
       return { path: absolute, value: normalizeWrite(
-        resolveSentinels(value, Date.now(), this.state.tree.read(absolute)) as JsonValue, absolute,
+        resolveSentinels(value, this.state.clock.now(), this.state.tree.read(absolute)) as JsonValue, absolute,
       ) };
     });
     for (const update of updates) {
@@ -239,7 +243,7 @@ export class WritePlane {
   }
 
   update(auth: AuthState, path: string, patch: Record<string, JsonValue>): void {
-    const now = Date.now();
+    const now = this.state.clock.now();
     const expanded = this.resolvePatch(path, patch, now);
     const multiPath = Object.keys(patch).some((key) => key.includes('/'));
     const mockData = this.state.tree.snapshot() as Record<string, unknown>;
@@ -249,13 +253,13 @@ export class WritePlane {
     ]));
     const groupId = this.state.events.nextGroupId('update');
     for (const update of updates) {
-      const at = Date.now();
+      const at = this.state.clock.now();
       const before = this.state.tree.read(update.path);
       const evaluation = this.state.rules.evaluate('write', update.path, {
         auth, mockData, newData: update.value, updates,
       });
       const fields = {
-        at, durationMs: Date.now() - at, origin: 'batch' as const,
+        at, durationMs: this.state.clock.now() - at, origin: 'batch' as const,
         request: { data: update.value, resourceData: update.value },
         resourceBefore: { data: before, exists: before !== null },
         resourceAfter: { data: update.value, exists: update.value !== null },
@@ -297,17 +301,17 @@ export class WritePlane {
     auth: AuthState, path: string, value: JsonValue,
     op: 'set' | 'remove', priority: Priority, prioritySupplied: boolean,
   ): void {
-    const now = Date.now();
+    const now = this.state.clock.now();
     const resolved = normalizeWrite(
       resolveSentinels(value, now, this.state.tree.read(path)) as JsonValue,
       path === '/' ? '' : path,
     );
     const before = this.state.tree.read(path);
     const priorNodePriority = this.state.priorities.get(path);
-    const at = Date.now();
+    const at = this.state.clock.now();
     const evaluation = this.writeEvaluation(auth, path, resolved);
     const common = {
-      at, durationMs: Date.now() - at,
+      at, durationMs: this.state.clock.now() - at,
       request: { data: value, resourceData: value },
       resourceBefore: { data: before, exists: before !== null },
       resourceAfter: { data: resolved, exists: resolved !== null },
@@ -355,8 +359,9 @@ export class WritePlane {
     const mockData = this.state.tree.snapshot() as Record<string, unknown>;
     const deniedValues: ValueListener[] = [];
     for (const listener of [...this.state.valueListeners]) {
+      if (listener.admin) continue;
       const evaluation = this.state.rules.evaluate('read', listener.path, {
-        auth: listener.auth, mockData,
+        auth: listener.auth, mockData, querySpec: listener.query,
       });
       if (evaluation.check === 'allow') continue;
       this.state.valueListeners.delete(listener);
@@ -382,7 +387,7 @@ export class WritePlane {
     const deniedChildren: ChildListener[] = [];
     for (const listener of [...this.state.childListeners]) {
       const evaluation = this.state.rules.evaluate('read', listener.path, {
-        auth: listener.auth, mockData,
+        auth: listener.auth, mockData, querySpec: listener.spec,
       });
       if (evaluation.check === 'allow') continue;
       this.state.childListeners.delete(listener);
@@ -419,9 +424,11 @@ export class WritePlane {
     }
   }
 
-  private readEvaluation(auth: AuthState, path: string) {
+  private readEvaluation(auth: AuthState, path: string, spec?: QuerySpec) {
     return this.state.rules.evaluate('read', path === '/' ? '/' : path, {
-      auth, mockData: this.state.tree.snapshot() as Record<string, unknown>,
+      auth,
+      mockData: this.state.tree.snapshot() as Record<string, unknown>,
+      querySpec: spec,
     });
   }
 

package/src/database/sdk-activity.ts

@@ -0,0 +1,26 @@
+import { captureDatabaseIndexQuery } from '../rules/indexes/service-query.js';
+import { sdkActivity, type SdkActivityHandle, type SdkActivityRecord } from '../sandbox/internal/sdk-activity.js';
+import { listenerAttachOwners, type ListenerAttribution } from '../sandbox/attribution/listener-owners.js';
+import { queryIdentifier, isQuery } from './query-shape.js';
+import { targetOf } from './routing.js';
+import type { DatabaseReference, Query } from './types.js';
+
+export function beginDatabaseActivity(
+  ref: DatabaseReference | Query,
+  method: string,
+  kind: SdkActivityRecord['kind'],
+  attribution?: ListenerAttribution,
+): SdkActivityHandle {
+  const base = isQuery(ref) ? (ref as Query).ref : ref as DatabaseReference;
+  const target = targetOf(base);
+  return sdkActivity.begin({
+    app: target.activityApp ?? target,
+    source: {
+      service: 'database', target: base._path,
+      key: JSON.stringify([target.activityScope, base._path, queryIdentifier(ref._spec)]),
+      isQuery: isQuery(ref),
+      ...(isQuery(ref) ? { indexQuery: captureDatabaseIndexQuery(base._path, ref._spec) } : {}),
+    },
+    method, kind, owners: listenerAttachOwners(attribution?.owner, attribution?.owners),
+  });
+}

package/src/database/transactions.ts

@@ -1,3 +1,5 @@
+import { runSdkWrite } from '../sandbox/internal/sdk-write-activity.js';
+import { beginDatabaseActivity } from './sdk-activity.js';
 import type { JsonValue } from './sandbox/data-tree.js';
 import { authFor, targetOf } from './routing.js';
 import type { DataSnapshot, DatabaseReference } from './types.js';
@@ -85,15 +87,17 @@ export async function runTransaction<T>(
   options?: TransactionOptions,
 ): Promise<TransactionResult> {
   const target = targetOf(r as unknown as object);
-  const result = target.backend.runTransaction(
-    authFor(target),
-    r._path,
-    transactionUpdate as (current: JsonValue) => JsonValue | undefined,
-    options,
-  );
-  const snap = buildSandboxSnapFromRaw(target, r, result.val);
-  return new TransactionResult(result.committed, snap) as TransactionResult & {
-    committed: boolean;
-    snapshot: DataSnapshot;
-  };
+  return runSdkWrite(beginDatabaseActivity(r, 'runTransaction', 'operation'), () => {
+    const result = target.backend.runTransaction(
+      authFor(target),
+      r._path,
+      transactionUpdate as (current: JsonValue) => JsonValue | undefined,
+      options,
+    );
+    const snap = buildSandboxSnapFromRaw(target, r, result.val);
+    return new TransactionResult(result.committed, snap) as TransactionResult & {
+      committed: boolean;
+      snapshot: DataSnapshot;
+    };
+  });
 }

package/src/database/types.ts

@@ -3,6 +3,10 @@ import { QUERY_SYMBOL } from './brands.js';
 import type { Database } from './database-handle.js';
 import type { DataSnapshot } from './data-snapshot.js';
 import type { JsonValue } from './sandbox/data-tree.js';
+import type {
+  ListenerOwnerHint,
+  RecordedListenerOwners,
+} from '../sandbox/attribution/listener-owners.js';
 import type { QuerySpec } from './sandbox/query.js';
 
 export { CONSTRAINT_SYMBOL, QUERY_SYMBOL } from './brands.js';
@@ -79,8 +83,15 @@ export type EventType =
   | 'child_moved'
   | 'child_removed';
 
-export interface ListenOptions {
+export interface ListenOptions extends RecordedListenerOwners {
   readonly onlyOnce?: boolean;
+  /**
+   * Pyric's own extension, absent from the Firebase Web SDK: who owns this
+   * listener. A name, or the DOM element the listener feeds. It is recorded
+   * as a `tag` owner on the sandbox's listener `attach` event and changes
+   * nothing about what the listener delivers.
+   */
+  readonly owner?: ListenerOwnerHint;
 }
 
 type FirebaseSignInProvider =

package/src/deferred/entry.ts

@@ -31,7 +31,7 @@
  */
 
 /**
- * Compose the single user-facing message every deferred entry raises.
+ * Compose the single user-facing message every deferred Web SDK entry raises.
  *
  * @param subpath - The Firebase subpath *without* the `firebase/` prefix, e.g.
  *   `functions` or `firestore/lite`.
@@ -58,8 +58,8 @@ export class PyricDeferredApiError extends Error {
   /** The exported symbol whose use triggered this error (e.g. `getFunctions`). */
   readonly symbol: string;
 
-  constructor(subpath: string, symbol: string) {
-    super(deferredApiMessage(subpath));
+  constructor(subpath: string, symbol: string, message: string = deferredApiMessage(subpath)) {
+    super(message);
     this.subpath = subpath;
     this.symbol = symbol;
   }
@@ -111,9 +111,9 @@ const INERT_PROPERTIES: ReadonlySet<string> = new Set([
  * constructed, wrapped in a proxy so member reads (the enum-constant shape)
  * throw the same error.
  */
-function deferredSymbol(subpath: string, symbol: string): DeferredApi {
+function deferredSymbol(subpath: string, symbol: string, message: string): DeferredApi {
   const throwing = function deferred(): never {
-    throw new PyricDeferredApiError(subpath, symbol);
+    throw new PyricDeferredApiError(subpath, symbol, message);
   };
   Object.defineProperty(throwing, 'name', { value: symbol, configurable: true });
 
@@ -125,10 +125,10 @@ function deferredSymbol(subpath: string, symbol: string): DeferredApi {
       if (typeof property === 'symbol' || INERT_PROPERTIES.has(property)) {
         return Reflect.get(target, property, receiver);
       }
-      throw new PyricDeferredApiError(subpath, `${symbol}.${property}`);
+      throw new PyricDeferredApiError(subpath, `${symbol}.${property}`, message);
     },
     construct() {
-      throw new PyricDeferredApiError(subpath, symbol);
+      throw new PyricDeferredApiError(subpath, symbol, message);
     },
   }) as unknown as DeferredApi;
 }
@@ -146,16 +146,22 @@ function deferredSymbol(subpath: string, symbol: string): DeferredApi {
  * generated `.d.ts` honest); the proxy just mints a correctly-attributed stub
  * for whichever name is read.
  *
- * @param subpath - The Firebase subpath, without the `firebase/` prefix.
+ * @param subpath - The Firebase subpath, without the package prefix.
+ * @param message - The message every export of this entry throws. Defaults
+ *   to the Web SDK message; `pyric-admin` passes its own for
+ *   `firebase-admin` subpaths.
  */
-export function deferredEntry(subpath: string): Record<string, DeferredApi> {
+export function deferredEntry(
+  subpath: string,
+  message: string = deferredApiMessage(subpath),
+): Record<string, DeferredApi> {
   const minted = new Map<string, DeferredApi>();
   return new Proxy(Object.create(null) as Record<string, DeferredApi>, {
     get(_target, property) {
       if (typeof property === 'symbol') return undefined as unknown as DeferredApi;
       let api = minted.get(property);
       if (!api) {
-        api = deferredSymbol(subpath, property);
+        api = deferredSymbol(subpath, property, message);
         minted.set(property, api);
       }
       return api;

package/src/firestore/activity-coverage.ts

@@ -0,0 +1,8 @@
+/** Public Firestore data operations observed by the modular adapters. */
+export const firestoreActivityCoverage = {
+  service: 'firestore',
+  read: ['getDoc', 'getDocs', 'getDocFromCache', 'getDocFromServer', 'getDocsFromCache', 'getDocsFromServer', 'getCountFromServer', 'getAggregateFromServer'],
+  write: ['setDoc', 'updateDoc', 'deleteDoc', 'addDoc', 'writeBatch.commit', 'runTransaction'],
+  listener: ['onSnapshot'],
+  untrackedMethods: [],
+} as const;

package/src/firestore/aggregates.ts

@@ -4,6 +4,8 @@
  * `count` / `sum` / `average` field descriptors and the
  * `getCountFromServer` / `getAggregateFromServer` executors.
  */
+import { beginFirestoreActivity } from './sdk-activity.js';
+import { finishSdkRead } from '../sandbox/internal/sdk-activity.js';
 import type {
   AggregateField as ChainAggregateField,
   AggregateSpec as ChainAggregateSpec,
@@ -103,10 +105,13 @@ export function average(field: string): AggregateField {
 export async function getCountFromServer(
   source: Query | CollectionReference,
 ): Promise<AggregateQuerySnapshot<{ count: number }>> {
-  const target = targetOf(source);
-  const snap = await chainQueryFor(target, source).aggregate({ count: { kind: 'count' } });
-  const data = snap.data();
-  return { data: () => ({ count: (data.count ?? 0) as number }) };
+  const activity = beginFirestoreActivity(targetOf(source), source, 'getCountFromServer', 'operation');
+  try {
+    const target = targetOf(source);
+    const snap = await chainQueryFor(target, source).aggregate({ count: { kind: 'count' } });
+    const data = snap.data();
+    return finishSdkRead(activity, { data: () => ({ count: (data.count ?? 0) as number }) });
+  } catch (error) { activity.fail(); throw error; }
 }
 
 /**
@@ -120,9 +125,12 @@ export async function getAggregateFromServer<S extends AggregateSpec>(
   source: Query | CollectionReference,
   spec: S,
 ): Promise<AggregateQuerySnapshot<{ [K in keyof S]: number | null }>> {
-  const target = targetOf(source);
-  const chainSpec: ChainAggregateSpec = {};
-  for (const alias of Object.keys(spec)) chainSpec[alias] = spec[alias] as ChainAggregateField;
-  const snap = await chainQueryFor(target, source).aggregate(chainSpec);
-  return { data: () => snap.data() as { [K in keyof S]: number | null } };
+  const activity = beginFirestoreActivity(targetOf(source), source, 'getAggregateFromServer', 'operation');
+  try {
+    const target = targetOf(source);
+    const chainSpec: ChainAggregateSpec = {};
+    for (const alias of Object.keys(spec)) chainSpec[alias] = spec[alias] as ChainAggregateField;
+    const snap = await chainQueryFor(target, source).aggregate(chainSpec);
+    return finishSdkRead(activity, { data: () => snap.data() as { [K in keyof S]: number | null } });
+  } catch (error) { activity.fail(); throw error; }
 }