pyric 0.0.1 → 0.1.0-alpha.7

package/dist/sandbox/index.js

@@ -0,0 +1,63 @@
+/**
+ * `pyric/sandbox` — sandbox host (foundation). Provides the
+ * `Sandbox` type, the `SandboxContext` identity handle, the
+ * `initializeSandbox` factory, and the `SandboxError` family.
+ *
+ * Service handles live in sibling packages (`pyric-admin` for the
+ * Admin-SDK-shaped chainable Firestore adapter, future
+ * `pyric/firestore` for the modular Web SDK adapter,
+ * `pyric/auth`/`pyric/database`/`pyric/storage` later) and consume
+ * `SandboxContext` from here.
+ *
+ * Adapter packages also reach into `pyric/sandbox/internal` for the
+ * non-public protocol (`getInternalEnv`, etc.). See
+ * the design rationale and
+ * the design rationale for the design rationale.
+ */
+import { SandboxImpl } from './internal/sandbox-impl.js';
+export { SandboxError } from './types.js';
+export { SandboxContextImpl } from './sandbox-context.js';
+// Remote sandbox (slice 1) — the brand + minimal channel contract that
+// lets `pyric-admin` recognize a Node-side handle onto the browser-hosted
+// worker sandbox (constructed by `pyric-tools`' `connectRemoteSandbox`)
+// and route its RTDB/Auth ops over the wire instead of into local state.
+export { REMOTE_SANDBOX, REMOTE_SANDBOX_FACTORY, isRemoteSandbox } from './remote.js';
+// Replay engine — capture a session via `sandbox.history()` and re-
+// issue every write against a fresh sandbox. See
+// `docs/how-to/replay-events.md`.
+export { replay } from './replay/index.js';
+// Branches — fork/apply/diff/promote/discard experiments built on top of
+// `snapshot()` + `replay()`. A branch is an isolated in-memory sandbox
+// seeded from a `SandboxSnapshot`; `apply` re-issues events via `replay`,
+// `diff` is a focused doc-level structural diff (reuses `Divergence`),
+// `promote` lands the branch's mutations on a target, `discard` drops it.
+// Substrate for Studio's agent dry-run/accept, rules-edit branches, and
+// time-travel. See the design rationale.
+export { apply, discard, diff, fork, promote } from './branches/index.js';
+export { attachPersistence, createIndexedDBBackend, createMemoryBackend, recordBackendOverBlob, serializeToBuckets, deserializeFromBuckets, bundleRecords, parseBundle, PersistenceSchemaError, rehydrateDocValue, } from './persistence/index.js';
+export { attachTabSync } from './tab-sync/index.js';
+/**
+ * Create a sandbox.
+ *
+ * Identity is **not** part of init — call `sandbox.withAuth(...)` to
+ * derive a {@link SandboxContext} for service operations. Service-
+ * specific configuration (rules, seed data) happens through service
+ * handles — for example, `getFirestore(ctx).setRules(...)`.
+ *
+ * @example
+ * ```ts
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getFirestore } from 'pyric-admin/firestore';
+ *
+ * const sandbox = initializeSandbox();
+ * const dbAlice = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+ * const dbAnon  = getFirestore(sandbox.withAuth(null));
+ * ```
+ */
+export function initializeSandbox(_config = {}) {
+    // `_config` is reserved for future service-agnostic options
+    // (rules/documents bundled at init when the multi-service
+    // architecture lands). Empty for now.
+    return SandboxImpl.createRoot();
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AA+BzD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,uEAAuE;AACvE,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAQtF,oEAAoE;AACpE,iDAAiD;AACjD,kCAAkC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,yEAAyE;AACzE,uEAAuE;AACvE,0EAA0E;AAC1E,uEAAuE;AACvE,0EAA0E;AAC1E,wEAAwE;AACxE,yCAAyC;AACzC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAY1E,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAyB,EAAE;IAC3D,4DAA4D;IAC5D,0DAA0D;IAC1D,sCAAsC;IACtC,OAAO,WAAW,CAAC,UAAU,EAAE,CAAC;AAClC,CAAC"}

package/dist/sandbox/internal/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `pyric/sandbox/internal` — adapter-only protocol surface.
+ *
+ * Service adapter packages (`pyric-admin`, future `pyric/firestore`,
+ * `pyric/auth`, etc.) consume this subpath to reach the underlying
+ * `LocalEnvironment` and any other primitives that need to flow
+ * through the sandbox boundary.
+ *
+ * **Not part of the public API.** The shape is subject to change
+ * without breaking-change semantics across `pyric/sandbox` versions.
+ * External adapter authors shouldn't rely on this — when the protocol
+ * stabilizes (post-multi-service architecture) it'll be promoted.
+ *
+ * Documented in the design rationale section "Migration
+ * scope summary".
+ */
+export { getInternalEnv } from './sandbox-impl.js';
+export { emitSandboxEvent, primeEventHistory, stampProvenance, makeSandboxCommitEvent, makeSandboxListenerEvent, makeSandboxOperationEvent, makeSandboxRuntimeErrorEvent, makeServiceMutationEvent, } from './sandbox-impl.js';
+export * from '../firestore/local-environment.js';
+export { LocalState, type BatchOperation, type BatchResult as LocalStateBatchResult, type CreateResult, type UpdateResult, type SetResult, type DeleteResult, } from '../firestore/local-state.js';
+export * from '../firestore/event-log.js';
+export * from '../firestore/auto-id.js';
+export * from '../firestore/transaction.js';
+export * from '../firestore/transaction-merge.js';
+export * from '../firestore/transaction-types.js';
+export * from '../firestore/errors.js';
+export * from '../firestore/value-resolver.js';
+export * from '../firestore/converters/timestamp.js';
+export * from '../firestore/converters/user-timestamp.js';
+export * from '../firestore/converters/reference.js';
+export * from '../firestore/converters/vector.js';
+export * from '../firestore/converters/fieldvalue.js';
+export * from '../firestore/converters/bytes-geopoint.js';
+export * from '../firestore/snapshot-listeners.js';
+export * from '../firestore/wire-encoder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/internal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/internal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUnD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAiB3B,cAAc,mCAAmC,CAAC;AAClD,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,WAAW,IAAI,qBAAqB,EACzC,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,YAAY,GAClB,MAAM,6BAA6B,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,oCAAoC,CAAC;AAKnD,cAAc,8BAA8B,CAAC"}

package/dist/sandbox/internal/index.js

@@ -0,0 +1,72 @@
+/**
+ * `pyric/sandbox/internal` — adapter-only protocol surface.
+ *
+ * Service adapter packages (`pyric-admin`, future `pyric/firestore`,
+ * `pyric/auth`, etc.) consume this subpath to reach the underlying
+ * `LocalEnvironment` and any other primitives that need to flow
+ * through the sandbox boundary.
+ *
+ * **Not part of the public API.** The shape is subject to change
+ * without breaking-change semantics across `pyric/sandbox` versions.
+ * External adapter authors shouldn't rely on this — when the protocol
+ * stabilizes (post-multi-service architecture) it'll be promoted.
+ *
+ * Documented in the design rationale section "Migration
+ * scope summary".
+ */
+export { getInternalEnv } from './sandbox-impl.js';
+// Pyric Studio event-unification seam: the provenance-stamping emit
+// choke-point non-Firestore services (auth/storage/rtdb) call to land
+// activity on the unified `onEvent`/`history()` stream. Firestore rides
+// the env→sandbox fan-out and doesn't need this. `stampProvenance` is
+// exported for callers that need to compute the stamped shape without
+// dispatching (e.g. branch/replay tooling). See the design rationale.
+// `makeServiceMutationEvent` builds the generic cross-service mutation
+// envelope (id/at minted from the shared counter) auth/storage/rtdb emit.
+export { emitSandboxEvent, primeEventHistory, stampProvenance, makeSandboxCommitEvent, makeSandboxListenerEvent, makeSandboxOperationEvent, makeSandboxRuntimeErrorEvent, makeServiceMutationEvent, } from './sandbox-impl.js';
+// LocalEnvironment + its closest siblings moved here in Slice 7.
+// Surfacing them through the /internal sub-path keeps the public
+// surface narrow (consumers compose via `getFirestore(ctx)`, not by
+// constructing LocalEnvironment directly) while letting adapter
+// packages reach the runtime.
+//
+// Star re-exports because admin-compat (in sdk) reaches in for a
+// long tail of helper symbols (DELETE_MARKER, KEEP,
+// FIRESTORE_ERROR_CODES, etc.). Anyone changing the moved files'
+// public exports automatically gets them propagated here.
+// local-environment exports BatchResult as its own outer shape;
+// local-state has a different (internal) BatchResult — alias the
+// local-state one to disambiguate. Same trick for DocumentData
+// (one canonical export from local-state; local-environment
+// re-exports it).
+export * from '../firestore/local-environment.js';
+export { LocalState, } from '../firestore/local-state.js';
+export * from '../firestore/event-log.js';
+export * from '../firestore/auto-id.js';
+export * from '../firestore/transaction.js';
+export * from '../firestore/transaction-merge.js';
+export * from '../firestore/transaction-types.js';
+export * from '../firestore/errors.js';
+export * from '../firestore/value-resolver.js';
+export * from '../firestore/converters/timestamp.js';
+export * from '../firestore/converters/user-timestamp.js';
+export * from '../firestore/converters/reference.js';
+export * from '../firestore/converters/vector.js';
+export * from '../firestore/converters/fieldvalue.js';
+export * from '../firestore/converters/bytes-geopoint.js';
+export * from '../firestore/snapshot-listeners.js';
+// Wire-encoder: produces Firestore JSON wire-format from sandbox
+// values. Used by the discover crawler's sandbox adapter (in
+// pyric/firestore/discover) to bridge LocalEnvironment ↔ the wire
+// decoder.
+export * from '../firestore/wire-encoder.js';
+// Pre-mortem H3 — the star re-exports above are NOT auditable by
+// reading this file. If two of the re-exported modules introduce a
+// same-named symbol, `tsc --noEmit` fails loudly at build time (this
+// has happened: BatchResult / DocumentData collisions, both
+// disambiguated above). When adding a new symbol to any of the
+// listed modules, check for collisions against the other modules in
+// this list first. Future-us should consider replacing the stars
+// with explicit named re-exports once the admin-compat layer's
+// surface stops drifting.
+//# sourceMappingURL=index.js.map

package/dist/sandbox/internal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sandbox/internal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,oEAAoE;AACpE,sEAAsE;AACtE,wEAAwE;AACxE,sEAAsE;AACtE,sEAAsE;AACtE,sEAAsE;AACtE,uEAAuE;AACvE,0EAA0E;AAC1E,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,iEAAiE;AACjE,iEAAiE;AACjE,oEAAoE;AACpE,gEAAgE;AAChE,8BAA8B;AAC9B,EAAE;AACF,iEAAiE;AACjE,oDAAoD;AACpD,iEAAiE;AACjE,0DAA0D;AAC1D,gEAAgE;AAChE,iEAAiE;AACjE,+DAA+D;AAC/D,4DAA4D;AAC5D,kBAAkB;AAClB,cAAc,mCAAmC,CAAC;AAClD,OAAO,EACL,UAAU,GAOX,MAAM,6BAA6B,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,oCAAoC,CAAC;AACnD,iEAAiE;AACjE,6DAA6D;AAC7D,kEAAkE;AAClE,WAAW;AACX,cAAc,8BAA8B,CAAC;AAE7C,iEAAiE;AACjE,mEAAmE;AACnE,qEAAqE;AACrE,4DAA4D;AAC5D,+DAA+D;AAC/D,oEAAoE;AACpE,iEAAiE;AACjE,+DAA+D;AAC/D,0BAA0B"}

package/dist/sandbox/internal/sandbox-impl.d.ts

@@ -0,0 +1,343 @@
+/**
+ * Internal `Sandbox` implementation — backs the public interface from
+ * `/app` and exposes the hook (`getEnv`) that other in-package modules
+ * (notably `/firestore`) need to reach the underlying
+ * `LocalEnvironment`.
+ *
+ * Not in the package's `exports` map — external consumers can't import
+ * this module. Internal modules can because workspace path resolution
+ * doesn't go through the exports gate.
+ *
+ * Why a class plus a private accessor: `/app` keeps its dependency
+ * direction clean by exposing only the `Sandbox` interface. Service
+ * modules need `LocalEnvironment` access but should not couple to
+ * `/app`'s implementation; they read it through {@link getEnv}.
+ *
+ * The class is identity-agnostic per the multi-context redesign — it
+ * holds the env, listener registries, and lifecycle. Identity belongs
+ * to {@link SandboxContext}, derived via `withAuth`.
+ */
+import { LocalEnvironment } from '../firestore/local-environment.js';
+import type { AuthState, EventProvenance, PersistableService, Sandbox, SandboxAdmin, SandboxContext, SandboxCommitEvent, SandboxEvent, SandboxListenerEvent, SandboxOperationEvent, SandboxRuntimeErrorEvent, SandboxSnapshot, ServiceMutationEvent } from '../types.js';
+import type { SandboxPersistenceOptions } from '../persistence/types.js';
+import type { TabSyncOptions } from '../tab-sync/index.js';
+/**
+ * Stamp {@link EventProvenance} onto a `SandboxEvent` in ONE place — the
+ * single choke-point every emitter routes through (see {@link
+ * SandboxImpl.emitEvent}). This is the Pyric Studio "event unification"
+ * keystone: today only Firestore emits, but every service's emit path is
+ * meant to funnel here so the unified `onEvent`/`history()` stream carries
+ * who/what/which-service for each event.
+ *
+ * Semantics — **additive, override-aware, no clobber**:
+ *   - `service`   defaults to `'firestore'` (the only emitter today). An
+ *                 Auth/Storage/RTDB emit site passes its own service via
+ *                 `overrides.service`; a value already on the event is kept.
+ *   - `actor`     defaults to `{ kind: 'app' }` (the served app). Studio /
+ *                 agent / app-builder emitters override.
+ *   - `authLens`  defaults to `{ mode: 'app-session' }` (the app's own
+ *                 signed-in user). Admin / impersonation paths override.
+ *   - `planId`    only set when an override supplies it (agent-plan ops).
+ *
+ * A field the event ALREADY carries always wins over the default — so an
+ * upstream emitter that pre-stamped provenance is never downgraded. The
+ * returned object is a shallow copy; the input is not mutated.
+ */
+export declare function stampProvenance<E extends SandboxEvent>(event: E, overrides?: EventProvenance): E;
+/**
+ * Concrete `Sandbox`. Holds the live `LocalEnvironment` directly and
+ * swaps it on `reset()`. Existing `SandboxContext`s continue to work
+ * after reset because they hold a reference to *this* sandbox object,
+ * not to a particular env — the next operation calls back through
+ * `getEnv()` and gets whatever env is current.
+ *
+ * Subscriber registries (`onDenial` / `onSnapshotError` / `onRequest`)
+ * live on the sandbox, NOT on `LocalEnvironment`. `reset()` swaps the
+ * env without invalidating user callbacks — see #307 probe (E7) for
+ * the bug that motivated this layout. The sandbox installs ONE adapter
+ * subscription per channel on the current env that fans out to the
+ * user registry; on swap, the adapter subscriptions get re-attached
+ * to the new env while user callbacks stay put.
+ */
+export declare class SandboxImpl implements Sandbox {
+    private _env;
+    /** User callbacks; stable across `reset()`. */
+    private eventSubs;
+    /** Adapter unsubscribers for the current env; refreshed on reset. */
+    private envUnsubs;
+    /** Monotonic — surfaced on session_boundary events so consumers can
+     *  segment a persisted stream. Increments on every dispatched event. */
+    private dispatchedCount;
+    /** Append-only history of every SandboxEvent emitted on this sandbox.
+     *  Cleared on `reset()` AFTER the session_boundary event is appended,
+     *  so the boundary is the last entry of the old session's history.
+     *  v1 doesn't cap; consumers persist the snapshot they need. */
+    private eventHistory;
+    /** Ambient provenance for the current {@link runWithProvenance} window
+     *  (undefined outside any window). Purely synchronous — set on entry,
+     *  restored in `finally` — so deferred work (microtask listener drains)
+     *  never observes a window it didn't open. */
+    private ambientProvenance;
+    /**
+     * Currently authenticated user. Mutated by `pyric/auth` (and any
+     * future stateful identity bridge). Read per-call by service
+     * factories that want to see auth changes without re-binding.
+     * Defaults to `null` (anonymous / signed out).
+     */
+    private _currentUser;
+    /** Subscribers to currentUser changes. Stable across reset() and
+     *  dispose() the same way `eventSubs` is — dispose clears them. */
+    private currentUserSubs;
+    /** Persistence controller. Null until `enablePersistence` is called.
+     *  Survives `reset()` so the next write re-flushes the empty state;
+     *  cleared by `dispose()` so the sandbox releases its event listeners. */
+    private persistence;
+    /** In-flight `enablePersistence` call. Awaiting this lets concurrent
+     *  enable calls share the same attach work (and same restored state)
+     *  rather than racing two restores. */
+    private enablePersistencePromise;
+    /**
+     * Persistable-service registry. Each entry is one service (auth,
+     * storage, …) that contributes its own state to the sandbox snapshot.
+     * The sandbox stays service-agnostic: it just calls `snapshot()` /
+     * `restore()` and defers the shape entirely to each service.
+     *
+     * Cleared in `dispose()`. The controller is notified via
+     * `_onServiceRegistered` whenever a new entry arrives so it can
+     * subscribe the service's change notifications without requiring the
+     * service to register BEFORE `enablePersistence` is called.
+     */
+    private serviceRegistry;
+    /**
+     * Optional callback set by the persistence controller so it learns
+     * about services registered AFTER `enablePersistence`. Supports the
+     * late-registration case: `enablePersistence` then later `getAuth()`
+     * (which registers 'auth'). The controller wires up the subscribe
+     * hook and schedules a flush.
+     *
+     * Only one controller at a time (enforced by `enablePersistence`),
+     * so a single slot is sufficient.
+     */
+    private _onServiceRegistered;
+    private constructor();
+    /** Factory used by `initializeSandbox`. */
+    static createRoot(): SandboxImpl;
+    /**
+     * Resolve the live `LocalEnvironment`. Stable across resets — the
+     * sandbox holds whatever env is current, and consumers of `getEnv`
+     * always see the latest one.
+     */
+    getEnv(): LocalEnvironment;
+    withAuth(auth: AuthState): SandboxContext;
+    /**
+     * Install one adapter subscription per env-level channel. Each adapter
+     * translates the env's payload into a `SandboxEvent` and dispatches
+     * through {@link emit}. Refreshed on `reset()` after the env swap.
+     */
+    private attachToEnv;
+    /**
+     * THE unified emit choke-point. Every SandboxEvent — from any service —
+     * flows through here so provenance is stamped in exactly one place
+     * ({@link stampProvenance}) and the event lands on the single
+     * `onEvent`/`history()` stream.
+     *
+     * `provenance` lets a non-default emitter (a future Auth/Storage/RTDB
+     * emit site, or a Studio admin/agent/impersonation path) declare its
+     * `service`/`actor`/`authLens`/`planId`. Omitted ⇒ Firestore / app /
+     * app-session defaults, which is exactly today's Firestore behaviour —
+     * so routing the existing Firestore emitters through here is a no-op on
+     * what consumers observe beyond the additive provenance fields.
+     */
+    emitEvent(event: SandboxEvent, provenance?: EventProvenance): void;
+    /**
+     * See `Sandbox.runWithProvenance` (types.ts) for the contract: ambient
+     * provenance defaults for events emitted synchronously during `fn`.
+     * Nested windows merge (innermost wins per field) and restore on exit.
+     */
+    runWithProvenance<T>(provenance: EventProvenance, fn: () => T): T;
+    /**
+     * Dispatch a (already-stamped) SandboxEvent to all user subscribers.
+     * Synchronous, with sync-throw + async-rejection isolation so a faulty
+     * subscriber can't destabilize the sandbox or crash the process via
+     * unhandledRejection. All callers go through {@link emitEvent}; this is
+     * the raw fan-out + history append it wraps.
+     */
+    private dispatch;
+    /**
+     * Internal entry point for sandbox-level event sources (snapshot
+     * deliveries / lifecycle / session_boundary) that don't have an
+     * env-level channel to ride on. Exposed only to the same package via
+     * {@link emitSandboxEvent}. Stamps provenance like every other emit.
+     */
+    emitInternal(event: SandboxEvent, provenance?: EventProvenance): void;
+    /**
+     * Subscribe to every event the sandbox emits. Survives `reset()`.
+     */
+    onEvent(cb: (event: SandboxEvent) => void): () => void;
+    /**
+     * Every SandboxEvent emitted on this sandbox since init (or since
+     * the last `reset()`). Returns a defensive copy — mutating the
+     * returned array doesn't affect future history() calls.
+     *
+     * Replay engine consumes this: hand the array to
+     * `replay(events, rules)` from `pyric/sandbox` and the
+     * engine re-issues every captured write against a fresh sandbox.
+     *
+     * `reset()` clears the history AFTER emitting the closing
+     * session_boundary event, so the last entry of a pre-reset history
+     * is always `{ kind: 'session_boundary', phase: 'reset' }`. Likewise
+     * `dispose()` leaves the boundary as the final entry.
+     */
+    history(): SandboxEvent[];
+    /**
+     * Prime the event-history log with events from a PRIOR session of the
+     * SAME origin (the served `.pyric/last-session.json` capture), for display
+     * continuity after a SharedWorker death — Traffic / activity / metrics read
+     * `history()` (and history-first `onEvent` batches), so a fresh worker would
+     * otherwise show an empty feed even though the data restored from IDB.
+     *
+     * This is history-priming ONLY:
+     *  - events are APPENDED to `eventHistory` so `history()` and any consumer
+     *    that subscribes AFTER boot (Studio's history-first batch) sees them;
+     *  - they are NOT dispatched to live `onEvent` subscribers (no re-emission);
+     *  - no operation is re-executed — the underlying data is restored
+     *    separately from persistence, these events are the record of it;
+     *  - `dispatchedCount` is untouched (it counts THIS session's live
+     *    dispatches, which drive session_boundary's priorOpCount).
+     *
+     * No-op unless history is empty, so a warm sandbox (live events already
+     * accumulated during boot) is never disturbed and primed events can never
+     * interleave after live ones. Returns the number of events primed.
+     */
+    primeEventHistory(events: readonly SandboxEvent[]): number;
+    /**
+     * Admin-plane access. Identity-agnostic: admin reads aren't gated on
+     * auth, so they're a sandbox property — not something contexts carry.
+     */
+    get admin(): SandboxAdmin;
+    reset(): void;
+    dispose(): void;
+    snapshot(): SandboxSnapshot;
+    loadSnapshot(data: SandboxSnapshot): void;
+    /**
+     * Current authenticated user across the sandbox. See the doc on
+     * {@link Sandbox.currentUser} — used by `pyric/auth` to thread
+     * identity through stateful Auth handles.
+     */
+    get currentUser(): AuthState;
+    set currentUser(user: AuthState);
+    onCurrentUserChanged(cb: (user: AuthState) => void): () => void;
+    private notifyCurrentUserSubs;
+    /**
+     * Wire a persistence controller into this sandbox. Restores any
+     * prior snapshot before resolving so the in-memory state matches
+     * the backend by the time the caller's await returns.
+     *
+     * Concurrent calls share the same in-flight attach; the second
+     * caller sees the same restored state without a duplicate restore
+     * pass. Repeat calls after the first resolves are accepted only when
+     * the `key` matches — different keys would mean re-pointing the
+     * sandbox at a new backend mid-flight, which is conceptually muddled
+     * and rejected.
+     */
+    enablePersistence(options: SandboxPersistenceOptions): Promise<void>;
+    /**
+     * Enable cross-tab realtime sync. Delegates to `attachTabSync` which
+     * wires the `BroadcastChannel` + `onEvent` subscription. Returns the
+     * disable function from `attachTabSync` so the caller can tear down
+     * sync without knowing the internals. Mirrors the pattern used by
+     * `enablePersistence` → `attachPersistence`.
+     */
+    enableTabSync(options?: TabSyncOptions): () => void;
+    flush(): Promise<void>;
+    clearPersistence(): Promise<void>;
+    registerPersistableService(name: string, hooks: PersistableService): () => void;
+    /**
+     * Internal hook for the persistence controller: called once at attach
+     * time so the controller can be notified when a service registers
+     * AFTER `enablePersistence`. Only one controller can be active at a
+     * time, so a single callback slot is sufficient.
+     *
+     * Pass `null` to detach (called by the controller's `dispose()`).
+     */
+    setServiceRegistrationHook(cb: ((name: string, hooks: PersistableService) => void) | null): void;
+    /**
+     * Internal: iterate the current service registry. Used by the
+     * persistence controller's restore path to apply each service's
+     * saved state from the blob.
+     */
+    getServiceRegistry(): ReadonlyMap<string, PersistableService>;
+}
+/**
+ * Internal helper for service modules: given a `Sandbox` (or a
+ * `SandboxContext`'s underlying sandbox), return its `LocalEnvironment`.
+ * Throws if the handle isn't a `SandboxImpl` (i.e. somebody hand-rolled
+ * one) — custom Sandbox implementations are not supported.
+ */
+export declare function getInternalEnv(sandbox: Sandbox): LocalEnvironment;
+/**
+ * Prime a sandbox's `history()` log with events from a prior session of the
+ * same origin (the served capture file), WITHOUT dispatching them to live
+ * `onEvent` subscribers or re-executing any op. History-priming seam for the
+ * served worker's boot-time event hydration — see
+ * {@link SandboxImpl.primeEventHistory}. No-op unless history is empty.
+ * Returns the number of events primed.
+ *
+ * Throws if `sandbox` wasn't produced by `initializeSandbox()` (same guard
+ * as {@link getInternalEnv}).
+ */
+export declare function primeEventHistory(sandbox: Sandbox, events: readonly SandboxEvent[]): number;
+/**
+ * Emit a `SandboxEvent` onto a sandbox's unified `onEvent`/`history()`
+ * stream, stamping {@link EventProvenance} through the single
+ * {@link SandboxImpl.emitEvent} choke-point.
+ *
+ * **This is the seam the Pyric Studio event-unification keystone reserves
+ * for non-Firestore services.** Firestore already emits via the env→sandbox
+ * fan-out in {@link SandboxImpl.attachToEnv} (no caller needs this for it).
+ * Auth / Storage / RTDB are meant to call this from their own emit sites so
+ * their activity lands on the same stream — e.g.
+ *   `emitSandboxEvent(sandbox, userCreatedEvent, { service: 'auth' })`.
+ *
+ * STATUS (Wave 1.5, Gap #1): Auth / Storage / RTDB now emit here. They share
+ * one additive union variant — {@link ServiceMutationEvent} (`kind:
+ * 'service_mutation'`) — built via {@link makeServiceMutationEvent}, rather
+ * than bending into Firestore's rule-eval-shaped `request`/`write` kinds.
+ * Wired emit sites:
+ *   - auth:    user create/update/delete, users-clear, sign-in, sign-out
+ *              (`SandboxBackend` in `pyric/auth`).
+ *   - storage: object put / delete / metadata-update (`pyric/storage`).
+ *   - rtdb:    set / update / remove / transaction-commit
+ *              (`RtdbBackend` in `pyric/database`, via the modular surface).
+ * Firestore still rides the env→sandbox fan-out and is unchanged. See
+ * the design rationale.
+ *
+ * Throws if `sandbox` wasn't produced by `initializeSandbox()` (same guard
+ * as {@link getInternalEnv}).
+ */
+export declare function emitSandboxEvent(sandbox: Sandbox, event: SandboxEvent, provenance?: EventProvenance): void;
+/**
+ * Build a {@link ServiceMutationEvent} with a fresh `id` + `at` minted from
+ * the same monotonic counter Firestore events use — so a non-Firestore
+ * service (auth/storage/rtdb) doesn't have to re-implement id minting or
+ * worry about colliding with the Firestore stream's ids.
+ *
+ * The returned event is NOT yet dispatched; hand it to
+ * {@link emitSandboxEvent} (which stamps provenance and lands it on the
+ * unified stream). The convenience seam for the keystone: a service emit
+ * site is `emitSandboxEvent(sandbox, makeServiceMutationEvent({ ... }), { service })`.
+ */
+export declare function makeServiceMutationEvent(fields: Omit<ServiceMutationEvent, 'kind' | 'id' | 'at'>): ServiceMutationEvent;
+export declare function makeSandboxOperationEvent(fields: Omit<SandboxOperationEvent, 'kind' | 'id' | 'at'> & {
+    at?: number;
+}): SandboxOperationEvent;
+export declare function makeSandboxCommitEvent(fields: Omit<SandboxCommitEvent, 'kind' | 'id' | 'at'> & {
+    at?: number;
+}): SandboxCommitEvent;
+export declare function makeSandboxListenerEvent(fields: Omit<SandboxListenerEvent, 'kind' | 'id' | 'at'> & {
+    at?: number;
+}): SandboxListenerEvent;
+export declare function makeSandboxRuntimeErrorEvent(fields: Omit<SandboxRuntimeErrorEvent, 'kind' | 'id' | 'at'> & {
+    at?: number;
+}): SandboxRuntimeErrorEvent;
+//# sourceMappingURL=sandbox-impl.d.ts.map

package/dist/sandbox/internal/sandbox-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-impl.d.ts","sourceRoot":"","sources":["../../../src/sandbox/internal/sandbox-impl.ts"],"names":[],"mappings":"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"}