@swirls/looms 0.0.1

package/dist/core/replay.d.ts

@@ -0,0 +1,13 @@
+import type { RuntimeEffect } from './effects';
+import type { EventEnvelope } from './envelope';
+import { type FoldRegistry } from './fold';
+import { type RunState } from './state';
+export interface ReplayStep {
+    seq: number;
+    event: EventEnvelope;
+    before: RunState;
+    after: RunState;
+    effects: RuntimeEffect[];
+}
+export declare function replayTo(events: readonly EventEnvelope[], registry: FoldRegistry, seq: number): ReplayStep | null;
+export declare function replayAll(events: readonly EventEnvelope[], registry: FoldRegistry): ReplayStep[];

package/dist/core/replay.js

@@ -0,0 +1,34 @@
+import { foldEvent, foldRun } from './fold.js';
+import { emptyRunState } from './state.js';
+export function replayTo(events, registry, seq) {
+    const target = events.find((event) => event.seq === seq && !event.ephemeral);
+    if (!target) {
+        return null;
+    }
+    const prior = events.filter((event) => event.seq < seq);
+    const before = foldRun(prior, registry, { runId: target.runId });
+    const after = foldEvent(before, target, registry);
+    const beforeIds = new Set(before.outstandingEffects.map((item) => item.effectId));
+    const effects = after.outstandingEffects
+        .filter((item) => !beforeIds.has(item.effectId))
+        .map((item) => item.effect);
+    return { seq, event: target, before, after, effects };
+}
+export function replayAll(events, registry) {
+    const steps = [];
+    let state = emptyRunState(events[0]?.runId ?? 'unknown');
+    for (const event of events) {
+        if (event.ephemeral) {
+            continue;
+        }
+        const before = state;
+        const after = foldEvent(before, event, registry);
+        const beforeIds = new Set(before.outstandingEffects.map((item) => item.effectId));
+        const effects = after.outstandingEffects
+            .filter((item) => !beforeIds.has(item.effectId))
+            .map((item) => item.effect);
+        steps.push({ seq: event.seq, event, before, after, effects });
+        state = after;
+    }
+    return steps;
+}

package/dist/core/schema.d.ts

@@ -0,0 +1,35 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Effect, Schema } from 'effect';
+import type { JsonValue } from './types';
+declare const InvalidInputError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InvalidInputError";
+} & Readonly<A>;
+export declare class InvalidInputError extends InvalidInputError_base<{
+    readonly message: string;
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+}> {
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(text: string, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+export type SchemaInput = StandardSchemaV1<any, any> | Schema.Top | Schema.Schema<any> | {
+    _output: any;
+};
+export type InferSchemaOutput<T> = T extends Schema.Schema<infer Out> ? Out : T extends Schema.Top ? Schema.Schema.Type<T> : T extends StandardSchemaV1<any, infer Out> ? Out : T extends {
+    _output: infer Out;
+} ? Out : never;
+/** Output of an optional `input` / `shape` schema, or `TFallback` when the schema is omitted. */
+export type InferDefinedSchema<T, TFallback = JsonValue> = [T] extends [undefined] ? TFallback : InferSchemaOutput<NonNullable<T>>;
+type SchemaCandidate<TInput> = StandardSchemaV1<JsonValue, TInput> | StandardSchemaV1<unknown, TInput> | StandardSchemaV1<any, TInput> | Schema.Schema<TInput> | {
+    _output: TInput;
+} | {
+    input?: StandardSchemaV1<JsonValue, TInput> | StandardSchemaV1<unknown, TInput> | StandardSchemaV1<any, TInput> | Schema.Schema<TInput> | {
+        _output: TInput;
+    };
+    schema?: StandardSchemaV1<JsonValue, TInput> | StandardSchemaV1<unknown, TInput> | StandardSchemaV1<any, TInput> | Schema.Schema<TInput> | {
+        _output: TInput;
+    };
+} | null | undefined;
+export declare function validateInputEffect<TInput = JsonValue>(schemaOrDef: SchemaCandidate<TInput>, raw: JsonValue): Effect.Effect<TInput, InvalidInputError>;
+export declare function validateInput<TInput = JsonValue>(schemaOrDef: SchemaCandidate<TInput>, raw: JsonValue): Promise<TInput>;
+export declare function validateInputSync<TInput = JsonValue>(schemaOrDef: SchemaCandidate<TInput>, raw: JsonValue): TInput;
+export {};

package/dist/core/schema.js

@@ -0,0 +1,130 @@
+import { Data, Effect, Predicate, Schema } from 'effect';
+export class InvalidInputError extends Data.TaggedError('InvalidInputError') {
+    issues;
+    constructor(text, issues = []) {
+        super({ message: text, issues });
+        this.name = 'InvalidInputError';
+        this.issues = issues;
+    }
+}
+function toStandard(candidate) {
+    if (!candidate) {
+        return undefined;
+    }
+    if (Schema.isSchema(candidate)) {
+        // SAFETY: Effect Schema converts to StandardSchemaV1 via official helper.
+        return Schema.toStandardSchemaV1(candidate);
+    }
+    if (Predicate.isObject(candidate) && '~standard' in candidate) {
+        // SAFETY: verified '~standard' property exists on object.
+        return candidate;
+    }
+    if (Predicate.isObject(candidate) && 'safeParse' in candidate) {
+        // SAFETY: candidate has safeParse property verified by key check.
+        const safeParse = candidate.safeParse;
+        if (Predicate.isFunction(safeParse)) {
+            // SAFETY: verified safeParse is a function matching the Zod safeParse contract.
+            const zodSchema = candidate;
+            return {
+                '~standard': {
+                    version: 1,
+                    vendor: 'zod-compat',
+                    validate(raw) {
+                        const res = zodSchema.safeParse(raw);
+                        if (res.success) {
+                            return { value: res.data };
+                        }
+                        return {
+                            issues: res.error.issues.map((issue) => ({
+                                message: issue.message,
+                                path: issue.path,
+                            })),
+                        };
+                    },
+                },
+            };
+        }
+    }
+    return undefined;
+}
+function extractSchema(schemaOrDef) {
+    const direct = toStandard(schemaOrDef);
+    if (direct) {
+        return direct;
+    }
+    if (schemaOrDef && Predicate.isObject(schemaOrDef)) {
+        if ('schema' in schemaOrDef) {
+            // SAFETY: verified schemaOrDef has schema property.
+            const fromSchema = toStandard(schemaOrDef.schema);
+            if (fromSchema) {
+                return fromSchema;
+            }
+        }
+        if ('input' in schemaOrDef) {
+            // SAFETY: Verified schemaOrDef has input property.
+            return toStandard(schemaOrDef.input);
+        }
+    }
+    return undefined;
+}
+function formatIssue(issue) {
+    if (!issue.path || issue.path.length === 0) {
+        return issue.message;
+    }
+    const pathStr = issue.path
+        .map((p) => {
+        if (Predicate.isReadonlyObject(p) && 'key' in p) {
+            return String(p.key);
+        }
+        if (Predicate.isString(p) || Predicate.isNumber(p)) {
+            return String(p);
+        }
+        return '';
+    })
+        .filter((s) => s.length > 0)
+        .join('.');
+    return `${pathStr}: ${issue.message}`;
+}
+export function validateInputEffect(schemaOrDef, raw) {
+    const schema = extractSchema(schemaOrDef);
+    if (!schema) {
+        // SAFETY: when no schema is provided, raw JsonValue is accepted as TInput.
+        return Effect.succeed(raw);
+    }
+    return Effect.gen(function* () {
+        let result = schema['~standard'].validate(raw);
+        if (result instanceof Promise) {
+            result = yield* Effect.tryPromise({
+                // SAFETY: Standard Schema validate() returns this Promise when async.
+                try: () => result,
+                catch: (cause) => new InvalidInputError(`Schema validation failed: ${cause instanceof Error ? cause.message : String(cause)}`),
+            });
+        }
+        if (result.issues !== undefined) {
+            const text = result.issues.map(formatIssue).join(', ');
+            return yield* Effect.fail(new InvalidInputError(`Invalid input: ${text}`, result.issues));
+        }
+        return result.value;
+    });
+}
+export async function validateInput(schemaOrDef, raw) {
+    return Effect.runPromise(validateInputEffect(schemaOrDef, raw));
+}
+export function validateInputSync(schemaOrDef, raw) {
+    const schema = extractSchema(schemaOrDef);
+    if (!schema) {
+        // SAFETY: when no schema is provided, raw JsonValue is accepted as TInput.
+        return raw;
+    }
+    // SAFETY: StandardSchemaV1.validate returns Result<TInput> or Promise<Result<TInput>>.
+    const result = schema['~standard'].validate(raw);
+    if (result instanceof Promise) {
+        throw new Error('Async schema validation is not supported in synchronous context');
+    }
+    if (result.issues !== undefined) {
+        const text = result.issues.map(formatIssue).join(', ');
+        throw new InvalidInputError(`Invalid input: ${text}`, result.issues);
+    }
+    // SAFETY: When result.issues is undefined, result is SuccessResult.
+    return result.value;
+}

package/dist/core/serialize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * FIFO serializer keyed by arbitrary identifier (stream / run / key).
+ * - Guarantees sequential execution of async tasks for the same key.
+ * - Independent keys execute concurrently.
+ * - A failed task does not reject or block the chain for subsequent tasks.
+ * - Automatically evicts completed chains from memory when idle.
+ */
+export declare function createKeyedSerializer(): {
+    run: <T>(key: string, task: () => Promise<T>) => Promise<T>;
+    drain: (key: string) => Promise<void>;
+    clear: (key?: string) => void;
+    size: () => number;
+};
+export type KeyedSerializer = ReturnType<typeof createKeyedSerializer>;

package/dist/core/serialize.js

@@ -0,0 +1,42 @@
+/**
+ * FIFO serializer keyed by arbitrary identifier (stream / run / key).
+ * - Guarantees sequential execution of async tasks for the same key.
+ * - Independent keys execute concurrently.
+ * - A failed task does not reject or block the chain for subsequent tasks.
+ * - Automatically evicts completed chains from memory when idle.
+ */
+export function createKeyedSerializer() {
+    const tails = new Map();
+    const run = (key, task) => {
+        const prev = tails.get(key) ?? Promise.resolve();
+        let cleanup;
+        const next = prev.then(task, task);
+        cleanup = next.then(() => {
+            if (tails.get(key) === cleanup) {
+                tails.delete(key);
+            }
+        }, () => {
+            if (tails.get(key) === cleanup) {
+                tails.delete(key);
+            }
+        });
+        tails.set(key, cleanup);
+        return next;
+    };
+    const drain = async (key) => {
+        const pending = tails.get(key);
+        if (pending) {
+            await pending;
+        }
+    };
+    const clear = (key) => {
+        if (key !== undefined) {
+            tails.delete(key);
+        }
+        else {
+            tails.clear();
+        }
+    };
+    const size = () => tails.size;
+    return { run, drain, clear, size };
+}

package/dist/core/snapshot-store.d.ts

@@ -0,0 +1,39 @@
+import { Context, Effect, Option } from 'effect';
+import type { RunState } from './state';
+import type { EventStore } from './store';
+/**
+ * Materialized run state at a known stream position.
+ *
+ * `cursor` is the seq of the last covered event (aligned with
+ * `SnapshotTakenPayload.seq`). Recovery resumes at `cursor + 1`.
+ */
+export interface RunSnapshot {
+    readonly runId: string;
+    readonly cursor: number;
+    readonly stateHash: string;
+    readonly takenAt: number;
+    readonly state: RunState;
+}
+declare const SnapshotStoreError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SnapshotStoreError";
+} & Readonly<A>;
+export declare class SnapshotStoreError extends SnapshotStoreError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    constructor(text: string, cause?: unknown);
+}
+export interface SnapshotStore {
+    readonly loadLatest: (runId: string) => Effect.Effect<Option.Option<RunSnapshot>, SnapshotStoreError>;
+    readonly save: (snapshot: RunSnapshot) => Effect.Effect<void, SnapshotStoreError>;
+    readonly listCursors?: (runId: string) => Effect.Effect<number[], SnapshotStoreError>;
+    readonly prune?: (runId: string, keepLatest: number) => Effect.Effect<void, SnapshotStoreError>;
+}
+declare const SnapshotStoreTag_base: Context.ServiceClass<SnapshotStoreTag, "looms/SnapshotStore", SnapshotStore>;
+export declare class SnapshotStoreTag extends SnapshotStoreTag_base {
+}
+/** Attach a SnapshotStore to an EventStore so facades can pair them without extra options. */
+export declare function withSnapshotStore(store: EventStore, snapshots: SnapshotStore): EventStore;
+export declare function snapshotStoreOf(store: EventStore): SnapshotStore | undefined;
+export declare const makeMemorySnapshotStore: Effect.Effect<SnapshotStore, never, never>;
+export {};

package/dist/core/snapshot-store.js

@@ -0,0 +1,53 @@
+import { Context, Data, Effect, Option, Ref } from 'effect';
+export class SnapshotStoreError extends Data.TaggedError('SnapshotStoreError') {
+    constructor(text, cause) {
+        super({ message: text, cause });
+        this.name = 'SnapshotStoreError';
+    }
+}
+export class SnapshotStoreTag extends Context.Service()('looms/SnapshotStore') {
+}
+const SNAPSHOT_STORE = Symbol.for('looms/EventStore.snapshotStore');
+/** Attach a SnapshotStore to an EventStore so facades can pair them without extra options. */
+export function withSnapshotStore(store, snapshots) {
+    const slot = store;
+    slot[SNAPSHOT_STORE] = snapshots;
+    return store;
+}
+export function snapshotStoreOf(store) {
+    const slot = store;
+    return slot[SNAPSHOT_STORE];
+}
+export const makeMemorySnapshotStore = Effect.gen(function* () {
+    const snapshots = yield* Ref.make(new Map());
+    const service = {
+        loadLatest: (runId) => Effect.gen(function* () {
+            const map = yield* Ref.get(snapshots);
+            const list = map.get(runId);
+            if (!list || list.length === 0) {
+                return Option.none();
+            }
+            return Option.some(list[list.length - 1]);
+        }),
+        save: (snapshot) => Ref.update(snapshots, (map) => {
+            const next = new Map(map);
+            const existing = next.get(snapshot.runId) ?? [];
+            next.set(snapshot.runId, [...existing, snapshot]);
+            return next;
+        }),
+        listCursors: (runId) => Effect.gen(function* () {
+            const map = yield* Ref.get(snapshots);
+            return (map.get(runId) ?? []).map((item) => item.cursor);
+        }),
+        prune: (runId, keepLatest) => Ref.update(snapshots, (map) => {
+            const list = map.get(runId);
+            if (!list || list.length <= keepLatest) {
+                return map;
+            }
+            const next = new Map(map);
+            next.set(runId, list.slice(list.length - keepLatest));
+            return next;
+        }),
+    };
+    return service;
+});

package/dist/core/snapshots.d.ts

@@ -0,0 +1,26 @@
+import { Schema } from 'effect';
+import { type EventEnvelope } from './envelope';
+import { type FoldRegistry } from './fold';
+import { type RunState } from './state';
+import { type JsonValue } from './types';
+export declare const DEFAULT_SNAPSHOT_EVERY = 200;
+export declare const SnapshotTakenPayloadSchema: Schema.Struct<{
+    readonly seq: Schema.Number;
+    readonly stateHash: Schema.String;
+    readonly state: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export declare function hashRunState(state: RunState): string;
+export declare function shouldTakeSnapshot(events: readonly EventEnvelope[], every?: number): boolean;
+export declare const DEFAULT_MAX_INLINE_SNAPSHOT_BYTES: number;
+export declare function runStateToJson(state: RunState): JsonValue;
+export declare function buildSnapshotEvent(runId: string, events: readonly EventEnvelope[], registry: FoldRegistry, options?: {
+    includeState?: boolean;
+}): EventEnvelope;
+export declare function buildSnapshotMarker(runId: string, cursor: number, stateHash: string, options?: {
+    state?: RunState;
+    maxInlineBytes?: number;
+}): EventEnvelope;
+export declare function foldFromSnapshots(events: readonly EventEnvelope[], registry: FoldRegistry, options?: {
+    runId?: string;
+}): RunState;
+export declare function emptySnapshot(runId: string): RunState;

package/dist/core/snapshots.js

@@ -0,0 +1,100 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { Schema } from 'effect';
+import { createEvent, JsonValueSchema } from './envelope.js';
+import { foldRun } from './fold.js';
+import { emptyRunState } from './state.js';
+import { asJson, fromJsonStruct } from './types.js';
+export const DEFAULT_SNAPSHOT_EVERY = 200;
+export const SnapshotTakenPayloadSchema = Schema.Struct({
+    seq: Schema.Number,
+    stateHash: Schema.String,
+    state: Schema.optional(JsonValueSchema),
+});
+export function hashRunState(state) {
+    const json = JSON.stringify(state);
+    return bytesToHex(sha256(new TextEncoder().encode(json))).slice(0, 16);
+}
+export function shouldTakeSnapshot(events, every = DEFAULT_SNAPSHOT_EVERY) {
+    const durable = events.filter((e) => !e.ephemeral && e.type !== 'runtime.snapshot.taken');
+    if (durable.length === 0) {
+        return false;
+    }
+    let lastSnap;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const candidate = events[i];
+        if (candidate?.type === 'runtime.snapshot.taken') {
+            lastSnap = candidate;
+            break;
+        }
+    }
+    const since = lastSnap ? durable.filter((e) => e.seq > lastSnap.seq).length : durable.length;
+    return since >= every;
+}
+export const DEFAULT_MAX_INLINE_SNAPSHOT_BYTES = 256 * 1024;
+export function runStateToJson(state) {
+    const raw = JSON.parse(JSON.stringify(state));
+    return Schema.decodeUnknownSync(JsonValueSchema)(raw);
+}
+export function buildSnapshotEvent(runId, events, registry, options) {
+    const state = foldRun(events, registry, { runId });
+    const last = events[events.length - 1];
+    return buildSnapshotMarker(runId, last?.seq ?? 0, hashRunState(state), {
+        state: options?.includeState ? state : undefined,
+    });
+}
+/**
+ * Pointer-only snapshot marker. Inline `state` only when provided and
+ * `JSON.stringify(state).length <= maxInlineBytes` (default 256 KiB).
+ */
+let warnedInlineSkip = false;
+export function buildSnapshotMarker(runId, cursor, stateHash, options) {
+    const maxInlineBytes = options?.maxInlineBytes ?? DEFAULT_MAX_INLINE_SNAPSHOT_BYTES;
+    let payload = asJson({ seq: cursor, stateHash });
+    if (options?.state !== undefined) {
+        const encoded = runStateToJson(options.state);
+        const bytes = JSON.stringify(encoded).length;
+        if (bytes <= maxInlineBytes) {
+            payload = asJson({ seq: cursor, stateHash, state: encoded });
+        }
+        else if (!warnedInlineSkip) {
+            warnedInlineSkip = true;
+            console.warn(`[looms] snapshot state is ${bytes} bytes (limit ${maxInlineBytes}); writing a pointer-only marker`);
+        }
+    }
+    return createEvent(runId, {
+        type: 'runtime.snapshot.taken',
+        payload,
+        threadId: null,
+        origin: { type: 'system' },
+    });
+}
+export function foldFromSnapshots(events, registry, options) {
+    const runId = options?.runId ?? events[0]?.runId ?? 'unknown';
+    let latestSnapIdx = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+        if (events[i]?.type === 'runtime.snapshot.taken') {
+            latestSnapIdx = i;
+            break;
+        }
+    }
+    if (latestSnapIdx < 0) {
+        return foldRun(events, registry, { runId });
+    }
+    const snap = events[latestSnapIdx];
+    const decoded = Schema.decodeUnknownSync(SnapshotTakenPayloadSchema)(snap.payload);
+    if (decoded.state !== undefined) {
+        const trailing = events.filter((e) => e.seq > decoded.seq);
+        if (trailing.length === 0) {
+            return fromJsonStruct(decoded.state);
+        }
+        return foldRun(trailing, registry, {
+            runId,
+            initial: fromJsonStruct(decoded.state),
+        });
+    }
+    return foldRun(events, registry, { runId });
+}
+export function emptySnapshot(runId) {
+    return emptyRunState(runId);
+}

package/dist/core/sqlite-store.d.ts

@@ -0,0 +1,31 @@
+import { type EventStore } from './store';
+export declare const SQLITE_EVENT_STORE_SCHEMA: string;
+export type SqlBinding = string | number | null;
+/**
+ * Minimal SQL surface used by the embedded event store.
+ * Compatible with `bun:sqlite` and Cloudflare Durable Object `ctx.storage.sql`.
+ */
+export interface SqliteExec {
+    run(sql: string, params?: readonly SqlBinding[]): void;
+    rows(sql: string, params?: readonly SqlBinding[]): readonly unknown[];
+    /**
+     * Run `fn` atomically. When omitted, `sqliteEventStore` uses `BEGIN IMMEDIATE` /
+     * `COMMIT` / `ROLLBACK`. Durable Object SQL must supply this via
+     * `storage.transactionSync` — DO SQLite rejects SQL transaction statements.
+     */
+    transaction?<T>(fn: () => T): T;
+}
+export interface SqliteEventStoreOptions {
+    readonly exec: SqliteExec;
+}
+/** Adapter for Cloudflare Durable Object `ctx.storage.sql`. */
+export declare function sqlStorageExec(sql: {
+    exec: (query: string, ...bindings: SqlBinding[]) => Iterable<unknown>;
+}, options?: {
+    readonly transaction?: <T>(fn: () => T) => T;
+}): SqliteExec;
+/**
+ * Embedded SQLite EventStore for actor-local execution.
+ * Snapshots live in the same database and are attached automatically.
+ */
+export declare function sqliteEventStore(options: SqliteEventStoreOptions): EventStore;