pyric-admin 0.1.0-alpha.10

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

@@ -0,0 +1,180 @@
+<p align="center">
+  <img src="https://pyric.dev/pyric-logo.svg" alt="Pyric" width="180" />
+</p>
+
+<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,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

@@ -0,0 +1,47 @@
+/**
+ * `pyric-admin/app` — sandbox-only admin app registry.
+ *
+ * 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';
+/** Brand carried by every sandbox admin app. */
+export declare const ADMIN_APP_TARGET: unique symbol;
+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;
+    readonly name: string;
+}
+export type PyricAdminApp = SandboxAdminApp;
+export type InitializeAdminAppConfig = {
+    sandbox: Sandbox;
+};
+/**
+ * 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.
+ */
+export declare function applicationDefault(): never;
+/**
+ * Initialize a sandbox admin app.
+ *
+ * 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`. */
+export declare function getApp(name?: string): PyricAdminApp;
+/** Return a copy of the app registry. */
+export declare function getApps(): PyricAdminApp[];
+/** Remove a sandbox app from the registry. */
+export declare function deleteApp(app: PyricAdminApp): Promise<void>;
+export declare function isSandboxAdminApp(app: PyricAdminApp): app is SandboxAdminApp;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/app/index.js

@@ -0,0 +1,164 @@
+/**
+ * `pyric-admin/app` — sandbox-only admin app registry.
+ *
+ * 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 { REMOTE_SANDBOX_FACTORY, } from 'pyric/sandbox';
+import { assertAdminAppActive, markAdminAppDeleted } from './lifecycle.js';
+/** Brand carried by every sandbox admin app. */
+export const ADMIN_APP_TARGET = Symbol.for('pyric.admin.app.target');
+/** firebase-admin's default app name. */
+export const DEFAULT_APP_NAME = '[DEFAULT]';
+/**
+ * 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.
+ */
+export function applicationDefault() {
+    throw new Error('pyric-admin/app: applicationDefault() is unavailable in the sandbox. ' +
+        'Pyric development does not use production credentials.');
+}
+/** Local error with the observable firebase-admin app-error shape. */
+class FirebaseAppError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'FirebaseAppError';
+        this.code = `app/${code}`;
+    }
+}
+// Node may evaluate this ESM-only mirror through distinct require(esm) and
+// import module records when the register hook rewrites both CJS and ESM
+// Firebase consumers. Firebase Admin's app registry is process-wide, so keep
+// the mirror registry behind Symbol.for as well: both module records must see
+// the same default app and sandbox handle.
+const APP_REGISTRY = Symbol.for('pyric.admin.app.registry');
+const AMBIENT_APPS = Symbol.for('pyric.admin.app.ambientApps');
+const globalRegistry = globalThis;
+const appRegistry = globalRegistry[APP_REGISTRY] ??= new Map();
+const ambientApps = globalRegistry[AMBIENT_APPS] ??= new WeakSet();
+function validateAppName(name) {
+    if (typeof name !== 'string' || name === '') {
+        throw new FirebaseAppError('invalid-app-name', `Invalid Firebase app name "${String(name)}" provided. App name must be a non-empty string.`);
+    }
+}
+function alreadyExists(name, code) {
+    return new FirebaseAppError(code, `A Firebase app named "${name}" already exists with a different configuration.`);
+}
+/**
+ * Initialize a sandbox admin app.
+ *
+ * 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 function initializeApp(config, name = DEFAULT_APP_NAME) {
+    validateAppName(name);
+    const existing = appRegistry.get(name);
+    if (config === undefined) {
+        if (existing !== undefined) {
+            if (ambientApps.has(existing))
+                return existing;
+            throw alreadyExists(name, 'invalid-app-options');
+        }
+        const app = initializeAmbientApp(name);
+        appRegistry.set(name, app);
+        ambientApps.add(app);
+        return app;
+    }
+    if (!isSandboxConfig(config)) {
+        throw new TypeError('pyric-admin/app is a sandbox-only mirror. Production applications must ' +
+            'load firebase-admin/app without Pyric activation.');
+    }
+    if (existing !== undefined) {
+        if (!ambientApps.has(existing) && existing.sandbox === config.sandbox)
+            return existing;
+        throw alreadyExists(name, ambientApps.has(existing) ? 'invalid-app-options' : 'duplicate-app');
+    }
+    const app = {
+        [ADMIN_APP_TARGET]: 'sandbox',
+        sandbox: config.sandbox,
+        name,
+    };
+    appRegistry.set(name, app);
+    return app;
+}
+/** Return the registered app for `name`. */
+export function getApp(name = DEFAULT_APP_NAME) {
+    validateAppName(name);
+    const app = appRegistry.get(name);
+    if (app === undefined) {
+        const lead = name === DEFAULT_APP_NAME
+            ? 'The default Firebase app does not exist. '
+            : `Firebase app named "${name}" does not exist. `;
+        throw new FirebaseAppError('no-app', lead + 'Make sure you call initializeApp() before using any of the Firebase services.');
+    }
+    return app;
+}
+/** Return a copy of the app registry. */
+export function getApps() {
+    return Array.from(appRegistry.values());
+}
+/** Remove a sandbox app from the registry. */
+export function deleteApp(app) {
+    if (typeof app !== 'object' || app === null || !(ADMIN_APP_TARGET in app)) {
+        throw new FirebaseAppError('invalid-argument', 'Invalid app argument.');
+    }
+    assertAdminAppActive(app);
+    const existing = getApp(app.name);
+    appRegistry.delete(existing.name);
+    markAdminAppDeleted(existing);
+    return Promise.resolve();
+}
+function initializeAmbientApp(name) {
+    const env = process.env.PYRIC_SANDBOX;
+    if (env === undefined || env.trim() === '') {
+        throw new Error('pyric-admin/app is a sandbox-only mirror and no sandbox is active. ' +
+            'Run under `pyric dev`, set PYRIC_SANDBOX with @pyric/cli/register, ' +
+            'or load firebase-admin/app without Pyric activation for production.');
+    }
+    const opts = parsePyricSandboxEnv(env);
+    if (process.env.NODE_ENV === 'production' && process.env.PYRIC_SANDBOX_FORCE !== '1') {
+        throw new Error('pyric-admin: PYRIC_SANDBOX is set but NODE_ENV is "production" — ' +
+            'refusing to route firebase-admin to a development sandbox. ' +
+            'Unset PYRIC_SANDBOX in production, or set PYRIC_SANDBOX_FORCE=1 ' +
+            'if this routing is intentional.');
+    }
+    const factory = globalThis[REMOTE_SANDBOX_FACTORY];
+    if (typeof factory !== 'function') {
+        throw new Error(`pyric-admin: PYRIC_SANDBOX=${env} is set but no remote sandbox ` +
+            "factory is installed (globalThis[Symbol.for('pyric.remote.sandboxFactory')] is absent). " +
+            'Run your server under `pyric dev`, or add `--import @pyric/cli/register` to NODE_OPTIONS.');
+    }
+    const sandbox = factory(opts);
+    process.stderr.write(`pyric: firebase-admin routed to sandbox${opts.url !== undefined ? ` at ${opts.url}` : ''}\n`);
+    return { [ADMIN_APP_TARGET]: 'sandbox', sandbox, name };
+}
+function parsePyricSandboxEnv(env) {
+    const value = env.trim();
+    if (value === 'remote')
+        return {};
+    if (value.startsWith('remote:')) {
+        const url = value.slice('remote:'.length).trim();
+        if (url === '') {
+            throw new Error('pyric-admin: PYRIC_SANDBOX=remote: has an empty url. Use ' +
+                'PYRIC_SANDBOX=remote to auto-discover the running `pyric dev`, ' +
+                'or PYRIC_SANDBOX=remote:<url> with the host url.');
+        }
+        return { url };
+    }
+    throw new Error(`pyric-admin: unrecognized PYRIC_SANDBOX value "${env}". Supported ` +
+        'values: "remote" (auto-discover the running `pyric dev`) or "remote:<url>".');
+}
+function isSandboxConfig(config) {
+    return typeof config === 'object' && config !== null && 'sandbox' in config;
+}
+export function isSandboxAdminApp(app) {
+    return app[ADMIN_APP_TARGET] === 'sandbox';
+}
+//# sourceMappingURL=index.js.map