pyric 0.1.0-alpha.20 → 0.1.0-alpha.21

package/src/ai/broker/openai-engine.ts

@@ -29,6 +29,7 @@ import {
   Synthesizer,
   errorEnvelope,
   estimateTokens,
+  redactUrl,
   resolveModelVersion,
 } from './synthesizer.js';
 import { promptTextOf } from './scripted-engine.js';
@@ -37,6 +38,7 @@ import type {
   CountTokensRequest,
   CountTokensResponse,
   GenerateContentRequest,
+  ModelResolution,
   WireChunk,
   WirePart,
   WireResponse,
@@ -487,10 +489,27 @@ export class OpenAiEngine implements AnswerEngine {
     );
   }
 
+  /**
+   * Gemini model id to upstream model, WITH the reason: `modelMap[model]` ??
+   * `config.model` ?? passthrough. The reason is what makes the redirect
+   * legible in the dev terminal: "which of my three knobs sent this
+   * elsewhere?" is the whole question when the answer came from a model the
+   * developer never named. Bare (never `models/`-prefixed), per
+   * {@link AnswerEngine.resolveEffectiveModel}.
+   */
+  resolveEffectiveModel(model: string): ModelResolution {
+    const bare = model.startsWith('models/') ? model.slice('models/'.length) : model;
+    const mapped = this.modelMap[bare] ?? this.modelMap[model];
+    if (mapped !== undefined) return { model: mapped, reason: 'engine modelMap' };
+    if (this.defaultModel !== undefined) {
+      return { model: this.defaultModel, reason: 'engine catch-all model' };
+    }
+    return { model: bare, reason: 'passthrough' };
+  }
+
   /** Gemini model id → upstream model: modelMap[model] ?? config.model ?? passthrough. */
   resolveUpstreamModel(model: string): string {
-    const bare = model.startsWith('models/') ? model.slice('models/'.length) : model;
-    return this.modelMap[bare] ?? this.modelMap[model] ?? this.defaultModel ?? bare;
+    return this.resolveEffectiveModel(model).model;
   }
 
   async generateContent(req: GenerateContentRequest, model: string): Promise<WireResponse> {
@@ -627,8 +646,17 @@ export class OpenAiEngine implements AnswerEngine {
         body: JSON.stringify(body),
       });
     } catch (err) {
+      // The openai engine has no key-in-URL auth mechanism today
+      // (`OpenAiEngineOptions` carries no `apiKey`), but a caller-supplied
+      // `baseUrl` could embed a credential in its query string, and some
+      // fetch implementations echo the request URL into their error text —
+      // redact defensively at this choke point (T1.7).
       throw new AiBrokerError(
-        errorEnvelope(502, `openai engine: upstream fetch failed: ${String(err)}`, 'UNAVAILABLE'),
+        errorEnvelope(
+          502,
+          `openai engine: upstream fetch failed: ${redactUrl(String(err))}`,
+          'UNAVAILABLE',
+        ),
       );
     }
     if (!res.ok) {

package/src/ai/broker/synthesizer.ts

@@ -117,6 +117,40 @@ export function errorEnvelope(code: number, message: string, status: string): Wi
   return { error: { code, message, status } };
 }
 
+// ── URL redaction (T1.7) ─────────────────────────────────────────────────
+
+/**
+ * Query-param names that carry plaintext credentials on upstream REST
+ * requests (Google AI Studio's `?key=...` auth is the known case; the rest
+ * are defensive for sibling engines / future upstreams).
+ *
+ * Matched with a direct regex over the raw string rather than
+ * `new URL(...).searchParams` — the streaming action string embeds its own
+ * `?alt=sse` before the `?key=` is appended (a pre-existing, unrelated
+ * quirk this fix does not touch), which the strict `URLSearchParams` parser
+ * would fold into a single malformed pair and fail to redact. A regex on
+ * "`[?&]<param>=`" catches the value regardless of how the surrounding
+ * query string is (mal)formed.
+ */
+const SENSITIVE_URL_PARAM_PATTERN = /([?&](?:key|apiKey|api_key|access_token)=)[^&\s]*/gi;
+
+/**
+ * Redacts credential-bearing query-string VALUES from a URL (or any string
+ * that may embed one) before it lands in an error message or log line —
+ * e.g. `?key=AIza...` becomes `?key=***`. Host and path are preserved so
+ * the message stays useful for diagnosing connectivity failures; only the
+ * secret value is masked.
+ *
+ * Used at every choke point where an upstream request URL is interpolated
+ * into a thrown error or logged text, so a leaked key never reaches
+ * terminal output, CI logs, or Studio traffic captures. Safe to apply
+ * defensively to values that are not themselves URLs (e.g. a raw fetch
+ * error message) — it is a no-op when no sensitive param is present.
+ */
+export function redactUrl(url: string): string {
+  return url.replace(SENSITIVE_URL_PARAM_PATTERN, '$1***');
+}
+
 /** `ai-error-unknown-model` (404 NOT_FOUND), captured text verbatim — including production's `v1main`. */
 export function unknownModel(name: string): WireErrorEnvelope {
   return errorEnvelope(

package/src/ai/broker/types.ts

@@ -136,6 +136,31 @@ export interface AnswerEngine {
   generateContent(req: GenerateContentRequest, model: string): Promise<WireResponse>;
   streamGenerateContent(req: GenerateContentRequest, model: string): AsyncIterable<WireChunk>;
   countTokens(req: CountTokensRequest, model: string): Promise<CountTokensResponse>;
+  /**
+   * OPTIONAL self-report: which model this engine will ACTUALLY answer with
+   * for a requested Gemini model id, and why it differs. Engines that redirect
+   * silently (an openai `modelMap` entry or catch-all `model`, a gemini
+   * experimental alias) implement it so the broker can announce the swap on
+   * the event stream. A developer must never believe they tested model X when
+   * model Y answered.
+   *
+   * Engines that never substitute (scripted, a caller's custom engine) omit
+   * the method entirely, and the broker stays silent for them.
+   */
+  resolveEffectiveModel?(model: string): ModelResolution;
+}
+
+/**
+ * Which model an engine answers with, and why it differs from the one the
+ * request named.
+ *
+ * `model` is BARE (no `models/` prefix) so the broker can compare it against
+ * the requested id without the prefix reading as a substitution. `reason` is
+ * a short phrase for the terminal line, e.g. `engine modelMap`.
+ */
+export interface ModelResolution {
+  model: string;
+  reason: string;
 }
 
 // ── Scripted authoring ──────────────────────────────────────────────────────

package/src/ai/internal.ts

@@ -6,6 +6,11 @@ import { TARGET_SYMBOL } from './target.js';
 import type { AI, AIOptions, TransportTarget } from './types.js';
 
 export { aiErrorFromEnvelope } from './errors.js';
+/** Host-only seam for the dev server's terminal diagnostics: the credential
+ *  masking every printed upstream URL goes through, and the gemini endpoint
+ *  the startup banner names when no `baseUrl` overrides it. Published here so
+ *  `@pyric/cli` reads one definition instead of copying both. */
+export { GEMINI_DEFAULT_BASE_URL, redactUrl } from './broker/index.js';
 
 const transportHandles = new WeakMap<FirebaseApp, Map<string, AI>>();
 

package/src/ai/response-helpers.ts

@@ -21,7 +21,7 @@
 
 import type { WireCandidate, WirePart, WireResponse } from './broker/index.js';
 import { AIError, AIErrorCode } from './errors.js';
-import { FinishReason } from './enums.js';
+import { isBlockingFinishReason } from './blocked.js';
 
 /** The wire envelope plus the SDK's helper methods. */
 export interface EnhancedResponse extends WireResponse {
@@ -31,28 +31,9 @@ export interface EnhancedResponse extends WireResponse {
   functionCalls(): Array<NonNullable<WirePart['functionCall']>> | undefined;
 }
 
-const badFinishReasons: string[] = [
-  FinishReason.RECITATION,
-  FinishReason.SAFETY,
-  FinishReason.BLOCKLIST,
-  FinishReason.PROHIBITED_CONTENT,
-  FinishReason.SPII,
-  FinishReason.MALFORMED_FUNCTION_CALL,
-  FinishReason.IMAGE_SAFETY,
-  FinishReason.IMAGE_PROHIBITED_CONTENT,
-  FinishReason.IMAGE_OTHER,
-  FinishReason.NO_IMAGE,
-  FinishReason.IMAGE_RECITATION,
-  FinishReason.LANGUAGE,
-  FinishReason.UNEXPECTED_TOOL_CALL,
-  FinishReason.TOO_MANY_TOOL_CALLS,
-  FinishReason.MISSING_THOUGHT_SIGNATURE,
-  FinishReason.MALFORMED_RESPONSE,
-];
-
-function hadBadFinishReason(candidate: WireCandidate): boolean {
-  return !!candidate.finishReason && badFinishReasons.some((r) => r === candidate.finishReason);
-}
+// Upstream's `badFinishReasons` set lives in `blocked.ts`: the broker
+// announces the SAME set on the event stream (`response_blocked`), and the
+// two must never drift apart.
 
 export function formatBlockErrorMessage(response: WireResponse): string {
   let message = '';
@@ -63,7 +44,7 @@ export function formatBlockErrorMessage(response: WireResponse): string {
     }
   } else if (response.candidates?.[0]) {
     const firstCandidate = response.candidates[0];
-    if (hadBadFinishReason(firstCandidate)) {
+    if (isBlockingFinishReason(firstCandidate.finishReason)) {
       message += `Candidate was blocked due to ${firstCandidate.finishReason}`;
       if (firstCandidate.finishMessage) {
         message += `: ${firstCandidate.finishMessage}`;
@@ -76,7 +57,7 @@ export function formatBlockErrorMessage(response: WireResponse): string {
 /** At least one candidate exists and the first has no bad finish reason. */
 function hasValidCandidates(response: WireResponse): boolean {
   if (response.candidates && response.candidates.length > 0) {
-    if (hadBadFinishReason(response.candidates[0]!)) {
+    if (isBlockingFinishReason(response.candidates[0]!.finishReason)) {
       throw new AIError(
         AIErrorCode.RESPONSE_ERROR,
         `Response error: ${formatBlockErrorMessage(response)}. Response body stored in error.response`,

package/src/analytics/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `pyric/analytics` — a DEFERRED mirror of `firebase/analytics`.
+ *
+ * Google Analytics for Firebase is a fire-and-forget telemetry pipe to
+ * Google servers. There is no observable local behavior for the sandbox to
+ * mirror, so it is deferred.
+ *
+ * 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/analytics`
+ * (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 {
+  getAnalytics, getGoogleAnalyticsClientId, initializeAnalytics, logEvent,
+  setAnalyticsCollectionEnabled, setConsent, setCurrentScreen, setDefaultEventParameters,
+  setUserId, setUserProperties, settings,
+} = deferredEntry('analytics');
+
+/**
+ * The one deferred symbol that answers instead of throwing: the real SDK
+ * resolves a boolean, and a deferred entry IS unsupported, so the standard
+ * `isSupported().then(ok => ok && get…(app))` guard must run — not crash.
+ */
+export const isSupported = async (): Promise<boolean> => false;
+
+
+// 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 Analytics = DeferredApi;
+export type AnalyticsCallOptions = DeferredApi;
+export type AnalyticsSettings = DeferredApi;
+export type ConsentSettings = DeferredApi;
+export type ConsentStatusString = DeferredApi;
+export type ControlParams = DeferredApi;
+export type Currency = DeferredApi;
+export type CustomEventName = DeferredApi;
+export type CustomParams = DeferredApi;
+export type EventNameString = DeferredApi;
+export type EventParams = DeferredApi;
+export type GtagConfigParams = DeferredApi;
+export type Item = DeferredApi;
+export type Promotion = DeferredApi;
+export type SettingsOptions = DeferredApi;

package/src/app/dispatch.test.ts

@@ -26,7 +26,7 @@ import {
   signInWithEmailAndPassword,
   signOut,
 } from '../auth/index.js';
-import { get, getDatabase, ref, set } from '../database/index.js';
+import { get, getDatabase, ref, sandbox as databaseSandbox, set } from '../database/index.js';
 import { getStorage } from '../storage/index.js';
 import { getAI } from '../ai/index.js';
 import { getMessaging } from '../messaging/index.js';
@@ -121,6 +121,8 @@ describe('pyric/app — Firebase-shaped service containers', () => {
 
     const dbA = getDatabase(a);
     const dbB = getDatabase(b);
+    databaseSandbox.setDefaultPolicy(dbA, 'allow');
+    databaseSandbox.setDefaultPolicy(dbB, 'allow');
     await set(ref(dbA, 'shared/value'), { from: authA.currentUser!.uid });
     expect((await get(ref(dbB, 'shared/value'))).val()).toEqual({ from: authA.currentUser!.uid });
   });

package/src/app-check/index.ts

@@ -0,0 +1,41 @@
+/**
+ * `pyric/app-check` — a DEFERRED mirror of `firebase/app-check`.
+ *
+ * App Check attests that a request comes from your app, via reCAPTCHA or a
+ * custom attestation provider talking to Google infrastructure. The sandbox
+ * has no attestation authority to model against, so the whole surface is
+ * deferred.
+ *
+ * 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/app-check`
+ * (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 {
+  CustomProvider, ReCaptchaEnterpriseProvider, ReCaptchaV3Provider, getLimitedUseToken,
+  getToken, initializeAppCheck, onTokenChanged, setTokenAutoRefreshEnabled,
+} = deferredEntry('app-check');
+
+// 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 AppCheck = DeferredApi;
+export type AppCheckOptions = DeferredApi;
+export type AppCheckToken = DeferredApi;
+export type AppCheckTokenListener = DeferredApi;
+export type AppCheckTokenResult = DeferredApi;
+export type CustomProvider = DeferredApi;
+export type CustomProviderOptions = DeferredApi;
+export type PartialObserver = DeferredApi;
+export type ReCaptchaEnterpriseProvider = DeferredApi;
+export type ReCaptchaV3Provider = DeferredApi;
+export type Unsubscribe = DeferredApi;

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/sandbox/rules-eval.ts

@@ -99,7 +99,7 @@ export type RtdbDefaultPolicy = 'allow' | 'deny';
 
 export class RulesEvaluator {
   private compiled: CompiledRtdbRules | null = null;
-  private defaultPolicy: RtdbDefaultPolicy = 'allow';
+  private defaultPolicy: RtdbDefaultPolicy = 'deny';
 
   /** Set default access policy when no rules are loaded ('allow' or 'deny'). */
   setDefaultPolicy(policy: RtdbDefaultPolicy): void {
@@ -122,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

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

@@ -233,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();
     }
   }
@@ -252,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/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;
+    },
+  });
+}