pyric-tools 0.1.0-alpha.7

package/dist/serve/worker/host-context.js

@@ -0,0 +1,45 @@
+/**
+ * SharedWorker host — shared foundation (context + reply helpers).
+ *
+ * The `HostCtx` is the single per-worker context shared across ALL connected
+ * ports and across the auth + event-stream subsystems. `PortLike`, `post`,
+ * `ok`, and `fail` are the minimal port + reply primitives every subsystem
+ * uses. This module imports NOTHING from the sibling `host-*` files, so it is
+ * the dependency root (no circular imports).
+ */
+import { serializeError, } from './protocol.js';
+// ─── Utility: post a typed reply to a port ───────────────────────────────
+export function post(port, msg) {
+    port.postMessage(msg);
+}
+export function ok(port, id, value) {
+    post(port, { t: 'res', id, ok: true, value });
+}
+export function fail(port, id, err) {
+    // The serialized error carries `denialContext` when present (spike gap 6) —
+    // post it whole so the structured denial frame reaches remote consumers.
+    post(port, { t: 'res', id, ok: false, error: serializeError(err) });
+}
+/**
+ * Await a persistence flush BEFORE acking a mutating op, so an acknowledged
+ * write is durable in IndexedDB when the reply reaches the client. This is
+ * the worker's ONLY durability mechanism: there is no beforeterminate-style
+ * event for a SharedWorker, so a teardown on last-tab close/reload can kill
+ * the worker inside the controller's debounce window — an un-flushed write
+ * would be silently lost (the reload-durability bug).
+ *
+ * "Best-effort" refers to the REPLY, not the flush: a flush failure (e.g.
+ * storage quota) must not turn a successful in-memory mutation into a wire
+ * error, but it IS logged — a silently swallowed flush failure is exactly
+ * how a broken flush contract stays invisible.
+ */
+export async function bestEffortFlush(ctx) {
+    try {
+        await ctx.sandbox.flush?.();
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.warn('[pyric worker] persistence flush after acked write failed:', e);
+    }
+}
+//# sourceMappingURL=host-context.js.map

package/dist/serve/worker/host-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-context.js","sourceRoot":"","sources":["../../../src/serve/worker/host-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EACL,cAAc,GAIf,MAAM,eAAe,CAAC;AAsJvB,4EAA4E;AAE5E,MAAM,UAAU,IAAI,CAAC,IAAc,EAAE,GAAoB;IACvD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,EAAE,CAAC,IAAc,EAAE,EAAU,EAAE,KAAc;IAC3D,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAc,EAAE,EAAU,EAAE,GAAY;IAC3D,4EAA4E;IAC5E,yEAAyE;IACzE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAY;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,4DAA4D,EAAE,CAAC,CAAC,CAAC;IAChF,CAAC;AACH,CAAC"}

package/dist/serve/worker/host-events.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SharedWorker host — event-stream subsystem (Pyric Studio keystone).
+ *
+ * Surfaces the sandbox's unified cross-service `onEvent`/`history()` stream over
+ * the port so Studio's Action Center / traffic / rules-debug denial feed see
+ * real activity. Imports only from `./host-context.js` + external packages (no
+ * circular imports).
+ */
+import { type HostCtx, type PortLike } from './host-context.js';
+import type { EventSubMessage } from './protocol.js';
+export declare function eventSubsFor(ctx: HostCtx): Map<PortLike, Set<string>>;
+/**
+ * Register an event-stream subscription for a port (Pyric Studio keystone).
+ * Records the (port, subId) so live events reach it, ensures the single real
+ * sandbox subscription is wired, and immediately delivers `sandbox.history()`
+ * (every event so far) as the initial batch — so a late subscriber folds the
+ * full backlog then streams uniformly (mirrors `onEvent` + `history`).
+ */
+export declare function handleEventSub(ctx: HostCtx, port: PortLike, msg: EventSubMessage): void;
+export declare function handleEventUnsub(ctx: HostCtx, port: PortLike, subId: string): boolean;
+//# sourceMappingURL=host-events.d.ts.map

package/dist/serve/worker/host-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-events.d.ts","sourceRoot":"","sources":["../../../src/serve/worker/host-events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAQ,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAoBrD,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAOrE;AA0BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAavF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOrF"}

package/dist/serve/worker/host-events.js

@@ -0,0 +1,87 @@
+/**
+ * SharedWorker host — event-stream subsystem (Pyric Studio keystone).
+ *
+ * Surfaces the sandbox's unified cross-service `onEvent`/`history()` stream over
+ * the port so Studio's Action Center / traffic / rules-debug denial feed see
+ * real activity. Imports only from `./host-context.js` + external packages (no
+ * circular imports).
+ */
+import { post } from './host-context.js';
+// ─── Event-stream subscription (Pyric Studio keystone) ─────────────────────
+//
+// Surfaces the sandbox's unified cross-service `onEvent`/`history()` stream over
+// the port so Studio's Action Center / traffic / rules-debug denial feed see
+// real activity. Architecture mirrors the AUTH fan-out: ONE real
+// `sandbox.onEvent` subscription per worker (lazily wired in {@link ensureEventStream}),
+// and a per-port routing registry telling the host which ports want events. On
+// any event the single sandbox subscription fires once and we fan it out to
+// EVERY subscribed port — so multiple Studio/app tabs share the one backend
+// stream. Events are plain JSON (no codec round-trip; see EventSubMessage).
+/** Per-port event-stream subscription registry. Map<port, Set<subId>>. The
+ *  WeakMap is keyed by ctx so multiple in-process hosts (tests) don't collide. */
+const _eventSubs = new WeakMap();
+/** Tracks whether the single real `sandbox.onEvent` subscription is wired. */
+const _eventStreamWired = new WeakSet();
+export function eventSubsFor(ctx) {
+    let m = _eventSubs.get(ctx);
+    if (!m) {
+        m = new Map();
+        _eventSubs.set(ctx, m);
+    }
+    return m;
+}
+/**
+ * Lazily wire the ONE real `sandbox.onEvent` subscription for this ctx. On every
+ * sandbox event it fans the event out (as a single-element batch) to every port
+ * subscribed to the stream. Idempotent — only the first event sub wires it; the
+ * subscription then lives for the worker's lifetime (cheap, observational).
+ */
+function ensureEventStream(ctx) {
+    if (_eventStreamWired.has(ctx))
+        return;
+    _eventStreamWired.add(ctx);
+    ctx.sandbox.onEvent((event) => {
+        broadcastEvents(ctx, [event]);
+    });
+}
+/** Fan a batch of events out to every port subscribed to the event stream. */
+function broadcastEvents(ctx, events) {
+    const subs = eventSubsFor(ctx);
+    for (const [port, subIds] of subs) {
+        for (const subId of subIds) {
+            post(port, { t: 'event', subId, events });
+        }
+    }
+}
+/**
+ * Register an event-stream subscription for a port (Pyric Studio keystone).
+ * Records the (port, subId) so live events reach it, ensures the single real
+ * sandbox subscription is wired, and immediately delivers `sandbox.history()`
+ * (every event so far) as the initial batch — so a late subscriber folds the
+ * full backlog then streams uniformly (mirrors `onEvent` + `history`).
+ */
+export function handleEventSub(ctx, port, msg) {
+    ensureEventStream(ctx);
+    const subs = eventSubsFor(ctx);
+    let subIds = subs.get(port);
+    if (!subIds) {
+        subIds = new Set();
+        subs.set(port, subIds);
+    }
+    if (subIds.has(msg.subId))
+        return; // idempotent
+    subIds.add(msg.subId);
+    // Initial fire: the full history snapshot (a defensive copy from the sandbox).
+    post(port, { t: 'event', subId: msg.subId, events: ctx.sandbox.history() });
+}
+export function handleEventUnsub(ctx, port, subId) {
+    const subs = eventSubsFor(ctx);
+    const subIds = subs.get(port);
+    if (!subIds || !subIds.has(subId))
+        return false;
+    subIds.delete(subId);
+    if (subIds.size === 0)
+        subs.delete(port);
+    return true;
+}
+//# sourceMappingURL=host-events.js.map

package/dist/serve/worker/host-events.js.map

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

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

@@ -0,0 +1,81 @@
+/**
+ * SharedWorker host — op handlers and subscription registry.
+ *
+ * WHY INJECTED DEPS
+ * -----------------
+ * The host is deliberately decoupled from `SharedWorkerGlobalScope` so
+ * unit tests can drive it with a REAL pyric sandbox + fake MessagePort
+ * objects — no browser or SharedWorker runtime required. The entry point
+ * (`entry.ts`) creates the real sandbox + db and wires the connecting ports
+ * to this module.
+ *
+ * ARCHITECTURE
+ * ------------
+ * One `HostCtx` is shared across ALL connected ports. It holds:
+ *   - `db` — the single modular Firestore handle (from pyric/firestore's
+ *     `getFirestore(sandbox)` — sandbox-live mode so auth changes propagate).
+ *   - `sandbox` — the underlying Sandbox, needed for `setRules` and for
+ *     constructing sentinels via FieldValue.
+ *   - `subs` — per-port subscription registry: Map<PortLike, Map<subId, unsub>>
+ *
+ * Each connecting port calls `handleMessage(ctx, port, msg)`. The function
+ * is exported so tests can call it directly.
+ *
+ * SENTINEL RESOLUTION
+ * -------------------
+ * Write data crossing the port may contain `SentinelMarker` objects
+ * (`{ __sentinel: 'serverTimestamp' }` etc.). Before passing data to the
+ * sandbox we walk the payload and replace each marker with the real
+ * FieldValue object from `pyric/firestore`'s sentinel factories. The
+ * sandbox's value-resolver then executes them as usual.
+ *
+ * SUBSCRIPTION FAN-OUT
+ * --------------------
+ * Because all ports share ONE sandbox, an onSnapshot listener registered
+ * via the sandbox automatically fires for writes from ANY port. We just
+ * need to forward the snapshot to the correct originating port(s).
+ *
+ * TRANSACTIONS + READ-SET VALIDATION
+ * ------------------------------------
+ * `runTransaction` on the worker is the full-fidelity path: the host calls
+ * the sandbox's `runTransaction`, which runs the update function, handles
+ * optimistic-concurrency retries, and commits atomically. The client now
+ * sends a `reads` array alongside `writes`; the worker re-reads each doc
+ * inside the sandbox transaction and validates that no concurrent write
+ * changed any of them between the client's read and this commit. A mismatch
+ * signals `{ code: 'aborted' }` on the wire so the client can re-run
+ * `updateFn` — see `txnCommit` handler for full details.
+ */
+import type { PersistenceBackend } from 'pyric/sandbox';
+import type { InboundMessage } from './protocol.js';
+import { type HostCtx, type PortLike } from './host-context.js';
+export { ensureAuth, portSession } from './host-auth.js';
+export type { HostCtx, PortLike } from './host-context.js';
+/**
+ * Per-SharedWorker instance id — generated once and persisted to the RAW idb
+ * (local-only, like the session record above; it must NEVER reach the
+ * committable server file). Because IndexedDB is per (origin + browser profile),
+ * two profiles on the same `localhost:<port>` get two distinct ids — which is
+ * exactly how the UI tells same-port-different-profile sandboxes apart.
+ */
+export declare const INSTANCE_ID_KEY = "pyric:worker:instance";
+/**
+ * `crypto.randomUUID()` is secure-context-only (https or localhost), so it is
+ * `undefined` over plain http on a non-localhost host (a Tailscale or LAN
+ * hostname). `crypto.getRandomValues` is NOT gated, so build a v4 UUID from it as
+ * the fallback. Without this the worker throws on init over Tailscale and the
+ * whole sandbox (auth, firestore, bridge) silently fails to come up.
+ */
+export declare function randomUuid(): string;
+export declare function getOrCreateInstanceId(idb: PersistenceBackend): Promise<string>;
+export declare const BRANCH_PREFIX = "pyric:worker:branch:";
+export declare const BRANCH_REGISTRY_KEY = "pyric:worker:branches";
+export declare function listBranchNames(idb?: PersistenceBackend): Promise<string[]>;
+export declare function handleMessage(ctx: HostCtx, port: PortLike, msg: InboundMessage): Promise<void>;
+/**
+ * Tear down all subscriptions for a disconnected port.
+ * Called when a port's `close` event fires (browser best-effort) or
+ * when the entry point explicitly cleans up a port.
+ */
+export declare function cleanupPort(ctx: HostCtx, port: PortLike): void;
+//# sourceMappingURL=host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../../src/serve/worker/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AA2CH,OAAO,KAAK,EAAW,kBAAkB,EAAY,MAAM,eAAe,CAAC;AAyC3E,OAAO,KAAK,EACV,cAAc,EAWf,MAAM,eAAe,CAAC;AAmBvB,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAmC,MAAM,mBAAmB,CAAC;AAiBjG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAM3D;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,0BAA0B,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAOnC;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMpF;AAQD,eAAO,MAAM,aAAa,yBAAyB,CAAC;AACpD,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,wBAAsB,eAAe,CAAC,GAAG,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIjF;AAg7CD,wBAAsB,aAAa,CACjC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAwCD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAmB9D"}