@pyric/cli 0.1.0-alpha.30 → 0.1.0-alpha.30.2

package/dist/serve/site-ui/docs/ai-compat/index.html

@@ -374,12 +374,12 @@ html{scrollbar-gutter:stable}
 <div class="compat-list">
 <details class="compat-row" data-status="diverged">
 <summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a registered server process</code><span class="compat-sub"><span class="compat-behavior">Under a remote register activation, <code>getAI(app)</code> in a server process fails with <code>failed-precondition</code> and a message that names the client services that do reach the Node host: <code>firebase/ai</code> has no path to the host, and no in-process sandbox stands in for it. Production AI pass-through (<code>PYRIC_AI=production</code>) loads the real <code>firebase/ai</code> and is unaffected.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L141" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
+<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L80" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
 <div class="compat-note">refused in a server process; production runs it in Node</div></div>
 </details>
 <details class="compat-row" data-status="diverged">
 <summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a server-rendered module under vite dev</code><span class="compat-sub"><span class="compat-behavior">Under <code>vite dev</code>, <code>getAI(app)</code> in a server-rendered module fails with <code>failed-precondition</code> in the default sandbox AI mode, naming the client services that reach the host: <code>firebase/ai</code> has no path to the dev server's host from server code. In production AI mode the real <code>firebase/ai</code> loads and the network guard permits Firebase AI Logic. A SharedWorker dev server refuses it the same way.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L9" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
+<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L4" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
 <div class="compat-note">refused in server-rendered modules under vite dev; production runs it in the server's runtime</div></div>
 </details>
 </div>
@@ -387,23 +387,42 @@ html{scrollbar-gutter:stable}
 <div class="compat-list">
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">initializeAppCheck(app) then getAI(app) in production AI mode</code><span class="compat-sub"><span class="compat-behavior">In production AI mode the app's <code>firebase/app-check</code> is the Firebase SDK attached to the same app <code>firebase/ai</code> uses, so <code>generateContent</code> carries <code>X-Firebase-AppCheck</code> equal to the token <code>getToken</code> returns, and AI Logic answers 200.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>appCheckInitialized</code>), replayed by the AI pass-through suite through the served App Check bridge. On main before the bridge, <code>firebase/app-check</code> was swapped to the deferred <code>pyric/app-check</code> stub in production AI mode, and the real SDK on the Pyric app failed <code>appCheck/use-before-activation</code> because activation and lookup used different app objects. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L131" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L53" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>appCheckInitialized</code>), replayed by the AI pass-through suite through the served App Check bridge. On main before the bridge, <code>firebase/app-check</code> was swapped to the deferred <code>pyric/app-check</code> stub in production AI mode, and the real SDK on the Pyric app failed <code>appCheck/use-before-activation</code> because activation and lookup used different app objects. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L131" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L122" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L112" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getAI(app, { useLimitedUseAppCheckTokens: true }) in production AI mode</code><span class="compat-sub"><span class="compat-behavior">With <code>useLimitedUseAppCheckTokens</code>, each request carries a fresh limited-use token rather than the cached one, and AI Logic answers 200.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>limitedUseModel</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L132" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L53" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>limitedUseModel</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L132" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L122" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L112" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContent without App Check in production AI mode</code><span class="compat-sub"><span class="compat-behavior">On an app that never initialized App Check, <code>firebase/ai</code> sends no <code>X-Firebase-AppCheck</code> header, and AI Logic rejects the request: HTTP 403, <code>PERMISSION_DENIED</code>, message <code>Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check.</code> with a docs link. A malformed header, the SDK placeholder token, and a tampered token get the same envelope; a valid token answers 200. Seen with App Check enforcement for AI Logic reading UNENFORCED.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">captures <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-ai-gate-wire.json" target="_blank" rel="noopener noreferrer"><code>app-check-ai-gate-wire</code></a> (all five cases on the wire) and <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>noAppCheck</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L109" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L4" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">captures <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-ai-gate-wire.json" target="_blank" rel="noopener noreferrer"><code>app-check-ai-gate-wire</code></a> (all five cases on the wire) and <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>noAppCheck</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L109" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L4" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L9" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">initializeAppCheck(app) after getAI(app)</code><span class="compat-sub"><span class="compat-behavior">Calling <code>initializeAppCheck</code> after <code>getAI(app)</code> built a model does not throw and <code>getToken</code> works, but that model sends no <code>X-Firebase-AppCheck</code> header and AI Logic answers 403. App Check must be initialized before <code>getAI</code>.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-get-token-before-initialize.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-get-token-before-initialize</code></a> (<code>initializeAfterAi</code>, <code>getTokenAfterLateInitialize</code>, <code>aiRequestAfterLateInitialize</code>, <code>aiGenerationAfterLateInitialize</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L170" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L53" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-get-token-before-initialize.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-get-token-before-initialize</code></a> (<code>initializeAfterAi</code>, <code>getTokenAfterLateInitialize</code>, <code>aiRequestAfterLateInitialize</code>, <code>aiGenerationAfterLateInitialize</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L170" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L122" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L112" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContent when App Check attestation fails</code><span class="compat-sub"><span class="compat-behavior">When the token exchange is refused, <code>firebase/ai</code> sends the SDK placeholder token (base64 of <code>{"error":"UNKNOWN_ERROR"}</code>) and AI Logic answers 403; with <code>useLimitedUseAppCheckTokens</code> it throws <code>AI/error</code> naming <code>appCheck/fetch-status-error</code> before sending any request.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-invalid-debug-token.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-invalid-debug-token</code></a> (<code>aiRequest</code>, <code>aiGeneration</code>, <code>aiLimitedUseRequest</code>, <code>aiLimitedUseGeneration</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L189" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L3" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-invalid-debug-token.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-invalid-debug-token</code></a> (<code>aiRequest</code>, <code>aiGeneration</code>, <code>aiLimitedUseRequest</code>, <code>aiLimitedUseGeneration</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L189" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L3" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L4" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+</div>
+<h2 id="app-check-in-sandbox-ai-mode">App Check in sandbox AI mode</h2>
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContent from getAI(app) in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior">An app that never initialized App Check gets the <code>AIError</code> the SDK throws for AI Logic's 403: code <code>fetch-error</code>, <code>customErrorData.status</code> 403, message <code>[403 Forbidden] Firebase AI Logic has been deactivated in this project. ...</code> with the docs link. The broker refuses a missing, malformed, placeholder, tampered or expired token with production's envelope before any engine runs, and answers a sandbox token, including one minted under the debug provider. Pyric's guidance goes to the console once per app and to the dev server terminal, beside the error.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">captures <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-ai-gate-wire.json" target="_blank" rel="noopener noreferrer"><code>app-check-ai-gate-wire</code></a> (<code>noHeader</code>, <code>malformedHeader</code>, <code>sdkPlaceholderToken</code>, <code>tamperedSignature</code>, <code>validAdminMintedToken</code>) and <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>noAppCheck</code>), replayed by the gate suite in process and over the worker port; the app scenario drives the in-page, SharedWorker, Node host and registered Node process planes. On main before #1291 the sandbox answered tokenless requests. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L8" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L10" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L2" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">initializeAppCheck(app) after getAI(app) in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior"><code>getAI(app)</code> reads App Check when it builds the handle. <code>initializeAppCheck</code> after it does not throw and <code>getToken</code> works, but that handle's requests carry no token and are refused with the 403.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-get-token-before-initialize.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-get-token-before-initialize</code></a> (<code>initializeAfterAi</code>, <code>getTokenAfterLateInitialize</code>, <code>aiRequestAfterLateInitialize</code>, <code>aiGenerationAfterLateInitialize</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L11" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L5" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L2" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getAI(app, { useLimitedUseAppCheckTokens: true }) in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior">Each request carries a fresh limited-use token rather than the cached one, and the sandbox answers.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>limitedUseModel</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L9" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L5" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L11" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContentStream and countTokens without App Check in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior">Streaming and <code>countTokens</code> are refused with the same 403 <code>AIError</code> as <code>generateContent</code>. In process <code>generateContentStream</code> rejects before any chunk; on the SharedWorker and Node host planes the error reaches the caller through the stream and <code>response</code>, as other request errors do there.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">AI Logic applies App Check to every request (https://firebase.google.com/docs/ai-logic/app-check); the captures cover only <code>generateContent</code>. Unit-backed by the gate suite and the worker protocol suite. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L193" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L12" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L40" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 </div>
 <h2 id="current-gaps">Current gaps</h2>
@@ -423,9 +442,9 @@ html{scrollbar-gutter:stable}
 <details class="compat-row" data-status="diverged"><summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">Schema.enumString()</code><span class="compat-sub"><span class="compat-behavior"><code>Schema.enumString</code> serializes the enum values with type <code>string</code> and format <code>enum</code></span></span></span></summary>
 <div class="compat-evidence"><div class="compat-note"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/helpers-schema.test.ts#L153" target="_blank" rel="noopener noreferrer"><code>unit:helpers-schema.test.ts</code></a> test <code>ai#schema-string-enum</code> (upstream toJSON request shape; GoogleAI accepts only enum and date-time formats)</div></div></details>
 <details class="compat-row" data-status="diverged"><summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a registered server process</code><span class="compat-sub"><span class="compat-behavior">Under a remote register activation, <code>getAI(app)</code> in a server process fails with <code>failed-precondition</code> and a message that names the client services that do reach the Node host: <code>firebase/ai</code> has no path to the host, and no in-process sandbox stands in for it. Production AI pass-through (<code>PYRIC_AI=production</code>) loads the real <code>firebase/ai</code> and is unaffected.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L141" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
+<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L80" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
 <details class="compat-row" data-status="diverged"><summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a server-rendered module under vite dev</code><span class="compat-sub"><span class="compat-behavior">Under <code>vite dev</code>, <code>getAI(app)</code> in a server-rendered module fails with <code>failed-precondition</code> in the default sandbox AI mode, naming the client services that reach the host: <code>firebase/ai</code> has no path to the dev server's host from server code. In production AI mode the real <code>firebase/ai</code> loads and the network guard permits Firebase AI Logic. A SharedWorker dev server refuses it the same way.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L9" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
+<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L4" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
 </div>
 <h2 id="reviewed-public-runtime-gaps">Reviewed public-runtime gaps</h2>
 <div class="compat-list">
@@ -454,4 +473,4 @@ html{scrollbar-gutter:stable}
 <div class="compat-evidence"><div class="compat-note"><code>startAudioConversation</code></div>
 <div class="compat-note">disposition:ai.live-api</div></div>
 </details>
-</div> </article> </main> <aside class="doc-toc" aria-label="On this page" data-astro-cid-mw7aashj> <h2 class="doc-toc-heading" data-astro-cid-mw7aashj>On this page</h2> <ul data-astro-cid-mw7aashj> <li data-depth="2" data-astro-cid-mw7aashj> <a href="#status-legend" data-astro-cid-mw7aashj>Status legend</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#getaitarget-and-dispatch" data-astro-cid-mw7aashj>getAI(target) and dispatch</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#generativemodelgeneratecontent-envelope" data-astro-cid-mw7aashj>GenerativeModel.generateContent envelope</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#generatecontentstream-framing-and-aggregation" data-astro-cid-mw7aashj>generateContentStream framing and aggregation</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#chatsession-history-and-streaming-turns" data-astro-cid-mw7aashj>ChatSession history and streaming turns</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#function-calling" data-astro-cid-mw7aashj>Function calling</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#counttokens" data-astro-cid-mw7aashj>countTokens</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#error-envelopes" data-astro-cid-mw7aashj>Error envelopes</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#response-helpers-enhancedgeneratecontentresponse" data-astro-cid-mw7aashj>Response helpers (EnhancedGenerateContentResponse)</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#schema-builders" data-astro-cid-mw7aashj>Schema builders</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#sandbox-answer-engine-scripted" data-astro-cid-mw7aashj>Sandbox answer engine: scripted</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#sandbox-answer-engine-openai-translation" data-astro-cid-mw7aashj>Sandbox answer engine: openai translation</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#client-sdks-in-a-registered-server-process" data-astro-cid-mw7aashj>Client SDKs in a registered server process</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#app-check-on-the-ai-path" data-astro-cid-mw7aashj>App Check on the AI path</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#current-gaps" data-astro-cid-mw7aashj>Current gaps</a> </li><li data-depth="3" data-astro-cid-mw7aashj> <a href="#documented-divergences" data-astro-cid-mw7aashj>Documented divergences</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#reviewed-public-runtime-gaps" data-astro-cid-mw7aashj>Reviewed public-runtime gaps</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script>  </body></html> 
+</div> </article> </main> <aside class="doc-toc" aria-label="On this page" data-astro-cid-mw7aashj> <h2 class="doc-toc-heading" data-astro-cid-mw7aashj>On this page</h2> <ul data-astro-cid-mw7aashj> <li data-depth="2" data-astro-cid-mw7aashj> <a href="#status-legend" data-astro-cid-mw7aashj>Status legend</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#getaitarget-and-dispatch" data-astro-cid-mw7aashj>getAI(target) and dispatch</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#generativemodelgeneratecontent-envelope" data-astro-cid-mw7aashj>GenerativeModel.generateContent envelope</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#generatecontentstream-framing-and-aggregation" data-astro-cid-mw7aashj>generateContentStream framing and aggregation</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#chatsession-history-and-streaming-turns" data-astro-cid-mw7aashj>ChatSession history and streaming turns</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#function-calling" data-astro-cid-mw7aashj>Function calling</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#counttokens" data-astro-cid-mw7aashj>countTokens</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#error-envelopes" data-astro-cid-mw7aashj>Error envelopes</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#response-helpers-enhancedgeneratecontentresponse" data-astro-cid-mw7aashj>Response helpers (EnhancedGenerateContentResponse)</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#schema-builders" data-astro-cid-mw7aashj>Schema builders</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#sandbox-answer-engine-scripted" data-astro-cid-mw7aashj>Sandbox answer engine: scripted</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#sandbox-answer-engine-openai-translation" data-astro-cid-mw7aashj>Sandbox answer engine: openai translation</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#client-sdks-in-a-registered-server-process" data-astro-cid-mw7aashj>Client SDKs in a registered server process</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#app-check-on-the-ai-path" data-astro-cid-mw7aashj>App Check on the AI path</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#app-check-in-sandbox-ai-mode" data-astro-cid-mw7aashj>App Check in sandbox AI mode</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#current-gaps" data-astro-cid-mw7aashj>Current gaps</a> </li><li data-depth="3" data-astro-cid-mw7aashj> <a href="#documented-divergences" data-astro-cid-mw7aashj>Documented divergences</a> </li><li data-depth="2" data-astro-cid-mw7aashj> <a href="#reviewed-public-runtime-gaps" data-astro-cid-mw7aashj>Reviewed public-runtime gaps</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script>  </body></html> 

package/dist/serve/site-ui/docs/ai-compat.md

@@ -399,12 +399,12 @@
 <div class="compat-list">
 <details class="compat-row" data-status="diverged">
 <summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a registered server process</code><span class="compat-sub"><span class="compat-behavior">Under a remote register activation, <code>getAI(app)</code> in a server process fails with <code>failed-precondition</code> and a message that names the client services that do reach the Node host: <code>firebase/ai</code> has no path to the host, and no in-process sandbox stands in for it. Production AI pass-through (<code>PYRIC_AI=production</code>) loads the real <code>firebase/ai</code> and is unaffected.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L141" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
+<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L80" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
 <div class="compat-note">refused in a server process; production runs it in Node</div></div>
 </details>
 <details class="compat-row" data-status="diverged">
 <summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a server-rendered module under vite dev</code><span class="compat-sub"><span class="compat-behavior">Under <code>vite dev</code>, <code>getAI(app)</code> in a server-rendered module fails with <code>failed-precondition</code> in the default sandbox AI mode, naming the client services that reach the host: <code>firebase/ai</code> has no path to the dev server's host from server code. In production AI mode the real <code>firebase/ai</code> loads and the network guard permits Firebase AI Logic. A SharedWorker dev server refuses it the same way.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L9" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
+<div class="compat-evidence"><div class="compat-probe">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L4" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div>
 <div class="compat-note">refused in server-rendered modules under vite dev; production runs it in the server's runtime</div></div>
 </details>
 </div>
@@ -414,23 +414,44 @@
 <div class="compat-list">
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">initializeAppCheck(app) then getAI(app) in production AI mode</code><span class="compat-sub"><span class="compat-behavior">In production AI mode the app's <code>firebase/app-check</code> is the Firebase SDK attached to the same app <code>firebase/ai</code> uses, so <code>generateContent</code> carries <code>X-Firebase-AppCheck</code> equal to the token <code>getToken</code> returns, and AI Logic answers 200.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>appCheckInitialized</code>), replayed by the AI pass-through suite through the served App Check bridge. On main before the bridge, <code>firebase/app-check</code> was swapped to the deferred <code>pyric/app-check</code> stub in production AI mode, and the real SDK on the Pyric app failed <code>appCheck/use-before-activation</code> because activation and lookup used different app objects. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L131" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L53" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>appCheckInitialized</code>), replayed by the AI pass-through suite through the served App Check bridge. On main before the bridge, <code>firebase/app-check</code> was swapped to the deferred <code>pyric/app-check</code> stub in production AI mode, and the real SDK on the Pyric app failed <code>appCheck/use-before-activation</code> because activation and lookup used different app objects. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L131" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L122" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L112" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getAI(app, { useLimitedUseAppCheckTokens: true }) in production AI mode</code><span class="compat-sub"><span class="compat-behavior">With <code>useLimitedUseAppCheckTokens</code>, each request carries a fresh limited-use token rather than the cached one, and AI Logic answers 200.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>limitedUseModel</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L132" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L53" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>limitedUseModel</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L132" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L122" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L112" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContent without App Check in production AI mode</code><span class="compat-sub"><span class="compat-behavior">On an app that never initialized App Check, <code>firebase/ai</code> sends no <code>X-Firebase-AppCheck</code> header, and AI Logic rejects the request: HTTP 403, <code>PERMISSION_DENIED</code>, message <code>Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check.</code> with a docs link. A malformed header, the SDK placeholder token, and a tampered token get the same envelope; a valid token answers 200. Seen with App Check enforcement for AI Logic reading UNENFORCED.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">captures <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-ai-gate-wire.json" target="_blank" rel="noopener noreferrer"><code>app-check-ai-gate-wire</code></a> (all five cases on the wire) and <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>noAppCheck</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L109" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L4" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">captures <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-ai-gate-wire.json" target="_blank" rel="noopener noreferrer"><code>app-check-ai-gate-wire</code></a> (all five cases on the wire) and <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>noAppCheck</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L109" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L4" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L9" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">initializeAppCheck(app) after getAI(app)</code><span class="compat-sub"><span class="compat-behavior">Calling <code>initializeAppCheck</code> after <code>getAI(app)</code> built a model does not throw and <code>getToken</code> works, but that model sends no <code>X-Firebase-AppCheck</code> header and AI Logic answers 403. App Check must be initialized before <code>getAI</code>.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-get-token-before-initialize.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-get-token-before-initialize</code></a> (<code>initializeAfterAi</code>, <code>getTokenAfterLateInitialize</code>, <code>aiRequestAfterLateInitialize</code>, <code>aiGenerationAfterLateInitialize</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L170" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L53" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-get-token-before-initialize.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-get-token-before-initialize</code></a> (<code>initializeAfterAi</code>, <code>getTokenAfterLateInitialize</code>, <code>aiRequestAfterLateInitialize</code>, <code>aiGenerationAfterLateInitialize</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L170" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L122" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L112" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 <details class="compat-row" data-status="ok">
 <summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContent when App Check attestation fails</code><span class="compat-sub"><span class="compat-behavior">When the token exchange is refused, <code>firebase/ai</code> sends the SDK placeholder token (base64 of <code>{"error":"UNKNOWN_ERROR"}</code>) and AI Logic answers 403; with <code>useLimitedUseAppCheckTokens</code> it throws <code>AI/error</code> naming <code>appCheck/fetch-status-error</code> before sending any request.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-invalid-debug-token.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-invalid-debug-token</code></a> (<code>aiRequest</code>, <code>aiGeneration</code>, <code>aiLimitedUseRequest</code>, <code>aiLimitedUseGeneration</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L189" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L3" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-invalid-debug-token.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-invalid-debug-token</code></a> (<code>aiRequest</code>, <code>aiGeneration</code>, <code>aiLimitedUseRequest</code>, <code>aiLimitedUseGeneration</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/ai-app-check-passthrough.test.ts#L189" target="_blank" rel="noopener noreferrer"><code>ai-app-check-passthrough.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-app-check/scenario.ts#L3" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/ai-production-import-map/scenario.ts#L4" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+</div>
+
+## App Check in sandbox AI mode
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContent from getAI(app) in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior">An app that never initialized App Check gets the <code>AIError</code> the SDK throws for AI Logic's 403: code <code>fetch-error</code>, <code>customErrorData.status</code> 403, message <code>[403 Forbidden] Firebase AI Logic has been deactivated in this project. ...</code> with the docs link. The broker refuses a missing, malformed, placeholder, tampered or expired token with production's envelope before any engine runs, and answers a sandbox token, including one minted under the debug provider. Pyric's guidance goes to the console once per app and to the dev server terminal, beside the error.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">captures <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-ai-gate-wire.json" target="_blank" rel="noopener noreferrer"><code>app-check-ai-gate-wire</code></a> (<code>noHeader</code>, <code>malformedHeader</code>, <code>sdkPlaceholderToken</code>, <code>tamperedSignature</code>, <code>validAdminMintedToken</code>) and <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>noAppCheck</code>), replayed by the gate suite in process and over the worker port; the app scenario drives the in-page, SharedWorker, Node host and registered Node process planes. On main before #1291 the sandbox answered tokenless requests. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L8" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L10" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L2" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">initializeAppCheck(app) after getAI(app) in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior"><code>getAI(app)</code> reads App Check when it builds the handle. <code>initializeAppCheck</code> after it does not throw and <code>getToken</code> works, but that handle's requests carry no token and are refused with the 403.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-get-token-before-initialize.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-get-token-before-initialize</code></a> (<code>initializeAfterAi</code>, <code>getTokenAfterLateInitialize</code>, <code>aiRequestAfterLateInitialize</code>, <code>aiGenerationAfterLateInitialize</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L11" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L5" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L2" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getAI(app, { useLimitedUseAppCheckTokens: true }) in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior">Each request carries a fresh limited-use token rather than the cached one, and the sandbox answers.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">capture <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/app-check/app-check-client-ai-header.json" target="_blank" rel="noopener noreferrer"><code>app-check-client-ai-header</code></a> (<code>limitedUseModel</code>). (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L9" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L5" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L11" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">generateContentStream and countTokens without App Check in sandbox AI mode</code><span class="compat-sub"><span class="compat-behavior">Streaming and <code>countTokens</code> are refused with the same 403 <code>AIError</code> as <code>generateContent</code>. In process <code>generateContentStream</code> rejects before any chunk; on the SharedWorker and Node host planes the error reaches the caller through the stream and <code>response</code>, as other request errors do there.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">AI Logic applies App Check to every request (https://firebase.google.com/docs/ai-logic/app-check); the captures cover only <code>generateContent</code>. Unit-backed by the gate suite and the worker protocol suite. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/app-check-gate.test.ts#L193" target="_blank" rel="noopener noreferrer"><code>app-check-gate.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/worker/ai-ops.test.ts#L12" target="_blank" rel="noopener noreferrer"><code>ai-ops.test.ts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/test/apps/sandbox-app-check/scenario.ts#L40" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
 </details>
 </div>
 
@@ -454,9 +475,9 @@ Known differences between Pyric and production Firebase. Each remains tracked as
 <details class="compat-row" data-status="diverged"><summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">Schema.enumString()</code><span class="compat-sub"><span class="compat-behavior"><code>Schema.enumString</code> serializes the enum values with type <code>string</code> and format <code>enum</code></span></span></span></summary>
 <div class="compat-evidence"><div class="compat-note"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/helpers-schema.test.ts#L153" target="_blank" rel="noopener noreferrer"><code>unit:helpers-schema.test.ts</code></a> test <code>ai#schema-string-enum</code> (upstream toJSON request shape; GoogleAI accepts only enum and date-time formats)</div></div></details>
 <details class="compat-row" data-status="diverged"><summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a registered server process</code><span class="compat-sub"><span class="compat-behavior">Under a remote register activation, <code>getAI(app)</code> in a server process fails with <code>failed-precondition</code> and a message that names the client services that do reach the Node host: <code>firebase/ai</code> has no path to the host, and no in-process sandbox stands in for it. Production AI pass-through (<code>PYRIC_AI=production</code>) loads the real <code>firebase/ai</code> and is unaffected.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L141" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
+<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/client-sdk-under-register</code> calls it under <code>node --import @pyric/cli/register</code> against a hosted Vite dev server and asserts the refusal; on main (942cb175) it returned a handle on a private in-process sandbox. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/mapping.test.ts#L80" target="_blank" rel="noopener noreferrer"><code>mapping.test.ts</code></a> pins that the subpath keeps its mirror under a remote activation, and <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/register/node-origin.test.ts#L2" target="_blank" rel="noopener noreferrer"><code>node-origin.test.ts</code></a> that a mirror resolved from such an app refuses. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/client-sdk-under-register/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
 <details class="compat-row" data-status="diverged"><summary class="compat-line"><span class="compat-dot" data-status="diverged" role="img" aria-label="Diverged (documented)" title="Diverged (documented)"></span><span class="compat-main"><code class="compat-api">getAI(app) in a server-rendered module under vite dev</code><span class="compat-sub"><span class="compat-behavior">Under <code>vite dev</code>, <code>getAI(app)</code> in a server-rendered module fails with <code>failed-precondition</code> in the default sandbox AI mode, naming the client services that reach the host: <code>firebase/ai</code> has no path to the dev server's host from server code. In production AI mode the real <code>firebase/ai</code> loads and the network guard permits Firebase AI Logic. A SharedWorker dev server refuses it the same way.</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L9" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
+<div class="compat-evidence"><div class="compat-note">App scenario <code>test/apps/vite-ssr-client-sdk</code> calls it in SSR on a hosted dev server and asserts the refusal; a second dev server in production AI mode lets the real SDK reach only <code>firebasevertexai.googleapis.com</code>, which a stand-in beneath the guard refuses. On main (ba2c0bf0a) it was the real SDK. <a href="https://github.com/davideast/pyric/blob/main/packages/cli/test/serve/vite-module-swap.test.ts#L4" target="_blank" rel="noopener noreferrer"><code>vite-module-swap.test.ts</code></a> pins the routing. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/test/apps/vite-ssr-client-sdk/scenario.ts#L1" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div></details>
 </div>
 
 ## Reviewed public-runtime gaps