@swirls/looms 0.1.0 → 0.3.0

package/dist/core/fork.js

@@ -0,0 +1,129 @@
+import { Data, Effect, Predicate } from 'effect';
+import { isPrimitiveEffect, isWithdrawnError, } from './effects.js';
+import { createEvent } from './envelope.js';
+import { foldEvent, foldRun } from './fold.js';
+import { emptyRunState, isRunTerminal } from './state.js';
+import { isTerminalStatus } from './thread.js';
+export class ForkSourceError extends Data.TaggedError('ForkSourceError') {
+    constructor(runId, message) {
+        super({ runId, message });
+        this.name = 'ForkSourceError';
+    }
+}
+function payloadThreadId(event) {
+    const threadId = Predicate.isObject(event.payload) ? event.payload.threadId : undefined;
+    return Predicate.isString(threadId) ? threadId : event.threadId;
+}
+function rootTerminal(state) {
+    const root = state.rootThreadId ? state.threads[state.rootThreadId] : undefined;
+    return isRunTerminal(state) || (root !== undefined && isTerminalStatus(root.status));
+}
+/** Where the cancellation that wrote `event` began, when it recorded that; a seq is an index + 1. */
+function cancellationStart(event) {
+    const resumeSeq = event.type === 'runtime.thread.cancelled' && Predicate.isObject(event.payload)
+        ? event.payload.resumeSeq
+        : undefined;
+    return Predicate.isNumber(resumeSeq) ? resumeSeq : undefined;
+}
+/**
+ * Fold the source until its root thread ends. Everything from that event on is how the run
+ * finished, so the fork leaves it out; a cancellation that recorded where it began is left
+ * out from there.
+ */
+function scanSource(events, registry) {
+    const effects = new Map();
+    const failedAt = new Map();
+    let state = emptyRunState(events[0]?.runId ?? '');
+    for (const [index, event] of events.entries()) {
+        state = foldEvent(state, event, registry);
+        for (const item of state.outstandingEffects) {
+            effects.set(item.effectId, item.effect);
+        }
+        for (const record of Object.values(state.threads)) {
+            if (record.status === 'failed' && !failedAt.has(record.threadId)) {
+                failedAt.set(record.threadId, index);
+            }
+        }
+        if (rootTerminal(state)) {
+            const root = state.rootThreadId ? state.threads[state.rootThreadId] : undefined;
+            const rootFailed = root?.status === 'failed' || state.status === 'failed';
+            return { cut: cancellationStart(event) ?? index, effects, failedAt, rootFailed };
+        }
+    }
+    return { cut: events.length, effects, failedAt, rootFailed: false };
+}
+/**
+ * Walk back from the root's failure to the effect outcome that started it, so the fork
+ * re-issues that effect instead of replaying a failure the modules already folded in.
+ */
+function failureOrigin(events, scan, registry) {
+    const indexById = new Map(events.map((event, index) => [event.id, index]));
+    /** A failed thread leads back to where the fold failed it, anything else to its cause. */
+    const previous = (index) => {
+        const event = events[index];
+        const threadId = event.type === 'runtime.thread.failed' ? payloadThreadId(event) : null;
+        const failedAt = threadId ? scan.failedAt.get(threadId) : undefined;
+        const cause = event.causationId ? indexById.get(event.causationId) : undefined;
+        const next = failedAt !== undefined && failedAt < index ? failedAt : cause;
+        return next !== undefined && next < index ? next : undefined;
+    };
+    for (let index = scan.cut; index !== undefined; index = previous(index)) {
+        const event = events[index];
+        const effect = event.effectId ? scan.effects.get(event.effectId) : undefined;
+        const error = Predicate.isObject(event.payload) ? event.payload.error : undefined;
+        const withdrawn = Predicate.isString(error) && isWithdrawnError(error);
+        if (effect &&
+            !isPrimitiveEffect(effect) &&
+            !registry.effects.get(effect.type)?.deterministic &&
+            !withdrawn) {
+            return index;
+        }
+    }
+    return scan.cut;
+}
+function copyEvent(event, runId, reissued) {
+    if (event.ephemeral && event.effectId && reissued.has(event.effectId)) {
+        return { ...event, runId, type: 'runtime.fork.elided', payload: { type: event.type } };
+    }
+    if (event.type === 'runtime.snapshot.taken' && Predicate.isObject(event.payload)) {
+        const { state: _state, ...pointer } = event.payload;
+        return { ...event, runId, payload: pointer };
+    }
+    if (event.type === 'runtime.run.started') {
+        return { ...event, runId, idempotencyKey: null };
+    }
+    return { ...event, runId };
+}
+/**
+ * Plan a new run that continues where the source run ended. The fork copies the source's
+ * history up to the point the run finished, keeping sequence numbers so effect ids still
+ * line up, and its next wake re-issues whatever effects were outstanding there.
+ */
+export function planFork(input) {
+    const { sourceRunId, runId, events, registry } = input;
+    if (events.length === 0) {
+        return Effect.fail(new ForkSourceError(sourceRunId, `Run "${sourceRunId}" has no events`));
+    }
+    if (events.some((event, index) => event.seq !== index + 1)) {
+        return Effect.fail(new ForkSourceError(sourceRunId, `Run "${sourceRunId}" does not have its full history from seq 1; it cannot be forked`));
+    }
+    const scan = scanSource(events, registry);
+    const cut = scan.rootFailed ? failureOrigin(events, scan, registry) : scan.cut;
+    const prefix = events.slice(0, cut);
+    const atCut = foldRun(prefix, registry, { runId });
+    if (!atCut.rootThreadId) {
+        return Effect.fail(new ForkSourceError(sourceRunId, `Run "${sourceRunId}" never started a root thread`));
+    }
+    const reissued = new Set(atCut.outstandingEffects.map((item) => item.effectId));
+    const marker = createEvent(runId, {
+        type: 'runtime.run.forked',
+        payload: { sourceRunId, sourceSeq: cut },
+        threadId: null,
+        origin: { type: 'system' },
+    }, { seq: cut + 1 });
+    return Effect.succeed({
+        events: [...prefix.map((event) => copyEvent(event, runId, reissued)), marker],
+        sourceSeq: cut,
+        rootThreadId: atCut.rootThreadId,
+    });
+}

package/dist/core/index.d.ts

@@ -13,6 +13,7 @@ export * from './state';
 export * from './match';
 export * from './fold';
 export * from './replay';
+export * from './fork';
 export * from './projection';
 export * from './module';
 export * from './kind';
@@ -28,3 +29,5 @@ export * from './coalesce';
 export * from './event-index';
 export * from './limits';
 export * from './definition-store';
+export * from './published';
+export type { DebuggerHost, DebuggerRequest } from './debugger-host';

package/dist/core/index.js

@@ -12,6 +12,7 @@ export * from './state.js';
 export * from './match.js';
 export * from './fold.js';
 export * from './replay.js';
+export * from './fork.js';
 export * from './projection.js';
 export * from './module.js';
 export * from './kind.js';
@@ -27,3 +28,4 @@ export * from './coalesce.js';
 export * from './event-index.js';
 export * from './limits.js';
 export * from './definition-store.js';
+export * from './published.js';

package/dist/core/module-scope.d.ts

@@ -65,6 +65,7 @@ export interface ModuleScope<TNamespace extends string, U extends EventEnvelope<
         input?: TSchema;
         retry?: RetryPolicy;
         execution?: EffectExecution;
+        deterministic?: boolean;
         execute?: (input: TInput, ctx: ScopedEffectContext<EventInputOf<U>>) => EffectHandlerResult<R, EventInputOf<U>, HandlerError>;
     }): NoInfer<EffectDefinition<TInput, R, EventInputOf<U>>>;
     input<K extends keyof (TEvents extends EventCatalog<any, infer E> ? E : never) & string>(key: K, payload: InferPayload<(TEvents extends EventCatalog<any, infer E> ? E : never)[K]>, meta?: Omit<EventInput, 'type' | 'payload'>): Omit<EventInput, 'type' | 'payload'> & {

package/dist/core/module.d.ts

@@ -10,8 +10,8 @@ export type NextEffectHandler = (effect: RuntimeEffect, ctx: EffectContext) => E
 export type EffectMiddleware = (effect: RuntimeEffect, ctx: EffectContext, next: NextEffectHandler) => Effect.Effect<ReadonlyArray<EventInput>, Error>;
 /**
  * Names the threads whose in-process effects an admitted signal event interrupts, so a running
- * effect (such as a model call) can stop early. Return an empty array when the event interrupts
- * nothing.
+ * effect (such as a model call) can stop early. The runtime also interrupts each named thread's
+ * descendants. Return an empty array when the event interrupts nothing.
  */
 export type SignalInterruptRule = (event: EventInput) => readonly string[];
 export interface RuntimeModuleDependency {
@@ -24,6 +24,7 @@ export interface DefinitionRef {
     readonly name: string;
     readonly version?: string;
     readonly input?: SchemaInput | undefined;
+    readonly description?: string | undefined;
 }
 export declare const DEFAULT_DEFINITION_VERSION = "v1";
 export declare function definitionKey(kind: string, name: string, version: string): string;
@@ -33,6 +34,7 @@ export interface RegisteredDefinition {
     readonly name: string;
     readonly version: string;
     readonly input?: SchemaInput | undefined;
+    readonly description?: string | undefined;
     readonly value: DefinitionRef;
 }
 /**

package/dist/core/projection.js

@@ -174,6 +174,7 @@ export function toThreadTree(state) {
         status: 'running',
         rootThreadId: state.rootThreadId,
         startIdentity: null,
+        forkedFrom: null,
         threads: state.records,
         waits: {},
         outstandingEffects: [],

package/dist/core/protocol.d.ts

@@ -17,6 +17,13 @@ export declare const protocolCatalog: import("./catalog").EventCatalog<"runtime"
     'run.cancelled': Schema.Struct<{
         readonly reason: Schema.optional<Schema.String>;
     }>;
+    'run.forked': Schema.Struct<{
+        readonly sourceRunId: Schema.String;
+        readonly sourceSeq: Schema.Finite;
+    }>;
+    'fork.elided': Schema.Struct<{
+        readonly type: Schema.String;
+    }>;
     'thread.started': Schema.Struct<{
         readonly threadId: Schema.String;
         readonly kind: Schema.String;
@@ -36,6 +43,8 @@ export declare const protocolCatalog: import("./catalog").EventCatalog<"runtime"
     'thread.cancelled': Schema.Struct<{
         readonly threadId: Schema.String;
         readonly reason: Schema.optional<Schema.String>;
+        /** The run's last seq before this cancellation began; a fork of the run resumes there. */
+        readonly resumeSeq: Schema.optional<Schema.Finite>;
     }>;
     'thread.cancel.requested': Schema.Struct<{
         readonly threadId: Schema.String;
@@ -138,7 +147,7 @@ export declare const protocolCatalog: import("./catalog").EventCatalog<"runtime"
 }>;
 export type ProtocolEvent = EventsOfCatalog<typeof protocolCatalog>;
 export type ProtocolEventInput = EventInputOf<typeof protocolCatalog>;
-export declare const PROTOCOL_TYPES: readonly ['runtime.run.started', 'runtime.run.completed', 'runtime.run.cancelled', 'runtime.thread.started', 'runtime.thread.completed', 'runtime.thread.failed', 'runtime.thread.cancelled', 'runtime.thread.cancel.requested', 'runtime.wait.registered', 'runtime.wait.satisfied', 'runtime.timer.set', 'runtime.timer.fired', 'runtime.effect.failed', 'runtime.effect.attempt.started', 'runtime.effect.queued', 'runtime.effect.dispatched', 'runtime.effect.worker.started', 'runtime.effect.heartbeat', 'runtime.effect.cancel.requested', 'runtime.effect.cancelled', 'runtime.effect.completed', 'runtime.effect.timed_out', 'runtime.effect.ambiguous', 'runtime.effect.retry.scheduled', 'runtime.snapshot.taken', 'runtime.signal.received'];
+export declare const PROTOCOL_TYPES: readonly ['runtime.run.started', 'runtime.run.completed', 'runtime.run.cancelled', 'runtime.run.forked', 'runtime.fork.elided', 'runtime.thread.started', 'runtime.thread.completed', 'runtime.thread.failed', 'runtime.thread.cancelled', 'runtime.thread.cancel.requested', 'runtime.wait.registered', 'runtime.wait.satisfied', 'runtime.timer.set', 'runtime.timer.fired', 'runtime.effect.failed', 'runtime.effect.attempt.started', 'runtime.effect.queued', 'runtime.effect.dispatched', 'runtime.effect.worker.started', 'runtime.effect.heartbeat', 'runtime.effect.cancel.requested', 'runtime.effect.cancelled', 'runtime.effect.completed', 'runtime.effect.timed_out', 'runtime.effect.ambiguous', 'runtime.effect.retry.scheduled', 'runtime.snapshot.taken', 'runtime.signal.received'];
 export type ProtocolEventType = (typeof PROTOCOL_TYPES)[number];
 export declare function isProtocolType(type: string): type is ProtocolEventType;
 export type RunStartedPayload = Schema.Schema.Type<(typeof protocolCatalog.entries)['run.started']>;

package/dist/core/protocol.js

@@ -20,6 +20,13 @@ export const protocolCatalog = defineEventCatalog('runtime', {
     'run.cancelled': Schema.Struct({
         reason: Schema.optional(Schema.String),
     }),
+    'run.forked': Schema.Struct({
+        sourceRunId: Schema.String,
+        sourceSeq: Schema.Finite,
+    }),
+    'fork.elided': Schema.Struct({
+        type: Schema.String,
+    }),
     'thread.started': Schema.Struct({
         threadId: Schema.String,
         kind: Schema.String,
@@ -39,6 +46,8 @@ export const protocolCatalog = defineEventCatalog('runtime', {
     'thread.cancelled': Schema.Struct({
         threadId: Schema.String,
         reason: Schema.optional(Schema.String),
+        /** The run's last seq before this cancellation began; a fork of the run resumes there. */
+        resumeSeq: Schema.optional(Schema.Finite),
     }),
     'thread.cancel.requested': Schema.Struct({
         threadId: Schema.String,
@@ -138,6 +147,8 @@ export const PROTOCOL_TYPES = [
     'runtime.run.started',
     'runtime.run.completed',
     'runtime.run.cancelled',
+    'runtime.run.forked',
+    'runtime.fork.elided',
     'runtime.thread.started',
     'runtime.thread.completed',
     'runtime.thread.failed',

package/dist/core/published.d.ts

@@ -0,0 +1,43 @@
+import { Schema } from 'effect';
+import type { RegisteredDefinition } from './module';
+import { type RunState } from './state';
+/** A registered definition as `GET /definitions` publishes it. */
+export declare const PublishedDefinitionSchema: Schema.Struct<{
+    readonly kind: Schema.String;
+    readonly name: Schema.String;
+    readonly version: Schema.String;
+    readonly description: Schema.optional<Schema.String>;
+    /** JSON Schema derived from the definition's `input`. */
+    readonly inputSchema: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export type PublishedDefinition = Schema.Schema.Type<typeof PublishedDefinitionSchema>;
+export declare const DefinitionCatalogSchema: Schema.Struct<{
+    readonly definitions: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.String;
+        readonly name: Schema.String;
+        readonly version: Schema.String;
+        readonly description: Schema.optional<Schema.String>;
+        /** JSON Schema derived from the definition's `input`. */
+        readonly inputSchema: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>;
+    readonly projections: Schema.$Array<Schema.String>;
+}>;
+export type DefinitionCatalog = Schema.Schema.Type<typeof DefinitionCatalogSchema>;
+export declare function publishDefinition(definition: RegisteredDefinition): PublishedDefinition;
+/** A run as `GET /runs/summaries` lists it. */
+export declare const RunSummarySchema: Schema.Struct<{
+    readonly runId: Schema.String;
+    readonly status: Schema.Union<readonly [Schema.Literal<"running">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+    readonly kind: Schema.NullOr<Schema.String>;
+    readonly definitionName: Schema.NullOr<Schema.String>;
+}>;
+export type RunSummary = Schema.Schema.Type<typeof RunSummarySchema>;
+export declare function summarizeRun(state: RunState): RunSummary;
+export declare const RunSummariesSchema: Schema.Struct<{
+    readonly runs: Schema.$Array<Schema.Struct<{
+        readonly runId: Schema.String;
+        readonly status: Schema.Union<readonly [Schema.Literal<"running">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+        readonly kind: Schema.NullOr<Schema.String>;
+        readonly definitionName: Schema.NullOr<Schema.String>;
+    }>>;
+}>;

package/dist/core/published.js

@@ -0,0 +1,44 @@
+import { Schema } from 'effect';
+import { JsonValueSchema } from './envelope.js';
+import { jsonSchemaOfInput } from './schema.js';
+import { RunStateSchema } from './state.js';
+/** A registered definition as `GET /definitions` publishes it. */
+export const PublishedDefinitionSchema = Schema.Struct({
+    kind: Schema.String,
+    name: Schema.String,
+    version: Schema.String,
+    description: Schema.optional(Schema.String),
+    /** JSON Schema derived from the definition's `input`. */
+    inputSchema: Schema.optional(JsonValueSchema),
+});
+export const DefinitionCatalogSchema = Schema.Struct({
+    definitions: Schema.Array(PublishedDefinitionSchema),
+    projections: Schema.Array(Schema.String),
+});
+export function publishDefinition(definition) {
+    return {
+        kind: definition.kind,
+        name: definition.name,
+        version: definition.version,
+        description: definition.description,
+        inputSchema: jsonSchemaOfInput(definition.input),
+    };
+}
+/** A run as `GET /runs/summaries` lists it. */
+export const RunSummarySchema = Schema.Struct({
+    runId: Schema.String,
+    status: RunStateSchema.fields.status,
+    kind: Schema.NullOr(Schema.String),
+    definitionName: Schema.NullOr(Schema.String),
+});
+export function summarizeRun(state) {
+    return {
+        runId: state.runId,
+        status: state.status,
+        kind: state.startIdentity?.kind ?? null,
+        definitionName: state.startIdentity?.definitionName ?? null,
+    };
+}
+export const RunSummariesSchema = Schema.Struct({
+    runs: Schema.Array(RunSummarySchema),
+});

package/dist/core/replay.d.ts

@@ -49,6 +49,10 @@ export declare const ReplayStepSchema: Schema.Struct<{
             readonly idempotencyKey: Schema.NullOr<Schema.String>;
             readonly rootThreadId: Schema.String;
         }>>, never>;
+        readonly forkedFrom: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Struct<{
+            readonly runId: Schema.String;
+            readonly seq: Schema.Finite;
+        }>>, never>;
         readonly threads: Schema.$Record<Schema.String, Schema.Struct<{
             readonly threadId: Schema.String;
             readonly kind: Schema.String;
@@ -161,6 +165,10 @@ export declare const ReplayStepSchema: Schema.Struct<{
             readonly idempotencyKey: Schema.NullOr<Schema.String>;
             readonly rootThreadId: Schema.String;
         }>>, never>;
+        readonly forkedFrom: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Struct<{
+            readonly runId: Schema.String;
+            readonly seq: Schema.Finite;
+        }>>, never>;
         readonly threads: Schema.$Record<Schema.String, Schema.Struct<{
             readonly threadId: Schema.String;
             readonly kind: Schema.String;

package/dist/core/schema.d.ts

@@ -1,6 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { Effect, Schema } from 'effect';
-import type { JsonValue } from './types';
+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>;
@@ -21,4 +21,6 @@ export declare function validateInput<TSchema extends SchemaInput>(schema: TSche
 export declare function validateInput(schema: null | undefined, raw: JsonValue): Promise<JsonValue>;
 export declare function validateInputSync<TSchema extends SchemaInput>(schema: TSchema, raw: JsonValue): InferSchemaOutput<TSchema>;
 export declare function validateInputSync(schema: null | undefined, raw: JsonValue): JsonValue;
+/** JSON Schema for a definition input, when the schema can describe itself. */
+export declare function jsonSchemaOfInput(input: SchemaInput | null | undefined): JsonValue | undefined;
 export {};

package/dist/core/schema.js

@@ -1,4 +1,5 @@
 import { Data, Effect, Predicate, Schema } from 'effect';
+import { isJsonObject } from './types.js';
 export class InvalidInputError extends Data.TaggedError('InvalidInputError') {
     issues;
     constructor(text, issues = []) {
@@ -73,3 +74,40 @@ export function validateInputSync(schema, raw) {
     }
     return result.value;
 }
+function isStandardJsonSchemaHolder(value) {
+    return '~standard' in value;
+}
+function jsonSchemaFromHolder(value) {
+    if (!isStandardJsonSchemaHolder(value)) {
+        return undefined;
+    }
+    const input = value['~standard'].jsonSchema?.input;
+    if (!input) {
+        return undefined;
+    }
+    try {
+        const schema = input({ target: 'draft-2020-12' });
+        return isJsonObject(schema) ? schema : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** JSON Schema for a definition input, when the schema can describe itself. */
+export function jsonSchemaOfInput(input) {
+    if (!input) {
+        return undefined;
+    }
+    if (isStandardSchema(input)) {
+        return jsonSchemaFromHolder(input);
+    }
+    if (!Schema.isSchema(input)) {
+        return undefined;
+    }
+    try {
+        return jsonSchemaFromHolder(Schema.toStandardJSONSchemaV1(input));
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -1,5 +1,6 @@
 import { Context, Effect, Option } from 'effect';
 import { SnapshotPayloadTooLargeError } from './limits';
+import type { RunSummary } from './published';
 import type { RunState } from './state';
 import type { EventStore } from './store';
 /**
@@ -29,6 +30,9 @@ export interface SnapshotStore {
     readonly save: (snapshot: RunSnapshot) => Effect.Effect<void, SnapshotStoreError | SnapshotPayloadTooLargeError>;
     readonly listCursors?: (runId: string) => Effect.Effect<number[], SnapshotStoreError>;
     readonly prune?: (runId: string, keepLatest: number) => Effect.Effect<void, SnapshotStoreError>;
+    /** Upsert the list-row for a run. Written where the cursor already advanced. */
+    readonly saveHeader: (header: RunSummary) => Effect.Effect<void, SnapshotStoreError>;
+    readonly listHeaders: Effect.Effect<readonly RunSummary[], SnapshotStoreError>;
 }
 declare const SnapshotStoreTag_base: Context.ServiceClass<SnapshotStoreTag, "looms/SnapshotStore", SnapshotStore>;
 export declare class SnapshotStoreTag extends SnapshotStoreTag_base {

package/dist/core/snapshot-store.js

@@ -21,6 +21,7 @@ export function snapshotStoreOf(store) {
 }
 export const makeMemorySnapshotStore = Effect.gen(function* () {
     const snapshots = yield* Ref.make(new Map());
+    const headers = yield* Ref.make(new Map());
     const service = {
         loadLatest: (runId) => Effect.gen(function* () {
             const map = yield* Ref.get(snapshots);
@@ -54,6 +55,12 @@ export const makeMemorySnapshotStore = Effect.gen(function* () {
             next.set(runId, list.slice(list.length - keepLatest));
             return next;
         }),
+        saveHeader: (header) => Ref.update(headers, (map) => {
+            const next = new Map(map);
+            next.set(header.runId, header);
+            return next;
+        }),
+        listHeaders: Ref.get(headers).pipe(Effect.map((map) => [...map.values()])),
     };
     return service;
 });

package/dist/core/snapshots.js

@@ -21,14 +21,7 @@ export function shouldTakeSnapshot(events, every = DEFAULT_SNAPSHOT_EVERY) {
     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 lastSnap = events.findLast((e) => e.type === 'runtime.snapshot.taken');
     const since = lastSnap ? durable.filter((e) => e.seq > lastSnap.seq).length : durable.length;
     return since >= every;
 }
@@ -66,17 +59,10 @@ export function buildSnapshotMarker(runId, cursor, stateHash, options) {
 }
 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) {
+    const snap = events.findLast((e) => e.type === 'runtime.snapshot.taken');
+    if (!snap) {
         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);

package/dist/core/sqlite-store.js

@@ -35,6 +35,13 @@ CREATE TABLE IF NOT EXISTS looms_commands (
   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,
@@ -124,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({
@@ -175,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) {

package/dist/core/state.d.ts

@@ -46,11 +46,17 @@ export interface RunStartIdentity {
     idempotencyKey: string | null;
     rootThreadId: string;
 }
+/** The run and last sequence a fork copied its history from. */
+export interface RunForkSource {
+    runId: string;
+    seq: number;
+}
 export interface RunState {
     runId: string;
     status: RunStatus;
     rootThreadId: string | null;
     startIdentity: RunStartIdentity | null;
+    forkedFrom: RunForkSource | null;
     threads: {
         [threadId: string]: ThreadRecord;
     };
@@ -77,6 +83,10 @@ export declare const RunStateSchema: Schema.Struct<{
         readonly idempotencyKey: Schema.NullOr<Schema.String>;
         readonly rootThreadId: Schema.String;
     }>>, never>;
+    readonly forkedFrom: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.Struct<{
+        readonly runId: Schema.String;
+        readonly seq: Schema.Finite;
+    }>>, never>;
     readonly threads: Schema.$Record<Schema.String, Schema.Struct<{
         readonly threadId: Schema.String;
         readonly kind: Schema.String;
@@ -178,4 +188,8 @@ export declare const RunStateSchema: Schema.Struct<{
 }>;
 export declare function emptyRunState(runId: string): RunState;
 export declare function isRunTerminal(state: RunState): boolean;
+/** Every thread below `threadId`, in the order they were started. */
+export declare function descendantThreadIds(state: RunState, threadId: string): string[];
+/** The status a `runtime.run.completed` payload ends the run with: an error means it failed. */
+export declare function completedRunStatus(payload: JsonValue): 'completed' | 'failed';
 export declare function isRunParked(state: RunState): boolean;