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

package/src/firestore/internal/value-codec.ts

@@ -1,65 +1,29 @@
 /**
- * Internal Firestore value codec — the marker-based serialize/rehydrate of
- * Firestore special scalar types (Timestamp, Bytes, LatLng/GeoPoint,
- * Duration, Reference, Path, Vector).
+ * Firestore wire values shared by browser transports and sandbox persistence.
  *
- * WHY THIS MODULE EXISTS (and why it is a LEAF)
- * ---------------------------------------------
- * Two very different consumers need this codec:
+ * Declared wire encodings can escape marker-shaped maps; legacy persistence
+ * retains its marker interpretation. SDK decoding restores public scalar values
+ * and references owned by the receiving client. Persistence decoding retains
+ * the rules wrappers used by the evaluator. Direct value
+ * imports keep this module independent of the sandbox and rules engines.
  *
- *   1. The sandbox persistence serializer (`sandbox/persistence/serialize.ts`)
- *      — server-side, already pulls the whole engine, doesn't care about size.
- *   2. The SharedWorker CLIENT (`@pyric/cli/.../worker/client.ts` via
- *      `protocol.ts`) — runs in EVERY page that opens a serve session. It only
- *      needs to reconstruct Timestamp/Bytes/LatLng instances from the JSON
- *      markers the worker host wrote; it must NOT drag the rules engine,
- *      simulator, parser, or sandbox into the per-page bundle.
- *
- * Importing the wrapper CLASSES from the `pyric/rules` BARREL would execute the
- * entire rules index (parser + linter + simulator + evaluator → ~10 MB). The
- * wrapper modules themselves are leaf — each depends only on `wrappers/base.js`
- * which has zero imports — so this codec imports them by their DIRECT leaf
- * paths. The result: importing this module pulls ONLY the seven small wrapper
- * classes + their `base.js`, nothing heavy.
- *
- * Real types, not structural stand-ins: because the wrapper constructors are
- * already leaf-cheap, the codec reconstructs the SAME real `Timestamp`/`Bytes`/
- * `LatLng`/etc. classes the in-page (`pyric/firestore`) path yields. This keeps
- * `instanceof` checks and method calls (`.toDate()`, `.toMillis()`, byte
- * access, `.lat`/`.lng`) identical on both sides of the MessagePort and in IDB
- * persistence — there is ONE codec, not two that can drift.
- *
- * Marker formats handled (must stay in sync with each wrapper's `toJSON()`):
- *
- * 1. `pyric/rules` wrapper markers (from `Timestamp.toJSON()` etc.):
- *   { __type: 'timestamp', seconds, nanos }   → Timestamp
- *   { __type: 'bytes', base64 }               → Bytes   (base64url)
- *   { __type: 'latlng', lat, lng }            → LatLng
- *   { __type: 'duration', seconds, nanos }    → Duration
- *   { __type: 'reference', path }             → Reference
- *   { __type: 'path', segments }              → Path
- *   { __type__: '__vector__', value }         → Vector
- *
- * 2. `firebase/firestore` SDK markers (from fb.Timestamp.toJSON() etc.),
- *    produced when `pyric/firestore`'s `getDoc` returns `firebase/firestore`
- *    class instances that are then serialized via JSON.stringify:
- *   { type: 'firestore/timestamp/1.0', seconds, nanoseconds } → Timestamp
- *   { type: 'firestore/bytes/1.0', bytes }                    → Bytes (std b64)
- *   { type: 'firestore/geoPoint/1.0', latitude, longitude }   → LatLng
- *
- * Unknown `__type`/`type` values pass through as plain objects rather than
- * throwing — the rest of the doc still restores cleanly.
+ * Encoding escapes ordinary maps with marker keys before they cross the wire.
+ * Legacy unknown markers remain maps. Complete validation and write-intent
+ * handling are still required by the wire contract.
  */
-
-// Direct leaf imports — NOT the `pyric/rules` barrel. Each of these modules
-// depends only on `./base.js` (no imports), so this stays engine-free.
-import { Bytes } from '../../rules/simulator/wrappers/bytes.js';
+import { Bytes as RulesBytes } from '../../rules/simulator/wrappers/bytes.js';
 import { Duration } from '../../rules/simulator/wrappers/duration.js';
 import { LatLng } from '../../rules/simulator/wrappers/latlng.js';
 import { Path } from '../../rules/simulator/wrappers/path.js';
 import { Reference } from '../../rules/simulator/wrappers/reference.js';
-import { Timestamp } from '../../rules/simulator/wrappers/timestamp.js';
+import { Timestamp as RulesTimestamp } from '../../rules/simulator/wrappers/timestamp.js';
 import { Vector } from '../../rules/simulator/wrappers/vector.js';
+import { Timestamp } from '../timestamp.js';
+import { Bytes } from '../bytes.js';
+import { GeoPoint } from '../geo-point.js';
+import { VectorValue } from '../vector-value.js';
+import { FirebaseError } from '../../sandbox/internal/firebase-error.js';
+import { assertEncodedDocValueDepth } from './value-depth.js';
 // Sideways leaf import into the firestore surface (same character as the
 // wrapper imports above): the activity value registry is a zero-dependency
 // leaf owned by `firestore/sandbox/`, consumed here only to stamp trusted
@@ -68,7 +32,76 @@ import {
   registerActivityValue,
   trustedWireActivityValue,
 } from '../sandbox/activity-value-registry.js';
-import { registerQueryValue } from '../sandbox/query-value-registry.js';
+import { registerQueryValue, registeredReferenceQueryValuePath } from '../sandbox/query-value-registry.js';
+export { registerReferenceQueryValue } from '../sandbox/query-value-registry.js';
+export { requireDocumentData } from './document-data.js';
+export { assertEncodedDocValueDepth } from './value-depth.js';
+
+export const DOC_VALUE_ENCODING = 'pyric/firestore-values/1';
+export type DocValueEncoding = typeof DOC_VALUE_ENCODING;
+
+function resolveMapEncoding(encoding: DocValueEncoding | undefined): boolean {
+  const isLegacyEncoding = encoding === undefined;
+  const allowsEscapedMaps = encoding === DOC_VALUE_ENCODING;
+  const isUnsupportedEncoding = !isLegacyEncoding && !allowsEscapedMaps;
+  if (isUnsupportedEncoding) {
+    throw new FirebaseError('invalid-argument', 'Unsupported Firestore value encoding.');
+  }
+  return allowsEscapedMaps;
+}
+
+/** Encode SDK values before transport removes their class or copies their owner. */
+export function encodeDocValue(value: unknown): unknown {
+  const isScalar = value === null || typeof value !== 'object';
+  if (isScalar) return value;
+  const isTimestamp = value instanceof Timestamp;
+  if (isTimestamp) return value.toJSON();
+  const isDate = value instanceof Date;
+  if (isDate) return Timestamp.fromDate(value).toJSON();
+  const isBytes = value instanceof Bytes;
+  if (isBytes) return value.toJSON();
+  const isGeoPoint = value instanceof GeoPoint;
+  if (isGeoPoint) return value.toJSON();
+  const isVector = value instanceof VectorValue;
+  if (isVector) return value.toJSON();
+  const referencePath = registeredReferenceQueryValuePath(value);
+  const isReference = referencePath !== undefined;
+  if (isReference) return { __type: 'reference', path: referencePath };
+  const isArray = Array.isArray(value);
+  if (isArray) return value.map(encodeDocValue);
+  const prototype = Object.getPrototypeOf(value);
+  const isPlainMap = prototype === Object.prototype || prototype === null;
+  if (isPlainMap) {
+    const fields = Object.fromEntries(Object.entries(value).map(([key, item]) => [key, encodeDocValue(item)]));
+    const hasMarkerField = Object.hasOwn(fields, 'type')
+      || Object.hasOwn(fields, '__type')
+      || Object.hasOwn(fields, '__type__');
+    if (hasMarkerField) return { type: 'pyric/map/1.0', fields };
+    return fields;
+  }
+  return value;
+}
+
+/** A decoder's owner supplies usable references; persistence keeps rules values. */
+export interface ReferenceDecoder {
+  create(path: string): object;
+}
+
+interface ValueConstructors {
+  bytes(value: Uint8Array): object;
+  geoPoint(latitude: number, longitude: number): object;
+  reference(path: string): object;
+  timestamp(seconds: number, nanoseconds: number): object;
+  vector(values: readonly number[]): object;
+}
+
+const rulesValues: ValueConstructors = {
+  bytes: (value) => new RulesBytes(value),
+  geoPoint: (latitude, longitude) => new LatLng(latitude, longitude),
+  reference: (path) => new Reference(path),
+  timestamp: (seconds, nanoseconds) => new RulesTimestamp(seconds, nanoseconds),
+  vector: (values) => new Vector(values),
+};
 
 /**
  * Decode a base64url string (`-`/`_` alphabet, no padding) back into a
@@ -95,23 +128,37 @@ function base64StdDecode(s: string): Uint8Array {
   return out;
 }
 
-/**
- * Walk a parsed JSON tree and re-wrap any marker shape back into its real
- * wrapper-class instance. Visits arrays and plain objects recursively. Plain
- * values (and plain objects without a recognized discriminator) pass through.
- *
- * This is the canonical rehydrate used by BOTH the sandbox persistence
- * serializer and the SharedWorker wire protocol, so the IDB format and the
- * MessagePort wire format are guaranteed identical.
- */
+/** Restore persisted marker trees to rules values, including nested maps and arrays. */
 export function rehydrateDocValue(value: unknown): unknown {
-  return rehydrateValue(value, true);
+  return rehydrateValue(value, true, rulesValues, false);
+}
+
+/** Decode explicitly declared wire values; absent declarations retain the legacy marker contract. */
+export function rehydrateEncodedDocValue(value: unknown, encoding: DocValueEncoding | undefined): unknown {
+  assertEncodedDocValueDepth(value);
+  const allowsEscapedMaps = resolveMapEncoding(encoding);
+  return rehydrateValue(value, true, rulesValues, allowsEscapedMaps);
 }
 
-function rehydrateValue(value: unknown, registerRootIdentity: boolean): unknown {
-  if (value === null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) {
-    const hydrated = value.map((item) => rehydrateValue(item, false));
+/** Decode values for an SDK owner while retaining the unary persistence decoder. */
+export function decodeDocValue(value: unknown, references: ReferenceDecoder, encoding?: DocValueEncoding): unknown {
+  assertEncodedDocValueDepth(value);
+  const allowsEscapedMaps = resolveMapEncoding(encoding);
+  return rehydrateValue(value, true, {
+    bytes: (value) => Bytes.fromUint8Array(value),
+    geoPoint: (latitude, longitude) => new GeoPoint(latitude, longitude),
+    reference: (path) => references.create(path),
+    timestamp: (seconds, nanoseconds) => new Timestamp(seconds, nanoseconds),
+    vector: (values) => VectorValue.create(values.slice()),
+  }, allowsEscapedMaps);
+}
+
+function rehydrateValue(value: unknown, registerRootIdentity: boolean, constructors: ValueConstructors, allowsEscapedMaps: boolean): unknown {
+  const isScalar = value === null || typeof value !== 'object';
+  if (isScalar) return value;
+  const isArray = Array.isArray(value);
+  if (isArray) {
+    const hydrated = value.map((item) => rehydrateValue(item, false, constructors, allowsEscapedMaps));
     if (registerRootIdentity) {
       registerActivityValue(hydrated, trustedWireActivityValue(value));
     }
@@ -130,43 +177,58 @@ function rehydrateValue(value: unknown, registerRootIdentity: boolean): unknown
     return withActivityIdentity(hydrated);
   };
 
-  if (obj.__type__ === '__vector__' && Array.isArray(obj.value)) {
+  const isVector = obj.__type__ === '__vector__' && Array.isArray(obj.value);
+  if (isVector) {
     const values = Object.freeze((obj.value as number[]).slice());
-    return withQueryIdentity(new Vector(values), { type: 'vector', values });
+    return withQueryIdentity(constructors.vector(values), { type: 'vector', values });
   }
 
   // pyric/rules wrapper marker form (used for IDB persistence + wire).
-  if (typeof obj.__type === 'string') {
+  const hasWrapperMarker = typeof obj.__type === 'string';
+  if (hasWrapperMarker) {
     switch (obj.__type) {
       case 'timestamp':
         return withQueryIdentity(
-          new Timestamp(obj.seconds as number, obj.nanos as number),
+          constructors.timestamp(obj.seconds as number, obj.nanos as number),
           { type: 'timestamp', seconds: obj.seconds, nanoseconds: obj.nanos },
         );
       case 'bytes': {
         const bytes = base64UrlDecode(obj.base64 as string);
         return withQueryIdentity(
-          new Bytes(bytes),
+          constructors.bytes(bytes),
           { type: 'bytes', values: Object.freeze(Array.from(bytes)) },
         );
       }
       case 'latlng':
         return withQueryIdentity(
-          new LatLng(obj.lat as number, obj.lng as number),
+          constructors.geoPoint(obj.lat as number, obj.lng as number),
           { type: 'geo-point', latitude: obj.lat, longitude: obj.lng },
         );
       case 'duration':
         return withActivityIdentity(new Duration(obj.seconds as number, obj.nanos as number));
-      case 'reference':
-        return withActivityIdentity(new Reference(obj.path as string));
+      case 'reference': {
+        const path = obj.path as string;
+        return withActivityIdentity(constructors.reference(path));
+      }
       case 'path':
         return withActivityIdentity(new Path(obj.segments as string[]));
     }
   }
 
-  // firebase/firestore SDK marker form (produced when pyric/firestore's
-  // getDoc returns fb-SDK class instances and JSON.stringify is called).
-  if (typeof obj.type === 'string') {
+  const isEscapedMap = allowsEscapedMaps && obj.type === 'pyric/map/1.0';
+  if (isEscapedMap) {
+    const fields = obj.fields;
+    const hasInvalidMapFields = fields === null || typeof fields !== 'object' || Array.isArray(fields);
+    if (hasInvalidMapFields) throw new TypeError('Invalid encoded map fields.');
+    const hydrated = Object.fromEntries(
+      Object.entries(fields).map(([key, item]) => [key, rehydrateValue(item, false, constructors, allowsEscapedMaps)]),
+    );
+    return withActivityIdentity(hydrated);
+  }
+
+  // Versioned markers distinguish SDK values from escaped user maps.
+  const hasVersionedMarker = typeof obj.type === 'string';
+  if (hasVersionedMarker) {
     switch (obj.type) {
       case 'firestore/timestamp/1.0': {
         // fb.Timestamp.toJSON() emits { type, seconds, nanoseconds }.
@@ -174,7 +236,7 @@ function rehydrateValue(value: unknown, registerRootIdentity: boolean): unknown
         const seconds = obj.seconds as number;
         const nanoseconds = obj.nanoseconds as number;
         return withQueryIdentity(
-          new Timestamp(seconds, nanoseconds),
+          constructors.timestamp(seconds, nanoseconds),
           { type: 'timestamp', seconds, nanoseconds },
         );
       }
@@ -182,21 +244,26 @@ function rehydrateValue(value: unknown, registerRootIdentity: boolean): unknown
         // fb.Bytes.toJSON() emits { type, bytes } where bytes is standard base64.
         const bytes = base64StdDecode(obj.bytes as string);
         return withQueryIdentity(
-          new Bytes(bytes),
+          constructors.bytes(bytes),
           { type: 'bytes', values: Object.freeze(Array.from(bytes)) },
         );
       }
       case 'firestore/geoPoint/1.0': {
         // fb.GeoPoint.toJSON() emits { latitude, longitude, type }.
         return withQueryIdentity(
-          new LatLng(obj.latitude as number, obj.longitude as number),
+          constructors.geoPoint(obj.latitude as number, obj.longitude as number),
           { type: 'geo-point', latitude: obj.latitude, longitude: obj.longitude },
         );
       }
+      case 'firestore/vectorValue/1.0': {
+        const vector = VectorValue.fromJSON(obj);
+        const values = Object.freeze(vector.toArray());
+        return withQueryIdentity(constructors.vector(values), { type: 'vector', values });
+      }
     }
   }
 
   const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(obj)) out[k] = rehydrateValue(v, false);
+  for (const [k, v] of Object.entries(obj)) out[k] = rehydrateValue(v, false, constructors, allowsEscapedMaps);
   return withActivityIdentity(out);
 }

package/src/firestore/internal/value-depth.ts

@@ -0,0 +1,19 @@
+import { FirebaseError } from '../../sandbox/internal/firebase-error.js';
+
+const MAX_ENCODED_DOCUMENT_DEPTH = 64;
+
+/** Count encoded containers, including the root, before recursive value decoding. */
+export function assertEncodedDocValueDepth(value: unknown): void {
+  checkContainerDepth(value, 0);
+}
+
+function checkContainerDepth(value: unknown, parentDepth: number): void {
+  const isScalar = value === null || typeof value !== 'object';
+  if (isScalar) return;
+  const depth = parentDepth + 1;
+  const exceedsLimit = depth > MAX_ENCODED_DOCUMENT_DEPTH;
+  if (exceedsLimit) {
+    throw new FirebaseError('invalid-argument', 'Encoded document nesting exceeds 64 containers.');
+  }
+  for (const child of Object.values(value)) checkContainerDepth(child, depth);
+}

package/src/firestore/listeners.ts

@@ -5,21 +5,31 @@
  * under current auth, threading the follows-current-user marker, tagging +
  * rehydrating delivered snapshots, and the default uncaught-error handler.
  */
+// Modular listeners use the chainable adapter installed by this module.
+import '../sandbox/admin-firestore/listeners.js';
 import type { DocumentData } from 'pyric/sandbox/admin-firestore';
 import { AUTH_SESSION_SCOPE, FOLLOWS_CURRENT_USER } from 'pyric/firestore/internal';
 import { FirebaseError } from '../sandbox/internal/firebase-error.js';
+import { toFirestoreFirebaseError } from './errors.js';
 import { clientStateFor } from './client-state.js';
+import { beginFirestoreActivity } from './sdk-activity.js';
+import { sdkActivity, type SdkActivityHandle } from '../sandbox/internal/sdk-activity.js';
+import type {
+  ListenerOwnerHint,
+  RecordedListenerOwners,
+} from '../sandbox/attribution/listener-owners.js';
 
 import {
   targetOf,
   sandboxDb,
   sandboxLiveRebuild,
   underlyingOf,
+  converterOf,
   type Target,
   type SandboxTarget,
   type SandboxLiveTarget,
 } from './state.js';
-import { wrapSandboxDocSnap, tagSnapshotRefs, recordQuerySnapshot } from './snapshots.js';
+import { wrapSandboxDocSnap, tagSnapshotRefs, recordQuerySnapshot, applyConverterToDeliveredSnap } from './snapshots.js';
 import type {
   DocumentReference,
   Query,
@@ -28,8 +38,16 @@ import type {
 
 // ─── Snapshot listeners ───────────────────────────────────────────────
 
-export interface SnapshotListenOptions {
+export interface SnapshotListenOptions extends RecordedListenerOwners {
   includeMetadataChanges?: 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 so a listener
+   * can be traced back to the part of the app that wanted it. It has no
+   * effect on delivery, and a production Firestore target ignores it.
+   */
+  owner?: ListenerOwnerHint;
 }
 
 export interface SnapshotObserver<T> {
@@ -58,22 +76,29 @@ export function onSnapshot(
   const target = targetOf(ref);
   clientStateFor(target).markStarted();
   const r = resolveSandboxListenable(target, ref);
-  const wrappedArgs = tagSandboxSnapshotArgs(arg2, arg3, arg4, target, ref as object);
+  const attribution = typeof arg2 === 'object' && arg2 !== null && !isPartialObserver(arg2) ? arg2 as SnapshotListenOptions : undefined;
+  const activity = beginFirestoreActivity(target, ref, 'onSnapshot', 'subscription', attribution);
+  const wrappedArgs = tagSandboxSnapshotArgs(arg2, arg3, arg4, target, ref as object, activity);
   const finalArgs = markSandboxLiveSnapshotArgs(wrappedArgs, target);
-  const unsubscribe = finalArgs.length === 3
-    ? r.onSnapshot(finalArgs[0], finalArgs[1], finalArgs[2])
-    : finalArgs.length === 2
-      ? r.onSnapshot(finalArgs[0], finalArgs[1])
-      : r.onSnapshot(finalArgs[0]);
-  if (!target.own) return unsubscribe;
+  let unsubscribe: Unsubscribe;
+  try {
+    unsubscribe = sdkActivity.registering(activity, () => {
+      if (finalArgs.length === 3) return r.onSnapshot(finalArgs[0], finalArgs[1], finalArgs[2]);
+      if (finalArgs.length === 2) return r.onSnapshot(finalArgs[0], finalArgs[1]);
+      return r.onSnapshot(finalArgs[0]);
+    });
+  } catch (error) { activity.fail(); throw error; }
+  if (!target.own) return () => { activity.close(); unsubscribe(); };
   let stopped = false;
   const stop = (): void => {
     if (stopped) return;
     stopped = true;
+    activity.close();
     unsubscribe();
   };
   const abort = (): void => {
     if (stopped) return;
+    activity.fail();
     stop();
     snapshotErrorHandler(finalArgs)?.(
       new FirebaseError('aborted', 'The operation was aborted.'),
@@ -161,6 +186,7 @@ function tagSandboxSnapshotArgs(
   arg4: ((error: unknown) => void) | undefined,
   target: Target,
   source: object,
+  activity: SdkActivityHandle,
 ): unknown[] {
   // Detect whether arg2 is the SnapshotListenOptions form. FS-B14 — an
   // observer is any object carrying at least one of `next` / `error` /
@@ -175,22 +201,22 @@ function tagSandboxSnapshotArgs(
     // (options, next | observer, error?)
     const next = arg3;
     if (typeof next === 'function') {
-      return [arg2, wrapNext(next as (snap: unknown) => void, target, source), arg4 ?? defaultSnapshotErrorHandler];
+      return [arg2, wrapNext(next as (snap: unknown) => void, target, source, activity), wrapError(arg4 ?? defaultSnapshotErrorHandler, activity)];
     }
     if (next && typeof next === 'object') {
-      return [arg2, wrapObserver(next as SnapshotObserver<unknown>, target, source)];
+      return [arg2, wrapObserver(next as SnapshotObserver<unknown>, target, source, activity)];
     }
     return [arg2];
   }
   // (next | observer, error?)
   if (typeof arg2 === 'function') {
     return [
-      wrapNext(arg2 as (snap: unknown) => void, target, source),
-      (arg3 as ((error: unknown) => void) | undefined) ?? defaultSnapshotErrorHandler,
+      wrapNext(arg2 as (snap: unknown) => void, target, source, activity),
+      wrapError((arg3 as ((error: unknown) => void) | undefined) ?? defaultSnapshotErrorHandler, activity),
     ];
   }
   if (arg2 && typeof arg2 === 'object') {
-    return [wrapObserver(arg2 as SnapshotObserver<unknown>, target, source)];
+    return [wrapObserver(arg2 as SnapshotObserver<unknown>, target, source, activity)];
   }
   return [arg2];
 }
@@ -238,11 +264,17 @@ function finalizeSandboxSnapshot(snap: unknown, target: Target, source: object):
     data?: () => DocumentData | undefined;
     docs?: Array<object>;
   };
+  const conv = converterOf(source) ?? null;
+  const hasConverter = conv !== null;
   if (typeof s.data === 'function') {
     wrapSandboxDocSnap(snap as object, target);
+    if (hasConverter) applyConverterToDeliveredSnap(snap as object, conv, target, 'document');
   }
   if (Array.isArray(s.docs)) {
-    for (const d of s.docs) wrapSandboxDocSnap(d as object, target);
+    for (const d of s.docs) {
+      wrapSandboxDocSnap(d as object, target);
+      if (hasConverter) applyConverterToDeliveredSnap(d as object, conv, target, 'query-child');
+    }
     recordQuerySnapshot(snap as object, snap as object, target, source, 'listener');
   }
   return snap;
@@ -266,9 +298,12 @@ function wrapNext(
   next: (snap: unknown) => void,
   target: Target,
   source: object,
+  activity: SdkActivityHandle,
 ): (snap: unknown) => void {
   return (snap) => {
-    next(finalizeSandboxSnapshot(tagSnapshotRefs(snap, target), target, source));
+    const value = finalizeSandboxSnapshot(tagSnapshotRefs(snap, target), target, source);
+    activity.delivered(value);
+    next(value);
     clientStateFor(target).notifySnapshotDelivered();
   };
 }
@@ -277,16 +312,23 @@ function wrapObserver(
   obs: SnapshotObserver<unknown>,
   target: Target,
   source: object,
+  activity: SdkActivityHandle,
 ): SnapshotObserver<unknown> {
   return {
     ...obs,
     next: obs.next
       ? (snap) => {
-          obs.next!(finalizeSandboxSnapshot(tagSnapshotRefs(snap, target), target, source));
+          const value = finalizeSandboxSnapshot(tagSnapshotRefs(snap, target), target, source);
+          activity.delivered(value);
+          obs.next!(value);
           clientStateFor(target).notifySnapshotDelivered();
         }
       : undefined,
     // Surface an unobserved listener error instead of swallowing it.
-    error: obs.error ?? defaultSnapshotErrorHandler,
+    error: wrapError(obs.error ?? defaultSnapshotErrorHandler, activity),
   };
 }
+
+function wrapError(callback: (error: unknown) => void, activity: SdkActivityHandle): (error: unknown) => void {
+  return error => { activity.fail(); callback(toFirestoreFirebaseError(error)); };
+}

package/src/firestore/persistence.ts

@@ -7,6 +7,9 @@
  * variants, `setLogLevel`, and `onSnapshotsInSync`. Read the section note
  * below before touching any function.
  */
+import { readDocument, readQuery } from './reads.js';
+import { beginFirestoreActivity } from './sdk-activity.js';
+import { finishSdkRead } from '../sandbox/internal/sdk-activity.js';
 import type { FirebaseApp } from '../app/types.js';
 import type { Sandbox, SandboxContext } from 'pyric/sandbox';
 import type { DocumentData } from 'pyric/sandbox/admin-firestore';
@@ -21,7 +24,6 @@ import type {
   Unsubscribe,
 } from './types.js';
 import { getFirestore } from './instances.js';
-import { getDoc, getDocs } from './reads.js';
 import { clientStateFor } from './client-state.js';
 
 // ─── Tier: offline / persistence / network family (issue #144) ────────
@@ -334,17 +336,17 @@ export function initializeFirestore(
  * same honest thing.
  *
  */
-export function getDocFromServer<T = DocumentData>(
+export async function getDocFromServer<T = DocumentData>(
   ref: DocumentReference<T>,
 ): Promise<DocumentSnapshot<T>> {
-  return getDoc(ref);
+  return readDocument(ref, beginFirestoreActivity(targetOf(ref), ref, 'getDocFromServer', 'operation'));
 }
 
 /** Query-plural form of {@link getDocFromServer}. */
-export function getDocsFromServer<T = DocumentData>(
+export async function getDocsFromServer<T = DocumentData>(
   query: Query<T>,
 ): Promise<QuerySnapshot<T>> {
-  return getDocs(query);
+  return readQuery(query, beginFirestoreActivity(targetOf(query), query, 'getDocsFromServer', 'operation'));
 }
 
 /**
@@ -360,12 +362,14 @@ export function getDocFromCache<T = DocumentData>(
 ): Promise<DocumentSnapshot<T>> {
   const target = targetOf(ref);
   const client = clientStateFor(target);
+  const activity = beginFirestoreActivity(target, ref, 'getDocFromCache', 'operation');
   try {
     client.assertPathCached(ref.path);
   } catch (error) {
+    activity.fail();
     return Promise.reject(error);
   }
-  return getDoc(ref).then((snapshot) => {
+  return readDocument(ref, activity).then((snapshot) => {
     Object.defineProperty(snapshot, 'metadata', {
       value: Object.freeze({
         fromCache: true,
@@ -383,15 +387,16 @@ export function getDocsFromCache<T = DocumentData>(
 ): Promise<QuerySnapshot<T>> {
   const target = targetOf(query);
   const client = clientStateFor(target);
+  const activity = beginFirestoreActivity(target, query, 'getDocsFromCache', 'operation');
   if (!client.hasCachedQuery(query as object)) {
-    return Promise.resolve(tag({
+    return Promise.resolve(finishSdkRead(activity, tag({
       size: 0,
       empty: true,
       docs: [],
       metadata: Object.freeze({ fromCache: true, hasPendingWrites: false }),
-    }, target));
+    }, target)));
   }
-  return getDocs(query).then((snapshot) => {
+  return readQuery(query, activity).then((snapshot) => {
     Object.defineProperty(snapshot, 'metadata', {
       value: Object.freeze({
         fromCache: true,

package/src/firestore/plain-object.ts

@@ -0,0 +1,7 @@
+/** Objects whose own fields form a document map, without a custom prototype. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  const isNotObject = value === null || typeof value !== 'object';
+  if (isNotObject) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/firestore/query-constraints.ts

@@ -21,8 +21,8 @@ import {
   converterOf,
   parentRebuild,
   tagSandboxRef,
-  buildSandboxShell,
 } from './state.js';
+import { attachConverterMethod, convertedView } from './converter-method.js';
 import { FieldPath } from './field-values.js';
 import { toFirestoreFirebaseError } from './errors.js';
 import { captureQueryOperand } from './sandbox/query-operand-equality.js';
@@ -82,17 +82,13 @@ export function query<T = DocumentData>(
   } catch (error) {
     throw toFirestoreFirebaseError(error);
   }
-  const tagged = tagSandboxRef(
+  const tagged = attachConverterMethod(tagSandboxRef(
     q as unknown as Query<T>,
     target,
     (fresh) => buildAt(fresh) as unknown as object,
-  );
+  ));
   if (conv) {
-    return buildSandboxShell(
-      tagged as unknown as { id?: string; path?: string },
-      target,
-      conv,
-    ) as Query<T>;
+    return convertedView(tagged, conv) as Query<T>;
   }
   return tagged as Query<T>;
 }