@swirls/looms 0.0.2 → 0.2.0

package/dist/core/snapshots.d.ts

@@ -5,7 +5,7 @@ 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 seq: Schema.Finite;
     readonly stateHash: Schema.String;
     readonly state: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
 }>;
@@ -16,6 +16,10 @@ export declare function runStateToJson(state: RunState): JsonValue;
 export declare function buildSnapshotEvent(runId: string, events: readonly EventEnvelope[], registry: FoldRegistry, options?: {
     includeState?: boolean;
 }): EventEnvelope;
+/**
+ * Pointer-only snapshot marker. Inline `state` only when provided and
+ * serialized state is at most `maxInlineBytes` (default 256 KiB).
+ */
 export declare function buildSnapshotMarker(runId: string, cursor: number, stateHash: string, options?: {
     state?: RunState;
     maxInlineBytes?: number;

package/dist/core/snapshots.js

@@ -3,16 +3,17 @@ 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';
+import { utf8JsonBytes } from './limits.js';
+import { emptyRunState, RunStateSchema } from './state.js';
+import { asJson, stringifyJson } from './types.js';
 export const DEFAULT_SNAPSHOT_EVERY = 200;
 export const SnapshotTakenPayloadSchema = Schema.Struct({
-    seq: Schema.Number,
+    seq: Schema.Finite,
     stateHash: Schema.String,
     state: Schema.optional(JsonValueSchema),
 });
 export function hashRunState(state) {
-    const json = JSON.stringify(state);
+    const json = stringifyJson(state);
     return bytesToHex(sha256(new TextEncoder().encode(json))).slice(0, 16);
 }
 export function shouldTakeSnapshot(events, every = DEFAULT_SNAPSHOT_EVERY) {
@@ -33,8 +34,7 @@ export function shouldTakeSnapshot(events, every = DEFAULT_SNAPSHOT_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);
+    return asJson(state);
 }
 export function buildSnapshotEvent(runId, events, registry, options) {
     const state = foldRun(events, registry, { runId });
@@ -45,22 +45,17 @@ export function buildSnapshotEvent(runId, events, registry, options) {
 }
 /**
  * Pointer-only snapshot marker. Inline `state` only when provided and
- * `JSON.stringify(state).length <= maxInlineBytes` (default 256 KiB).
+ * serialized state is at most `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;
+        const bytes = utf8JsonBytes(encoded);
         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',
@@ -86,11 +81,11 @@ export function foldFromSnapshots(events, registry, options) {
     if (decoded.state !== undefined) {
         const trailing = events.filter((e) => e.seq > decoded.seq);
         if (trailing.length === 0) {
-            return fromJsonStruct(decoded.state);
+            return Schema.decodeUnknownSync(RunStateSchema)(decoded.state);
         }
         return foldRun(trailing, registry, {
             runId,
-            initial: fromJsonStruct(decoded.state),
+            initial: Schema.decodeUnknownSync(RunStateSchema)(decoded.state),
         });
     }
     return foldRun(events, registry, { runId });

package/dist/core/sqlite-store.js

@@ -1,6 +1,8 @@
 import { Effect, Option, Queue, Schema, Stream } from 'effect';
 import { EventEnvelopeSchema, fromWireEvent, withAssignedSeq } from './envelope.js';
+import { assertEventByteLimits, assertSnapshotByteLimit, EventPayloadTooLargeError, SnapshotPayloadTooLargeError, } from './limits.js';
 import { SnapshotStoreError, withSnapshotStore, } from './snapshot-store.js';
+import { RunStateSchema } from './state.js';
 import { EventStoreConflictError, EventStoreError, EventStoreFencedError, } from './store.js';
 export const SQLITE_EVENT_STORE_SCHEMA = `
 CREATE TABLE IF NOT EXISTS looms_streams (
@@ -25,11 +27,26 @@ CREATE TABLE IF NOT EXISTS looms_snapshots (
   state TEXT NOT NULL,
   PRIMARY KEY (run_id, cursor)
 );
+
+CREATE TABLE IF NOT EXISTS looms_commands (
+  run_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  fingerprint TEXT,
+  committed_tail INTEGER NOT NULL,
+  PRIMARY KEY (run_id, idempotency_key)
+);
+
+CREATE TABLE IF NOT EXISTS looms_run_headers (
+  run_id TEXT PRIMARY KEY,
+  status TEXT NOT NULL,
+  kind TEXT,
+  definition_name TEXT
+);
 `.trim();
 const StreamRowSchema = Schema.Struct({
     run_id: Schema.String,
-    head: Schema.Number,
-    tail: Schema.Number,
+    head: Schema.Finite,
+    tail: Schema.Finite,
     fence_token: Schema.NullOr(Schema.String),
 });
 const EventRowSchema = Schema.Struct({
@@ -37,25 +54,30 @@ const EventRowSchema = Schema.Struct({
 });
 const SnapshotRowSchema = Schema.Struct({
     run_id: Schema.String,
-    cursor: Schema.Number,
+    cursor: Schema.Finite,
     state_hash: Schema.String,
-    taken_at: Schema.Number,
+    taken_at: Schema.Finite,
     state: Schema.String,
 });
 const RunIdRowSchema = Schema.Struct({
     run_id: Schema.String,
 });
 const CursorRowSchema = Schema.Struct({
-    cursor: Schema.Number,
+    cursor: Schema.Finite,
+});
+const CommandRowSchema = Schema.Struct({
+    fingerprint: Schema.NullOr(Schema.String),
+    committed_tail: Schema.Finite,
 });
 const decodeEventBody = Schema.decodeUnknownSync(Schema.fromJsonString(EventEnvelopeSchema));
-const decodeRunState = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
+const decodeRunState = Schema.decodeUnknownSync(Schema.fromJsonString(RunStateSchema));
 const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
 const decodeStreamRow = Schema.decodeUnknownSync(StreamRowSchema);
 const decodeEventRow = Schema.decodeUnknownSync(EventRowSchema);
 const decodeSnapshotRow = Schema.decodeUnknownSync(SnapshotRowSchema);
 const decodeRunIdRow = Schema.decodeUnknownSync(RunIdRowSchema);
 const decodeCursorRow = Schema.decodeUnknownSync(CursorRowSchema);
+const decodeCommandRow = Schema.decodeUnknownSync(CommandRowSchema);
 /** Adapter for Cloudflare Durable Object `ctx.storage.sql`. */
 export function sqlStorageExec(sql, options) {
     return {
@@ -100,7 +122,6 @@ function parseEvent(body) {
     return fromWireEvent(decodeEventBody(body));
 }
 function toSnapshot(row) {
-    // SAFETY: snapshot state is a JSON-encoded RunState written by this store.
     const state = decodeRunState(row.state);
     return {
         runId: row.run_id,
@@ -110,6 +131,21 @@ function toSnapshot(row) {
         state,
     };
 }
+const HeaderRowSchema = Schema.Struct({
+    run_id: Schema.String,
+    status: RunStateSchema.fields.status,
+    kind: Schema.NullOr(Schema.String),
+    definition_name: Schema.NullOr(Schema.String),
+});
+const decodeHeaderRow = Schema.decodeUnknownSync(HeaderRowSchema);
+function headerFromRow(row) {
+    return {
+        runId: row.run_id,
+        status: row.status,
+        kind: row.kind,
+        definitionName: row.definition_name,
+    };
+}
 function createSqliteSnapshotStore(exec) {
     return {
         loadLatest: (runId) => Effect.try({
@@ -121,6 +157,7 @@ function createSqliteSnapshotStore(exec) {
         }),
         save: (snapshot) => Effect.try({
             try: () => {
+                assertSnapshotByteLimit(snapshot);
                 exec.run(`INSERT INTO looms_snapshots (run_id, cursor, state_hash, taken_at, state)
              VALUES (?, ?, ?, ?, ?)
              ON CONFLICT (run_id, cursor) DO UPDATE SET
@@ -134,7 +171,9 @@ function createSqliteSnapshotStore(exec) {
                     encodeJson(snapshot.state),
                 ]);
             },
-            catch: (cause) => new SnapshotStoreError(`Failed to save snapshot for ${snapshot.runId}`, cause),
+            catch: (cause) => cause instanceof SnapshotPayloadTooLargeError
+                ? cause
+                : new SnapshotStoreError(`Failed to save snapshot for ${snapshot.runId}`, cause),
         }),
         listCursors: (runId) => Effect.try({
             try: () => exec
@@ -158,6 +197,23 @@ function createSqliteSnapshotStore(exec) {
             },
             catch: (cause) => new SnapshotStoreError(`Failed to prune snapshots for ${runId}`, cause),
         }),
+        saveHeader: (header) => Effect.try({
+            try: () => {
+                exec.run(`INSERT INTO looms_run_headers (run_id, status, kind, definition_name)
+             VALUES (?, ?, ?, ?)
+             ON CONFLICT (run_id) DO UPDATE SET
+               status = excluded.status,
+               kind = excluded.kind,
+               definition_name = excluded.definition_name`, [header.runId, header.status, header.kind, header.definitionName]);
+            },
+            catch: (cause) => new SnapshotStoreError(`Failed to save run header for ${header.runId}`, cause),
+        }),
+        listHeaders: Effect.try({
+            try: () => exec
+                .rows('SELECT run_id, status, kind, definition_name FROM looms_run_headers')
+                .map((row) => headerFromRow(decodeHeaderRow(row))),
+            catch: (cause) => new SnapshotStoreError('Failed to list run headers', cause),
+        }),
     };
 }
 function createSqliteEventStore(exec) {
@@ -194,11 +250,33 @@ function createSqliteEventStore(exec) {
     const service = {
         append: (runId, events, options) => Effect.try({
             try: () => {
-                if (events.length === 0 && options?.fence === undefined) {
+                assertEventByteLimits(runId, events);
+                if (events.length === 0 &&
+                    options?.fence === undefined &&
+                    options?.idempotency === undefined) {
                     return { sequences: [], tail: getStream(runId).tail };
                 }
                 return runInTransaction(exec, () => {
                     const log = ensureStream(runId);
+                    const idempotency = options?.idempotency;
+                    if (idempotency) {
+                        const [commandRow] = exec.rows(`SELECT fingerprint, committed_tail
+                 FROM looms_commands
+                 WHERE run_id = ? AND idempotency_key = ?`, [runId, idempotency.key]);
+                        if (commandRow !== undefined) {
+                            const command = decodeCommandRow(commandRow);
+                            if (idempotency.fingerprint !== undefined &&
+                                command.fingerprint !== null &&
+                                command.fingerprint !== idempotency.fingerprint) {
+                                throw new EventStoreError(`Idempotency key "${idempotency.key}" was reused with different content`);
+                            }
+                            return {
+                                sequences: [],
+                                tail: getStream(runId).tail,
+                                deduplicated: true,
+                            };
+                        }
+                    }
                     if (options?.expectedTail !== undefined && log.tail !== options.expectedTail) {
                         throw new EventStoreConflictError(runId, options.expectedTail, log.tail);
                     }
@@ -231,13 +309,19 @@ function createSqliteEventStore(exec) {
                ON CONFLICT (run_id) DO UPDATE SET
                  tail = excluded.tail,
                  fence_token = excluded.fence_token`, [runId, log.head, nextTail, fenceToken]);
+                    if (idempotency) {
+                        exec.run(`INSERT INTO looms_commands
+                   (run_id, idempotency_key, fingerprint, committed_tail)
+                 VALUES (?, ?, ?, ?)`, [runId, idempotency.key, idempotency.fingerprint ?? null, nextTail]);
+                    }
                     notify(runId, appended);
                     return { sequences, tail: nextTail };
                 });
             },
             catch: (cause) => cause instanceof EventStoreConflictError ||
                 cause instanceof EventStoreFencedError ||
-                cause instanceof EventStoreError
+                cause instanceof EventStoreError ||
+                cause instanceof EventPayloadTooLargeError
                 ? cause
                 : new EventStoreError(`append failed for ${runId}`, cause),
         }),
@@ -308,7 +392,7 @@ function createSqliteEventStore(exec) {
                 }
             }));
         })),
-        listRuns: () => Effect.try({
+        listRuns: Effect.try({
             try: () => exec
                 .rows('SELECT run_id FROM looms_streams ORDER BY run_id ASC')
                 .map((row) => decodeRunIdRow(row).run_id),

package/dist/core/state.d.ts

@@ -1,9 +1,11 @@
-import type { RuntimeEffect, WaitCondition } from './effects';
+import { Schema } from 'effect';
+import { type RuntimeEffect, type WaitCondition } from './effects';
 import type { JsonValue, ThreadStatus, RunStatus } from './types';
 export interface ThreadRecord {
     threadId: string;
     kind: string;
     definitionName: string;
+    definitionVersion: string;
     parentThreadId: string | null;
     status: ThreadStatus;
     input: JsonValue;
@@ -24,20 +26,156 @@ export interface OutstandingEffect {
     causingEventId: string;
     effect: RuntimeEffect;
 }
+export interface EffectExecutionRecord {
+    effectId: string;
+    attempt: number;
+    status: 'queued' | 'dispatched' | 'started' | 'heartbeat' | 'retry_wait' | 'cancel_requested' | 'timed_out' | 'ambiguous' | 'running';
+    nextAttemptAt: number | null;
+    deadlineAt: number | null;
+    /** When the current attempt started executing, locally or on a worker. */
+    startedAt: number | null;
+    lastHeartbeatAt: number | null;
+    lastError: string | null;
+}
+export interface RunStartIdentity {
+    kind: string;
+    definitionName: string;
+    definitionVersion: string;
+    input: JsonValue;
+    requestedThreadId: string | null;
+    idempotencyKey: string | null;
+    rootThreadId: string;
+}
 export interface RunState {
     runId: string;
     status: RunStatus;
     rootThreadId: string | null;
+    startIdentity: RunStartIdentity | null;
     threads: {
         [threadId: string]: ThreadRecord;
     };
     waits: {
         [waitId: string]: WaitRecord;
     };
-    outstandingEffects: OutstandingEffect[];
-    completedEffectIds?: string[];
-    processedIdempotencyKeys?: string[];
+    outstandingEffects: readonly OutstandingEffect[];
+    effectExecutions: {
+        [effectId: string]: EffectExecutionRecord;
+    };
+    completedEffectIds: readonly string[];
+    processedIdempotencyKeys: readonly string[];
 }
+export declare const RunStateSchema: Schema.Struct<{
+    readonly runId: Schema.String;
+    readonly status: Schema.Union<readonly [Schema.Literal<"running">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+    readonly rootThreadId: Schema.NullOr<Schema.String>;
+    readonly startIdentity: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Struct<{
+        readonly kind: Schema.String;
+        readonly definitionName: Schema.String;
+        readonly definitionVersion: Schema.String;
+        readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly requestedThreadId: Schema.NullOr<Schema.String>;
+        readonly idempotencyKey: Schema.NullOr<Schema.String>;
+        readonly rootThreadId: Schema.String;
+    }>>, never>;
+    readonly threads: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly threadId: Schema.String;
+        readonly kind: Schema.String;
+        readonly definitionName: Schema.String;
+        readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
+        readonly parentThreadId: Schema.NullOr<Schema.String>;
+        readonly status: Schema.Union<readonly [Schema.Literal<"running">, Schema.Literal<"waiting">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+        readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly output: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly error: Schema.NullOr<Schema.String>;
+        readonly state: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>;
+    readonly waits: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly waitId: Schema.String;
+        readonly threadId: Schema.String;
+        readonly on: Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>;
+            readonly match: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>, Schema.Struct<{
+            readonly timerAt: Schema.Finite;
+        }>]>;
+        readonly tag: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>;
+    readonly outstandingEffects: Schema.$Array<Schema.Struct<{
+        readonly effectId: Schema.String;
+        readonly threadId: Schema.String;
+        readonly causingSeq: Schema.Finite;
+        readonly causingEventId: Schema.String;
+        readonly effect: Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.spawn">;
+            readonly childThreadId: Schema.String;
+            readonly kind: Schema.String;
+            readonly definitionName: Schema.String;
+            readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
+            readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.wait">;
+            readonly waitId: Schema.String;
+            readonly on: Schema.Union<readonly [Schema.Struct<{
+                readonly type: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>;
+                readonly match: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            }>, Schema.Struct<{
+                readonly timerAt: Schema.Finite;
+            }>]>;
+            readonly tag: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.emit">;
+            readonly event: Schema.Struct<{
+                readonly type: Schema.String;
+                readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+                readonly threadId: Schema.optional<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.optional<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 id: Schema.optional<Schema.String>;
+                readonly ts: Schema.optional<Schema.Finite>;
+                readonly idempotencyKey: Schema.optional<Schema.NullOr<Schema.String>>;
+            }>;
+            readonly tag: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.complete">;
+            readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.fail">;
+            readonly error: Schema.String;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.cancel">;
+            readonly threadId: Schema.String;
+            readonly tag: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.String;
+            readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly tag: Schema.optional<Schema.String>;
+        }>]>;
+    }>>;
+    readonly effectExecutions: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly effectId: Schema.String;
+        readonly attempt: Schema.Finite;
+        readonly status: Schema.Union<readonly [Schema.Literal<"queued">, Schema.Literal<"dispatched">, Schema.Literal<"started">, Schema.Literal<"heartbeat">, Schema.Literal<"retry_wait">, Schema.Literal<"cancel_requested">, Schema.Literal<"timed_out">, Schema.Literal<"ambiguous">, Schema.Literal<"running">]>;
+        readonly nextAttemptAt: Schema.NullOr<Schema.Finite>;
+        readonly deadlineAt: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Finite>, never>;
+        readonly startedAt: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Finite>, never>;
+        readonly lastHeartbeatAt: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Finite>, never>;
+        readonly lastError: Schema.NullOr<Schema.String>;
+    }>>, never>;
+    readonly completedEffectIds: Schema.withDecodingDefaultKey<Schema.$Array<Schema.String>, never>;
+    readonly processedIdempotencyKeys: Schema.withDecodingDefaultKey<Schema.$Array<Schema.String>, never>;
+}>;
 export declare function emptyRunState(runId: string): RunState;
 export declare function isRunTerminal(state: RunState): boolean;
 export declare function isRunParked(state: RunState): boolean;

package/dist/core/state.js

@@ -1,11 +1,89 @@
+import { Effect, Schema } from 'effect';
+import { RuntimeEffectSchema, WaitConditionSchema, } from './effects.js';
+import { JsonValueSchema } from './envelope.js';
+import { DEFAULT_DEFINITION_VERSION } from './module.js';
+export const RunStateSchema = Schema.Struct({
+    runId: Schema.String,
+    status: Schema.Union([
+        Schema.Literal('running'),
+        Schema.Literal('completed'),
+        Schema.Literal('failed'),
+        Schema.Literal('cancelled'),
+    ]),
+    rootThreadId: Schema.NullOr(Schema.String),
+    startIdentity: Schema.NullOr(Schema.Struct({
+        kind: Schema.String,
+        definitionName: Schema.String,
+        definitionVersion: Schema.String,
+        input: JsonValueSchema,
+        requestedThreadId: Schema.NullOr(Schema.String),
+        idempotencyKey: Schema.NullOr(Schema.String),
+        rootThreadId: Schema.String,
+    })).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+    threads: Schema.Record(Schema.String, Schema.Struct({
+        threadId: Schema.String,
+        kind: Schema.String,
+        definitionName: Schema.String,
+        definitionVersion: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION))),
+        parentThreadId: Schema.NullOr(Schema.String),
+        status: Schema.Union([
+            Schema.Literal('running'),
+            Schema.Literal('waiting'),
+            Schema.Literal('completed'),
+            Schema.Literal('failed'),
+            Schema.Literal('cancelled'),
+        ]),
+        input: JsonValueSchema,
+        output: Schema.NullOr(JsonValueSchema),
+        error: Schema.NullOr(Schema.String),
+        state: JsonValueSchema,
+    })),
+    waits: Schema.Record(Schema.String, Schema.Struct({
+        waitId: Schema.String,
+        threadId: Schema.String,
+        on: WaitConditionSchema,
+        tag: Schema.optional(JsonValueSchema),
+    })),
+    outstandingEffects: Schema.Array(Schema.Struct({
+        effectId: Schema.String,
+        threadId: Schema.String,
+        causingSeq: Schema.Finite,
+        causingEventId: Schema.String,
+        effect: RuntimeEffectSchema,
+    })),
+    effectExecutions: Schema.Record(Schema.String, Schema.Struct({
+        effectId: Schema.String,
+        attempt: Schema.Finite,
+        status: Schema.Union([
+            Schema.Literal('queued'),
+            Schema.Literal('dispatched'),
+            Schema.Literal('started'),
+            Schema.Literal('heartbeat'),
+            Schema.Literal('retry_wait'),
+            Schema.Literal('cancel_requested'),
+            Schema.Literal('timed_out'),
+            Schema.Literal('ambiguous'),
+            Schema.Literal('running'),
+        ]),
+        nextAttemptAt: Schema.NullOr(Schema.Finite),
+        deadlineAt: Schema.NullOr(Schema.Finite).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+        startedAt: Schema.NullOr(Schema.Finite).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+        lastHeartbeatAt: Schema.NullOr(Schema.Finite).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+        lastError: Schema.NullOr(Schema.String),
+    })).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+    completedEffectIds: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+    processedIdempotencyKeys: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+});
 export function emptyRunState(runId) {
     return {
         runId,
         status: 'running',
         rootThreadId: null,
+        startIdentity: null,
         threads: {},
         waits: {},
         outstandingEffects: [],
+        effectExecutions: {},
         completedEffectIds: [],
         processedIdempotencyKeys: [],
     };

package/dist/core/store.d.ts

@@ -1,5 +1,6 @@
 import { Context, Effect, Layer, Stream } from 'effect';
 import { type AppendableEvent, type EventEnvelope } from './envelope';
+import { EventPayloadTooLargeError } from './limits';
 declare const EventStoreError_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: "EventStoreError";
 } & Readonly<A>;
@@ -59,8 +60,31 @@ export declare class EventStoreFencedError extends EventStoreFencedError_base<{
 }> {
     constructor(runId: string, token: string);
 }
-export type EventStoreAppendError = EventStoreError | EventStoreConflictError | EventStoreFencedError;
-export type AnyEventStoreError = EventStoreError | EventStoreConflictError | EventStoreTruncationError | EventStoreTrimmedError | EventStoreFencedError;
+declare const UnsafeEventStoreTrimError_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: "UnsafeEventStoreTrimError";
+} & Readonly<A>;
+export declare class UnsafeEventStoreTrimError extends UnsafeEventStoreTrimError_base<{
+    readonly runId: string;
+    readonly trimThrough: number;
+    readonly message: string;
+}> {
+    constructor(runId: string, trimThrough: number);
+}
+export type EventStoreTrimCoverage = {
+    /** Durable archive contains every event through this sequence. */
+    readonly archiveCursor: number;
+    readonly requiredProjectors?: never;
+    readonly projectorCursors?: never;
+} | {
+    readonly archiveCursor?: never;
+    /** Authoritative identities of every projector required before trimming. */
+    readonly requiredProjectors: readonly string[];
+    /** Durable checkpoint by projector identity. Every required projector must be present. */
+    readonly projectorCursors: Readonly<Record<string, number>>;
+};
+export declare function trimEventStoreSafely(store: EventStore, runId: string, beforeSeq: number, coverage: EventStoreTrimCoverage): Effect.Effect<void, EventStoreError | UnsafeEventStoreTrimError>;
+export type EventStoreAppendError = EventStoreError | EventStoreConflictError | EventStoreFencedError | EventPayloadTooLargeError;
+export type AnyEventStoreError = EventStoreError | EventStoreConflictError | EventStoreTruncationError | EventStoreTrimmedError | EventStoreFencedError | EventPayloadTooLargeError;
 export declare function isEventStoreError(err: unknown): err is AnyEventStoreError;
 export interface StreamBounds {
     readonly head: number;
@@ -68,6 +92,16 @@ export interface StreamBounds {
 }
 export interface AppendOptions {
     readonly expectedTail?: number;
+    /**
+     * Atomically claims an ingress command with the append. Reusing the key
+     * returns a deduplicated result without appending events. Stores without a
+     * command table may ignore this; callers must pair it with `expectedTail`
+     * so a retried command conflicts instead of appending twice.
+     */
+    readonly idempotency?: {
+        readonly key: string;
+        readonly fingerprint?: string;
+    };
     /** Set the stream fencing token atomically in this batch (`''` clears). */
     readonly fence?: string;
     /** Must match the stream's current fencing token, or the append fails. */
@@ -92,6 +126,7 @@ export declare function paginatePages<T, SCursor, E = never, R = never>(options:
 export interface AppendResult {
     sequences: number[];
     tail: number;
+    deduplicated?: boolean;
 }
 export interface EventStore {
     readonly append: (runId: string, events: ReadonlyArray<AppendableEvent>, options?: AppendOptions) => Effect.Effect<AppendResult, EventStoreAppendError>;
@@ -128,7 +163,7 @@ export interface EventStore {
     readonly subscribe: (runId: string, options?: {
         fromSeq?: number;
     }) => Stream.Stream<EventEnvelope, EventStoreError>;
-    readonly listRuns: () => Effect.Effect<string[], EventStoreError>;
+    readonly listRuns: Effect.Effect<string[], EventStoreError>;
 }
 /**
  * Utility to read an EventStore as a Stream.Stream, using `store.readStream` if implemented