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

package/src/database/operations.ts

@@ -1,7 +1,10 @@
+import { runSdkWrite } from '../sandbox/internal/sdk-write-activity.js';
 import { generatePushId } from './sandbox/push-id.js';
 import { joinPath, pathSegments, type JsonValue } from './sandbox/data-tree.js';
 import { authFor, targetOf } from './routing.js';
 import { isQuery } from './query-shape.js';
+import { finishSdkRead } from '../sandbox/internal/sdk-activity.js';
+import { beginDatabaseActivity } from './sdk-activity.js';
 import type { DataSnapshot, DatabaseReference, Query, ThenableReference } from './types.js';
 import { buildSandboxRef } from './references.js';
 import { buildSandboxQuerySnap, buildSandboxSnap } from './snapshots.js';
@@ -19,24 +22,27 @@ import { buildSandboxQuerySnap, buildSandboxSnap } from './snapshots.js';
  * Matches the SDK's `DataSnapshot.val()` contract.
  */
 export function get(r: DatabaseReference | Query): Promise<DataSnapshot> {
-  // Query branch — windowed read.
-  if (isQuery(r as object)) {
-    const q = r as Query;
-    const target = targetOf(q.ref as unknown as object);
-    return Promise.resolve().then(() => {
-      const rows = target.admin
-        ? target.backend.adminGetQuery(q.ref._path, q._spec)
-        : target.backend.getQuery(authFor(target), q.ref._path, q._spec);
-      return buildSandboxQuerySnap(target, q.ref, rows);
-    });
-  }
-  const ref0 = r as DatabaseReference;
-  const target = targetOf(ref0 as unknown as object);
+  const query = isQuery(r as object) ? r as Query : undefined;
+  const ref0 = query?.ref ?? r as DatabaseReference;
+  const target = targetOf(ref0 as object);
+  const activity = beginDatabaseActivity(r, 'get', 'operation');
+  // Keep the existing single Promise reaction and exact backend error object.
   return Promise.resolve().then(() => {
-    const val = target.admin
-      ? target.backend.adminGet(ref0._path)
-      : target.backend.get(authFor(target), ref0._path);
-    return buildSandboxSnap(target, ref0, val);
+    try {
+      if (query) {
+        const rows = target.admin
+          ? target.backend.adminGetQuery(query.ref._path, query._spec)
+          : target.backend.getQuery(authFor(target), query.ref._path, query._spec);
+        return finishSdkRead(activity, buildSandboxQuerySnap(target, query.ref, rows));
+      }
+      const val = target.admin
+        ? target.backend.adminGet(ref0._path)
+        : target.backend.get(authFor(target), ref0._path);
+      return finishSdkRead(activity, buildSandboxSnap(target, ref0, val));
+    } catch (error) {
+      activity.fail();
+      throw error;
+    }
   });
 }
 
@@ -49,11 +55,13 @@ export function get(r: DatabaseReference | Query): Promise<DataSnapshot> {
  */
 export async function set(r: DatabaseReference, value: unknown): Promise<void> {
   const target = targetOf(r as unknown as object);
-  if (target.admin) {
-    target.backend.adminSet(r._path, value as JsonValue);
-  } else {
-    target.backend.set(authFor(target), r._path, value as JsonValue);
-  }
+  return runSdkWrite(beginDatabaseActivity(r, 'set', 'operation'), () => {
+    if (target.admin) {
+      target.backend.adminSet(r._path, value as JsonValue);
+    } else {
+      target.backend.set(authFor(target), r._path, value as JsonValue);
+    }
+  });
 }
 
 export async function setPriority(
@@ -61,11 +69,13 @@ export async function setPriority(
   priority: string | number | null,
 ): Promise<void> {
   const target = targetOf(r as unknown as object);
-  if (target.admin) {
-    target.backend.adminSetPriority(r._path, priority);
-  } else {
-    target.backend.setPriority(authFor(target), r._path, priority);
-  }
+  return runSdkWrite(beginDatabaseActivity(r, 'setPriority', 'operation'), () => {
+    if (target.admin) {
+      target.backend.adminSetPriority(r._path, priority);
+    } else {
+      target.backend.setPriority(authFor(target), r._path, priority);
+    }
+  });
 }
 
 export async function setWithPriority(
@@ -74,11 +84,13 @@ export async function setWithPriority(
   priority: string | number | null,
 ): Promise<void> {
   const target = targetOf(r as unknown as object);
-  if (target.admin) {
-    target.backend.adminSetWithPriority(r._path, value as JsonValue, priority);
-  } else {
-    target.backend.setWithPriority(authFor(target), r._path, value as JsonValue, priority);
-  }
+  return runSdkWrite(beginDatabaseActivity(r, 'setWithPriority', 'operation'), () => {
+    if (target.admin) {
+      target.backend.adminSetWithPriority(r._path, value as JsonValue, priority);
+    } else {
+      target.backend.setWithPriority(authFor(target), r._path, value as JsonValue, priority);
+    }
+  });
 }
 
 /**
@@ -100,16 +112,18 @@ export function update(
 ): Promise<void> {
   const target = targetOf(r as unknown as object);
   validateUpdatePaths(values);
-  return Promise.resolve().then(() => {
-    if (target.admin) {
-      target.backend.adminUpdate(r._path, values as Record<string, JsonValue>);
-    } else {
-      target.backend.update(
-        authFor(target),
-        r._path,
-        values as Record<string, JsonValue>,
-      );
-    }
+  return runSdkWrite(beginDatabaseActivity(r, 'update', 'operation'), () => {
+    return Promise.resolve().then(() => {
+      if (target.admin) {
+        target.backend.adminUpdate(r._path, values as Record<string, JsonValue>);
+      } else {
+        target.backend.update(
+          authFor(target),
+          r._path,
+          values as Record<string, JsonValue>,
+        );
+      }
+    });
   });
 }
 
@@ -140,11 +154,13 @@ function validateUpdatePaths(values: Record<string, unknown>): void {
  */
 export async function remove(r: DatabaseReference): Promise<void> {
   const target = targetOf(r as unknown as object);
-  if (target.admin) {
-    target.backend.adminRemove(r._path);
-  } else {
-    target.backend.remove(authFor(target), r._path);
-  }
+  return runSdkWrite(beginDatabaseActivity(r, 'remove', 'operation'), () => {
+    if (target.admin) {
+      target.backend.adminRemove(r._path);
+    } else {
+      target.backend.remove(authFor(target), r._path);
+    }
+  });
 }
 
 /**
@@ -175,9 +191,16 @@ export function push(r: DatabaseReference, value?: unknown): ThenableReference {
   // thenable's own `then` (the self-reference unwrap trap).
   const thenablePushRef = buildSandboxRef(target, childPath);
   const pushRef = buildSandboxRef(target, childPath);
-  const promise = value === undefined
-    ? Promise.resolve(pushRef)
-    : set(pushRef, value).then(() => pushRef);
+  let promise: Promise<DatabaseReference>;
+  if (value === undefined) {
+    promise = Promise.resolve(pushRef);
+  } else {
+    promise = runSdkWrite(beginDatabaseActivity(pushRef, 'push', 'operation'), () => {
+      if (target.admin) target.backend.adminSet(childPath, value as JsonValue);
+      else target.backend.set(authFor(target), childPath, value as JsonValue);
+      return pushRef;
+    });
+  }
   return makeThenable(thenablePushRef, promise);
 }
 

package/src/database/replay.ts

@@ -1,3 +1,4 @@
+import { assertCompleteHistory } from '../sandbox/internal/history-integrity.js';
 import {
   initializeSandbox,
   type Sandbox,
@@ -56,6 +57,7 @@ export async function replay(
   events: readonly SandboxEvent[],
   opts: RtdbReplayOptions,
 ): Promise<RtdbReplayResult> {
+  assertCompleteHistory(events);
   const sandbox = initializeSandbox();
   const db = getDatabase(sandbox);
   const adminDb = getAdminDatabase(sandbox);
@@ -73,7 +75,8 @@ export async function replay(
 
   for (const commit of commits) {
     const path = commit.path ?? '/';
-    if (commit.detail?.admin === true) {
+    const isAdmin = commit.detail?.admin === true;
+    if (isAdmin) {
       await replayRtdbAdminCommit(sandbox, commit, divergences);
       continue;
     }
@@ -82,11 +85,12 @@ export async function replay(
     try {
       await replayRtdbAppCommit(sandbox, commit, divergences);
     } catch (e) {
+      const isError = e instanceof Error;
       divergences.push({
         kind: 'now-denied',
         path,
         method: commit.method,
-        reason: e instanceof Error ? e.message : String(e),
+        reason: isError ? e.message : String(e),
       });
     }
   }

package/src/database/routing.ts

@@ -44,6 +44,8 @@ export const TARGET_SYMBOL: unique symbol = Symbol('pyric/database/target');
 
 export type SandboxTarget = {
   kind: 'sandbox';
+  activityApp?: object;
+  activityScope?: string;
   backend: RtdbBackend;
   auth: AuthState;
   admin?: boolean;
@@ -51,6 +53,8 @@ export type SandboxTarget = {
 };
 export type SandboxLiveTarget = {
   kind: 'sandbox-live';
+  activityApp?: object;
+  activityScope?: string;
   backend: RtdbBackend;
   sandbox: Sandbox;
   currentUser?: () => AuthState;

package/src/database/sandbox/backend-for.ts

@@ -1,41 +1,161 @@
 /**
- * One RTDB backend per local sandbox.
+ * One coordinator per local sandbox managing isolated RTDB backends per database URL.
  *
  * The database mirror and the owner controls both cross this internal seam so
- * they cannot accidentally create parallel trees for the same Sandbox.
+ * they cannot accidentally create parallel trees for the same Sandbox and database URL.
  */
 import type { Sandbox } from 'pyric/sandbox';
 
 import { RtdbBackend } from './backend.js';
 import type { JsonValue } from './data-tree.js';
 
-const backendBySandbox = new WeakMap<Sandbox, RtdbBackend>();
+export function canonicalizeDatabaseUrl(urlOrId?: string): string {
+  if (!urlOrId || urlOrId.trim() === '' || urlOrId.trim().toLowerCase() === 'default') {
+    return 'default';
+  }
+  const trimmed = urlOrId.trim();
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith('http://') || lower.startsWith('https://')) {
+    try {
+      const u = new URL(trimmed);
+      const origin = u.origin.toLowerCase();
+      const pathname = u.pathname.replace(/\/+$/, '');
+      const sp = new URLSearchParams();
+      for (const [k, v] of u.searchParams.entries()) {
+        if (k.toLowerCase() === 'ns') {
+          sp.set('ns', v.toLowerCase());
+        } else {
+          sp.set(k, v);
+        }
+      }
+      const searchStr = sp.toString();
+      const search = searchStr ? `?${searchStr}` : '';
+      return `${origin}${pathname}${search}`;
+    } catch {
+      return lower;
+    }
+  }
+  return `https://${lower}.firebaseio.com`;
+}
+
+interface SandboxRtdbCoordinator {
+  backends: Map<string, RtdbBackend>;
+  defaultBackend?: RtdbBackend;
+  listeners: Set<() => void>;
+  notifyChange: () => void;
+}
+
+const coordinatorBySandbox = new WeakMap<Sandbox, SandboxRtdbCoordinator>();
+
+export function getOrCreateBackend(sandbox: Sandbox, databaseUrl?: string): RtdbBackend {
+  const canonicalUrl = canonicalizeDatabaseUrl(databaseUrl);
+
+  let coordinator = coordinatorBySandbox.get(sandbox);
+  if (!coordinator) {
+    const listeners = new Set<() => void>();
+    const backends = new Map<string, RtdbBackend>();
+    const initialBackend = new RtdbBackend(sandbox);
+    backends.set(canonicalUrl, initialBackend);
+
+    const notifyChange = () => {
+      for (const listener of listeners) {
+        try {
+          listener();
+        } catch {
+          // ignore
+        }
+      }
+    };
+
+    coordinator = {
+      backends,
+      defaultBackend: canonicalUrl === 'default' ? initialBackend : undefined,
+      listeners,
+      notifyChange,
+    };
+    coordinatorBySandbox.set(sandbox, coordinator);
+
+    initialBackend.subscribeWrites(notifyChange);
+
+    const getDefaultBackend = (): RtdbBackend => {
+      let b = coordinator!.backends.get('default');
+      if (!b) {
+        b = new RtdbBackend(sandbox);
+        coordinator!.backends.set('default', b);
+        coordinator!.defaultBackend = b;
+        b.subscribeWrites(notifyChange);
+      }
+      return b;
+    };
+
+    sandbox.onEvent((event) => {
+      if (event.kind === 'session_boundary' && event.phase === 'reset') {
+        for (const b of coordinator!.backends.values()) {
+          b.invalidateConnectionQueues();
+          b.setRules(null);
+        }
+      }
+    });
 
-export function getOrCreateBackend(sandbox: Sandbox): RtdbBackend {
-  let backend = backendBySandbox.get(sandbox);
-  if (backend) return backend;
+    sandbox.registerPersistableService('rtdb', {
+      snapshot: () => {
+        const defaultState = getDefaultBackend().exportPersistenceState();
+        const instances: Record<string, unknown> = {};
+        for (const [url, b] of coordinator!.backends.entries()) {
+          if (url !== 'default') {
+            instances[url] = b.exportPersistenceState();
+          }
+        }
+        if (
+          Object.keys(instances).length > 0 &&
+          defaultState !== null &&
+          typeof defaultState === 'object' &&
+          !Array.isArray(defaultState)
+        ) {
+          return {
+            ...(defaultState as Record<string, unknown>),
+            instances,
+          };
+        }
+        return defaultState;
+      },
+      restore: (data: unknown) => {
+        if (!data || typeof data !== 'object') return;
+        getDefaultBackend().restoreTree(data as JsonValue);
+        const record = data as { instances?: Record<string, unknown> };
+        if (record.instances && typeof record.instances === 'object') {
+          for (const [url, instData] of Object.entries(record.instances)) {
+            const b = getOrCreateBackend(sandbox, url);
+            b.restoreTree(instData as JsonValue);
+          }
+        }
+      },
+      subscribe: (onChange: () => void) => {
+        listeners.add(onChange);
+        return () => {
+          listeners.delete(onChange);
+        };
+      },
+      // Sandbox.resetAll: clear trees across all instances
+      reset: () => {
+        for (const b of coordinator!.backends.values()) {
+          b.resetTree();
+        }
+      },
+    });
 
-  backend = new RtdbBackend(sandbox);
-  backendBySandbox.set(sandbox, backend);
+    return initialBackend;
+  }
 
-  const capturedBackend = backend;
-  sandbox.onEvent((event) => {
-    if (event.kind === 'session_boundary' && event.phase === 'reset') {
-      capturedBackend.invalidateConnectionQueues();
+  let backend = coordinator.backends.get(canonicalUrl);
+  if (!backend) {
+    backend = new RtdbBackend(sandbox);
+    backend.subscribeWrites(coordinator.notifyChange);
+    coordinator.backends.set(canonicalUrl, backend);
+    if (canonicalUrl === 'default') {
+      coordinator.defaultBackend = backend;
     }
-  });
-  sandbox.registerPersistableService('rtdb', {
-    snapshot: () => capturedBackend.exportPersistenceState(),
-    restore: (data: unknown) => {
-      capturedBackend.restoreTree(data as JsonValue);
-    },
-    subscribe: (onChange: () => void) => capturedBackend.subscribeWrites(onChange),
-    // Sandbox.resetAll: clear the whole tree (restoreTree fans listeners out,
-    // so live views converge on the emptied state).
-    reset: () => {
-      capturedBackend.resetTree();
-    },
-  });
+  }
 
   return backend;
 }

package/src/database/sandbox/backend-state.ts

@@ -1,4 +1,6 @@
 import type { Sandbox } from 'pyric/sandbox';
+import { SandboxClock } from 'pyric/sandbox';
+import { getClock } from 'pyric/sandbox/internal';
 import { DataTree } from './data-tree.js';
 import type { ChildListener, ValueListener } from './listener-types.js';
 import { MutationHistory } from './mutation-history.js';
@@ -8,7 +10,7 @@ import { RulesEvaluator } from './rules-eval.js';
 
 export class BackendState {
   readonly tree = new DataTree();
-  readonly rules = new RulesEvaluator();
+  readonly rules: RulesEvaluator;
   activeRules: { rules: Record<string, unknown> } | null = null;
   readonly valueListeners = new Set<ValueListener>();
   readonly childListeners = new Set<ChildListener>();
@@ -17,9 +19,21 @@ export class BackendState {
   readonly events: OperationEvents;
   readonly writeSubscribers = new Set<() => void>();
   resetGeneration = 0;
+  /**
+   * The sandbox's clock. Every server-set time this backend produces reads it:
+   * `ServerValue.TIMESTAMP`, the rules engine's `now`, push-id keys, and the
+   * operation-event stamps. A backend with no sandbox keeps its own wall clock.
+   */
+  readonly clock: SandboxClock;
 
   constructor(sandbox?: Sandbox) {
     this.events = new OperationEvents(sandbox);
+    this.clock = sandbox ? getClock(sandbox) : new SandboxClock();
+    this.rules = new RulesEvaluator(this.clock, (path, spec, ctx) => {
+      this.events.operation(ctx.auth, ctx.indexMethod ?? 'get', path, 'error', undefined, {
+        request: { query: spec }, detail: { failure: 'missing-index' },
+      });
+    });
   }
 
   notifyWrite(): void {

package/src/database/sandbox/backend.ts

@@ -14,6 +14,7 @@ import { Transactions } from './transactions.js';
 import { ValueListeners } from './value-listeners.js';
 import { WritePlane } from './write-plane.js';
 import type { JsonValue } from './data-tree.js';
+import type { ListenerAttribution } from '../../sandbox/attribution/listener-owners.js';
 
 export class RtdbBackend {
   private readonly state: BackendState;
@@ -85,8 +86,9 @@ export class RtdbBackend {
     query?: QuerySpec,
     cancelCallback?: (error: Error) => void,
     onCanceled?: () => void,
+    attribution?: ListenerAttribution,
   ): () => void {
-    return this.values.onValue(auth, path, cb, query, cancelCallback, onCanceled);
+    return this.values.onValue(auth, path, cb, query, cancelCallback, onCanceled, attribution);
   }
 
   adminOnValue(
@@ -132,7 +134,7 @@ export class RtdbBackend {
   restoreTree(root: JsonValue): void { this.persistence.restore(root); }
   resetTree(): void { this.persistence.reset(); }
   subscribeWrites(onChange: () => void): () => void { return this.persistence.subscribe(onChange); }
-  mintKey(): string { return generatePushId(); }
+  mintKey(): string { return generatePushId(this.state.clock.now()); }
   listenerCount(): number { return this.values.count(); }
   childListenerCount(): number { return this.children.count(); }
 }

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

@@ -8,7 +8,9 @@ import {
   type QueryRow, type QuerySpec,
 } from './query.js';
 import { permissionDenied } from './rules-eval.js';
-import { listenerPermissionDenied } from './value-listeners.js';
+import { listenerPermissionDenied, ownersFor } from './value-listeners.js';
+import { listenerAttachOwners } from '../../sandbox/attribution/listener-owners.js';
+import { recordEffectRegions } from '../../sandbox/attribution/effect-regions.js';
 
 type ChildEvent = ChildListener['event'];
 type ChildSnapshot = { key: string; val: JsonValue; previousChildName: string | null };
@@ -44,15 +46,18 @@ export class ChildListeners {
     cancelCallback?: (error: Error) => void,
     onCanceled?: () => void,
   ): () => void {
-    const at = Date.now();
+    const at = this.state.clock.now();
     const id = this.state.events.nextListenerId();
+    const attachOwners = listenerAttachOwners();
     const evaluation = this.state.rules.evaluate('read', path === '/' ? '/' : path, {
+      indexMethod: 'listen',
       auth,
       mockData: this.state.tree.snapshot() as Record<string, unknown>,
+      querySpec: spec,
     });
     if (evaluation.check !== 'allow') {
       this.state.events.operation(auth, 'listen', path, denyResultFor(evaluation.check), evaluation, {
-        at, durationMs: Date.now() - at, origin: 'listener', detail: { event },
+        at, durationMs: this.state.clock.now() - at, origin: 'listener', detail: { event },
       });
       const rulesObj = {
         engine: 'rtdb' as const,
@@ -80,12 +85,14 @@ export class ChildListeners {
       throw permissionDenied();
     }
     this.state.events.operation(auth, 'listen', path, 'allow', evaluation, {
-      at, durationMs: Date.now() - at, origin: 'listener', detail: { event },
+      at, durationMs: this.state.clock.now() - at, origin: 'listener', detail: { event },
     });
     const listener: ChildListener = { id, auth, event, path, cb, spec, cancelCallback, onCanceled };
     this.state.childListeners.add(listener);
     this.state.events.listener('attach', listener, auth, {
       event, result: 'allow', detail: spec ? { query: spec } : undefined,
+      ...(spec ? { query: spec } : {}),
+      owners: attachOwners,
     });
     if (spec) {
       const rows = executeQuery(this.state.tree.read(path), spec, this.state.priorities.forChild(path));
@@ -237,18 +244,30 @@ export class ChildListeners {
     for (const snapshot of events) this.deliver(listener, snapshot, { query: true });
   }
 
+  /**
+   * Deliver one child event. The callback runs before the delivery event is
+   * emitted so the event can carry the regions the callback touched; what the
+   * callback receives, and when, is unchanged.
+   */
   private deliver(listener: ChildListener, snapshot: ChildSnapshot, 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: listener.event, size: 1, sample: detail.query ? { key: snapshot.key, val: snapshot.val } : snapshot,
-      detail,
+      detail, owners: ownersFor(regions),
+    });
+    if (!caught) return;
+    this.state.events.listener('errored', listener, listener.auth, {
+      event: listener.event, 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: listener.event, result: 'error',
-        error: { message: error instanceof Error ? error.message : String(error) }, detail,
-      });
-    }
   }
 }

package/src/database/sandbox/listener-types.ts

@@ -1,4 +1,5 @@
 import type { AuthState } from 'pyric/sandbox';
+import type { ListenerOwner } from '../../sandbox/types/events.js';
 import type { JsonValue } from './data-tree.js';
 import type { QueryRow, QuerySpec } from './query.js';
 
@@ -20,6 +21,10 @@ export interface ValueListener {
   lastWindow?: QueryRow[];
   lastValue?: JsonValue;
   lastPriorityState?: string;
+  /** Attached through the admin SDK, which bypasses rules. */
+  admin?: boolean;
+  /** Owners recorded on this listener's `attach` event. */
+  owners?: ListenerOwner[];
 }
 
 export interface ChildListener {