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

package/src/firestore/sandbox/document-store.ts

@@ -0,0 +1,108 @@
+/** Contracts shared by Firestore document stores and atomic state application. */
+export type DocumentData = Record<string, unknown>;
+
+/** One row from a {@link DocStore} scan/list. */
+export interface DocEntry {
+  path: string;
+  data: DocumentData;
+  /** Synthesized parent of deeper descendants (no stored doc of its own). */
+  phantom?: true;
+}
+
+/** Options for {@link DocStore.scan}. */
+export interface ScanOptions {
+  /** Only direct children of the prefix (a collection scan), not all descendants. */
+  directOnly?: boolean;
+  /** Synthesize phantom-parent entries for paths whose parent has no stored doc. */
+  phantoms?: boolean;
+  /** Project each emitted doc's data down to only these top-level fields (others
+   *  omitted), so callers can skip large fields like vectors. Phantoms stay `{}`. */
+  projection?: readonly string[];
+}
+
+/**
+ * The store seam over the document keyspace. Everything that touches documents
+ * (queries, listeners, the worker, branches, writes, undo) goes through this
+ * contract rather than a raw Map, so the backing store can be swapped (a CoW
+ * overlay for branches, chunked persistence) without touching the callers.
+ * `scan` is the single read-iteration primitive; `list` builds on it.
+ * Synchronous by design: the rules simulator consumes pre-resolved reads, so the
+ * read path cannot go async.
+ */
+export interface DocStore {
+  // Reads
+  get(path: string): DocumentData | null;
+  /** Monotonic local write version used for optimistic transaction checks. */
+  version(path: string): number;
+  /** Latest version allocated anywhere in this store. */
+  currentVersion(): number;
+  exists(path: string): boolean;
+  scan(prefix: string, opts?: ScanOptions): DocEntry[];
+  list(collection: string): DocEntry[];
+  listRootCollections(): string[];
+  listSubcollections(docPath: string): string[];
+  snapshot(): Record<string, DocumentData>;
+  size(): number;
+  // Writes
+  create(path: string, data: DocumentData): CreateResult;
+  update(path: string, data: DocumentData): UpdateResult;
+  set(path: string, data: DocumentData): SetResult;
+  setMerge(path: string, data: DocumentData, mergeFields?: readonly string[]): SetResult;
+  delete(path: string): DeleteResult;
+  applyBatch(operations: BatchOperation[]): BatchResult;
+  // Undo support
+  restore(snapshot: Record<string, DocumentData>): void;
+  restorePaths(priorDocs: Record<string, DocumentData | null>): void;
+}
+
+/**
+ * The raw key->doc backing under {@link LocalState}: the subset of `Map` the
+ * store uses. A plain `Map` satisfies it (the default); branches inject an
+ * `OverlayBacking` for copy-on-write over an immutable base, so the store's
+ * read/write/merge logic is reused unchanged over either backing.
+ */
+export interface DocBacking {
+  get(path: string): DocumentData | undefined;
+  set(path: string, data: DocumentData): void;
+  has(path: string): boolean;
+  delete(path: string): boolean;
+  clear(): void;
+  keys(): IterableIterator<string>;
+  readonly size: number;
+  [Symbol.iterator](): IterableIterator<[string, DocumentData]>;
+}
+
+export interface CreateResult {
+  success: boolean;
+  error?: string;
+}
+
+export interface UpdateResult {
+  success: boolean;
+  error?: string;
+  priorData?: DocumentData;
+}
+
+export interface SetResult {
+  success: true;
+  priorData: DocumentData | null;
+  created: boolean;
+}
+
+export interface DeleteResult {
+  success: boolean;
+  error?: string;
+  priorData?: DocumentData;
+}
+
+export interface BatchOperation {
+  method: 'create' | 'update' | 'set' | 'delete';
+  path: string;
+  data?: DocumentData;
+}
+
+export interface BatchResult {
+  success: boolean;
+  errors?: { index: number; error: string }[];
+  priorStates?: Map<string, DocumentData | null>;
+}

package/src/firestore/sandbox/errors.ts

@@ -23,6 +23,7 @@
  * `unauthenticated`) are reserved so adding their wiring later is a
  * pure callsite change, no error-set churn.
  */
+import type { QueryProofDiagnostic } from '../../sandbox/types/query-proof.js';
 
 export const FIRESTORE_ERROR_CODES = [
   'permission-denied',
@@ -70,6 +71,7 @@ export interface FirestoreEvalResource {
 }
 
 export interface FirestoreSimError {
+  queryProof?: QueryProofDiagnostic;
   code: FirestoreErrorCode;
   message: string;
   /**
@@ -121,7 +123,7 @@ export interface QueryDenialDescriptor {
   readonly where?: readonly {
     readonly field: string;
     readonly op: string;
-    readonly value: string | number | boolean | null;
+    readonly value: string | number | boolean | null | readonly (string | number | boolean | null)[];
   }[];
   readonly limit?: number | null;
   readonly offset?: number | null;
@@ -138,6 +140,7 @@ export function makeError(
   code: FirestoreErrorCode,
   message: string,
   extras?: {
+    queryProof?: QueryProofDiagnostic;
     request?: FirestoreEvalRequest;
     resource?: FirestoreEvalResource;
     remediation?: string;
@@ -155,6 +158,7 @@ export function makeError(
   const out: FirestoreSimError = { code, message };
   const hasExtras = extras !== undefined;
   if (hasExtras) {
+    if (extras!.queryProof !== undefined) out.queryProof = extras!.queryProof;
     const hasRequest = extras!.request !== undefined;
     if (hasRequest) {
       out.request = extras!.request;

package/src/firestore/sandbox/event-log.ts

@@ -1,10 +1,13 @@
 /**
- * Event Log — append-only audit trail for the local environment.
+ * Event Log — bounded audit and undo history for the local environment.
  *
- * Every operation (allowed or denied) is recorded. Undo is implemented
+ * Operations (allowed or denied) are retained within count and byte limits. Undo is implemented
  * via state snapshots — no need to replay events.
  */
 import type { DocumentData } from './local-state.js';
+import { encodedBytes, type EventHistoryLimits } from '../../sandbox/internal/history-retention.js';
+import { OBSERVATION_HISTORY_LIMITS } from '../../sandbox/internal/observation-history.js';
+import { SandboxClock } from '../../sandbox/clock.js';
 
 export interface AgentEvent {
   id: number;
@@ -60,24 +63,46 @@ export interface AgentEvent {
   debugMessages: string[];
 }
 
+export interface EventLogRetention {
+  retainedEvents: number;
+  retainedBytes: number;
+  omittedCount: number;
+}
+
 export class EventLog {
   private events: AgentEvent[] = [];
   private nextId = 1;
   private undoneEvents: AgentEvent[] = [];
+  private readonly eventBytes = new Map<number, number>();
+  private retainedBytes = 0;
+  private omittedCount = 0;
+
+  /** @param clock The sandbox clock every appended entry is stamped from. */
+  constructor(
+    private readonly clock: SandboxClock = new SandboxClock(),
+    private readonly limits: EventHistoryLimits = OBSERVATION_HISTORY_LIMITS,
+  ) {}
 
   /** Append an event. Clears redo stack unless preserveRedo is true. */
   append(event: Omit<AgentEvent, 'id' | 'timestamp'>, preserveRedo = false): AgentEvent {
     const full: AgentEvent = {
       ...event,
       id: this.nextId++,
-      timestamp: new Date().toISOString(),
+      timestamp: new Date(this.clock.now()).toISOString(),
     };
+    if (!preserveRedo) {
+      for (const undone of this.undoneEvents) this.release(undone);
+      this.undoneEvents = [];
+    }
     this.events.push(full);
-    if (!preserveRedo) this.undoneEvents = [];
+    const bytes = encodedBytes(full) + 1;
+    this.eventBytes.set(full.id, bytes);
+    this.retainedBytes += bytes;
+    this.prune();
     return full;
   }
 
-  /** Get all events. */
+  /** Get retained events in their original order. */
   getEvents(): AgentEvent[] {
     return [...this.events];
   }
@@ -117,10 +142,47 @@ export class EventLog {
 
   /** Get the last undone event (for redo). */
   popLastUndo(): AgentEvent | null {
-    return this.undoneEvents.pop() ?? null;
+    const event = this.undoneEvents.pop();
+    if (!event) return null;
+    this.release(event);
+    return event;
+  }
+
+  /** Shared accounting for the visible log and redo stack. */
+  getRetention(): EventLogRetention {
+    return {
+      retainedEvents: this.eventBytes.size,
+      retainedBytes: this.retainedBytes,
+      omittedCount: this.omittedCount,
+    };
+  }
+
+  private release(event: AgentEvent): void {
+    this.retainedBytes -= this.eventBytes.get(event.id) ?? 0;
+    this.eventBytes.delete(event.id);
+    // An unserializable event has infinite estimated size; removing the final
+    // retained entry must reset accounting rather than leave Infinity - Infinity.
+    const isEmpty = this.eventBytes.size === 0;
+    if (isEmpty) this.retainedBytes = 0;
+  }
+
+  private prune(): void {
+    const exceedsBudget = () => this.eventBytes.size > this.limits.maxEvents
+      || this.retainedBytes > this.limits.maxBytes;
+    while (exceedsBudget()) {
+      // Accounting preserves append order even when undo/redo reorders stacks.
+      const oldestId = this.eventBytes.keys().next().value;
+      const oldestIsUndone = this.events[0]?.id !== oldestId;
+      const entries = oldestIsUndone ? this.undoneEvents : this.events;
+      const index = oldestIsUndone ? entries.findIndex(event => event.id === oldestId) : 0;
+      const [omitted] = entries.splice(index, 1);
+      if (!omitted) break;
+      this.release(omitted);
+      this.omittedCount++;
+    }
   }
 
-  /** Total event count. */
+  /** Visible event count; undone events remain accounted in getRetention(). */
   size(): number {
     return this.events.length;
   }
@@ -130,5 +192,8 @@ export class EventLog {
     this.events = [];
     this.undoneEvents = [];
     this.nextId = 1;
+    this.eventBytes.clear();
+    this.retainedBytes = 0;
+    this.omittedCount = 0;
   }
 }

package/src/firestore/sandbox/field-merge.ts

@@ -36,6 +36,8 @@ import {
   stripMarkers,
   type DocumentData,
 } from './value-resolver.js';
+import { FirebaseError } from '../../sandbox/internal/firebase-error.js';
+import { cloneDoc } from './document-copy.js';
 
 /** Split a dot-separated FieldPath string into segments. */
 function splitPath(key: string): string[] {
@@ -63,22 +65,6 @@ function assertSafeSegment(seg: string): void {
   }
 }
 
-/** Deep clone a plain document tree, leaving class instances by reference
- *  (Timestamp, Bytes, etc. are immutable wrappers — safe to share). */
-function cloneDoc(data: DocumentData): DocumentData {
-  const out: DocumentData = {};
-  for (const [k, v] of Object.entries(data)) {
-    out[k] = cloneValue(v);
-  }
-  return out;
-}
-
-function cloneValue(v: unknown): unknown {
-  if (Array.isArray(v)) return v.map(cloneValue);
-  if (isPlainObject(v)) return cloneDoc(v);
-  return v;
-}
-
 /**
  * Navigate to the parent map of `segments`, creating (or replacing
  * non-map intermediates with) plain maps along the way, then set or
@@ -185,13 +171,18 @@ export function applyMerge(
   const out = cloneDoc(existing);
   const mask: Array<{ segments: string[]; value: unknown }> = [];
 
-  if (mergeFields !== undefined) {
+  const hasFieldMask = mergeFields !== undefined;
+  if (hasFieldMask) {
     // Restrict to the listed field paths. Each is a dot-separated path
-    // into `resolved`; read the value at that path (skip absent ones).
+    // into `resolved` and must be present in the supplied data.
     for (const field of mergeFields) {
       const segments = splitPath(field);
       const value = readPath(resolved, segments);
-      if (value !== ABSENT) mask.push({ segments, value });
+      const isMissing = value === ABSENT;
+      if (isMissing) {
+        throw new FirebaseError('invalid-argument', `Field '${field}' is specified in your field mask but missing from your input data.`);
+      }
+      mask.push({ segments, value });
     }
   } else {
     collectLeaves(resolved, [], mask);

package/src/firestore/sandbox/history-controls.ts

@@ -86,7 +86,7 @@ export class HistoryControls {
     };
   }
 
-  /** Get all events. */
+  /** Get retained events in their original order. */
   getEvents(): AgentEvent[] {
     return this.eventLog.getEvents();
   }

package/src/firestore/sandbox/list-query-proof.ts

@@ -30,6 +30,7 @@
  * `resource.data` access the equalities do NOT pin errors in the evaluator
  * and the rule denies — the conservative (prod-safe) direction.
  */
+import type { QueryProofFailure } from '../../sandbox/types/query-proof.js';
 import {
   collectMatches,
   evaluateQueryProof,
@@ -63,14 +64,15 @@ export type ListProofVerdict =
    *  document and contains only query-pinned equality fields. */
   | {
       kind: 'provable';
+      failures: QueryProofFailure[];
       evaluationAst: FirestoreRules;
       syntheticResource: Record<string, unknown>;
     }
   /** Every matching rule depends on per-document data the query's
-   *  constraints cannot guarantee — prod rejects the WHOLE query.
+   *  constraints cannot prove safe — Pyric rejects the whole query.
    *  `residual` is the structured account (missing / mismatched equalities,
    *  or an out-of-scope shape) that the denial site renders remediation from. */
-  | { kind: 'unprovable'; reason: string; residual: QueryProofResidual; rule?: EvaluatedRuleInfo }
+  | { kind: 'unprovable'; failures: QueryProofFailure[]; reason: string; residual: QueryProofResidual; rule?: EvaluatedRuleInfo }
   /** No match block / no list rules — let simulate() default-deny exactly
    *  as it does today (the proof has nothing to add). */
   | { kind: 'no-rule' };
@@ -112,8 +114,8 @@ export function proveListQuery(
   // OR semantics across allow rules: ANY provable rule makes the query
   // provable. Residual simulation receives ONLY those provable rules, so an
   // unprovable sibling cannot grant from a concrete placeholder document.
-  const failures: { reason: string; residual: QueryProofResidual; rule?: AllowRule }[] = [];
-  const provableRules = new Set<AllowRule>();
+  const failures: QueryProofFailure[] = [];
+  const provableRules = new Map<AllowRule, AllowRule>();
   let applicableRuleCount = 0;
   for (const match of matches) {
     const functionScope = buildListRuleFunctionScope(match.functions);
@@ -140,9 +142,10 @@ export function proveListQuery(
       const isInvariant = pathAnalysis.pathInvariant === true;
       if (isInvariant === false) {
         failures.push({
+          kind: 'unsupported-path',
           reason: 'list rule depends on the candidate document path',
           residual: { missing: [], mismatched: [] },
-          rule,
+          rule: proofRuleInfo(rule, sourceString),
         });
         continue;
       }
@@ -152,9 +155,17 @@ export function proveListQuery(
       const result = evaluateQueryProof(rule.condition, constraints, fnMap, auth?.uid);
       const isProvable = result.provable === true;
       if (isProvable) {
-        provableRules.add(rule);
-      } else {
-        failures.push({ reason: result.reason, residual: result.residual, rule });
+        provableRules.set(rule, result.residualCondition ? {...rule, condition: result.residualCondition} : rule);
+      }
+      const failure = result.provable ? result.proofFailure : result;
+      if (failure) {
+        failures.push({
+          kind: failure.kind, reason: failure.reason, residual: failure.residual,
+          rule: proofRuleInfo(rule, sourceString),
+          ...(failure.residual.predicate ? { predicate: proofSourceInfo(
+            failure.residual.predicate, failure.residual.predicateLoc ?? rule.loc, sourceString,
+          ) } : {}),
+        });
       }
     }
   }
@@ -164,87 +175,47 @@ export function proveListQuery(
   }
   const isProvableEmpty = provableRules.size === 0;
   if (isProvableEmpty) {
-    const first = failures[0];
-    let reason = 'list rule depends on per-document data the query cannot guarantee';
-    let residual: QueryProofResidual = { missing: [], mismatched: [] };
-    let ruleInfo: EvaluatedRuleInfo | undefined = undefined;
-    const isFirstDefined = first !== undefined;
-    if (isFirstDefined) {
-      reason = first!.reason;
-      residual = first!.residual;
-      const hasRule = first!.rule !== undefined;
-      if (hasRule) {
-        const r = first!.rule!;
-        const condText = printExpression(r.condition);
-        ruleInfo = { verdict: 'deny', expression: condText };
-        const hasLoc = r.loc !== undefined;
-        if (hasLoc) {
-          const loc = r.loc!;
-          let sourceStr = '';
-          const hasSourceStr = sourceString !== undefined;
-          if (hasSourceStr) {
-            sourceStr = sourceString!;
-          }
-          const authored = resolveAuthoredSourceLoc(sourceStr, loc.line, loc.col, loc.file, condText);
-          const hasAuthored = authored !== undefined;
-          if (hasAuthored) {
-            ruleInfo.line = authored!.line;
-            ruleInfo.col = authored!.col;
-            ruleInfo.column = authored!.col;
-            ruleInfo.file = authored!.file;
-            ruleInfo.citation = authored!.citation;
-            const hasAuthoredExpr = authored!.expression !== undefined;
-            if (hasAuthoredExpr) {
-              ruleInfo.expression = authored!.expression;
-            }
-          } else {
-            ruleInfo.line = loc.line;
-            ruleInfo.col = loc.col;
-            ruleInfo.column = loc.col;
-            const hasFile = loc.file !== undefined;
-            if (hasFile) {
-              ruleInfo.file = loc.file;
-              ruleInfo.citation = `${loc.file}:${loc.line}:${loc.col}`;
-            } else {
-              ruleInfo.file = 'firestore.rules';
-              ruleInfo.citation = `firestore.rules:${loc.line}:${loc.col}`;
-            }
-          }
-        }
-      }
-    }
-    const unprovableVerdict: {
-      kind: 'unprovable';
-      reason: string;
-      residual: QueryProofResidual;
-      rule?: EvaluatedRuleInfo;
-    } = {
+    const first = failures[0]!;
+    return {
       kind: 'unprovable',
-      reason,
-      residual,
+      failures,
+      reason: first.reason,
+      residual: first.residual,
+      ...(first.rule ? { rule: { ...first.rule, verdict: 'deny' as const } } : {}),
     };
-    const hasRuleInfo = ruleInfo !== undefined;
-    if (hasRuleInfo) {
-      unprovableVerdict.rule = ruleInfo;
-    }
-    return unprovableVerdict;
   }
+
   return {
     kind: 'provable',
+    failures,
     evaluationAst: projectRules(ast!, provableRules),
     syntheticResource: syntheticResourceFromWheres(constraints),
   };
 }
 
+/** Resolve against authored source before assembly removes rejected siblings. */
+function proofRuleInfo(rule: AllowRule, source = ''): NonNullable<QueryProofFailure['rule']> {
+  return proofSourceInfo(printExpression(rule.condition), rule.loc, source);
+}
+
+function proofSourceInfo(expression: string, loc: AllowRule['loc'], source = ''): NonNullable<QueryProofFailure['rule']> {
+  if (!loc) return { expression };
+  const { line, col, file } = loc;
+  const authored = resolveAuthoredSourceLoc(source, line, col, file, expression);
+  if (authored) return { ...authored, column: authored.col, expression: authored.expression ?? expression };
+  return { line, col, column: col, file: file ?? 'firestore.rules',
+    citation: `${file ?? 'firestore.rules'}:${line}:${col}`, expression };
+}
+
 // ─── Proof/execution projection ──────────────────────────────────
 
 /** Preserve match paths and helper scopes while removing every rule the
  * static proof did not approve. This keeps residual execution and proof on
  * the exact same set of potentially granting rules. */
-function projectRules(ast: FirestoreRules, retained: ReadonlySet<AllowRule>): FirestoreRules {
+function projectRules(ast: FirestoreRules, retained: ReadonlyMap<AllowRule, AllowRule>): FirestoreRules {
   const projectBlock = (block: MatchBlock): MatchBlock => ({
     ...block,
-    allows: block.allows.filter((rule) => retained.has(rule)),
+    allows: block.allows.filter((rule) => retained.has(rule)).map(rule => retained.get(rule)!),
     children: block.children.map(projectBlock),
   });
   return {

package/src/firestore/sandbox/listener-dispatch.ts

@@ -35,10 +35,14 @@ import { nextRequestEventId } from './request-events.js';
 import type { FirestoreEventBus } from './event-bus.js';
 import type { TriggerScope } from './trigger-scope.js';
 import type {
+  ListenerOwner,
   SnapshotDeliveryEvent,
   SnapshotSuppressedEvent,
   ListenerLifecycleEvent,
 } from '../../sandbox/types/events.js';
+import { listenerAttachOwners } from '../../sandbox/attribution/listener-owners.js';
+import { recordEffectRegions } from '../../sandbox/attribution/effect-regions.js';
+import { SandboxClock } from '../../sandbox/clock.js';
 
 /**
  * The engine capabilities listener dispatch needs — nothing more. Both are
@@ -96,14 +100,49 @@ export class ListenerDispatch {
   private deliveryQueue: Array<() => void> = [];
   private deliveryScheduled = false;
 
+  /**
+   * Effect attribution for the delivery currently being emitted, keyed by
+   * listener id. The instrumented callback writes the entry while the user
+   * callback runs; the delivery event that follows on the same synchronous
+   * stack takes it back out. One entry per listener at most, cleared on
+   * every invocation and on detach, so a suppressed or errored re-eval can
+   * never publish a previous delivery's regions.
+   */
+  private deliveryOwners: Map<string, ListenerOwner[]> = new Map();
+
   constructor(
     private readonly events: FirestoreEventBus,
     private readonly triggerScope: TriggerScope,
     private readonly host: ListenerDispatchHost,
+    /** The sandbox's clock, read for every server-set time this produces.
+     *  Defaults to a private wall clock for a standalone construction. */
+    private readonly clock: SandboxClock = new SandboxClock(),
   ) {}
 
   // ═══ Listener-owned event payloads ═══
 
+  /**
+   * Wrap a user callback so each invocation's DOM effects are observed and
+   * staged for the delivery event that follows it. The wrapper adds no
+   * asynchrony and swallows nothing: whatever the callback throws still
+   * propagates to the existing try/catch at the call site.
+   */
+  private instrumentCallback(id: string, callback: SnapshotCallback): SnapshotCallback {
+    return (snapshot: unknown) => {
+      this.deliveryOwners.delete(id);
+      const regions = recordEffectRegions(() => callback(snapshot));
+      if (regions === undefined) return;
+      this.deliveryOwners.set(id, [regions]);
+    };
+  }
+
+  /** Take the staged effect attribution for `listenerId`, clearing it. */
+  private takeDeliveryOwners(listenerId: string): ListenerOwner[] | undefined {
+    const owners = this.deliveryOwners.get(listenerId);
+    this.deliveryOwners.delete(listenerId);
+    return owners;
+  }
+
   private emitSnapshotDelivery(input: {
     listenerId: string;
     target: SnapshotDeliveryEvent['target'];
@@ -115,11 +154,12 @@ export class ListenerDispatch {
     sample?: { docs: Array<{ path: string; data: Record<string, unknown> | null }> };
     triggeredBy?: { method: string; path: string };
   }): void {
+    const owners = this.takeDeliveryOwners(input.listenerId);
     if (!this.events.delivery.hasSubscribers) return;
     const event: SnapshotDeliveryEvent = {
       kind: 'snapshot_delivery',
       id: nextRequestEventId().replace(/^req-/, 'snd-'),
-      at: Date.now(),
+      at: this.clock.now(),
       listenerId: input.listenerId,
       target: input.target,
       auth: input.auth
@@ -132,6 +172,9 @@ export class ListenerDispatch {
       ...(input.sample ? { sample: input.sample } : {}),
       ...(input.triggeredBy ? { triggeredBy: input.triggeredBy } : {}),
     };
+    if (owners !== undefined) {
+      event.owners = owners;
+    }
     this.events.delivery.emit(event);
   }
 
@@ -145,7 +188,7 @@ export class ListenerDispatch {
     const event: SnapshotSuppressedEvent = {
       kind: 'snapshot_suppressed',
       id: nextRequestEventId().replace(/^req-/, 'sup-'),
-      at: Date.now(),
+      at: this.clock.now(),
       listenerId: input.listenerId,
       target: input.target,
       auth: input.auth
@@ -162,18 +205,22 @@ export class ListenerDispatch {
     listenerId: string;
     target: ListenerLifecycleEvent['target'];
     auth: ListenerAuth;
+    owners?: ListenerOwner[];
   }): void {
     if (!this.events.lifecycle.hasSubscribers) return;
     const event: ListenerLifecycleEvent = {
       kind: input.phase,
       id: nextRequestEventId().replace(/^req-/, 'lc-'),
-      at: Date.now(),
+      at: this.clock.now(),
       listenerId: input.listenerId,
       target: input.target,
       auth: input.auth
         ? { uid: input.auth.uid, ...(input.auth.token ? { token: input.auth.token } : {}) }
         : null,
     };
+    if (input.owners !== undefined) {
+      event.owners = input.owners;
+    }
     this.events.lifecycle.emit(event);
   }
 
@@ -223,10 +270,15 @@ export class ListenerDispatch {
     authScope?: object,
   ): () => void {
     const id = String(this.nextListenerId++);
+    // One `Error` construction per attach, on the caller's own stack, the
+    // only place the application frame is still reachable. A caller reaching
+    // the sandbox across a port sends `options.owners` instead: its stack and
+    // its DOM are on the other side, and this one describes neither.
+    const attachOwners = listenerAttachOwners(options.owner, options.owners);
     const record: ListenerRecord = {
       id,
       target,
-      callback,
+      callback: this.instrumentCallback(id, callback),
       auth,
       bypassRules,
       followsCurrentUser,
@@ -253,6 +305,7 @@ export class ListenerDispatch {
               : {}),
           },
       auth,
+      owners: attachOwners,
     });
 
     // Items 3 + 5 — the initial snapshot is delivered off-stack through the
@@ -273,6 +326,7 @@ export class ListenerDispatch {
     return () => {
       const stillRegistered = this.snapshotListeners.has(id);
       this.snapshotListeners.delete(id);
+      this.deliveryOwners.delete(id);
       // Only emit detach if the listener was actually registered when
       // the unsubscribe was called. Idempotent calls and listeners
       // dropped by `reset()` don't double-emit.
@@ -933,6 +987,7 @@ export class ListenerDispatch {
    */
   dispose(): void {
     this.snapshotListeners.clear();
+    this.deliveryOwners.clear();
     this.deliveryQueue.length = 0;
     this.deliveryScheduled = false;
   }