pyric-tools 0.1.0-alpha.7

package/dist/serve/worker/client.d.ts

@@ -0,0 +1,668 @@
+/**
+ * Worker client SDK — mirrors `pyric/firestore` for the SharedWorker path.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * When the SharedWorker is available, app code should be able to swap its
+ * `pyric/firestore` import for this module (via an import-map) and have
+ * every operation transparently route to the single worker-hosted sandbox
+ * instead of running an in-page sandbox. The API surface is identical:
+ * same function names, same argument shapes, same return types.
+ *
+ * DESIGN SPLIT
+ * ------------
+ * Client-side only (no RPC — build descriptor objects in-page):
+ *   `getFirestore`, `doc`, `collection`, `collectionGroup`, `query`,
+ *   `where`, `orderBy`, `limit`, `limitToLast`, `startAt`, `startAfter`,
+ *   `endAt`, `endBefore`
+ *
+ *   These return `ClientDb`, `DocRefHandle`, `CollRefHandle`, `QueryHandle`
+ *   objects that carry the port + a serializable descriptor. No RPC fires
+ *   until an execution function is called.
+ *
+ *   WHY IN-PAGE: Firebase's `doc()` / `collection()` / `query()` are
+ *   synchronous — they build ref objects. Making them async (RPC) would
+ *   break every existing app pattern. Since path-building needs no data
+ *   from the sandbox, it's correct and cheap to do it in-page.
+ *
+ * Sentinel factories (client-side markers, worker resolves them):
+ *   `serverTimestamp`, `increment`, `arrayUnion`, `arrayRemove`, `deleteField`
+ *
+ *   Return `SentinelMarker` objects that embed in write data.
+ *   The host's `resolveSentinels` converts them before writing.
+ *
+ * Execution functions (RPC — send op to worker, await reply):
+ *   `getDoc`, `getDocs`, `setDoc`, `updateDoc`, `deleteDoc`, `addDoc`,
+ *   `onSnapshot`, `getCountFromServer`, `runTransaction`, `writeBatch`
+ *
+ * TRANSACTION SEMANTICS + MULTI-TAB CORRECTNESS
+ * -----------------------------------------------
+ * `runTransaction(db, updateFn)` on the client:
+ *   1. Runs `updateFn(txn)` locally — `txn.get(ref)` RPCs a getDoc, records
+ *      `{ path, data }` in the per-attempt read-set, returns the snapshot.
+ *   2. `txn.set/update/delete` buffer writes locally in `txn`.
+ *   3. When `updateFn` resolves, sends `{ method:'txnCommit', reads, writes }`.
+ *   4. The worker re-reads each read-set doc inside a sandbox transaction,
+ *      compares the JSON-serialized current data against the recorded data,
+ *      and aborts with `{ code:'aborted' }` on any mismatch.
+ *   5. On `aborted`, the client re-runs `updateFn` with a fresh txn object
+ *      (up to 5 attempts). All other errors are propagated immediately.
+ *
+ * WHY RETRY IS NECESSARY (multi-tab gap):
+ * A transaction spans two messages: the `txn.get` RPC and `txnCommit`. Another
+ * tab can write to a read doc in between (the event loop is free between
+ * messages). Without read-set validation that produces a silent lost update.
+ * The retry loop mirrors real Firestore SDK behaviour.
+ *
+ * SNAPSHOT DESERIALIZATION
+ * ------------------------
+ * The worker sends document data as `{ json: string }` (SerializedDocData).
+ * `deserializeDocData` (protocol.ts) parses the JSON and calls
+ * `rehydrateDocValue` (from pyric/sandbox) to reconstruct REAL class
+ * instances — Timestamp with `.seconds`/`.nanos`, Bytes with `.data`, LatLng
+ * with `.lat`/`.lng`. The wire format == the IDB persistence format.
+ */
+import type { DocRef, CollRef, QueryDescriptor, QueryConstraintDescriptor, AggregateFieldDescriptor, AggregateSpecDescriptor, SentinelMarker, SerializedUser, SerializedIdTokenResult, AuthPersistenceMode, ResolvedIdentity } from './protocol.js';
+import type { PolicyRequest } from './protocol.js';
+import type { WorkerOpPayload, WorkerSubPayload } from '../../bridge/protocol.js';
+import type { AuthLens, SandboxEvent, SandboxSnapshot } from 'pyric/sandbox';
+import type { AuthUserRecord, CreateUserRequest, UpdateUserRequest } from 'pyric/auth';
+import type { FullMetadata } from 'pyric/storage';
+/** Opaque client-side Firestore handle. Holds the MessagePort to the worker. */
+export interface ClientDb {
+    readonly __kind: 'client-db';
+    readonly port: MessagePort;
+}
+export interface ClientRtdb {
+    readonly __kind: 'client-rtdb';
+    readonly port: MessagePort;
+}
+export interface RtdbRefHandle {
+    readonly __kind: 'rtdb-ref';
+    readonly port: MessagePort;
+    readonly path: string;
+    readonly key: string | null;
+    readonly parent: RtdbRefHandle | null;
+    readonly root: RtdbRefHandle;
+    toString(): string;
+}
+export interface RtdbDataSnapshot {
+    readonly key: string | null;
+    readonly size: number;
+    exists(): boolean;
+    val(): unknown;
+    child(path: string): RtdbDataSnapshot;
+    hasChild(path: string): boolean;
+    hasChildren(): boolean;
+    exportVal(): unknown;
+    toJSON(): unknown;
+    forEach(cb: (child: RtdbDataSnapshot) => boolean | void): boolean;
+    readonly ref: RtdbRefHandle;
+}
+/** Client-side document reference — carries a DocRef descriptor + port. */
+export interface DocRefHandle {
+    readonly __kind: 'doc-ref';
+    readonly descriptor: DocRef;
+    readonly port: MessagePort;
+    readonly id: string;
+    readonly path: string;
+}
+/** Client-side collection reference. */
+export interface CollRefHandle {
+    readonly __kind: 'coll-ref';
+    readonly descriptor: CollRef;
+    readonly port: MessagePort;
+    readonly id: string;
+    readonly path: string;
+}
+/** Client-side query. */
+export interface QueryHandle {
+    readonly __kind: 'query';
+    readonly descriptor: QueryDescriptor;
+    readonly port: MessagePort;
+}
+/** Union of all client handles. */
+export type AnyHandle = ClientDb | DocRefHandle | CollRefHandle | QueryHandle;
+/**
+ * Set the default auth lens applied to subsequent Firestore DATA ops from this
+ * client (Pyric Studio). Pass `{ mode: 'as', uid }` to read/write AS a user
+ * (rules apply), `{ mode: 'admin' }` for the admin lens, or
+ * `{ mode: 'app-session' }` / `undefined` to revert to the app's own session.
+ *
+ * The lens is process-wide for this client module (one served page = one
+ * worker port), mirroring how Studio drives a single active identity at a time.
+ * Auth ops are unaffected — they always operate the real session.
+ */
+export declare function setLens(lens: AuthLens | undefined): void;
+/** The active default lens (read-only view), for Studio UI to reflect state. */
+export declare function getLens(): AuthLens | undefined;
+/** Declare who issues the ops this client module constructs. See {@link _opIssuer}. */
+export declare function setOpIssuer(source: 'studio' | undefined): void;
+/**
+ * Connect to the SharedWorker and return a client Firestore handle.
+ *
+ * Pass the URL of the SharedWorker script as `workerUrl`. Under `pyric dev`
+ * this is `/__pyric/sdk/worker.js`; for tests or standalone use, pass the path
+ * explicitly.
+ *
+ * `getFirestore` mirrors `pyric/firestore`'s `getFirestore(sandbox)` shape
+ * but returns a `ClientDb` backed by a `MessagePort` instead of a sandbox.
+ */
+export declare function getFirestore(workerUrl: string | URL, name?: string): ClientDb;
+/**
+ * Ask the worker for its baked build version (staleness guard). The page
+ * compares it to the served bundle version and warns when a still-running OLD
+ * worker is older than what's served (a SharedWorker can't hot-update).
+ */
+export declare function getWorkerVersion(db: ClientDb): Promise<string>;
+/**
+ * Ask the worker for its stable per-instance id (see host `INSTANCE_ID_KEY`).
+ * Studio renders a human-friendly form so a user can tell which sandbox instance
+ * they're looking at — the same `localhost:<port>` in a different browser profile
+ * is a SEPARATE sandbox (a separate SharedWorker + IndexedDB), and this is how
+ * the two are told apart.
+ */
+export declare function getWorkerInstanceId(db: ClientDb): Promise<string>;
+/**
+ * Phase 2 (transfer): export the FULL sandbox state as a portable bundle string
+ * (the chunk format the persist layer uses, so wrapper types round-trip). Save
+ * it to a file and {@link importWorkerState} it into another instance.
+ */
+export declare function exportWorkerState(db: ClientDb): Promise<string>;
+/** Phase 2 (clobber): replace this sandbox's ENTIRE state with `bundle`. */
+export declare function importWorkerState(db: ClientDb, bundle: string): Promise<void>;
+/** Phase 3: save the live sandbox as a named branch (a saved state bundle). */
+export declare function saveWorkerBranch(db: ClientDb, name: string): Promise<void>;
+/** Phase 3: list this instance's saved branch names. */
+export declare function listWorkerBranches(db: ClientDb): Promise<string[]>;
+/** Phase 3 (clobber): switch the live sandbox to a named branch's state. */
+export declare function switchWorkerBranch(db: ClientDb, name: string): Promise<void>;
+/** Phase 3: delete a named branch. */
+export declare function deleteWorkerBranch(db: ClientDb, name: string): Promise<void>;
+/**
+ * Forward an agent tool-call to the worker so it executes against the SAME
+ * sandbox the app + Studio use. The worker runs the canonical tool dispatcher
+ * (`buildSandboxDispatcher`) and replies with the `{ ok, summary, data }`
+ * result. Used by the bridge peer on the worker path (`connectBridgePeer` in
+ * `entries/runtime.ts`) so the agent shares the one authoritative sandbox.
+ */
+export declare function callTool(db: ClientDb, name: string, args: Record<string, unknown>): Promise<{
+    ok: boolean;
+    summary: string;
+    data?: unknown;
+}>;
+/**
+ * Relay one raw worker-protocol op into the SharedWorker. `op` is the op
+ * message minus `t`/`id` (the `WorkerOpPayload` wire shape); resolves with
+ * the worker's `res.value`, rejects with an Error carrying `.code`.
+ */
+export declare function relayWorkerOp(db: ClientDb, op: WorkerOpPayload): Promise<unknown>;
+/**
+ * Relay a raw worker-protocol subscription into the SharedWorker. `sub` is
+ * the sub message minus `t`/`subId` (the `WorkerSubPayload` wire shape).
+ * `onValue` receives every snap value VERBATIM — including the worker host's
+ * `{ __error: { code, message } }` establishment-failure convention (listener
+ * errors are re-wrapped into the same shape so the far side sees one form).
+ * Returns the unsubscribe function.
+ *
+ * The unified event stream (`target: 'events'`) is NOT relayable yet — its
+ * history batches aren't coalescible, so it needs bounded backpressure first
+ * (slice 2).
+ */
+export declare function relayWorkerSub(db: ClientDb, sub: WorkerSubPayload, onValue: (value: unknown) => void): () => void;
+/**
+ * Build a document reference. Mirrors `pyric/firestore`'s `doc(db, path)`.
+ *
+ * WHY CLIENT-SIDE: Firebase's `doc()` is synchronous and path-only — it
+ * needs no data from the sandbox. We build a descriptor object here and
+ * include the port so execution calls can route to the worker.
+ */
+export declare function doc(parent: ClientDb | CollRefHandle, ...pathSegments: string[]): DocRefHandle;
+/**
+ * Build a collection reference. Mirrors `pyric/firestore`'s `collection(db, path)`.
+ */
+export declare function collection(parent: ClientDb | DocRefHandle, ...pathSegments: string[]): CollRefHandle;
+/**
+ * Build a collection-group query. Mirrors `pyric/firestore`'s `collectionGroup(db, id)`.
+ */
+export declare function collectionGroup(db: ClientDb, collectionId: string): QueryHandle;
+/** Opaque query constraint — carries its descriptor for embedding in queries. */
+export interface QueryConstraintHandle {
+    readonly _descriptor: QueryConstraintDescriptor;
+}
+export declare function where(field: string, op: string, value: unknown): QueryConstraintHandle;
+/**
+ * OR composite filter — at least one operand must match. Operands must be
+ * filters (`where()`, or nested `or()`/`and()`). Mirrors `pyric/firestore`'s
+ * `or(...)`; the worker rebuilds it with the real modular factory.
+ */
+export declare function or(...filters: QueryConstraintHandle[]): QueryConstraintHandle;
+/** AND composite filter — every operand must match. See {@link or}. */
+export declare function and(...filters: QueryConstraintHandle[]): QueryConstraintHandle;
+export declare function orderBy(field: string, direction?: 'asc' | 'desc'): QueryConstraintHandle;
+export declare function limit(n: number): QueryConstraintHandle;
+export declare function limitToLast(n: number): QueryConstraintHandle;
+export declare function startAt(...values: unknown[]): QueryConstraintHandle;
+export declare function startAfter(...values: unknown[]): QueryConstraintHandle;
+export declare function endAt(...values: unknown[]): QueryConstraintHandle;
+export declare function endBefore(...values: unknown[]): QueryConstraintHandle;
+/**
+ * Apply query constraints to a source ref or query.
+ * Mirrors `pyric/firestore`'s `query(source, ...constraints)`.
+ */
+export declare function query(source: CollRefHandle | QueryHandle, ...constraints: QueryConstraintHandle[]): QueryHandle;
+export declare function serverTimestamp(): SentinelMarker;
+export declare function increment(n: number): SentinelMarker;
+export declare function arrayUnion(...values: unknown[]): SentinelMarker;
+export declare function arrayRemove(...values: unknown[]): SentinelMarker;
+export declare function deleteField(): SentinelMarker;
+export interface ClientDocSnapshot {
+    readonly id: string;
+    readonly path: string;
+    /** Lightweight document ref (id + path), mirroring the modular SDK's
+     *  `snap.ref` that `@pyric/ui` reads off query docs. */
+    readonly ref: {
+        readonly id: string;
+        readonly path: string;
+    };
+    exists(): boolean;
+    data(): Record<string, unknown> | undefined;
+}
+export interface ClientQuerySnapshot {
+    readonly size: number;
+    readonly empty: boolean;
+    readonly docs: ClientDocSnapshot[];
+}
+export declare function getDoc(ref: DocRefHandle): Promise<ClientDocSnapshot>;
+export declare function getDocs(source: CollRefHandle | QueryHandle): Promise<ClientQuerySnapshot>;
+/**
+ * Enumerate root collection ids (Pyric Studio data browse). The modular SDK has
+ * no client `listCollections`, so the host scans the sandbox keyspace and
+ * returns the ids. Lens is attached (via dataRpc) but the host enumeration is
+ * lens-independent.
+ */
+export declare function listRootCollections(db: ClientDb): Promise<string[]>;
+/** Enumerate subcollection ids under a document path (Pyric Studio data browse). */
+export declare function listSubcollections(db: ClientDb, docPath: string): Promise<string[]>;
+export declare function setDoc(ref: DocRefHandle, data: Record<string, unknown>, options?: {
+    merge?: boolean;
+    mergeFields?: string[];
+}): Promise<void>;
+export declare function updateDoc(ref: DocRefHandle, data: Record<string, unknown>): Promise<void>;
+export declare function deleteDoc(ref: DocRefHandle): Promise<void>;
+export declare function addDoc(coll: CollRefHandle, data: Record<string, unknown>): Promise<DocRefHandle>;
+export declare function getCountFromServer(source: CollRefHandle | QueryHandle): Promise<{
+    data(): {
+        count: number;
+    };
+}>;
+/** Factory: count() aggregate field. Mirrors `pyric/firestore`'s `count()`. */
+export declare function count(): AggregateFieldDescriptor;
+/** Factory: sum-of-`field` aggregate. Mirrors `pyric/firestore`'s `sum()`. */
+export declare function sum(field: string): AggregateFieldDescriptor;
+/** Factory: average-of-`field` aggregate. Empty input yields `null`. */
+export declare function average(field: string): AggregateFieldDescriptor;
+/**
+ * Run a multi-field aggregate on the worker. Mirrors `pyric/firestore`'s
+ * `getAggregateFromServer(query, spec)`: spec entries are keyed by
+ * caller-chosen aliases; `.data()` returns the numbers under the same keys
+ * (`average` over no rows is `null`).
+ */
+export declare function getAggregateFromServer<S extends AggregateSpecDescriptor>(source: CollRefHandle | QueryHandle, spec: S): Promise<{
+    data(): {
+        [K in keyof S]: number | null;
+    };
+}>;
+export type Unsubscribe = () => void;
+/**
+ * Subscribe to a document or query. Mirrors `pyric/firestore`'s `onSnapshot`.
+ *
+ * Returns an `unsub` function. Sends `{ t:'unsub', subId }` to the worker
+ * to deregister the listener on the worker side.
+ */
+export declare function onSnapshot(target: DocRefHandle | CollRefHandle | QueryHandle, callback: (snap: ClientDocSnapshot | ClientQuerySnapshot) => void, errorCallback?: (err: unknown) => void): Unsubscribe;
+/**
+ * Client-side write batch. Buffers `set`/`update`/`delete` calls and
+ * sends them all to the worker on `.commit()`.
+ *
+ * Mirrors `pyric/firestore`'s `writeBatch(db)` shape:
+ *   const batch = writeBatch(db);
+ *   batch.set(ref, { ... });
+ *   batch.delete(ref2);
+ *   await batch.commit();
+ */
+export interface ClientWriteBatch {
+    set(ref: DocRefHandle, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+        mergeFields?: string[];
+    }): ClientWriteBatch;
+    update(ref: DocRefHandle, data: Record<string, unknown>): ClientWriteBatch;
+    delete(ref: DocRefHandle): ClientWriteBatch;
+    commit(): Promise<void>;
+}
+export declare function writeBatch(db: ClientDb): ClientWriteBatch;
+/** Client-side transaction handle. */
+export interface ClientTransaction {
+    get(ref: DocRefHandle): Promise<ClientDocSnapshot>;
+    set(ref: DocRefHandle, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+        mergeFields?: string[];
+    }): void;
+    update(ref: DocRefHandle, data: Record<string, unknown>): void;
+    delete(ref: DocRefHandle): void;
+}
+/**
+ * Run a transaction. Mirrors `pyric/firestore`'s `runTransaction(db, fn)`.
+ *
+ * MULTI-TAB CORRECTNESS — READ-SET VALIDATION + RETRY
+ * ----------------------------------------------------
+ * A transaction spans two messages: the `txn.get` RPC (read) and the
+ * `txnCommit` RPC (commit). Between those two messages another tab may
+ * write to a doc the current tab read — a silent lost update without
+ * validation. We fix this the standard way:
+ *
+ *   1. Each `txn.get(ref)` records `{ path, data }` in a per-attempt
+ *      read-set (`data` is the raw `SerializedDocData` the worker
+ *      returned, or `null` if the doc was missing).
+ *   2. `txnCommit` carries both `reads` (the read-set) and `writes`.
+ *   3. The worker re-reads each doc inside a sandbox transaction, re-
+ *      serializes it the same way, and compares the JSON strings.
+ *      Any mismatch → `{ ok: false, error: { code: 'aborted' } }`.
+ *   4. On `aborted`, the client discards the result of `updateFn` and
+ *      re-runs it with a fresh transaction object (fresh reads, empty
+ *      write buffer). Up to `TXN_MAX_ATTEMPTS` attempts are made.
+ *   5. After the cap, throws an error with `.code === 'aborted'`.
+ *
+ * This matches real Firestore's behaviour: the SDK retries `updateFn`
+ * on conflict rather than surfacing the error immediately.
+ */
+export declare function runTransaction<R>(db: ClientDb, updateFn: (txn: ClientTransaction) => Promise<R> | R): Promise<R>;
+/**
+ * Deploy new rules to the worker's sandbox. Active onSnapshot listeners
+ * that were allowed by the old rules may start receiving error callbacks
+ * if the new rules deny them.
+ */
+export declare function setRules(db: ClientDb, source: string): Promise<{
+    warnings: unknown[];
+}>;
+export declare function setFirestoreRules(db: ClientDb, source: string): Promise<{
+    ok: boolean;
+    warnings: unknown[];
+    messages: unknown[];
+}>;
+export declare function setDatabaseRules(db: ClientDb | ClientRtdb, source: unknown): Promise<{
+    ok: boolean;
+    messages: unknown[];
+}>;
+export declare function getActiveRules(db: ClientDb | ClientRtdb, service?: 'firestore' | 'database'): Promise<unknown>;
+export declare function getRulesStatus(db: ClientDb | ClientRtdb, service?: 'firestore' | 'database'): Promise<unknown>;
+export declare function adminGetDocument(db: ClientDb, path: string): Promise<Record<string, unknown> | null>;
+export declare function adminListDocuments(db: ClientDb, path: string): Promise<Array<{
+    path: string;
+    data: unknown;
+    phantom?: boolean;
+}>>;
+export declare function adminSetDocument(db: ClientDb, path: string, data: unknown): Promise<void>;
+export declare function adminDeleteDocument(db: ClientDb, path: string): Promise<boolean>;
+export declare function adminReadState(db: ClientDb, opts?: {
+    path?: string;
+    maxDepth?: number;
+}): Promise<Record<string, unknown>>;
+export declare function rtdbGetDatabase(source?: ClientDb | string | URL, name?: string): ClientRtdb;
+export declare function rtdbRef(db: ClientRtdb, path?: string): RtdbRefHandle;
+export declare function rtdbChild(parent: RtdbRefHandle, path: string): RtdbRefHandle;
+export declare function rtdbGet(r: RtdbRefHandle): Promise<RtdbDataSnapshot>;
+export declare function adminReadRtdbState(db: ClientDb | ClientRtdb): Promise<unknown>;
+export declare function adminSetRtdbValue(db: ClientDb | ClientRtdb, path: string, value: unknown): Promise<void>;
+export declare function adminUpdateRtdbValue(db: ClientDb | ClientRtdb, path: string, values: Record<string, unknown>): Promise<void>;
+export declare function adminDeleteRtdbValue(db: ClientDb | ClientRtdb, path: string): Promise<void>;
+/**
+ * Subscribe to the raw value at an RTDB path with the ADMIN lens (Pyric Studio
+ * data viewer). Rides the same `{service:'rtdb'}` value-subscription channel as
+ * `rtdbOnValue`, but pins `actAs: {mode:'admin'}` per-sub instead of following
+ * the module default lens, so Studio's viewer stays admin (PRINCIPLES M3) while
+ * the page's own listeners keep their session semantics.
+ *
+ * `next` receives the plain JSON value at `path` (`null` when absent) on
+ * subscribe and again after every write that changes the subtree.
+ */
+export declare function adminSubscribeRtdbValue(db: ClientDb | ClientRtdb, path: string, next: (value: unknown) => void, error?: (err: unknown) => void): Unsubscribe;
+export declare function rtdbSet(r: RtdbRefHandle, value: unknown): Promise<void>;
+export declare function rtdbUpdate(r: RtdbRefHandle, values: Record<string, unknown>): Promise<void>;
+export declare function rtdbRemove(r: RtdbRefHandle): Promise<void>;
+export declare function rtdbPush(r: RtdbRefHandle, value?: unknown): RtdbRefHandle & PromiseLike<RtdbRefHandle>;
+export declare function rtdbOnValue(r: RtdbRefHandle, next: (snap: RtdbDataSnapshot) => void, error?: (err: unknown) => void): Unsubscribe;
+export declare function rtdbOff(_r: RtdbRefHandle, _eventType?: unknown, _callback?: unknown): void;
+export declare function rtdbServerTimestamp(): {
+    readonly __rtdbSentinel: 'serverTimestamp';
+};
+export declare function rtdbConnectDatabaseEmulator(): void;
+/**
+ * Subscribe to the worker sandbox's unified event stream. The callback fires
+ * with each delivered BATCH of events — the FIRST call carries the initial
+ * `history()` snapshot (possibly empty), each subsequent call carries one live
+ * event. Returns an unsubscribe that deregisters on the worker.
+ *
+ * This is the live counterpart to `sandbox.onEvent` + an initial `history()`
+ * fold, collapsed into one subscription so a late subscriber never misses the
+ * backlog.
+ */
+export declare function subscribeEvents(db: ClientDb, callback: (events: readonly SandboxEvent[]) => void): Unsubscribe;
+/**
+ * Fetch the worker sandbox's event history as a one-shot snapshot (every event
+ * so far). Opens a transient stream sub, resolves with the initial history
+ * batch, and tears the sub down immediately — so it never holds a live
+ * subscription. Useful for a late, snapshot-only consumer.
+ */
+export declare function eventHistory(db: ClientDb): Promise<readonly SandboxEvent[]>;
+/** Push the active runtime confirm-policy to the worker (Pyric Studio F3). */
+export declare function setPolicy(db: ClientDb, policy: PolicyRequest): Promise<void>;
+/** Read the active runtime confirm-policy back (null until the dial set one). */
+export declare function getPolicy(db: ClientDb): Promise<PolicyRequest | null>;
+/**
+ * Export the current sandbox snapshot (Pyric Studio rules re-run). Studio forks
+ * it locally to test a denied op against edited rules or re-issue it as the
+ * attempting user, on a throwaway branch (no live mutation).
+ */
+export declare function getSnapshot(db: ClientDb): Promise<SandboxSnapshot>;
+/**
+ * Client-side User — a snapshot of the worker's `User` with token accessors
+ * that RPC back to the worker. Mirrors `firebase/auth`'s `User` shape.
+ */
+export interface ClientUser {
+    readonly uid: string;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+    readonly displayName: string | null;
+    readonly photoURL: string | null;
+    readonly phoneNumber: string | null;
+    readonly isAnonymous: boolean;
+    readonly providerId: string | null;
+    readonly providerData: SerializedUser['providerData'];
+    getIdToken(forceRefresh?: boolean): Promise<string>;
+    getIdTokenResult(forceRefresh?: boolean): Promise<SerializedIdTokenResult>;
+}
+/** Client-side UserCredential — mirrors `firebase/auth`. */
+export interface ClientUserCredential {
+    user: ClientUser;
+    providerId: string | null;
+    operationType: 'signIn' | 'reauthenticate' | 'link';
+}
+/**
+ * Client-side Auth handle. Holds the port + a local `currentUser` mirror.
+ * Returned by `getAuth(db | workerUrl)`. Mirrors `firebase/auth`'s `Auth`.
+ */
+export interface ClientAuth {
+    readonly __kind: 'client-auth';
+    readonly port: MessagePort;
+    /** Local mirror of the worker's currentUser, updated from the stream. */
+    currentUser: ClientUser | null;
+}
+/**
+ * Get the worker-backed Auth handle.
+ *
+ * Mirrors `pyric/auth`'s `getAuth(sandbox)` / `firebase/auth`'s
+ * `getAuth(app)` — but the input is either an existing `ClientDb` (reusing
+ * its port, the common case in serve where Firestore + auth share one
+ * worker) or a worker URL (standalone).
+ *
+ * The returned handle seeds its `currentUser` mirror by opening an internal
+ * authState subscription that keeps it live across tabs.
+ */
+export declare function getAuth(source: ClientDb | string | URL, name?: string): ClientAuth;
+/**
+ * Connect to the auth emulator. No-op shim over the worker: the worker's
+ * sandbox IS the emulator-equivalent backend, so there's nothing to point at.
+ * Present for surface parity so app code that calls it doesn't break.
+ */
+export declare function connectAuthEmulator(_auth: ClientAuth, _url: string, _options?: {
+    disableWarnings?: boolean;
+}): void;
+export declare function createUserWithEmailAndPassword(auth: ClientAuth, email: string, password: string): Promise<ClientUserCredential>;
+export declare function listUsers(auth: ClientAuth): Promise<AuthUserRecord[]>;
+export declare function adminCreateUser(auth: ClientAuth, request: CreateUserRequest): Promise<AuthUserRecord>;
+export declare function adminUpdateUser(auth: ClientAuth, uid: string, request: UpdateUserRequest): Promise<AuthUserRecord>;
+export declare function adminDeleteUser(auth: ClientAuth, uid: string): Promise<void>;
+export declare function adminClearUsers(auth: ClientAuth): Promise<void>;
+export declare function getProviderConfig(auth: ClientAuth): Promise<Array<{
+    providerId: string;
+    enabled: boolean;
+}>>;
+export declare function setProviderConfig(auth: ClientAuth, providerId: string, enabled: boolean): Promise<void>;
+export declare function signInWithEmailAndPassword(auth: ClientAuth, email: string, password: string): Promise<ClientUserCredential>;
+export declare function signInAnonymously(auth: ClientAuth): Promise<ClientUserCredential>;
+export declare function signOut(auth: ClientAuth): Promise<void>;
+/**
+ * Bridge a provider identity resolved IN-PAGE to the worker (the provider
+ * sign-in seam). The entry adapter's worker-path `signInWithPopup`/
+ * `signInWithRedirect` runs the in-page `AuthFlowResolver` (which can't cross
+ * the worker port), then calls this with the picked identity; the worker seeds
+ * it + signs it in, returning a worker-backed credential. The mirror updates
+ * eagerly (like the email/anon paths) so a synchronous `auth.currentUser`
+ * read right after the await reflects the new user.
+ */
+export declare function acceptProviderCredential(auth: ClientAuth, identity: ResolvedIdentity): Promise<ClientUserCredential>;
+/**
+ * Re-establish THIS PORT's session for an existing identity (#754) — the
+ * per-tab reload restore. The page persists its uid in web storage
+ * (SessionStore); runtime.ts calls this at boot BEFORE app code runs. Soft:
+ * returns null (and leaves the port signed out) when the uid no longer
+ * resolves, so a stale record never throws.
+ */
+export declare function restorePortSession(auth: ClientAuth, uid: string): Promise<ClientUser | null>;
+/** Persistence markers — mirror `firebase/auth` / `pyric/auth`. */
+export declare const inMemoryPersistence: {
+    readonly type: "NONE";
+};
+export declare const browserSessionPersistence: {
+    readonly type: "SESSION";
+};
+export declare const browserLocalPersistence: {
+    readonly type: "LOCAL";
+};
+export type ClientPersistence = {
+    readonly type: AuthPersistenceMode;
+};
+/**
+ * Record the session-persistence mode on the worker (surface parity). The
+ * effective persistence is CLIENT-side (#754): the entry adapter mirrors the
+ * mode into the page's SessionStore, which decides where — or whether — this
+ * tab's session uid is stored for reload restore.
+ */
+export declare function setPersistence(auth: ClientAuth, persistence: ClientPersistence): Promise<void>;
+/**
+ * Subscribe to auth-state changes. Mirrors `firebase/auth`'s
+ * `onAuthStateChanged`. Fires immediately with THIS PORT's current session,
+ * then on every change to it (#754: sessions are per-port — another tab's
+ * sign-in is a different user, not an update to this one). Updates the
+ * handle's `currentUser` mirror before invoking the callback.
+ */
+export declare function onAuthStateChanged(auth: ClientAuth, callback: (user: ClientUser | null) => void): Unsubscribe;
+/**
+ * Subscribe to ID-token changes. Mirrors `firebase/auth`'s
+ * `onIdTokenChanged` — fires on THIS PORT's identity transitions (per-port
+ * sessions, #754).
+ */
+export declare function onIdTokenChanged(auth: ClientAuth, callback: (user: ClientUser | null) => void): Unsubscribe;
+/** Top-level mirror of `firebase/auth`'s `getIdToken(user)`. */
+export declare function getIdToken(user: ClientUser, forceRefresh?: boolean): Promise<string>;
+/** Top-level mirror of `firebase/auth`'s `getIdTokenResult(user)`. */
+export declare function getIdTokenResult(user: ClientUser, forceRefresh?: boolean): Promise<SerializedIdTokenResult>;
+/**
+ * Top-level mirror of `firebase/auth`'s `updateProfile(user, profile)` over
+ * the worker. RPCs `auth.updateProfile` for THIS PORT's session (the worker
+ * owns the real `User`), then mutates the passed `user` mirror in place with
+ * the returned fields so a synchronous read right after the await is
+ * consistent. `null` clears a field; an absent field is left untouched.
+ *
+ * The port is recovered from the hidden {@link CLIENT_USER_PORT} handle stamped
+ * on every `ClientUser`, so this works without an `auth` handle in scope.
+ */
+export declare function updateProfile(user: ClientUser, profile: {
+    displayName?: string | null;
+    photoURL?: string | null;
+}): Promise<void>;
+/**
+ * Provider sign-in (`signInWithCredential`, `signInWithPopup`,
+ * `signInWithRedirect`) needs the AuthFlowResolver, which lives in-page and
+ * can't cross the worker port. NOT SUPPORTED over the SharedWorker in v1 —
+ * a clear error rather than silent breakage. Tracked as a Phase 2 follow-up:
+ * thread the resolver through, or run provider flows in-page and hand the
+ * resulting credential to the worker.
+ */
+export declare function signInWithCredential(): Promise<never>;
+/** Worker-backed Storage handle (carries the shared `MessagePort`). */
+export interface ClientFirebaseStorage {
+    readonly __kind: 'client-storage';
+    readonly port: MessagePort;
+}
+/** Worker-backed Storage reference (path + name; carries the port for ops). */
+export interface ClientStorageReference {
+    readonly __kind: 'storage-ref';
+    readonly port: MessagePort;
+    readonly fullPath: string;
+    readonly name: string;
+}
+/**
+ * Get the worker-backed Storage handle. Like `getAuth`, accepts an existing
+ * `ClientDb` (reusing its port) or a worker URL (standalone).
+ */
+export declare function getStorage(source: ClientDb | string | URL, name?: string): ClientFirebaseStorage;
+/** Build a Storage reference. Mirrors `pyric/storage`'s `ref(storage, path?)` /
+ *  `ref(parentRef, path)`. Client-side path math; no RPC. */
+export declare function ref(parent: ClientFirebaseStorage | ClientStorageReference, path?: string): ClientStorageReference;
+/** Enumerate immediate child items + sub-prefixes under a ref (Pyric Studio
+ *  data browse). The host enforces `read` rules on the scanned prefix. */
+export declare function listAll(reference: ClientStorageReference): Promise<{
+    items: ClientStorageReference[];
+    prefixes: ClientStorageReference[];
+}>;
+/** Read an object's metadata (Pyric Studio inspector). */
+export declare function getMetadata(reference: ClientStorageReference): Promise<FullMetadata>;
+/** Read an object's bytes as a Blob (Pyric Studio inspector preview).
+ *  MessagePort-only — a Blob cannot cross the JSON bridge relay. */
+export declare function getBlob(reference: ClientStorageReference): Promise<Blob>;
+/** Mirror of `pyric/storage`'s `SettableMetadata` (plain JSON on the wire). */
+export interface ClientSettableMetadata {
+    contentType?: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    customMetadata?: {
+        [key: string]: string;
+    };
+}
+/** Upload bytes at the reference's path (replaces existing content).
+ *  Mirrors `pyric/storage`'s `uploadBytes` result shape. */
+export declare function uploadBytes(reference: ClientStorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: ClientSettableMetadata): Promise<{
+    ref: ClientStorageReference;
+    metadata: FullMetadata;
+}>;
+/** Read an object's bytes (JSON-safe base64 op → `ArrayBuffer`). Mirrors
+ *  `pyric/storage`'s `getBytes`, including the optional client-side cap. */
+export declare function getBytes(reference: ClientStorageReference, maxDownloadSizeBytes?: number): Promise<ArrayBuffer>;
+/** Delete the object at the reference's path (idempotent — missing = no-op,
+ *  matching the sandbox backend's delete semantics). */
+export declare function deleteObject(reference: ClientStorageReference): Promise<void>;
+//# sourceMappingURL=client.d.ts.map