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

package/README.md

@@ -2,50 +2,39 @@
   <img src="https://pyric.dev/pyric-logo.svg" alt="Pyric" width="180" />
 </p>
 
-<h1 align="center">A local first Firebase development framework built for Agents</h1>
+<h1 align="center">A Firebase that runs inside your app</h1>
 
-<p align="center">Keep the same <code>firebase/*</code> code. Pyric runs it against a local backend during development, then gets out of the way when the app ships to Firebase.</p>
+<p align="center">Keep the same <code>firebase/*</code> code. During <code>vite dev</code> those imports resolve to a local backend running in the page. A production build ships the real Firebase SDK, unchanged.</p>
 
 <p align="center"><a href="https://pyric.dev">pyric.dev</a></p>
 
 <br />
 
-Pyric adds a development-only resolution layer to a Firebase application. Run the Vite development server and supported Firebase imports resolve to a browser-local backend. Run a normal production build and those imports resolve to Firebase again. The application source does not branch between the two.
+Application code stays canonical Firebase:
 
-The mirrored data services do not connect to a production Firebase project. Local writes cannot delete production data or create Firebase usage charges, and local rules changes do not deploy. Pyric owns the development sandbox and verification workflow. Firebase owns production, with `firebase-tools` or the Firebase Console handling deployment.
-
-## Start with a coding agent
-
-Install the Pyric plugin:
-
-```bash
-npx plugins add davideast/pyric
-```
-
-Antigravity CLI and OpenCode use the standalone skill installer:
+```ts
+// src/firebase.ts
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+import { getFirestore } from 'firebase/firestore';
 
-```bash
-# Antigravity CLI
-npx skills add https://github.com/davideast/pyric/tree/main/pyric-plugin/skills/pyric-start --agent antigravity-cli
+const app = initializeApp({
+  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+});
 
-# OpenCode
-npx skills add https://github.com/davideast/pyric/tree/main/pyric-plugin/skills/pyric-start --agent opencode
+export const auth = getAuth(app);
+export const db = getFirestore(app);
 ```
 
-Then invoke the skill:
+Run the Vite development server and supported Firebase imports resolve to a browser-local backend: Auth, Firestore with Security Rules, persistence in IndexedDB, one SharedWorker backend shared by every tab on the dev origin. Run a normal production build and those imports resolve to Firebase again. The application source does not branch between the two, and the local mirror never connects to a production project.
 
-| Agent | Enter |
-|---|---|
-| Codex | `$pyric-start` |
-| Claude Code | `/pyric:pyric-start` |
-| Antigravity CLI | `/pyric-start` |
-| OpenCode | `/pyric-start` |
+Coding agents get the same backend. A [skill](#start-with-a-coding-agent) sets up the sandbox end to end (`npx plugins add davideast/pyric`, then `/pyric`), and an opt-in MCP bridge lets an agent seed, inspect, and change the backend the app is already running against. `can-i-use` answers what conforms to real Firebase before the agent builds on it.
 
-The leading `$` or `/` is part of the command.
-
-The skill chooses the project launcher, starts one local sandbox bridge, opens the application, and confirms that the browser sandbox is connected.
+<img width="1512" height="947" alt="Pyric Studio showing local data, requests, authentication state, and Security Rules verdicts" src="https://github.com/user-attachments/assets/cb4a219c-c5f0-4fb7-8904-996416c0a79c" />
 
-## Start from the terminal
+## Create a new app
 
 Create a Vite application with canonical Firebase imports, Firestore rules, and the Pyric development plugin already configured:
 
@@ -82,70 +71,69 @@ Start the normal development server:
 npm run dev
 ```
 
-During `vite dev`, the plugin swaps supported `firebase/*` modules at resolution time. The backend runs in a SharedWorker, so tabs on the same development origin use one local backend. Browser-local persistence uses IndexedDB.
+During `vite dev`, the plugin swaps supported `firebase/*` modules at resolution time. Pyric Studio is available on the Vite origin at `/__pyric/ui/studio`. It opens the same backend used by the application.
 
-Pyric Studio is available on the Vite origin at `/__pyric/ui/`. It opens the same backend used by the application.
+For a static application or a Node process, `pyric sandbox` provides the same development-only package swap without the Vite plugin. The [CLI reference](packages/site-docs/src/content/reference/cli.md) documents those paths and every command.
 
-For a static application or a Node process, `pyric dev` provides the same development-only package swap without the Vite plugin. The [CLI reference](packages/cli/docs/reference/cli.md) documents those paths and every command.
+## Start with a coding agent
 
-## Keep using official Firebase SDKs
+Install the Pyric plugin:
 
-Application code continues to import Firebase:
+```bash
+npx plugins add davideast/pyric
+```
 
-```ts
-// src/firebase.ts
-import { initializeApp } from 'firebase/app';
-import { getAuth } from 'firebase/auth';
-import { getFirestore } from 'firebase/firestore';
+Antigravity CLI and OpenCode use the standalone skill installer:
 
-const app = initializeApp({
-  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
-  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
-  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
-});
+```bash
+# Antigravity CLI
+npx skills add https://github.com/davideast/pyric/tree/main/pyric-plugin/skills/pyric --agent antigravity-cli
 
-export const auth = getAuth(app);
-export const db = getFirestore(app);
+# OpenCode
+npx skills add https://github.com/davideast/pyric/tree/main/pyric-plugin/skills/pyric --agent opencode
 ```
 
-The Firebase configuration is accepted by the local mirror during development. The production build passes that same configuration to Firebase. Normal Auth, Firestore, Realtime Database, Storage, Messaging, and Firebase AI Logic usage still belongs in the [Firebase documentation](https://firebase.google.com/docs).
-
-Pyric documents the parts that differ locally, including supported behavior, Security Rules, persistence, inspection, verification, and known gaps. See [use the Vite plugin](packages/cli/docs/how-to/use-the-vite-plugin.md) for the complete plugin contract.
-
-## Monitor the local environment in Pyric Studio
+Then invoke the skill:
 
-Pyric Studio shows local data, requests, authentication state, Security Rules verdicts, and denied operations. Open `/__pyric/ui/` on the development server and reproduce the failure. A denied request includes the path and verdict needed to correct the rule or the application code.
+| Agent | Enter |
+|---|---|
+| Codex | `$pyric` |
+| Claude Code | `/pyric:pyric` |
+| Antigravity CLI | `/pyric` |
+| OpenCode | `/pyric` |
 
-<img width="1512" height="947" alt="image" src="https://github.com/user-attachments/assets/cb4a219c-c5f0-4fb7-8904-996416c0a79c" />
+The leading `$` or `/` is part of the command.
 
-The Vite plugin discovers the Firestore rules path from `firebase.json`, or falls back to `firestore.rules`. Saving that file replaces the active local ruleset without a production deploy. A parse failure leaves the last valid ruleset active and reports the error in the development server.
+The skill chooses the project launcher, starts one local sandbox bridge, opens the application, and confirms that the browser sandbox is connected.
 
-State and test identities stay browser-local by default. Add `persist: true` to write a committable `.pyric/state/state.json`, or use `seed` to start from a known scenario:
+An agent can also work through the MCP bridge directly. It keeps writing the same Firebase code while inspecting and changing the backend the application is already using. Agent access is opt-in:
 
 ```ts
 pyric({
-  persist: true,
-  seed: 'seed.json',
+  bridge: true
 });
 ```
 
-See [persistence and multi-tab behavior](packages/cli/docs/how-to/serve-persistence-and-multi-tab.md) for reset and seed precedence.
+The bridge mounts on the Vite development origin and routes agent operations to the same SharedWorker backend used by the application and Studio. This protects the local workflow, not an independently credentialed process. A coding agent with production Firebase credentials or deployment access can still affect production outside Pyric.
+
+## Monitor the local environment in Pyric Studio
+
+Pyric Studio shows local data, requests, authentication state, Security Rules verdicts, and denied operations. Open `/__pyric/ui/studio` on the development server and reproduce the failure. A denied request includes the path and verdict needed to correct the rule or the application code.
 
-## Connect Coding Agents to the Sandbox using the Pyric MCP server
+The Vite plugin discovers the Firestore rules path from `firebase.json`, or falls back to `firestore.rules`. Saving that file replaces the active local ruleset without a production deploy. A parse failure leaves the last valid ruleset active and reports the error in the development server.
 
-An agent can keep writing the same Firebase code while inspecting and changing the backend that the application is already using. Agent access is opt-in. Enable the MCP bridge in the Vite plugin:
+State and test identities stay browser-local by default. Add `persist: true` to write a committable `.pyric/state/state.json`, or use `seed` to start from a known scenario:
 
 ```ts
-pyric({ 
-  bridge: true 
+pyric({
+  persist: true,
+  seed: 'seed.json',
 });
 ```
 
-The bridge mounts on the Vite development origin and routes agent operations to the same SharedWorker backend used by the application and Studio.
+See [persistence and multi-tab behavior](packages/site-docs/src/content/observe/shape-your-data.md) for reset and seed precedence.
 
-This protects the local workflow, not an independently credentialed process. A coding agent with production Firebase credentials or deployment access can still affect production outside Pyric.
-
-## Verify the rules against production 
+## Verify the rules against production
 
 Development sessions capture Firestore and Realtime Database operations in `.pyric/last-session.json` by default. Replay those requests against candidate rules before deployment:
 
@@ -153,7 +141,7 @@ Development sessions capture Firestore and Realtime Database operations in `.pyr
 npx pyric verify
 ```
 
-The default engine runs locally. The optional Firestore Rules Test API engine sends derived rule cases to Google's hosted evaluator when production-authority verification is needed. It verifies rules and does not deploy them. See [verify against a captured session](packages/cli/docs/how-to/verify-against-a-captured-session.md).
+The default engine runs locally. The optional Firestore Rules Test API engine sends derived rule cases to Google's hosted evaluator when production-authority verification is needed. It verifies rules and does not deploy them. See [verify against a captured session](packages/site-docs/src/content/ship/ship-to-production.md).
 
 ## Ship the same application code
 
@@ -165,37 +153,24 @@ npm run build
 
 The built application contains the real Firebase SDK and uses the Firebase configuration already present in the source. Deploy the build, rules, and indexes with `firebase-tools` or the Firebase Console. Pyric has no production deployment path.
 
+The mirrored data services do not connect to a production Firebase project. Local writes cannot delete production data or create Firebase usage charges, and local rules changes do not deploy. Pyric owns the development sandbox and verification workflow. Firebase owns production, with `firebase-tools` or the Firebase Console handling deployment.
+
+Normal Auth, Firestore, Realtime Database, Storage, Messaging, and Firebase AI Logic usage still belongs in the [Firebase documentation](https://firebase.google.com/docs). Pyric documents the parts that differ locally, including supported behavior, Security Rules, persistence, inspection, verification, and known gaps. See [use the Vite plugin](packages/site-docs/src/content/get-started/vite.md) for the complete plugin contract.
+
 ## Check what Pyric mirrors
 
 Pyric is an independent implementation of observable Firebase behavior. Conformance evidence records what has been compared with Firebase and keeps five outcomes distinct: conforms, documented divergence, bug, unsupported, and unverified. The evidence is a floor, not a claim that every Firebase behavior has been measured.
 
-Ask about a developer-facing feature without nesting discovery under rules verification:
+Ask about a developer-facing feature:
 
 ```bash
 npx pyric can-i-use getAfter
 npx pyric can-i-use firestore-rules/request.query --json
 ```
 
-The result reports availability, Firebase fidelity, and assurance eligibility as separate axes. Exact names succeed; a name shared by multiple surfaces asks you to qualify it, and fuzzy input prints labeled suggestions and exits nonzero instead of presenting a guess as a trust answer.
-
-Documentation and other Node consumers can bind the same feature name to the
-published import that exposes it, without maintaining a second surface map:
-
-```ts
-import { canIUse, canIUseImport } from '@pyric/cli/conformance';
-
-const result = canIUse('getDownloadURL', { importPath: 'pyric/storage' });
-const evidence = canIUseImport('pyric/storage');
-const evidencePage = evidence && `/docs/${evidence.evidenceSlug}/`;
-```
-
-Each support result carries only census-proven `importPaths`; registry ownership
-cannot invent package exports. `canIUseImport()` supplies the separate canonical
-import-to-evidence join used by generated API documentation. An unrelated
-import path returns no exact match rather than borrowing another surface's trust
-claim.
+The result reports availability, Firebase fidelity, and assurance eligibility as separate axes. Exact names succeed; fuzzy input prints labeled suggestions and exits nonzero instead of presenting a guess as a trust answer.
 
-Read the generated [conformance scores](https://pyric.dev/docs/conformance-scores/) and the service matrices in the site's Conformance section. They are built from the same canonical registry used by assurance and `canIUse`, without committing duplicate Markdown. The [versioning and compatibility policy](packages/pyric/docs/explanation/versioning-and-compatibility.md) explains the release boundary.
+Read the generated [conformance scores](https://pyric.dev/docs/conformance-scores/) and the service matrices in the site's Conformance section. They are built from the same canonical registry used by assurance and `canIUse`. Node consumers can query the same registry through [`@pyric/cli/conformance`](packages/site-docs/src/content/reference/cli.md). The [versioning and compatibility policy](packages/site-docs/src/content/trust/versioning-and-compatibility.md) explains the release boundary.
 
 ## Stability
 
@@ -212,4 +187,4 @@ bun run test
 bun run compat:check
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md), [CONTEXT.md](CONTEXT.md), and [AGENTS.md](AGENTS.md) before changing the codebase.
+See [CONTEXT.md](CONTEXT.md) and [AGENTS.md](AGENTS.md) before changing the codebase.

package/dist/ai/blocked.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Blocked-response detection: the ONE definition of "this envelope carries
+ * no usable content because a filter fired", shared by the two places that
+ * need it:
+ *
+ *   - `response-helpers.ts`, which throws upstream's exact
+ *     `Response error: Candidate was blocked due to <reason>` out of
+ *     `text()` / `functionCalls()` / `inlineDataParts()` when the caller
+ *     reaches for content that isn't there;
+ *   - `broker/broker.ts`, which lands a `response_blocked` event on the
+ *     sandbox's unified stream at RESPONSE time, so the block is visible
+ *     even when nobody ever calls `text()` (an app that renders
+ *     `response.text ?? ''` used to show an empty bubble and nothing else).
+ *
+ * A block is not a rejection: production answers HTTP 200 with an empty
+ * candidate and the reason in `finishReason` (SAFETY, RECITATION,
+ * BLOCKLIST, PROHIBITED_CONTENT, SPII, the IMAGE_* variants), or, when the
+ * PROMPT itself was refused, with no candidates at all and a
+ * `promptFeedback.blockReason`. Nothing throws on the wire path.
+ *
+ * Leaf module by construction: it imports only `./enums.js` (which imports
+ * nothing) and a type. `broker/` must NOT reach into `response-helpers.ts`
+ * for this: that file pulls `./errors.js`, which imports `./broker/index.js`
+ * as a value, and the round trip would be a real runtime cycle.
+ */
+import type { WireResponse } from './broker/types.js';
+/** Does this candidate's finish reason mean the content was withheld? */
+export declare function isBlockingFinishReason(finishReason: string | undefined): boolean;
+/** What a block was, in the wire's own vocabulary. Exactly one of
+ *  `finishReason` (a candidate was withheld) / `blockReason` (the prompt was
+ *  refused) is normally set; both may be absent when production sent
+ *  `promptFeedback` with no reason at all. */
+export interface ResponseBlock {
+    /** Candidate-level: the blocking `finishReason` off candidate 0. */
+    finishReason?: string;
+    /** Candidate-level: production's own explanatory `finishMessage`. */
+    finishMessage?: string;
+    /** Prompt-level: `promptFeedback.blockReason`. */
+    blockReason?: string;
+}
+/**
+ * Classify an envelope, mirroring `hasValidCandidates` in
+ * `response-helpers.ts` EXACTLY so the event stream and the thrown error can
+ * never disagree: candidate 0 with a blocking finish reason is a block; no
+ * candidate 0 at all plus any `promptFeedback` is a block; everything else
+ * (including a plain `STOP` or `MAX_TOKENS`) is not.
+ *
+ * Returns `null` when the response is fine, so a caller reads as
+ * `const block = describeResponseBlock(res); if (block !== null) …`.
+ */
+export declare function describeResponseBlock(response: WireResponse): ResponseBlock | null;
+//# sourceMappingURL=blocked.d.ts.map

package/dist/ai/blocked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocked.d.ts","sourceRoot":"","sources":["../../src/ai/blocked.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA4BtD,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGhF;AAED;;;8CAG8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa,GAAG,IAAI,CAalF"}

package/dist/ai/blocked.js

@@ -0,0 +1,83 @@
+/**
+ * Blocked-response detection: the ONE definition of "this envelope carries
+ * no usable content because a filter fired", shared by the two places that
+ * need it:
+ *
+ *   - `response-helpers.ts`, which throws upstream's exact
+ *     `Response error: Candidate was blocked due to <reason>` out of
+ *     `text()` / `functionCalls()` / `inlineDataParts()` when the caller
+ *     reaches for content that isn't there;
+ *   - `broker/broker.ts`, which lands a `response_blocked` event on the
+ *     sandbox's unified stream at RESPONSE time, so the block is visible
+ *     even when nobody ever calls `text()` (an app that renders
+ *     `response.text ?? ''` used to show an empty bubble and nothing else).
+ *
+ * A block is not a rejection: production answers HTTP 200 with an empty
+ * candidate and the reason in `finishReason` (SAFETY, RECITATION,
+ * BLOCKLIST, PROHIBITED_CONTENT, SPII, the IMAGE_* variants), or, when the
+ * PROMPT itself was refused, with no candidates at all and a
+ * `promptFeedback.blockReason`. Nothing throws on the wire path.
+ *
+ * Leaf module by construction: it imports only `./enums.js` (which imports
+ * nothing) and a type. `broker/` must NOT reach into `response-helpers.ts`
+ * for this: that file pulls `./errors.js`, which imports `./broker/index.js`
+ * as a value, and the round trip would be a real runtime cycle.
+ */
+import { FinishReason } from './enums.js';
+/**
+ * Finish reasons that mean "no usable content": the installed
+ * `@firebase/ai@2.12.0` `badFinishReasons` set, verbatim and in upstream's
+ * order. Every one of these makes the response helpers throw instead of
+ * returning text, which is exactly the set worth announcing to a developer.
+ */
+const BLOCKING_FINISH_REASONS = [
+    FinishReason.RECITATION,
+    FinishReason.SAFETY,
+    FinishReason.BLOCKLIST,
+    FinishReason.PROHIBITED_CONTENT,
+    FinishReason.SPII,
+    FinishReason.MALFORMED_FUNCTION_CALL,
+    FinishReason.IMAGE_SAFETY,
+    FinishReason.IMAGE_PROHIBITED_CONTENT,
+    FinishReason.IMAGE_OTHER,
+    FinishReason.NO_IMAGE,
+    FinishReason.IMAGE_RECITATION,
+    FinishReason.LANGUAGE,
+    FinishReason.UNEXPECTED_TOOL_CALL,
+    FinishReason.TOO_MANY_TOOL_CALLS,
+    FinishReason.MISSING_THOUGHT_SIGNATURE,
+    FinishReason.MALFORMED_RESPONSE,
+];
+/** Does this candidate's finish reason mean the content was withheld? */
+export function isBlockingFinishReason(finishReason) {
+    if (!finishReason)
+        return false;
+    return BLOCKING_FINISH_REASONS.some((reason) => reason === finishReason);
+}
+/**
+ * Classify an envelope, mirroring `hasValidCandidates` in
+ * `response-helpers.ts` EXACTLY so the event stream and the thrown error can
+ * never disagree: candidate 0 with a blocking finish reason is a block; no
+ * candidate 0 at all plus any `promptFeedback` is a block; everything else
+ * (including a plain `STOP` or `MAX_TOKENS`) is not.
+ *
+ * Returns `null` when the response is fine, so a caller reads as
+ * `const block = describeResponseBlock(res); if (block !== null) …`.
+ */
+export function describeResponseBlock(response) {
+    const firstCandidate = response.candidates?.[0];
+    if (firstCandidate !== undefined) {
+        if (!isBlockingFinishReason(firstCandidate.finishReason))
+            return null;
+        const candidateBlock = {};
+        candidateBlock.finishReason = firstCandidate.finishReason;
+        candidateBlock.finishMessage = firstCandidate.finishMessage;
+        return candidateBlock;
+    }
+    if (response.promptFeedback === undefined)
+        return null;
+    const promptBlock = {};
+    promptBlock.blockReason = response.promptFeedback.blockReason;
+    return promptBlock;
+}
+//# sourceMappingURL=blocked.js.map

package/dist/ai/blocked.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocked.js","sourceRoot":"","sources":["../../src/ai/blocked.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,uBAAuB,GAAsB;IACjD,YAAY,CAAC,UAAU;IACvB,YAAY,CAAC,MAAM;IACnB,YAAY,CAAC,SAAS;IACtB,YAAY,CAAC,kBAAkB;IAC/B,YAAY,CAAC,IAAI;IACjB,YAAY,CAAC,uBAAuB;IACpC,YAAY,CAAC,YAAY;IACzB,YAAY,CAAC,wBAAwB;IACrC,YAAY,CAAC,WAAW;IACxB,YAAY,CAAC,QAAQ;IACrB,YAAY,CAAC,gBAAgB;IAC7B,YAAY,CAAC,QAAQ;IACrB,YAAY,CAAC,oBAAoB;IACjC,YAAY,CAAC,mBAAmB;IAChC,YAAY,CAAC,yBAAyB;IACtC,YAAY,CAAC,kBAAkB;CAChC,CAAC;AAEF,yEAAyE;AACzE,MAAM,UAAU,sBAAsB,CAAC,YAAgC;IACrE,IAAI,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC;AAC3E,CAAC;AAeD;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAsB;IAC1D,MAAM,cAAc,GAAG,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,sBAAsB,CAAC,cAAc,CAAC,YAAY,CAAC;YAAE,OAAO,IAAI,CAAC;QACtE,MAAM,cAAc,GAAkB,EAAE,CAAC;QACzC,cAAc,CAAC,YAAY,GAAG,cAAc,CAAC,YAAY,CAAC;QAC1D,cAAc,CAAC,aAAa,GAAG,cAAc,CAAC,aAAa,CAAC;QAC5D,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,IAAI,QAAQ,CAAC,cAAc,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,WAAW,GAAkB,EAAE,CAAC;IACtC,WAAW,CAAC,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC;IAC9D,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/ai/broker/broker.d.ts

@@ -18,6 +18,17 @@
  *   - a model-turn functionCall part with no thoughtSignature
  *                                         → `ai-error-fncall-missing-thought-signature`
  *
+ * It also announces the refusals production does NOT throw for: a safety /
+ * recitation / blocklist block arrives as a 200 with an empty candidate, so
+ * the broker lands a `response_blocked` event ({@link emitBlockIfBlocked})
+ * alongside the normal op event. Without it a filtered answer is
+ * indistinguishable from a model that simply had nothing to say.
+ *
+ * The same goes for a model SUBSTITUTION ({@link emitModelSubstitution}): an
+ * engine that redirects the requested model (an openai `modelMap` entry or
+ * catch-all `model`, a gemini experimental alias) answers normally, so
+ * nothing anywhere says the developer tested a model they never named.
+ *
  * Event emission is best-effort behind one small choke-point ({@link emit}):
  * a throw from the emit path (or any event consumer downstream) must never
  * poison the AI operation the caller just completed — handler errors are the
@@ -43,6 +54,45 @@ export declare class AiBroker {
     private describeEngine;
     /** Additive detail fields every emitted event carries so Studio can show the engine. */
     private engineDetail;
+    /**
+     * Announce a SAFETY / RECITATION / BLOCKLIST / … block on the event stream.
+     *
+     * A block is the broker's SILENT refusal: unlike `request_rejected` nothing
+     * throws (production answers 200 with an empty candidate), so an app that
+     * renders whatever `text()` gave it just shows nothing, and the developer
+     * gets no signal anywhere. Emitting at RESPONSE time (not from the response
+     * helpers, which only fire if someone reaches for content) means the event
+     * lands whether or not the caller ever asks for the text.
+     *
+     * Detection is `blocked.ts`'s, shared verbatim with the response helpers'
+     * throw path, so the stream and the thrown error can never disagree.
+     *
+     * Returns whether the envelope WAS blocked, so the stream wrapper can
+     * announce at most once across its chunks.
+     */
+    private emitBlockIfBlocked;
+    /**
+     * Announce that the engine will answer as a DIFFERENT model than the one
+     * requested.
+     *
+     * A substitution is the quietest failure the broker has: nothing throws,
+     * content comes back, and the developer concludes they tested model X when
+     * model Y answered (an openai `modelMap` entry or catch-all `model`, a
+     * gemini experimental alias). Only engines that actually redirect implement
+     * {@link AnswerEngine.resolveEffectiveModel}; the rest are silent by
+     * construction.
+     *
+     * Fired at REQUEST time, before delegating: the swap is a property of the
+     * call about to go out, so it lands even when that call then fails.
+     * Comparison is bare-vs-bare, since `models/x` to `x` is the wire's prefix
+     * convention rather than a substitution, and an exact match emits nothing.
+     *
+     * `countTokens` is deliberately not announced: the openai engine never
+     * sends a model there at all (the count is synthesized locally), so an
+     * announcement would name an upstream call that never happens.
+     */
+    private emitModelSubstitution;
+    private emitRejectionIfBrokerError;
     generateContent(req: GenerateContentRequest, model: string): Promise<WireResponse>;
     /**
      * Chunk objects with the captured framing SEMANTICS (finishReason last

package/dist/ai/broker/broker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker.d.ts","sourceRoot":"","sources":["../../../src/ai/broker/broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAM7C,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAuBpB,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;IACrC,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AASD,qBAAa,QAAQ;IACnB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,OAAO,GAAE,eAAoB;IAkBzC,0EAA0E;IAC1E,OAAO,CAAC,cAAc;IAUtB,wFAAwF;IACxF,OAAO,CAAC,YAAY;IASd,eAAe,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAYxF;;;;;OAKG;IACH,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC;IAkBrF,WAAW,CAAC,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASvF,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,gBAAgB;IAaxB,8EAA8E;IAC9E,OAAO,CAAC,MAAM;IAWd;;;;OAIG;IACH,OAAO,CAAC,IAAI;CAkBb;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAYrE"}
+{"version":3,"file":"broker.d.ts","sourceRoot":"","sources":["../../../src/ai/broker/broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAQ7C,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,sBAAsB,EAEtB,WAAW,EACX,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAuBpB,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;IACrC,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AASD,qBAAa,QAAQ;IACnB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,OAAO,GAAE,eAAoB;IAsBzC,0EAA0E;IAC1E,OAAO,CAAC,cAAc;IAgBtB,wFAAwF;IACxF,OAAO,CAAC,YAAY;IAgBpB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,0BAA0B;IAS5B,eAAe,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBxF;;;;;OAKG;IACH,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC;IAmCrF,WAAW,CAAC,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAcvF,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,gBAAgB;IAaxB,8EAA8E;IAC9E,OAAO,CAAC,MAAM;IAWd;;;;OAIG;IACH,OAAO,CAAC,IAAI;CAkBb;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAYrE"}