pyric-admin 0.1.0-alpha.24 → 0.1.0-alpha.26

package/src/database/index.ts

@@ -40,11 +40,12 @@
  *         backing rule state to expose.
  *
  *     Sandbox state lives on the underlying `Sandbox` via a `WeakMap`
- *     keyed by the `Sandbox` instance — `sandbox.reset()` wipes it via
- *     the sandbox's `session_boundary` event with `phase: 'reset'`.
- *     Successive `getDatabase(app)` calls for the same sandbox return
- *     handles that share data (matches firebase-admin's
- *     singleton-per-app semantics).
+ *     keyed by the `Sandbox` instance, with one tree per RTDB instance
+ *     (the instance a database URL names). `sandbox.reset()` wipes every
+ *     tree via the sandbox's `session_boundary` event.
+ *     Successive `getDatabase(app)` calls for the same sandbox and instance
+ *     return the same handle (matches firebase-admin's one database per
+ *     app and URL).
  *
  *   - **Remote sandbox arm** (sandbox target whose `Sandbox` carries the
  *     `pyric/sandbox` remote brand — a Node-side handle onto the
@@ -52,7 +53,9 @@
  *     `connectRemoteSandbox()`) — every `Reference` data operation routes
  *     through the handle's worker-relay channel (`rtdb.get/set/update/
  *     remove/push` ops with `actAs: { mode: 'admin' }` pinned — firebase-
- *     admin's rules-bypass semantics), NOT into the process-local tree:
+ *     admin's rules-bypass semantics, and the instance the database
+ *     URL names on every op and value subscription), NOT into the
+ *     process-local tree:
  *     a local tree on a remote handle would be private server-side data
  *     the browser never sees. Differences from the local arm, both
  *     deliberate upgrades:
@@ -78,6 +81,16 @@ import {
   type Sandbox,
 } from 'pyric/sandbox';
 
+import {
+  createDatabaseInstanceRegistry,
+  isCustomDatabaseHost,
+  isDefaultDatabaseInstance,
+  parseDatabaseLocationUrl,
+  parseDatabaseUrl,
+  type DatabaseInstance,
+  type DatabaseInstanceRegistry,
+} from 'pyric/sandbox/internal';
+
 import {
   ADMIN_APP_TARGET,
   getApp,
@@ -85,6 +98,12 @@ import {
 } from '../app/index.js';
 import { assertAdminAppActive } from '../app/lifecycle.js';
 import { increment, serverTimestamp } from 'pyric/database';
+import { valueAtChildPath, valueChildren } from 'pyric/database/internal';
+import { deferredExport } from 'pyric/app/internal';
+
+/** `firebase-admin/database`'s `enableLogging`. The sandbox does not model
+ *  the client logger, so it fails with an error naming it. */
+export const enableLogging = deferredExport('pyric-admin/database', 'enableLogging');
 
 /** Mirror of `firebase-admin/database`'s `ServerValue` constant and sentinel constructors. */
 export const ServerValue: {
@@ -154,20 +173,22 @@ type AdminEventType = EventType;
  *
  * Signature mirrors `firebase-admin/database`'s `getDatabase(app?)`.
  *
- *   - `getDatabase()` — default database for the DEFAULT app (resolved
+ *   - `getDatabase()`: default database for the DEFAULT app (resolved
  *     through `pyric-admin/app`'s registry, exactly like firebase-admin's
  *     no-arg `getDatabase()`; throws `app/no-app` when no default app has
  *     been initialized). Works for local and remote sandbox apps.
- *   - `getDatabase(app)` — default database for the app.
- *   - `getDatabase(app, url)` — legacy Pyric-only compatibility form. New
- *     code should use the upstream-shaped {@link getDatabaseWithUrl} export.
+ *   - `getDatabase(app)`: the database the app's `databaseURL` option names,
+ *     else the default instance.
+ *   - `getDatabase(app, url)`: the database `url` names, as
+ *     {@link getDatabaseWithUrl} selects it.
  *
- * The sandbox brand returns the local or remote `Database` backed by the
- * per-`Sandbox` state described in the module-level docs.
+ * Each RTDB instance has its own data: one `Database` per sandbox and
+ * instance, backed by the per-`Sandbox` state described in the module-level
+ * docs. A URL that does not parse as a database URL throws the SDK's error.
  */
 export function getDatabase(
   app?: PyricAdminApp,
-  _url?: string,
+  url?: string,
 ): AdminDatabase {
   if (app === undefined) {
     // No-arg mirror of firebase-admin's `getDatabase()` — resolve the
@@ -176,7 +197,7 @@ export function getDatabase(
   }
   assertAdminAppActive(app);
   if (app[ADMIN_APP_TARGET] === 'sandbox') {
-    return getSandboxDatabase(app.sandbox);
+    return getSandboxDatabase(app.sandbox, adminDatabaseInstance(app, url));
   }
   throw new TypeError(
     'pyric-admin/database: getDatabase expected a PyricAdminApp ' +
@@ -185,19 +206,47 @@ export function getDatabase(
 }
 
 /**
- * Returns the {@link AdminDatabase} service selected by an upstream-shaped
- * database URL.
+ * Returns the {@link AdminDatabase} service for the RTDB instance `url` names.
  *
  * This is the exact `firebase-admin/database` argument order used by the
- * Firebase Functions SDK: `getDatabaseWithUrl(url, app?)`. The first Pyric
- * Functions slice has one shared RTDB instance, so the URL selects that
- * instance rather than creating a second sandbox database.
+ * Firebase Functions SDK: `getDatabaseWithUrl(url, app?)`.
  */
 export function getDatabaseWithUrl(
-  _url: string,
+  url: string,
   app?: PyricAdminApp,
 ): AdminDatabase {
-  return getDatabase(app);
+  if (typeof url !== 'string' || url === '') {
+    throw invalidDatabaseUrl();
+  }
+  return getDatabase(app, url);
+}
+
+/** firebase-admin's error for a missing or empty database URL. */
+function invalidDatabaseUrl(): Error {
+  return Object.assign(
+    new Error('Database URL must be a valid, non-empty URL string.'),
+    { code: 'database/invalid-argument' },
+  );
+}
+
+/**
+ * The instance an admin database targets: `url`, else the app's `databaseURL`
+ * option, parsed as the production SDK parses it. `undefined` is the default
+ * instance, which the instance named `<projectId>-default-rtdb` or, for a
+ * project created before about 2020, `<projectId>` also is when the app's
+ * options name the project.
+ */
+function adminDatabaseInstance(
+  app: PyricAdminApp,
+  url: string | undefined,
+): DatabaseInstance | undefined {
+  if (url === '') throw invalidDatabaseUrl();
+  const source = url ?? app.options.databaseURL;
+  if (source === undefined) return undefined;
+  const instance = parseDatabaseUrl(source);
+  const projectId = app.options.projectId;
+  const isProjectDefault = isDefaultDatabaseInstance(instance.name, projectId);
+  return isProjectDefault ? undefined : instance;
 }
 
 // ─── Sandbox backend ─────────────────────────────────────────────────
@@ -218,54 +267,61 @@ type JsonValue =
   | { [key: string]: JsonValue };
 
 /**
- * Per-sandbox state. One instance per `Sandbox`; the WeakMap below
- * keys this off the `Sandbox` reference so `sandbox.reset()` can wipe
- * everything in one swap. The `Database` handle returned to consumers
- * holds onto the `SandboxState` directly so reads / writes don't
- * re-resolve through the WeakMap on every op.
+ * One RTDB instance's in-memory tree. The `Database` handle returned to
+ * consumers holds onto the `SandboxState` directly so reads / writes don't
+ * re-resolve through the registry on every op.
  */
 interface SandboxState {
   root: Record<string, JsonValue>;
 }
 
-/** One backend per `Sandbox`. Successive `getDatabase(app)` calls for
- *  the same sandbox return handles that share data — matches
- *  firebase-admin's singleton-per-app semantics. */
-const stateBySandbox = new WeakMap<Sandbox, SandboxState>();
-
-function getOrCreateState(sandbox: Sandbox): SandboxState {
-  let state = stateBySandbox.get(sandbox);
-  if (state !== undefined) return state;
-  state = { root: {} };
-  stateBySandbox.set(sandbox, state);
-  // Wire `sandbox.reset()` → wipe the tree. `session_boundary` fires
-  // before the env swap, so consumer code that observes a reset sees
+/** One instance's tree and the one `Database` handle over it, built on first use. */
+interface LocalInstance {
+  state: SandboxState;
+  db?: AdminDatabase;
+}
+
+/** One registry of instances per `Sandbox`. Successive `getDatabase(app)`
+ *  calls for the same sandbox and instance return the same handle, and
+ *  each instance keeps its own tree, as firebase-admin keeps one database
+ *  per URL. */
+const localInstancesBySandbox = new WeakMap<Sandbox, DatabaseInstanceRegistry<LocalInstance>>();
+
+function localInstances(sandbox: Sandbox): DatabaseInstanceRegistry<LocalInstance> {
+  const existing = localInstancesBySandbox.get(sandbox);
+  if (existing !== undefined) return existing;
+  const registry: DatabaseInstanceRegistry<LocalInstance> = createDatabaseInstanceRegistry({
+    create: () => ({ state: { root: {} } }),
+  });
+  localInstancesBySandbox.set(sandbox, registry);
+  // Wire `sandbox.reset()` → wipe every instance's tree. `session_boundary`
+  // fires before the env swap, so consumer code that observes a reset sees
   // the freshly-cleared tree on the next read. `dispose` also fires a
   // boundary; treat it the same (the sandbox is being torn down — any
   // in-flight handle on the tree gets an empty view).
   sandbox.onEvent((event) => {
     if (event.kind === 'session_boundary') {
-      state!.root = {};
+      for (const [, entry] of registry.entries()) entry.state.root = {};
     }
   });
-  return state;
+  return registry;
 }
 
-/** Build (or reuse) the sandbox Database handle for `sandbox`.
+/** Build (or reuse) the sandbox Database handle for `sandbox` and `instance`
+ *  (`undefined` is the default instance).
  *
  *  REMOTE handles dispatch here, BEFORE any local state is touched: a
  *  remote sandbox must never get a `SandboxState` (a private local tree)
  *  or a `sandbox.onEvent` wire-up (which throws on remote handles). */
-function getSandboxDatabase(sandbox: Sandbox): AdminDatabase {
+function getSandboxDatabase(sandbox: Sandbox, instance: DatabaseInstance | undefined): AdminDatabase {
   if (isRemoteSandbox(sandbox)) {
-    return getRemoteDatabase(sandbox);
+    return getRemoteDatabase(sandbox, instance);
   }
-  const state = getOrCreateState(sandbox);
-  return buildSandboxDatabase(state);
-}
-
-function buildSandboxDatabase(state: SandboxState): AdminDatabase {
-  return buildDatabaseShell((db, path) => buildSandboxRef(state, db, path));
+  const registry = localInstances(sandbox);
+  const entry = registry.getOrCreate(registry.keyOf(instance));
+  const state = entry.state;
+  entry.db ??= buildDatabaseShell(instance, (handle, path) => buildSandboxRef(state, handle, path));
+  return entry.db;
 }
 
 /**
@@ -275,18 +331,26 @@ function buildSandboxDatabase(state: SandboxState): AdminDatabase {
  * local emulator).
  */
 function buildDatabaseShell(
+  instance: DatabaseInstance | undefined,
   refFactory: (db: AdminDatabase, path: string) => AdminReference,
 ): AdminDatabase {
   const db = {
     ref(path?: string): AdminReference {
       return refFactory(db as unknown as AdminDatabase, path ?? '/');
     },
+    /** As the SDK parses it: the URL names a location, and for a
+     *  `firebaseio.com` database its host must be this database's host. */
     refFromURL(url: string): AdminReference {
-      // Best-effort: strip the `https://<host>` prefix and treat the
-      // remainder as a path. The sandbox has no notion of multi-database
-      // hosts, so the host portion is ignored.
-      const u = url.replace(/^https?:\/\/[^/]+/, '');
-      return refFactory(db as unknown as AdminDatabase, u || '/');
+      const location = parseDatabaseLocationUrl(url);
+      if (instance !== undefined) {
+        const expectedHost = parseDatabaseLocationUrl(instance.url).host;
+        if (!isCustomDatabaseHost(expectedHost) && location.host !== expectedHost) {
+          throw new Error(
+            `FIREBASE FATAL ERROR: refFromURL: Host name does not match the current database: (found ${location.host} but expected ${expectedHost}) `,
+          );
+        }
+      }
+      return refFactory(db as unknown as AdminDatabase, location.path);
     },
     // Admin-only metadata methods — not modeled in the sandbox. The
     // sandbox is rule-bypass by construction; surfacing rule JSON would
@@ -757,6 +821,9 @@ function buildSandboxSnap(
   const segs = pathSegments(path);
   const key = segs.length === 0 ? null : segs[segs.length - 1]!;
   const exists = val !== null;
+  // An array value still has children: `val()` renders integer keys as an
+  // array, and the SDK iterates them as '0', '1', ... (#1110).
+  const children = valueChildren(val);
   const snap = {
     key,
     get ref(): AdminReference {
@@ -770,35 +837,21 @@ function buildSandboxSnap(
     },
     child(p: string): AdminDataSnapshot {
       const childSegs = pathSegments(p);
-      let cur: JsonValue = val;
-      for (const s of childSegs) {
-        if (cur === null || typeof cur !== 'object' || Array.isArray(cur)) {
-          cur = null;
-          break;
-        }
-        cur = (cur as Record<string, JsonValue>)[s] ?? null;
-      }
-      return buildSandboxSnap(refAt, joinPath([...segs, ...childSegs]), cur);
+      const childVal = valueAtChildPath(val, childSegs) as JsonValue;
+      return buildSandboxSnap(refAt, joinPath([...segs, ...childSegs]), childVal);
     },
     hasChild(p: string): boolean {
       return snap.child(p).exists();
     },
     hasChildren(): boolean {
-      return (
-        val !== null &&
-        typeof val === 'object' &&
-        !Array.isArray(val) &&
-        Object.keys(val as Record<string, JsonValue>).length > 0
-      );
+      return children.length > 0;
     },
     numChildren(): number {
-      if (val === null || typeof val !== 'object' || Array.isArray(val)) return 0;
-      return Object.keys(val as Record<string, JsonValue>).length;
+      return children.length;
     },
     forEach(cb: (child: AdminDataSnapshot) => boolean | void): boolean {
-      if (val === null || typeof val !== 'object' || Array.isArray(val)) return false;
-      for (const [k, v] of Object.entries(val as Record<string, JsonValue>)) {
-        const childSnap = buildSandboxSnap(refAt, joinPath([...segs, k]), v);
+      for (const { key: childKey, value } of children) {
+        const childSnap = buildSandboxSnap(refAt, joinPath([...segs, childKey]), value as JsonValue);
         if (cb(childSnap) === true) return true;
       }
       return false;
@@ -845,30 +898,60 @@ interface RemoteWireSnapshot {
 }
 
 /**
- * Per-remote-handle state: the relay channel plus the `on('value')`
- * listener registry (`path → callback → detach`) that `off()` consults.
+ * Per-remote-handle, per-instance state: the relay channel, the instance
+ * every op and subscription names (`undefined` is the default instance),
+ * and the `on('value')` listener registry (`path → callback → detach`) that
+ * `off()` consults.
  */
 interface RemoteDbState {
   channel: RemoteSandboxChannel;
+  instance: string | undefined;
   listeners: Map<string, Map<unknown, () => void>>;
 }
 
-/** One `Database` per remote handle — successive `getDatabase(app)` calls
- *  share the listener registry (matches the local arm's singleton-per-
- *  sandbox semantics). Keyed off the handle object; the data itself lives
- *  in the browser worker. */
-const remoteDbBySandbox = new WeakMap<Sandbox, AdminDatabase>();
-
-function getRemoteDatabase(sandbox: RemoteSandbox): AdminDatabase {
-  let db = remoteDbBySandbox.get(sandbox);
-  if (db !== undefined) return db;
+/** One `Database` per remote handle and instance. Successive
+ *  `getDatabase(app)` calls for an instance share the listener registry
+ *  (matches the local arm's singleton-per-instance semantics). Keyed off
+ *  the handle object; the data itself lives in the host. */
+const remoteDbsBySandbox = new WeakMap<Sandbox, DatabaseInstanceRegistry<{ db?: AdminDatabase }>>();
+
+function getRemoteDatabase(sandbox: RemoteSandbox, instance: DatabaseInstance | undefined): AdminDatabase {
+  let registry = remoteDbsBySandbox.get(sandbox);
+  if (registry === undefined) {
+    registry = createDatabaseInstanceRegistry({ create: () => ({}) });
+    remoteDbsBySandbox.set(sandbox, registry);
+  }
+  const entry = registry.getOrCreate(registry.keyOf(instance));
+  if (entry.db !== undefined) return entry.db;
   const state: RemoteDbState = {
     channel: sandbox.channel,
+    instance: instance?.name,
     listeners: new Map(),
   };
-  db = buildDatabaseShell((dbHandle, path) => buildRemoteRef(state, dbHandle, path));
-  remoteDbBySandbox.set(sandbox, db);
-  return db;
+  entry.db = buildDatabaseShell(instance, (dbHandle, path) => buildRemoteRef(state, dbHandle, path));
+  return entry.db;
+}
+
+/** An RTDB op this arm relays, without the instance and lens {@link relayRtdbOp} adds. */
+type RemoteRtdbOp = { method: `rtdb.${string}`; path: string } & Record<string, unknown>;
+
+/** Relay `op` on the state's instance, under firebase-admin's rules-bypass lens. */
+function relayRtdbOp(state: RemoteDbState, op: RemoteRtdbOp): Promise<unknown> {
+  return state.channel.op({ ...op, instance: state.instance, actAs: REMOTE_ADMIN_LENS });
+}
+
+/** Subscribe to the value at `path` on the state's instance, under the admin lens. */
+function subscribeRtdbValue(
+  state: RemoteDbState,
+  path: string,
+  onSnap: (value: unknown) => void,
+  onError: (err: Error & { code: string }) => void,
+): () => void {
+  return state.channel.subscribe(
+    { target: { service: 'rtdb', instance: state.instance, path }, actAs: REMOTE_ADMIN_LENS },
+    onSnap,
+    onError,
+  );
 }
 
 /**
@@ -910,20 +993,18 @@ function buildRemoteRef(
 
     /** Set `value` at this path. `null` deletes. Relays `rtdb.set`. */
     async set(value: unknown): Promise<void> {
-      await state.channel.op({
+      await relayRtdbOp(state, {
         method: 'rtdb.set',
         path: canonical,
         value: value ?? null,
-        actAs: REMOTE_ADMIN_LENS,
       });
     },
 
     /** Read this path (`rtdb.get`). Resolves to a `DataSnapshot`. */
     async get(): Promise<AdminDataSnapshot> {
-      const wire = (await state.channel.op({
+      const wire = (await relayRtdbOp(state, {
         method: 'rtdb.get',
         path: canonical,
-        actAs: REMOTE_ADMIN_LENS,
       })) as RemoteWireSnapshot;
       return snapFromWire(wire);
     },
@@ -943,8 +1024,9 @@ function buildRemoteRef(
       return new Promise<AdminDataSnapshot>((resolve, reject) => {
         let detach: (() => void) | null = null;
         let settled = false;
-        detach = state.channel.subscribe(
-          { target: { service: 'rtdb', path: canonical }, actAs: REMOTE_ADMIN_LENS },
+        detach = subscribeRtdbValue(
+          state,
+          canonical,
           (value) => {
             if (settled) return;
             settled = true;
@@ -971,20 +1053,18 @@ function buildRemoteRef(
           'pyric-admin/database sandbox: update expected an object.',
         );
       }
-      await state.channel.op({
+      await relayRtdbOp(state, {
         method: 'rtdb.update',
         path: canonical,
         values: values as Record<string, unknown>,
-        actAs: REMOTE_ADMIN_LENS,
       });
     },
 
     /** Delete the subtree at this path (`rtdb.remove`). */
     async remove(): Promise<void> {
-      await state.channel.op({
+      await relayRtdbOp(state, {
         method: 'rtdb.remove',
         path: canonical,
-        actAs: REMOTE_ADMIN_LENS,
       });
     },
 
@@ -1003,14 +1083,7 @@ function buildRemoteRef(
       const write: Promise<void> =
         value === undefined
           ? Promise.resolve()
-          : state.channel
-              .op({
-                method: 'rtdb.push',
-                path: canonical,
-                key: id,
-                value,
-                actAs: REMOTE_ADMIN_LENS,
-              })
+          : relayRtdbOp(state, { method: 'rtdb.push', path: canonical, key: id, value })
               .then(() => undefined);
       // Surface completion without forcing the caller to await: `.then`'s
       // rejection handler also keeps a fire-and-forget push from becoming
@@ -1069,8 +1142,9 @@ function buildRemoteRef(
         typeof cancelCallbackOrContext === 'function'
           ? (cancelCallbackOrContext as (err: Error) => unknown)
           : undefined;
-      const detach = state.channel.subscribe(
-        { target: { service: 'rtdb', path: canonical }, actAs: REMOTE_ADMIN_LENS },
+      const detach = subscribeRtdbValue(
+        state,
+        canonical,
         (value) => {
           callback(snapFromWire(value as RemoteWireSnapshot));
         },

package/src/deferred.ts

@@ -1,20 +1,40 @@
 /**
- * The `firebase-admin` subpaths the sandbox does not mirror.
+ * Unmodeled `firebase-admin/*` subpaths and their `App`-bound service handles.
  *
  * Under `pyric sandbox`, every `firebase-admin/*` import resolves to the same
- * subpath of `pyric-admin`. For a service the sandbox does not model, that
- * subpath is a deferred entry: it resolves and every export links, so a module
- * graph that imports the service still loads, and using any export throws a
- * `PyricDeferredApiError` that names the subpath. The import is never passed
- * through to the real `firebase-admin`, which would reach production from
- * inside the sandbox.
+ * subpath of `pyric-admin`. Many server codebases initialize unmodeled services
+ * unconditionally at module load (`export const appCheck = getAppCheck(app)`)
+ * while never invoking methods on that handle on sandboxed request paths.
+ *
+ * Mirroring upstream's container contract keeps module initialization faithful
+ * without ever reaching production Firebase:
+ * - `get<Service>(app?)` resolves the active `PyricAdminApp` (throwing
+ *   `FirebaseAppError` `app/no-app` before `initializeApp()`, or
+ *   `app/app-deleted` after `deleteApp()`), caches one handle per app, and
+ *   exposes `.app`.
+ * - Every method on the returned handle is wired via `defineDeferredMembers` so
+ *   calling it throws synchronously or returns a rejected `Promise` with
+ *   `PyricDeferredApiError` naming `<Class>.<method>` and `pyric-admin/<subpath>`.
+ * - Helper classes, enums, and direct `new <Service>()` calls throw
+ *   `PyricDeferredApiError` naming the subpath.
  */
-import { deferredEntry, type DeferredApi } from 'pyric/app/internal';
+import {
+  deferredEntry,
+  defineDeferredMembers,
+  PyricDeferredApiError,
+  type DeferredApi,
+  type DeferredMembers,
+} from 'pyric/app/internal';
+import { getApp, type PyricAdminApp } from './app/index.js';
+import { assertAdminAppActive } from './app/lifecycle.js';
+
+export { PyricDeferredApiError };
 
-export { PyricDeferredApiError } from 'pyric/app/internal';
+/** Private construction token so `new <Service>()` throws while `get<Service>(app)` succeeds. */
+export const DEFERRED_SERVICE_TOKEN: unique symbol = Symbol('pyric.admin.deferredService');
 
-/** The message every export of a deferred `firebase-admin` subpath throws. */
-function deferredAdminMessage(subpath: string): string {
+/** The message every unmodeled `firebase-admin` export raises when called or constructed directly. */
+export function deferredAdminMessage(subpath: string): string {
   return (
     `pyric: 'firebase-admin/${subpath}' is not mirrored by the local sandbox, so its calls fail here. ` +
     'Imports resolve so module graphs load. Code that needs this service runs against Firebase outside ' +
@@ -23,11 +43,54 @@ function deferredAdminMessage(subpath: string): string {
 }
 
 /**
- * The export bag for one deferred `firebase-admin` subpath. Each entry
- * destructures the names the real subpath exports off it.
- *
- * @param subpath - The subpath without the `firebase-admin/` prefix.
+ * The export bag for non-service exports of one deferred `firebase-admin`
+ * subpath (helper classes, error classes, enum-like constants).
  */
 export function deferredAdminEntry(subpath: string): Record<string, DeferredApi> {
   return deferredEntry(subpath, deferredAdminMessage(subpath));
 }
+
+/** Resolve the default or explicit admin `App` and assert it has not been deleted. */
+export function resolveActiveAdminApp(app?: PyricAdminApp): PyricAdminApp {
+  const resolved = app ?? getApp();
+  assertAdminAppActive(resolved);
+  return resolved;
+}
+
+/** Guard direct `new <Service>()` construction while allowing `wireDeferredService` to mint handles. */
+export function guardDeferredServiceApp(
+  subpath: string,
+  className: string,
+  args: readonly unknown[],
+): PyricAdminApp {
+  if (args[0] !== DEFERRED_SERVICE_TOKEN) {
+    throw new PyricDeferredApiError(subpath, className, deferredAdminMessage(subpath));
+  }
+  return args[1] as PyricAdminApp;
+}
+
+/**
+ * Attach deferred member stubs onto `ctor.prototype` and return a per-app
+ * cached `get<Service>(app?)` factory matching `firebase-admin`'s
+ * `firebaseApp.getOrInitService(...)`.
+ */
+export function wireDeferredService<T extends object>(
+  ctor: { prototype: T },
+  subpath: string,
+  owner: string,
+  members: DeferredMembers,
+): (app?: PyricAdminApp) => T {
+  defineDeferredMembers(ctor.prototype, `pyric-admin/${subpath}`, owner, members);
+  const instances = new WeakMap<PyricAdminApp, T>();
+  return function getDeferredService(app?: PyricAdminApp): T {
+    const resolved = resolveActiveAdminApp(app);
+    const existing = instances.get(resolved);
+    if (existing !== undefined) return existing;
+    const created = new (ctor as unknown as new (...ctorArgs: unknown[]) => T)(
+      DEFERRED_SERVICE_TOKEN,
+      resolved,
+    );
+    instances.set(resolved, created);
+    return created;
+  };
+}

package/src/eventarc/index.ts

@@ -1,14 +1,37 @@
 /**
- * `pyric-admin/eventarc`: a deferred entry for `firebase-admin/eventarc`.
- *
- * The sandbox does not model Eventarc. Every value `firebase-admin/eventarc`
- * exports is present so imports link; using one throws `PyricDeferredApiError`.
- * See `../deferred.ts`.
+ * `pyric-admin/eventarc`: deferred service handle for `firebase-admin/eventarc`.
  */
-import { deferredAdminEntry } from '../deferred.js';
+import type { PyricAdminApp } from '../app/index.js';
+import {
+  deferredAdminEntry,
+  guardDeferredServiceApp,
+  wireDeferredService,
+} from '../deferred.js';
 
 export { PyricDeferredApiError } from '../deferred.js';
 
-export const {
-  Channel, Eventarc, getEventarc,
-} = deferredAdminEntry('eventarc');
+export class Eventarc {
+  readonly #app: PyricAdminApp;
+
+  /** @internal */
+  constructor(...args: unknown[]) {
+    this.#app = guardDeferredServiceApp('eventarc', 'Eventarc', args);
+  }
+
+  get app(): PyricAdminApp {
+    return this.#app;
+  }
+
+  declare channel: (...args: unknown[]) => never;
+}
+
+export const getEventarc: (app?: PyricAdminApp) => Eventarc = wireDeferredService(
+  Eventarc,
+  'eventarc',
+  'Eventarc',
+  {
+    sync: ['channel'],
+  },
+);
+
+export const { Channel } = deferredAdminEntry('eventarc');