@swirls/looms 0.0.1

package/dist/cloudflare/router.js

@@ -0,0 +1,26 @@
+import { resolveRunTarget } from '@swirls/looms/actor';
+/**
+ * Routes incoming HTTP requests to the appropriate Durable Object actor cell.
+ * Handles `/health` locally, returns 501 for global `GET /runs`, and forwards
+ * all other run and event-stream requests to `namespace.getByName(runId)`.
+ */
+export async function routeToDurableObject(namespace, req) {
+    const url = new URL(req.url);
+    if (url.pathname === '/health') {
+        return Response.json({ ok: true });
+    }
+    if (req.method === 'GET' && url.pathname === '/runs') {
+        return Response.json({
+            error: 'Global run listing is not supported in the Durable Object backend without a global index',
+        }, { status: 501 });
+    }
+    try {
+        const { runId, request } = await resolveRunTarget(req);
+        const stub = namespace.getByName(runId);
+        return stub.fetch(request);
+    }
+    catch {
+        // Paths without a resolvable runId (e.g. GET /) are not handled by this router.
+        return null;
+    }
+}

package/dist/core/bun-sqlite.d.ts

@@ -0,0 +1,13 @@
+import { Database } from 'bun:sqlite';
+import { type SqliteExec } from './sqlite-store';
+import type { EventStore } from './store';
+export interface BunSqliteEventStoreOptions {
+    /** File path or `:memory:`. Default `:memory:`. */
+    readonly path?: string;
+    readonly db?: Database;
+}
+export declare function bunSqliteExec(db: Database): SqliteExec;
+/**
+ * Embedded EventStore backed by Bun's native SQLite engine (`bun:sqlite`).
+ */
+export declare function bunSqliteEventStore(options?: BunSqliteEventStoreOptions): EventStore;

package/dist/core/bun-sqlite.js

@@ -0,0 +1,19 @@
+import { Database } from 'bun:sqlite';
+import { sqliteEventStore } from './sqlite-store.js';
+export function bunSqliteExec(db) {
+    return {
+        run(sql, params = []) {
+            db.run(sql, [...params]);
+        },
+        rows(sql, params = []) {
+            return db.query(sql).all(...params);
+        },
+    };
+}
+/**
+ * Embedded EventStore backed by Bun's native SQLite engine (`bun:sqlite`).
+ */
+export function bunSqliteEventStore(options = {}) {
+    const db = options.db ?? new Database(options.path ?? ':memory:');
+    return sqliteEventStore({ exec: bunSqliteExec(db) });
+}

package/dist/core/catalog.d.ts

@@ -0,0 +1,49 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Schema } from 'effect';
+import { type EventEnvelope, type EventInput, type TypedEvent } from './envelope';
+import { type JsonValue } from './types';
+declare const catalogPayloadBrand: unique symbol;
+/** Type-only catalog entry. Carries a payload type without a runtime schema. */
+export type CatalogEventSpec<TPayload = object> = {
+    readonly [catalogPayloadBrand]?: TPayload;
+};
+/**
+ * Declare a catalog event's payload type when you do not have a Zod / Standard Schema.
+ *
+ * `payload<{ amount: number }>()` is a compile-time marker — not a cast of `{}`.
+ */
+export declare function payload<TPayload>(): CatalogEventSpec<TPayload>;
+export type CatalogEntry = CatalogEventSpec | Schema.Top | StandardSchemaV1;
+export type CatalogEntries = {
+    readonly [key: string]: CatalogEntry;
+};
+export type InferPayload<T> = T extends CatalogEventSpec<infer P> ? P : T extends Schema.Top ? Schema.Schema.Type<T> : T extends StandardSchemaV1<infer _In, infer Out> ? Out : JsonValue;
+export interface EventCatalog<TNamespace extends string = string, TEntries extends CatalogEntries = CatalogEntries> {
+    readonly namespace: TNamespace;
+    readonly entries: TEntries;
+    event<K extends keyof TEntries & string>(key: K, payload: InferPayload<TEntries[K]>, meta: Omit<EventInput, 'type' | 'payload'> & {
+        runId: string;
+    }): EventEnvelope<`${TNamespace}.${K}`, InferPayload<TEntries[K]>>;
+    input<K extends keyof TEntries & string>(key: K, payload: InferPayload<TEntries[K]>, meta?: Omit<EventInput, 'type' | 'payload'>): Omit<EventInput, 'type' | 'payload'> & {
+        readonly type: `${TNamespace}.${K}`;
+        readonly payload: InferPayload<TEntries[K]>;
+    };
+}
+export type CatalogEvent<TNamespace extends string, TEntries extends CatalogEntries> = {
+    [K in keyof TEntries & string]: TypedEvent<`${TNamespace}.${K}`, InferPayload<TEntries[K]>>;
+}[keyof TEntries & string];
+export type EventsOfCatalog<T> = T extends EventCatalog<infer N, infer E> ? CatalogEvent<N, E> : never;
+export type EventTypeOf<T> = T extends EventCatalog<infer N, infer E> ? `${N}.${keyof E & string}` : T extends EventEnvelope<infer Type, any> ? Type : string;
+export type EventInputOf<T> = T extends EventCatalog<infer N, infer E> ? {
+    [K in keyof E & string]: Omit<EventInput, 'type' | 'payload'> & {
+        readonly type: `${N}.${K}`;
+        readonly payload: InferPayload<E[K]>;
+    };
+}[keyof E & string] : T extends EventEnvelope<infer Type, infer Payload> ? Omit<EventInput, 'type' | 'payload'> & {
+    readonly type: Type;
+    readonly payload: Payload;
+} : EventInput;
+export declare function eventType<TNamespace extends string, K extends string>(namespace: TNamespace, key: K): `${TNamespace}.${K}`;
+export declare function defineEventCatalog<TNamespace extends string, TEntries extends CatalogEntries>(namespace: TNamespace, entries: TEntries): EventCatalog<TNamespace, TEntries>;
+export declare function isCatalogEvent<TNamespace extends string>(event: EventEnvelope, catalog: EventCatalog<TNamespace>): event is EventEnvelope<`${TNamespace}.${string}`>;
+export {};

package/dist/core/catalog.js

@@ -0,0 +1,39 @@
+import { createEvent } from './envelope.js';
+import { asJson } from './types.js';
+/**
+ * Declare a catalog event's payload type when you do not have a Zod / Standard Schema.
+ *
+ * `payload<{ amount: number }>()` is a compile-time marker — not a cast of `{}`.
+ */
+export function payload() {
+    return {};
+}
+export function eventType(namespace, key) {
+    return `${namespace}.${key}`;
+}
+export function defineEventCatalog(namespace, entries) {
+    return {
+        namespace,
+        entries,
+        event(key, eventPayload, meta) {
+            const { runId, ...rest } = meta;
+            // SAFETY: createEvent returns EventEnvelope with inferred payload type.
+            return createEvent(runId, {
+                ...rest,
+                type: eventType(namespace, key),
+                payload: asJson(eventPayload),
+            });
+        },
+        input(key, eventPayload, meta) {
+            return {
+                ...meta,
+                type: eventType(namespace, key),
+                // SAFETY: asJson returns typed payload for catalog event.
+                payload: asJson(eventPayload),
+            };
+        },
+    };
+}
+export function isCatalogEvent(event, catalog) {
+    return event.type.startsWith(`${catalog.namespace}.`);
+}

package/dist/core/coalesce.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Per-key coalescing append buffer.
+ * - `push` enqueues and succeeds without waiting for the store ack (unless over `maxPending`).
+ * - At most one flush is in flight per key; arrivals during a flush form the next batch.
+ * - Buffer order is flush order. Independent keys flush concurrently.
+ * - A failed flush poisons the key: later `push` calls fail, `drain` still succeeds.
+ */
+import { Effect } from 'effect';
+export interface CoalescingAppenderOptions {
+    /** When the buffer exceeds this size, `push` waits for the next flush. Default 1024. */
+    readonly maxPending?: number;
+    /** Extra delay before the first flush of an idle key. `0` (default) yields to the scheduler. */
+    readonly lingerMs?: number;
+}
+export declare function createCoalescingAppender<T, E = Error>(flush: (key: string, batch: readonly T[]) => Effect.Effect<void, E>, options?: CoalescingAppenderOptions): {
+    push: (key: string, event: T) => Effect.Effect<void, E>;
+    drain: (key: string) => Effect.Effect<void>;
+    clear: (key?: string) => void;
+    size: () => number;
+};
+export type CoalescingAppender<T, E = Error> = ReturnType<typeof createCoalescingAppender<T, E>>;

package/dist/core/coalesce.js

@@ -0,0 +1,178 @@
+/**
+ * Per-key coalescing append buffer.
+ * - `push` enqueues and succeeds without waiting for the store ack (unless over `maxPending`).
+ * - At most one flush is in flight per key; arrivals during a flush form the next batch.
+ * - Buffer order is flush order. Independent keys flush concurrently.
+ * - A failed flush poisons the key: later `push` calls fail, `drain` still succeeds.
+ */
+import { Deferred, Effect, Exit, Ref } from 'effect';
+function createState() {
+    return {
+        buffer: [],
+        flushing: false,
+        scheduled: false,
+        poison: undefined,
+        nextFlush: Deferred.makeUnsafe(),
+    };
+}
+const completeFlush = (state, cause) => Effect.gen(function* () {
+    const current = state.nextFlush;
+    state.nextFlush = Deferred.makeUnsafe();
+    if (cause) {
+        yield* Deferred.failCause(current, cause);
+        return;
+    }
+    yield* Deferred.succeed(current, undefined);
+});
+export function createCoalescingAppender(flush, options) {
+    const maxPending = options?.maxPending ?? 1024;
+    const lingerMs = options?.lingerMs ?? 0;
+    const states = Ref.makeUnsafe(new Map());
+    const evictIfIdle = (key) => Ref.update(states, (map) => {
+        const state = map.get(key);
+        if (!state ||
+            state.buffer.length > 0 ||
+            state.flushing ||
+            state.scheduled ||
+            state.poison !== undefined) {
+            return map;
+        }
+        const next = new Map(map);
+        next.delete(key);
+        return next;
+    });
+    const take = (key) => Ref.modify(states, (map) => {
+        const state = map.get(key);
+        if (!state) {
+            return [{ kind: 'gone' }, map];
+        }
+        if (state.buffer.length === 0) {
+            state.flushing = false;
+            state.scheduled = false;
+            return [{ kind: 'idle', state }, map];
+        }
+        const batch = state.buffer;
+        state.buffer = [];
+        state.flushing = true;
+        state.scheduled = false;
+        return [{ kind: 'batch', batch, state }, map];
+    });
+    const stillCurrent = (key, state) => Ref.modify(states, (map) => [map.get(key) === state, map]);
+    const runFlush = (key) => Effect.gen(function* () {
+        while (true) {
+            const taken = yield* take(key);
+            switch (taken.kind) {
+                case 'gone':
+                    return;
+                case 'idle':
+                    yield* completeFlush(taken.state);
+                    yield* evictIfIdle(key);
+                    return;
+                case 'batch': {
+                    const exit = yield* Effect.exit(flush(key, taken.batch));
+                    if (Exit.isFailure(exit)) {
+                        const current = yield* stillCurrent(key, taken.state);
+                        if (current) {
+                            taken.state.poison = exit.cause;
+                            taken.state.buffer = [];
+                            taken.state.flushing = false;
+                            taken.state.scheduled = false;
+                            yield* completeFlush(taken.state, exit.cause);
+                        }
+                        return;
+                    }
+                    const current = yield* stillCurrent(key, taken.state);
+                    if (!current) {
+                        return;
+                    }
+                    yield* completeFlush(taken.state);
+                    continue;
+                }
+                default: {
+                    const exhaustiveCheck = taken;
+                    return exhaustiveCheck;
+                }
+            }
+        }
+    });
+    const scheduleFlush = (key) => Effect.sync(() => {
+        Effect.runFork((lingerMs > 0 ? Effect.sleep(lingerMs) : Effect.yieldNow).pipe(Effect.andThen(runFlush(key))));
+    });
+    const enqueue = (key, event) => Ref.modify(states, (map) => {
+        const existing = map.get(key);
+        if (existing?.poison !== undefined) {
+            return [{ kind: 'poisoned', cause: existing.poison }, map];
+        }
+        const next = existing ? map : new Map(map);
+        const state = existing ?? createState();
+        if (!existing) {
+            next.set(key, state);
+        }
+        state.buffer.push(event);
+        const shouldSchedule = !state.flushing && !state.scheduled;
+        if (shouldSchedule) {
+            state.scheduled = true;
+        }
+        return [
+            {
+                kind: 'enqueued',
+                shouldSchedule,
+                pending: state.buffer.length,
+                deferred: state.nextFlush,
+            },
+            next,
+        ];
+    });
+    const push = (key, event) => Effect.gen(function* () {
+        const result = yield* enqueue(key, event);
+        switch (result.kind) {
+            case 'poisoned':
+                return yield* Effect.failCause(result.cause);
+            case 'enqueued': {
+                if (result.shouldSchedule) {
+                    yield* scheduleFlush(key);
+                }
+                if (result.pending > maxPending) {
+                    yield* Deferred.await(result.deferred);
+                }
+                return;
+            }
+            default: {
+                const exhaustiveCheck = result;
+                return exhaustiveCheck;
+            }
+        }
+    });
+    const drain = (key) => Effect.gen(function* () {
+        while (true) {
+            const wait = yield* Ref.modify(states, (map) => {
+                const state = map.get(key);
+                if (!state ||
+                    state.poison !== undefined ||
+                    (state.buffer.length === 0 && !state.flushing && !state.scheduled)) {
+                    return [{ kind: 'done' }, map];
+                }
+                return [{ kind: 'wait', deferred: state.nextFlush }, map];
+            });
+            if (wait.kind === 'done') {
+                return;
+            }
+            yield* Deferred.await(wait.deferred).pipe(Effect.ignoreCause);
+        }
+    });
+    const clear = (key) => {
+        Effect.runSync(Ref.update(states, (map) => {
+            if (key === undefined) {
+                return new Map();
+            }
+            if (!map.has(key)) {
+                return map;
+            }
+            const next = new Map(map);
+            next.delete(key);
+            return next;
+        }));
+    };
+    const size = () => Effect.runSync(Ref.get(states)).size;
+    return { push, drain, clear, size };
+}

package/dist/core/compose.d.ts

@@ -0,0 +1,59 @@
+import { Effect } from 'effect';
+import type { CatalogEvent, EventCatalog } from './catalog';
+import type { EffectDefinition } from './effects';
+import type { EventEnvelope } from './envelope';
+import type { FoldRegistry } from './fold';
+import type { AnyRuntimeModule, EffectMiddleware, RuntimeModule, RegisteredDefinition } from './module';
+import type { ProjectionDefinition } from './projection';
+import { protocolCatalog } from './protocol';
+import type { ThreadDefinition } from './thread';
+declare const ModuleCompositionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ModuleCompositionError";
+} & Readonly<A>;
+export declare class ModuleCompositionError extends ModuleCompositionError_base<{
+    readonly message: string;
+}> {
+    constructor(text: string);
+}
+export interface ComposedRegistry extends FoldRegistry {
+    readonly definitions: readonly RegisteredDefinition[];
+    readonly modules: readonly AnyRuntimeModule[];
+    readonly effects: ReadonlyMap<string, EffectDefinition>;
+    readonly projections: ReadonlyMap<string, ProjectionDefinition>;
+    readonly catalogs: readonly EventCatalog[];
+    readonly middleware: readonly EffectMiddleware[];
+}
+export declare function composeModules(modules: readonly AnyRuntimeModule[]): ComposedRegistry;
+export declare function composeModulesEffect(modules: readonly AnyRuntimeModule[]): Effect.Effect<ComposedRegistry, ModuleCompositionError>;
+export type ProtocolEvents = CatalogEvent<'runtime', typeof protocolCatalog.entries>;
+export type ModuleEvents<T> = T extends {
+    readonly events?: infer C;
+} ? C extends EventCatalog<infer N, infer E> ? CatalogEvent<N, E> : never : never;
+export type EventsOf<T> = T extends (...args: never[]) => infer R ? EventsOf<R> : T extends (...args: any[]) => infer R ? EventsOf<R> : T extends {
+    readonly modules: infer M;
+} ? EventsOf<M> : T extends readonly (infer Item)[] ? Item extends AnyRuntimeModule ? ProtocolEvents | ModuleEvents<Item> : Item extends EventCatalog<infer N, infer E> ? ProtocolEvents | CatalogEvent<N, E> : EventEnvelope : T extends RuntimeModule ? ProtocolEvents | ModuleEvents<T> : T extends EventCatalog<infer N, infer E> ? CatalogEvent<N, E> : EventEnvelope;
+export type EffectsOf<T> = T extends {
+    readonly modules: infer M;
+} ? M extends readonly AnyRuntimeModule[] ? ModuleEffects<M[number]> : string : T extends RuntimeModule ? ModuleEffects<T> : string;
+type ModuleEffects<T> = T extends {
+    readonly effects: infer E;
+} ? E extends {
+    readonly [key: string]: EffectDefinition;
+} ? E[keyof E]['type'] : never : never;
+export type ThreadsOf<T> = T extends {
+    readonly modules: infer M;
+} ? M extends readonly AnyRuntimeModule[] ? ModuleKinds<M[number]> : string : T extends RuntimeModule ? ModuleKinds<T> : string;
+type ModuleKinds<T> = T extends {
+    readonly threads: infer E;
+} ? E extends {
+    readonly [key: string]: ThreadDefinition;
+} ? keyof E & string : never : never;
+export type ProjectionsOf<T> = T extends {
+    readonly modules: infer M;
+} ? M extends readonly AnyRuntimeModule[] ? ModuleProjectionNames<M[number]> : string : T extends RuntimeModule ? ModuleProjectionNames<T> : string;
+type ModuleProjectionNames<T> = T extends {
+    readonly projections: infer P;
+} ? P extends {
+    readonly [key: string]: ProjectionDefinition;
+} ? keyof P & string : never : never;
+export {};

package/dist/core/compose.js

@@ -0,0 +1,97 @@
+import { Data, Effect } from 'effect';
+import { protocolCatalog } from './protocol.js';
+export class ModuleCompositionError extends Data.TaggedError('ModuleCompositionError') {
+    constructor(text) {
+        super({ message: text });
+        this.name = 'ModuleCompositionError';
+    }
+}
+export function composeModules(modules) {
+    const definitions = [];
+    const definitionKeys = new Set();
+    const namespaces = new Set();
+    const threads = new Map();
+    const effects = new Map();
+    const projections = new Map();
+    const middleware = [];
+    const catalogs = [protocolCatalog];
+    for (const module of modules) {
+        if (namespaces.has(module.namespace)) {
+            throw new ModuleCompositionError(`Duplicate module namespace: ${module.namespace}`);
+        }
+        namespaces.add(module.namespace);
+        if (module.dependencies) {
+            for (const dep of module.dependencies) {
+                if (!namespaces.has(dep.namespace) && dep.namespace !== 'runtime') {
+                    const present = modules.some((item) => item.namespace === dep.namespace);
+                    if (!present) {
+                        throw new ModuleCompositionError(`Module ${module.namespace} depends on missing module ${dep.namespace}`);
+                    }
+                }
+            }
+        }
+        if (module.events && !catalogs.some((c) => c.namespace === module.events.namespace)) {
+            catalogs.push(module.events);
+        }
+        if (module.observes) {
+            for (const obs of module.observes) {
+                if (!catalogs.some((c) => c.namespace === obs.namespace)) {
+                    catalogs.push(obs);
+                }
+            }
+        }
+        for (const definition of module.definitions ?? []) {
+            const key = `${definition.kind}:${definition.name}`;
+            if (definitionKeys.has(key)) {
+                throw new ModuleCompositionError(`Duplicate definition: ${key}`);
+            }
+            if (!module.threads || !Object.hasOwn(module.threads, definition.kind)) {
+                throw new ModuleCompositionError(`Module ${module.namespace} registers definition ${key} but does not implement thread kind ${definition.kind}`);
+            }
+            definitionKeys.add(key);
+            definitions.push({
+                kind: definition.kind,
+                name: definition.name,
+                input: definition.input,
+                value: definition,
+            });
+        }
+        const moduleThreads = module.threads;
+        if (moduleThreads) {
+            for (const [kind, definition] of Object.entries(moduleThreads)) {
+                if (threads.has(kind)) {
+                    throw new ModuleCompositionError(`Duplicate thread kind: ${kind}`);
+                }
+                threads.set(kind, definition);
+            }
+        }
+        if (module.effects) {
+            for (const definition of Object.values(module.effects)) {
+                if (effects.has(definition.type)) {
+                    throw new ModuleCompositionError(`Duplicate effect type: ${definition.type}`);
+                }
+                effects.set(definition.type, definition);
+            }
+        }
+        if (module.middleware) {
+            middleware.push(...module.middleware);
+        }
+        if (module.projections) {
+            for (const definition of Object.values(module.projections)) {
+                if (projections.has(definition.name)) {
+                    throw new ModuleCompositionError(`Duplicate projection: ${definition.name}`);
+                }
+                projections.set(definition.name, definition);
+            }
+        }
+    }
+    return { definitions, modules, threads, effects, projections, catalogs, middleware };
+}
+export function composeModulesEffect(modules) {
+    return Effect.try({
+        try: () => composeModules(modules),
+        catch: (cause) => cause instanceof ModuleCompositionError
+            ? cause
+            : new ModuleCompositionError(cause instanceof Error ? cause.message : String(cause)),
+    });
+}

package/dist/core/cursor.d.ts

@@ -0,0 +1,16 @@
+import { type AppendableEvent, type EventEnvelope } from './envelope';
+import { type FoldRegistry } from './fold';
+import { type RunState } from './state';
+import type { AppendResult } from './store';
+export interface RunCursor {
+    readonly state: RunState;
+    readonly seq: number;
+    readonly durableSinceSnapshot: number;
+}
+export declare function emptyCursor(runId: string): RunCursor;
+/**
+ * Folds events into the cursor. Ephemeral events are skipped by `foldEvent`
+ * (no RunState change) but still advance `seq`.
+ */
+export declare function advanceCursor(cursor: RunCursor, events: readonly EventEnvelope[], registry: FoldRegistry): RunCursor;
+export declare function assignSequences(batch: readonly AppendableEvent[], result: AppendResult): EventEnvelope[];

package/dist/core/cursor.js

@@ -0,0 +1,46 @@
+import { withAssignedSeq } from './envelope.js';
+import { foldEvent } from './fold.js';
+import { emptyRunState } from './state.js';
+export function emptyCursor(runId) {
+    return {
+        state: emptyRunState(runId),
+        seq: 0,
+        durableSinceSnapshot: 0,
+    };
+}
+/**
+ * Folds events into the cursor. Ephemeral events are skipped by `foldEvent`
+ * (no RunState change) but still advance `seq`.
+ */
+export function advanceCursor(cursor, events, registry) {
+    let state = cursor.state;
+    let seq = cursor.seq;
+    let durableSinceSnapshot = cursor.durableSinceSnapshot;
+    for (const event of events) {
+        if (event.seq > seq) {
+            seq = event.seq;
+        }
+        if (!event.ephemeral) {
+            if (event.type === 'runtime.snapshot.taken') {
+                durableSinceSnapshot = 0;
+            }
+            else {
+                durableSinceSnapshot += 1;
+            }
+        }
+        state = foldEvent(state, event, registry);
+    }
+    return { state, seq, durableSinceSnapshot };
+}
+export function assignSequences(batch, result) {
+    if (batch.length !== result.sequences.length) {
+        throw new Error(`assignSequences length mismatch: batch has ${batch.length} events but append returned ${result.sequences.length} sequences`);
+    }
+    return batch.map((partial, index) => {
+        const seq = result.sequences[index];
+        if (seq === undefined) {
+            throw new Error(`assignSequences missing sequence at index ${index}`);
+        }
+        return withAssignedSeq(partial, partial.runId, seq);
+    });
+}