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

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

@@ -0,0 +1,311 @@
+/**
+ * The Gemini AnswerEngine: Gemini wire in, Google AI Studio / Vertex AI REST API
+ * out, Gemini wire back.
+ *
+ * Unlike the browser-side `@firebase/ai` SDK (which calls Vertex AI directly
+ * from the browser and fails with HTTP 401 for sandboxed mock auth users),
+ * `GeminiEngine` runs on Pyric's backend server, authenticating via a local
+ * API key (`GEMINI_API_KEY` / `GOOGLE_GENAI_API_KEY` / `VITE_GEMINI_API_KEY`)
+ * or Google Cloud Application Default Credentials (`gcloud auth application-default login`)
+ * without exposing secrets to the browser.
+ */
+
+import { AiBrokerError, errorEnvelope, redactUrl } from './synthesizer.js';
+import type {
+  AnswerEngine,
+  CountTokensRequest,
+  CountTokensResponse,
+  GenerateContentRequest,
+  ModelResolution,
+  WireChunk,
+  WireResponse,
+} from './types.js';
+
+/** Where the gemini engine talks when no `baseUrl` overrides it. Published
+ *  through `pyric/ai/internal` so the CLI's startup banner can name the same
+ *  endpoint instead of keeping its own copy. */
+export const GEMINI_DEFAULT_BASE_URL = 'https://generativelanguage.googleapis.com';
+
+/**
+ * BROWSER-CLEAN: acquires `node:child_process` lazily via `process.getBuiltinModule`
+ * so no static node import exists for browser bundlers to resolve.
+ */
+function getExecSync(): ((command: string, options: Record<string, unknown>) => string) | null {
+  const get = (globalThis as { process?: { getBuiltinModule?: (id: string) => unknown } }).process
+    ?.getBuiltinModule;
+  const hasGetBuiltinModule = typeof get === 'function';
+  if (!hasGetBuiltinModule) {
+    return null;
+  }
+  const cp = get.call(process, 'node:child_process') as
+    | { execSync?: (cmd: string, opts: unknown) => string }
+    | undefined;
+  const hasExecSync = cp !== undefined && typeof cp.execSync === 'function';
+  if (!hasExecSync) {
+    return null;
+  }
+  return cp.execSync as (command: string, options: Record<string, unknown>) => string;
+}
+
+export interface GeminiEngineOptions {
+  /** Explicit API key. Absent ⇒ resolved from environment variables or ADC. */
+  apiKey?: string;
+  /** Explicit base URL override (default: https://generativelanguage.googleapis.com). */
+  baseUrl?: string;
+  /** Explicit fetch seam for testing or custom transport. */
+  fetch?: typeof fetch;
+}
+
+export class GeminiEngine implements AnswerEngine {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  private readonly explicitKey?: string;
+
+  constructor(options?: GeminiEngineOptions) {
+    this.baseUrl = (options?.baseUrl ?? GEMINI_DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.fetchImpl = options?.fetch ?? ((input, init) => fetch(input, init));
+    this.explicitKey = options?.apiKey;
+  }
+
+  /**
+   * Resolves authentication credentials sequentially, checking static options,
+   * environment variables, and finally Google Cloud Application Default
+   * Credentials (`gcloud auth application-default print-access-token`).
+   */
+  private async resolveAuthToken(): Promise<{ token: string; isBearer: boolean }> {
+    let key = this.explicitKey;
+    if (key === undefined) {
+      key = process.env.GEMINI_API_KEY;
+    }
+    if (key === undefined) {
+      key = process.env.GOOGLE_GENAI_API_KEY;
+    }
+    if (key === undefined) {
+      key = process.env.VITE_GEMINI_API_KEY;
+    }
+
+    if (key !== undefined) {
+      const trimmedKey = key.trim();
+      const hasStaticKey = trimmedKey !== '';
+      if (hasStaticKey) {
+        return { token: trimmedKey, isBearer: false };
+      }
+    }
+
+    try {
+      const execSyncFn = getExecSync();
+      const hasExecSyncFn = execSyncFn !== null;
+      if (hasExecSyncFn) {
+        const adcToken = execSyncFn('gcloud auth application-default print-access-token', {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const hasAdcToken = adcToken !== '';
+        if (hasAdcToken) {
+          return { token: adcToken, isBearer: true };
+        }
+      }
+    } catch {
+      // Best-effort attempt to recover ADC credentials when env keys are absent
+    }
+
+    throw new AiBrokerError(
+      errorEnvelope(
+        401,
+        'Pyric AI production passthrough mode requires GEMINI_API_KEY, GOOGLE_GENAI_API_KEY, or VITE_GEMINI_API_KEY in your server environment (or Application Default Credentials via `gcloud auth application-default login`).',
+        'UNAUTHENTICATED',
+      ),
+    );
+  }
+
+  /**
+   * Which model this engine ACTUALLY calls upstream, and why it differs.
+   * Experimental and superseded flash aliases are redirected onto the served
+   * `gemini-flash-lite-latest`; everything else passes through. Reported so
+   * the broker can announce the redirect rather than let a developer believe
+   * `gemini-2.5-flash` answered when `gemini-flash-lite-latest` did
+   * ({@link AnswerEngine.resolveEffectiveModel}).
+   */
+  resolveEffectiveModel(model: string): ModelResolution {
+    const stripped = model.replace(/^models\//, '');
+    const isExperimentalFlashLite =
+      stripped === 'gemini-3.5-flash-lite' ||
+      stripped === 'gemini-2.5-flash' ||
+      stripped === 'gemini-2.5-flash-lite' ||
+      stripped === 'gemini-1.5-flash';
+    if (isExperimentalFlashLite) {
+      return { model: 'gemini-flash-lite-latest', reason: 'experimental alias' };
+    }
+    return { model: stripped, reason: 'passthrough' };
+  }
+
+  private normalizeModel(model: string): string {
+    return `models/${this.resolveEffectiveModel(model).model}`;
+  }
+
+  /**
+   * Formats upstream REST endpoint URLs and request headers for either Google
+   * AI Studio (`generativelanguage.googleapis.com`) or Vertex AI regional APIs.
+   */
+  private formatUpstreamRequest(
+    resource: string,
+    action: string,
+    auth: { token: string; isBearer: boolean },
+  ): { url: string; headers: Record<string, string> } {
+    const isVertexUrl =
+      this.baseUrl.includes('firebasevertexai.googleapis.com') ||
+      this.baseUrl.includes('aiplatform.googleapis.com');
+    const shouldUseBearerAuth = auth.isBearer || isVertexUrl;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (shouldUseBearerAuth) {
+      headers['Authorization'] = `Bearer ${auth.token}`;
+      return {
+        url: `${this.baseUrl}/v1beta/${resource}:${action}`,
+        headers,
+      };
+    }
+
+    return {
+      url: `${this.baseUrl}/v1beta/${resource}:${action}?key=${encodeURIComponent(auth.token)}`,
+      headers,
+    };
+  }
+
+  private async fetchUpstream(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<Response> {
+    let response: Response;
+    try {
+      response = await this.fetchImpl(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      // Redact both: `url` always carries the key when auth is a static key
+      // (not bearer/ADC); `message` is defensively redacted too in case the
+      // fetch implementation's own error text echoes the request URL.
+      const rawMessage = err instanceof Error ? err.message : String(err);
+      const safeUrl = redactUrl(url);
+      const safeMessage = redactUrl(rawMessage);
+      throw new AiBrokerError(
+        errorEnvelope(
+          502,
+          `Failed to connect to Gemini API at ${safeUrl}: ${safeMessage}`,
+          'UNAVAILABLE',
+        ),
+      );
+    }
+
+    const isSuccess = response.ok;
+    if (!isSuccess) {
+      const errorText = await response.text().catch(() => '');
+      throw new AiBrokerError(
+        errorEnvelope(
+          response.status,
+          `Gemini API returned status ${response.status}: ${redactUrl(errorText)}`,
+          'INTERNAL',
+        ),
+      );
+    }
+
+    return response;
+  }
+
+  async generateContent(req: GenerateContentRequest, model: string): Promise<WireResponse> {
+    const auth = await this.resolveAuthToken();
+    const resource = this.normalizeModel(model);
+    const { url, headers } = this.formatUpstreamRequest(resource, 'generateContent', auth);
+    const response = await this.fetchUpstream(url, headers, req);
+    return (await response.json()) as WireResponse;
+  }
+
+  async *streamGenerateContent(
+    req: GenerateContentRequest,
+    model: string,
+  ): AsyncIterable<WireChunk> {
+    const auth = await this.resolveAuthToken();
+    const resource = this.normalizeModel(model);
+    const { url, headers } = this.formatUpstreamRequest(
+      resource,
+      'streamGenerateContent?alt=sse',
+      auth,
+    );
+    const response = await this.fetchUpstream(url, headers, req);
+
+    const hasBody = response.body !== null && response.body !== undefined;
+    if (!hasBody) {
+      throw new AiBrokerError(
+        errorEnvelope(500, 'Gemini API returned an empty stream response.', 'INTERNAL'),
+      );
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        const isDone = done === true;
+        if (isDone) {
+          break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const isDataLine = line.startsWith('data: ');
+          if (!isDataLine) {
+            continue;
+          }
+          const dataStr = line.slice(6).trim();
+          const isEmptyOrDone = dataStr === '' || dataStr === '[DONE]';
+          if (isEmptyOrDone) {
+            continue;
+          }
+          try {
+            const chunk = JSON.parse(dataStr) as WireChunk;
+            yield chunk;
+          } catch {
+            // Ignore malformed SSE chunk in stream
+          }
+        }
+      }
+
+      const hasTrailingBuffer = buffer.trim().length > 0;
+      if (hasTrailingBuffer) {
+        const line = buffer.trim();
+        const isDataLine = line.startsWith('data: ');
+        if (isDataLine) {
+          const dataStr = line.slice(6).trim();
+          const isNotEmptyOrDone = dataStr !== '' && dataStr !== '[DONE]';
+          if (isNotEmptyOrDone) {
+            try {
+              const chunk = JSON.parse(dataStr) as WireChunk;
+              yield chunk;
+            } catch {
+              // Ignore malformed SSE chunk in stream
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  async countTokens(req: CountTokensRequest, model: string): Promise<CountTokensResponse> {
+    const auth = await this.resolveAuthToken();
+    const resource = this.normalizeModel(model);
+    const { url, headers } = this.formatUpstreamRequest(resource, 'countTokens', auth);
+    const response = await this.fetchUpstream(url, headers, req);
+    return (await response.json()) as CountTokensResponse;
+  }
+}

package/src/ai/broker/index.ts

@@ -7,6 +7,7 @@
 
 export { AiBroker, loadObservationEnvelope, type AiBrokerOptions } from './broker.js';
 export { ScriptedEngine, lastUserText, promptTextOf } from './scripted-engine.js';
+export { GeminiEngine, GEMINI_DEFAULT_BASE_URL, type GeminiEngineOptions } from './gemini-engine.js';
 export {
   OpenAiEngine,
   ToolCallBuffer,
@@ -36,6 +37,7 @@ export {
   estimateTokens,
   mintThoughtSignature,
   mintFunctionCallId,
+  redactUrl,
   type SynthesizeOptions,
 } from './synthesizer.js';
 export type {

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 ──────────────────────────────────────────────────────
@@ -191,4 +216,5 @@ export type EngineConfig =
       modelMap?: Record<string, string>;
       /** Injectable fetch for tests; defaults to globalThis.fetch. */
       fetch?: typeof fetch;
-    };
+    }
+  | { kind: 'gemini'; baseUrl?: string; apiKey?: string; fetch?: typeof fetch };

package/src/ai/instances.ts

@@ -91,7 +91,7 @@ export function getAI(target?: Sandbox | FirebaseApp, options?: AIOptions): AI {
     return sandboxAI(target, options);
   }
   throw new TypeError(
-    'pyric/ai is a sandbox-only mirror. Package resolution must leave firebase/ai unchanged for production; activate pyric dev or @pyric/cli/register before importing to select the sandbox.',
+    'pyric/ai is a sandbox-only mirror. Package resolution must leave firebase/ai unchanged for production; activate pyric sandbox or @pyric/cli/register before importing to select the sandbox.',
   );
 }
 

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/auth/instances.ts

@@ -80,7 +80,7 @@ export function getAuth(target?: Sandbox | FirebaseApp): Auth {
     return handle;
   }
   throw new TypeError(
-    'pyric/auth is a sandbox-only mirror. Package resolution must leave firebase/auth unchanged for production; activate pyric dev or @pyric/cli/register before importing to select the sandbox.',
+    'pyric/auth is a sandbox-only mirror. Package resolution must leave firebase/auth unchanged for production; activate pyric sandbox or @pyric/cli/register before importing to select the sandbox.',
   );
 }