pyric 0.0.1 → 0.1.0-alpha.7

package/dist/sandbox/firestore/local-environment.d.ts

@@ -0,0 +1,806 @@
+/**
+ * LocalEnvironment — stateful Firestore sandbox.
+ *
+ * Wraps LocalState + SimulateFirestoreRulesHandler + EventLog into a
+ * complete local development environment. Agents can seed data, deploy
+ * rules, execute operations, and undo — all without touching production.
+ */
+import { type DocumentData, type DocEntry, type ScanOptions } from './local-state.js';
+import { type AgentEvent } from './event-log.js';
+import { type LintResult } from 'pyric/rules';
+import { type QueryConstraints } from './list-query-proof.js';
+import { Timestamp } from 'pyric/rules';
+import { type FirestoreSimError } from './errors.js';
+import type { Transaction, TransactionOptions, TransactionResult } from './transaction-types.js';
+import type { ListenerAuth, SnapshotCallback, SnapshotErrorCallback, SnapshotListenerOptions, SnapshotTarget } from './snapshot-listeners.js';
+/**
+ * Thrown by `LocalEnvironment.execute` / `.batch` when the simulator
+ * abstained on a rule (state: UNSUPPORTED). The agent's rule may be
+ * correct — the simulator just doesn't implement the feature it uses.
+ *
+ * Returning `allowed: false` here would silently re-create the
+ * misleading-DENY pattern that Item 0.A is designed to prevent (the
+ * agent can't tell sim-gap apart from real rule bug). Throwing forces
+ * the test to fail loudly with an actionable message pointing at the
+ * production Test API as the workaround.
+ */
+export declare class SimulatorUnsupportedError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly debugMessages: string[];
+    constructor(message: string, method: string, path: string, debugMessages: string[]);
+}
+export interface Operation {
+    /**
+     * `'set'` is the replace-semantics single-write counterpart of the
+     * batch `'set'` op: storage replaces, rule eval translates to
+     * `'create'` (doc absent) or `'update'` (doc exists). Use it for
+     * `DocumentReference.set(data)` without merge options.
+     */
+    method: 'get' | 'list' | 'create' | 'update' | 'set' | 'delete';
+    path: string;
+    auth: {
+        uid: string;
+        token?: Record<string, unknown>;
+    } | null;
+    data?: DocumentData;
+    /** Signals that this `create`'s path-last-segment was minted by
+     *  `LocalEnvironment.createWithAutoId` (not user-supplied). The
+     *  replay engine reads `WriteSandboxEvent.autoId` and mints a fresh
+     *  ID on replay rather than preserving the original. Only meaningful
+     *  on `method: 'create'`; ignored otherwise. */
+    autoId?: boolean;
+    /** Pin the server-time the rule engine sees for this op (replaces
+     *  `Timestamp.fromMillis(Date.now())`). Used by the replay engine
+     *  with `pinRequestTime: true` so `serverTimestamp()` sentinels
+     *  resolve to the captured value and rules that branch on
+     *  `request.time` evaluate identically on replay. */
+    requestTime?: Timestamp;
+    /** FS-B6 — `setDoc(data, {merge})` storage semantics. When set, an
+     *  `update`/`create` op DEEP-merges (`merge: true`) or projects to the
+     *  listed field paths (`{ mergeFields }`) instead of the shallow
+     *  field-path update. Rule evaluation is unaffected (merge still
+     *  evaluates as create-when-absent / update-when-present). Only
+     *  meaningful when `doc-ref.set` routes a merge write through here. */
+    merge?: boolean | {
+        mergeFields: readonly string[];
+    };
+    /**
+     * Studio admin lens (Pyric Studio Gap #2). When `true`, rule
+     * evaluation is SKIPPED for this op — `simulate()` is never called and
+     * the op is treated as ALLOW. The write still goes through `applyWrite`
+     * (so structural preconditions like create-already-exists / update-
+     * missing STILL apply, matching real Firestore admin) and still emits
+     * the same `request`/`write` events + wakes listeners. This is the
+     * modular-shaped sibling of the path-string `adminSetDocument` /
+     * `adminDeleteDocument` bypass — same effect (rules off, store + events
+     * on), reachable through the chainable/modular op surface. Default
+     * (absent/false) is the unchanged rules-enforced path. */
+    bypassRules?: boolean;
+}
+export interface OperationResult {
+    allowed: boolean;
+    data?: DocumentData | null;
+    debugMessages: string[];
+    event: AgentEvent;
+    /**
+     * Item 6 — typed error code present on every denial / structural
+     * failure. Absent when `allowed: true`. See {@link FirestoreSimError}
+     * for the canonical code set and {@link makeError} for construction.
+     */
+    error?: FirestoreSimError;
+}
+export interface BatchOperationInput {
+    method: 'create' | 'update' | 'delete';
+    path: string;
+    data?: DocumentData;
+}
+export interface BatchResult {
+    allowed: boolean;
+    results: {
+        path: string;
+        allowed: boolean;
+        debugMessages: string[];
+        /** Item 6 — populated for any per-op denial inside the batch. */
+        error?: FirestoreSimError;
+    }[];
+    event: AgentEvent;
+    /**
+     * Item 6 — top-level batch error. Set when the batch as a whole was
+     * rejected (atomic rollback) — typically the first per-op error, or
+     * a sentinel-resolution error that aborted before per-op evaluation.
+     */
+    error?: FirestoreSimError;
+}
+export declare class LocalEnvironment {
+    private state;
+    private eventLog;
+    private simulator;
+    private rulesSource;
+    private seedSnapshot;
+    /**
+     * Subscribers notified after every `permission-denied` is constructed,
+     * regardless of whether downstream user code catches the resulting
+     * throw. Lets host environments (the playground runner, tests) surface
+     * denials with full eval context even when test code wraps the call
+     * in try/catch — the catch otherwise hides everything past `e.code`.
+     */
+    private denialListeners;
+    /**
+     * Subscribers notified for every evaluated op (issue #307). Each
+     * receives a public-shape `RequestEvent`. Re-shape from the internal
+     * eval payload happens in {@link emitRequest} so the env's hot path
+     * doesn't allocate the event object until we know someone's listening.
+     *
+     * Listener throws are swallowed (same rationale as `denialListeners`).
+     */
+    private requestListeners;
+    /**
+     * Subscribers notified for every COMMITTED write (issue #307). Fires
+     * after the keyspace successfully applied the write — denied or
+     * rolled-back writes don't emit here (they surface as a request-deny
+     * RequestEvent instead). Bridged to `Sandbox.onEvent` consumers via
+     * SandboxImpl's attachToEnv.
+     */
+    private writeListeners;
+    /**
+     * Subscribers notified for every snapshot DELIVERED to a user
+     * `onSnapshot` callback. Fires after the suppress-check in
+     * notify*Listener, so this count tracks real callback invocations
+     * (in contrast to `requestListeners[origin='listener']`, which used
+     * to over-count before the step-5 refactor).
+     */
+    private deliveryListeners;
+    /**
+     * Subscribers notified for every listener re-eval that was suppressed
+     * before reaching the user callback — Slice 3's no-op suppression
+     * surfaces here. Useful for "why didn't my listener fire" debugging.
+     */
+    private suppressedListeners;
+    /**
+     * Subscribers notified for listener attach / detach lifecycle. Errored
+     * still routes through onSnapshotError (bridged to listener_errored
+     * in SandboxImpl) so this channel only carries attach + detach.
+     */
+    private lifecycleListeners;
+    /**
+     * The user-origin op that's currently triggering a listener re-eval,
+     * if any. Set by the execute / batch / transaction call sites
+     * immediately before `notifyListenersForPaths`. Call sites use a
+     * **save/restore** pattern — a listener callback may itself issue a
+     * write, recursing through execute and setting up its own trigger; we
+     * must put the outer trigger back when the nested call returns so the
+     * remaining listeners in the outer fan-out still attribute correctly.
+     *
+     * Listener-origin RequestEvents copy this into `triggeredBy`. Undefined
+     * for the initial-fire path and for deployRules re-evaluation.
+     */
+    private currentTrigger?;
+    /**
+     * RULES-B11 — parsed-AST cache for the query-proof gate. The proof
+     * needs the matched `list` rule's condition AST on EVERY list read;
+     * re-parsing the (unchanging) rules source per read would be O(source)
+     * on the listener hot path. Keyed on the exact source string so
+     * `deployRules` / `seed` invalidate it for free.
+     */
+    private parsedRulesCache;
+    /**
+     * Subscribers notified when a snapshot listener is marked errored
+     * (Slice 7). Mirrors `denialListeners` but fires from the listener
+     * dispatch path, not from one-shot operation evaluation. Two-level
+     * model per source survey section 9: the listener's own `errorCallback`
+     * receives the error AND every env-level subscriber receives it —
+     * the playground subscribes here to surface stream errors as toasts
+     * the same way it surfaces denials today.
+     */
+    private snapshotErrorListeners;
+    /**
+     * Active `onSnapshot` listeners. Slice 1 — registry only; the dispatch
+     * path is wired in Slices 2 (initial fire), 3 (change detection), and
+     * 5 (transaction/batch deferral). Stored as a flat `Map<id, record>`
+     * per the implementation plan; query-canonicalization-based dedup
+     * (production's `EventManager` shape) is layered on later when caching
+     * actually saves work — see source survey section 2 for the eventual target
+     * shape. Each record carries its own target so future slices can scan
+     * and group on demand without restructuring the registry first.
+     */
+    private snapshotListeners;
+    private nextListenerId;
+    /**
+     * Deferred listener deliveries — the shared delivery scheduler (items
+     * 3 + 5). Production never invokes an `onSnapshot` callback synchronously
+     * on the registering/writing stack: the initial snapshot arrives after
+     * the listen round-trip (COMPAT firestore#80 — "asynchronous, never
+     * during register"), and a local write's echo + server ack arrive on the
+     * async event queue (firestore#85). The sandbox mirrors that by enqueuing
+     * every user-facing delivery here and draining it off-stack, on a
+     * `queueMicrotask` boundary — which satisfies the "asynchronous" contract
+     * without a macrotask's extra latency (the prototype in the deep-divergence
+     * review measured identical behavior for micro- vs macro-task deferral).
+     *
+     * Per-listener FIFO order is preserved: deliveries enqueued *during* a
+     * drain — a callback that itself writes, or the item-3 metadata ack a
+     * write echo schedules — are appended and drained in the same pass, so a
+     * write settles fully before control returns to the microtask loop.
+     */
+    private deliveryQueue;
+    private deliveryScheduled;
+    constructor();
+    /**
+     * Subscribe to permission-denied events. Returns an unsubscribe fn.
+     * The callback receives the structured `FirestoreSimError` carrying
+     * `request` / `resource` (when populated) — so subscribers can render
+     * a debugger-style frame without re-deriving any state.
+     *
+     * Listener throws are swallowed to keep the simulator hot path
+     * resilient — a faulty subscriber should not change rule semantics.
+     */
+    onDenial(cb: (err: FirestoreSimError) => void): () => void;
+    private emitDenial;
+    /**
+     * Subscribe to every evaluated op (issue #307). Returns an unsubscribe
+     * fn. The emit sites in `execute`, `batch`, `silentReadDoc`,
+     * `silentReadCollection` build the public-shape event lazily — when
+     * no subscribers are attached, eval doesn't pay the allocation cost.
+     */
+    onRequest(cb: (event: import('../types.js').RequestEvent) => void): () => void;
+    /**
+     * Subscribe to committed-write events. Internal — bridged to the
+     * public `Sandbox.onEvent` channel by SandboxImpl. Fires AFTER the
+     * keyspace applies the write; denied / rolled-back writes don't
+     * emit here.
+     */
+    onWrite(cb: (event: import('../types.js').WriteSandboxEvent) => void): () => void;
+    /** Internal — bridge for sandbox-level `onEvent` to receive
+     *  snapshot-delivery events. Fires after the user callback runs. */
+    onSnapshotDelivery(cb: (event: import('../types.js').SnapshotDeliveryEvent) => void): () => void;
+    /** Internal bridge for snapshot_suppressed events — re-evals that
+     *  didn't deliver because diffing found no observable change. */
+    onSnapshotSuppressed(cb: (event: import('../types.js').SnapshotSuppressedEvent) => void): () => void;
+    /** Internal bridge for listener attach/detach lifecycle. Errored
+     *  routes through onSnapshotError separately. */
+    onListenerLifecycle(cb: (event: import('../types.js').ListenerLifecycleEvent) => void): () => void;
+    private emitSnapshotDelivery;
+    private emitSnapshotSuppressed;
+    private emitLifecycle;
+    /**
+     * Build and dispatch a `WriteSandboxEvent`. Same sync-throw +
+     * async-rejection isolation as emitRequest. Bails early when no
+     * subscribers are attached so the hot path stays allocation-free.
+     *
+     * `sentinels` and `autoId` are reserved fields the caller can
+     * populate when the replay-engine work lands. v1 always passes
+     * undefined for both.
+     */
+    private emitWrite;
+    /**
+     * Build and dispatch a `RequestEvent` to all `onRequest` subscribers.
+     * Bails early when no one's listening so the hot path doesn't allocate
+     * an event object. Per the V1 probe numbers, eval rate can reach
+     * ~4500/sec in listener-storm scenarios — every cycle matters.
+     *
+     * Subscriber-throw isolation has two layers:
+     *   - Sync throws are caught by the try/catch around the invocation.
+     *   - Async subscribers that return a rejected Promise (e.g.
+     *     `async (e) => { throw }`) have the rejection silently swallowed
+     *     by attaching a noop `.catch`. Without this, an
+     *     `unhandledRejection` would terminate the sandbox process on
+     *     Node ≥15 default config — one bad subscriber would kill every
+     *     other observer.
+     *
+     * Subscriber callbacks are observational; the sandbox doesn't await
+     * them and doesn't propagate their errors.
+     */
+    private emitRequest;
+    /**
+     * Subscribe to snapshot-listener stream errors (Slice 7). Returns an
+     * unsubscribe fn. Fires every time a snapshot listener is marked
+     * errored — initial fire denial, change-driven re-read denial, or
+     * `deployRules` re-evaluation flipping a listener allowed → denied.
+     *
+     * The callback receives the structured `FirestoreSimError` plus the
+     * listener's `SnapshotTarget` so the host UI can attribute the error
+     * to a specific watch (e.g. "listener on `games/g1` errored").
+     *
+     * Per source survey section 9, this is the playground-side channel: stream
+     * errors fan out to both the listener's own `errorCallback` AND every
+     * env-level subscriber here. Subscriber throws are swallowed so a
+     * faulty UI handler can't destabilize the simulator.
+     */
+    onSnapshotError(cb: (err: FirestoreSimError, target: SnapshotTarget, listenerId: string) => void): () => void;
+    private emitSnapshotError;
+    /**
+     * Register a snapshot listener. Returns an `Unsubscribe` function
+     * matching the Web SDK's contract — a zero-arg call that detaches
+     * the listener. Idempotent: calling the returned function more than
+     * once after the first detach is a no-op.
+     *
+     * Slice 2: fires the **initial snapshot** synchronously after the
+     * record is registered. The current matching docs are read under
+     * `auth`'s rules — denied reads invoke `errorCallback` and mark the
+     * listener `errored` (no further notifications). Slice 3 will add
+     * change-driven fires; Slice 5 batches them through `applyBatch`.
+     *
+     * `auth` is captured at registration so notifications later evaluate
+     * rules under the auth that subscribed — not whatever auth happens
+     * to be active when a write triggers the dispatch.
+     */
+    addSnapshotListener(target: SnapshotTarget, callback: SnapshotCallback, options?: SnapshotListenerOptions, auth?: ListenerAuth, errorCallback?: SnapshotErrorCallback, 
+    /**
+     * `true` when the registering Firestore handle was a `sandbox-live`
+     * (`getFirestore(sandbox)`) target — its identity follows
+     * `sandbox.currentUser`, so this listener re-evaluates on a
+     * `currentUser` change (see {@link reevaluateLiveListeners}).
+     * `false` (default) for frozen-ctx (`getFirestore(ctx)`) listeners,
+     * which stay pinned to the auth they captured at registration.
+     */
+    followsCurrentUser?: boolean): () => void;
+    /**
+     * Compute and deliver the initial snapshot for a freshly-registered
+     * listener. Reads under the listener's `auth` and respects the
+     * deployed rules — denied reads route to `errorCallback` and mark
+     * the record `errored`. Splits doc vs query targets along the same
+     * seam {@link execute} uses, but does **not** append to the event
+     * log: listener reads are bookkeeping, not user-visible operations,
+     * and would otherwise drown the event log under any non-trivial UI.
+     */
+    private fireInitialSnapshot;
+    /**
+     * Enqueue a listener delivery and ensure an off-stack drain is pending.
+     * See {@link deliveryQueue}.
+     */
+    private scheduleDelivery;
+    /**
+     * Enqueue a write-driven delivery, restoring the triggering op while it
+     * runs so listener-origin RequestEvents / delivery events still attribute
+     * to the write (`triggeredBy`) even though the callback now fires off the
+     * writing stack. See {@link currentTrigger}.
+     */
+    private scheduleTriggeredDelivery;
+    /**
+     * Drain queued deliveries in FIFO order. A delivery may enqueue more (a
+     * callback that writes; the item-3 metadata ack a write echo schedules) —
+     * those are appended and drained in the same pass.
+     */
+    private drainDeliveries;
+    /**
+     * Synchronously deliver all pending snapshot fires. Test-only seam:
+     * production consumers observe deliveries via the microtask drain, but a
+     * synchronous test body calls this to settle the queue deterministically
+     * before asserting fire counts / snapshot contents. Idempotent — a no-op
+     * on an empty queue, and safe when a microtask drain is also pending (that
+     * drain then finds the queue already empty).
+     */
+    flushListeners(): void;
+    /**
+     * Walk every active snapshot listener and fire those whose target
+     * intersects `touchedPaths`. Called by the write-path commit hooks
+     * — `execute` (single write) and the two `applyBatch` call-sites
+     * (batch + transaction). Suppresses no-op snapshots per findings section 5
+     * (View-level suppression rather than `isEqual`): doc listeners only
+     * fire when the underlying data shape changes; query listeners only
+     * fire when the change list is non-empty.
+     *
+     * Iteration walks a snapshotted list of records — a callback is
+     * allowed to add or remove listeners (StrictMode + HMR routinely do)
+     * and we must not iterate a mutating Map.
+     *
+     * Items 3 + 5 — each per-listener fire is enqueued on the delivery
+     * scheduler rather than run inline, so the write echo lands off the
+     * writing stack (like prod's async event queue) and stays ordered behind
+     * any still-pending initial fire for the same listener. The errored /
+     * unsubscribe checks are re-run at delivery time because a listener may
+     * detach or error between this write and the drain.
+     */
+    private notifyListenersForPaths;
+    private notifyDocListener;
+    /**
+     * Item 3 — schedule the server-ack fire that follows a write echo. Only
+     * fires for includeMetadataChanges listeners (default listeners never see
+     * the metadata-only ack; their snapshot stays `pending:true`). Re-delivers
+     * the just-echoed data with `hasPendingWrites:false`, as a metadata-only
+     * change (no added/modified/removed). Rides the delivery scheduler so it
+     * lands off the echo's stack, matching prod's async ack rather than a
+     * synchronous same-tick fire. `data` is captured from the echo so a later
+     * write can't retroactively change what this ack reports. COMPAT firestore#85.
+     */
+    private scheduleDocMetadataAck;
+    private notifyQueryListener;
+    /**
+     * Item 3 — query counterpart of {@link scheduleDocMetadataAck}. Re-delivers
+     * the echoed doc set with `hasPendingWrites:false` as a metadata-only change
+     * (no added/modified/removed — `prevDocs` equals the current docs), for
+     * includeMetadataChanges listeners only. COMPAT firestore#85.
+     */
+    private scheduleQueryMetadataAck;
+    /**
+     * Run a `get` through the rules without touching the event log.
+     * Returns the read shape used by listener-snapshot construction.
+     *
+     * Throws `SimulatorUnsupportedError` on UNSUPPORTED — same loud
+     * surface as {@link execute}; the caller is then responsible for
+     * propagating it. Listener-init paths catch nothing: an unsupported
+     * rule is a sandbox limitation worth surfacing to the agent
+     * verbatim, not silently rerouting through `errorCallback`.
+     */
+    private silentReadDoc;
+    /**
+     * RULES-B11 — the parsed rules AST for the query-proof gate, cached
+     * per source string. `null` when the source doesn't parse (the
+     * simulate() call then reports the failure on its own).
+     */
+    private rulesAst;
+    /**
+     * Collection variant of {@link silentReadDoc}. Returns docs in
+     * `LocalState.list` order. Phantom parents are dropped here;
+     * agent-visible snapshots only contain real docs.
+     *
+     * **RULES-B11 — query-proof enforcement ("rules are not filters").**
+     * Production never filters a query down to the readable subset: the
+     * `list` rule is proven against the query's constraints, and an
+     * unprovable query is DENIED whole (firebase.google.com/docs/firestore/
+     * security/rules-query). The gate here:
+     *   1. `proveListQuery` decides PROVABLE / UNPROVABLE from the matched
+     *      `list`/`read` rule conditions + the structured `where`
+     *      constraints carried on the applier (FS-B2 threading).
+     *   2. UNPROVABLE → one deny request event + `permission-denied` for
+     *      the WHOLE query — no silent truncation.
+     *   3. PROVABLE → the ordinary simulate() run evaluates the residual
+     *      (auth / time / request.query) condition; doc-data conjuncts the
+     *      query pins are evaluated against the synthetic representative
+     *      resource (see `list-query-proof.ts`).
+     * Per-doc `get` rules do NOT filter query results — prod queries are
+     * governed by the `list` rule alone (the old per-doc filter loop was
+     * the rules-as-filters divergence this replaces). UNSUPPORTED still
+     * bubbles through unchanged.
+     */
+    private silentReadCollection;
+    /**
+     * RULES-B11 — apply a PROVABLE proof to the `list` test case before the
+     * residual simulate() run:
+     *   - inject the synthetic representative `resource` (the fields the
+     *     query pins with `where(field, ==, value)`) so doc-data conjuncts
+     *     evaluate against what every returnable doc is guaranteed to carry;
+     *   - populate `request.query` from the structured constraints so rules
+     *     reading `request.query.limit` / `.orderBy` see the real values.
+     */
+    private applyListProof;
+    /**
+     * Mark a listener as errored and fan the error out to two channels:
+     *   1. The listener's own `errorCallback` (per-listener handler the
+     *      Web SDK consumer registered via `onSnapshot(next, error)`).
+     *   2. Every env-level `onSnapshotError` subscriber (Slice 7) — the
+     *      playground UI surfaces stream errors here without each
+     *      listener needing to register its own toast handler.
+     *
+     * Fan-out is unconditional even when `errorCallback` is missing: the
+     * env-level channel is the catch-all so the host environment can
+     * surface errors from listeners that didn't supply their own handler.
+     */
+    private markErrored;
+    /**
+     * Test seam — exposes registry size without leaking the records.
+     * Slice 2+ may add a richer accessor when the diff path needs to
+     * iterate; for now this is enough to assert add/remove correctness.
+     */
+    getSnapshotListenerCount(): number;
+    /**
+     * Tear down the environment's listener registries (Slice 8).
+     *
+     * Clears every snapshot listener, denial subscriber, and snapshot-error
+     * subscriber so the environment drops its references to consumer
+     * callbacks. Use case: a host (e.g. the playground runner) is about to
+     * discard this `LocalEnvironment` in favor of a fresh one — calling
+     * `dispose()` first guarantees that any orphan callbacks held by the
+     * outgoing env can no longer be invoked, even if some external code path
+     * still holds a reference to the old instance.
+     *
+     * Idempotent: clearing already-empty sets is a no-op. Does not touch
+     * data state (`state` / `eventLog` / `rulesSource`) — `dispose()` is
+     * about *callback ownership*, not data lifecycle. Construct a fresh
+     * `LocalEnvironment` (or call `seed()`) to reset data.
+     */
+    dispose(): void;
+    /** Seed the environment with rules and initial data. */
+    seed(options: {
+        rules: string;
+        documents?: Record<string, DocumentData>;
+        baseDocuments?: Record<string, DocumentData>;
+    }): LintResult;
+    /**
+     * Deploy new rules (re-lint, swap for next operation).
+     *
+     * **Slice 6 — re-evaluation.** After a successful swap, every active
+     * listener is re-evaluated under the new rules. This **diverges from
+     * production** (where rule changes don't affect already-attached
+     * listeners) and is intentional per the design rationale
+     * section 4.1 — the playground's value is seeing rule changes reflected
+     * immediately in live UI. Concretely:
+     *   - A doc that was unreadable but is now readable fires a snapshot
+     *     (and clears the listener's `errored` flag if applicable).
+     *   - A doc that was readable but is now unreadable marks the listener
+     *     errored via {@link markErrored}.
+     *   - Query listeners diff old↔new readable doc sets; flips surface as
+     *     `added` / `removed` change entries.
+     */
+    deployRules(source: string): LintResult;
+    /**
+     * Walk every active listener and recompute its snapshot under the
+     * current rules. Called by {@link deployRules} after a successful
+     * rules swap (Slice 6 section 4.1). Iteration follows the same
+     * snapshot-then-skip-orphans pattern as {@link notifyListenersForPaths}
+     * — a callback may add or remove listeners (StrictMode + HMR both
+     * routinely do this), and the dispatch loop must not iterate a
+     * mutating Map.
+     */
+    private reEvaluateAllListeners;
+    /**
+     * Re-evaluate every LIVE listener against a new session auth.
+     *
+     * Called when the sandbox's `currentUser` changes (sign-out / sign-in
+     * as a different user). Production re-establishes the listen stream on
+     * a session auth change — an auth-gated listener loses access on
+     * sign-out and re-reads under the new identity on sign-in. The sandbox
+     * matches that here: for each listener with `followsCurrentUser`, we
+     * set `record.auth = newAuth` and re-run the SAME per-listener
+     * evaluation `deployRules` uses ({@link reEvaluateDocListener} /
+     * {@link reEvaluateQueryListener}) — which re-reads under the new auth
+     * and flips allowed↔denied (delivering a fresh snapshot, or marking
+     * the listener errored with `permission-denied` when the new auth
+     * can't read).
+     *
+     * Frozen-ctx listeners (`followsCurrentUser === false`) are left
+     * untouched — they stay pinned to the identity chosen at
+     * `getFirestore(ctx)` time. WRITE-driven re-eval is unaffected: a
+     * write by another user still re-evaluates each listener against ITS
+     * OWN captured `auth` (this method only runs on auth change, and only
+     * touches live listeners' captured auth).
+     *
+     * No-op when there are no live listeners. Iteration follows the same
+     * snapshot-then-skip-orphans pattern as {@link notifyListenersForPaths}
+     * — a callback may add or remove listeners during dispatch.
+     */
+    reevaluateLiveListeners(newAuth: ListenerAuth): void;
+    /**
+     * Doc-listener re-evaluation. Three flip cases matter:
+     *   - Allowed → denied: mark errored (unless already errored, in which
+     *     case the error is not re-delivered — matches production's
+     *     once-per-stream error contract).
+     *   - Errored → allowed: clear `errored` and fire as an initial
+     *     snapshot (the listener gets a fresh baseline; suppression cannot
+     *     apply because there is no comparable `currentDocData` from the
+     *     errored state).
+     *   - Allowed → allowed: behaves like a write-driven re-fire — diff
+     *     against `currentDocData` and suppress if unchanged.
+     */
+    private reEvaluateDocListener;
+    /**
+     * Query-listener re-evaluation. Flip semantics mirror the doc path:
+     * {@link silentReadCollection} re-runs the query-proof gate + `list`
+     * rule under the new rules — a query that flipped unprovable/denied
+     * surfaces as a stream error, one that flipped allowed re-delivers,
+     * and the diff against `currentDocs` is computed by the same
+     * `buildQuerySnapshot` path the write-driven notifier uses.
+     */
+    private reEvaluateQueryListener;
+    /** Get current rules source. */
+    getRules(): string;
+    /** Read a document from local state (admin, no rules). */
+    getDocument(path: string): DocumentData | null;
+    /**
+     * List documents in a collection (admin, no rules).
+     *
+     * Includes phantom parent docs (records synthesized for any parent path
+     * that has descendants but no stored data of its own). Phantom records
+     * carry `phantom: true` and `data: {}` so the discover crawler — which
+     * walks structure rather than data — sees the same shape live Firestore
+     * would expose. See {@link LocalState#list} for the contract.
+     */
+    listDocuments(collection: string): {
+        path: string;
+        data: DocumentData;
+        phantom?: true;
+    }[];
+    /**
+     * Scan documents under a path through the {@link DocStore} seam (admin, no
+     * rules). The query engine gathers candidates with `{ directOnly: true }` for
+     * a collection's real direct children (no phantoms); the discover crawler
+     * still uses {@link listDocuments}, which adds phantom parents.
+     */
+    scanDocuments(prefix: string, opts?: ScanOptions): DocEntry[];
+    /**
+     * Rule-enforced collection read — the query (`getDocs` / `Query.get` /
+     * aggregate) read path for the web-modular + auth-scoped admin-compat
+     * surfaces. **Unlike {@link listDocuments} this evaluates security
+     * rules** (FS-B1 / RULES-B1): query reads must not be a silent total
+     * bypass when single-doc reads (`DocumentReference.get`) are enforced.
+     *
+     * Semantics mirror the listener read path ({@link silentReadCollection}):
+     *   1. RULES-B11 — prove the query against the matched `list` rule
+     *      ("rules are not filters"): an unprovable query returns
+     *      `{ allowed: false, error }` for the WHOLE query — the caller
+     *      throws `permission-denied`. No silent truncation.
+     *   2. Evaluate the `list` rule's residual condition once under `auth`
+     *      (with the synthetic representative resource when the proof
+     *      pinned doc-data fields). A denial (or simulator error) returns
+     *      `{ allowed: false, error }`.
+     *   3. On PASS every candidate is returned — production queries are
+     *      governed by the `list` rule alone; per-doc `get` rules do not
+     *      filter query results.
+     *
+     * `candidates` is supplied by the caller so collection-group queries
+     * (whose candidate set is a cross-collection scan, not a single
+     * `state.list`) can reuse the same enforcement. `listPath` is the
+     * collection path the `list` rule evaluates against; for
+     * collection-group reads the caller passes the group id's match path.
+     * `query` is the structured `where`/`limit`/`orderBy` view the proof
+     * consumes (the caller still applies the actual row filtering).
+     *
+     * Emits `origin: 'user'` request events (one per `list`) so inspector
+     * consumers see query reads the same way they see writes. UNSUPPORTED
+     * rules still bubble as {@link SimulatorUnsupportedError}.
+     */
+    readQueryCandidates(candidates: {
+        path: string;
+        data: DocumentData;
+    }[], listPath: string, auth: Operation['auth'], query?: QueryConstraints, bypassRules?: boolean): {
+        allowed: true;
+        docs: {
+            path: string;
+            data: DocumentData;
+        }[];
+    } | {
+        allowed: false;
+        error: FirestoreSimError;
+    };
+    /**
+     * List root collection IDs derived from the in-memory keyspace.
+     * Used by the discover/crawler adapter so `firestore_discover_paths`
+     * can run against the simulator without hitting live Firestore.
+     */
+    listRootCollections(): string[];
+    /**
+     * List subcollection IDs underneath the given document path.
+     * Companion to {@link listRootCollections} for the discover/crawler adapter.
+     */
+    listSubcollections(docPath: string): string[];
+    /** Get full state snapshot. */
+    snapshot(): Record<string, DocumentData>;
+    /**
+     * Capture the prior state of just the given paths (for single-write / batch
+     * undo), as `{ path: priorData | null }` where `null` records a doc that did
+     * not exist. The affected-path alternative to a whole-keyspace
+     * {@link snapshot}, so the undo stack stays O(affected) not O(keyspace).
+     * Must be called BEFORE the write applies.
+     */
+    private capturePriors;
+    /**
+     * Replace a document at `path` (admin, no rules). `set` semantics —
+     * creates if absent, overwrites if present, no merge. Wakes any
+     * active listeners attached to `path` so subscriptions see the
+     * change live, mirroring what a rule-allowed `set` would do.
+     */
+    adminSetDocument(path: string, data: DocumentData): void;
+    /**
+     * Delete a document at `path` (admin, no rules). Returns
+     * `{ deleted }` reflecting whether a doc was actually removed
+     * (`false` if the path didn't exist). Idempotent — a no-op on a
+     * missing path does not throw. Wakes listeners on `path`.
+     */
+    adminDeleteDocument(path: string): {
+        deleted: boolean;
+    };
+    /**
+     * Run the rules engine for the given test cases — UNLESS `bypassRules`
+     * is set, in which case the rules engine is skipped entirely and a
+     * synthetic all-ALLOW result is returned (Pyric Studio Gap #2 admin
+     * lens). Every `simulate()` call site in `execute` / `batch` /
+     * `transaction` routes through here so the bypass is centralized and
+     * the rules-enforced path is byte-for-byte unchanged when `bypassRules`
+     * is absent/false.
+     *
+     * The synthetic result mirrors the engine's success shape
+     * (`{ success: true, data: { results, passed, failed, unsupported } }`)
+     * with one PASSED entry per test case, so callers that read
+     * `simResult.data.results[i]` see a normal ALLOW with no special-casing.
+     */
+    private runSimulate;
+    /** Execute a single operation. Rules are evaluated against local state.
+     *  When `operation.bypassRules` is set, rule evaluation is skipped (admin
+     *  lens — Studio Gap #2): the op is treated as ALLOW and routed through
+     *  the same apply + emit path, so structural preconditions, events, and
+     *  listeners behave exactly as a rule-allowed op would. */
+    execute(operation: Operation): OperationResult;
+    /**
+     * Item 7 — `addDoc()`-style create with a Firestore-compatible auto ID.
+     *
+     * Mirrors the live SDK's `addDoc(collection(db, c), data)` flow: mint a
+     * 20-char alphanumeric document ID, append it to the collection path,
+     * then run the same `execute({ method: 'create', ... })` pipeline that
+     * an explicit-ID create would (rules, sentinel resolution, applyWrite).
+     * The minted path is returned so callers can re-read the doc without
+     * having to capture the ID via a side channel.
+     */
+    createWithAutoId(collection: string, data: DocumentData, auth: Operation['auth'], bypassRules?: boolean): {
+        path: string;
+        result: OperationResult;
+    };
+    /** Execute multiple writes atomically. All must pass rules or none apply. */
+    batch(operations: BatchOperationInput[], auth: Operation['auth'], bypassRules?: boolean): BatchResult;
+    /**
+     * Run a callback inside a Firestore-style transaction.
+     *
+     * The callback may be synchronous or async — return a `Promise` and
+     * the method returns `Promise<TransactionResult<R>>`; return a value
+     * (or void) and the method returns `TransactionResult<R>` directly.
+     * This mirrors the Admin SDK's `runTransaction(fn)` signature, which
+     * accepts both shapes.
+     *
+     * Lifecycle:
+     *   1. Build a `TransactionContext` with the read callback bound to
+     *      `this.state.get` (admin-mode reads, no rules eval — probe 0.B).
+     *   2. Invoke `fn(tx)`. If it returns a Promise, await before
+     *      continuing — sentinel resolution, rules eval, and applyBatch
+     *      all happen AFTER the callback fully resolves.
+     *      - Throws (including `ReadAfterWriteError` from probe 0.A/0.J,
+     *        `AmbiguousPostDeleteWriteError` from the merge layer, or any
+     *        user error) propagate unchanged after an aborted-tx event is
+     *        logged. Probe 0.G: custom Error properties survive.
+     *   3. Merge same-path queued writes (Item 1.3) into `BatchOperation[]`.
+     *   4. Resolve sentinels against pre-tx state (one `serverTime` for the
+     *      whole tx — mirrors `batch()` semantics). For async callbacks
+     *      `serverTime` is pinned at commit time, AFTER the await — so
+     *      `serverTimestamp()` reflects when the writes are actually
+     *      committed, not when the read happened.
+     *   5. Per-op rules evaluation against PRE-tx state. No inter-write
+     *      visibility (extrapolated from batch parity, probe 0.E). For a
+     *      queued `set`, rules eval under `create` if the doc is missing
+     *      pre-tx, else `update` — `applyBatch` still runs the `set` op.
+     *   6. If every write passes rules, run `applyBatch` atomically.
+     *      Structural failures (create-already-exists, update/delete-
+     *      missing) demote per-op `allowed` and surface typed errors —
+     *      matches single-op + batch behavior.
+     *   7. Append a single `type: 'transaction'` `AgentEvent` carrying
+     *      `reads[]`, `operations[]`, and a pre-tx snapshot for undo.
+     */
+    transaction<R>(fn: (tx: Transaction) => Promise<R>, options: TransactionOptions): Promise<TransactionResult<R>>;
+    transaction<R>(fn: (tx: Transaction) => R, options: TransactionOptions): TransactionResult<R>;
+    /**
+     * Commit phase shared by sync + async transaction paths. Runs after
+     * the callback has fully completed (sync return or awaited resolve).
+     * Splitting this out keeps `transaction()` readable and keeps the
+     * commit logic from being duplicated across the two branches.
+     */
+    private commitTransaction;
+    /**
+     * Append an aborted-transaction event for a callback throw (sync or
+     * async path). The original Error is re-thrown by the caller —
+     * probe 0.G locks "exceptions propagate unchanged", so this helper
+     * never throws on its own.
+     */
+    private logAbortedTransaction;
+    /** Undo the last write operation. Restores the affected paths (single-write /
+     *  batch) or the whole keyspace (transaction) to their pre-write state. */
+    undo(): AgentEvent | null;
+    /** Redo the last undone operation. Re-applies the write directly
+     *  without going through execute() (which would clear the redo stack). */
+    redo(): OperationResult | null;
+    /** Get all events. */
+    getEvents(): AgentEvent[];
+    /** Get event count. */
+    getEventCount(): number;
+    private buildTestCase;
+    /**
+     * Apply a write to local state, returning a structural error when
+     * the underlying state operation rejects (Item 6). Rules have already
+     * decided to ALLOW by the time we get here; what's left are the
+     * preconditions only the keyspace knows about — `create` of an
+     * existing path, `update`/`delete` of a missing path. The simulator
+     * previously dropped these silently (state.create returned
+     * `{success:false}` and we ignored it), which let `allowed:true`
+     * results coexist with no actual mutation. Returning the failure
+     * lets `execute()` demote `allowed` and surface the right error code.
+     */
+    private applyWrite;
+}
+//# sourceMappingURL=local-environment.d.ts.map