@swirls/looms 0.4.0 → 0.5.0

package/dist/schedule/threads.d.ts

@@ -0,0 +1,25 @@
+import { type DefinitionStore, type JsonValue, type ThreadDefinition } from '@swirls/looms/core';
+import type { ScheduleDefinition, ScheduleMisfire, ScheduleOverlap } from './definitions';
+import { type ScheduleSpec } from './specs';
+export interface ScheduleState {
+    readonly spec: ScheduleSpec | null;
+    readonly input: JsonValue | null;
+    readonly endAt: number | null;
+    readonly maxFires: number | null;
+    readonly startAt: number | null;
+    readonly paused: boolean;
+    readonly retired: boolean;
+    readonly generation: number;
+    readonly nextAt: number | null;
+    readonly fireCount: number;
+    readonly lastFiredRunId: string | null;
+    readonly pendingTriggers: readonly string[];
+    readonly done: boolean;
+    readonly invalid: string | null;
+    readonly rejection: string | null;
+    readonly misfire: ScheduleMisfire;
+    readonly overlap: ScheduleOverlap;
+    readonly definitionName: string;
+    readonly definitionVersion: string;
+}
+export declare function createScheduleThread(definitions: DefinitionStore<ScheduleDefinition>, minIntervalMs: number): ThreadDefinition<ScheduleState>;

package/dist/schedule/threads.js

@@ -0,0 +1,259 @@
+import { Option, Schema } from 'effect';
+import { complete, emit, fail, invoke, stringifyJson, } from '@swirls/looms/core';
+import { ScheduleStartSchema } from './definitions.js';
+import { fireEffect, fireInputOf, planEffect, planInputOf } from './effects.js';
+import { ScheduleUpdatedPayloadSchema } from './events.js';
+import { scheduleModule } from './scope.js';
+import { specRejection } from './specs.js';
+const PENDING_TRIGGER_CAP = 32;
+const decodeStart = Schema.decodeUnknownOption(ScheduleStartSchema);
+const decodeUpdate = Schema.decodeUnknownOption(ScheduleUpdatedPayloadSchema);
+export function createScheduleThread(definitions, minIntervalMs) {
+    return scheduleModule.thread({
+        kind: 'schedule',
+        input: ScheduleStartSchema,
+        forgetsCompletedEffects: true,
+        initialState: (ctx) => {
+            const definition = definitions.get(ctx.definitionName, ctx.definitionVersion);
+            const base = {
+                input: null,
+                endAt: null,
+                maxFires: null,
+                startAt: null,
+                paused: false,
+                retired: false,
+                generation: 0,
+                nextAt: null,
+                fireCount: 0,
+                lastFiredRunId: null,
+                pendingTriggers: [],
+                done: false,
+                rejection: null,
+                misfire: definition?.misfire ?? 'fire-once',
+                overlap: definition?.overlap ?? 'allow',
+                definitionName: ctx.definitionName,
+                definitionVersion: ctx.definitionVersion,
+            };
+            if (!definition) {
+                return {
+                    ...base,
+                    spec: null,
+                    invalid: `Unknown schedule definition "${ctx.definitionName}@${ctx.definitionVersion}"`,
+                };
+            }
+            const start = Option.getOrUndefined(decodeStart(ctx.input));
+            const config = start && start !== null ? start : {};
+            const spec = config.spec ?? definition.spec;
+            const invalid = specRejection(spec, minIntervalMs) ?? boundsError(config);
+            return {
+                ...base,
+                spec: invalid ? null : spec,
+                input: config.input ?? null,
+                endAt: config.endAt ?? null,
+                maxFires: config.maxFires ?? null,
+                startAt: config.startAt ?? null,
+                invalid: invalid ?? null,
+            };
+        },
+        step(state, event) {
+            switch (event.type) {
+                case 'schedule.planned': {
+                    if (event.payload.generation !== state.generation) {
+                        return state;
+                    }
+                    if (event.payload.nextAt === null) {
+                        return { ...state, spec: event.payload.spec, nextAt: null, done: true };
+                    }
+                    return { ...state, spec: event.payload.spec, nextAt: event.payload.nextAt };
+                }
+                case 'schedule.fired': {
+                    const pending = dropTrigger(state.pendingTriggers, event.payload.triggerId);
+                    const fireCount = state.fireCount + 1;
+                    if (event.payload.manual) {
+                        const done = state.maxFires !== null && fireCount >= state.maxFires;
+                        return {
+                            ...state,
+                            fireCount,
+                            lastFiredRunId: event.payload.runId,
+                            nextAt: done ? null : state.nextAt,
+                            done: state.done || done,
+                            pendingTriggers: pending,
+                        };
+                    }
+                    if (event.payload.generation !== state.generation) {
+                        return state;
+                    }
+                    const done = event.payload.nextAt === null;
+                    return {
+                        ...state,
+                        fireCount,
+                        lastFiredRunId: event.payload.runId,
+                        nextAt: event.payload.nextAt,
+                        done,
+                        pendingTriggers: pending,
+                    };
+                }
+                case 'schedule.skipped': {
+                    const pending = dropTrigger(state.pendingTriggers, event.payload.triggerId);
+                    if (event.payload.manual) {
+                        return { ...state, pendingTriggers: pending };
+                    }
+                    if (event.payload.generation !== state.generation) {
+                        return state;
+                    }
+                    const done = event.payload.nextAt === null;
+                    return {
+                        ...state,
+                        nextAt: event.payload.nextAt,
+                        done,
+                        pendingTriggers: pending,
+                    };
+                }
+                case 'schedule.updated':
+                    return applyUpdate(state, event.payload, definitions, minIntervalMs);
+                case 'schedule.paused':
+                    return { ...state, paused: true, nextAt: null };
+                case 'schedule.resumed':
+                    if (!state.paused && !state.retired) {
+                        return state;
+                    }
+                    return {
+                        ...state,
+                        paused: false,
+                        retired: false,
+                        nextAt: null,
+                        generation: state.generation + 1,
+                        rejection: null,
+                    };
+                case 'schedule.retired':
+                    return {
+                        ...state,
+                        retired: true,
+                        paused: true,
+                        nextAt: null,
+                        pendingTriggers: [],
+                    };
+                case 'schedule.triggered': {
+                    const pending = state.pendingTriggers.length < PENDING_TRIGGER_CAP
+                        ? [...state.pendingTriggers, event.id]
+                        : state.pendingTriggers;
+                    return { ...state, pendingTriggers: pending };
+                }
+                case 'schedule.rejected':
+                    return { ...state, rejection: null };
+                default:
+                    return state;
+            }
+        },
+        effects(state, ctx) {
+            if (state.invalid && state.fireCount === 0 && state.nextAt === null) {
+                return [fail(state.invalid)];
+            }
+            const spec = state.spec;
+            if (state.done || !spec) {
+                return [complete({ fireCount: state.fireCount })];
+            }
+            const armed = { ...state, spec };
+            const effects = [];
+            if (state.rejection) {
+                effects.push(emit({
+                    type: 'schedule.rejected',
+                    payload: { reason: state.rejection },
+                    threadId: ctx.threadId,
+                }));
+            }
+            const triggerId = state.pendingTriggers[0];
+            if (!state.retired && triggerId !== undefined) {
+                effects.push(invoke(fireEffect, fireInputOf(armed, state.nextAt ?? 0, true, triggerId), `manual:${String(triggerId)}`));
+            }
+            if (!state.paused && !state.retired) {
+                if (state.nextAt === null) {
+                    effects.push(invoke(planEffect, planInputOf(armed), `plan:${state.generation}`));
+                }
+                else {
+                    const nextAt = state.nextAt;
+                    effects.push(invoke(fireEffect, fireInputOf(armed, nextAt, false), `fire:${String(state.generation)}:${String(state.fireCount)}:${String(nextAt)}`, { at: nextAt }));
+                }
+            }
+            return effects;
+        },
+    });
+}
+function applyUpdate(state, payload, definitions, minIntervalMs) {
+    const decoded = decodeUpdate(payload);
+    if (Option.isNone(decoded)) {
+        return { ...state, rejection: 'schedule update payload is invalid' };
+    }
+    const patch = decoded.value;
+    const definitionName = patch.definitionName ?? state.definitionName;
+    const definitionVersion = patch.definitionVersion ?? state.definitionVersion;
+    const definition = definitions.get(definitionName, definitionVersion);
+    if ((patch.definitionName !== undefined || patch.definitionVersion !== undefined) &&
+        !definition) {
+        return {
+            ...state,
+            rejection: `Unknown schedule definition "${definitionName}@${definitionVersion}"`,
+        };
+    }
+    if (patch.spec) {
+        const rejection = specRejection(patch.spec, minIntervalMs);
+        if (rejection) {
+            return { ...state, rejection };
+        }
+    }
+    const spec = patch.spec ?? state.spec;
+    if (!spec) {
+        return { ...state, rejection: 'schedule has no spec' };
+    }
+    const input = patch.input === undefined ? state.input : patch.input;
+    const endAt = patch.endAt === undefined ? state.endAt : patch.endAt;
+    const maxFires = patch.maxFires === undefined ? state.maxFires : patch.maxFires;
+    const bounds = boundsError({ endAt, maxFires, startAt: state.startAt });
+    if (bounds) {
+        return { ...state, rejection: bounds };
+    }
+    const misfire = definition ? definition.misfire : state.misfire;
+    const overlap = definition ? definition.overlap : state.overlap;
+    if (stringifyJson(spec) === stringifyJson(state.spec) &&
+        stringifyJson(input) === stringifyJson(state.input) &&
+        endAt === state.endAt &&
+        maxFires === state.maxFires &&
+        definitionName === state.definitionName &&
+        definitionVersion === state.definitionVersion &&
+        misfire === state.misfire &&
+        overlap === state.overlap) {
+        return state;
+    }
+    return {
+        ...state,
+        spec,
+        input,
+        endAt,
+        maxFires,
+        definitionName,
+        definitionVersion,
+        misfire,
+        overlap,
+        generation: state.generation + 1,
+        nextAt: null,
+        rejection: null,
+    };
+}
+function boundsError(config) {
+    if (config.maxFires != null && (!Number.isInteger(config.maxFires) || config.maxFires < 1)) {
+        return 'maxFires must be an integer of at least 1';
+    }
+    if (config.startAt != null && !Number.isFinite(config.startAt)) {
+        return 'startAt must be a finite epoch timestamp';
+    }
+    if (config.endAt != null && !Number.isFinite(config.endAt)) {
+        return 'endAt must be a finite epoch timestamp';
+    }
+    return undefined;
+}
+function dropTrigger(pending, triggerId) {
+    if (triggerId === undefined) {
+        return pending;
+    }
+    return pending.filter((id) => id !== triggerId);
+}

package/dist/testing/corpus-module.d.ts

@@ -0,0 +1,34 @@
+import { type EventInput, type JsonValue } from '@swirls/looms/core';
+/**
+ * A small production-shaped module used to record and replay the upgrade-safety corpus.
+ * Keep its event and effect contracts stable; add a new type when meaning changes.
+ */
+export declare const corpusDefinition: {
+    kind: string;
+    name: string;
+    version: string;
+};
+export declare const corpusChargeV1 = "payments.charge";
+export declare const corpusChargeV2 = "payments.charge@v2";
+export declare function corpusModule(options?: {
+    readonly charge?: (input: JsonValue) => ReadonlyArray<EventInput>;
+}): import("@swirls/looms/core").RuntimeModule<"corpus", import("@swirls/looms/core").EventCatalog<"corpus", {
+    charged: import("@swirls/looms/core").CatalogEventSpec<{
+        amount: number;
+        version: string;
+    }>;
+    approved: import("@swirls/looms/core").CatalogEventSpec<{
+        decision: 'approve' | 'reject';
+    }>;
+}>, {
+    charge: import("@swirls/looms/core").EffectDefinition<JsonValue, never, EventInput>;
+    chargeV2: import("@swirls/looms/core").EffectDefinition<JsonValue, never, EventInput>;
+}, {
+    'corpus.checkout': import("@swirls/looms/core").ThreadDefinition<{
+        readonly amount: number;
+        readonly charged: boolean;
+        readonly decision: "approve" | "reject" | null;
+    }>;
+}, {
+    readonly [key: string]: import("@swirls/looms/core").ProjectionDefinition<unknown>;
+}, import("effect/Context").Service.Any>;

package/dist/testing/corpus-module.js

@@ -0,0 +1,87 @@
+import { Option, Schema } from 'effect';
+import { complete, defineEffect, defineEventCatalog, defineRuntimeModule, defineThread, fail, invoke, payload, wait, } from '@swirls/looms/core';
+/**
+ * A small production-shaped module used to record and replay the upgrade-safety corpus.
+ * Keep its event and effect contracts stable; add a new type when meaning changes.
+ */
+export const corpusDefinition = {
+    kind: 'corpus.checkout',
+    name: 'checkout',
+    version: 'v1',
+};
+export const corpusChargeV1 = 'payments.charge';
+export const corpusChargeV2 = 'payments.charge@v2';
+const DecisionSchema = Schema.Union([Schema.Literal('approve'), Schema.Literal('reject')]);
+const ApprovedPayloadSchema = Schema.Struct({ decision: DecisionSchema });
+const CheckoutInputSchema = Schema.Finite;
+const decodeApproved = Schema.decodeUnknownOption(ApprovedPayloadSchema);
+const decodeCheckoutInput = Schema.decodeUnknownOption(CheckoutInputSchema);
+export function corpusModule(options) {
+    const charge = defineEffect({
+        type: corpusChargeV1,
+        retry: { maxAttempts: 3, backoffMs: 1, scheduleToStartTimeoutMs: 60_000 },
+        execute: options?.charge,
+    });
+    const chargeV2 = defineEffect({
+        type: corpusChargeV2,
+        retry: { maxAttempts: 1, scheduleToStartTimeoutMs: 60_000 },
+        execute: options?.charge,
+    });
+    return defineRuntimeModule({
+        namespace: 'corpus',
+        protocolVersion: '1.0.0',
+        events: defineEventCatalog('corpus', {
+            charged: payload(),
+            approved: payload(),
+        }),
+        effects: { charge, chargeV2 },
+        threads: {
+            'corpus.checkout': defineThread({
+                kind: 'corpus.checkout',
+                shape: Schema.Struct({
+                    amount: Schema.Finite,
+                    charged: Schema.Boolean,
+                    decision: Schema.NullOr(DecisionSchema),
+                }),
+                initialState: (ctx) => {
+                    const decision = null;
+                    return {
+                        amount: Option.getOrElse(decodeCheckoutInput(ctx.input), () => 0),
+                        charged: false,
+                        decision,
+                    };
+                },
+                step: (state, event) => {
+                    if (event.type === 'corpus.approved') {
+                        return Option.match(decodeApproved(event.payload), {
+                            onNone: () => state,
+                            onSome: ({ decision }) => ({ ...state, decision }),
+                        });
+                    }
+                    if (event.type === 'corpus.charged') {
+                        return { ...state, charged: true };
+                    }
+                    return state;
+                },
+                effects: (state) => {
+                    if (state.decision === 'reject') {
+                        return [fail('rejected')];
+                    }
+                    if (state.decision === null) {
+                        return [
+                            wait({
+                                waitId: 'approval',
+                                on: { type: 'corpus.approved' },
+                            }),
+                        ];
+                    }
+                    if (!state.charged) {
+                        return [invoke(charge, { amount: state.amount }, 'charge')];
+                    }
+                    return [complete({ amount: state.amount, ok: true })];
+                },
+            }),
+        },
+        definitions: [corpusDefinition],
+    });
+}

package/dist/testing/index.d.ts

@@ -8,6 +8,8 @@ export interface TestRuntime {
 }
 export declare function createTestRuntime(modules: readonly AnyRuntimeModule[]): Promise<TestRuntime>;
 export declare function assertReplayDeterministic(test: TestRuntime, runId: string): Promise<void>;
+export { assertCorpusEntry, assertReplayDeterministicEvents, corpusRegistry, readCorpusEntry, type CorpusEntry, } from './replay-corpus';
+export { corpusChargeV1, corpusChargeV2, corpusDefinition, corpusModule } from './corpus-module';
 export declare function moduleConformance(module: AnyRuntimeModule): string[];
 export type EventStoreFaultOperation = 'append' | 'read' | 'tail' | 'bounds' | 'trim' | 'listRuns';
 export interface EventStoreFaultContext {

package/dist/testing/index.js

@@ -1,6 +1,7 @@
 import { Effect, Predicate } from 'effect';
-import { composeModules, EventStoreTag, foldRun, makeMemoryEventStore, ModuleCompositionError, EventStoreError, snapshotStoreOf, stringifyJson, withSnapshotStore, } from '@swirls/looms/core';
+import { composeModules, EventStoreTag, makeMemoryEventStore, ModuleCompositionError, EventStoreError, snapshotStoreOf, withSnapshotStore, } from '@swirls/looms/core';
 import { createRuntime } from '@swirls/looms/runtime';
+import { assertReplayDeterministicEvents } from './replay-corpus.js';
 function namedEffects(effects) {
     const listed = [];
     for (const key of Object.keys(effects)) {
@@ -27,13 +28,11 @@ export function createTestRuntime(modules) {
 }
 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}`);
-        }
+        assertReplayDeterministicEvents(events, test.runtime.registry, runId);
     });
 }
+export { assertCorpusEntry, assertReplayDeterministicEvents, corpusRegistry, readCorpusEntry, } from './replay-corpus.js';
+export { corpusChargeV1, corpusChargeV2, corpusDefinition, corpusModule } from './corpus-module.js';
 export function moduleConformance(module) {
     const errors = [];
     if (!module.namespace) {

package/dist/testing/replay-corpus.d.ts

@@ -0,0 +1,22 @@
+import { type AnyRuntimeModule, type EventEnvelope, type FoldRegistry, type JsonValue, type RunState } from '@swirls/looms/core';
+export type CorpusEntry = {
+    readonly name: string;
+    readonly runId: string;
+    readonly events: ReadonlyArray<EventEnvelope>;
+    readonly stateHash: string;
+};
+/** Modules every corpus fixture was recorded against. Keep them stable across releases. */
+export declare function corpusRegistry(modules?: ReadonlyArray<AnyRuntimeModule>): FoldRegistry;
+/**
+ * Fold the same log twice and require a byte-identical {@link RunState}. Use this in CI against a
+ * recorded corpus so a fold or protocol change that breaks replay fails before release.
+ */
+export declare function assertReplayDeterministicEvents(events: ReadonlyArray<EventEnvelope>, registry: FoldRegistry, runId: string): RunState;
+/** Parse one recorded corpus JSON document. */
+export declare function readCorpusEntry(raw: JsonValue): CorpusEntry;
+/**
+ * Replay one recorded log: fold must be deterministic and must match the hash taken when the
+ * fixture was written. A changed hash means the fold or a domain reducer moved under a recorded
+ * production-shaped log.
+ */
+export declare function assertCorpusEntry(entry: CorpusEntry, registry?: FoldRegistry): RunState;

package/dist/testing/replay-corpus.js

@@ -0,0 +1,50 @@
+import { Schema } from 'effect';
+import { composeModules, EventEnvelopeSchema, foldRun, fromWireEvent, hashRunState, stringifyJson, } from '@swirls/looms/core';
+import { corpusModule } from './corpus-module.js';
+const CorpusEntrySchema = Schema.Struct({
+    name: Schema.String,
+    runId: Schema.String,
+    events: Schema.Array(EventEnvelopeSchema),
+    /** Hash of the folded state when the log was recorded. */
+    stateHash: Schema.String,
+});
+const decodeEntry = Schema.decodeUnknownSync(CorpusEntrySchema);
+/** Modules every corpus fixture was recorded against. Keep them stable across releases. */
+export function corpusRegistry(modules = [corpusModule()]) {
+    return composeModules(modules);
+}
+/**
+ * Fold the same log twice and require a byte-identical {@link RunState}. Use this in CI against a
+ * recorded corpus so a fold or protocol change that breaks replay fails before release.
+ */
+export function assertReplayDeterministicEvents(events, registry, runId) {
+    const first = foldRun(events, registry, { runId });
+    const second = foldRun(events, registry, { runId });
+    if (stringifyJson(first) !== stringifyJson(second)) {
+        throw new Error(`Replay is not deterministic for run ${runId}`);
+    }
+    return first;
+}
+/** Parse one recorded corpus JSON document. */
+export function readCorpusEntry(raw) {
+    const entry = decodeEntry(raw);
+    return {
+        name: entry.name,
+        runId: entry.runId,
+        stateHash: entry.stateHash,
+        events: entry.events.map(fromWireEvent),
+    };
+}
+/**
+ * Replay one recorded log: fold must be deterministic and must match the hash taken when the
+ * fixture was written. A changed hash means the fold or a domain reducer moved under a recorded
+ * production-shaped log.
+ */
+export function assertCorpusEntry(entry, registry = corpusRegistry()) {
+    const state = assertReplayDeterministicEvents(entry.events, registry, entry.runId);
+    const actual = hashRunState(state);
+    if (actual !== entry.stateHash) {
+        throw new Error(`Corpus "${entry.name}" folded to ${actual}, expected ${entry.stateHash}. Re-record only after confirming the change is intentional.`);
+    }
+    return state;
+}

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

@@ -6,5 +6,5 @@ declare const WorkflowDefinitionsTag_base: Context.ServiceClass<WorkflowDefiniti
 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 declare const WorkflowDefinitionsLive: (definitions: WorkflowDefinitionStore) => Layer.Layer<WorkflowDefinitionsTag, never, never>;
 export {};

package/dist/workflow/definitions-store.js

@@ -5,4 +5,4 @@ export class WorkflowDefinitionsTag extends Context.Service()('looms/WorkflowDef
 export function makeWorkflowDefinitionStore(definitions) {
     return makeDefinitionStore('workflow', definitions);
 }
-export const WorkflowDefinitionsLive = (definitions) => Layer.succeed(WorkflowDefinitionsTag, makeWorkflowDefinitionStore(definitions));
+export const WorkflowDefinitionsLive = (definitions) => Layer.succeed(WorkflowDefinitionsTag, definitions);

package/dist/workflow/definitions.d.ts

@@ -118,6 +118,16 @@ export interface WorkflowDefinition<TName extends string = string, TInput = Json
     readonly inputLimitBytes?: number;
     readonly outputLimitBytes?: number;
     readonly checkpointLimitBytes?: number;
+    /**
+     * `thread` keeps spawned, mapped, and looped children in this run.
+     * `run` launches each child as its own run.
+     */
+    readonly childExecution?: 'thread' | 'run';
+    /**
+     * When this run is cancelled, `terminate` cancels child runs immediately and `wait` cancels
+     * this run only after those children have finished cancelling. Ignored when children are threads.
+     */
+    readonly childClose?: 'terminate' | 'wait';
     output?(ctx: {
         input: TInput;
         results: {
@@ -125,6 +135,10 @@ export interface WorkflowDefinition<TName extends string = string, TInput = Json
         };
     }): TOutput;
 }
+export interface WorkflowChildMode {
+    readonly execution: 'thread' | 'run';
+    readonly close: 'terminate' | 'wait';
+}
 export type AnyWorkflowDefinition = WorkflowDefinition;
 export declare function defineWorkflow<TName extends string, TInput = JsonValue, TOutput extends JsonValue = JsonValue>(def: Omit<WorkflowDefinition<TName, TInput, TOutput>, 'kind' | 'version'> & {
     readonly version?: string;