@swirls/looms 0.2.0 → 0.3.0

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';

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 {

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/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/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/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;

package/dist/core/state.js

@@ -1,7 +1,8 @@
-import { Effect, Schema } from 'effect';
+import { Effect, Predicate, Schema } from 'effect';
 import { RuntimeEffectSchema, WaitConditionSchema, } from './effects.js';
 import { JsonValueSchema } from './envelope.js';
 import { DEFAULT_DEFINITION_VERSION } from './module.js';
+import { isTerminalStatus } from './thread.js';
 export const RunStateSchema = Schema.Struct({
     runId: Schema.String,
     status: Schema.Union([
@@ -20,6 +21,7 @@ export const RunStateSchema = Schema.Struct({
         idempotencyKey: Schema.NullOr(Schema.String),
         rootThreadId: Schema.String,
     })).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+    forkedFrom: Schema.NullOr(Schema.Struct({ runId: Schema.String, seq: Schema.Finite })).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
     threads: Schema.Record(Schema.String, Schema.Struct({
         threadId: Schema.String,
         kind: Schema.String,
@@ -80,6 +82,7 @@ export function emptyRunState(runId) {
         status: 'running',
         rootThreadId: null,
         startIdentity: null,
+        forkedFrom: null,
         threads: {},
         waits: {},
         outstandingEffects: [],
@@ -89,7 +92,27 @@ export function emptyRunState(runId) {
     };
 }
 export function isRunTerminal(state) {
-    return state.status === 'completed' || state.status === 'failed' || state.status === 'cancelled';
+    return isTerminalStatus(state.status);
+}
+/** Every thread below `threadId`, in the order they were started. */
+export function descendantThreadIds(state, threadId) {
+    return Object.values(state.threads)
+        .filter((record) => {
+        let parentThreadId = record.parentThreadId;
+        while (parentThreadId) {
+            if (parentThreadId === threadId) {
+                return true;
+            }
+            parentThreadId = state.threads[parentThreadId]?.parentThreadId ?? null;
+        }
+        return false;
+    })
+        .map((record) => record.threadId);
+}
+/** The status a `runtime.run.completed` payload ends the run with: an error means it failed. */
+export function completedRunStatus(payload) {
+    const error = Predicate.isObject(payload) ? payload.error : undefined;
+    return Predicate.isString(error) && error.length > 0 ? 'failed' : 'completed';
 }
 export function isRunParked(state) {
     if (isRunTerminal(state)) {

package/dist/core/store.d.ts

@@ -91,6 +91,7 @@ export interface StreamBounds {
     readonly tail: number;
 }
 export interface AppendOptions {
+    /** Fail unless the stream is at this tail. The batch is numbered from `expectedTail + 1`. */
     readonly expectedTail?: number;
     /**
      * Atomically claims an ingress command with the append. Reusing the key