@swirls/looms 0.0.1

package/dist/s2/store.js

@@ -0,0 +1,337 @@
+import { AppendInput, AppendRecord, S2, S2Endpoints, S2Error } from '@s2-dev/streamstore';
+import { Effect, Layer, Option, Predicate, Queue, Schema, Stream } from 'effect';
+import { createKeyedSerializer, EventStoreConflictError, EventStoreError, EventStoreFencedError, EventStoreTag, EventEnvelopeSchema, fromWireEvent, withSnapshotStore, } from '@swirls/looms/core';
+import { S2ConfigSchema, streamNameForRun } from './config.js';
+import { s2SnapshotStore } from './snapshot-store.js';
+function toStoreError(cause, message) {
+    if (cause instanceof EventStoreError) {
+        return cause;
+    }
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return new EventStoreError(`${message}: ${detail}`, cause);
+}
+function isUnsatisfiableCause(cause) {
+    if (cause instanceof S2Error && (cause.status === 404 || cause.status === 416)) {
+        return true;
+    }
+    if (Predicate.isReadonlyObject(cause) && (cause.status === 404 || cause.status === 416)) {
+        return true;
+    }
+    const text = cause instanceof Error ? cause.message : String(cause);
+    return text.includes('out of range') || text.includes('Range not satisfiable');
+}
+/**
+ * Paginate an S2 stream lazily using Effect Streams.
+ *
+ * Pulls pages on demand until the stream tail is reached, an empty page is returned,
+ * or the caller's optional limit is satisfied.
+ */
+export function paginateS2Stream(fetchPage, options) {
+    const fromSeq = options?.fromSeq ?? 0;
+    const userLimit = options?.limit;
+    const maxPageSize = options?.maxPageSize ?? 1000;
+    if (userLimit !== undefined && userLimit <= 0) {
+        return Stream.empty;
+    }
+    const baseStream = Stream.paginate({ cursor: fromSeq, remaining: userLimit }, (state) => Effect.gen(function* () {
+        if (state.remaining !== undefined && state.remaining <= 0) {
+            return [[], Option.none()];
+        }
+        const count = state.remaining !== undefined ? Math.min(maxPageSize, state.remaining) : maxPageSize;
+        const page = yield* fetchPage(state.cursor, count);
+        if (!page || page.records.length === 0) {
+            return [[], Option.none()];
+        }
+        const records = page.records.filter((r) => r.seqNum >= fromSeq);
+        const nextRemaining = state.remaining !== undefined ? state.remaining - records.length : undefined;
+        const lastRecord = page.records[page.records.length - 1];
+        if (!lastRecord || (nextRemaining !== undefined && nextRemaining <= 0)) {
+            return [records, Option.none()];
+        }
+        const nextCursor = Math.max(state.cursor + 1, lastRecord.seqNum + 1);
+        if (nextCursor <= state.cursor) {
+            return [records, Option.none()];
+        }
+        // A byte-capped page is shorter than `count`. Do not trust `page.tail`
+        // there — S2 may report the batch end, not the stream tail.
+        const shortPage = page.records.length < count;
+        const reachedTail = !shortPage && page.tail?.seqNum !== undefined && nextCursor >= page.tail.seqNum;
+        if (reachedTail) {
+            return [records, Option.none()];
+        }
+        return [records, Option.some({ cursor: nextCursor, remaining: nextRemaining })];
+    }));
+    return userLimit !== undefined ? baseStream.pipe(Stream.take(userLimit)) : baseStream;
+}
+export async function readAllPages(fetchPage, options) {
+    const fetchPageEffect = (cursor, count) => Effect.tryPromise({
+        try: () => fetchPage(cursor, count),
+        catch: (cause) => toStoreError(cause, 'S2 page fetch failed'),
+    });
+    const stream = paginateS2Stream(fetchPageEffect, options);
+    return Effect.runPromise(Stream.runCollect(stream));
+}
+function parseEvent(body, seqNum) {
+    const raw = JSON.parse(body);
+    const decoded = Schema.decodeUnknownSync(EventEnvelopeSchema)(raw);
+    return fromWireEvent({ ...decoded, seq: seqNum + 1 });
+}
+function createClient(config) {
+    if (Schema.is(Schema.String)(config.endpoint)) {
+        return new S2({
+            accessToken: config.accessToken,
+            endpoints: new S2Endpoints({
+                account: config.endpoint,
+                basin: config.endpoint,
+            }),
+        });
+    }
+    if (config.endpoint) {
+        return new S2({
+            accessToken: config.accessToken,
+            endpoints: new S2Endpoints(config.endpoint),
+        });
+    }
+    return new S2({ accessToken: config.accessToken });
+}
+/**
+ * Synchronous constructor for an S2-backed EventStore.
+ *
+ * Basin creation is deferred and memoized lazily on first stream access.
+ * Expected tail mismatches during `append` map to `EventStoreConflictError`.
+ */
+export function s2(config) {
+    const parsed = Schema.decodeUnknownSync(S2ConfigSchema)(config);
+    const client = createClient(parsed);
+    const basin = client.basin(parsed.basin);
+    const ensured = new Set();
+    const appends = createKeyedSerializer();
+    let basinEnsured = false;
+    const ensureBasin = Effect.tryPromise({
+        try: async () => {
+            if (basinEnsured) {
+                return;
+            }
+            try {
+                await client.basins.create({ basin: parsed.basin });
+            }
+            catch (err) {
+                // 409 = already exists
+                if (!(err instanceof S2Error && err.status === 409)) {
+                    throw err;
+                }
+            }
+            basinEnsured = true;
+        },
+        catch: (cause) => toStoreError(cause, `Failed to ensure basin ${parsed.basin}`),
+    });
+    const ensureStream = (runId) => Effect.gen(function* () {
+        yield* ensureBasin;
+        return yield* Effect.tryPromise({
+            try: async () => {
+                const name = streamNameForRun(runId);
+                if (ensured.has(name)) {
+                    return basin.stream(name);
+                }
+                try {
+                    await basin.streams.create({
+                        stream: name,
+                        config: parsed.streamConfig,
+                    });
+                }
+                catch (err) {
+                    // 409 = already exists
+                    if (!(err instanceof S2Error && err.status === 409)) {
+                        // Some local servers may not support create; try using the stream anyway.
+                        if (!(err instanceof S2Error && (err.status === 404 || err.status === 405))) {
+                            throw err;
+                        }
+                    }
+                }
+                ensured.add(name);
+                return basin.stream(name);
+            },
+            catch: (cause) => toStoreError(cause, `Failed to open stream for ${runId}`),
+        });
+    });
+    const service = {
+        append: (runId, events, options) => Effect.gen(function* () {
+            if (events.length === 0 && options?.fence === undefined) {
+                const tail = yield* service.tail(runId);
+                return { sequences: [], tail };
+            }
+            const stream = yield* ensureStream(runId);
+            const fenced = options?.fence !== undefined;
+            const eventRecords = events.map((partial) => {
+                const body = JSON.stringify({
+                    ...partial,
+                    runId,
+                    seq: partial.seq ?? 0,
+                });
+                return AppendRecord.string({
+                    body,
+                    headers: [['content-type', 'application/json']],
+                });
+            });
+            const records = fenced ? [AppendRecord.fence(options.fence), ...eventRecords] : eventRecords;
+            const input = AppendInput.create(records, {
+                matchSeqNum: options?.expectedTail,
+                fencingToken: options?.fencingToken,
+            });
+            const appendResult = yield* Effect.promise(() => appends.run(runId, () => stream.append(input).then((ack) => ({ ok: true, ack }), (err) => ({ ok: false, err }))));
+            if (!appendResult.ok) {
+                const cause = appendResult.err;
+                const message = cause instanceof Error ? cause.message.toLowerCase() : String(cause);
+                const isFence = cause instanceof S2Error &&
+                    cause.status === 412 &&
+                    (message.includes('fenc') || message.includes('token'));
+                if (isFence) {
+                    return yield* Effect.fail(new EventStoreFencedError(runId, options?.fencingToken ?? options?.fence ?? ''));
+                }
+                if (cause instanceof S2Error &&
+                    (cause.status === 409 ||
+                        cause.status === 412 ||
+                        message.includes('conflict') ||
+                        message.includes('match'))) {
+                    const tailCheck = yield* Effect.promise(() => stream.checkTail().catch(() => null));
+                    const actualTail = tailCheck?.tail?.seqNum ?? 0;
+                    return yield* Effect.fail(new EventStoreConflictError(runId, options?.expectedTail ?? 0, actualTail));
+                }
+                return yield* Effect.fail(toStoreError(cause, `Append failed for ${runId}`));
+            }
+            const ack = appendResult.ack;
+            const sequences = [];
+            const eventOffset = fenced ? 1 : 0;
+            for (let i = 0; i < events.length; i++) {
+                sequences.push(ack.start.seqNum + eventOffset + i + 1);
+            }
+            return { sequences, tail: ack.tail.seqNum };
+        }),
+        readStream: (runId, options) => {
+            const fromSeq = options?.fromSeq ?? 1;
+            const s2From = Math.max(0, fromSeq - 1);
+            return Stream.unwrap(Effect.gen(function* () {
+                const stream = yield* ensureStream(runId);
+                const fetchPage = (cursor, count) => Effect.tryPromise({
+                    try: async () => {
+                        try {
+                            return await stream.read({
+                                start: { from: { seqNum: cursor }, clamp: true },
+                                stop: { limits: { count } },
+                                ignoreCommandRecords: true,
+                            });
+                        }
+                        catch (cause) {
+                            if (isUnsatisfiableCause(cause)) {
+                                return null;
+                            }
+                            throw cause;
+                        }
+                    },
+                    catch: (cause) => toStoreError(cause, `Read failed for ${runId}`),
+                });
+                const recordStream = paginateS2Stream(fetchPage, {
+                    fromSeq: s2From,
+                    limit: options?.limit,
+                });
+                return recordStream.pipe(Stream.map((r) => parseEvent(r.body, r.seqNum)));
+            }));
+        },
+        read: (runId, options) => Effect.gen(function* () {
+            const stream = service.readStream(runId, options);
+            return yield* Stream.runCollect(stream);
+        }),
+        tail: (runId) => Effect.gen(function* () {
+            const stream = yield* ensureStream(runId);
+            const res = yield* Effect.tryPromise({
+                try: () => stream.checkTail(),
+                catch: (cause) => toStoreError(cause, `Tail failed for ${runId}`),
+            }).pipe(Effect.catch((err) => err.cause instanceof S2Error && err.cause.status === 404
+                ? Effect.succeed({ tail: { seqNum: 0, timestamp: new Date(0) } })
+                : Effect.fail(err)));
+            return res.tail.seqNum;
+        }),
+        bounds: (runId) => Effect.gen(function* () {
+            const stream = yield* ensureStream(runId);
+            const page = yield* Effect.tryPromise({
+                try: async () => {
+                    try {
+                        return await stream.read({
+                            start: { from: { seqNum: 0 }, clamp: true },
+                            stop: { limits: { count: 1 } },
+                            ignoreCommandRecords: false,
+                        });
+                    }
+                    catch (cause) {
+                        if (isUnsatisfiableCause(cause)) {
+                            return null;
+                        }
+                        throw cause;
+                    }
+                },
+                catch: (cause) => toStoreError(cause, `Bounds failed for ${runId}`),
+            });
+            const tail = page?.tail?.seqNum ?? 0;
+            const first = page?.records[0];
+            const head = first ? first.seqNum + 1 : tail + 1;
+            return { head, tail };
+        }),
+        trim: (runId, beforeSeq) => Effect.gen(function* () {
+            const stream = yield* ensureStream(runId);
+            const trimTo = Math.max(0, beforeSeq - 1);
+            yield* Effect.tryPromise({
+                try: () => appends.run(runId, () => stream.append(AppendInput.create([AppendRecord.trim(trimTo)]))),
+                catch: (cause) => toStoreError(cause, `Trim failed for ${runId}`),
+            });
+        }),
+        subscribe: (runId, options) => Stream.callback((queue) => Effect.callback((resume) => {
+            const fromSeq = options?.fromSeq ?? 1;
+            const s2From = Math.max(0, fromSeq - 1);
+            let stopped = false;
+            const run = async () => {
+                try {
+                    const stream = await Effect.runPromise(ensureStream(runId));
+                    const session = await stream.readSession({
+                        start: { from: { seqNum: s2From }, clamp: true },
+                        ignoreCommandRecords: true,
+                    });
+                    for await (const record of session) {
+                        if (stopped) {
+                            break;
+                        }
+                        if (record.seqNum < s2From) {
+                            continue;
+                        }
+                        Queue.offerUnsafe(queue, parseEvent(record.body, record.seqNum));
+                    }
+                    Queue.endUnsafe(queue);
+                    resume(Effect.void);
+                }
+                catch (cause) {
+                    await Effect.runPromise(Queue.fail(queue, toStoreError(cause, `Subscribe failed for ${runId}`)));
+                    resume(Effect.void);
+                }
+            };
+            void run();
+            return Effect.sync(() => {
+                stopped = true;
+            });
+        })),
+        listRuns: () => Effect.tryPromise({
+            try: async () => {
+                const listed = await basin.streams.list({ prefix: 'runs/' });
+                return listed.streams
+                    .map((s) => s.name)
+                    .filter((name) => name.startsWith('runs/'))
+                    .map((name) => name.slice('runs/'.length));
+            },
+            catch: (cause) => toStoreError(cause, 'listRuns failed'),
+        }),
+    };
+    return withSnapshotStore(service, s2SnapshotStore(parsed));
+}
+export const makeS2EventStore = (config) => Effect.try({
+    try: () => s2(config),
+    catch: (cause) => new EventStoreError('Failed to initialize S2 event store', cause),
+});
+export const S2EventStoreLive = (config) => Layer.effect(EventStoreTag, makeS2EventStore(config));

package/dist/testing/index.d.ts

@@ -0,0 +1,11 @@
+import { Effect } from 'effect';
+import { EventStoreTag, type AnyRuntimeModule, type EventStore } from '@swirls/looms/core';
+import { type LoomsRuntime } from '@swirls/looms/runtime';
+export interface TestRuntime {
+    readonly runtime: LoomsRuntime;
+    readonly store: EventStore;
+    run<A, E>(effect: Effect.Effect<A, E, EventStoreTag>): Promise<A>;
+}
+export declare function createTestRuntime(modules: readonly AnyRuntimeModule[]): Promise<TestRuntime>;
+export declare function assertReplayDeterministic(test: TestRuntime, runId: string): Promise<void>;
+export declare function moduleConformance(module: AnyRuntimeModule): string[];

package/dist/testing/index.js

@@ -0,0 +1,63 @@
+import { Effect, Predicate } from 'effect';
+import { composeModules, EventStoreTag, foldRun, makeMemoryEventStore, ModuleCompositionError, } from '@swirls/looms/core';
+import { createRuntime } from '@swirls/looms/runtime';
+function namedEffects(effects) {
+    const listed = [];
+    for (const key of Object.keys(effects)) {
+        const value = effects[key];
+        if (!value || !Predicate.isString(value.type)) {
+            continue;
+        }
+        listed.push({
+            type: value.type,
+            hasExecute: 'execute' in value,
+        });
+    }
+    return listed;
+}
+export async function createTestRuntime(modules) {
+    const store = await Effect.runPromise(makeMemoryEventStore);
+    const runtime = createRuntime({ modules, store });
+    return {
+        runtime,
+        store,
+        run: (effect) => Effect.runPromise(Effect.provideService(effect, EventStoreTag, store)),
+    };
+}
+export async function assertReplayDeterministic(test, runId) {
+    const events = await test.run(test.runtime.getEvents(runId));
+    const first = foldRun(events, test.runtime.registry, { runId });
+    const second = foldRun(events, test.runtime.registry, { runId });
+    if (JSON.stringify(first) !== JSON.stringify(second)) {
+        throw new Error(`Replay is not deterministic for run ${runId}`);
+    }
+}
+export function moduleConformance(module) {
+    const errors = [];
+    if (!module.namespace) {
+        errors.push('namespace required');
+    }
+    if (!module.protocolVersion) {
+        errors.push('protocolVersion required');
+    }
+    if (module.events && module.events.namespace !== module.namespace) {
+        errors.push(`catalog namespace ${module.events.namespace} !== module ${module.namespace}`);
+    }
+    if (module.effects) {
+        for (const effect of namedEffects(module.effects)) {
+            if (!effect.type.startsWith(`${module.namespace}.`)) {
+                errors.push(`effect ${effect.type} is not namespaced under ${module.namespace}`);
+            }
+            if (!effect.hasExecute) {
+                errors.push(`effect ${effect.type} is missing execute`);
+            }
+        }
+    }
+    try {
+        composeModules([module]);
+    }
+    catch (err) {
+        errors.push(err instanceof ModuleCompositionError ? err.message : String(err));
+    }
+    return errors;
+}

package/dist/workflow/definitions-store.d.ts

@@ -0,0 +1,11 @@
+import { Context, Layer } from 'effect';
+import type { WorkflowDefinition } from './definitions';
+export interface WorkflowDefinitionStore {
+    get(name: string): WorkflowDefinition | undefined;
+}
+declare const WorkflowDefinitionsTag_base: Context.ServiceClass<WorkflowDefinitionsTag, "looms/WorkflowDefinitions", WorkflowDefinitionStore>;
+export declare class WorkflowDefinitionsTag extends WorkflowDefinitionsTag_base {
+}
+export declare function makeWorkflowDefinitionStore(definitions: ReadonlyArray<WorkflowDefinition>): WorkflowDefinitionStore;
+export declare const WorkflowDefinitionsLive: (definitions: ReadonlyArray<WorkflowDefinition>) => Layer.Layer<WorkflowDefinitionsTag, never, never>;
+export {};

package/dist/workflow/definitions-store.js

@@ -0,0 +1,8 @@
+import { Context, Layer } from 'effect';
+export class WorkflowDefinitionsTag extends Context.Service()('looms/WorkflowDefinitions') {
+}
+export function makeWorkflowDefinitionStore(definitions) {
+    const map = new Map(definitions.map((def) => [def.name, def]));
+    return { get: (name) => map.get(name) };
+}
+export const WorkflowDefinitionsLive = (definitions) => Layer.succeed(WorkflowDefinitionsTag, makeWorkflowDefinitionStore(definitions));

package/dist/workflow/definitions.d.ts

@@ -0,0 +1,82 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Schema } from 'effect';
+import type { InferDefinedSchema, JsonValue, RuntimeEffect } from '@swirls/looms/core';
+export declare const NodeStatusSchema: Schema.Union<readonly [Schema.Literal<"pending">, Schema.Literal<"running">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"skipped">]>;
+export type NodeStatus = Schema.Schema.Type<typeof NodeStatusSchema>;
+export declare const NodeStateSchema: Schema.Struct<{
+    readonly status: Schema.Union<readonly [Schema.Literal<"pending">, Schema.Literal<"running">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"skipped">]>;
+    readonly result: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly error: Schema.NullOr<Schema.String>;
+}>;
+export type NodeState = Schema.Schema.Type<typeof NodeStateSchema>;
+export interface WorkflowNodeContext<TInput = JsonValue> {
+    readonly threadId: string;
+    readonly nodeId: string;
+    readonly input: TInput;
+    readonly results: {
+        [nodeId: string]: JsonValue | null;
+    };
+    spawn(child: {
+        kind: string;
+        name: string;
+    }, input: JsonValue): NodeResult;
+    sleep(ms: number): NodeResult;
+    effects(effects: RuntimeEffect[]): NodeResult;
+}
+export type NodeResult = {
+    type: 'value';
+    value: JsonValue;
+} | {
+    type: 'spawn';
+    kind: string;
+    name: string;
+    input: JsonValue;
+} | {
+    type: 'sleep';
+    ms: number;
+} | {
+    type: 'effects';
+    effects: RuntimeEffect[];
+};
+export interface WorkflowNodeDefinition<TInput = JsonValue> {
+    id: string;
+    deps?: string[];
+    run(ctx: WorkflowNodeContext<TInput>): Promise<JsonValue | NodeResult> | JsonValue | NodeResult;
+}
+export interface WorkflowDefinition<TName extends string = string, TInput = JsonValue, TOutput extends JsonValue = JsonValue> {
+    readonly kind: 'workflow';
+    readonly name: TName;
+    readonly description?: string;
+    readonly input?: StandardSchemaV1<any, TInput> | Schema.Schema<TInput>;
+    readonly nodes: WorkflowNodeDefinition<TInput>[];
+    readonly concurrency?: number;
+    output?(ctx: {
+        input: TInput;
+        results: {
+            [nodeId: string]: JsonValue | null;
+        };
+    }): TOutput;
+}
+export type AnyWorkflowDefinition = WorkflowDefinition;
+export declare function defineWorkflow<TName extends string, TSchema = undefined, TInput = InferDefinedSchema<TSchema>, TOutput extends JsonValue = JsonValue>(def: {
+    name: TName;
+    description?: string;
+    input?: TSchema;
+    nodes: Array<{
+        id: string;
+        deps?: string[];
+        run: (ctx: WorkflowNodeContext<TInput>) => Promise<JsonValue | NodeResult> | JsonValue | NodeResult;
+    }>;
+    concurrency?: number;
+    output?: (ctx: {
+        input: TInput;
+        results: {
+            [nodeId: string]: JsonValue | null;
+        };
+    }) => TOutput;
+}): WorkflowDefinition<TName, TInput, TOutput>;
+export declare function readyNodes(workflow: WorkflowDefinition, nodeStates: {
+    [nodeId: string]: {
+        status: string;
+    };
+}): string[];

package/dist/workflow/definitions.js

@@ -0,0 +1,32 @@
+import { Schema } from 'effect';
+export const NodeStatusSchema = Schema.Union([
+    Schema.Literal('pending'),
+    Schema.Literal('running'),
+    Schema.Literal('completed'),
+    Schema.Literal('failed'),
+    Schema.Literal('skipped'),
+]);
+export const NodeStateSchema = Schema.Struct({
+    status: NodeStatusSchema,
+    result: Schema.NullOr(Schema.Json),
+    error: Schema.NullOr(Schema.String),
+});
+export function defineWorkflow(def) {
+    // SAFETY: factory fields match WorkflowDefinition.
+    return { kind: 'workflow', ...def, input: def.input };
+}
+export function readyNodes(workflow, nodeStates) {
+    return workflow.nodes
+        .filter((node) => {
+        const state = nodeStates[node.id];
+        if (state && state.status !== 'pending') {
+            return false;
+        }
+        const deps = node.deps ?? [];
+        return deps.every((depId) => {
+            const dep = nodeStates[depId];
+            return dep?.status === 'completed' || dep?.status === 'skipped';
+        });
+    })
+        .map((node) => node.id);
+}