pyric-tools 0.1.0-alpha.7

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

@@ -0,0 +1,955 @@
+/**
+ * SharedWorker protocol — message types + wire serialization.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * All traffic between an in-page client and the SharedWorker host travels
+ * over a `MessagePort`. Structured clone handles the envelope (plain objects,
+ * numbers, strings). Firestore's special scalar types (Timestamp, Bytes,
+ * GeoPoint/LatLng) are NOT structured-cloneable as class instances — they
+ * must be serialized to plain marker objects for the port crossing and
+ * re-hydrated on the other side.
+ *
+ * We use the persistence serializer's codec for doc DATA:
+ *   serialize:   JSON.stringify(data)  — toJSON() on each wrapper emits a
+ *                marker shape ({ __type: 'timestamp', seconds, nanos } etc.)
+ *   deserialize: JSON.parse → rehydrateDocValue (from pyric/sandbox) — walks
+ *                the tree and reconstructs REAL class instances (Timestamp,
+ *                Bytes, LatLng) so instanceof checks and method calls work.
+ *
+ * This is the SAME codec the sandbox uses for IndexedDB persistence, so the
+ * wire format == the persistence format and values round-trip to real instances
+ * on BOTH sides of the port.
+ *
+ * Sentinels (serverTimestamp, increment, arrayUnion, arrayRemove, deleteField)
+ * are FieldValue objects that DO cross the port as plain marker objects that
+ * the worker's sandbox resolves natively — the sandbox sentinel-capture code
+ * recognizes them by shape.
+ *
+ * SURFACE SPLIT
+ * -------------
+ * Client-side only (never cross the port):
+ *   doc, collection, collectionGroup, query, where, and, or, orderBy, limit,
+ *   limitToLast, startAt, startAfter, endAt, endBefore
+ *   → return plain RefDescriptor / QueryDescriptor objects.
+ *   getFirestore → returns a ClientDb holding the MessagePort.
+ *
+ * Sentinels (client-side markers, resolved by the worker's sandbox):
+ *   serverTimestamp, increment, arrayUnion, arrayRemove, deleteField
+ *   → return SentinelMarker objects that embed in write data.
+ *
+ * Execution (RPC):
+ *   getDoc, getDocs, setDoc, updateDoc, deleteDoc, addDoc,
+ *   onSnapshot, getCountFromServer, runTransaction, writeBatch().commit()
+ */
+import type { AuthLens, SandboxEvent, DenialContext } from 'pyric/sandbox';
+/**
+ * A serializable reference to a Firestore document path. Produced by
+ * `doc()` on the client; embedded in op/sub messages for the worker to
+ * resolve against the real sandbox.
+ */
+export interface DocRef {
+    readonly __ref: 'doc';
+    readonly path: string;
+}
+/**
+ * A serializable reference to a collection path. Produced by `collection()`.
+ */
+export interface CollRef {
+    readonly __ref: 'collection';
+    readonly path: string;
+}
+/**
+ * A serializable collectionGroup descriptor. Produced by `collectionGroup()`.
+ */
+export interface GroupRef {
+    readonly __ref: 'group';
+    readonly collectionId: string;
+}
+/**
+ * A serializable query descriptor. Wraps a source ref with a constraint list.
+ * Constraints encode `where`/`orderBy`/`limit`/`limitToLast`/`startAt`/
+ * `startAfter`/`endAt`/`endBefore` as plain data so they can be rebuilt on
+ * the worker side by calling the pyric/firestore constraint factories.
+ */
+export interface QueryDescriptor {
+    readonly __ref: 'query';
+    readonly source: DocRef | CollRef | GroupRef;
+    readonly constraints: readonly QueryConstraintDescriptor[];
+}
+/**
+ * Plain data representation of a FILTER constraint — the subset of
+ * constraints valid at a query's top level AND inside composite `and`/`or`
+ * filters (orderBy/limit/cursors are not filters). Mirrors the modular SDK's
+ * `where()` / `and(...)` / `or(...)` composition: composites nest arbitrarily,
+ * and the worker rebuilds them with the pyric/firestore `and`/`or` factories.
+ */
+export type FilterConstraintDescriptor = {
+    kind: 'where';
+    field: string;
+    op: string;
+    value: unknown;
+} | {
+    kind: 'and';
+    filters: readonly FilterConstraintDescriptor[];
+} | {
+    kind: 'or';
+    filters: readonly FilterConstraintDescriptor[];
+};
+/** Plain data representation of a query constraint. */
+export type QueryConstraintDescriptor = FilterConstraintDescriptor | {
+    kind: 'orderBy';
+    field: string;
+    direction?: 'asc' | 'desc';
+} | {
+    kind: 'limit';
+    n: number;
+} | {
+    kind: 'limitToLast';
+    n: number;
+} | {
+    kind: 'startAt';
+    values: unknown[];
+    isSnapshot?: false;
+} | {
+    kind: 'startAfter';
+    values: unknown[];
+    isSnapshot?: false;
+} | {
+    kind: 'endAt';
+    values: unknown[];
+    isSnapshot?: false;
+} | {
+    kind: 'endBefore';
+    values: unknown[];
+    isSnapshot?: false;
+};
+export type TargetDescriptor = DocRef | CollRef | GroupRef | QueryDescriptor;
+/**
+ * Wire representation of a FieldValue sentinel. The worker's sandbox
+ * resolves these via FieldValue factories before writing — the sentinel
+ * objects themselves are structurally identical to what `pyric/sandbox/
+ * admin-compat`'s FieldValue class produces, so they round-trip naturally.
+ *
+ * We use a `__sentinel` discriminator instead of relying on class identity
+ * (class instances aren't reliably transferred across message ports as class
+ * instances — the structured clone algorithm produces plain objects).
+ */
+export type SentinelMarker = {
+    readonly __sentinel: 'serverTimestamp';
+} | {
+    readonly __sentinel: 'increment';
+    readonly n: number;
+} | {
+    readonly __sentinel: 'arrayUnion';
+    readonly values: unknown[];
+} | {
+    readonly __sentinel: 'arrayRemove';
+    readonly values: unknown[];
+} | {
+    readonly __sentinel: 'deleteField';
+};
+export declare function isSentinelMarker(v: unknown): v is SentinelMarker;
+/**
+ * Aggregate-field descriptor for the `aggregate` op. Structurally identical
+ * to `pyric/firestore`'s `AggregateField` (and to admin-compat's — the
+ * `pyric-admin` remote arm's `Query.aggregate({ count/sum/average })`
+ * surface), so specs cross the wire verbatim: plain JSON, no translation.
+ * The host rebuilds the query and runs `getAggregateFromServer`; the reply
+ * is `{ data: Record<alias, number | null> }` (empty-input `average` is
+ * `null`, matching the SDKs).
+ */
+export type AggregateFieldDescriptor = {
+    kind: 'count';
+} | {
+    kind: 'sum';
+    field: string;
+} | {
+    kind: 'average';
+    field: string;
+};
+/** Spec passed on the `aggregate` op — aliases become the result's keys. */
+export type AggregateSpecDescriptor = Record<string, AggregateFieldDescriptor>;
+export type WriteDescriptor = {
+    method: 'set';
+    path: string;
+    data: unknown;
+    options?: {
+        merge?: boolean;
+        mergeFields?: string[];
+    };
+} | {
+    method: 'update';
+    path: string;
+    data: unknown;
+} | {
+    method: 'delete';
+    path: string;
+};
+/**
+ * One entry in the read-set sent by the client on `txnCommit`.
+ *
+ * The client records every doc it read during `updateFn` (via `txn.get`)
+ * along with the serialized data it saw at read time (`data` is the
+ * `SerializedDocData` the worker returned, or `null` if the doc didn't
+ * exist). The worker re-reads each path inside a real sandbox transaction
+ * and deep-compares by re-serializing the current state to the same JSON
+ * form — any mismatch means another tab wrote the doc between our read and
+ * commit, so we abort and let the client retry `updateFn`.
+ */
+export interface TxnReadEntry {
+    /** Firestore path of the document that was read. */
+    path: string;
+    /**
+     * The serialized doc data seen by the client at read time.
+     * `null` means the document did not exist when the client read it.
+     */
+    data: SerializedDocData | null;
+}
+/**
+ * Wire representation of a signed-in `User`. The real `pyric/auth` `User`
+ * carries methods (`getIdToken`, `getIdTokenResult`) that don't survive
+ * structured clone, so the worker flattens the fields the client mirror
+ * needs into a plain object. Token accessors on the client re-RPC to the
+ * worker (the worker holds the one real user).
+ *
+ * `null` means "signed out" — there is no current user.
+ */
+export interface SerializedUser {
+    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: ReadonlyArray<{
+        readonly displayName: string | null;
+        readonly email: string | null;
+        readonly phoneNumber: string | null;
+        readonly photoURL: string | null;
+        readonly providerId: string;
+        readonly uid: string;
+    }>;
+}
+/**
+ * A provider identity resolved IN-PAGE (by the `ServeAuthHelper`'s
+ * popup/redirect picker) and handed to the worker for sign-in. Provider flows
+ * (`signInWithPopup`/`signInWithRedirect`) can't cross the worker port — the
+ * `AuthFlowResolver` lives in-page — so the page resolves the picked identity
+ * and bridges it here; the worker seeds it + `restoreSession`s it (no password
+ * — provider users never sign in with one). See `auth.acceptIdentity`.
+ */
+export interface ResolvedIdentity {
+    readonly uid: string;
+    readonly email: string | null;
+    readonly displayName: string | null;
+    readonly customClaims: Record<string, unknown>;
+    readonly providerId: string;
+}
+/** Wire form of a `UserCredential` returned by the sign-in/create ops. */
+export interface SerializedUserCredential {
+    readonly user: SerializedUser;
+    readonly providerId: string | null;
+    readonly operationType: 'signIn' | 'reauthenticate' | 'link';
+}
+/** Wire form of `getIdTokenResult()`. */
+export interface SerializedIdTokenResult {
+    readonly token: string;
+    readonly claims: Record<string, unknown>;
+    readonly expirationTime: string;
+    readonly issuedAtTime: string;
+    readonly authTime: string;
+    readonly signInProvider: string | null;
+}
+/**
+ * Flatten a live `pyric/auth` `User` (or `null`) into its wire form.
+ * Methods are dropped; only the structured fields cross the port.
+ */
+export declare function serializeUser(user: {
+    uid: string;
+    email: string | null;
+    emailVerified?: boolean;
+    displayName: string | null;
+    photoURL?: string | null;
+    phoneNumber?: string | null;
+    isAnonymous: boolean;
+    providerId?: string;
+    providerData?: ReadonlyArray<{
+        displayName: string | null;
+        email: string | null;
+        phoneNumber: string | null;
+        photoURL: string | null;
+        providerId: string;
+        uid: string;
+    }>;
+} | null): SerializedUser | null;
+/**
+ * Persistence mode for the worker's shared auth session.
+ * Mirrors `pyric/auth`'s `Persistence.type`. `'NONE'` (inMemoryPersistence)
+ * disables the IndexedDB session record so a full close does NOT keep the
+ * user signed in; `'LOCAL'` and `'SESSION'` both persist the session in
+ * this single-backend model (see SESSION/LOCAL collapse note in host.ts).
+ */
+export type AuthPersistenceMode = 'LOCAL' | 'SESSION' | 'NONE';
+/**
+ * The four `ConfirmPolicy` levels the bridge's governance engine recognises.
+ * Mirrors `pyric-tools/src/bridge/server/confirm-policy.ts`'s `ConfirmPolicy`
+ * and Studio's `permission-dial/policy.ts` — kept structurally identical so a
+ * `PolicyRequest` produced by the dial crosses the port without translation.
+ */
+export type ConfirmPolicy = 'never' | 'session' | 'always' | 'deny';
+/**
+ * Per-tool override knobs. Structurally identical to the bridge's
+ * `PolicyOverrides` (confirm-policy.ts) so `buildPolicyMap(base, overrides)`
+ * consumes a wire `PolicyRequest.overrides` verbatim.
+ */
+export interface PolicyOverrides {
+    autoApprove?: string[];
+    requireConfirm?: string[];
+    requireConfirmAll?: boolean;
+    fallback?: ConfirmPolicy;
+}
+/**
+ * The confirm-policy descriptor the permission dial pushes (Pyric Studio F3).
+ *
+ * Structurally identical to `@pyric/studio`'s `permission-dial/policy.ts`
+ * `PolicyRequest` — that module's `toPolicyRequest(mode)` produces exactly this
+ * shape, and it crosses the MessagePort unchanged (all plain JSON, no class
+ * instances). The worker stores the latest one (see the `set-policy` op + the
+ * host's runtime policy store) so a consumer can read back the active governance
+ * the served sandbox/agent runtime should honour.
+ *
+ * HONEST SCOPE NOTE (bridge-process limitation):
+ * The interactive confirm-policy that gates AGENT TOOL CALLS lives in the bridge
+ * — a SEPARATE node process (the MCP server), built once at bridge startup and
+ * held in a closure (`createInteractiveConfirmHandler`). The SharedWorker is
+ * browser-resident and does NOT host that handler, so `set-policy` here updates a
+ * WORKER-SIDE store (the source of truth Studio reflects + a future in-worker
+ * agent runtime would consult); it does NOT reach into a running bridge process.
+ * Pushing a live policy to an already-running bridge is a separate transport
+ * (an HTTP control route on `pyric dev`, or a bridge restart) and is out of
+ * scope for the worker data-plane. This store is the additive, honest seam.
+ */
+export interface PolicyRequest {
+    /** Which bridge mode the policy runs under. Studio v1 only emits `sandbox`. */
+    bridgeMode: 'sandbox' | 'prod';
+    /** Which base map the bridge builds from. */
+    base: 'sandbox' | 'prod-defaults';
+    /** Overrides merged onto the base. */
+    overrides: PolicyOverrides;
+    /** Fallback policy for tools not in the base map. */
+    fallback: ConfirmPolicy;
+}
+/**
+ * All one-shot operation messages share the `t:'op'` discriminator and a
+ * correlation `id` that the worker echoes back in the `res` reply.
+ */
+export type OpMessage = ({
+    t: 'op';
+    id: string;
+    method: 'getDoc';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'getDocs';
+    source: TargetDescriptor;
+} | {
+    t: 'op';
+    id: string;
+    method: 'setDoc';
+    path: string;
+    data: unknown;
+    options?: {
+        merge?: boolean;
+        mergeFields?: string[];
+    };
+} | {
+    t: 'op';
+    id: string;
+    method: 'updateDoc';
+    path: string;
+    data: unknown;
+} | {
+    t: 'op';
+    id: string;
+    method: 'deleteDoc';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'addDoc';
+    collectionPath: string;
+    data: unknown;
+} | {
+    t: 'op';
+    id: string;
+    method: 'count';
+    source: TargetDescriptor;
+} | {
+    t: 'op';
+    id: string;
+    method: 'aggregate';
+    source: TargetDescriptor;
+    spec: AggregateSpecDescriptor;
+} | {
+    t: 'op';
+    id: string;
+    method: 'batchCommit';
+    writes: WriteDescriptor[];
+} | {
+    t: 'op';
+    id: string;
+    method: 'txnCommit';
+    reads: TxnReadEntry[];
+    writes: WriteDescriptor[];
+} | {
+    t: 'op';
+    id: string;
+    method: 'setRules';
+    source: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'setFirestoreRules';
+    source: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'setDatabaseRules';
+    source: unknown;
+} | {
+    t: 'op';
+    id: string;
+    method: 'getActiveRules';
+    service?: 'firestore' | 'database';
+} | {
+    t: 'op';
+    id: string;
+    method: 'getRulesStatus';
+    service?: 'firestore' | 'database';
+} | {
+    t: 'op';
+    id: string;
+    method: 'admin.getDocument';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'admin.listDocuments';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'admin.setDocument';
+    path: string;
+    data: unknown;
+} | {
+    t: 'op';
+    id: string;
+    method: 'admin.deleteDocument';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'admin.readState';
+    path?: string;
+    maxDepth?: number;
+} | {
+    t: 'op';
+    id: string;
+    method: 'rtdb.get';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'rtdb.set';
+    path: string;
+    value: unknown;
+} | {
+    t: 'op';
+    id: string;
+    method: 'rtdb.update';
+    path: string;
+    values: Record<string, unknown>;
+} | {
+    t: 'op';
+    id: string;
+    method: 'rtdb.remove';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'rtdb.push';
+    path: string;
+    key: string;
+    value?: unknown;
+} | {
+    t: 'op';
+    id: string;
+    method: 'rtdb.adminSnapshot';
+} | {
+    t: 'op';
+    id: string;
+    method: 'listRootCollections';
+} | {
+    t: 'op';
+    id: string;
+    method: 'listSubcollections';
+    docPath: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.createUser';
+    email: string;
+    password: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.signInEmail';
+    email: string;
+    password: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.signInAnonymously';
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.signOut';
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.getIdToken';
+    forceRefresh?: boolean;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.getIdTokenResult';
+    forceRefresh?: boolean;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.setPersistence';
+    mode: AuthPersistenceMode;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.getCurrentUser';
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.updateProfile';
+    displayName?: string | null;
+    photoURL?: string | null;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.restorePortSession';
+    uid: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.acceptIdentity';
+    identity: ResolvedIdentity;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.listUsers';
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.adminCreateUser';
+    request: Record<string, unknown>;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.adminUpdateUser';
+    uid: string;
+    request: Record<string, unknown>;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.adminDeleteUser';
+    uid: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.adminClearUsers';
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.getProviderConfig';
+} | {
+    t: 'op';
+    id: string;
+    method: 'auth.setProviderConfig';
+    providerId: string;
+    enabled: boolean;
+} | {
+    t: 'op';
+    id: string;
+    method: 'storage.listAll';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'storage.getMetadata';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'storage.getBlob';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'storage.putBytes';
+    path: string;
+    dataB64: string;
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+} | {
+    t: 'op';
+    id: string;
+    method: 'storage.getBytes';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'storage.deleteObject';
+    path: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'getVersion';
+} | {
+    t: 'op';
+    id: string;
+    method: 'exportState';
+} | {
+    t: 'op';
+    id: string;
+    method: 'importState';
+    bundle: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'saveBranch';
+    name: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'listBranches';
+} | {
+    t: 'op';
+    id: string;
+    method: 'switchBranch';
+    name: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'deleteBranch';
+    name: string;
+} | {
+    t: 'op';
+    id: string;
+    method: 'setPolicy';
+    policy: PolicyRequest;
+} | {
+    t: 'op';
+    id: string;
+    method: 'getPolicy';
+} | {
+    t: 'op';
+    id: string;
+    method: 'getSnapshot';
+}) & {
+    /**
+     * Per-op auth lens (Pyric Studio): `admin` bypasses rules, `{ as: uid }`
+     * evaluates rules as that user (impersonation), `anon` runs genuinely
+     * UNAUTHENTICATED (`withAuth(null)` — the remote arm's "no auth", which an
+     * absent lens does NOT mean: absent ⇒ the app's session, i.e. whoever the
+     * browser tab is signed in as). The host resolves the data handle from
+     * this — see `lensDb` in `host.ts`. Additive: existing senders omit it.
+     * Plain tagged union → structured-clones.
+     */
+    actAs?: AuthLens;
+    /**
+     * MECHANICAL op provenance (Pyric Studio traffic attribution): the
+     * client that CONSTRUCTS this op declares who issued it. The host maps
+     * it onto the unified event stream's `actor` field (`{ kind: 'studio' }`)
+     * via the sandbox's ambient-provenance window, so Traffic can filter
+     * Studio's own viewer/editor noise out of the app's stream.
+     *
+     * Declared at the issuing call site, never inferred: Studio's worker
+     * client stamps it on every op it builds (see `setOpIssuer` in
+     * `client.ts`); the bridge relay (`relayWorkerOp`) forwards remote
+     * frames VERBATIM without stamping, so a user's own admin-SDK traffic
+     * through the remote bridge — which also rides this port when Studio
+     * holds the peer slot — is never mislabeled as Studio's. Additive:
+     * existing senders omit it (events default to `actor: { kind: 'app' }`).
+     */
+    issuer?: 'studio';
+};
+/** Register a Firestore snapshot listener for a doc or query. The worker
+ *  fires `{ t:'snap', subId, value }` immediately (initial) and on each
+ *  update. */
+export interface FirestoreSubMessage {
+    t: 'sub';
+    subId: string;
+    target: TargetDescriptor;
+    /**
+     * Per-subscription auth lens (Pyric Studio F4 — "watch as user"). Mirrors
+     * the per-op `actAs` on {@link OpMessage}: `{ mode: 'as', uid }` registers the
+     * listener through the impersonation data handle so the snapshot's initial
+     * fire AND every re-eval evaluate security rules AS that uid; `{ mode: 'admin' }`
+     * watches through the rule-bypass handle; `{ mode: 'anon' }` watches genuinely
+     * unauthenticated (`withAuth(null)`); absent / `{ mode: 'app-session' }`
+     * watches as the app's own session (the unchanged default).
+     *
+     * The host resolves the listener's data handle from this via the SAME
+     * `lensDb` path ops use (`host.ts`), so "re-run a denied watch as the user who
+     * hit it" reuses the impersonation seam. Additive: existing senders omit it,
+     * so the wire message is byte-identical and existing subs don't regress.
+     */
+    actAs?: AuthLens;
+    /** Mechanical op provenance — see the field's doc on {@link OpMessage}.
+     *  Tags the listener's REGISTRATION events (the initial rules eval); the
+     *  listener's deferred re-evals stay attributed to the app (they fire on
+     *  the microtask drain, outside any provenance window). */
+    issuer?: 'studio';
+}
+/**
+ * Register an AUTH listener (cross-tab auth — the headline of Phase 2).
+ *
+ * `target: 'authState'` mirrors `onAuthStateChanged`; `target: 'idToken'`
+ * mirrors `onIdTokenChanged`. The worker registers ONE real sandbox auth
+ * listener and fans out the new current user to EVERY subscribed port —
+ * so a sign-in on any tab updates every tab live. The `snap.value` is a
+ * `SerializedUser | null` (signed-out → null).
+ */
+export interface AuthSubMessage {
+    t: 'sub';
+    subId: string;
+    target: 'authState' | 'idToken';
+}
+/**
+ * Subscribe to the sandbox's unified cross-service EVENT STREAM (Pyric Studio
+ * keystone — Action Center / traffic / rules-debug denial feed).
+ *
+ * `target: 'events'` mirrors `sandbox.onEvent(cb)`. On subscribe the host
+ * immediately delivers `sandbox.history()` (every event so far) as ONE
+ * `{ t:'event', subId, events: [...] }` batch, then streams each subsequent
+ * `SandboxEvent` as a single-element batch. Multiple Studio/app ports may
+ * subscribe; the host owns the ONE sandbox + ONE `onEvent` subscription and
+ * fans out to every subscribed port (same pattern as auth fan-out).
+ *
+ * Every `SandboxEvent` is plain JSON (provenance-stamped, marker-shaped doc
+ * data — no class instances), so it structured-clones across the port verbatim;
+ * no codec round-trip is needed (unlike Firestore doc data).
+ */
+export interface EventSubMessage {
+    t: 'sub';
+    subId: string;
+    target: 'events';
+}
+export interface RtdbValueSubMessage {
+    t: 'sub';
+    subId: string;
+    target: {
+        service: 'rtdb';
+        path: string;
+    };
+    /** Mirrors Firestore subscriptions: absent/app-session uses this port's session. */
+    actAs?: AuthLens;
+    /** Mechanical op provenance — see the field's doc on {@link OpMessage}. */
+    issuer?: 'studio';
+}
+export type SubMessage = FirestoreSubMessage | AuthSubMessage | EventSubMessage | RtdbValueSubMessage;
+/** Type guard: is this an auth subscription (vs a Firestore / event one)? */
+export declare function isAuthSub(msg: SubMessage): msg is AuthSubMessage;
+/** Type guard: is this an event-stream subscription? */
+export declare function isEventSub(msg: SubMessage): msg is EventSubMessage;
+export declare function isRtdbSub(msg: SubMessage): msg is RtdbValueSubMessage;
+/** Tear down a previously registered snapshot listener. */
+export interface UnsubMessage {
+    t: 'unsub';
+    subId: string;
+}
+/**
+ * Agent tool-call, forwarded by the bridge peer to the worker so the agent
+ * executes against the SAME sandbox the app + Studio use (no separate in-page
+ * backend). The worker host runs the canonical sandbox tool dispatcher and
+ * replies with a `ResMessage` whose `value` is the `{ ok, summary, data }`
+ * dispatch result. Keeps app, Studio, and agent on one authoritative instance.
+ */
+export interface ToolMessage {
+    t: 'tool';
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export type InboundMessage = OpMessage | SubMessage | UnsubMessage | ToolMessage;
+/**
+ * Reply to a one-shot op. `value` is present on success; `error` on failure.
+ *
+ * `value` shapes by method:
+ *   getDoc   → { id, path, exists, data?: SerializedDocData }
+ *   getDocs  → { docs: Array<{ id, path, data: SerializedDocData }> }
+ *   setDoc / updateDoc / deleteDoc / setRules → null (ack)
+ *   addDoc   → { id, path }   (the minted document id + full path)
+ *   count    → { count: number }
+ *   batchCommit / txnCommit → null (ack)
+ */
+export type ResMessage = {
+    t: 'res';
+    id: string;
+    ok: true;
+    value: unknown;
+} | {
+    t: 'res';
+    id: string;
+    ok: false;
+    error: SerializedError;
+};
+/**
+ * Streamed snapshot delivery. `value` is the same shape as `getDoc`/`getDocs`
+ * result above but always present (not null) — listeners always fire with data.
+ *
+ * For a doc listener: `{ id, path, exists, data?: SerializedDocData }`
+ * For a query listener: `{ docs: Array<{ id, path, data: SerializedDocData }> }`
+ */
+export interface SnapMessage {
+    t: 'snap';
+    subId: string;
+    value: unknown;
+}
+/**
+ * Streamed delivery for an event-stream subscription ({@link EventSubMessage}).
+ *
+ * Carries a BATCH of `SandboxEvent`s for the given `subId`:
+ *   - the FIRST message after subscribe is the initial `sandbox.history()`
+ *     snapshot (possibly empty);
+ *   - each subsequent message is a single live event (`events.length === 1`).
+ *
+ * A batch keeps the initial history one structured-clone instead of N, and lets
+ * the client fold history then stream uniformly. Events are plain JSON — no
+ * rehydration needed (see {@link EventSubMessage}).
+ */
+export interface EventStreamMessage {
+    t: 'event';
+    subId: string;
+    events: readonly SandboxEvent[];
+}
+export type OutboundMessage = ResMessage | SnapMessage | EventStreamMessage;
+/**
+ * Document data as it crosses the port: Timestamp/Bytes/LatLng/etc. are
+ * serialized to their JSON marker shapes so they survive structured clone,
+ * then rehydrated back to REAL class instances on the receiving side.
+ *
+ * Wire format == persistence format: we use the same codec the sandbox uses
+ * for IndexedDB persistence (`serializeSnapshot` / `deserializeSnapshot` in
+ * `pyric/sandbox`). Concretely:
+ *
+ *   serialize:   JSON.stringify(data)  — each wrapper's toJSON() emits a
+ *                marker shape ({ __type: 'timestamp', seconds, nanos } etc.)
+ *   deserialize: JSON.parse → rehydrateDocValue — re-wraps every marker
+ *                shape into a real class instance (Timestamp, Bytes, LatLng).
+ *
+ * WHY REAL INSTANCES MATTER:
+ * Consumer code does `snap.data().createdAt.toDate()`, `instanceof Timestamp`,
+ * `bytes.data`, etc. Plain marker objects don't have those methods/prototype.
+ * The persistence serializer's `rehydrateDocValue` is the canonical codec that
+ * the sandbox already relies on — reusing it here ensures the wire format and
+ * the persistence format are identical and don't drift.
+ *
+ * WHY JSON AND NOT STRUCTURED CLONE FOR DATA:
+ * Structured clone can transfer Uint8Arrays, but class instances of pyric's
+ * Timestamp/Bytes/LatLng are NOT in the structured clone spec — they'd arrive
+ * as plain objects and lose their prototype chain, breaking instanceof checks.
+ */
+export interface SerializedDocData {
+    /** JSON string of the document data (Timestamp/Bytes/LatLng serialized via toJSON). */
+    json: string;
+}
+/**
+ * Serialize document data to cross-port form.
+ *
+ * Uses `JSON.stringify` which calls `toJSON()` on each Timestamp, Bytes,
+ * LatLng, etc., producing the canonical marker shapes. This is identical to
+ * what `serializeSnapshot` does for the Firestore state before IDB writes.
+ */
+export declare function serializeDocData(data: Record<string, unknown>): SerializedDocData;
+/**
+ * Deserialize document data from cross-port form.
+ *
+ * Parses the JSON string and walks the result with `rehydrateDocValue`
+ * (from `pyric/sandbox`) to restore REAL class instances — the same codec
+ * `deserializeSnapshot` uses when restoring from IDB. After this call,
+ * Timestamp values are real `Timestamp` instances with `.seconds`/`.nanos`,
+ * Bytes values have `.data` (Uint8Array), LatLng values have `.lat`/`.lng`.
+ *
+ * Disambiguation: a plain user object `{ seconds: 1, nanoseconds: 0 }` is
+ * NOT mistaken for a Timestamp because the marker-based codec requires the
+ * `__type: 'timestamp'` discriminator emitted by `Timestamp.toJSON()`. Raw
+ * plain objects that happen to have numeric fields are passed through as-is.
+ */
+export declare function deserializeDocData(serialized: SerializedDocData): unknown;
+/**
+ * Maximum RAW byte size a single storage op may carry (`storage.putBytes`
+ * payloads and `storage.getBytes` results). 8 MiB raw ≈ 11 MiB base64 —
+ * comfortably under `ws`'s 100 MiB default `maxPayload` while keeping the
+ * four-hop whole-object buffering (Node → bridge → page → worker and back)
+ * sane. Enforced on BOTH ends: the Node conveniences / pyric-admin remote
+ * arm reject before sending, and the worker host rejects oversized inputs
+ * and results so a big browser-side object can't blow up the relay. Bigger
+ * objects need the (unshipped) streaming story — do not raise the cap.
+ */
+export declare const MAX_STORAGE_OP_BYTES: number;
+/** Base64 length ceiling for a payload within {@link MAX_STORAGE_OP_BYTES} —
+ *  a cheap pre-decode gate so an oversized `dataB64` is rejected without
+ *  materializing its bytes first. */
+export declare const MAX_STORAGE_OP_B64_LENGTH: number;
+/** Build the canonical over-cap error (`code: 'payload-too-large'`). */
+export declare function storagePayloadTooLarge(sizeBytes: number, what: string): Error & {
+    code: string;
+};
+/**
+ * Encode bytes to standard base64. Chunked `String.fromCharCode` so a
+ * multi-MiB payload doesn't overflow the argument-spread limit. `btoa` is
+ * available in browsers, workers, Node ≥ 16, and Bun.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decode standard base64 to bytes (inverse of {@link bytesToBase64}). */
+export declare function base64ToBytes(b64: string): Uint8Array;
+/**
+ * Wire form of a thrown error. `denialContext` (spike gap 6) is the
+ * structured "why did this deny" frame `SandboxError` carries on
+ * `permission-denied` — plain JSON end to end (rule line/expression, auth
+ * state, simulator reasons, eval-time request shape), so it survives both
+ * structured clone AND the JSON WS relay legs verbatim. Receivers re-attach
+ * it to the reconstructed error so remote `SandboxError`s match local ones.
+ */
+export interface SerializedError {
+    code: string;
+    message: string;
+    denialContext?: DenialContext;
+}
+/**
+ * Serialize any thrown value to a `{ code, message, denialContext? }` shape
+ * suitable for structured-clone across the MessagePort (and the JSON relay).
+ *
+ * SandboxError (from pyric/sandbox) carries `.code` (e.g. 'permission-denied')
+ * and `.message`, plus `.denialContext` on rule denials — carried through
+ * whenever present. All other errors get `code: 'unknown'`. Plain strings get
+ * `code: 'unknown'` and `message: String(err)`.
+ *
+ * Class instances don't survive structured clone as their original class —
+ * the receiver sees a plain object. We normalize so the client can
+ * reconstruct a typed error with `.code` (and `.denialContext`) attached.
+ */
+export declare function serializeError(err: unknown): SerializedError;
+//# sourceMappingURL=protocol.d.ts.map