@pyric/cli 0.1.0-alpha.30.1 → 0.1.0-alpha.31

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

@@ -19,6 +19,7 @@
 <div class="compat-key">
 <span class="compat-key-item"><span class="compat-dot" data-status="ok"></span><strong>Conforming</strong>: sandbox matches prod, locked by a passing probe</span>
 <span class="compat-key-item"><span class="compat-dot" data-status="diverged"></span><strong>Diverged (documented)</strong>: intentional difference with a written reason</span>
+<span class="compat-key-item"><span class="compat-dot" data-status="bug"></span><strong>Bug</strong>: should match prod but doesn't; failing probe pins it</span>
 </div>
 
 ## `getAI(target)` and dispatch
@@ -107,16 +108,20 @@
 <div class="compat-evidence"><div class="compat-probe">Capture ai-system-instruction-accepted replayed by packages/pyric/test/ai/generate-content.test.ts test <code>ai#generate-system-instruction</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-system-instruction-accepted.json" target="_blank" rel="noopener noreferrer"><code>ai-system-instruction-accepted</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L100" target="_blank" rel="noopener noreferrer"><code>generate-content.test.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(request)</code><span class="compat-sub"><span class="compat-behavior">A <code>contents</code> turn under role <code>assistant</code> is accepted (200, finishReason STOP), although the unknown-role text lists only MODEL, USER</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Capture ai-contents-role-assistant replayed by packages/pyric/test/ai/generate-content.test.ts test <code>ai#contents-role-assistant</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-contents-role-assistant.json" target="_blank" rel="noopener noreferrer"><code>ai-contents-role-assistant</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L110" target="_blank" rel="noopener noreferrer"><code>generate-content.test.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(request)</code><span class="compat-sub"><span class="compat-behavior"><code>responseMimeType</code> <code>application/json</code> plus a <code>responseSchema</code> yields a text part that parses as JSON with the schema key set</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">Capture ai-structured-output-shape replayed by packages/pyric/test/ai/generate-content.test.ts test <code>ai#generate-structured-output</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-structured-output-shape.json" target="_blank" rel="noopener noreferrer"><code>ai-structured-output-shape</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L110" target="_blank" rel="noopener noreferrer"><code>generate-content.test.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">Capture ai-structured-output-shape replayed by packages/pyric/test/ai/generate-content.test.ts test <code>ai#generate-structured-output</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-structured-output-shape.json" target="_blank" rel="noopener noreferrer"><code>ai-structured-output-shape</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L123" target="_blank" rel="noopener noreferrer"><code>generate-content.test.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(request)</code><span class="compat-sub"><span class="compat-behavior">With <code>thinkingConfig</code> on the probe model, text parts carry <code>thoughtSignature</code> and no part is flagged <code>thought: true</code></span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe">Capture ai-thinking-thought-parts (partKeySets, anyThoughtPart false) replayed by packages/pyric/test/ai/generate-content.test.ts test <code>ai#generate-thinking-signature</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-thinking-thought-parts.json" target="_blank" rel="noopener noreferrer"><code>ai-thinking-thought-parts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L125" target="_blank" rel="noopener noreferrer"><code>generate-content.test.ts</code></a>)</div></div>
+<div class="compat-evidence"><div class="compat-probe">Capture ai-thinking-thought-parts (partKeySets, anyThoughtPart false) replayed by packages/pyric/test/ai/generate-content.test.ts test <code>ai#generate-thinking-signature</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-thinking-thought-parts.json" target="_blank" rel="noopener noreferrer"><code>ai-thinking-thought-parts</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L138" target="_blank" rel="noopener noreferrer"><code>generate-content.test.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(request, singleRequestOptions)</code><span class="compat-sub"><span class="compat-behavior">A pre-aborted <code>SingleRequestOptions.signal</code> rejects the call</span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L138" target="_blank" rel="noopener noreferrer"><code>unit:generate-content.test.ts</code></a> test <code>ai#generate-abort-signal</code> (no capture; upstream SingleRequestOptions contract)</div></div>
+<div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/generate-content.test.ts#L151" target="_blank" rel="noopener noreferrer"><code>unit:generate-content.test.ts</code></a> test <code>ai#generate-abort-signal</code> (no capture; upstream SingleRequestOptions contract)</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()</code><span class="compat-sub"><span class="compat-behavior">Token counts are minted without a tokenizer, and the minimal envelope omits <code>safetyRatings</code>, matching the captured candidate key set</span></span></span></summary>
@@ -222,6 +227,10 @@
 <div class="compat-evidence"><div class="compat-probe">Capture ai-error-fncall-missing-thought-signature replayed by packages/pyric/test/ai/function-calling.test.ts test <code>ai#fncall-thought-signature-required</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-error-fncall-missing-thought-signature.json" target="_blank" rel="noopener noreferrer"><code>ai-error-fncall-missing-thought-signature</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/function-calling.test.ts#L4" target="_blank" rel="noopener noreferrer"><code>function-calling.test.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">functionResponse round trip</code><span class="compat-sub"><span class="compat-behavior">A function response under role <code>function</code>, the role the SDK <code>ChatSession</code> sends, is refused 400 INVALID_ARGUMENT with a message that names the role; the same round trip under role <code>user</code> is accepted</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Capture ai-error-function-role-refused replayed by packages/pyric/test/ai/function-calling.test.ts test <code>ai#fncall-function-role-refused</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-error-function-role-refused.json" target="_blank" rel="noopener noreferrer"><code>ai-error-function-role-refused</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/function-calling.test.ts#L5" target="_blank" rel="noopener noreferrer"><code>function-calling.test.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">scripted engine synthesis</code><span class="compat-sub"><span class="compat-behavior">The engine mints a <code>thoughtSignature</code> on every functionCall part it synthesizes, so scripted tool round trips replay cleanly</span></span></span></summary>
 <div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/function-calling.test.ts#L4" target="_blank" rel="noopener noreferrer"><code>unit:function-calling.test.ts</code></a> test <code>ai#fncall-signature-minted</code> (capture ai-error-fncall-missing-thought-signature cited as the motivating rejection) (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-error-fncall-missing-thought-signature.json" target="_blank" rel="noopener noreferrer"><code>ai-error-fncall-missing-thought-signature</code></a>)</div></div>
 </details>
@@ -260,16 +269,39 @@
 <div class="compat-evidence"><div class="compat-probe">Capture ai-error-empty-contents replayed by packages/pyric/test/ai/errors-counttokens.test.ts test <code>ai#error-empty-contents</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-error-empty-contents.json" target="_blank" rel="noopener noreferrer"><code>ai-error-empty-contents</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/errors-counttokens.test.ts#L116" target="_blank" rel="noopener noreferrer"><code>errors-counttokens.test.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">error envelope</code><span class="compat-sub"><span class="compat-behavior">An invalid content role fails 400 INVALID_ARGUMENT and the message lists the production role vocabulary: SYSTEM, SYSTEM_1, USER, ASSISTANT, DEVELOPER, CONTEXT, USER_CONTEXT, MODEL, USER</span></span></span></summary>
+<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">error envelope</code><span class="compat-sub"><span class="compat-behavior">An invalid content role fails 400 INVALID_ARGUMENT and the message lists the production role vocabulary: MODEL, USER</span></span></span></summary>
 <div class="compat-evidence"><div class="compat-probe">Capture ai-error-bad-role replayed by packages/pyric/test/ai/errors-counttokens.test.ts test <code>ai#error-bad-role</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-error-bad-role.json" target="_blank" rel="noopener noreferrer"><code>ai-error-bad-role</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/errors-counttokens.test.ts#L125" target="_blank" rel="noopener noreferrer"><code>errors-counttokens.test.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">error envelope</code><span class="compat-sub"><span class="compat-behavior">A <code>contents</code> turn under role <code>system</code> fails 400 INVALID_ARGUMENT with the unknown-role text that lists MODEL, USER, although the role <code>function</code> refusal lists SYSTEM</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Capture ai-contents-role-system replayed by packages/pyric/test/ai/errors-counttokens.test.ts test <code>ai#contents-role-system</code> (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-contents-role-system.json" target="_blank" rel="noopener noreferrer"><code>ai-contents-role-system</code></a>, <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/errors-counttokens.test.ts#L138" target="_blank" rel="noopener noreferrer"><code>errors-counttokens.test.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">AIError</code><span class="compat-sub"><span class="compat-behavior">HTTP failures surface as <code>AIError</code> with an <code>AIErrorCode</code> code and <code>customErrorData</code> carrying <code>status</code>, <code>statusText</code>, and <code>errorDetails</code></span></span></span></summary>
 <div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/errors-counttokens.test.ts#L83" target="_blank" rel="noopener noreferrer"><code>unit:errors-counttokens.test.ts</code></a> test <code>ai#error-aierror-shape</code> (capture ai-error-bad-api-key cited as the sample envelope) (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-error-bad-api-key.json" target="_blank" rel="noopener noreferrer"><code>ai-error-bad-api-key</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">AIErrorCode</code><span class="compat-sub"><span class="compat-behavior"><code>AIErrorCode</code> exposes the 14 documented codes, from <code>error</code> through <code>unsupported</code></span></span></span></summary>
-<div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/errors-counttokens.test.ts#L154" target="_blank" rel="noopener noreferrer"><code>unit:errors-counttokens.test.ts</code></a> test <code>ai#error-code-vocabulary</code> (upstream constant vocabulary)</div></div>
+<div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/errors-counttokens.test.ts#L170" target="_blank" rel="noopener noreferrer"><code>unit:errors-counttokens.test.ts</code></a> test <code>ai#error-code-vocabulary</code> (upstream constant vocabulary)</div></div>
+</details>
+</div>
+
+## Requests checked against production captures
+
+Each row cites a production capture from the App Check and AI Logic hunt. A `bug` row states production's behavior and pyric's; its replay holds both answers until the fix lands.
+
+<div class="compat-list">
+<details class="compat-row" data-status="bug">
+<summary class="compat-line"><span class="compat-dot" data-status="bug" role="img" aria-label="Bug" title="Bug"></span><span class="compat-main"><code class="compat-api">generateContent({ contents: [{ parts }] }) with no role</code><span class="compat-sub"><span class="compat-behavior">AI-21: production answers contents with no role (200); pyric refuses it (400, Role '' is not supported).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-request-edge-roleless-contents.json" target="_blank" rel="noopener noreferrer"><code>oracle:ai-request-edge-roleless-contents</code></a>. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/hunt-captures.test.ts#L56" target="_blank" rel="noopener noreferrer"><code>hunt-captures.test.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="bug">
+<summary class="compat-line"><span class="compat-dot" data-status="bug" role="img" aria-label="Bug" title="Bug"></span><span class="compat-main"><code class="compat-api">startChat({ systemInstruction: 'text' }).sendMessage(prompt)</code><span class="compat-sub"><span class="compat-behavior">AI-22: production refuses a string systemInstruction from startChat (400 INVALID_ARGUMENT); pyric answers.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-request-edge-string-system-instruction.json" target="_blank" rel="noopener noreferrer"><code>oracle:ai-request-edge-string-system-instruction</code></a>. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/hunt-captures.test.ts#L64" target="_blank" rel="noopener noreferrer"><code>hunt-captures.test.ts</code></a>)</div></div>
+</details>
+<details class="compat-row" data-status="bug">
+<summary class="compat-line"><span class="compat-dot" data-status="bug" role="img" aria-label="Bug" title="Bug"></span><span class="compat-main"><code class="compat-api">getGenerativeModel(ai, { model: 'gemini-pro' }).generateContent(prompt)</code><span class="compat-sub"><span class="compat-behavior">AI-23: production refuses the model gemini-pro (404 NOT_FOUND); pyric answers.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe"><a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-request-edge-model-gemini-pro.json" target="_blank" rel="noopener noreferrer"><code>oracle:ai-request-edge-model-gemini-pro</code></a>. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/hunt-captures.test.ts#L74" target="_blank" rel="noopener noreferrer"><code>hunt-captures.test.ts</code></a>)</div></div>
 </details>
 </div>
 
@@ -399,7 +431,7 @@
 <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#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-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#L78" 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">
@@ -434,6 +466,27 @@
 </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#L311" 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#L77" target="_blank" rel="noopener noreferrer"><code>scenario.ts</code></a>)</div></div>
+</details>
+</div>
+
 ## Current gaps
 
 ### Documented divergences
@@ -454,11 +507,24 @@ 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#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>
+<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#L78" 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#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>
 
+### Bugs
+
+Behavior that should match production Firebase but currently does not.
+
+<div class="compat-list">
+<details class="compat-row" data-status="bug"><summary class="compat-line"><span class="compat-dot" data-status="bug" role="img" aria-label="Bug" title="Bug"></span><span class="compat-main"><code class="compat-api">generateContent({ contents: [{ parts }] }) with no role</code><span class="compat-sub"><span class="compat-behavior">AI-21: production answers contents with no role (200); pyric refuses it (400, Role '' is not supported).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-note"><a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-request-edge-roleless-contents.json" target="_blank" rel="noopener noreferrer"><code>oracle:ai-request-edge-roleless-contents</code></a>. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/hunt-captures.test.ts#L56" target="_blank" rel="noopener noreferrer"><code>hunt-captures.test.ts</code></a>)</div></div></details>
+<details class="compat-row" data-status="bug"><summary class="compat-line"><span class="compat-dot" data-status="bug" role="img" aria-label="Bug" title="Bug"></span><span class="compat-main"><code class="compat-api">startChat({ systemInstruction: 'text' }).sendMessage(prompt)</code><span class="compat-sub"><span class="compat-behavior">AI-22: production refuses a string systemInstruction from startChat (400 INVALID_ARGUMENT); pyric answers.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-note"><a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-request-edge-string-system-instruction.json" target="_blank" rel="noopener noreferrer"><code>oracle:ai-request-edge-string-system-instruction</code></a>. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/hunt-captures.test.ts#L64" target="_blank" rel="noopener noreferrer"><code>hunt-captures.test.ts</code></a>)</div></div></details>
+<details class="compat-row" data-status="bug"><summary class="compat-line"><span class="compat-dot" data-status="bug" role="img" aria-label="Bug" title="Bug"></span><span class="compat-main"><code class="compat-api">getGenerativeModel(ai, { model: 'gemini-pro' }).generateContent(prompt)</code><span class="compat-sub"><span class="compat-behavior">AI-23: production refuses the model gemini-pro (404 NOT_FOUND); pyric answers.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-note"><a href="https://github.com/davideast/pyric/blob/main/packages/conformance/observations/ai/ai-request-edge-model-gemini-pro.json" target="_blank" rel="noopener noreferrer"><code>oracle:ai-request-edge-model-gemini-pro</code></a>. (Structured evidence: <a href="https://github.com/davideast/pyric/blob/main/packages/pyric/test/ai/hunt-captures.test.ts#L74" target="_blank" rel="noopener noreferrer"><code>hunt-captures.test.ts</code></a>)</div></div></details>
+</div>
+
 ## Reviewed public-runtime gaps
 
 <div class="compat-list">