pyric-admin 0.1.0-alpha.7 → 0.1.0-alpha.9

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,49 +1,156 @@
-# pyric-admin
+<p align="center">
+  <img src="https://pyric.dev/pyric-logo.svg" alt="Pyric" width="180" />
+</p>
 
-Firebase Admin-shaped adapters that can run against either a Pyric sandbox or
-real Firebase Admin SDK backends.
+<h1 align="center">Build with Firebase without touching production</h1>
 
-Use `pyric-admin` when you want server/admin ergonomics while keeping the same
-backend-selection model as the client package.
+<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>
 
-> **Alpha.** This package is an early alpha. The admin-shaped subpaths are
-> best-effort mirror contracts of `firebase-admin` — not guaranteed parity.
-> Any exported surface beyond the mirrored shapes is experimental public-alpha
-> and may change without notice.
+<p align="center"><a href="https://pyric.dev">pyric.dev</a></p>
 
-## Subpaths
+<br />
 
-| Subpath | Surface |
-|---|---|
-| `pyric-admin/app` | Admin app initialization for sandbox or production |
-| `pyric-admin/firestore` | Admin Firestore shape over sandbox or `firebase-admin/firestore` |
-| `pyric-admin/auth` | Admin Auth shape over sandbox or `firebase-admin/auth` |
-| `pyric-admin/database` | Admin Realtime Database shape over sandbox or `firebase-admin/database` |
-| `pyric-admin/storage` | Admin Storage shape over sandbox or `firebase-admin/storage` |
+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.
 
-## Example
+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
+npx create-pyric my-app
+cd my-app
+npm install
+npm run dev
+```
+
+`npm create pyric my-app` runs the same scaffold.
+
+## 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
-import { initializeApp } from 'pyric-admin/app';
-import { initializeSandbox } from 'pyric/sandbox';
-import { getFirestore } from 'pyric-admin/firestore';
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { pyricSandbox } from '@pyric/cli/vite';
 
-const app = initializeApp({ sandbox: initializeSandbox() });
-const db = getFirestore(app);
+export default defineConfig({
+  plugins: [pyricSandbox()],
+});
+```
+
+Start the normal development server:
 
-await db.collection('posts').doc('hello').set({ title: 'Hello' });
+```bash
+npm run dev
 ```
 
-Production apps pass normal Firebase Admin credentials:
+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
-import { initializeApp, cert } from 'pyric-admin/app';
+// src/firebase.ts
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+import { getFirestore } from 'firebase/firestore';
 
 const app = initializeApp({
-  credential: cert(serviceAccount),
+  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',
 });
 ```
 
-## Docs
+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.
+
+Read the generated matrices for [App](packages/pyric/docs/app/COMPAT.md), [Auth](packages/pyric/docs/auth/COMPAT.md), [Firestore](packages/pyric/docs/firestore/COMPAT.md), [Realtime Database](packages/pyric/docs/database/COMPAT.md), [Storage](packages/pyric/docs/storage/COMPAT.md), [Messaging](packages/pyric/docs/messaging/COMPAT.md), [AI Logic](packages/pyric/docs/ai/COMPAT.md), [Security Rules](packages/pyric/docs/rules/COMPAT.md), and [Functions with Realtime Database](packages/cli/docs/functions-rtdb/COMPAT.md). 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
+```
 
-- [Firestore docs](docs/firestore/)
+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,48 @@
+# `pyric-admin`
+
+Firebase Admin-shaped adapters for a Pyric sandbox.
+
+Use these subpaths when tests, development servers, or scripts need
+`firebase-admin` ergonomics against local or browser-hosted sandbox state. In
+activated development, `@pyric/cli/register` resolves canonical
+`firebase-admin/*` imports here. With activation absent, production execution
+loads `firebase-admin` directly.
+
+> **Alpha.** These are best-effort mirror contracts of `firebase-admin`. Read
+> the conformance matrices and service references for implemented behaviour and
+> explicit gaps.
+
+## Subpaths
+
+| Subpath | Sandbox surface |
+|---|---|
+| `pyric-admin/app` | Admin app registry and sandbox binding |
+| `pyric-admin/firestore` | Admin Firestore shape |
+| `pyric-admin/auth` | Admin Auth shape |
+| `pyric-admin/database` | Admin Realtime Database shape |
+| `pyric-admin/storage` | Admin Storage shape |
+
+## Explicit sandbox setup
+
+```ts
+import { initializeApp } from 'pyric-admin/app';
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore } from 'pyric-admin/firestore';
+
+const app = initializeApp({ sandbox: initializeSandbox() });
+const db = getFirestore(app);
+
+await db.collection('posts').doc('hello').set({ title: 'Hello' });
+```
+
+For unchanged server source, keep `firebase-admin/*` imports and run the
+development command through `pyric dev`. Production runs the same source
+without sandbox activation and therefore resolves Firebase Admin directly.
+
+## Documentation
+
+- [App registry and activation](docs/app/)
+- [Firestore](docs/firestore/)
+- [Auth API](https://pyric.dev/docs/pyric-admin-auth-reference-api/)
+- [Realtime Database API](https://pyric.dev/docs/pyric-admin-database-reference-api/)
+- [Storage API](https://pyric.dev/docs/pyric-admin-storage-reference-api/)

package/dist/app/index.d.ts

@@ -1,158 +1,47 @@
 /**
- * `pyric-admin/app` — Phase 3 initializeApp surface (ADR-001 D6) plus the
- * default-app registry and AMBIENT INIT (adoption experience, layer 3).
+ * `pyric-admin/app` — sandbox-only admin app registry.
  *
- * Mirror shape: at cutover this becomes `pyric-admin/app` and is the
- * single entry point where the sandbox-vs-prod choice is made for the
- * admin surface. Every `pyric-admin/*` subpath inspects the handle's
- * brand for backend dispatch.
- *
- * Current shadow scope:
- *   - `initializeApp({ credential, ... })` — prod-backed (live;
- *     delegates to `firebase-admin/app.initializeApp`).
- *   - `initializeApp({ sandbox })` — sandbox-backed (live).
- *   - `initializeApp()` — BARE, zero pyric identifiers in app code. The
- *     environment decides the backend (see "Ambient init" below).
- *   - Per-subpath adapter dispatch via the brand: implemented in
- *     `pyric-admin/{auth,database,storage}` via structural
- *     checks on the `app` argument. Phase 4 commits use property
- *     probing today; cutover swaps to brand-symbol reads.
- *
- * ── Default-app registry ──────────────────────────────────────────────
- *
- * Mirrors `firebase-admin/app`'s lifecycle exactly (oracle:
- * `firebase-admin/lib/app/lifecycle.js`):
- *
- *   - `initializeApp(config?, name?)` registers under `'[DEFAULT]'` when
- *     unnamed; `getApp(name?)` / `getApps()` / `deleteApp(app)` read it.
- *   - Duplicate-name errors carry firebase-admin's codes and message
- *     text: `app/duplicate-app` for a config'd re-init with a different
- *     configuration, `app/invalid-app-options` for a bare-vs-config'd
- *     mismatch (firebase-admin's autoInit mismatch), `app/no-app` from
- *     `getApp` on a missing name, `app/invalid-app-name` for a
- *     non-string/empty name. Errors reuse firebase-admin's own
- *     `FirebaseAppError` class, so `instanceof`, `constructor.name`,
- *     `.code`, and message text match production byte-for-byte
- *     (oracle: `admin-app-*` observations).
- *   - Idempotency mirror: a bare `initializeApp()` repeated for the same
- *     name returns the existing auto-initialized app (firebase-admin's
- *     autoInit path); `initializeApp({ sandbox })` repeated with the
- *     SAME `Sandbox` reference returns the existing app (the reference
- *     is our deep-equal analog — sandboxes have identity, not value
- *     equality); prod re-inits delegate the equality decision to
- *     firebase-admin itself (deep-equal options → same app; credential /
- *     httpAgent present → `app/invalid-app-options`, exactly upstream).
- *
- * ── Ambient init (bare `initializeApp()`) ─────────────────────────────
- *
- * The user's server code contains ZERO pyric identifiers — bare
- * `initializeApp()` + no-arg `getDatabase()` / `getAuth()`. The
- * environment picks the backend:
- *
- *   - `PYRIC_SANDBOX` unset → exactly firebase-admin's behavior:
- *     delegate to `firebase-admin/app.initializeApp()` (FIREBASE_CONFIG
- *     env + application-default credentials), register the prod arm.
- *   - `PYRIC_SANDBOX=remote` or `remote:<url>` → obtain a remote sandbox
- *     handle from the factory installed by `pyric-tools/register` at
- *     `globalThis[REMOTE_SANDBOX_FACTORY]`
- *     (`Symbol.for('pyric.remote.sandboxFactory')`) and register the
- *     sandbox arm. One activation line is logged to stderr. If the env
- *     is set but no factory is installed, throw with remediation (run
- *     under `pyric dev`, or add `--import pyric-tools/register` to
- *     NODE_OPTIONS).
- *   - Production guard: refuses to route to a sandbox when
- *     `NODE_ENV === 'production'`, unless `PYRIC_SANDBOX_FORCE=1`.
- *
- * Ambient resolution happens ONLY on the bare call — any explicit
- * config (`{ sandbox }` or prod `AppOptions`, even `{}`) bypasses the
- * env entirely, so pyric-aware code keeps full control.
+ * Production selection happens before this module loads: activated Node
+ * processes resolve `firebase-admin/app` here, while inactive applications
+ * continue resolving their own `firebase-admin/app` package unchanged.
  */
 import { type Sandbox } from 'pyric/sandbox';
-import { type App as AdminApp, type AppOptions } from 'firebase-admin/app';
-/**
- * Brand on every PyricAdminApp. Matches the symbol used in
- * `pyric/app` so a future shared `pyric/runtime` package can
- * unify dispatch helpers across both packages.
- */
+/** Brand carried by every sandbox admin app. */
 export declare const ADMIN_APP_TARGET: unique symbol;
-export type PyricAdminAppTarget = 'sandbox' | 'prod';
-/** firebase-admin's default app name — `'[DEFAULT]'`. */
+export type PyricAdminAppTarget = 'sandbox';
+/** firebase-admin's default app name. */
 export declare const DEFAULT_APP_NAME = "[DEFAULT]";
 export interface SandboxAdminApp {
     readonly [ADMIN_APP_TARGET]: 'sandbox';
     readonly sandbox: Sandbox;
-    /** Registry name (mirrors firebase-admin `App.name`). */
-    readonly name: string;
-}
-export interface ProdAdminApp {
-    readonly [ADMIN_APP_TARGET]: 'prod';
-    readonly adminApp: AdminApp;
-    /** Registry name (mirrors firebase-admin `App.name`). */
     readonly name: string;
 }
-export type PyricAdminApp = SandboxAdminApp | ProdAdminApp;
+export type PyricAdminApp = SandboxAdminApp;
 export type InitializeAdminAppConfig = {
     sandbox: Sandbox;
-} | AppOptions;
+};
 /**
- * App-lifecycle errors reuse `firebase-admin`'s own exported
- * `FirebaseAppError` so the thrown error's class, `constructor.name`,
- * `.code` (`app/no-app`, `app/duplicate-app`, `app/invalid-app-options`,
- * `app/invalid-app-name`, `app/invalid-argument`), and message text match
- * production byte-for-byte (oracle: `admin-app-*` observations assert
- * `errorName: "FirebaseAppError"`). The published typings declare only the
- * base `Error` constructor, but the real runtime class is
- * `new FirebaseAppError(code, message)` where `code` becomes `app/<code>` —
- * the typed cast recovers it.
+ * Firebase Functions' ESM runtime statically imports this credential factory
+ * while linking its database provider. Pyric initializes the sandbox app
+ * before that provider executes, so the factory is not used by supported
+ * Functions flows. Keep the named export link-compatible, but fail clearly if
+ * application code asks the development sandbox for production credentials.
  */
-declare const AdminAppError: new (code: string, message: string) => Error & {
-    readonly code: string;
-};
-/** @deprecated Alias kept for pre-merge call sites; errors ARE `FirebaseAppError`. */
-export declare const PyricAdminAppError: new (code: string, message: string) => Error & {
-    readonly code: string;
-};
-export type PyricAdminAppError = InstanceType<typeof AdminAppError>;
+export declare function applicationDefault(): never;
 /**
- * Initialize a Pyric admin app and register it under `name`
- * (default `'[DEFAULT]'`), mirroring `firebase-admin/app.initializeApp`.
+ * Initialize a sandbox admin app.
  *
- * @example
- * ```ts
- * // Ambient (zero pyric identifiers — environment decides)
- * import { initializeApp } from 'pyric-admin/app';
- * const app = initializeApp();
- *
- * // Prod-backed
- * import { applicationDefault } from 'firebase-admin/app';
- * const app = initializeApp({ credential: applicationDefault() });
- *
- * // Sandbox-backed
- * import { initializeSandbox } from 'pyric/sandbox';
- * const app = initializeApp({ sandbox: initializeSandbox() });
- * ```
+ * An explicit `{ sandbox }` config binds an in-process or remote sandbox.
+ * A bare call resolves the remote sandbox factory installed by
+ * `@pyric/cli/register`. Production callers must import `firebase-admin/app`
+ * without Pyric activation instead of passing production options here.
  */
 export declare function initializeApp(config?: InitializeAdminAppConfig, name?: string): PyricAdminApp;
-/**
- * Return the registered app for `name` (default `'[DEFAULT]'`).
- * Mirrors `firebase-admin/app.getApp` — including the exact `app/no-app`
- * error text on a miss.
- */
+/** Return the registered app for `name`. */
 export declare function getApp(name?: string): PyricAdminApp;
-/**
- * A copy of the list of all registered apps.
- * Mirrors `firebase-admin/app.getApps`.
- */
+/** Return a copy of the app registry. */
 export declare function getApps(): PyricAdminApp[];
-/**
- * Remove `app` from the registry, mirroring `firebase-admin/app.deleteApp`.
- * Prod-backed apps also delete the underlying firebase-admin app (freeing
- * its resources and its slot in firebase-admin's own registry, so the
- * name can be re-initialized). Sandbox-backed apps only deregister — the
- * `Sandbox` handle's lifetime belongs to its creator.
- */
+/** Remove a sandbox app from the registry. */
 export declare function deleteApp(app: PyricAdminApp): Promise<void>;
 export declare function isSandboxAdminApp(app: PyricAdminApp): app is SandboxAdminApp;
-export declare function isProdAdminApp(app: PyricAdminApp): app is ProdAdminApp;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,GAAG,IAAI,QAAQ,EACpB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,eAAuC,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,YAAY,CAAC;AAE3D,MAAM,MAAM,wBAAwB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,QAAA,MAAM,aAAa,EAAkC,KACnD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,KACZ,KAAK,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,aALvB,MAAM,WACH,MAAM,KACZ,KAAK,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAGW,CAAC;AAChD,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC;AA8BpE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,CAAC,EAAE,wBAAwB,EACjC,IAAI,GAAE,MAAyB,GAC9B,aAAa,CA8Df;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,GAAE,MAAyB,GAAG,aAAa,CAcrE;AAED;;;GAGG;AACH,wBAAgB,OAAO,IAAI,aAAa,EAAE,CAEzC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3D;AA0FD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,eAAe,CAE5E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,YAAY,CAEtE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,eAAe,CAAC;AAGvB,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,eAAuC,CAAC;AACrE,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE5C,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAC5C,MAAM,MAAM,wBAAwB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,KAAK,CAK1C;AA4CD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,CAAC,EAAE,wBAAwB,EACjC,IAAI,GAAE,MAAyB,GAC9B,aAAa,CAqCf;AAED,4CAA4C;AAC5C,wBAAgB,MAAM,CAAC,IAAI,GAAE,MAAyB,GAAG,aAAa,CAarE;AAED,yCAAyC;AACzC,wBAAgB,OAAO,IAAI,aAAa,EAAE,CAEzC;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3D;AAgED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,eAAe,CAE5E"}