@pyric/cli 0.1.0-alpha.10

package/dist/serve/worker/host/firestore-reads.js

@@ -0,0 +1,108 @@
+/**
+ * SharedWorker host — Firestore read + aggregate + keyspace ops.
+ *
+ * The rule-gated read surface: `getDoc`/`getDocs`, the `count`/`aggregate`
+ * server aggregations, and the lens-independent keyspace enumeration
+ * (`listRootCollections`/`listSubcollections`, the Pyric Studio data browse).
+ *
+ * Routed here by the host dispatcher (host/dispatch.ts) with the op's resolved
+ * Firestore handle (`db` — already lens/session-resolved). This module never
+ * imports the dispatcher; it leans only on host-context + host/core.
+ */
+import { doc as pyricDoc, getDoc, getDocs, getCountFromServer, getAggregateFromServer, } from 'pyric/firestore';
+import { getInternalEnv } from 'pyric/sandbox/internal';
+import { ok, fail } from '../host-context.js';
+import { resolveTarget, serializeDocSnap } from './core.js';
+/** The read/aggregate/keyspace op methods routed to {@link handleFirestoreReadOp}. */
+const READ_METHODS = new Set([
+    'getDoc',
+    'getDocs',
+    'count',
+    'aggregate',
+    'listRootCollections',
+    'listSubcollections',
+]);
+export function isFirestoreReadOp(method) {
+    return READ_METHODS.has(method);
+}
+export async function handleFirestoreReadOp(ctx, port, msg, db) {
+    const { sandbox } = ctx;
+    switch (msg.method) {
+        case 'getDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                const snap = await getDoc(ref);
+                ok(port, msg.id, serializeDocSnap(snap));
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'getDocs': {
+            try {
+                const source = resolveTarget(db, msg.source);
+                // CollectionReference is always also queryable — getDocs accepts Query<T>
+                // and CollectionReference is structurally compatible at runtime even though
+                // the type system doesn't know that (CollectionReference has no `_isQuery`
+                // brand). Cast through Query to satisfy the type checker.
+                const snap = await getDocs(source);
+                const docs = snap.docs.map((d) => serializeDocSnap(d));
+                ok(port, msg.id, { docs });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'count': {
+            try {
+                const source = resolveTarget(db, msg.source);
+                const snap = await getCountFromServer(source);
+                ok(port, msg.id, { count: snap.data().count });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'aggregate': {
+            // Multi-field aggregates (count/sum/average). The wire spec is
+            // structurally pyric/firestore's AggregateSpec, so it passes straight
+            // through; the reply data is plain numbers / null (empty-input average).
+            try {
+                const source = resolveTarget(db, msg.source);
+                const snap = await getAggregateFromServer(source, msg.spec);
+                ok(port, msg.id, { data: snap.data() });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'listRootCollections': {
+            // Keyspace enumeration (Pyric Studio data browse). Lens-independent: it
+            // lists the collection ids present, not rule-gated reads.
+            try {
+                ok(port, msg.id, { ids: getInternalEnv(sandbox).listRootCollections() });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'listSubcollections': {
+            try {
+                ok(port, msg.id, { ids: getInternalEnv(sandbox).listSubcollections(msg.docPath) });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        default: {
+            fail(port, msg.id, new Error(`Unknown method: ${String(msg.method)}`));
+        }
+    }
+}
+//# sourceMappingURL=firestore-reads.js.map

package/dist/serve/worker/host/firestore-reads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-reads.js","sourceRoot":"","sources":["../../../../src/serve/worker/host/firestore-reads.ts"],"names":[],"mappings":"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"}

package/dist/serve/worker/host/firestore-writes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SharedWorker host — Firestore write ops (single writes + batch + transaction).
+ *
+ * `setDoc`/`updateDoc`/`deleteDoc`/`addDoc`, the all-or-nothing `batchCommit`,
+ * and the full-fidelity `txnCommit` (read-set validation for multi-tab
+ * correctness). Owns the write-payload preparation helpers: sentinel
+ * reconstruction + marker rehydration (`prepareWriteData`), the batch-write
+ * applier, and the transaction read-set canonicalizer.
+ *
+ * Routed here by the host dispatcher (host/dispatch.ts) with the op's resolved
+ * Firestore handle (`db`). Never imports the dispatcher.
+ */
+import { type Firestore } from 'pyric/firestore';
+import type { OpMessage } from '../protocol.js';
+import { type HostCtx, type PortLike } from '../host-context.js';
+/**
+ * Prepare an incoming WRITE payload for the sandbox: rehydrate marker-shaped
+ * scalars into REAL wrapper instances, then rebuild FieldValue sentinels.
+ *
+ * WHY REHYDRATE WRITES (spike gap 4): over the JSON relay legs a Node-side
+ * `Timestamp`/`Bytes`/`GeoPoint` arrives as its `toJSON()` marker
+ * (`{ type: 'firestore/timestamp/1.0', … }` or `{ __type: 'timestamp', … }`).
+ * Without rehydration the worker STORES the marker as a plain map — reads
+ * mask the bug (the read path rehydrates), but in-worker rules comparisons
+ * and `orderBy` over that field see a map, not a timestamp. `rehydrateDocValue`
+ * is the same canonical codec the read path / persistence uses, so the wire,
+ * store, and IDB formats stay one format.
+ *
+ * Order matters: rehydration first (it passes `__sentinel` markers through
+ * as plain objects, rehydrating any marker-shaped values nested inside
+ * arrayUnion/arrayRemove), then sentinel resolution (which now skips the
+ * freshly rehydrated class instances — see resolveSentinels).
+ */
+export declare function prepareWriteData(value: unknown): unknown;
+export declare function isFirestoreWriteOp(method: OpMessage['method']): boolean;
+export declare function handleFirestoreWriteOp(ctx: HostCtx, port: PortLike, msg: OpMessage, db: Firestore): Promise<void>;
+//# sourceMappingURL=firestore-writes.d.ts.map

package/dist/serve/worker/host/firestore-writes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-writes.d.ts","sourceRoot":"","sources":["../../../../src/serve/worker/host/firestore-writes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAcL,KAAK,SAAS,EAGf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,SAAS,EAAiD,MAAM,gBAAgB,CAAC;AAE/F,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAmC,MAAM,oBAAoB,CAAC;AA4ClG;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAExD;AA8ED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,OAAO,CAEvE;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,SAAS,EACd,EAAE,EAAE,SAAS,GACZ,OAAO,CAAC,IAAI,CAAC,CA4Qf"}

package/dist/serve/worker/host/firestore-writes.js

@@ -0,0 +1,409 @@
+/**
+ * SharedWorker host — Firestore write ops (single writes + batch + transaction).
+ *
+ * `setDoc`/`updateDoc`/`deleteDoc`/`addDoc`, the all-or-nothing `batchCommit`,
+ * and the full-fidelity `txnCommit` (read-set validation for multi-tab
+ * correctness). Owns the write-payload preparation helpers: sentinel
+ * reconstruction + marker rehydration (`prepareWriteData`), the batch-write
+ * applier, and the transaction read-set canonicalizer.
+ *
+ * Routed here by the host dispatcher (host/dispatch.ts) with the op's resolved
+ * Firestore handle (`db`). Never imports the dispatcher.
+ */
+import { doc as pyricDoc, collection as pyricCollection, setDoc, updateDoc, deleteDoc, addDoc, runTransaction, writeBatch, serverTimestamp, increment, arrayUnion, arrayRemove, deleteField, } from 'pyric/firestore';
+import { rehydrateDocValue } from 'pyric/firestore-values';
+import { serializeDocData, isSentinelMarker } from '../protocol.js';
+import { post, ok, fail, bestEffortFlush } from '../host-context.js';
+// ─── Sentinel resolution ──────────────────────────────────────────────────
+/**
+ * Walk a write payload and replace every `SentinelMarker` with the
+ * corresponding pyric/firestore FieldValue sentinel object.
+ *
+ * WHY: FieldValue class instances don't survive structured clone — they
+ * arrive as plain objects and lose their prototype, breaking sandbox
+ * sentinel detection. The client sends `{ __sentinel: 'serverTimestamp' }`
+ * etc. and we reconstruct the real FieldValue here before the sandbox sees
+ * the data.
+ *
+ * The sandbox's sentinel-capture code (sentinel-capture.ts) recognizes
+ * FieldValue objects by their internal `__type` property, which the
+ * factories produce correctly.
+ */
+function resolveSentinels(value) {
+    if (isSentinelMarker(value)) {
+        return resolveSentinel(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(resolveSentinels);
+    }
+    if (value !== null && typeof value === 'object') {
+        // Leave CLASS instances intact (Timestamp/Bytes/LatLng rehydrated by
+        // prepareWriteData below, or FieldValue objects): walking their entries
+        // into a plain object would strip the prototype the sandbox keys on.
+        // Sentinel markers only ever live in plain JSON containers.
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            return value;
+        }
+        const obj = value;
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            out[k] = resolveSentinels(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Prepare an incoming WRITE payload for the sandbox: rehydrate marker-shaped
+ * scalars into REAL wrapper instances, then rebuild FieldValue sentinels.
+ *
+ * WHY REHYDRATE WRITES (spike gap 4): over the JSON relay legs a Node-side
+ * `Timestamp`/`Bytes`/`GeoPoint` arrives as its `toJSON()` marker
+ * (`{ type: 'firestore/timestamp/1.0', … }` or `{ __type: 'timestamp', … }`).
+ * Without rehydration the worker STORES the marker as a plain map — reads
+ * mask the bug (the read path rehydrates), but in-worker rules comparisons
+ * and `orderBy` over that field see a map, not a timestamp. `rehydrateDocValue`
+ * is the same canonical codec the read path / persistence uses, so the wire,
+ * store, and IDB formats stay one format.
+ *
+ * Order matters: rehydration first (it passes `__sentinel` markers through
+ * as plain objects, rehydrating any marker-shaped values nested inside
+ * arrayUnion/arrayRemove), then sentinel resolution (which now skips the
+ * freshly rehydrated class instances — see resolveSentinels).
+ */
+export function prepareWriteData(value) {
+    return resolveSentinels(rehydrateDocValue(value));
+}
+function resolveSentinel(marker) {
+    switch (marker.__sentinel) {
+        case 'serverTimestamp': return serverTimestamp();
+        case 'increment': return increment(marker.n);
+        case 'arrayUnion': return arrayUnion(...marker.values);
+        case 'arrayRemove': return arrayRemove(...marker.values);
+        case 'deleteField': return deleteField();
+    }
+}
+// ─── Transaction read-set canonicalization helpers ─────────────────────────
+/**
+ * Rebuild a JSON-flattened `Uint8Array` (an index-keyed `{ "0": n, … }`
+ * map) and encode it as base64url without padding — the exact form
+ * `pyric/rules`' `Bytes.toBase64()` emits. Backs the transaction read-set
+ * canonicalizer's handling of prototype-stripped `Bytes` clones.
+ */
+/** Timestamp/Duration stripped-clone key set (they share field names). */
+const TS_CLONE_KEYS = ['typeName', 'seconds', 'nanos'];
+/** Does `o` carry EXACTLY these own enumerable keys (no more, no fewer)?
+ *  Backs the transaction canonicalizer's strict clone-shape matching. */
+function hasExactKeys(o, keys) {
+    const own = Object.keys(o);
+    return own.length === keys.length && keys.every((k) => k in o);
+}
+function indexMapToBase64Url(data) {
+    const map = (data ?? {});
+    const keys = Object.keys(map);
+    const bytes = new Uint8Array(keys.length);
+    for (let i = 0; i < keys.length; i++)
+        bytes[i] = map[String(i)] ?? 0;
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function applyWriteToBatch(db, batch, w) {
+    const b = batch;
+    const ref = pyricDoc(db, w.path);
+    if (w.method === 'set') {
+        const data = prepareWriteData(w.data);
+        b.set(ref, data, w.options);
+    }
+    else if (w.method === 'update') {
+        const data = prepareWriteData(w.data);
+        b.update(ref, data);
+    }
+    else if (w.method === 'delete') {
+        b.delete(ref);
+    }
+}
+// ─── Op handler ────────────────────────────────────────────────────────────
+/** The write op methods routed to {@link handleFirestoreWriteOp}. */
+const WRITE_METHODS = new Set([
+    'setDoc',
+    'updateDoc',
+    'deleteDoc',
+    'addDoc',
+    'batchCommit',
+    'txnCommit',
+]);
+export function isFirestoreWriteOp(method) {
+    return WRITE_METHODS.has(method);
+}
+export async function handleFirestoreWriteOp(ctx, port, msg, db) {
+    switch (msg.method) {
+        case 'setDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                const data = prepareWriteData(msg.data);
+                await setDoc(ref, data, msg.options);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'updateDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                const data = prepareWriteData(msg.data);
+                await updateDoc(ref, data);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'deleteDoc': {
+            try {
+                const ref = pyricDoc(db, msg.path);
+                await deleteDoc(ref);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'addDoc': {
+            try {
+                const coll = pyricCollection(db, msg.collectionPath);
+                const data = prepareWriteData(msg.data);
+                const ref = await addDoc(coll, data);
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, { id: ref.id, path: ref.path });
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'batchCommit': {
+            /**
+             * WHY: writeBatch in pyric/firestore buffers set/update/delete calls
+             * and commits them as one unit through the sandbox backend. We
+             * reconstruct the batch here from the wire write descriptors.
+             * Atomicity guarantee: the sandbox backend applies all writes or none
+             * (per-collection lock semantics of LocalEnvironment.batch()).
+             */
+            try {
+                const batch = writeBatch(db);
+                for (const w of msg.writes) {
+                    applyWriteToBatch(db, batch, w);
+                }
+                await batch.commit();
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                fail(port, msg.id, e);
+            }
+            break;
+        }
+        case 'txnCommit': {
+            /**
+             * READ-SET VALIDATION FOR MULTI-TAB CORRECTNESS
+             * -----------------------------------------------
+             * The client sends `{ method: 'txnCommit', reads, writes }` after its
+             * `updateFn` callback has resolved. `reads` is the set of docs the
+             * client read during `updateFn` (each entry is `{ path, data }` where
+             * `data` is the serialized snapshot the client saw, or null if the doc
+             * was missing).
+             *
+             * WHY READ-SET VALIDATION IS NECESSARY
+             * -------------------------------------
+             * A transaction spans two messages: the client's `txn.get` RPC (sent
+             * during `updateFn`) and this `txnCommit` RPC. Between those messages
+             * the event loop is free — another tab's write to any of the read docs
+             * can land in that gap via a separate `setDoc` message. Without
+             * validation that would be a silent lost update: the client computed
+             * its writes using stale data, committed them, and the other tab's
+             * changes were silently overwritten.
+             *
+             * HOW WE VALIDATE (no per-doc version/updateTime in the sandbox)
+             * ---------------------------------------------------------------
+             * Inside a real `runTransaction(db, callback)`, the callback re-reads
+             * every doc from the read-set via `tx.get(ref)`, serializes its current
+             * data to the same JSON form the client produced (using `serializeDocData`
+             * on both sides), and compares the JSON strings. If any doc's current
+             * serialized form differs from what the client recorded, another tab
+             * wrote it between the client's read and this commit — we throw an abort
+             * sentinel so the sandbox rolls back the transaction, and we return
+             * `{ ok: false, error: { code: 'aborted' } }` on the wire. The client's
+             * retry loop then re-runs `updateFn` with fresh reads.
+             *
+             * SERIALIZED-FORM EQUALITY — VIA THE CANONICAL CODEC
+             * ---------------------------------------------------
+             * Both JSON strings are CANONICALIZED before comparison:
+             * `JSON.stringify(rehydrateDocValue(JSON.parse(json)))`. Raw string
+             * equality is NOT safe here even within one process, because the two
+             * read paths yield DIFFERENT wrapper classes for the same stored
+             * value: `getDoc` (what the client's read-set echoes) returns
+             * `firebase/firestore` classes whose `Timestamp.toJSON()` emits
+             * `{ seconds, nanoseconds, type }`, while the transaction's
+             * validation re-read comes through the admin-compat wrapper whose
+             * `Timestamp.toJSON()` emits `{ type, seconds, nanoseconds }` — same
+             * value, different key order, different string. Rehydrating both
+             * sides through the ONE shared codec (`pyric/firestore-values`)
+             * collapses every marker family into the same wrapper classes with
+             * deterministic `toJSON()` key order, so string equality ↔ value
+             * equality again — an unmodified doc can never phantom-abort (which
+             * would livelock the client's retry loop), while a real concurrent
+             * write still mismatches. Plain-map key order is preserved by both
+             * paths from the same stored object, so it stays comparable.
+             *
+             * NOTE ON tx.set/update/delete SIGNATURE
+             * ---------------------------------------
+             * The modular pyric/firestore Transaction (wrapping the admin-compat
+             * TransactionWrapper) takes `tx.set(docRef, data)` where `docRef` is a
+             * real `DocumentReference` — NOT a path string. We build refs via
+             * `pyricDoc(db, path)` for each write.
+             */
+            /** Sentinel thrown inside the transaction callback to signal an abort. */
+            const TXN_ABORT = Symbol('txn-abort');
+            /**
+             * Canonicalize a serialized doc-data JSON string (see
+             * SERIALIZED-FORM EQUALITY above). Two normalization passes:
+             *
+             *   1. `rehydrateDocValue` collapses the marker families (`__type`
+             *      persistence markers and `firebase/firestore` `toJSON()`
+             *      markers) into the one set of wrapper classes, whose
+             *      `toJSON()` re-emits a single deterministic form.
+             *   2. The stringify replacer additionally normalizes PROTOTYPE-
+             *      STRIPPED wrapper clones — the sandbox transaction's
+             *      capture-by-value `structuredClone` turns a stored rules
+             *      wrapper into a plain `{ typeName, … }` object that neither
+             *      marker family matches, so without this pass an unmodified
+             *      typed doc would never compare equal to the client's getDoc
+             *      echo (a guaranteed phantom abort → retry livelock).
+             */
+            const canonicalDocJson = (json) => JSON.stringify(rehydrateDocValue(JSON.parse(json)), (_key, v) => {
+                if (v === null || typeof v !== 'object' || Array.isArray(v))
+                    return v;
+                const o = v;
+                if (typeof o.typeName !== 'string' || o.__type !== undefined)
+                    return v;
+                // Re-shape a stripped rules-wrapper clone into the wrapper's own
+                // canonical toJSON marker form (kept in sync with pyric/rules'
+                // simulator/wrappers/* instance fields + toJSON()) — but ONLY
+                // when the key set EXACTLY matches that wrapper's own-field
+                // shape. A looser match would silently DROP extra keys from
+                // user data that merely resembles a clone, collapsing two
+                // genuinely different docs into one canonical form and letting
+                // a concurrent write commit undetected (false equality). A
+                // near-miss map passes through unchanged — worst case is a
+                // spurious abort + retry, never a lost update.
+                switch (o.typeName) {
+                    case 'timestamp':
+                        return hasExactKeys(o, TS_CLONE_KEYS)
+                            ? { __type: 'timestamp', seconds: o.seconds, nanos: o.nanos }
+                            : v;
+                    case 'duration':
+                        return hasExactKeys(o, TS_CLONE_KEYS)
+                            ? { __type: 'duration', seconds: o.seconds, nanos: o.nanos }
+                            : v;
+                    case 'latlng':
+                        return hasExactKeys(o, ['typeName', 'lat', 'lng'])
+                            ? { __type: 'latlng', lat: o.lat, lng: o.lng }
+                            : v;
+                    case 'reference':
+                        return hasExactKeys(o, ['typeName', 'path'])
+                            ? { __type: 'reference', path: o.path }
+                            : v;
+                    case 'path':
+                        return hasExactKeys(o, ['typeName', 'segments', 'bindings'])
+                            ? { __type: 'path', segments: o.segments }
+                            : v;
+                    case 'bytes':
+                        // The Uint8Array field serialized as an index-keyed map;
+                        // rebuild and emit Bytes.toJSON()'s base64url form.
+                        return hasExactKeys(o, ['typeName', 'data'])
+                            ? { __type: 'bytes', base64: indexMapToBase64Url(o.data) }
+                            : v;
+                    default:
+                        return v;
+                }
+            });
+            try {
+                await runTransaction(db, async (tx) => {
+                    // ── Step 1: validate the read-set ──────────────────────────────
+                    // Re-read each doc the client touched and compare its current
+                    // serialized form against what the client recorded at read time.
+                    const modularTx = tx;
+                    for (const r of msg.reads) {
+                        const ref = pyricDoc(db, r.path);
+                        const currentSnap = await modularTx.get(ref);
+                        const existsBool = typeof currentSnap.exists === 'function'
+                            ? currentSnap.exists()
+                            : currentSnap.exists;
+                        // Compute the serialized form of the current doc state.
+                        const currentSerialized = existsBool && currentSnap.data()
+                            ? serializeDocData(currentSnap.data())
+                            : null;
+                        // Compare against what the client recorded:
+                        //   both null → ok (doc still doesn't exist)
+                        //   both present + same JSON → ok
+                        //   anything else → conflict
+                        const clientHadNull = r.data === null;
+                        const workerHasNull = currentSerialized === null;
+                        if (clientHadNull !== workerHasNull) {
+                            // Existence changed (created or deleted by another tab).
+                            throw TXN_ABORT;
+                        }
+                        if (!clientHadNull &&
+                            !workerHasNull &&
+                            canonicalDocJson(r.data.json) !== canonicalDocJson(currentSerialized.json)) {
+                            // Data changed by another tab.
+                            throw TXN_ABORT;
+                        }
+                    }
+                    // ── Step 2: apply the queued writes ────────────────────────────
+                    for (const w of msg.writes) {
+                        const ref = pyricDoc(db, w.path);
+                        if (w.method === 'set') {
+                            const data = prepareWriteData(w.data);
+                            modularTx.set(ref, data, w.options);
+                        }
+                        else if (w.method === 'update') {
+                            const data = prepareWriteData(w.data);
+                            modularTx.update(ref, data);
+                        }
+                        else if (w.method === 'delete') {
+                            modularTx.delete(ref);
+                        }
+                    }
+                });
+                await bestEffortFlush(ctx);
+                ok(port, msg.id, null);
+            }
+            catch (e) {
+                if (e === TXN_ABORT) {
+                    // Read-set conflict — signal the client to retry its updateFn.
+                    const abortErr = { code: 'aborted', message: 'Transaction read-set conflict: a concurrent write invalidated the read snapshot.' };
+                    post(port, { t: 'res', id: msg.id, ok: false, error: abortErr });
+                }
+                else {
+                    fail(port, msg.id, e);
+                }
+            }
+            break;
+        }
+        default: {
+            fail(port, msg.id, new Error(`Unknown method: ${String(msg.method)}`));
+        }
+    }
+}
+//# sourceMappingURL=firestore-writes.js.map

package/dist/serve/worker/host/firestore-writes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-writes.js","sourceRoot":"","sources":["../../../../src/serve/worker/host/firestore-writes.ts"],"names":[],"mappings":"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"}

package/dist/serve/worker/host/presence.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SharedWorker host — connected-page presence (#227).
+ *
+ * Ephemeral, worker-lifetime registry of logical pages attached to this
+ * sandbox worker. Distinct from per-port subscription / auth-session /
+ * messaging maps: the user-facing count is keyed by `clientId`, so one page
+ * with multiple MessagePorts still counts as one client.
+ *
+ * Correctness rests on heartbeats + lease expiry (MessagePort `close` is
+ * best-effort and unreliable in Chrome). `cleanupPort` is an optimization
+ * that removes a client when its last associated port disappears.
+ */
+import type { OpMessage, PresenceSnapshot, PresenceSubMessage } from '../protocol.js';
+import { type HostCtx, type PortLike } from '../host-context.js';
+import { PRESENCE_HEARTBEAT_INTERVAL_MS, PRESENCE_STALE_MS } from '../presence-timing.js';
+export { PRESENCE_HEARTBEAT_INTERVAL_MS, PRESENCE_STALE_MS };
+export declare function setPresenceNow(fn: () => number): void;
+export declare function resetPresenceNow(): void;
+export declare function presenceNow(): number;
+/**
+ * Drop clients whose lease is older than {@link PRESENCE_STALE_MS}.
+ * Returns true when any client was removed (and subscribers were notified).
+ * Tests call this with a controllable {@link setPresenceNow}.
+ */
+export declare function expireStalePresence(ctx: HostCtx, now?: number): boolean;
+/** Authoritative presence snapshot for diagnostics / tests. */
+export declare function getPresenceSnapshot(ctx: HostCtx): PresenceSnapshot;
+export declare function isPresenceOp(method: OpMessage['method']): boolean;
+export declare function handlePresenceOp(ctx: HostCtx, port: PortLike, msg: OpMessage): Promise<void>;
+export declare function handlePresenceSub(ctx: HostCtx, port: PortLike, msg: PresenceSubMessage): void;
+export declare function handlePresenceUnsub(ctx: HostCtx, port: PortLike, subId: string): boolean;
+/**
+ * Port-close optimization: if this port was the last association for a
+ * logical client, remove that client. Lease expiry remains the correctness
+ * path when close events are missing.
+ */
+export declare function cleanupPortPresence(ctx: HostCtx, port: PortLike): void;
+//# sourceMappingURL=presence.d.ts.map

package/dist/serve/worker/host/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../../../src/serve/worker/host/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAwB,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5G,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,8BAA8B,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1F,OAAO,EAAE,8BAA8B,EAAE,iBAAiB,EAAE,CAAC;AAK7D,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,MAAM,GAAG,IAAI,CAErD;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAgFD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,GAAE,MAAsB,GAAG,OAAO,CAiBtF;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAGlE;AASD,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,OAAO,CAEjE;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,IAAI,CAAC,CAqGf;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAY7F;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQxF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAsBtE"}