@swirls/looms 0.0.2 → 0.2.0

package/dist/s2/store.js

@@ -1,7 +1,8 @@
 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 { DateTime, Effect, Layer, Predicate, Schema, Stream } from 'effect';
+import { createKeyedSerializer, assertEventByteLimits, EventStoreConflictError, EventStoreError, EventStoreFencedError, EventPayloadTooLargeError, EventStoreTag, EventEnvelopeSchema, fromWireEvent, withSnapshotStore, } from '@swirls/looms/core';
 import { S2ConfigSchema, streamNameForRun } from './config.js';
+import { paginateS2Stream } from './pagination.js';
 import { s2SnapshotStore } from './snapshot-store.js';
 function toStoreError(cause, message) {
     if (cause instanceof EventStoreError) {
@@ -20,50 +21,8 @@ function isUnsatisfiableCause(cause) {
     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) {
+export { paginateS2Stream };
+export function readAllPages(fetchPage, options) {
     const fetchPageEffect = (cursor, count) => Effect.tryPromise({
         try: () => fetchPage(cursor, count),
         catch: (cause) => toStoreError(cause, 'S2 page fetch failed'),
@@ -101,61 +60,49 @@ function createClient(config) {
  * Expected tail mismatches during `append` map to `EventStoreConflictError`.
  */
 export function s2(config) {
-    const parsed = Schema.decodeUnknownSync(S2ConfigSchema)(config);
+    const parsed = Schema.decodeSync(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;
-                }
-            }
+    const ensureBasin = Effect.suspend(() => {
+        if (basinEnsured) {
+            return Effect.void;
+        }
+        return Effect.tryPromise({
+            try: () => client.basins.create({ basin: parsed.basin }),
+            catch: (cause) => toStoreError(cause, `Failed to ensure basin ${parsed.basin}`),
+        }).pipe(Effect.catchIf((error) => error.cause instanceof S2Error && error.cause.status === 409, () => Effect.void), Effect.tap(() => Effect.sync(() => {
             basinEnsured = true;
-        },
-        catch: (cause) => toStoreError(cause, `Failed to ensure basin ${parsed.basin}`),
+        })), Effect.asVoid);
     });
     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 name = streamNameForRun(runId);
+        if (!ensured.has(name)) {
+            yield* Effect.tryPromise({
+                try: () => basin.streams.create({
+                    stream: name,
+                    config: parsed.streamConfig,
+                }),
+                catch: (cause) => toStoreError(cause, `Failed to open stream for ${runId}`),
+            }).pipe(Effect.catchIf((error) => error.cause instanceof S2Error &&
+                (error.cause.status === 409 ||
+                    error.cause.status === 404 ||
+                    error.cause.status === 405), () => Effect.void));
+            ensured.add(name);
+        }
+        return basin.stream(name);
     });
     const service = {
         append: (runId, events, options) => Effect.gen(function* () {
+            yield* Effect.try({
+                try: () => assertEventByteLimits(runId, events),
+                catch: (cause) => cause instanceof EventPayloadTooLargeError
+                    ? cause
+                    : new EventStoreError('event size validation failed', cause),
+            });
             if (events.length === 0 && options?.fence === undefined) {
                 const tail = yield* service.tail(runId);
                 return { sequences: [], tail };
@@ -186,7 +133,7 @@ export function s2(config) {
                     cause.status === 412 &&
                     (message.includes('fenc') || message.includes('token'));
                 if (isFence) {
-                    return yield* Effect.fail(new EventStoreFencedError(runId, options?.fencingToken ?? options?.fence ?? ''));
+                    return yield* new EventStoreFencedError(runId, options?.fencingToken ?? options?.fence ?? '');
                 }
                 if (cause instanceof S2Error &&
                     (cause.status === 409 ||
@@ -195,9 +142,9 @@ export function s2(config) {
                         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* new EventStoreConflictError(runId, options?.expectedTail ?? 0, actualTail);
                 }
-                return yield* Effect.fail(toStoreError(cause, `Append failed for ${runId}`));
+                return yield* toStoreError(cause, `Append failed for ${runId}`);
             }
             const ack = appendResult.ack;
             const sequences = [];
@@ -213,23 +160,13 @@ export function s2(config) {
             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;
-                        }
-                    },
+                    try: () => stream.read({
+                        start: { from: { seqNum: cursor }, clamp: true },
+                        stop: { limits: { count } },
+                        ignoreCommandRecords: true,
+                    }),
                     catch: (cause) => toStoreError(cause, `Read failed for ${runId}`),
-                });
+                }).pipe(Effect.catchIf((error) => isUnsatisfiableCause(error.cause), () => Effect.succeed(null)));
                 const recordStream = paginateS2Stream(fetchPage, {
                     fromSeq: s2From,
                     limit: options?.limit,
@@ -246,31 +183,21 @@ export function s2(config) {
             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)));
+            }).pipe(Effect.catchIf((err) => err.cause instanceof S2Error && err.cause.status === 404, () => Effect.succeed({
+                tail: { seqNum: 0, timestamp: DateTime.toDateUtc(DateTime.makeUnsafe(0)) },
+            })));
             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;
-                    }
-                },
+                try: () => stream.read({
+                    start: { from: { seqNum: 0 }, clamp: true },
+                    stop: { limits: { count: 1 } },
+                    ignoreCommandRecords: false,
+                }),
                 catch: (cause) => toStoreError(cause, `Bounds failed for ${runId}`),
-            });
+            }).pipe(Effect.catchIf((error) => isUnsatisfiableCause(error.cause), () => Effect.succeed(null)));
             const tail = page?.tail?.seqNum ?? 0;
             const first = page?.records[0];
             const head = first ? first.seqNum + 1 : tail + 1;
@@ -284,49 +211,28 @@ export function s2(config) {
                 catch: (cause) => toStoreError(cause, `Trim failed for ${runId}`),
             });
         }),
-        subscribe: (runId, options) => Stream.callback((queue) => Effect.callback((resume) => {
+        subscribe: (runId, options) => {
             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({
+            return Stream.unwrap(Effect.gen(function* () {
+                const stream = yield* ensureStream(runId);
+                const session = yield* Effect.tryPromise({
+                    try: () => 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, `Subscribe failed for ${runId}`),
+                });
+                return Stream.fromAsyncIterable(session, (cause) => toStoreError(cause, `Subscribe failed for ${runId}`)).pipe(Stream.filter((record) => record.seqNum >= s2From), Stream.map((record) => parseEvent(record.body, record.seqNum)));
+            }));
+        },
+        listRuns: Effect.tryPromise({
+            try: () => basin.streams.list({ prefix: 'runs/' }),
             catch: (cause) => toStoreError(cause, 'listRuns failed'),
-        }),
+        }).pipe(Effect.map((listed) => listed.streams
+            .map((stream) => stream.name)
+            .filter((name) => name.startsWith('runs/'))
+            .map((name) => name.slice('runs/'.length)))),
     };
     return withSnapshotStore(service, s2SnapshotStore(parsed));
 }

package/dist/testing/index.d.ts

@@ -9,3 +9,18 @@ export interface TestRuntime {
 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[];
+export type EventStoreFaultOperation = 'append' | 'read' | 'tail' | 'bounds' | 'trim' | 'listRuns';
+export interface EventStoreFaultContext {
+    readonly operation: EventStoreFaultOperation;
+    readonly runId: string | null;
+    readonly call: number;
+}
+export interface FaultInjectingEventStore {
+    readonly store: EventStore;
+    readonly calls: ReadonlyMap<EventStoreFaultOperation, number>;
+}
+/**
+ * Wraps an EventStore with deterministic delay/failure injection. Throw from
+ * `before` to fail a call, or await inside it to pause a race at an exact store boundary.
+ */
+export declare function createFaultInjectingEventStore(source: EventStore, before: (context: EventStoreFaultContext) => void | Promise<void>): FaultInjectingEventStore;

package/dist/testing/index.js

@@ -1,5 +1,5 @@
 import { Effect, Predicate } from 'effect';
-import { composeModules, EventStoreTag, foldRun, makeMemoryEventStore, ModuleCompositionError, } from '@swirls/looms/core';
+import { composeModules, EventStoreTag, foldRun, makeMemoryEventStore, ModuleCompositionError, EventStoreError, snapshotStoreOf, stringifyJson, withSnapshotStore, } from '@swirls/looms/core';
 import { createRuntime } from '@swirls/looms/runtime';
 function namedEffects(effects) {
     const listed = [];
@@ -15,22 +15,24 @@ function namedEffects(effects) {
     }
     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 function createTestRuntime(modules) {
+    return Effect.runPromise(makeMemoryEventStore.pipe(Effect.map((store) => {
+        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 assertReplayDeterministic(test, runId) {
+    return test.run(test.runtime.getEvents(runId)).then((events) => {
+        const first = foldRun(events, test.runtime.registry, { runId });
+        const second = foldRun(events, test.runtime.registry, { runId });
+        if (stringifyJson(first) !== stringifyJson(second)) {
+            throw new Error(`Replay is not deterministic for run ${runId}`);
+        }
+    });
 }
 export function moduleConformance(module) {
     const errors = [];
@@ -61,3 +63,38 @@ export function moduleConformance(module) {
     }
     return errors;
 }
+/**
+ * Wraps an EventStore with deterministic delay/failure injection. Throw from
+ * `before` to fail a call, or await inside it to pause a race at an exact store boundary.
+ */
+export function createFaultInjectingEventStore(source, before) {
+    const calls = new Map();
+    const inject = (operation, runId) => Effect.tryPromise({
+        try: () => {
+            const call = (calls.get(operation) ?? 0) + 1;
+            calls.set(operation, call);
+            return Promise.resolve(before({ operation, runId, call }));
+        },
+        catch: (cause) => cause instanceof EventStoreError
+            ? cause
+            : new EventStoreError(`Injected ${operation} fault`, cause),
+    });
+    const store = {
+        append: (runId, events, options) => inject('append', runId).pipe(Effect.andThen(source.append(runId, events, options))),
+        read: (runId, options) => inject('read', runId).pipe(Effect.andThen(source.read(runId, options))),
+        tail: (runId) => inject('tail', runId).pipe(Effect.andThen(source.tail(runId))),
+        subscribe: source.subscribe,
+        listRuns: inject('listRuns', null).pipe(Effect.andThen(source.listRuns)),
+    };
+    if (source.bounds) {
+        store.bounds = (runId) => inject('bounds', runId).pipe(Effect.andThen(source.bounds(runId)));
+    }
+    if (source.trim) {
+        store.trim = (runId, beforeSeq) => inject('trim', runId).pipe(Effect.andThen(source.trim(runId, beforeSeq)));
+    }
+    const snapshots = snapshotStoreOf(source);
+    if (snapshots) {
+        withSnapshotStore(store, snapshots);
+    }
+    return { store, calls };
+}

package/dist/workflow/debugger/index.d.ts

@@ -0,0 +1,4 @@
+import type { DebuggerPlugin } from '@swirls/looms/debugger';
+import { WorkflowNodesView } from './nodes-view';
+export declare const workflowDebugger: DebuggerPlugin;
+export { WorkflowNodesView };

package/dist/workflow/debugger/index.js

@@ -0,0 +1,11 @@
+import { nodes } from '../projections.js';
+import { WorkflowNodesView } from './nodes-view.js';
+import { summarizeWorkflowEvent } from './summarize.js';
+export const workflowDebugger = {
+    name: 'workflow',
+    families: [
+        { family: 'workflow', color: 'oklch(0.76 0.12 300)', summarize: summarizeWorkflowEvent },
+    ],
+    projections: [{ name: nodes.name, component: WorkflowNodesView }],
+};
+export { WorkflowNodesView };

package/dist/workflow/debugger/nodes-view.d.ts

@@ -0,0 +1,3 @@
+export declare function WorkflowNodesView({ runId }: {
+    runId: string;
+}): import("react").JSX.Element;

package/dist/workflow/debugger/nodes-view.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { asJson } from '@swirls/looms/core';
+import { JsonTree, StatusBadge } from '@swirls/looms/debugger';
+import { useProjection, useRunStore } from '@swirls/looms/react';
+import { nodes } from '../projections.js';
+export function WorkflowNodesView({ runId }) {
+    const state = useProjection(useRunStore(runId), nodes);
+    const entries = Object.entries(state.nodes);
+    if (entries.length === 0) {
+        return _jsx("p", { className: "text-muted-foreground text-xs", children: "No nodes yet." });
+    }
+    return (_jsx("ul", { className: "grid gap-2", children: entries.map(([id, node]) => (_jsxs("li", { className: "border-border bg-card/60 rounded-lg border p-2.5 text-xs", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "min-w-0 flex-1 truncate font-mono font-medium", children: id }), _jsx(StatusBadge, { status: node.status })] }), node.result !== null ? (_jsx(JsonTree, { value: asJson(node.result), className: "mt-1.5" })) : null, node.error ? _jsx("p", { className: "text-status-failed mt-1.5", children: node.error }) : null] }, id))) }));
+}

package/dist/workflow/debugger/summarize.d.ts

@@ -0,0 +1,2 @@
+import { type DebuggerEvent, type EventSummary } from '@swirls/looms/debugger';
+export declare function summarizeWorkflowEvent(event: DebuggerEvent): EventSummary | undefined;

package/dist/workflow/debugger/summarize.js

@@ -0,0 +1,30 @@
+import { compactJson, jsonFields, jsonText, } from '@swirls/looms/debugger';
+export function summarizeWorkflowEvent(event) {
+    const payload = jsonFields(event.payload);
+    switch (event.type) {
+        case 'workflow.node.started':
+            return { title: 'node started', detail: jsonText(payload.nodeId) };
+        case 'workflow.node.finished':
+            return {
+                title: jsonText(payload.error) ? 'node failed' : 'node finished',
+                detail: jsonText(payload.error) ??
+                    `${jsonText(payload.nodeId) ?? ''} ${compactJson(payload.result ?? null)}`,
+            };
+        case 'workflow.node.skipped':
+            return {
+                title: 'node skipped',
+                detail: `${jsonText(payload.nodeId) ?? ''} · ${jsonText(payload.reason) ?? ''}`,
+            };
+        case 'workflow.spawn.requested':
+            return {
+                title: 'workflow spawn',
+                detail: `${jsonText(payload.definitionName) ?? 'unknown'} from ${jsonText(payload.nodeId) ?? ''}`,
+            };
+        case 'workflow.sleep.requested':
+            return { title: 'sleep', detail: jsonText(payload.nodeId) };
+        case 'workflow.effects.requested':
+            return { title: 'workflow effects', detail: jsonText(payload.nodeId) };
+        default:
+            return undefined;
+    }
+}

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

@@ -1,8 +1,7 @@
 import { Context, Layer } from 'effect';
+import { type DefinitionStore } from '@swirls/looms/core';
 import type { WorkflowDefinition } from './definitions';
-export interface WorkflowDefinitionStore {
-    get(name: string): WorkflowDefinition | undefined;
-}
+export type WorkflowDefinitionStore = DefinitionStore<WorkflowDefinition>;
 declare const WorkflowDefinitionsTag_base: Context.ServiceClass<WorkflowDefinitionsTag, "looms/WorkflowDefinitions", WorkflowDefinitionStore>;
 export declare class WorkflowDefinitionsTag extends WorkflowDefinitionsTag_base {
 }

package/dist/workflow/definitions-store.js

@@ -1,8 +1,8 @@
 import { Context, Layer } from 'effect';
+import { makeDefinitionStore } from '@swirls/looms/core';
 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) };
+    return makeDefinitionStore('workflow', definitions);
 }
 export const WorkflowDefinitionsLive = (definitions) => Layer.succeed(WorkflowDefinitionsTag, makeWorkflowDefinitionStore(definitions));