@swirls/looms 0.0.1

package/dist/core/effects.d.ts

@@ -0,0 +1,110 @@
+import { Effect } from 'effect';
+import type { EventInput } from './envelope';
+import { type InferDefinedSchema, type SchemaInput } from './schema';
+import { type JsonValue } from './types';
+export type WaitOnEvent = {
+    type: string | readonly string[];
+    match?: JsonValue;
+};
+export type WaitOnTimer = {
+    timerAt: number;
+};
+export type WaitCondition = WaitOnEvent | WaitOnTimer;
+export type SpawnEffect = {
+    type: 'runtime.spawn';
+    childThreadId: string;
+    kind: string;
+    definitionName: string;
+    input: JsonValue;
+};
+export type WaitEffect = {
+    type: 'runtime.wait';
+    waitId: string;
+    on: WaitCondition;
+    tag?: JsonValue;
+};
+export type EmitEffect<E extends EventInput = EventInput> = {
+    type: 'runtime.emit';
+    event: E;
+};
+export type CompleteEffect = {
+    type: 'runtime.complete';
+    output: JsonValue;
+};
+export type FailEffect = {
+    type: 'runtime.fail';
+    error: string;
+};
+export type CancelEffect = {
+    type: 'runtime.cancel';
+    threadId: string;
+};
+export interface RetryPolicy {
+    readonly maxAttempts: number;
+    readonly backoffMs?: number;
+    readonly maxBackoffMs?: number;
+}
+export type InvokeEffect = {
+    type: string;
+    input: JsonValue;
+    tag?: string;
+};
+export type PrimitiveEffect = SpawnEffect | WaitEffect | EmitEffect | CompleteEffect | FailEffect | CancelEffect;
+export type RuntimeEffect = PrimitiveEffect | InvokeEffect;
+export declare function isPrimitiveEffect(effect: RuntimeEffect): effect is PrimitiveEffect;
+export declare function isWaitOnTimer(on: WaitCondition): on is WaitOnTimer;
+export declare function isWaitOnEvent(on: WaitCondition): on is WaitOnEvent;
+export declare const WITHDRAWN_ERROR_PREFIX = "withdrawn:";
+export declare function withdrawnError(siblingEffectId: string): string;
+export declare function isWithdrawnError(error: string): boolean;
+export interface EffectContext {
+    readonly effectId: string;
+    readonly runId: string;
+    readonly threadId: string;
+    readonly causingEventId: string;
+    emit(event: EventInput): Promise<void>;
+}
+export interface ScopedEffectContext<E extends EventInput = EventInput> {
+    readonly effectId: string;
+    readonly runId: string;
+    readonly threadId: string;
+    readonly causingEventId: string;
+    emit(event: E): Promise<void>;
+}
+export type EffectInputSchema = SchemaInput;
+export type EffectHandlerResult<R = never, E extends EventInput = EventInput> = ReadonlyArray<E> | Promise<ReadonlyArray<E>> | Effect.Effect<ReadonlyArray<E>, Error, R>;
+export interface EffectDefinition<TInput = JsonValue, R = any, E extends EventInput = EventInput> {
+    readonly type: string;
+    readonly input?: SchemaInput;
+    readonly retry?: RetryPolicy;
+    execute(input: TInput, ctx: EffectContext): Effect.Effect<ReadonlyArray<E>, Error, R>;
+}
+/**
+ * Define an effect handler. A run's actor cell executes each effect at most
+ * once while it is alive. If the cell dies mid-execution, the replacement
+ * actor may re-run the handler (at-least-once across failover). Keep handlers
+ * idempotent when they have external side effects.
+ */
+export declare function defineEffect<TSchema = undefined, TInput = InferDefinedSchema<TSchema>, R = never, E extends EventInput = EventInput>(def: {
+    type: string;
+    input?: TSchema;
+    retry?: RetryPolicy;
+    execute: (input: TInput, ctx: EffectContext) => EffectHandlerResult<R, E>;
+}): EffectDefinition<TInput, R, E>;
+export declare function spawn(args: {
+    childThreadId?: string;
+    kind: string;
+    definitionName: string;
+    input: JsonValue;
+}): SpawnEffect;
+export declare function wait(args: {
+    waitId: string;
+    on: WaitCondition;
+    tag?: JsonValue;
+}): WaitEffect;
+export declare function emit<E extends EventInput = EventInput>(event: E): EmitEffect<E>;
+export declare function complete(output: JsonValue): CompleteEffect;
+export declare function fail(error: string): FailEffect;
+export declare function cancel(threadId: string): CancelEffect;
+export declare function invoke<TInput>(definition: EffectDefinition<TInput, any, any>, input: TInput, tag?: string): InvokeEffect;
+export declare function invoke(type: string, input: JsonValue, tag?: string): InvokeEffect;

package/dist/core/effects.js

@@ -0,0 +1,99 @@
+import { Effect, Predicate } from 'effect';
+import { validateInputEffect } from './schema.js';
+import { asJson } from './types.js';
+export function isPrimitiveEffect(effect) {
+    switch (effect.type) {
+        case 'runtime.spawn':
+        case 'runtime.wait':
+        case 'runtime.emit':
+        case 'runtime.complete':
+        case 'runtime.fail':
+        case 'runtime.cancel':
+            return true;
+        default:
+            return false;
+    }
+}
+export function isWaitOnTimer(on) {
+    return 'timerAt' in on;
+}
+export function isWaitOnEvent(on) {
+    return 'type' in on;
+}
+export const WITHDRAWN_ERROR_PREFIX = 'withdrawn:';
+export function withdrawnError(siblingEffectId) {
+    return `${WITHDRAWN_ERROR_PREFIX} sibling effect ${siblingEffectId} failed`;
+}
+export function isWithdrawnError(error) {
+    return error.startsWith(WITHDRAWN_ERROR_PREFIX);
+}
+function liftHandlerResult(result) {
+    if (Effect.isEffect(result)) {
+        return result;
+    }
+    if (result instanceof Promise) {
+        return Effect.tryPromise({
+            try: () => result,
+            catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+        });
+    }
+    return Effect.succeed(result);
+}
+/**
+ * Define an effect handler. A run's actor cell executes each effect at most
+ * once while it is alive. If the cell dies mid-execution, the replacement
+ * actor may re-run the handler (at-least-once across failover). Keep handlers
+ * idempotent when they have external side effects.
+ */
+export function defineEffect(def) {
+    const schema = def.input;
+    // SAFETY: execute validates raw JsonValue against the optional schema before the typed handler.
+    return {
+        type: def.type,
+        input: schema,
+        retry: def.retry,
+        execute: (raw, ctx) => Effect.gen(function* () {
+            const input = schema ? yield* validateInputEffect(schema, raw) : raw;
+            // SAFETY: input has been validated against schema or is unconstrained raw input
+            return yield* liftHandlerResult(def.execute(input, ctx));
+        }),
+    };
+}
+export function spawn(args) {
+    const childThreadId = args.childThreadId ?? '';
+    return {
+        type: 'runtime.spawn',
+        childThreadId,
+        kind: args.kind,
+        definitionName: args.definitionName,
+        input: args.input,
+    };
+}
+export function wait(args) {
+    const effect = {
+        type: 'runtime.wait',
+        waitId: args.waitId,
+        on: args.on,
+    };
+    if (args.tag !== undefined) {
+        effect.tag = args.tag;
+    }
+    return effect;
+}
+export function emit(event) {
+    return { type: 'runtime.emit', event };
+}
+export function complete(output) {
+    return { type: 'runtime.complete', output };
+}
+export function fail(error) {
+    return { type: 'runtime.fail', error };
+}
+export function cancel(threadId) {
+    return { type: 'runtime.cancel', threadId };
+}
+export function invoke(typeOrDef, input, tag) {
+    const type = Predicate.isString(typeOrDef) ? typeOrDef : typeOrDef.type;
+    const jsonInput = asJson(input);
+    return tag !== undefined ? { type, input: jsonInput, tag } : { type, input: jsonInput };
+}

package/dist/core/envelope.d.ts

@@ -0,0 +1,79 @@
+import { Schema } from 'effect';
+import type { JsonValue } from './types';
+export declare const JsonValueSchema: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+export declare const EventOriginSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"thread">;
+    readonly threadId: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"external">;
+    readonly actorId: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"system">;
+}>]>;
+export type EventOrigin = Schema.Schema.Type<typeof EventOriginSchema>;
+export declare const EventEnvelopeSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly runId: Schema.String;
+    readonly seq: Schema.Number;
+    readonly ts: Schema.Number;
+    readonly type: Schema.String;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly threadId: Schema.NullOr<Schema.String>;
+    readonly parentThreadId: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly causationId: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly correlationId: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly effectId: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly origin: Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"thread">;
+        readonly threadId: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"external">;
+        readonly actorId: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"system">;
+    }>]>;
+    readonly ephemeral: Schema.optional<Schema.Boolean>;
+    readonly idempotencyKey: Schema.optional<Schema.NullOr<Schema.String>>;
+}>;
+export type EventEnvelope<TType extends string = string, TPayload = JsonValue> = {
+    id: string;
+    runId: string;
+    seq: number;
+    ts: number;
+    type: TType;
+    payload: TPayload;
+    threadId: string | null;
+    parentThreadId?: string | null;
+    causationId?: string | null;
+    correlationId?: string | null;
+    effectId?: string | null;
+    origin: EventOrigin;
+    ephemeral?: boolean;
+    idempotencyKey?: string | null;
+};
+export type TypedEvent<TType extends string, TPayload = JsonValue> = EventEnvelope<TType, TPayload>;
+export type EventInput<TType extends string = string, TPayload = JsonValue> = {
+    type: TType;
+    payload: TPayload;
+    threadId?: string | null;
+    parentThreadId?: string | null;
+    causationId?: string | null;
+    correlationId?: string | null;
+    effectId?: string | null;
+    origin?: EventOrigin;
+    ephemeral?: boolean;
+    id?: string;
+    ts?: number;
+    idempotencyKey?: string | null;
+};
+export type AppendableEvent = Omit<EventEnvelope, 'seq'> & {
+    seq?: number;
+};
+export declare function payloadAsJson(payload: JsonValue): JsonValue;
+export declare function withAssignedSeq(partial: AppendableEvent, runId: string, seq: number): EventEnvelope;
+export declare function createEvent<TType extends string>(runId: string, input: Omit<EventInput, 'type'> & {
+    type: TType;
+}, options?: {
+    seq?: number;
+}): EventEnvelope<TType>;
+export declare function fromWireEvent(wire: Schema.Schema.Type<typeof EventEnvelopeSchema>): EventEnvelope;

package/dist/core/envelope.js

@@ -0,0 +1,68 @@
+import { Schema } from 'effect';
+import { createEventId } from './ids.js';
+export const JsonValueSchema = Schema.Json;
+export const EventOriginSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal('thread'),
+        threadId: Schema.String,
+    }),
+    Schema.Struct({
+        type: Schema.Literal('external'),
+        actorId: Schema.optional(Schema.String),
+    }),
+    Schema.Struct({
+        type: Schema.Literal('system'),
+    }),
+]);
+export const EventEnvelopeSchema = Schema.Struct({
+    id: Schema.String,
+    runId: Schema.String,
+    seq: Schema.Number,
+    ts: Schema.Number,
+    type: Schema.String,
+    payload: JsonValueSchema,
+    threadId: Schema.NullOr(Schema.String),
+    parentThreadId: Schema.optional(Schema.NullOr(Schema.String)),
+    causationId: Schema.optional(Schema.NullOr(Schema.String)),
+    correlationId: Schema.optional(Schema.NullOr(Schema.String)),
+    effectId: Schema.optional(Schema.NullOr(Schema.String)),
+    origin: EventOriginSchema,
+    ephemeral: Schema.optional(Schema.Boolean),
+    idempotencyKey: Schema.optional(Schema.NullOr(Schema.String)),
+});
+export function payloadAsJson(payload) {
+    // SAFETY: round-trip through JSON yields JsonValue.
+    return JSON.parse(JSON.stringify(payload));
+}
+export function withAssignedSeq(partial, runId, seq) {
+    return { ...partial, runId, seq };
+}
+export function createEvent(runId, input, options) {
+    const threadId = input.threadId ?? null;
+    const parentThreadId = input.parentThreadId ?? null;
+    return {
+        id: input.id ?? createEventId(),
+        runId,
+        seq: options?.seq ?? 0,
+        ts: input.ts ?? Date.now(),
+        type: input.type,
+        payload: input.payload,
+        threadId,
+        parentThreadId,
+        causationId: input.causationId,
+        correlationId: input.correlationId,
+        effectId: input.effectId,
+        origin: input.origin ?? { type: 'system' },
+        ephemeral: input.ephemeral,
+        idempotencyKey: input.idempotencyKey ?? null,
+    };
+}
+export function fromWireEvent(wire) {
+    const threadId = wire.threadId ?? null;
+    const parentThreadId = wire.parentThreadId ?? null;
+    return {
+        ...wire,
+        threadId,
+        parentThreadId,
+    };
+}

package/dist/core/event-codec.d.ts

@@ -0,0 +1,8 @@
+import type { AppendableEvent, EventEnvelope } from './envelope';
+import type { JsonValue } from './types';
+/** JSON-safe event envelope for SSE and pull responses. */
+export type EncodedLoomsEvent = EventEnvelope;
+export declare function encodeLoomsEvent(event: EventEnvelope): EncodedLoomsEvent;
+export declare function encodeAppendableEvent(event: AppendableEvent): EncodedLoomsEvent;
+export declare function decodeLoomsEvent(raw: JsonValue | EncodedLoomsEvent, runId: string): EventEnvelope;
+export declare function decodeAppendableEvent(raw: JsonValue | EncodedLoomsEvent, runId: string): AppendableEvent | undefined;

package/dist/core/event-codec.js

@@ -0,0 +1,82 @@
+import { Predicate } from 'effect';
+import { createEvent, payloadAsJson } from './envelope.js';
+import { createEventId } from './ids.js';
+export function encodeLoomsEvent(event) {
+    return {
+        ...event,
+        payload: payloadAsJson(event.payload),
+    };
+}
+export function encodeAppendableEvent(event) {
+    return {
+        id: event.id ?? createEventId(),
+        runId: event.runId,
+        seq: event.seq ?? 0,
+        ts: event.ts ?? Date.now(),
+        type: event.type,
+        payload: payloadAsJson(event.payload),
+        threadId: event.threadId ?? null,
+        parentThreadId: event.parentThreadId ?? null,
+        causationId: event.causationId ?? null,
+        correlationId: event.correlationId ?? null,
+        effectId: event.effectId ?? null,
+        ephemeral: event.ephemeral ?? false,
+        origin: event.origin,
+    };
+}
+function readOrigin(raw) {
+    if ('type' in raw && raw.type === 'thread') {
+        const threadId = 'threadId' in raw && Predicate.isString(raw.threadId) ? raw.threadId : '';
+        return { type: 'thread', threadId };
+    }
+    if ('type' in raw && raw.type === 'external') {
+        const actorId = 'actorId' in raw && Predicate.isString(raw.actorId) ? raw.actorId : undefined;
+        return actorId ? { type: 'external', actorId } : { type: 'external' };
+    }
+    return { type: 'system' };
+}
+export function decodeLoomsEvent(raw, runId) {
+    if (!Predicate.isReadonlyObject(raw)) {
+        throw new Error('Invalid event payload: expected object');
+    }
+    if ('type' in raw && Predicate.isString(raw.type)) {
+        const rawPayload = 'payload' in raw ? raw.payload : {};
+        // SAFETY: payload is JSON-compatible.
+        const payload = rawPayload;
+        const id = 'id' in raw && Predicate.isString(raw.id) ? raw.id : createEventId();
+        const ts = 'ts' in raw && Predicate.isNumber(raw.ts) ? raw.ts : Date.now();
+        const seq = 'seq' in raw && Predicate.isNumber(raw.seq) ? raw.seq : 0;
+        const ephemeral = 'ephemeral' in raw && Predicate.isBoolean(raw.ephemeral) ? raw.ephemeral : false;
+        const itemRunId = 'runId' in raw && Predicate.isString(raw.runId) ? raw.runId : runId;
+        const threadId = 'threadId' in raw && Predicate.isString(raw.threadId) ? raw.threadId : null;
+        const parentThreadId = 'parentThreadId' in raw && Predicate.isString(raw.parentThreadId) ? raw.parentThreadId : null;
+        const origin = 'origin' in raw && Predicate.isReadonlyObject(raw.origin)
+            ? readOrigin(raw.origin)
+            : { type: 'system' };
+        return createEvent(itemRunId, {
+            id,
+            ts,
+            type: raw.type,
+            payload,
+            threadId,
+            parentThreadId,
+            causationId: 'causationId' in raw && Predicate.isString(raw.causationId) ? raw.causationId : null,
+            correlationId: 'correlationId' in raw && Predicate.isString(raw.correlationId)
+                ? raw.correlationId
+                : null,
+            effectId: 'effectId' in raw && Predicate.isString(raw.effectId) ? raw.effectId : null,
+            ephemeral,
+            origin,
+        }, { seq });
+    }
+    throw new Error('Invalid event payload: missing type');
+}
+export function decodeAppendableEvent(raw, runId) {
+    try {
+        const { seq: _seq, ...rest } = decodeLoomsEvent(raw, runId);
+        return rest;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/event-index.d.ts

@@ -0,0 +1,28 @@
+import type { EventEnvelope } from './envelope';
+/** Thread bucket key used by run-tree counts (`threadId` or `'run'` for run-scoped). */
+export declare function eventThreadKey(event: {
+    threadId?: string | null;
+}): string;
+/**
+ * Append-only indexes over an event log. Thread/count snapshots are rebuilt
+ * lazily on read so coalesced applies avoid repeated O(n) freezes.
+ */
+export declare class EventIndex<TEvent extends EventEnvelope = EventEnvelope> {
+    private counts;
+    private countsSnapshot;
+    private countsDirty;
+    private byThread;
+    private byThreadSnapshots;
+    private dirtyThreads;
+    private bySeqMap;
+    private latestByType;
+    private startedAtTimestamp;
+    append(batch: readonly TEvent[]): void;
+    private publish;
+    getCounts(): ReadonlyMap<string, number>;
+    getByThread(threadId: string): readonly TEvent[];
+    getBySeq(seq: number): TEvent | undefined;
+    getStartedAt(): number | undefined;
+    getLatest(type: string): TEvent | undefined;
+    clear(): void;
+}

package/dist/core/event-index.js

@@ -0,0 +1,86 @@
+const EMPTY_EVENTS = Object.freeze([]);
+/** Thread bucket key used by run-tree counts (`threadId` or `'run'` for run-scoped). */
+export function eventThreadKey(event) {
+    return event.threadId ?? 'run';
+}
+/**
+ * Append-only indexes over an event log. Thread/count snapshots are rebuilt
+ * lazily on read so coalesced applies avoid repeated O(n) freezes.
+ */
+export class EventIndex {
+    counts = new Map();
+    countsSnapshot = new Map();
+    countsDirty = false;
+    byThread = new Map();
+    byThreadSnapshots = new Map();
+    dirtyThreads = new Set();
+    bySeqMap = new Map();
+    latestByType = new Map();
+    startedAtTimestamp = undefined;
+    append(batch) {
+        if (batch.length === 0) {
+            return;
+        }
+        for (const event of batch) {
+            this.bySeqMap.set(event.seq, event);
+            this.latestByType.set(event.type, event);
+            if (this.startedAtTimestamp === undefined && event.type === 'runtime.run.started') {
+                this.startedAtTimestamp = event.ts;
+            }
+            const threadKey = eventThreadKey(event);
+            this.counts.set(threadKey, (this.counts.get(threadKey) ?? 0) + 1);
+            this.dirtyThreads.add(threadKey);
+            this.countsDirty = true;
+            let threadList = this.byThread.get(threadKey);
+            if (!threadList) {
+                threadList = [];
+                this.byThread.set(threadKey, threadList);
+            }
+            threadList.push(event);
+        }
+    }
+    publish() {
+        if (this.dirtyThreads.size > 0) {
+            for (const threadKey of this.dirtyThreads) {
+                const list = this.byThread.get(threadKey);
+                if (list) {
+                    this.byThreadSnapshots.set(threadKey, Object.freeze(list.slice()));
+                }
+            }
+            this.dirtyThreads.clear();
+        }
+        if (this.countsDirty) {
+            this.countsSnapshot = new Map(this.counts);
+            this.countsDirty = false;
+        }
+    }
+    getCounts() {
+        this.publish();
+        return this.countsSnapshot;
+    }
+    getByThread(threadId) {
+        this.publish();
+        // SAFETY: EMPTY_EVENTS is an empty frozen array compatible with any TEvent[].
+        return this.byThreadSnapshots.get(threadId) ?? EMPTY_EVENTS;
+    }
+    getBySeq(seq) {
+        return this.bySeqMap.get(seq);
+    }
+    getStartedAt() {
+        return this.startedAtTimestamp;
+    }
+    getLatest(type) {
+        return this.latestByType.get(type);
+    }
+    clear() {
+        this.counts.clear();
+        this.countsSnapshot = new Map();
+        this.countsDirty = false;
+        this.byThread.clear();
+        this.byThreadSnapshots.clear();
+        this.dirtyThreads.clear();
+        this.bySeqMap.clear();
+        this.latestByType.clear();
+        this.startedAtTimestamp = undefined;
+    }
+}

package/dist/core/fold.d.ts

@@ -0,0 +1,19 @@
+import { Stream, type Effect } from 'effect';
+import type { EventEnvelope } from './envelope';
+import type { RunState } from './state';
+import { type ThreadDefinition } from './thread';
+export interface FoldRegistry {
+    readonly threads: ReadonlyMap<string, ThreadDefinition>;
+}
+export declare function foldEvent(state: RunState, event: EventEnvelope, registry: FoldRegistry): RunState;
+export declare function foldRun(events: readonly EventEnvelope[], registry: FoldRegistry, options?: {
+    runId?: string;
+    initial?: RunState;
+}): RunState;
+/**
+ * Folds an Effect Stream of events into RunState without buffering all events into memory.
+ */
+export declare function foldStream<E = never, R = never>(stream: Stream.Stream<EventEnvelope, E, R>, registry: FoldRegistry, options?: {
+    runId?: string;
+    initial?: RunState;
+}): Effect.Effect<RunState, E, R>;