pyric 0.0.1 → 0.1.0-alpha.11

package/LICENSE

@@ -0,0 +1,216 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 David East
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,180 @@
-# pyric
+<p align="center">
+  <img src="https://pyric.dev/pyric-logo.svg" alt="Pyric" width="180" />
+</p>
 
-Reserved.
+<h1 align="center">Build with Firebase without touching production</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"><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.
+
+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 a new Firebase application locally
+
+Create a Vite application with canonical Firebase imports, Firestore rules, and the Pyric development plugin already configured:
+
+```bash
+npm create pyric my-app
+cd my-app
+npm install
+npm run dev
+```
+
+## Run an existing Firebase application locally
+
+Install the development plugin:
+
+```bash
+npm install --save-dev @pyric/cli
+```
+
+Add it to the existing Vite configuration:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { pyricSandbox } from '@pyric/cli/vite';
+
+export default defineConfig({
+  plugins: [pyricSandbox()],
+});
+```
+
+Start the normal development server:
+
+```bash
+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.
+
+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 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.
+
+## Keep writing Firebase code
+
+Application code continues to import Firebase:
+
+```ts
+// src/firebase.ts
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+import { getFirestore } from 'firebase/firestore';
+
+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,
+});
+
+export const auth = getAuth(app);
+export const db = getFirestore(app);
+```
+
+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.
+
+## Inspect and correct a failed operation
+
+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.
+
+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.
+
+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
+pyricSandbox({
+  persist: true,
+  seed: 'seed.json',
+});
+```
+
+See [persistence and multi-tab behavior](packages/cli/docs/how-to/serve-persistence-and-multi-tab.md) for reset and seed precedence.
+
+## Give coding agents the same local Firebase target
+
+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:
+
+```ts
+pyricSandbox({ bridge: true });
+```
+
+The bridge mounts on the Vite development origin and routes agent operations to the same SharedWorker backend used by the application and Studio. The included [Claude Code plugin](pyric-plugin/README.md) discovers that bridge, while other MCP clients can connect to its HTTP endpoint.
+
+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 boundary
+
+Development sessions capture Firestore and Realtime Database operations in `.pyric/last-session.json` by default. Replay those requests against candidate rules before deployment:
+
+```bash
+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).
+
+## Ship the same application code
+
+A standard Vite production build leaves the development swap inactive:
+
+```bash
+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.
+
+## 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:
+
+```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.
+
+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.
+
+## Stability
+
+Pyric is alpha software, currently `0.1.0-alpha.8`. Firebase-shaped surfaces are tracked through the compatibility matrices. Pyric-specific development APIs may change between alpha releases. All packages are ESM-only and require Node 22.15 or later.
+
+## Develop Pyric
+
+The repository is a Bun workspace:
+
+```bash
+bun install
+bun run build
+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.

package/README.md.orig

@@ -0,0 +1,54 @@
+# `pyric`
+
+Firebase-shaped Web SDK mirrors backed by an in-process sandbox, plus Security
+Rules tooling and explicit sandbox controls.
+
+> **Alpha.** Mirrored subpaths are best-effort Firebase contracts. Read the
+> generated conformance scores and service matrices for measured coverage,
+> fidelity, and known gaps. Pyric-specific sandbox APIs are public alpha.
+
+## Public service fronts
+
+| Subpath | Surface |
+|---|---|
+| `pyric/app` | Firebase-shaped default and named app registry |
+| `pyric/firestore` | Firestore modular mirror and data/inspection tools |
+| `pyric/auth` | Auth modular mirror and sandbox auth helpers |
+| `pyric/database` | Realtime Database modular mirror |
+| `pyric/storage` | Storage modular mirror and rules-aware sandbox tools |
+| `pyric/rules` | Firestore and RTDB rules lint, simulation, explanation, constraints, and standard library |
+| `pyric/firestore-values` | Firestore value helpers |
+| `pyric/sandbox` | Sandbox lifecycle, identity, events, persistence, and replay |
+
+The package manifest is the authority for public exports, including the
+service-specific sandbox controls and adapter-only internal seams.
+
+## Explicit sandbox example
+
+```ts
+import { initializeApp } from 'pyric/app';
+import { collection, getDocs, getFirestore } from 'pyric/firestore';
+
+const app = initializeApp({ projectId: 'demo-project' });
+const db = getFirestore(app);
+const snap = await getDocs(collection(db, 'posts'));
+```
+
+Application code normally keeps canonical `firebase/*` imports.
+`@pyric/cli/vite`, `pyric dev`, or `@pyric/cli/register` activates development
+resolution to these mirrors. With activation absent, production loads Firebase
+directly; `pyric` contains no production dispatch.
+
+Pyric currently accepts one Firebase configuration per runtime. Default and
+named apps with equal options are distinct service containers connected to the
+same sandbox backend.
+
+## Documentation
+
+- [Firestore](docs/firestore/)
+- [Auth](docs/auth/)
+- [Realtime Database](docs/database/)
+- [Storage](docs/storage/)
+- [Rules](docs/rules/)
+- [Sandbox](docs/sandbox/)
+- [Conformance scores](https://pyric.dev/docs/conformance-scores/)

package/dist/ai/backend.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Backend configuration classes for `pyric/ai`, mirroring the installed
+ * `@firebase/ai@2.12.0`: an abstract {@link Backend} carrying
+ * `backendType`, with {@link GoogleAIBackend} (the default) and
+ * {@link VertexAIBackend} (location defaults to `us-central1`).
+ *
+ * In the sandbox mirror the backend is a pure configuration marker; the
+ * broker answers in-process either way. Production imports load Firebase's
+ * own backend classes before this package enters the graph.
+ */
+/** Identifies which backend service the SDK communicates with. */
+export declare const BackendType: {
+    readonly VERTEX_AI: "VERTEX_AI";
+    readonly GOOGLE_AI: "GOOGLE_AI";
+};
+export type BackendType = (typeof BackendType)[keyof typeof BackendType];
+/**
+ * Abstract base class representing the configuration for an AI service
+ * backend. Do not instantiate directly — use {@link GoogleAIBackend} or
+ * {@link VertexAIBackend}.
+ */
+export declare abstract class Backend {
+    readonly backendType: BackendType;
+    protected constructor(type: BackendType);
+}
+/** Configuration class for the Gemini Developer API backend (the default). */
+export declare class GoogleAIBackend extends Backend {
+    constructor();
+}
+/** Configuration class for the Vertex AI Gemini API backend. */
+export declare class VertexAIBackend extends Backend {
+    readonly location: string;
+    constructor(location?: string);
+}
+//# sourceMappingURL=backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/ai/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,kEAAkE;AAClE,eAAO,MAAM,WAAW;;;CAGd,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE;;;;GAIG;AACH,8BAAsB,OAAO;IAC3B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC,SAAS,aAAa,IAAI,EAAE,WAAW;CAGxC;AAED,8EAA8E;AAC9E,qBAAa,eAAgB,SAAQ,OAAO;;CAI3C;AAED,gEAAgE;AAChE,qBAAa,eAAgB,SAAQ,OAAO;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,GAAE,MAAyB;CAIhD"}

package/dist/ai/backend.js

@@ -0,0 +1,42 @@
+/**
+ * Backend configuration classes for `pyric/ai`, mirroring the installed
+ * `@firebase/ai@2.12.0`: an abstract {@link Backend} carrying
+ * `backendType`, with {@link GoogleAIBackend} (the default) and
+ * {@link VertexAIBackend} (location defaults to `us-central1`).
+ *
+ * In the sandbox mirror the backend is a pure configuration marker; the
+ * broker answers in-process either way. Production imports load Firebase's
+ * own backend classes before this package enters the graph.
+ */
+const DEFAULT_LOCATION = 'us-central1';
+/** Identifies which backend service the SDK communicates with. */
+export const BackendType = {
+    VERTEX_AI: 'VERTEX_AI',
+    GOOGLE_AI: 'GOOGLE_AI',
+};
+/**
+ * Abstract base class representing the configuration for an AI service
+ * backend. Do not instantiate directly — use {@link GoogleAIBackend} or
+ * {@link VertexAIBackend}.
+ */
+export class Backend {
+    backendType;
+    constructor(type) {
+        this.backendType = type;
+    }
+}
+/** Configuration class for the Gemini Developer API backend (the default). */
+export class GoogleAIBackend extends Backend {
+    constructor() {
+        super(BackendType.GOOGLE_AI);
+    }
+}
+/** Configuration class for the Vertex AI Gemini API backend. */
+export class VertexAIBackend extends Backend {
+    location;
+    constructor(location = DEFAULT_LOCATION) {
+        super(BackendType.VERTEX_AI);
+        this.location = location || DEFAULT_LOCATION;
+    }
+}
+//# sourceMappingURL=backend.js.map

package/dist/ai/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/ai/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAEvC,kEAAkE;AAClE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,SAAS,EAAE,WAAW;IACtB,SAAS,EAAE,WAAW;CACd,CAAC;AAGX;;;;GAIG;AACH,MAAM,OAAgB,OAAO;IAClB,WAAW,CAAc;IAElC,YAAsB,IAAiB;QACrC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,OAAO,eAAgB,SAAQ,OAAO;IAC1C;QACE,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,OAAO,eAAgB,SAAQ,OAAO;IACjC,QAAQ,CAAS;IAE1B,YAAY,WAAmB,gBAAgB;QAC7C,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,gBAAgB,CAAC;IAC/C,CAAC;CACF"}

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

@@ -0,0 +1,72 @@
+/**
+ * The sandbox AI broker — the ONE in-process Gemini-wire model every plane
+ * consumes (house pattern: the messaging broker):
+ *
+ *   - the client mirror (`pyric/ai`, next stage) calls generateContent /
+ *     streamGenerateContent / countTokens exactly like `rtdb.*` / `auth.*`
+ *     will over the worker protocol (cdd-deltas #98.3);
+ *   - Pyric Studio & tracing consume the typed `service_mutation` events the
+ *     broker emits onto the sandbox's unified `onEvent` stream;
+ *   - answering is delegated through ONE seam ({@link AnswerEngine},
+ *     cdd-deltas #97): `scripted` (default, zero-I/O) or `openai`.
+ *
+ * The broker validates requests LIKE PRODUCTION does — before any engine
+ * runs — throwing {@link AiBrokerError} carrying the exact captured error
+ * envelope:
+ *   - empty/missing `contents`            → `ai-error-empty-contents`
+ *   - a role outside the captured list    → `ai-error-bad-role`
+ *   - a model-turn functionCall part with no thoughtSignature
+ *                                         → `ai-error-fncall-missing-thought-signature`
+ *
+ * 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
+ * consumer's problem, never the broker's (the sandbox's emit fan-out already
+ * isolates listener throws; this guard covers the emit path itself).
+ */
+import type { Sandbox } from 'pyric/sandbox';
+import type { AnswerEngine, CountTokensRequest, CountTokensResponse, EngineConfig, GenerateContentRequest, RawEnvelope, WireChunk, WireResponse } from './types.js';
+export interface AiBrokerOptions {
+    /** Engine config, or a fully custom engine. Default: zero-config scripted. */
+    engine?: EngineConfig | AnswerEngine;
+    /** When present, ops land on the sandbox's unified event stream. */
+    sandbox?: Sandbox;
+}
+export declare class AiBroker {
+    readonly engine: AnswerEngine;
+    private readonly sandbox;
+    private readonly engineKind;
+    private readonly engineModel;
+    private readonly engineBaseUrl;
+    constructor(options?: AiBrokerOptions);
+    /** One-line construction-time summary of what this broker resolved to. */
+    private describeEngine;
+    /** Additive detail fields every emitted event carries so Studio can show the engine. */
+    private engineDetail;
+    generateContent(req: GenerateContentRequest, model: string): Promise<WireResponse>;
+    /**
+     * Chunk objects with the captured framing SEMANTICS (finishReason last
+     * chunk only, usageMetadata every chunk). Validation runs EAGERLY — a bad
+     * request throws here, before iteration, the way production answers with
+     * an HTTP error instead of a stream.
+     */
+    streamGenerateContent(req: GenerateContentRequest, model: string): AsyncIterable<WireChunk>;
+    countTokens(req: CountTokensRequest, model: string): Promise<CountTokensResponse>;
+    private validate;
+    private validateContents;
+    /** Emit the rejection onto the event stream, then throw the wire envelope. */
+    private reject;
+    /**
+     * Land a broker operation on the sandbox's unified event stream.
+     * Best-effort, storage-precedent: a throw from the emit path must never
+     * fail the AI operation the caller just completed.
+     */
+    private emit;
+}
+/**
+ * Fixture helper: extract `behavior.raw` from a parsed oracle observation
+ * JSON so a capture pastes straight into a script entry
+ * (`{ respond: loadObservationEnvelope(obs) }`). Captures are the corpus.
+ */
+export declare function loadObservationEnvelope(obsJson: unknown): RawEnvelope;
+//# sourceMappingURL=broker.d.ts.map

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

@@ -0,0 +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"}