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

package/src/sandbox/active-listeners.ts

@@ -0,0 +1,245 @@
+/**
+ * Every listener the sandbox currently holds attached, derived by folding the
+ * event stream's attach and detach lifecycle rather than tracked as separate
+ * live state. A listener that never detached before a restart is still
+ * active; one that detached, or errored, is not, no matter how many
+ * deliveries it saw first.
+ *
+ * Firestore reports lifecycle through its own `listener_attach` /
+ * `listener_detach` / `listener_errored` / `snapshot_delivery` /
+ * `snapshot_suppressed` variants; the Realtime Database and every future
+ * listening service report it through the canonical `listener` variant. This
+ * module is the one place both shapes are folded into one answer, so a caller
+ * asking "what is still listening" never has to know which service produced
+ * the events.
+ */
+import type { AuthLens, EventActor, EventService } from './types/operation.js';
+import { operationContextFor } from './operation-record.js';
+import type { ListenerOwner, SandboxEvent } from './types/events.js';
+
+/** The two families of target a listener watches. */
+export type ActiveListenerTarget =
+  | string
+  | { readonly collection: string; readonly query?: unknown };
+
+/** One listener that has attached and not yet detached or errored. */
+export interface ActiveListener {
+  readonly id: string;
+  readonly service: 'firestore' | 'database';
+  readonly target: ActiveListenerTarget;
+  readonly actor: EventActor;
+  readonly authLens: AuthLens;
+  readonly attachedAt: number;
+  readonly deliveryCount: number;
+  readonly suppressedCount: number;
+  readonly lastDeliveryAt?: number;
+  /**
+   * Who owns the listener, as its attach event recorded it (a creation frame,
+   * an explicit tag) and as its deliveries revealed it (the DOM regions its
+   * callback changed). Absent when the emitter recorded nothing.
+   */
+  readonly owners?: readonly ListenerOwner[];
+  /**
+   * The id the page's own client gave this subscription, when the host
+   * stamped it on the attach as the activity listener id. A page that
+   * observes a delivery knows only this id, so it is how a page-side
+   * observation finds the listener the sandbox recorded.
+   */
+  readonly clientListenerId?: string;
+  /**
+   * The query the attach recorded, when the listener watches a query rather
+   * than one record: Firestore's constraint projection, or the Realtime
+   * Database's query spec. Absent for a document or a bare path.
+   */
+  readonly query?: unknown;
+}
+
+type ListenerPhase = 'attach' | 'detach' | 'delivery' | 'suppressed' | 'errored';
+
+/** The listener-shaped fields this module reads off one raw event. */
+interface ListenerEventInfo {
+  readonly phase: ListenerPhase;
+  readonly listenerId: string;
+  readonly service: 'firestore' | 'database';
+  readonly target: ActiveListenerTarget;
+  readonly actor: EventActor;
+  readonly authLens: AuthLens;
+  readonly owners?: readonly ListenerOwner[];
+  readonly query?: unknown;
+}
+
+/** The internal service token 'rtdb' translated to the word this module's
+ * callers already use for the Realtime Database everywhere else on this
+ * surface. */
+function externalService(service: EventService | undefined): 'firestore' | 'database' {
+  if (service === 'rtdb') return 'database';
+  return 'firestore';
+}
+
+/** Firestore's own lifecycle target shape: a doc path, or a query's collection. */
+function firestoreTarget(target: { kind: 'doc'; path: string } | { kind: 'query'; collection: string; query?: unknown }): ActiveListenerTarget {
+  if (target.kind === 'doc') return target.path;
+  return { collection: target.collection, query: target.query };
+}
+
+/** Canonical lifecycle target: today only a path, carried by the Realtime
+ * Database's listeners. */
+function canonicalTarget(target: { kind: string; path?: string; query?: unknown }): ActiveListenerTarget {
+  if (target.path !== undefined) return target.path;
+  return { collection: '', query: target.query };
+}
+
+/** The query a lifecycle target carries, as a spreadable field. Both services
+ * put it on the target, so one reader serves them. */
+function targetQuery(target: object): { query?: unknown } {
+  const query = (target as { query?: unknown }).query;
+  return query === undefined ? {} : { query };
+}
+
+/** The fields this module needs off one event, or `null` when it is not
+ * listener lifecycle. */
+function listenerEventInfo(event: SandboxEvent): ListenerEventInfo | null {
+  const context = operationContextFor(event);
+  const owners = 'owners' in event && Array.isArray(event.owners) ? event.owners : undefined;
+  const identity = { actor: context.source, authLens: context.authLens, owners };
+
+  if (event.kind === 'listener_attach') {
+    return {
+      phase: 'attach',
+      listenerId: event.listenerId,
+      service: 'firestore',
+      target: firestoreTarget(event.target),
+      ...identity,
+      ...targetQuery(event.target),
+    };
+  }
+  if (event.kind === 'listener_detach') {
+    return { phase: 'detach', listenerId: event.listenerId, service: 'firestore', target: firestoreTarget(event.target), ...identity };
+  }
+  if (event.kind === 'listener_errored') {
+    return { phase: 'errored', listenerId: event.listenerId, service: 'firestore', target: firestoreTarget(event.target), ...identity };
+  }
+  if (event.kind === 'snapshot_delivery') {
+    return { phase: 'delivery', listenerId: event.listenerId, service: 'firestore', target: firestoreTarget(event.target), ...identity };
+  }
+  if (event.kind === 'snapshot_suppressed') {
+    return { phase: 'suppressed', listenerId: event.listenerId, service: 'firestore', target: firestoreTarget(event.target), ...identity };
+  }
+  if (event.kind === 'listener') {
+    return {
+      phase: event.phase,
+      listenerId: event.listenerId,
+      service: externalService(event.service),
+      target: canonicalTarget(event.target),
+      ...identity,
+      ...targetQuery(event.target),
+    };
+  }
+  return null;
+}
+
+interface ActiveListenerDraft {
+  id: string;
+  service: 'firestore' | 'database';
+  target: ActiveListenerTarget;
+  actor: EventActor;
+  authLens: AuthLens;
+  attachedAt: number;
+  deliveryCount: number;
+  suppressedCount: number;
+  lastDeliveryAt?: number;
+  owners?: ListenerOwner[];
+  clientListenerId?: string;
+  query?: unknown;
+}
+
+/**
+ * Every listener the sandbox holds attached right now, folded from its whole
+ * event history. Order is attach order; a listener that detached and
+ * reattached under the same id is folded from its most recent attach.
+ */
+export function activeListeners(events: readonly SandboxEvent[]): readonly ActiveListener[] {
+  const state = createActiveListenerState();
+  for (const event of events) state.append(event);
+  return state.snapshot();
+}
+
+/** The same lifecycle fold, retained by adapters that consume a live stream. */
+export function createActiveListenerState() {
+  const active = new Map<string, ActiveListenerDraft>();
+  const append = (event: SandboxEvent): void => {
+    const info = listenerEventInfo(event);
+    const isOtherEvent = info === null;
+    if (isOtherEvent) return;
+    const attaches = info.phase === 'attach';
+    if (attaches) {
+      const draft: ActiveListenerDraft = {
+        id: info.listenerId,
+        service: info.service,
+        target: info.target,
+        actor: info.actor,
+        authLens: info.authLens,
+        attachedAt: event.at,
+        deliveryCount: 0,
+        suppressedCount: 0,
+      };
+      const hasOwners = info.owners !== undefined;
+      if (hasOwners) draft.owners = [...info.owners];
+      const hasQuery = info.query !== undefined;
+      if (hasQuery) draft.query = info.query;
+      const clientListenerId = (event as { activity?: { listenerId?: unknown } }).activity?.listenerId;
+      const hasClientListener = typeof clientListenerId === 'string';
+      if (hasClientListener) draft.clientListenerId = clientListenerId;
+      active.set(info.listenerId, draft);
+      return;
+    }
+    const entry = active.get(info.listenerId);
+    const isDetached = entry === undefined;
+    if (isDetached) return;
+    const delivers = info.phase === 'delivery';
+    if (delivers) {
+      entry.deliveryCount += 1;
+      entry.lastDeliveryAt = event.at;
+      const hasOwners = info.owners !== undefined;
+      if (hasOwners) entry.owners = withDeliveryOwners(entry.owners, info.owners);
+      return;
+    }
+    const suppresses = info.phase === 'suppressed';
+    if (suppresses) {
+      entry.suppressedCount += 1;
+      return;
+    }
+    // 'detach' and 'errored' both end a listener's active life.
+    active.delete(info.listenerId);
+  };
+  return {
+    append,
+    snapshot: (): readonly ActiveListener[] => Object.freeze([...active.values()].map(entry => Object.freeze({ ...entry }))),
+    clear: (): void => active.clear(),
+  };
+}
+
+/**
+ * A listener's owners after one delivery: the attach-time owners stay, and the
+ * delivery's `regions` replace any earlier regions, since the latest delivery
+ * is the current answer to what the callback paints.
+ */
+function withDeliveryOwners(
+  current: readonly ListenerOwner[] | undefined,
+  delivered: readonly ListenerOwner[],
+): ListenerOwner[] {
+  const regions = delivered.filter((owner) => owner.kind === 'regions');
+  if (regions.length === 0) return [...(current ?? [])];
+  const kept = (current ?? []).filter((owner) => owner.kind !== 'regions');
+  return [...kept, ...regions];
+}
+
+/** Whether a listener's target starts with a caller-supplied prefix. A
+ * query-shaped target is matched on its collection. */
+export function activeListenerTargetStartsWith(
+  target: ActiveListenerTarget,
+  prefix: string,
+): boolean {
+  if (typeof target === 'string') return target.startsWith(prefix);
+  return target.collection.startsWith(prefix);
+}

package/src/sandbox/admin-firestore/error-translation.ts

@@ -93,6 +93,19 @@ export function registerOnSnapshotImpl(fn: OnSnapshotImpl): void {
  * Snapshots, batches, transactions, and the Firestore handle itself
  * carry neither, so the shim correctly skips them.
  */
+/**
+ * Marks a value built by `pyric/firestore`'s modular layer rather than by the
+ * compat impl. Such a value carries its routing in the modular layer's
+ * WeakMaps, so re-wrapping it in this proxy would substitute a fresh object
+ * for the key those maps hold. Registered globally so a src copy and a dist
+ * copy of either layer agree on the marker.
+ */
+const MODULAR_VALUE_SYMBOL = Symbol.for('pyric.firestore.modular-value');
+
+function isModularValue(value: object): boolean {
+  return MODULAR_VALUE_SYMBOL in value;
+}
+
 function isRefLike(obj: object): boolean {
   const o = obj as { path?: unknown; collectionPath?: unknown };
   return (typeof o.path === 'string' && o.path.length > 0)
@@ -152,6 +165,7 @@ export function toSandboxError(err: unknown, ctx: SandboxContext): unknown {
   const sim = err.simError;
   const hasSim = sim !== undefined;
   if (hasSim) {
+    if (sim!.queryProof !== undefined) denialContext.queryProof = sim!.queryProof;
     const hasRequest = sim!.request !== undefined;
     if (hasRequest) {
       const r = sim!.request!;
@@ -255,12 +269,12 @@ export function wrapWithErrorTranslation<T extends object>(
         }
         if (result instanceof Promise) {
           return result
-            .then((v) => (v && typeof v === 'object'
+            .then((v) => (v && typeof v === 'object' && !isModularValue(v as object)
               ? wrapWithErrorTranslation(v as object, ctx, bypassRules)
               : v))
             .catch((e) => { throw toSandboxError(e, ctx); });
         }
-        if (result && typeof result === 'object') {
+        if (result && typeof result === 'object' && !isModularValue(result as object)) {
           return wrapWithErrorTranslation(result as object, ctx, bypassRules);
         }
         return result;

package/src/sandbox/admin-firestore/listeners.ts

@@ -23,6 +23,8 @@
  * any local-engine resolution, since `getInternalEnv` rejects remote
  * handles.
  */
+import { FIRESTORE_ERROR_CODES, type FirestoreSimError } from '../../firestore/sandbox/errors.js';
+import { FirestoreCompatError } from '../../firestore/sandbox/firestore-compat-error.js';
 
 import { SandboxError, type SandboxContext } from 'pyric/sandbox';
 import type {
@@ -36,6 +38,7 @@ import {
   BYPASS_RULES_SYMBOL,
   CONTEXT_SYMBOL,
   registerOnSnapshotImpl,
+  toSandboxError,
 } from './error-translation.js';
 import { getRemoteSnapshotRegistrar, registerRemoteOnSnapshotImpl } from './remote/listeners.js';
 import type { SnapshotObserver, Unsubscribe } from './types.js';
@@ -329,7 +332,7 @@ export function onSnapshot(
     onNext ?? (() => {}),
     options,
     ctx.auth,
-    onError,
+    onError ? (error) => onError(translateListenerError(error, ctx)) : undefined,
     followsCurrentUser,
     bypassRules,
     authScope,
@@ -395,3 +398,25 @@ function contextFromRef(ref: unknown): SandboxContext {
 // function (a static import back from remote/listeners.ts would be a cycle).
 registerOnSnapshotImpl(onSnapshot as (ref: unknown, ...args: unknown[]) => () => void);
 registerRemoteOnSnapshotImpl(onSnapshot as (ref: unknown, ...args: unknown[]) => () => void);
+
+/** The engine also accepts foreign listener errors; translate only its coded records. */
+function isSimError(error: unknown): error is FirestoreSimError {
+  return typeof error === 'object' && error !== null
+    && 'code' in error && FIRESTORE_ERROR_CODES.some(code => code === error.code)
+    && 'message' in error && typeof error.message === 'string';
+}
+
+function translateListenerError(error: unknown, ctx: SandboxContext): unknown {
+  if (!isSimError(error) || error.queryProof === undefined) return error;
+  const translated = toSandboxError(new FirestoreCompatError(error), {
+    ...ctx, auth: error.request ? error.request.auth : ctx.auth,
+  });
+  if (translated instanceof Error) {
+    // Existing listener consumers read these directly. Keep those aliases
+    // alongside the structured context used by worker serialization.
+    for (const field of ['request', 'resource', 'query', 'rule', 'queryProof'] as const) {
+      if (error[field] !== undefined) Object.assign(translated, { [field]: error[field] });
+    }
+  }
+  return translated;
+}

package/src/sandbox/admin-firestore/remote/listeners.ts

@@ -83,48 +83,66 @@ export function registerRemoteListener(
   // same way the local listener path does.
   let prevDocs: Array<{ path: string; data: DocumentData }> | undefined;
 
+  function reportError(error: unknown): void {
+    const translated = toRemoteSandboxError(error);
+    const hasErrorCallback = onError !== undefined;
+    if (hasErrorCallback) onError(translated);
+    else console.error('pyric remote Firestore: uncaught onSnapshot error:', translated);
+  }
+
   let detach: () => void;
   try {
     detach = arm.sandbox.channel.subscribe(
       { target, actAs: arm.lens },
       (value) => {
-        if (!onNext) return;
-        const snap = value as Partial<WireDocSnap> & Partial<WireQuerySnap>;
-        if (Array.isArray(snap.docs)) {
-          // Query fire. `buildQuerySnapshot` translates the internal-form
-          // data to compat shapes itself, so decode WITHOUT translation.
-          const docList = snap.docs.map((row) => ({
-            path: row.path ?? row.id,
-            data: row.data ? decodeInternal(row.data) : {},
-          }));
-          const queryPath = target.__ref === 'query'
-            ? (target.source.__ref === 'group' ? target.source.collectionId : target.source.path)
-            : target.__ref === 'group'
-              ? target.collectionId
-              : target.path;
-          const querySnap = buildQuerySnapshot(
-            { path: queryPath },
-            docList,
-            { excludesMetadataChanges },
-            prevDocs,
-          );
-          prevDocs = docList;
-          onNext(querySnap);
-        } else if (typeof snap.id === 'string') {
-          // Doc fire.
-          const path = snap.path ?? snap.id;
-          const data = snap.exists && snap.data ? decodeInternal(snap.data) : null;
-          onNext(buildDocumentSnapshot(path, data));
+        const hasNoCallback = onNext === undefined;
+        if (hasNoCallback) return;
+        let decoded: unknown;
+        try {
+          const snap = value as Partial<WireDocSnap> & Partial<WireQuerySnap>;
+          const documents = snap.docs;
+          const isQuery = Array.isArray(documents);
+          if (isQuery) {
+            const docList = documents.map((row) => {
+              const data = row.data;
+              const hasData = data !== undefined;
+              return { path: row.path ?? row.id, data: hasData ? decodeInternal(data) : {} };
+            });
+            decoded = buildQuerySnapshot(
+              { path: listenerTargetPath(target) }, docList, { excludesMetadataChanges }, prevDocs,
+            );
+            prevDocs = docList;
+          } else {
+            const id = snap.id;
+            const isDocument = typeof id === 'string';
+            if (isDocument) {
+              const path = snap.path ?? id;
+              const serialized = snap.data;
+              const hasData = snap.exists === true && serialized !== undefined;
+              const data = hasData ? decodeInternal(serialized) : null;
+              decoded = buildDocumentSnapshot(path, data);
+            }
+          }
+        } catch (error) {
+          detach();
+          reportError(error);
+          return;
         }
+        const hasSnapshot = decoded !== undefined;
+        if (hasSnapshot) onNext(decoded);
       },
-      (err) => {
-        const translated = toRemoteSandboxError(err);
-        if (onError) onError(translated);
-        else console.error('pyric remote Firestore: uncaught onSnapshot error:', translated);
-      },
+      reportError,
     );
   } catch (e) {
     throw toRemoteSandboxError(e);
   }
   return detach;
 }
+
+function listenerTargetPath(target: WireTarget): string {
+  switch (target.__ref) {
+    case 'query': return listenerTargetPath(target.source);
+    case 'group': return target.collectionId;
+    default: return target.path;
+  }
+}

package/src/sandbox/admin-firestore/remote/value-codec.ts

@@ -10,25 +10,18 @@
  * the worker STORES real typed values (rules comparisons and `orderBy`
  * see a Timestamp, not a map). Read payloads arrive as the
  * `SerializedDocData` JSON envelope and are rehydrated with the ONE shared
- * codec (`pyric/firestore/internal/value-codec`'s `rehydrateDocValue`) then
+ * codec (`pyric/firestore/internal/value-codec`) under the reply's encoding, then
  * translated to
  * the compat field shapes (`translateReadData`) — the same shapes the
  * local arm's read path yields.
  *
- * KNOWN CODEC DIVERGENCE (accepted): user data that happens to be SHAPED
- * like a codec marker — a plain map such as `{ __type: 'timestamp',
- * seconds, nanos }` or `{ type: 'firestore/timestamp/1.0', … }` — is
- * TRANSMUTED into the real typed value on the relayed path (the host's
- * `prepareWriteData` / constraint rehydration cannot tell an intentional
- * marker from a lookalike), while an in-page `setDoc` of the same map
- * stores a plain map. This is the persistence codec's own behavior (an
- * IndexedDB save/reload transmutes the same shapes), so the relay is
- * consistent with the sandbox's durability semantics rather than with
- * the in-page live path — marker-shaped user data is already reserved
- * vocabulary in this system.
+ * Legacy remote writes still reserve scalar-marker shapes. They do not yet
+ * declare the newer map-safe value encoding. Reads honor the returned
+ * envelope's encoding through the shared codec. Adopting explicit encoding
+ * for remote writes and migrating persistence remain required work.
  */
 
-import { rehydrateDocValue } from 'pyric/firestore/internal/value-codec';
+import { rehydrateEncodedDocValue } from 'pyric/firestore/internal/value-codec';
 import {
   Timestamp as CompatTimestamp,
   type DocumentData,
@@ -123,7 +116,7 @@ export function encodeWriteData(data: DocumentData): unknown {
  *  their RULES-INTERNAL wrapper form (what the local engine stores). Used
  *  where a downstream helper does its own compat translation. */
 export function decodeInternal(serialized: WireDocData): DocumentData {
-  return rehydrateDocValue(JSON.parse(serialized.json)) as DocumentData;
+  return rehydrateEncodedDocValue(JSON.parse(serialized.json), serialized.valueEncoding) as DocumentData;
 }
 
 /** Full read-path decode: shared codec rehydration + the same

package/src/sandbox/admin-firestore/remote/wire-types.ts

@@ -5,6 +5,8 @@
  * structurally identical to `packages/cli/src/serve/worker/protocol.ts`.
  */
 
+import type { DocValueEncoding } from 'pyric/firestore/internal/value-codec';
+
 /** Wire form of a doc/collection/group/query target. Mirrors
  *  `@pyric/cli`' `TargetDescriptor` — plain JSON, spelled loosely here
  *  because `pyric` cannot import the protocol module. */
@@ -41,6 +43,7 @@ export type WireWrite =
 
 /** Mirrors the protocol's `SerializedDocData` — the JSON string envelope. */
 export interface WireDocData {
+  valueEncoding?: DocValueEncoding;
   json: string;
 }
 

package/src/sandbox/attribution/attribution-mode.ts

@@ -0,0 +1,74 @@
+/**
+ * The switch that decides whether listener attribution runs.
+ *
+ * Attribution is a development diagnostic: it constructs one `Error` per
+ * listener attach to read a stack, and installs one `MutationObserver` around
+ * each snapshot callback. Neither cost belongs in a production build, and
+ * neither result has a consumer there, so attribution is off whenever the
+ * environment says production.
+ *
+ * Two production signals are read, in this order, because the mirror runs in
+ * two runtimes:
+ *
+ * 1. `import.meta.env.PROD`, which a browser bundler substitutes at build
+ *    time. This is the signal that survives into a shipped bundle, where no
+ *    `process` exists.
+ * 2. `process.env.NODE_ENV === 'production'`, the marker the rest of this
+ *    repository already treats as "this is production" (the CLI's Next.js
+ *    passthrough guard and the `@pyric/cli/register` refusal both read it).
+ *
+ * A caller that wants attribution regardless of either signal turns it on
+ * explicitly through {@link configureListenerAttribution}, which overrides
+ * both. That is the "explicit option" path: a production-mode test harness, or
+ * a host that wants attribution in a build the bundler marked production.
+ */
+
+const PRODUCTION_ENVIRONMENT = 'production';
+
+/**
+ * How the switch decides. `'auto'` reads the environment; `'on'` and `'off'`
+ * are explicit caller overrides that ignore it.
+ */
+export type ListenerAttributionMode = 'auto' | 'on' | 'off';
+
+let mode: ListenerAttributionMode = 'auto';
+
+/** Override the environment decision. Pass `'auto'` to hand it back. */
+export function configureListenerAttribution(next: ListenerAttributionMode): void {
+  mode = next;
+}
+
+/** The override currently in force. `'auto'` means the environment decides. */
+export function listenerAttributionMode(): ListenerAttributionMode {
+  return mode;
+}
+
+/**
+ * `true` when the bundler stamped this build as production. Read through a
+ * cast and a try/catch because `import.meta.env` exists only under a bundler,
+ * and a plain Node ESM runtime leaves it undefined.
+ */
+function isBundledProduction(): boolean {
+  try {
+    const env = (import.meta as { env?: { PROD?: boolean } }).env;
+    return env?.PROD === true;
+  } catch {
+    return false;
+  }
+}
+
+/** `true` when the host process declares itself production. */
+function isProcessProduction(): boolean {
+  const runtime = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
+  if (runtime === undefined) return false;
+  return runtime.env?.NODE_ENV === PRODUCTION_ENVIRONMENT;
+}
+
+/** Whether listener attribution should run right now. */
+export function listenerAttributionEnabled(): boolean {
+  if (mode === 'on') return true;
+  if (mode === 'off') return false;
+  if (isBundledProduction()) return false;
+  if (isProcessProduction()) return false;
+  return true;
+}