@swirls/looms 0.0.1

package/dist/core/sqlite-store.js

@@ -0,0 +1,328 @@
+import { Effect, Option, Queue, Schema, Stream } from 'effect';
+import { EventEnvelopeSchema, fromWireEvent, withAssignedSeq } from './envelope.js';
+import { SnapshotStoreError, withSnapshotStore, } from './snapshot-store.js';
+import { EventStoreConflictError, EventStoreError, EventStoreFencedError, } from './store.js';
+export const SQLITE_EVENT_STORE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS looms_streams (
+  run_id TEXT PRIMARY KEY,
+  head INTEGER NOT NULL DEFAULT 1,
+  tail INTEGER NOT NULL DEFAULT 0,
+  fence_token TEXT
+);
+
+CREATE TABLE IF NOT EXISTS looms_events (
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  body TEXT NOT NULL,
+  PRIMARY KEY (run_id, seq)
+);
+
+CREATE TABLE IF NOT EXISTS looms_snapshots (
+  run_id TEXT NOT NULL,
+  cursor INTEGER NOT NULL,
+  state_hash TEXT NOT NULL,
+  taken_at INTEGER NOT NULL,
+  state TEXT NOT NULL,
+  PRIMARY KEY (run_id, cursor)
+);
+`.trim();
+const StreamRowSchema = Schema.Struct({
+    run_id: Schema.String,
+    head: Schema.Number,
+    tail: Schema.Number,
+    fence_token: Schema.NullOr(Schema.String),
+});
+const EventRowSchema = Schema.Struct({
+    body: Schema.String,
+});
+const SnapshotRowSchema = Schema.Struct({
+    run_id: Schema.String,
+    cursor: Schema.Number,
+    state_hash: Schema.String,
+    taken_at: Schema.Number,
+    state: Schema.String,
+});
+const RunIdRowSchema = Schema.Struct({
+    run_id: Schema.String,
+});
+const CursorRowSchema = Schema.Struct({
+    cursor: Schema.Number,
+});
+const decodeEventBody = Schema.decodeUnknownSync(Schema.fromJsonString(EventEnvelopeSchema));
+const decodeRunState = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
+const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+const decodeStreamRow = Schema.decodeUnknownSync(StreamRowSchema);
+const decodeEventRow = Schema.decodeUnknownSync(EventRowSchema);
+const decodeSnapshotRow = Schema.decodeUnknownSync(SnapshotRowSchema);
+const decodeRunIdRow = Schema.decodeUnknownSync(RunIdRowSchema);
+const decodeCursorRow = Schema.decodeUnknownSync(CursorRowSchema);
+/** Adapter for Cloudflare Durable Object `ctx.storage.sql`. */
+export function sqlStorageExec(sql, options) {
+    return {
+        run(sqlText, params = []) {
+            void sql.exec(sqlText, ...params);
+        },
+        rows(sqlText, params = []) {
+            return [...sql.exec(sqlText, ...params)];
+        },
+        transaction: options?.transaction,
+    };
+}
+function runInTransaction(exec, fn) {
+    if (exec.transaction) {
+        return exec.transaction(fn);
+    }
+    exec.run('BEGIN IMMEDIATE');
+    try {
+        const result = fn();
+        exec.run('COMMIT');
+        return result;
+    }
+    catch (cause) {
+        try {
+            exec.run('ROLLBACK');
+        }
+        catch {
+            // Ignore rollback failures so the original error surfaces.
+        }
+        throw cause;
+    }
+}
+function initSchema(exec) {
+    for (const statement of SQLITE_EVENT_STORE_SCHEMA.split(';')) {
+        const sql = statement.trim();
+        if (sql.length > 0) {
+            exec.run(sql);
+        }
+    }
+}
+function parseEvent(body) {
+    return fromWireEvent(decodeEventBody(body));
+}
+function toSnapshot(row) {
+    // SAFETY: snapshot state is a JSON-encoded RunState written by this store.
+    const state = decodeRunState(row.state);
+    return {
+        runId: row.run_id,
+        cursor: row.cursor,
+        stateHash: row.state_hash,
+        takenAt: row.taken_at,
+        state,
+    };
+}
+function createSqliteSnapshotStore(exec) {
+    return {
+        loadLatest: (runId) => Effect.try({
+            try: () => {
+                const [row] = exec.rows('SELECT run_id, cursor, state_hash, taken_at, state FROM looms_snapshots WHERE run_id = ? ORDER BY cursor DESC LIMIT 1', [runId]);
+                return row === undefined ? Option.none() : Option.some(toSnapshot(decodeSnapshotRow(row)));
+            },
+            catch: (cause) => new SnapshotStoreError(`Failed to load snapshot for ${runId}`, cause),
+        }),
+        save: (snapshot) => Effect.try({
+            try: () => {
+                exec.run(`INSERT INTO looms_snapshots (run_id, cursor, state_hash, taken_at, state)
+             VALUES (?, ?, ?, ?, ?)
+             ON CONFLICT (run_id, cursor) DO UPDATE SET
+               state_hash = excluded.state_hash,
+               taken_at = excluded.taken_at,
+               state = excluded.state`, [
+                    snapshot.runId,
+                    snapshot.cursor,
+                    snapshot.stateHash,
+                    snapshot.takenAt,
+                    encodeJson(snapshot.state),
+                ]);
+            },
+            catch: (cause) => new SnapshotStoreError(`Failed to save snapshot for ${snapshot.runId}`, cause),
+        }),
+        listCursors: (runId) => Effect.try({
+            try: () => exec
+                .rows('SELECT cursor FROM looms_snapshots WHERE run_id = ? ORDER BY cursor ASC', [
+                runId,
+            ])
+                .map((row) => decodeCursorRow(row).cursor),
+            catch: (cause) => new SnapshotStoreError(`Failed to list snapshots for ${runId}`, cause),
+        }),
+        prune: (runId, keepLatest) => Effect.try({
+            try: () => {
+                const cursors = exec
+                    .rows('SELECT cursor FROM looms_snapshots WHERE run_id = ? ORDER BY cursor DESC', [
+                    runId,
+                ])
+                    .map((row) => decodeCursorRow(row).cursor);
+                const drop = cursors.slice(Math.max(0, keepLatest));
+                for (const cursor of drop) {
+                    exec.run('DELETE FROM looms_snapshots WHERE run_id = ? AND cursor = ?', [runId, cursor]);
+                }
+            },
+            catch: (cause) => new SnapshotStoreError(`Failed to prune snapshots for ${runId}`, cause),
+        }),
+    };
+}
+function createSqliteEventStore(exec) {
+    const waiters = new Map();
+    const getStream = (runId) => {
+        const [existingRow] = exec.rows('SELECT run_id, head, tail, fence_token FROM looms_streams WHERE run_id = ?', [runId]);
+        const existing = existingRow === undefined ? undefined : decodeStreamRow(existingRow);
+        if (existing) {
+            return existing;
+        }
+        return { run_id: runId, head: 1, tail: 0, fence_token: null };
+    };
+    const ensureStream = (runId) => {
+        const existing = getStream(runId);
+        const [listedRow] = exec.rows('SELECT run_id FROM looms_streams WHERE run_id = ?', [runId]);
+        const listed = listedRow === undefined ? undefined : decodeRunIdRow(listedRow);
+        if (existing.tail > 0 || listed) {
+            return existing;
+        }
+        exec.run('INSERT OR IGNORE INTO looms_streams (run_id, head, tail) VALUES (?, 1, 0)', [runId]);
+        return getStream(runId);
+    };
+    const notify = (runId, events) => {
+        const listeners = waiters.get(runId);
+        if (!listeners) {
+            return;
+        }
+        for (const event of events) {
+            for (const waiter of listeners) {
+                waiter(event);
+            }
+        }
+    };
+    const service = {
+        append: (runId, events, options) => Effect.try({
+            try: () => {
+                if (events.length === 0 && options?.fence === undefined) {
+                    return { sequences: [], tail: getStream(runId).tail };
+                }
+                return runInTransaction(exec, () => {
+                    const log = ensureStream(runId);
+                    if (options?.expectedTail !== undefined && log.tail !== options.expectedTail) {
+                        throw new EventStoreConflictError(runId, options.expectedTail, log.tail);
+                    }
+                    if (options?.fencingToken !== undefined &&
+                        (log.fence_token ?? undefined) !== options.fencingToken) {
+                        throw new EventStoreFencedError(runId, options.fencingToken);
+                    }
+                    let nextTail = log.tail;
+                    let fenceToken = log.fence_token;
+                    if (options?.fence !== undefined) {
+                        nextTail += 1;
+                        fenceToken = options.fence === '' ? null : options.fence;
+                    }
+                    const sequences = [];
+                    const appended = [];
+                    for (const partial of events) {
+                        const seq = nextTail + appended.length + 1;
+                        const event = withAssignedSeq(partial, runId, seq);
+                        appended.push(event);
+                        sequences.push(seq);
+                        exec.run('INSERT INTO looms_events (run_id, seq, body) VALUES (?, ?, ?)', [
+                            runId,
+                            seq,
+                            encodeJson(event),
+                        ]);
+                    }
+                    nextTail += appended.length;
+                    exec.run(`INSERT INTO looms_streams (run_id, head, tail, fence_token)
+               VALUES (?, ?, ?, ?)
+               ON CONFLICT (run_id) DO UPDATE SET
+                 tail = excluded.tail,
+                 fence_token = excluded.fence_token`, [runId, log.head, nextTail, fenceToken]);
+                    notify(runId, appended);
+                    return { sequences, tail: nextTail };
+                });
+            },
+            catch: (cause) => cause instanceof EventStoreConflictError ||
+                cause instanceof EventStoreFencedError ||
+                cause instanceof EventStoreError
+                ? cause
+                : new EventStoreError(`append failed for ${runId}`, cause),
+        }),
+        read: (runId, options) => Effect.try({
+            try: () => {
+                const fromSeq = options?.fromSeq ?? 1;
+                const limit = options?.limit;
+                const sql = limit === undefined
+                    ? 'SELECT body FROM looms_events WHERE run_id = ? AND seq >= ? ORDER BY seq ASC'
+                    : 'SELECT body FROM looms_events WHERE run_id = ? AND seq >= ? ORDER BY seq ASC LIMIT ?';
+                const params = limit === undefined ? [runId, fromSeq] : [runId, fromSeq, limit];
+                return exec.rows(sql, params).map((row) => parseEvent(decodeEventRow(row).body));
+            },
+            catch: (cause) => new EventStoreError(`read failed for ${runId}`, cause),
+        }),
+        readStream: (runId, options) => Stream.fromIterableEffect(service.read(runId, options)),
+        tail: (runId) => Effect.try({
+            try: () => getStream(runId).tail,
+            catch: (cause) => new EventStoreError(`tail failed for ${runId}`, cause),
+        }),
+        bounds: (runId) => Effect.try({
+            try: () => {
+                const log = getStream(runId);
+                return { head: log.head, tail: log.tail };
+            },
+            catch: (cause) => new EventStoreError(`bounds failed for ${runId}`, cause),
+        }),
+        trim: (runId, beforeSeq) => Effect.try({
+            try: () => {
+                exec.run('DELETE FROM looms_events WHERE run_id = ? AND seq < ?', [runId, beforeSeq]);
+                exec.run('UPDATE looms_streams SET head = MAX(head, ?) WHERE run_id = ?', [
+                    beforeSeq,
+                    runId,
+                ]);
+            },
+            catch: (cause) => new EventStoreError(`trim failed for ${runId}`, cause),
+        }),
+        subscribe: (runId, options) => Stream.callback((queue) => Effect.gen(function* () {
+            const fromSeq = options?.fromSeq ?? 1;
+            const existing = exec
+                .rows('SELECT body FROM looms_events WHERE run_id = ? AND seq >= ? ORDER BY seq ASC', [
+                runId,
+                fromSeq,
+            ])
+                .map((row) => parseEvent(decodeEventRow(row).body));
+            for (const event of existing) {
+                Queue.offerUnsafe(queue, event);
+            }
+            const waiter = (event) => {
+                if (event.seq >= fromSeq) {
+                    Queue.offerUnsafe(queue, event);
+                }
+            };
+            const listeners = waiters.get(runId) ?? [];
+            listeners.push(waiter);
+            waiters.set(runId, listeners);
+            yield* Effect.addFinalizer(() => Effect.sync(() => {
+                const current = waiters.get(runId);
+                if (!current) {
+                    return;
+                }
+                const idx = current.indexOf(waiter);
+                if (idx >= 0) {
+                    current.splice(idx, 1);
+                }
+                if (current.length === 0) {
+                    waiters.delete(runId);
+                }
+            }));
+        })),
+        listRuns: () => Effect.try({
+            try: () => exec
+                .rows('SELECT run_id FROM looms_streams ORDER BY run_id ASC')
+                .map((row) => decodeRunIdRow(row).run_id),
+            catch: (cause) => new EventStoreError('listRuns failed', cause),
+        }),
+    };
+    return service;
+}
+/**
+ * Embedded SQLite EventStore for actor-local execution.
+ * Snapshots live in the same database and are attached automatically.
+ */
+export function sqliteEventStore(options) {
+    const exec = options.exec;
+    initSchema(exec);
+    return withSnapshotStore(createSqliteEventStore(exec), createSqliteSnapshotStore(exec));
+}

package/dist/core/state.d.ts

@@ -0,0 +1,43 @@
+import type { RuntimeEffect, WaitCondition } from './effects';
+import type { JsonValue, ThreadStatus, RunStatus } from './types';
+export interface ThreadRecord {
+    threadId: string;
+    kind: string;
+    definitionName: string;
+    parentThreadId: string | null;
+    status: ThreadStatus;
+    input: JsonValue;
+    output: JsonValue | null;
+    error: string | null;
+    state: JsonValue;
+}
+export interface WaitRecord {
+    waitId: string;
+    threadId: string;
+    on: WaitCondition;
+    tag?: JsonValue;
+}
+export interface OutstandingEffect {
+    effectId: string;
+    threadId: string;
+    causingSeq: number;
+    causingEventId: string;
+    effect: RuntimeEffect;
+}
+export interface RunState {
+    runId: string;
+    status: RunStatus;
+    rootThreadId: string | null;
+    threads: {
+        [threadId: string]: ThreadRecord;
+    };
+    waits: {
+        [waitId: string]: WaitRecord;
+    };
+    outstandingEffects: OutstandingEffect[];
+    completedEffectIds?: string[];
+    processedIdempotencyKeys?: string[];
+}
+export declare function emptyRunState(runId: string): RunState;
+export declare function isRunTerminal(state: RunState): boolean;
+export declare function isRunParked(state: RunState): boolean;

package/dist/core/state.js

@@ -0,0 +1,31 @@
+export function emptyRunState(runId) {
+    return {
+        runId,
+        status: 'running',
+        rootThreadId: null,
+        threads: {},
+        waits: {},
+        outstandingEffects: [],
+        completedEffectIds: [],
+        processedIdempotencyKeys: [],
+    };
+}
+export function isRunTerminal(state) {
+    return state.status === 'completed' || state.status === 'failed' || state.status === 'cancelled';
+}
+export function isRunParked(state) {
+    if (isRunTerminal(state)) {
+        return true;
+    }
+    if (state.outstandingEffects.length > 0) {
+        return false;
+    }
+    const records = Object.values(state.threads);
+    if (records.length === 0) {
+        return false;
+    }
+    return records.every((record) => record.status === 'waiting' ||
+        record.status === 'completed' ||
+        record.status === 'failed' ||
+        record.status === 'cancelled');
+}

package/dist/core/store.d.ts

@@ -0,0 +1,146 @@
+import { Context, Effect, Layer, Stream } from 'effect';
+import { type AppendableEvent, type EventEnvelope } from './envelope';
+declare const EventStoreError_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: "EventStoreError";
+} & Readonly<A>;
+export declare class EventStoreError extends EventStoreError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly conflict?: boolean;
+}> {
+    readonly conflict?: boolean;
+    readonly cause?: unknown;
+    constructor(text: string, cause?: unknown, options?: {
+        conflict?: boolean;
+    });
+}
+declare const EventStoreConflictError_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: "EventStoreConflictError";
+} & Readonly<A>;
+export declare class EventStoreConflictError extends EventStoreConflictError_base<{
+    readonly runId: string;
+    readonly expectedTail: number;
+    readonly actualTail: number;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    readonly conflict = true;
+    constructor(runId: string, expectedTail: number, actualTail: number, cause?: unknown);
+}
+declare const EventStoreTruncationError_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: "EventStoreTruncationError";
+} & Readonly<A>;
+export declare class EventStoreTruncationError extends EventStoreTruncationError_base<{
+    readonly runId: string;
+    readonly readCount: number;
+    readonly tail: number;
+    readonly message: string;
+}> {
+    constructor(runId: string, readCount: number, tail: number);
+}
+declare const EventStoreTrimmedError_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: "EventStoreTrimmedError";
+} & Readonly<A>;
+export declare class EventStoreTrimmedError extends EventStoreTrimmedError_base<{
+    readonly runId: string;
+    readonly head: number;
+    readonly requestedSeq: number;
+    readonly message: string;
+}> {
+    constructor(runId: string, head: number, requestedSeq: number);
+}
+declare const EventStoreFencedError_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: "EventStoreFencedError";
+} & Readonly<A>;
+export declare class EventStoreFencedError extends EventStoreFencedError_base<{
+    readonly runId: string;
+    readonly token: string;
+    readonly message: string;
+}> {
+    constructor(runId: string, token: string);
+}
+export type EventStoreAppendError = EventStoreError | EventStoreConflictError | EventStoreFencedError;
+export type AnyEventStoreError = EventStoreError | EventStoreConflictError | EventStoreTruncationError | EventStoreTrimmedError | EventStoreFencedError;
+export declare function isEventStoreError(err: unknown): err is AnyEventStoreError;
+export interface StreamBounds {
+    readonly head: number;
+    readonly tail: number;
+}
+export interface AppendOptions {
+    readonly expectedTail?: number;
+    /** Set the stream fencing token atomically in this batch (`''` clears). */
+    readonly fence?: string;
+    /** Must match the stream's current fencing token, or the append fails. */
+    readonly fencingToken?: string;
+}
+export interface PaginatePagesOptions<SCursor> {
+    readonly initialCursor: SCursor;
+    readonly limit?: number;
+}
+/**
+ * Pure Effect-native stream pagination primitive.
+ *
+ * Lazily pulls pages using `fetchPage` until:
+ * 1. `fetchPage` returns null or an empty record list,
+ * 2. `nextCursor` is null/undefined (signaling stream exhaustion / tail reached),
+ * 3. Or the caller's optional `limit` is satisfied (avoiding subsequent page fetches).
+ */
+export declare function paginatePages<T, SCursor, E = never, R = never>(options: PaginatePagesOptions<SCursor>, fetchPage: (cursor: SCursor) => Effect.Effect<{
+    readonly records: ReadonlyArray<T>;
+    readonly nextCursor?: SCursor | null;
+} | null, E, R>): Stream.Stream<T, E, R>;
+export interface AppendResult {
+    sequences: number[];
+    tail: number;
+}
+export interface EventStore {
+    readonly append: (runId: string, events: ReadonlyArray<AppendableEvent>, options?: AppendOptions) => Effect.Effect<AppendResult, EventStoreAppendError>;
+    /**
+     * Reads events for a run in sequence order.
+     *
+     * Contract:
+     * - If `limit` is omitted, returns every event from `fromSeq` (default 1) through
+     *   the current stream tail. Implementations must page internally if the backing
+     *   storage limits unary reads (e.g. S2 1000-record / 1 MiB limits).
+     * - If `limit` is provided, returns at most `limit` events starting from `fromSeq`.
+     *   Callers using `limit` must page with their own cursor.
+     * - If the stream does not exist or has no events at or beyond `fromSeq`, returns an empty array.
+     */
+    readonly read: (runId: string, options?: {
+        fromSeq?: number;
+        limit?: number;
+    }) => Effect.Effect<EventEnvelope[], EventStoreError>;
+    /**
+     * Reads events for a run as an interruptible stream in sequence order.
+     */
+    readonly readStream?: (runId: string, options?: {
+        fromSeq?: number;
+        limit?: number;
+    }) => Stream.Stream<EventEnvelope, EventStoreError>;
+    readonly tail: (runId: string) => Effect.Effect<number, EventStoreError>;
+    /**
+     * Sequence bounds of the retained log.
+     * `head` is the seq of the first retained record (1 when nothing trimmed, `tail + 1` when empty).
+     */
+    readonly bounds?: (runId: string) => Effect.Effect<StreamBounds, EventStoreError>;
+    /** Discard records with `seq < beforeSeq`. */
+    readonly trim?: (runId: string, beforeSeq: number) => Effect.Effect<void, EventStoreError>;
+    readonly subscribe: (runId: string, options?: {
+        fromSeq?: number;
+    }) => Stream.Stream<EventEnvelope, EventStoreError>;
+    readonly listRuns: () => Effect.Effect<string[], EventStoreError>;
+}
+/**
+ * Utility to read an EventStore as a Stream.Stream, using `store.readStream` if implemented
+ * or falling back to `Stream.fromIterableEffect(store.read(...))`.
+ */
+export declare function readEventStream(store: EventStore, runId: string, options?: {
+    fromSeq?: number;
+    limit?: number;
+}): Stream.Stream<EventEnvelope, EventStoreError>;
+declare const EventStoreTag_base: Context.ServiceClass<EventStoreTag, "looms/EventStore", EventStore>;
+export declare class EventStoreTag extends EventStoreTag_base {
+}
+export declare const makeMemoryEventStore: Effect.Effect<EventStore, never, never>;
+export declare const MemoryEventStoreLive: Layer.Layer<EventStoreTag, never, never>;
+export {};