@swirls/looms 0.0.1

package/dist/runtime/server.js

@@ -0,0 +1,226 @@
+import { Effect, Schema } from 'effect';
+import { createRunId, EventStoreTag, InvalidEventError, InvalidInputError, JsonValueSchema, } from '@swirls/looms/core';
+import { handleEventsApi } from './events-api.js';
+import { createEventStreamResponse } from './sse.js';
+const StartRunBodySchema = Schema.Struct({
+    kind: Schema.optional(Schema.String),
+    definitionName: Schema.optional(Schema.String),
+    name: Schema.optional(Schema.String),
+    input: Schema.optional(JsonValueSchema),
+    runId: Schema.optional(Schema.String),
+    idempotencyKey: Schema.optional(Schema.String),
+});
+const SignalBodySchema = Schema.Struct({
+    events: Schema.optional(Schema.Array(Schema.Struct({
+        type: Schema.String,
+        payload: JsonValueSchema,
+        threadId: Schema.optional(Schema.NullOr(Schema.String)),
+    }))),
+    type: Schema.optional(Schema.String),
+    payload: Schema.optional(JsonValueSchema),
+    threadId: Schema.optional(Schema.NullOr(Schema.String)),
+    idempotencyKey: Schema.optional(Schema.String),
+});
+function extractIdempotencyKey(req, bodyKey) {
+    return (bodyKey ??
+        req.headers.get('idempotency-key') ??
+        req.headers.get('x-idempotency-key') ??
+        undefined);
+}
+function run(effect, store) {
+    return Effect.runPromise(Effect.provideService(effect, EventStoreTag, store));
+}
+function wantsRunStream(req, url) {
+    const accept = req.headers.get('accept') ?? '';
+    return url.searchParams.get('stream') === 'true' || accept.includes('text/event-stream');
+}
+function streamStartRun(req, runtime, store, args) {
+    return createEventStreamResponse({
+        signal: req.signal,
+        request: req,
+        store,
+        runId: args.runId,
+        fromSeq: 1,
+        onStart: async (write, close) => {
+            try {
+                const result = await run(runtime.startRun({
+                    kind: args.kind,
+                    definitionName: args.definitionName,
+                    input: args.input,
+                    runId: args.runId,
+                    idempotencyKey: args.idempotencyKey,
+                }), store);
+                write(`event: done\ndata: ${JSON.stringify(result)}\n\n`);
+            }
+            catch (cause) {
+                const error = cause instanceof Error ? cause.message : String(cause);
+                write(`event: error\ndata: ${JSON.stringify({ error })}\n\n`);
+            }
+            finally {
+                close();
+            }
+        },
+    });
+}
+async function readJson(req) {
+    try {
+        const value = await req.json();
+        return Schema.decodeUnknownSync(JsonValueSchema)(value);
+    }
+    catch {
+        return {};
+    }
+}
+export function isLoomsApiPath(path) {
+    return path === '/health' || path.startsWith('/api/events') || path.startsWith('/runs');
+}
+function toErrorResponse(err) {
+    if (err instanceof InvalidInputError || err instanceof InvalidEventError) {
+        return Response.json({ error: err.message, issues: err.issues }, { status: 400 });
+    }
+    return Response.json({ error: err.message }, { status: 500 });
+}
+export function createFetchHandler(options) {
+    const { runtime, store } = options;
+    return async (req) => {
+        const url = new URL(req.url);
+        const path = url.pathname;
+        if (!isLoomsApiPath(path)) {
+            return null;
+        }
+        const accept = req.headers.get('accept') ?? '';
+        if (req.method === 'GET' && accept.includes('text/html') && !path.startsWith('/api/')) {
+            return null;
+        }
+        if (path === '/health') {
+            return Response.json({ ok: true });
+        }
+        if (path.startsWith('/api/events')) {
+            return handleEventsApi(req, runtime, store);
+        }
+        try {
+            if (req.method === 'GET' && path === '/runs') {
+                const runIds = await run(runtime.listRuns(), store);
+                return Response.json({ runIds });
+            }
+            if (req.method === 'POST' && path === '/runs') {
+                const body = Schema.decodeUnknownSync(StartRunBodySchema)(await readJson(req));
+                const definitionName = body.definitionName ?? body.name;
+                const kind = body.kind;
+                if (!definitionName || !kind) {
+                    return Response.json({ error: 'kind and definitionName required' }, { status: 400 });
+                }
+                const runId = body.runId ?? createRunId();
+                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
+                if (wantsRunStream(req, url)) {
+                    return streamStartRun(req, runtime, store, {
+                        kind,
+                        definitionName,
+                        input: body.input ?? null,
+                        runId,
+                        idempotencyKey,
+                    });
+                }
+                const result = await run(runtime.startRun({
+                    kind,
+                    definitionName,
+                    input: body.input ?? null,
+                    runId,
+                    idempotencyKey,
+                }), store);
+                return Response.json(result);
+            }
+            const replayMatch = path.match(/^\/runs\/([^/]+)\/replay$/);
+            if (req.method === 'GET' && replayMatch) {
+                const runId = decodeURIComponent(replayMatch[1]);
+                const seq = Number(url.searchParams.get('seq') ?? '0');
+                const step = await run(runtime.replayTo(runId, seq), store);
+                return Response.json({ runId, step });
+            }
+            const projectionMatch = path.match(/^\/runs\/([^/]+)\/projections\/([^/]+)$/);
+            if (req.method === 'GET' && projectionMatch) {
+                const runId = decodeURIComponent(projectionMatch[1]);
+                const name = decodeURIComponent(projectionMatch[2]);
+                const definition = runtime.registry.projections.get(name);
+                if (!definition) {
+                    return Response.json({ error: `Unknown projection: ${name}` }, { status: 404 });
+                }
+                const value = await run(runtime.project(runId, definition), store);
+                return Response.json({ runId, name, value });
+            }
+            const eventsMatch = path.match(/^\/runs\/([^/]+)\/events$/);
+            if (req.method === 'POST' && eventsMatch) {
+                const runId = decodeURIComponent(eventsMatch[1]);
+                const body = Schema.decodeUnknownSync(SignalBodySchema)(await readJson(req));
+                const events = body.events ??
+                    (body.type
+                        ? [
+                            {
+                                type: body.type,
+                                payload: body.payload ?? null,
+                                threadId: body.threadId,
+                            },
+                        ]
+                        : []);
+                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
+                const state = await run(runtime.signal(runId, events, { idempotencyKey }), store);
+                return Response.json({ runId, state });
+            }
+            if (req.method === 'GET' && eventsMatch) {
+                const runId = decodeURIComponent(eventsMatch[1]);
+                const fromSeq = url.searchParams.get('fromSeq')
+                    ? Number(url.searchParams.get('fromSeq'))
+                    : undefined;
+                const limit = url.searchParams.get('limit')
+                    ? Number(url.searchParams.get('limit'))
+                    : undefined;
+                const events = await run(runtime.getEvents(runId, { fromSeq, limit }), store);
+                return Response.json({ runId, events });
+            }
+            const threadsMatch = path.match(/^\/runs\/([^/]+)\/(threads)$/);
+            if (req.method === 'GET' && threadsMatch) {
+                const runId = decodeURIComponent(threadsMatch[1]);
+                const state = await run(runtime.getRun(runId), store);
+                return Response.json({ runId, threads: state.threads });
+            }
+            const wakeMatch = path.match(/^\/runs\/([^/]+)\/wake$/);
+            if (req.method === 'POST' && wakeMatch) {
+                const runId = decodeURIComponent(wakeMatch[1]);
+                const state = await run(runtime.wake(runId), store);
+                return Response.json({ runId, state });
+            }
+            const runMatch = path.match(/^\/runs\/([^/]+)$/);
+            if (req.method === 'GET' && runMatch) {
+                const runId = decodeURIComponent(runMatch[1]);
+                const state = await run(runtime.getRun(runId), store);
+                return Response.json({ runId, state });
+            }
+            return new Response('Not Found', { status: 404 });
+        }
+        catch (rawErr) {
+            const err = rawErr instanceof Error ? rawErr : new Error(String(rawErr));
+            return toErrorResponse(err);
+        }
+    };
+}
+export function serveHttp(fetchHandler, options) {
+    const port = options?.port ?? 8787;
+    const hostname = options?.hostname ?? '0.0.0.0';
+    const server = Bun.serve({
+        port,
+        hostname,
+        idleTimeout: 0,
+        async fetch(req, srv) {
+            srv.timeout(req, 0);
+            const result = await fetchHandler(req);
+            if (result === null) {
+                return new Response('Not Found', { status: 404 });
+            }
+            return result;
+        },
+    });
+    return {
+        port: server.port ?? port,
+        stop: () => server.stop(true),
+    };
+}

package/dist/runtime/sse.d.ts

@@ -0,0 +1,15 @@
+import { type EventStore } from '@swirls/looms/core';
+export interface EventStreamOptions {
+    signal: AbortSignal;
+    store: EventStore;
+    runId: string;
+    fromSeq?: number;
+    heartbeatMs?: number;
+    onStart?: (write: (text: string) => void, close: () => void) => Promise<void> | void;
+    request?: Request;
+}
+/**
+ * Creates an SSE Response backed by an EventStore subscription.
+ * Handles heartbeats, fiber cancellation on disconnect, event encoding, and optional lifecycle hooks.
+ */
+export declare function createEventStreamResponse(options: EventStreamOptions): Response;

package/dist/runtime/sse.js

@@ -0,0 +1,96 @@
+import { Effect, Fiber, Stream } from 'effect';
+import { encodeLoomsEvent } from '@swirls/looms/core';
+function disableBunSocketTimeout(request) {
+    if (!request) {
+        return;
+    }
+    try {
+        // SAFETY: Bun.serve attaches runtime.bun.server to Request in srvx and Bun handlers.
+        const reqWithBun = request;
+        const bunServer = reqWithBun.runtime?.bun?.server;
+        if (bunServer) {
+            bunServer.timeout?.(request, 0);
+        }
+    }
+    catch {
+        // Ignore environments where timeout is not supported.
+    }
+}
+/**
+ * Creates an SSE Response backed by an EventStore subscription.
+ * Handles heartbeats, fiber cancellation on disconnect, event encoding, and optional lifecycle hooks.
+ */
+export function createEventStreamResponse(options) {
+    const { signal, store, runId, fromSeq = 1, heartbeatMs = 3_000, onStart, request } = options;
+    disableBunSocketTimeout(request);
+    let closed = false;
+    let heartbeat;
+    let fiber;
+    let streamController;
+    const close = () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        if (heartbeat !== undefined) {
+            clearInterval(heartbeat);
+        }
+        if (fiber) {
+            Effect.runFork(Fiber.interrupt(fiber));
+        }
+        try {
+            streamController?.close();
+        }
+        catch {
+            // already closed
+        }
+    };
+    const stream = new ReadableStream({
+        start(controller) {
+            streamController = controller;
+            const encoder = new TextEncoder();
+            const write = (text) => {
+                if (closed) {
+                    return;
+                }
+                try {
+                    controller.enqueue(encoder.encode(text));
+                }
+                catch {
+                    close();
+                }
+            };
+            fiber = Effect.runFork(store.subscribe(runId, { fromSeq }).pipe(Stream.tap((event) => Effect.sync(() => {
+                write(`id: ${event.seq}\ndata: ${JSON.stringify({ batch: [encodeLoomsEvent(event)] })}\n\n`);
+            })), Stream.runDrain));
+            // Send an immediate keepalive so bytes and headers flush over the wire immediately,
+            // preventing dev server proxies and Bun.serve from aborting quiet connections.
+            write(': keepalive\n\n');
+            heartbeat = setInterval(() => write(': keepalive\n\n'), heartbeatMs);
+            if (onStart) {
+                Promise.resolve(onStart(write, close)).catch((cause) => {
+                    const error = cause instanceof Error ? cause.message : String(cause);
+                    write(`event: error\ndata: ${JSON.stringify({ error })}\n\n`);
+                    close();
+                });
+            }
+            if (signal.aborted) {
+                close();
+                return;
+            }
+            signal.addEventListener('abort', close);
+        },
+        cancel() {
+            // When the consumer closes the stream or client disconnects, tear down resources immediately.
+            close();
+        },
+    });
+    return new Response(stream, {
+        headers: {
+            'content-type': 'text/event-stream',
+            'cache-control': 'no-cache, no-transform',
+            connection: 'keep-alive',
+            'x-accel-buffering': 'no',
+        },
+    });
+}

package/dist/runtime/wake-scheduler.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from 'effect';
+export interface WakeScheduler {
+    schedule(runId: string, at: number): void | Promise<void>;
+    cancel(runId: string): void | Promise<void>;
+    dispose?(): void;
+}
+export declare function createTimeoutScheduler(wake: (runId: string) => Promise<void> | void): WakeScheduler;
+export declare function toEffectVoid(result: void | Promise<void>): Effect.Effect<void>;

package/dist/runtime/wake-scheduler.js

@@ -0,0 +1,38 @@
+import { Effect } from 'effect';
+export function createTimeoutScheduler(wake) {
+    const scheduledTimers = new Map();
+    return {
+        schedule(runId, timerAt) {
+            const existing = scheduledTimers.get(runId);
+            if (existing) {
+                clearTimeout(existing);
+                scheduledTimers.delete(runId);
+            }
+            const delay = Math.max(0, timerAt - Date.now() + 5);
+            const handle = setTimeout(() => {
+                scheduledTimers.delete(runId);
+                void wake(runId);
+            }, delay);
+            scheduledTimers.set(runId, handle);
+        },
+        cancel(runId) {
+            const existing = scheduledTimers.get(runId);
+            if (existing) {
+                clearTimeout(existing);
+                scheduledTimers.delete(runId);
+            }
+        },
+        dispose() {
+            for (const handle of scheduledTimers.values()) {
+                clearTimeout(handle);
+            }
+            scheduledTimers.clear();
+        },
+    };
+}
+export function toEffectVoid(result) {
+    if (result instanceof Promise) {
+        return Effect.promise(() => result);
+    }
+    return Effect.void;
+}

package/dist/s2/config.d.ts

@@ -0,0 +1,27 @@
+import { Schema } from 'effect';
+/**
+ * Configuration for the S2-backed EventStore.
+ *
+ * `endpoint` is optional and typically used for local s2-lite:
+ *   `{ account: "http://localhost:8080", basin: "http://localhost:8080" }`
+ */
+export declare const S2ConfigSchema: Schema.Struct<{
+    readonly basin: Schema.String;
+    readonly accessToken: Schema.String;
+    readonly endpoint: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+        readonly account: Schema.optional<Schema.String>;
+        readonly basin: Schema.optional<Schema.String>;
+    }>]>>;
+    readonly streamConfig: Schema.optional<Schema.Struct<{
+        readonly retentionPolicy: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+            readonly ageSecs: Schema.Number;
+        }>, Schema.Struct<{
+            readonly infinite: Schema.Struct<{}>;
+        }>]>>;
+        readonly storageClass: Schema.optional<Schema.Literals<readonly ["standard", "express"]>>;
+    }>>;
+    readonly snapshotPrefix: Schema.optional<Schema.String>;
+}>;
+export type S2Config = Schema.Schema.Type<typeof S2ConfigSchema>;
+export declare function streamNameForRun(runId: string): string;
+export declare function s2ConfigFromEnv(env: Record<string, string | undefined>): S2Config;

package/dist/s2/config.js

@@ -0,0 +1,54 @@
+import { Schema } from 'effect';
+/**
+ * Configuration for the S2-backed EventStore.
+ *
+ * `endpoint` is optional and typically used for local s2-lite:
+ *   `{ account: "http://localhost:8080", basin: "http://localhost:8080" }`
+ */
+export const S2ConfigSchema = Schema.Struct({
+    basin: Schema.String,
+    accessToken: Schema.String,
+    endpoint: Schema.optional(Schema.Union([
+        Schema.String,
+        Schema.Struct({
+            account: Schema.optional(Schema.String),
+            basin: Schema.optional(Schema.String),
+        }),
+    ])),
+    streamConfig: Schema.optional(Schema.Struct({
+        retentionPolicy: Schema.optional(Schema.Union([
+            Schema.Struct({ ageSecs: Schema.Number }),
+            Schema.Struct({ infinite: Schema.Struct({}) }),
+        ])),
+        storageClass: Schema.optional(Schema.Literals(['standard', 'express'])),
+    })),
+    snapshotPrefix: Schema.optional(Schema.String),
+});
+export function streamNameForRun(runId) {
+    return `runs/${runId}`;
+}
+export function s2ConfigFromEnv(env) {
+    const basin = env.LOOMS_S2_BASIN ?? env.S2_BASIN ?? 'looms-demo';
+    const accessToken = env.LOOMS_S2_ACCESS_TOKEN ??
+        env.LOOMS_S2_AUTH_TOKEN ??
+        env.S2_ACCESS_TOKEN ??
+        env.S2_AUTH_TOKEN ??
+        's2_local';
+    const endpoint = env.LOOMS_S2_ENDPOINT ??
+        env.S2_ENDPOINT ??
+        ((env.LOOMS_S2_PORT ?? env.S2_PORT ?? env.S2_LITE_PORT)
+            ? `http://127.0.0.1:${env.LOOMS_S2_PORT ?? env.S2_PORT ?? env.S2_LITE_PORT}`
+            : undefined);
+    const config = {
+        basin,
+        accessToken,
+    };
+    if (endpoint !== undefined) {
+        return {
+            basin,
+            accessToken,
+            endpoint,
+        };
+    }
+    return config;
+}

package/dist/s2/index.d.ts

@@ -0,0 +1,6 @@
+export { S2ConfigSchema, s2ConfigFromEnv, streamNameForRun, type S2Config } from './config';
+export { findS2Binary, isPortOpen, s2Lite, startS2Lite, type S2LiteOptions, type StartedS2Lite, } from './lite';
+export { makeS2EventStore, paginateS2Stream, readAllPages, s2, S2EventStoreLive, type ReadAllPagesOptions, type S2ReadBatchLike, } from './store';
+export { createKeyedSerializer, type KeyedSerializer } from './serialize';
+export { s2Projector } from './projector';
+export { assembleSnapshot, frameSnapshot, s2SnapshotStore, S2SnapshotStoreLive, type SnapshotFrame, } from './snapshot-store';

package/dist/s2/index.js

@@ -0,0 +1,6 @@
+export { S2ConfigSchema, s2ConfigFromEnv, streamNameForRun } from './config.js';
+export { findS2Binary, isPortOpen, s2Lite, startS2Lite, } from './lite.js';
+export { makeS2EventStore, paginateS2Stream, readAllPages, s2, S2EventStoreLive, } from './store.js';
+export { createKeyedSerializer } from './serialize.js';
+export { s2Projector } from './projector.js';
+export { assembleSnapshot, frameSnapshot, s2SnapshotStore, S2SnapshotStoreLive, } from './snapshot-store.js';

package/dist/s2/lite.d.ts

@@ -0,0 +1,26 @@
+import type { EventStore } from '@swirls/looms/core';
+export interface S2LiteOptions {
+    /** Port for local s2-lite process. Defaults to 8080. */
+    readonly port?: number;
+    /** Basin name. Defaults to 'looms-demo'. */
+    readonly basin?: string;
+    /** Auth token for local access. Defaults to 's2_local'. */
+    readonly accessToken?: string;
+    /** Environment bag used to locate the s2 binary. */
+    readonly env?: Record<string, string | undefined>;
+    /** Explicit path to the s2 binary, skipping lookup. */
+    readonly binaryPath?: string;
+}
+export declare function findS2Binary(env: Record<string, string | undefined>): string | undefined;
+export declare function isPortOpen(port: number, host?: string): Promise<boolean>;
+export interface StartedS2Lite {
+    readonly port: number;
+    readonly endpoint: string;
+    readonly stop: () => void;
+}
+export declare function startS2Lite(options?: S2LiteOptions): Promise<StartedS2Lite>;
+/**
+ * Returns a factory function for createLooms that automatically starts local s2-lite
+ * and connects an S2 EventStore to it.
+ */
+export declare function s2Lite(options?: S2LiteOptions): () => Promise<EventStore>;

package/dist/s2/lite.js

@@ -0,0 +1,150 @@
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs';
+import * as net from 'node:net';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { s2 } from './store.js';
+export function findS2Binary(env) {
+    // 1. Check PATH
+    const pathDirs = (env.PATH ?? '').split(path.delimiter);
+    for (const dir of pathDirs) {
+        if (!dir) {
+            continue;
+        }
+        const candidate = path.join(dir, 's2');
+        try {
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        catch {
+            // Ignore filesystem access errors during lookup.
+        }
+    }
+    // 2. Check FLOX_ENV_CACHE
+    if (env.FLOX_ENV_CACHE) {
+        const floxCandidate = path.join(env.FLOX_ENV_CACHE, 's2', 'bin', 's2');
+        if (fs.existsSync(floxCandidate)) {
+            return floxCandidate;
+        }
+    }
+    // 3. Check S2_INSTALL_PREFIX
+    if (env.S2_INSTALL_PREFIX) {
+        const prefixCandidate = path.join(env.S2_INSTALL_PREFIX, 'bin', 's2');
+        if (fs.existsSync(prefixCandidate)) {
+            return prefixCandidate;
+        }
+    }
+    // 4. Check ~/.s2/bin/s2
+    const homeCandidate = path.join(os.homedir(), '.s2', 'bin', 's2');
+    if (fs.existsSync(homeCandidate)) {
+        return homeCandidate;
+    }
+    // 5. Check local ./.s2/bin/s2
+    const localCandidate = path.join(process.cwd(), '.s2', 'bin', 's2');
+    if (fs.existsSync(localCandidate)) {
+        return localCandidate;
+    }
+    return undefined;
+}
+export function isPortOpen(port, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(200);
+        socket.once('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.once('error', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, host);
+    });
+}
+let activeProcess = null;
+export async function startS2Lite(options = {}) {
+    const port = options.port ?? 8080;
+    const endpoint = `http://127.0.0.1:${port}`;
+    // 1. Check if an s2-lite instance is already responding on this port.
+    const alreadyRunning = await isPortOpen(port);
+    if (alreadyRunning) {
+        return {
+            port,
+            endpoint,
+            stop: () => {
+                // Did not spawn this process, no-op stop.
+            },
+        };
+    }
+    // 2. Locate the s2 binary.
+    const binaryPath = options.binaryPath ?? findS2Binary(options.env ?? {});
+    if (!binaryPath) {
+        throw new Error(`s2 CLI binary not found on PATH or in standard locations.
+To install s2-lite for local development:
+  flox activate          # installs into $FLOX_ENV_CACHE/s2 (preferred)
+  bun run setup:s2       # scripts/install-s2-cli.sh
+  https://s2.dev/docs/cli/installation`);
+    }
+    // 3. Spawn s2 lite.
+    // SAFETY: child_process.spawn returns child process matching S2ChildProcess.
+    const child = childProcess.spawn(binaryPath, ['lite', '--port', String(port)], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: false,
+    });
+    activeProcess = child;
+    const cleanup = () => {
+        if (activeProcess === child) {
+            activeProcess = null;
+        }
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            // Process may already have exited.
+        }
+    };
+    process.once('exit', cleanup);
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+    let stderrOutput = '';
+    child.stderr?.on('data', (chunk) => {
+        stderrOutput += chunk.toString();
+    });
+    // 4. Poll until the port responds or the process exits unexpectedly.
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        if (child.exitCode !== null) {
+            throw new Error(`s2 lite process exited with code ${child.exitCode} before becoming ready: ${stderrOutput}`);
+        }
+        const ready = await isPortOpen(port);
+        if (ready) {
+            return {
+                port,
+                endpoint,
+                stop: cleanup,
+            };
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    cleanup();
+    throw new Error(`Timed out waiting for s2 lite to start on port ${port}: ${stderrOutput}`);
+}
+/**
+ * Returns a factory function for createLooms that automatically starts local s2-lite
+ * and connects an S2 EventStore to it.
+ */
+export function s2Lite(options = {}) {
+    return async () => {
+        const started = await startS2Lite(options);
+        return s2({
+            basin: options.basin ?? 'looms-demo',
+            accessToken: options.accessToken ?? 's2_local',
+            endpoint: started.endpoint,
+        });
+    };
+}

package/dist/s2/projector.d.ts

@@ -0,0 +1,8 @@
+import type { Projector } from '@swirls/looms/projectors';
+import { S2ConfigSchema, s2ConfigFromEnv, streamNameForRun, type S2Config } from './config';
+export { S2ConfigSchema, s2ConfigFromEnv, streamNameForRun, type S2Config };
+/**
+ * Asynchronous S2 projector. The actor's local EventStore stays authoritative;
+ * this fans committed events out to `runs/{runId}` for the global stream lake.
+ */
+export declare function s2Projector(config: S2Config): Projector;