pyric 0.1.0-alpha.19 → 0.1.0-alpha.21

package/src/database/controls.ts

@@ -69,7 +69,7 @@ export function forceWebSockets(): void {
  *
  * Accepted no-op: the sandbox has no modular-SDK-style logger to wire a
  * level/sink into (it uses host-level `console` logging directly, gated
- * by `pyric dev`'s own flags — matching `pyric/firestore`'s
+ * by `pyric sandbox`'s own flags — matching `pyric/firestore`'s
  * `setLogLevel`). Accepted so init code that calls it compiles + runs.
  */
 export function enableLogging(

package/src/database/instances.ts

@@ -119,7 +119,7 @@ export function getAdminDatabase(target: Sandbox | SandboxContext | FirebaseApp)
 
 function packageResolutionError(): TypeError {
   return new TypeError(
-    'pyric/database is a sandbox-only mirror. Package resolution must leave firebase/database unchanged for production; activate pyric dev or @pyric/cli/register before importing to select the sandbox.',
+    'pyric/database is a sandbox-only mirror. Package resolution must leave firebase/database unchanged for production; activate pyric sandbox or @pyric/cli/register before importing to select the sandbox.',
   );
 }
 

package/src/database/sandbox/backend.ts

@@ -42,6 +42,7 @@ export class RtdbBackend {
   getPriority(path: string): Priority { return this.state.priorities.get(path); }
   setData(seed: Record<string, JsonValue>): void { this.writes.setData(seed); }
   setRules(rules: { rules: Record<string, unknown> } | null): void { this.writes.setRules(rules); }
+  setDefaultPolicy(policy: 'allow' | 'deny'): void { this.writes.setDefaultPolicy(policy); }
   getActiveRules(): { rules: Record<string, unknown> } | null { return this.writes.getActiveRules(); }
   snapshotState(): JsonValue { return this.writes.snapshotState(); }
 

package/src/database/sandbox/rules-eval.ts

@@ -95,11 +95,19 @@ export interface EvalContext {
   updates?: { path: string; value: unknown }[];
 }
 
+export type RtdbDefaultPolicy = 'allow' | 'deny';
+
 export class RulesEvaluator {
   private compiled: CompiledRtdbRules | null = null;
+  private defaultPolicy: RtdbDefaultPolicy = 'deny';
+
+  /** Set default access policy when no rules are loaded ('allow' or 'deny'). */
+  setDefaultPolicy(policy: RtdbDefaultPolicy): void {
+    this.defaultPolicy = policy;
+  }
 
   /** Replace the deployed rules. `null` clears (sandbox returns to
-   *  default-allow). */
+   *  configured default policy). */
   setRules(rulesJson: { rules: Record<string, unknown> } | null): void {
     if (rulesJson === null) {
       this.compiled = null;
@@ -114,7 +122,7 @@ export class RulesEvaluator {
   }
 
   /**
-   * Evaluate one op. Default-allow when no rules are loaded.
+   * Evaluate one op. Default-deny when no rules are loaded.
    *
    * Errors from the underlying simulator (grammar mismatches, etc.)
    * surface as `'no-rule'` — they're treated as deny by user-mode
@@ -161,6 +169,14 @@ export class RulesEvaluator {
       }
     }
     if (this.compiled === null) {
+      if (this.defaultPolicy === 'deny') {
+        return {
+          check: 'no-rule',
+          reasons: ['No RTDB rules loaded; default deny.'],
+          errorCode: 'NO_MATCHING_RULE',
+          errorMessage: 'No RTDB rules loaded; default deny.',
+        };
+      }
       return {
         check: 'allow',
         reasons: ['No RTDB rules loaded; default allow.'],

package/src/database/sandbox/write-plane.ts

@@ -52,6 +52,12 @@ export class WritePlane {
     this.state.notifyWrite();
   }
 
+  setDefaultPolicy(policy: 'allow' | 'deny'): void {
+    this.state.rules.setDefaultPolicy(policy);
+    this.cancelDeniedListeners();
+    this.state.notifyWrite();
+  }
+
   getActiveRules(): { rules: Record<string, unknown> } | null {
     const isRulesNull = this.state.activeRules === null;
     let result: { rules: Record<string, unknown> } | null = null;
@@ -227,7 +233,7 @@ export class WritePlane {
     });
     for (const update of updates) {
       if (this.state.rules.evaluate('write', update.path, {
-        auth, mockData, newData: update.value, ...(updates.length > 1 ? { updates } : {}),
+        auth, mockData, newData: update.value, updates,
       }).check !== 'allow') throw permissionDenied();
     }
   }
@@ -246,7 +252,7 @@ export class WritePlane {
       const at = Date.now();
       const before = this.state.tree.read(update.path);
       const evaluation = this.state.rules.evaluate('write', update.path, {
-        auth, mockData, newData: update.value, ...(multiPath ? { updates } : {}),
+        auth, mockData, newData: update.value, updates,
       });
       const fields = {
         at, durationMs: Date.now() - at, origin: 'batch' as const,

package/src/database/sandbox-controls.ts

@@ -2,34 +2,54 @@
 import type { LocalSandbox } from 'pyric/sandbox';
 
 import { getOrCreateBackend } from './sandbox/backend-for.js';
+import type { RtdbBackend } from './sandbox/backend.js';
 import type { JsonValue } from './sandbox/data-tree.js';
+import { TARGET_SYMBOL, targetOf } from './routing.js';
 
 export type RtdbRulesJson = { rules: Record<string, unknown> };
 
-/** Replace the active RTDB rules. Pass `null` to restore default allow. */
+/** Target accepting either a LocalSandbox root or a branded Database handle. */
+export type RtdbTarget = LocalSandbox | { [TARGET_SYMBOL]: unknown };
+
+function backendOf(target: RtdbTarget): RtdbBackend {
+  if (target && typeof target === 'object' && TARGET_SYMBOL in target) {
+    return targetOf(target).backend;
+  }
+  return getOrCreateBackend(target as LocalSandbox);
+}
+
+/** Set default access policy when no rules are loaded ('allow' or 'deny'). Internal test/dev harness control. */
+export function setDefaultPolicy(
+  target: RtdbTarget,
+  policy: 'allow' | 'deny',
+): void {
+  backendOf(target).setDefaultPolicy(policy);
+}
+
+/** Replace the active RTDB rules. Pass `null` to restore default deny. */
 export function setRules(
-  sandbox: LocalSandbox,
+  target: RtdbTarget,
   rules: RtdbRulesJson | null,
 ): void {
-  getOrCreateBackend(sandbox).setRules(rules);
+  backendOf(target).setRules(rules);
 }
 
 /** Read the currently active rules as detached JSON. */
-export function getActiveRules(sandbox: LocalSandbox): RtdbRulesJson | null {
-  return getOrCreateBackend(sandbox).getActiveRules();
+export function getActiveRules(target: RtdbTarget): RtdbRulesJson | null {
+  return backendOf(target).getActiveRules();
 }
 
 /** Replace RTDB data in bulk without applying security rules. */
 export function setData(
-  sandbox: LocalSandbox,
+  target: RtdbTarget,
   data: Record<string, unknown>,
 ): void {
-  getOrCreateBackend(sandbox).setData(data as Record<string, JsonValue>);
+  backendOf(target).setData(data as Record<string, JsonValue>);
 }
 
 /** Snapshot the complete RTDB tree without applying security rules. */
-export function snapshotState(sandbox: LocalSandbox): JsonValue {
-  return getOrCreateBackend(sandbox).snapshotState();
+export function snapshotState(target: RtdbTarget): JsonValue {
+  return backendOf(target).snapshotState();
 }
 
 /**

package/src/database/sandbox-namespace.ts

@@ -7,10 +7,37 @@ import type { Database } from './types.js';
 // Mirrors `pyric/firestore`'s `sandbox` namespace — explicit
 // per-package sandbox lifecycle.
 
+export const DEFAULT_DENY_RTDB_RULES: { rules: Record<string, unknown> } = {
+  rules: {
+    '.read': false,
+    '.write': false,
+  },
+};
+
+export const DEFAULT_OPEN_RTDB_RULES: { rules: Record<string, unknown> } = {
+  rules: {
+    '.read': true,
+    '.write': true,
+  },
+};
+
 export const sandbox = {
+  DEFAULT_DENY_RULES: DEFAULT_DENY_RTDB_RULES,
+  DEFAULT_OPEN_RULES: DEFAULT_OPEN_RTDB_RULES,
+
+  /**
+   * Set the default access policy when no rules are loaded ('allow' or 'deny').
+   * In 'deny' mode (matching production Firebase), all client reads and writes
+   * without rules are rejected with PERMISSION_DENIED.
+   */
+  setDefaultPolicy(db: Database, policy: 'allow' | 'deny'): void {
+    const target = targetOf(db);
+    target.backend.setDefaultPolicy(policy);
+  },
+
   /**
    * Replace deployed rules. Pass `null` to clear (sandbox returns to
-   * default-allow). Rules are evaluated through the existing
+   * default policy). Rules are evaluated through the existing
    * RTDB rules simulator — the same engine used by the rules tooling.
    *
    * @example

package/src/deferred/entry.ts

@@ -0,0 +1,167 @@
+/**
+ * The shared factory behind pyric's *deferred* Firebase Web SDK subpaths —
+ * `pyric/functions`, `pyric/analytics`, `pyric/app-check`,
+ * `pyric/firestore/lite`, `pyric/performance` and `pyric/remote-config`.
+ *
+ * WHY THESE EXIST AT ALL. pyric is a symbol-for-symbol drop-in for the
+ * Firebase Web SDK: an app swaps the `firebase` specifier for `pyric` and its
+ * module graph must keep loading. A subpath that is simply absent from the
+ * package `exports` map fails at RESOLVE time — Node raises
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED`, bundlers raise their own variants — long
+ * before any pyric code runs. That error names neither pyric nor the reason,
+ * so a developer whose app merely *mentions* `firebase/functions` on a code
+ * path it never takes sees an unattributable build failure.
+ *
+ * THE CONTRACT. Resolution and linking succeed; *use* fails loudly.
+ *   - The subpath resolves, so the module graph loads.
+ *   - Every symbol the real Firebase entry exports is present as a value, so
+ *     named-import linking (which is static in ESM — a missing name is a link
+ *     error, not a runtime one) succeeds and bundlers can tree-shake.
+ *   - Calling, constructing, or reading a member off one of those values
+ *     throws {@link PyricDeferredApiError} with a message that names the
+ *     subpath and points at the conformance matrix.
+ *
+ * An app that imports but never calls therefore runs unchanged. An app that
+ * genuinely depends on a deferred service gets one clear, attributed error at
+ * the exact call site instead of a cryptic resolver failure.
+ *
+ * NOT a mirror. These entries deliberately implement nothing. They are marked
+ * deferred in the conformance surface story and must never be counted as
+ * implemented surface.
+ */
+
+/**
+ * Compose the single user-facing message every deferred entry raises.
+ *
+ * @param subpath - The Firebase subpath *without* the `firebase/` prefix, e.g.
+ *   `functions` or `firestore/lite`.
+ */
+function deferredApiMessage(subpath: string): string {
+  return (
+    `pyric: 'firebase/${subpath}' is not yet mirrored by the local sandbox. ` +
+    'This API is deferred — see the conformance matrix. Imports resolve so ' +
+    'module graphs load; calls fail with this message.'
+  );
+}
+
+/**
+ * The error thrown by every deferred Firebase entry. Carries the subpath and
+ * the symbol that was touched so tooling can group these without parsing the
+ * message.
+ */
+export class PyricDeferredApiError extends Error {
+  override readonly name = 'PyricDeferredApiError';
+
+  /** The Firebase subpath, without the `firebase/` prefix (e.g. `functions`). */
+  readonly subpath: string;
+
+  /** The exported symbol whose use triggered this error (e.g. `getFunctions`). */
+  readonly symbol: string;
+
+  constructor(subpath: string, symbol: string) {
+    super(deferredApiMessage(subpath));
+    this.subpath = subpath;
+    this.symbol = symbol;
+  }
+}
+
+/**
+ * The static type of a deferred export.
+ *
+ * It is callable, constructible, and indexable so a deferred symbol can stand
+ * in for any of the three shapes a Firebase entry exports — a factory function
+ * (`getFunctions`), a class (`ReCaptchaV3Provider`), or an enum-like constant
+ * object (`HarmCategory`). Every result is `never`, which is assignable to
+ * anything, so a consumer's own annotations keep type-checking.
+ */
+export interface DeferredApi {
+  (...args: readonly unknown[]): never;
+  new (...args: readonly unknown[]): never;
+  readonly [member: string]: never;
+}
+
+/**
+ * Property reads that must NOT throw.
+ *
+ * Bundlers, test runners, `console.log`, promise adoption and React all probe
+ * values with these keys as part of ordinary machinery, never as an intent to
+ * use the API. Throwing on `then` in particular would turn `await`-ing
+ * anything holding a deferred value into this error at the wrong site, and
+ * throwing on `$$typeof` would break React's element check. They read as
+ * `undefined`, exactly as they would on a real function.
+ */
+const INERT_PROPERTIES: ReadonlySet<string> = new Set([
+  '$$typeof',
+  '__esModule',
+  'constructor',
+  'displayName',
+  'inspect',
+  'length',
+  'name',
+  'nodeType',
+  'prototype',
+  'then',
+  'toJSON',
+  'toString',
+  'valueOf',
+]);
+
+/**
+ * Build one deferred export: a function that throws when called or
+ * constructed, wrapped in a proxy so member reads (the enum-constant shape)
+ * throw the same error.
+ */
+function deferredSymbol(subpath: string, symbol: string): DeferredApi {
+  const throwing = function deferred(): never {
+    throw new PyricDeferredApiError(subpath, symbol);
+  };
+  Object.defineProperty(throwing, 'name', { value: symbol, configurable: true });
+
+  return new Proxy(throwing, {
+    get(target, property, receiver) {
+      // Symbol-keyed reads are always machinery (Symbol.toPrimitive,
+      // Symbol.hasInstance, Symbol.toStringTag, the inspect hook, …) — never a
+      // user reaching for an API member.
+      if (typeof property === 'symbol' || INERT_PROPERTIES.has(property)) {
+        return Reflect.get(target, property, receiver);
+      }
+      throw new PyricDeferredApiError(subpath, `${symbol}.${property}`);
+    },
+    construct() {
+      throw new PyricDeferredApiError(subpath, symbol);
+    },
+  }) as unknown as DeferredApi;
+}
+
+/**
+ * The lazily-materialised export bag for one deferred subpath.
+ *
+ * Each entry module destructures the symbols it needs off this object:
+ *
+ * ```ts
+ * export const { getFunctions, httpsCallable } = deferredEntry('functions');
+ * ```
+ *
+ * Destructuring is what makes the names real ESM exports (and what keeps the
+ * generated `.d.ts` honest); the proxy just mints a correctly-attributed stub
+ * for whichever name is read.
+ *
+ * @param subpath - The Firebase subpath, without the `firebase/` prefix.
+ */
+export function deferredEntry(subpath: string): Record<string, DeferredApi> {
+  const minted = new Map<string, DeferredApi>();
+  return new Proxy(Object.create(null) as Record<string, DeferredApi>, {
+    get(_target, property) {
+      if (typeof property === 'symbol') return undefined as unknown as DeferredApi;
+      let api = minted.get(property);
+      if (!api) {
+        api = deferredSymbol(subpath, property);
+        minted.set(property, api);
+      }
+      return api;
+    },
+    has() {
+      return true;
+    },
+  });
+}

package/src/firestore/instances.ts

@@ -115,7 +115,7 @@ export function getFirestore(target?: SandboxContext | Sandbox | FirebaseApp): F
     return { [TARGET_SYMBOL]: t };
   }
   throw new TypeError(
-    'pyric/firestore is a sandbox-only mirror. Package resolution must leave firebase/firestore unchanged for production; activate pyric dev or @pyric/cli/register before importing to select the sandbox.',
+    'pyric/firestore is a sandbox-only mirror. Package resolution must leave firebase/firestore unchanged for production; activate pyric sandbox or @pyric/cli/register before importing to select the sandbox.',
   );
 }
 

package/src/firestore/lite.ts

@@ -0,0 +1,91 @@
+/**
+ * `pyric/firestore/lite` — a DEFERRED mirror of `firebase/firestore/lite`.
+ *
+ * The Lite SDK is a separate build of Firestore with no local cache, no
+ * listeners and no offline queue. pyric mirrors the full `firebase/firestore`
+ * surface against the in-process sandbox; the Lite build needs its own
+ * cache-free instance identity, so it is deferred rather than aliased — an
+ * alias would silently give Lite consumers listener-backed semantics the real
+ * Lite SDK does not have.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/firestore/lite`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  AggregateField, AggregateQuerySnapshot, Bytes, CollectionReference, DocumentReference,
+  DocumentSnapshot, FieldPath, FieldValue, Firestore, FirestoreError, GeoPoint, Query,
+  QueryCompositeFilterConstraint, QueryConstraint, QueryDocumentSnapshot, QueryEndAtConstraint,
+  QueryFieldFilterConstraint, QueryLimitConstraint, QueryOrderByConstraint, QuerySnapshot,
+  QueryStartAtConstraint, Timestamp, Transaction, VectorValue, WriteBatch, addDoc,
+  aggregateFieldEqual, aggregateQuerySnapshotEqual, and, arrayRemove, arrayUnion, average,
+  collection, collectionGroup, connectFirestoreEmulator, count, deleteDoc, deleteField, doc,
+  documentId, endAt, endBefore, getAggregate, getCount, getDoc, getDocs, getFirestore,
+  increment, initializeFirestore, limit, limitToLast, or, orderBy, query, queryEqual, refEqual,
+  runTransaction, serverTimestamp, setDoc, setLogLevel, snapshotEqual, startAfter, startAt,
+  sum, terminate, updateDoc, vector, where, writeBatch,
+} = deferredEntry('firestore/lite');
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type AddPrefixToKeys = DeferredApi;
+export type AggregateField = DeferredApi;
+export type AggregateFieldType = DeferredApi;
+export type AggregateQuerySnapshot = DeferredApi;
+export type AggregateSpec = DeferredApi;
+export type AggregateSpecData = DeferredApi;
+export type AggregateType = DeferredApi;
+export type Bytes = DeferredApi;
+export type ChildUpdateFields = DeferredApi;
+export type CollectionReference = DeferredApi;
+export type DocumentData = DeferredApi;
+export type DocumentReference = DeferredApi;
+export type DocumentSnapshot = DeferredApi;
+export type EmulatorMockTokenOptions = DeferredApi;
+export type FieldPath = DeferredApi;
+export type FieldValue = DeferredApi;
+export type Firestore = DeferredApi;
+export type FirestoreDataConverter = DeferredApi;
+export type FirestoreError = DeferredApi;
+export type FirestoreErrorCode = DeferredApi;
+export type GeoPoint = DeferredApi;
+export type LogLevel = DeferredApi;
+export type NestedUpdateFields = DeferredApi;
+export type OrderByDirection = DeferredApi;
+export type PartialWithFieldValue = DeferredApi;
+export type Primitive = DeferredApi;
+export type Query = DeferredApi;
+export type QueryCompositeFilterConstraint = DeferredApi;
+export type QueryConstraint = DeferredApi;
+export type QueryConstraintType = DeferredApi;
+export type QueryDocumentSnapshot = DeferredApi;
+export type QueryEndAtConstraint = DeferredApi;
+export type QueryFieldFilterConstraint = DeferredApi;
+export type QueryFilterConstraint = DeferredApi;
+export type QueryLimitConstraint = DeferredApi;
+export type QueryNonFilterConstraint = DeferredApi;
+export type QueryOrderByConstraint = DeferredApi;
+export type QuerySnapshot = DeferredApi;
+export type QueryStartAtConstraint = DeferredApi;
+export type SetOptions = DeferredApi;
+export type Settings = DeferredApi;
+export type Timestamp = DeferredApi;
+export type Transaction = DeferredApi;
+export type TransactionOptions = DeferredApi;
+export type UnionToIntersection = DeferredApi;
+export type UpdateData = DeferredApi;
+export type VectorValue = DeferredApi;
+export type WhereFilterOp = DeferredApi;
+export type WithFieldValue = DeferredApi;
+export type WriteBatch = DeferredApi;

package/src/firestore/persistence.ts

@@ -191,7 +191,7 @@ const TAB_MANAGER_SYMBOL: unique symbol = Symbol('pyric/firestore/tabManager');
 const GC_SYMBOL: unique symbol = Symbol('pyric/firestore/gc');
 
 /** Opaque tab-manager config token. Inert — persistence is always on,
- *  and the SharedWorker/`pyric dev` path already is the one shared
+ *  and the SharedWorker/`pyric sandbox` path already is the one shared
  *  store every tab talks to, so there is no separate multi-tab mode
  *  to opt into. Carries the requested kind only for debugging. */
 export interface PersistentTabManager {
@@ -409,7 +409,7 @@ export type LogLevel = 'debug' | 'verbose' | 'info' | 'warn' | 'error' | 'silent
 /**
  * Accepted no-op: the sandbox has no modular-SDK-style logger to wire
  * a level into (it uses host-level `console` logging directly, gated
- * by `pyric dev`'s own flags, not this call). Exists purely so app
+ * by `pyric sandbox`'s own flags, not this call). Exists purely so app
  * code that calls this defensively at startup doesn't crash on a
  * missing export.
  */

package/src/firestore/sandbox-controls.ts

@@ -41,6 +41,8 @@ export interface FirestoreInspectReport {
       method: string;
       auth: unknown;
       debugMessage?: string;
+      rule?: unknown;
+      reasons?: string[];
     }>;
     recentRequests: Array<{
       path: string;
@@ -187,11 +189,19 @@ export function inspect(
     if (typeof event.debugMessage === 'string') {
       debugMessageVal = event.debugMessage;
     }
+    const ruleVal = (event as any).evaluatedRule ?? (event as any).rule ?? undefined;
+    const reasonsVal = Array.isArray((event as any).debugMessages)
+      ? (event as any).debugMessages
+      : typeof event.debugMessage === 'string'
+      ? [event.debugMessage]
+      : undefined;
     return {
       path: pathVal,
       method: methodVal,
       auth: authVal,
       debugMessage: debugMessageVal,
+      rule: ruleVal,
+      reasons: reasonsVal,
     };
   });
 

package/src/functions/index.ts

@@ -0,0 +1,38 @@
+/**
+ * `pyric/functions` — a DEFERRED mirror of `firebase/functions`.
+ *
+ * Callable Cloud Functions dispatch to deployed server code. Mirroring this
+ * means running the user’s functions, which is the emulator’s job, not the
+ * in-process sandbox’s — deferred pending a decision on the function-host
+ * seam.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/functions`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  FunctionsError, connectFunctionsEmulator, getFunctions, httpsCallable, httpsCallableFromURL,
+} = deferredEntry('functions');
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type Functions = DeferredApi;
+export type FunctionsError = DeferredApi;
+export type FunctionsErrorCode = DeferredApi;
+export type FunctionsErrorCodeCore = DeferredApi;
+export type HttpsCallable = DeferredApi;
+export type HttpsCallableOptions = DeferredApi;
+export type HttpsCallableResult = DeferredApi;
+export type HttpsCallableStreamOptions = DeferredApi;
+export type HttpsCallableStreamResult = DeferredApi;

package/src/messaging/client.ts

@@ -14,6 +14,7 @@
  * upstream counterpart and is additive to the mirrored surface.
  */
 import type { FirebaseApp } from '../app/types.js';
+import type { Sandbox, SandboxContext } from '../sandbox/index.js';
 import {
   defaultRegistration,
   deliverToMessaging,
@@ -88,8 +89,8 @@ export interface GetTokenOptions {
  * Return the FCM `Messaging` instance for the given (or default) app —
  * window-client plane (upstream component name `messaging`).
  */
-export function getMessaging(app?: FirebaseApp): Messaging {
-  return resolveMessaging('window', app);
+export function getMessaging(target?: FirebaseApp | Sandbox | SandboxContext): Messaging {
+  return resolveMessaging('window', target);
 }
 
 /**

package/src/messaging/instance.ts

@@ -12,7 +12,8 @@
  */
 import type { FirebaseApp } from '../app/types.js';
 import { defaultClientApp, resolveClientApp } from '../sandbox/internal/client-app.js';
-import type { Sandbox } from '../sandbox/types/service.js';
+import type { Sandbox, SandboxContext } from '../sandbox/index.js';
+import { SandboxContextImpl } from '../sandbox/index.js';
 import { DEFAULT_CLIENT_ID, getMessagingBroker, MessagingBroker } from './broker/index.js';
 import type { DeliveredPayload, DeliveryResult } from './broker/index.js';
 
@@ -38,6 +39,22 @@ interface InstanceState {
 const instanceState = new WeakMap<Messaging, InstanceState>();
 /** One instance per (app, plane); brokers remain shared by sandbox. */
 const instancesByApp = new WeakMap<FirebaseApp, Partial<Record<MessagingPlane, Messaging>>>();
+const instancesBySandbox = new WeakMap<Sandbox, Partial<Record<MessagingPlane, Messaging>>>();
+
+function isSandboxContext(target: unknown): target is SandboxContext {
+  return target instanceof SandboxContextImpl;
+}
+
+function isSandbox(target: unknown): target is Sandbox {
+  if (target === null || typeof target !== 'object') return false;
+  const o = target as Record<string, unknown>;
+  return (
+    typeof o.withAuth === 'function' &&
+    typeof o.onCurrentUserChanged === 'function' &&
+    'currentUser' in o &&
+    'admin' in o
+  );
+}
 
 // ── Simulated service-worker registrations ──────────────────────────────────
 
@@ -81,19 +98,39 @@ function resolveDefaultApp(): FirebaseApp {
 
 // ── Instance resolution ──────────────────────────────────────────────────────
 
-export function resolveMessaging(plane: MessagingPlane, app?: FirebaseApp): Messaging {
-  const resolved = app ?? resolveDefaultApp();
-  const runtime = resolveClientApp(resolved);
+export function resolveMessaging(plane: MessagingPlane, target?: FirebaseApp | Sandbox | SandboxContext): Messaging {
+  const resolved = target ?? resolveDefaultApp();
+  if (isSandbox(resolved) || isSandboxContext(resolved)) {
+    const sandbox = isSandboxContext(resolved) ? resolved.sandbox : resolved;
+    const bySandbox = instancesBySandbox.get(sandbox) ?? {};
+    instancesBySandbox.set(sandbox, bySandbox);
+    const existing = bySandbox[plane];
+    if (existing !== undefined) return existing;
+
+    const broker = getMessagingBroker(sandbox);
+    const instance: Messaging = { app: undefined as unknown as FirebaseApp };
+    instanceState.set(instance, {
+      broker,
+      sandbox,
+      plane,
+      activeRegistrationId: registrationIdOf(DEFAULT_REGISTRATION),
+      own: (cleanup) => () => { cleanup(); },
+    });
+    bySandbox[plane] = instance;
+    return instance;
+  }
+  const app = resolved as FirebaseApp;
+  const runtime = resolveClientApp(app);
   if (!runtime) throw new TypeError('pyric/messaging: unrecognized FirebaseApp handle');
   const sandbox = runtime.sandbox;
-  const byApp = instancesByApp.get(resolved) ?? {};
-  instancesByApp.set(resolved, byApp);
+  const byApp = instancesByApp.get(app) ?? {};
+  instancesByApp.set(app, byApp);
   const existing = byApp[plane];
   if (existing !== undefined) return existing;
   runtime.assertAlive();
 
   const broker = getMessagingBroker(sandbox);
-  const instance: Messaging = { app: resolved };
+  const instance: Messaging = { app };
   instanceState.set(instance, {
     broker,
     sandbox,