@swirls/looms 0.3.0 → 0.5.0

package/dist/core/launcher.d.ts

@@ -0,0 +1,97 @@
+import { Context, Effect, Schema } from 'effect';
+import type { EventInput } from './envelope';
+import type { RunAttributes, SecretContext } from './run-context';
+import type { TraceContext } from './trace';
+import type { JsonValue, RunStatus } from './types';
+export declare const ChildCloseSchema: Schema.Union<readonly [Schema.Literal<"terminate">, Schema.Literal<"wait">]>;
+export type ChildClose = Schema.Schema.Type<typeof ChildCloseSchema>;
+/** The effect that launched a run, recorded on the launched run's `runtime.run.started`. */
+export declare const RunLaunchSourceSchema: Schema.Struct<{
+    readonly runId: Schema.String;
+    readonly threadId: Schema.String;
+    readonly effectId: Schema.String;
+    /** The event in `runId` that requested the launching effect. */
+    readonly causationId: Schema.String;
+    readonly causationSeq: Schema.Finite;
+}>;
+export type RunLaunchSource = Schema.Schema.Type<typeof RunLaunchSourceSchema>;
+export declare function readRunLaunchSource(value: JsonValue | undefined): RunLaunchSource | null;
+/** Arguments for starting a run without waiting for it to finish. */
+export interface LaunchRunArgs {
+    readonly runId?: string;
+    readonly kind: string;
+    readonly definitionName: string;
+    readonly definitionVersion?: string;
+    readonly input?: JsonValue;
+    readonly threadId?: string;
+    readonly idempotencyKey?: string;
+    /** Set by the runtime when an effect launches. A value passed by the effect is replaced. */
+    readonly launchedBy?: RunLaunchSource;
+    /**
+     * Groups runs launched from the same root run. The runtime sets it to the launching run's
+     * correlation id, or to the launching run's id when that run has none.
+     */
+    readonly correlationId?: string;
+    /**
+     * What the launching run does with this child when the launching run closes.
+     * `terminate` cancels the child. `wait` lets the child finish cancelling first.
+     */
+    readonly close?: ChildClose;
+    readonly attributes?: RunAttributes;
+    readonly secrets?: SecretContext;
+    /** Defaults to the launching run's trace context. */
+    readonly trace?: TraceContext;
+}
+/** Enough of a run to decide whether a previous fire is still in progress. */
+export interface RunStatusSnapshot {
+    readonly status: RunStatus;
+}
+/**
+ * Starts runs and reads their status from inside an effect. A single-store host launches into its
+ * own runtime. An actor host launches into the cell that owns `runId`.
+ */
+export interface RunLauncher {
+    readonly launch: (args: LaunchRunArgs) => Effect.Effect<void, Error>;
+    readonly status: (runId: string) => Effect.Effect<RunStatusSnapshot | null, Error>;
+    /**
+     * Append events to a run and wake it. When that run is already waking, the wake coalesces
+     * instead of waiting, so a child can notify its parent from inside the parent's wake.
+     */
+    readonly signal: (runId: string, events: readonly EventInput[], options?: {
+        readonly idempotencyKey?: string;
+    }) => Effect.Effect<void, Error>;
+    readonly cancel: (runId: string) => Effect.Effect<void, Error>;
+}
+declare const RunLauncherTag_base: Context.ServiceClass<RunLauncherTag, "looms/RunLauncher", RunLauncher>;
+export declare class RunLauncherTag extends RunLauncherTag_base {
+}
+declare const RunLauncherError_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: "RunLauncherError";
+} & Readonly<A>;
+export declare class RunLauncherError extends RunLauncherError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+export declare function runLauncherError(cause: unknown): RunLauncherError;
+declare const RunLauncherUnavailableError_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: "RunLauncherUnavailableError";
+} & Readonly<A>;
+export declare class RunLauncherUnavailableError extends RunLauncherUnavailableError_base<{
+    readonly message: string;
+}> {
+    constructor();
+}
+/** Fails both operations. Actor cells and Durable Objects use this unless a launcher is configured. */
+export declare const unavailableRunLauncher: RunLauncher;
+/** Adapts a per-`runId` RPC or cell lookup into a `RunLauncher`. */
+export declare function createRemoteRunLauncher(target: {
+    readonly launch: (runId: string, args: LaunchRunArgs) => Promise<void>;
+    readonly status: (runId: string) => Promise<RunStatusSnapshot | null>;
+    readonly accept: (runId: string, events: readonly EventInput[], options?: {
+        readonly idempotencyKey?: string;
+        readonly coalesce?: boolean;
+    }) => Promise<void>;
+    readonly cancel: (runId: string) => Promise<void>;
+}): RunLauncher;
+export {};

package/dist/core/launcher.js

@@ -0,0 +1,67 @@
+import { Context, Data, Effect, Option, Schema } from 'effect';
+export const ChildCloseSchema = Schema.Union([Schema.Literal('terminate'), Schema.Literal('wait')]);
+/** The effect that launched a run, recorded on the launched run's `runtime.run.started`. */
+export const RunLaunchSourceSchema = Schema.Struct({
+    runId: Schema.String,
+    threadId: Schema.String,
+    effectId: Schema.String,
+    /** The event in `runId` that requested the launching effect. */
+    causationId: Schema.String,
+    causationSeq: Schema.Finite,
+});
+const decodeRunLaunchSource = Schema.decodeUnknownOption(RunLaunchSourceSchema);
+export function readRunLaunchSource(value) {
+    return value === undefined ? null : Option.getOrNull(decodeRunLaunchSource(value));
+}
+export class RunLauncherTag extends Context.Service()('looms/RunLauncher') {
+}
+export class RunLauncherError extends Data.TaggedError('RunLauncherError') {
+}
+export function runLauncherError(cause) {
+    return new RunLauncherError({
+        message: cause instanceof Error ? cause.message : String(cause),
+        cause,
+    });
+}
+export class RunLauncherUnavailableError extends Data.TaggedError('RunLauncherUnavailableError') {
+    constructor() {
+        super({
+            message: 'No RunLauncher is configured. Pass launcher when hosting schedules in an actor cell or Durable Object.',
+        });
+        this.name = 'RunLauncherUnavailableError';
+    }
+}
+/** Fails both operations. Actor cells and Durable Objects use this unless a launcher is configured. */
+export const unavailableRunLauncher = {
+    launch: () => Effect.fail(new RunLauncherUnavailableError()),
+    status: () => Effect.fail(new RunLauncherUnavailableError()),
+    signal: () => Effect.fail(new RunLauncherUnavailableError()),
+    cancel: () => Effect.fail(new RunLauncherUnavailableError()),
+};
+/** Adapts a per-`runId` RPC or cell lookup into a `RunLauncher`. */
+export function createRemoteRunLauncher(target) {
+    return {
+        launch: (args) => {
+            const runId = args.runId;
+            if (!runId) {
+                return Effect.fail(new RunLauncherError({ message: 'RunLauncher.launch requires runId' }));
+            }
+            return Effect.tryPromise({
+                try: () => target.launch(runId, { ...args, runId }),
+                catch: runLauncherError,
+            });
+        },
+        status: (runId) => Effect.tryPromise({
+            try: () => target.status(runId),
+            catch: runLauncherError,
+        }),
+        signal: (runId, events, options) => Effect.tryPromise({
+            try: () => target.accept(runId, events, { ...options, coalesce: true }),
+            catch: runLauncherError,
+        }),
+        cancel: (runId) => Effect.tryPromise({
+            try: () => target.cancel(runId),
+            catch: runLauncherError,
+        }),
+    };
+}

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

@@ -3,7 +3,8 @@ import { type CatalogEntries, type EventCatalog, type EventInputOf, type EventsO
 import type { EventsOf, ProtocolEvents } from './compose';
 import { type EffectDefinition, type EffectExecution, type EffectHandlerResult, type EmitEffect, type RetryPolicy, type RuntimeEffect, type ScopedEffectContext } from './effects';
 import type { EventEnvelope, EventInput } from './envelope';
-import { type AnyRuntimeModule, type EffectMiddleware, type RuntimeModule, type DefinitionRef, type RuntimeModuleDependency, type SignalInterruptRule } from './module';
+import type { RunLauncherTag } from './launcher';
+import { type AnyRuntimeModule, type DefinitionHost, type EffectMiddleware, type RuntimeModule, type DefinitionRef, type RuntimeModuleDependency, type SignalInterruptRule } from './module';
 import { type ProjectionDefinition } from './projection';
 import type { InferDefinedSchema, InferSchemaOutput, SchemaInput } from './schema';
 import { type StartContext, type ThreadContext, type ThreadDefinition } from './thread';
@@ -18,9 +19,9 @@ export interface DefineModuleOptions<TNamespace extends string, TEvents extends
 export type ScopeUniverse<TEvents extends EventCatalog | undefined, TObserves extends readonly EventCatalog[] | undefined> = ProtocolEvents | (TEvents extends EventCatalog ? EventsOfCatalog<TEvents> : never) | (TObserves extends readonly EventCatalog[] ? EventsOfCatalog<TObserves[number]> : never);
 export type EffectRequirementsOf<TEffects> = TEffects extends {
     readonly [key: string]: EffectDefinition<any, any, any>;
-} ? {
+} ? Exclude<{
     [K in keyof TEffects]: TEffects[K] extends EffectDefinition<any, infer R, any> ? R : never;
-}[keyof TEffects] : never;
+}[keyof TEffects], RunLauncherTag> : never;
 export type ModuleServicesConfig<TR> = [TR] extends [never] ? {
     readonly services?: () => Layer.Layer<any>;
 } : {
@@ -36,6 +37,7 @@ export interface ModuleScope<TNamespace extends string, U extends EventEnvelope<
         readonly kind: string;
         readonly shape?: undefined;
         readonly input?: TInputSchema;
+        readonly forgetsCompletedEffects?: boolean;
         initialState(ctx: StartContext<InferDefinedSchema<TInputSchema>>): S;
         step(state: S, event: U, ctx: ThreadContext): S;
         effects?(state: S, ctx: ThreadContext): RuntimeEffect[];
@@ -44,6 +46,7 @@ export interface ModuleScope<TNamespace extends string, U extends EventEnvelope<
         readonly kind: string;
         readonly shape: TShape;
         readonly input?: TInputSchema;
+        readonly forgetsCompletedEffects?: boolean;
         initialState(ctx: StartContext<InferDefinedSchema<TInputSchema>>): InferSchemaOutput<TShape>;
         step(state: NoInfer<InferSchemaOutput<TShape>>, event: U, ctx: ThreadContext): InferSchemaOutput<TShape>;
         effects?(state: NoInfer<InferSchemaOutput<TShape>>, ctx: ThreadContext): RuntimeEffect[];
@@ -95,6 +98,7 @@ export declare function defineModule<const N extends string, E extends EventCata
     readonly definitions?: readonly DefinitionRef[];
     readonly middleware?: readonly EffectMiddleware[];
     readonly interruptsOnSignal?: SignalInterruptRule;
+    readonly bindHost?: (host: DefinitionHost) => void;
 } & ModuleServicesConfig<EffectRequirementsOf<FX>>): RuntimeModule<N, Extract<ModuleCatalog<N, E>, EventCatalog>, FX, TH, PR> & {
     readonly effects: FX;
     readonly threads: TH;

package/dist/core/module-scope.js

@@ -78,5 +78,8 @@ export function defineModule(options, setup) {
     if (members.interruptsOnSignal) {
         module.interruptsOnSignal = members.interruptsOnSignal;
     }
+    if (members.bindHost) {
+        module.bindHost = members.bindHost;
+    }
     return module;
 }

package/dist/core/module.d.ts

@@ -1,5 +1,6 @@
 import type { Context, Effect, Layer } from 'effect';
 import type { EventCatalog } from './catalog';
+import type { DefinitionResolver } from './definition-resolver';
 import type { EffectContext, EffectDefinition, RuntimeEffect } from './effects';
 import type { EventInput } from './envelope';
 import type { ProjectionDefinition } from './projection';
@@ -14,6 +15,10 @@ export type EffectMiddleware = (effect: RuntimeEffect, ctx: EffectContext, next:
  * descendants. Return an empty array when the event interrupts nothing.
  */
 export type SignalInterruptRule = (event: EventInput) => readonly string[];
+/** Passed to a module once, before its services layer is constructed. */
+export interface DefinitionHost {
+    readonly definitionResolver: DefinitionResolver;
+}
 export interface RuntimeModuleDependency {
     readonly namespace: string;
     readonly protocolVersion?: string;
@@ -70,6 +75,11 @@ export interface RuntimeModule<TNamespace extends string = string, TEvents exten
     readonly interruptsOnSignal?: SignalInterruptRule;
     /** Host-side services this module's effect handlers need (an LLM, a definition lookup, a DB pool). */
     readonly services?: () => Layer.Layer<TServices>;
+    /**
+     * Receives the host's definition resolver before `services()` runs.
+     * Modules that look definitions up during fold share one store with this resolver.
+     */
+    readonly bindHost?: (host: DefinitionHost) => void;
 }
 export declare function defineRuntimeModule<TNamespace extends string, TEvents extends EventCatalog, TEffects extends {
     readonly [key: string]: EffectDefinition;

package/dist/core/projection.d.ts

@@ -1,5 +1,6 @@
 import { Schema, Stream, type Effect } from 'effect';
 import type { EventEnvelope } from './envelope';
+import type { AnyEventEnvelope, RegisteredEvent } from './register';
 import type { InferSchemaOutput, SchemaInput } from './schema';
 import type { RunState, ThreadRecord } from './state';
 export interface ProjectionDefinition<S = unknown> {
@@ -8,17 +9,17 @@ export interface ProjectionDefinition<S = unknown> {
     initialState: S;
     reduce(state: S, event: EventEnvelope): S;
 }
-export declare function defineProjection<S = unknown>(def: {
+export declare function defineProjection<S = unknown, TEvent extends AnyEventEnvelope = RegisteredEvent>(def: {
     readonly name: string;
     readonly shape?: undefined;
     readonly initialState: S;
-    reduce(state: S, event: EventEnvelope): S;
+    reduce(state: S, event: TEvent): S;
 }): ProjectionDefinition<S>;
-export declare function defineProjection<TShape extends SchemaInput>(def: {
+export declare function defineProjection<TShape extends SchemaInput, TEvent extends AnyEventEnvelope = RegisteredEvent>(def: {
     readonly name: string;
     readonly shape: TShape;
     readonly initialState: InferSchemaOutput<TShape>;
-    reduce(state: NoInfer<InferSchemaOutput<TShape>>, event: EventEnvelope): InferSchemaOutput<TShape>;
+    reduce(state: NoInfer<InferSchemaOutput<TShape>>, event: TEvent): InferSchemaOutput<TShape>;
 }): ProjectionDefinition<InferSchemaOutput<TShape>>;
 export declare function foldProjection<S>(projection: ProjectionDefinition<S>, events: readonly EventEnvelope[], initial?: S): S;
 /** Fold a projection over events, skipping ephemeral ones. */

package/dist/core/projection.js

@@ -175,12 +175,16 @@ export function toThreadTree(state) {
         rootThreadId: state.rootThreadId,
         startIdentity: null,
         forkedFrom: null,
+        attributes: {},
         threads: state.records,
         waits: {},
         outstandingEffects: [],
         effectExecutions: {},
         completedEffectIds: [],
         processedIdempotencyKeys: [],
+        launchedRuns: [],
+        closeWaiting: false,
+        childCloseSent: false,
     });
 }
 export function treeFromRun(state) {

package/dist/core/protocol.d.ts

@@ -9,6 +9,18 @@ export declare const protocolCatalog: import("./catalog").EventCatalog<"runtime"
         readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
         readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
         readonly requestedThreadId: Schema.optional<Schema.NullOr<Schema.String>>;
+        readonly launchedBy: Schema.optional<Schema.Struct<{
+            readonly runId: Schema.String;
+            readonly threadId: Schema.String;
+            readonly effectId: Schema.String;
+            readonly causationId: Schema.String;
+            readonly causationSeq: Schema.Finite;
+        }>>;
+        readonly attributes: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        readonly trace: Schema.optional<Schema.Struct<{
+            readonly traceparent: Schema.String;
+            readonly tracestate: Schema.optional<Schema.String>;
+        }>>;
     }>;
     'run.completed': Schema.Struct<{
         readonly output: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
@@ -17,6 +29,24 @@ export declare const protocolCatalog: import("./catalog").EventCatalog<"runtime"
     'run.cancelled': Schema.Struct<{
         readonly reason: Schema.optional<Schema.String>;
     }>;
+    'run.launched': Schema.Struct<{
+        readonly runId: Schema.String;
+        readonly kind: Schema.String;
+        readonly definitionName: Schema.String;
+        readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
+        /** In the payload, not the envelope: an envelope `effectId` would complete the effect. */
+        readonly effectId: Schema.String;
+        readonly close: Schema.withDecodingDefaultKey<Schema.Union<readonly [Schema.Literal<"terminate">, Schema.Literal<"wait">]>, never>;
+    }>;
+    'child.settled': Schema.Struct<{
+        readonly runId: Schema.String;
+        readonly status: Schema.Union<readonly [Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+        readonly output: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly error: Schema.NullOr<Schema.String>;
+    }>;
+    'child.close.requested': Schema.Struct<{
+        readonly policy: Schema.Union<readonly [Schema.Literal<"terminate">, Schema.Literal<"wait">]>;
+    }>;
     'run.forked': Schema.Struct<{
         readonly sourceRunId: Schema.String;
         readonly sourceSeq: Schema.Finite;
@@ -81,6 +111,8 @@ export declare const protocolCatalog: import("./catalog").EventCatalog<"runtime"
     'effect.failed': Schema.Struct<{
         readonly effectId: Schema.String;
         readonly error: Schema.String;
+        readonly nonRetryable: Schema.optional<Schema.Boolean>;
+        readonly retryAfterMs: Schema.optional<Schema.Finite>;
     }>;
     'effect.attempt.started': Schema.Struct<{
         readonly effectId: Schema.String;
@@ -106,6 +138,8 @@ export declare const protocolCatalog: import("./catalog").EventCatalog<"runtime"
         readonly attempt: Schema.Finite;
         readonly heartbeatAt: Schema.Finite;
         readonly deadlineAt: Schema.NullOr<Schema.Finite>;
+        /** Progress the next attempt should resume from. Absent on heartbeats that only extend the deadline. */
+        readonly details: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     }>;
     'effect.cancel.requested': Schema.Struct<{
         readonly effectId: Schema.String;
@@ -147,10 +181,11 @@ 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.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 declare const PROTOCOL_TYPES: readonly ['runtime.run.started', 'runtime.run.completed', 'runtime.run.cancelled', 'runtime.run.launched', 'runtime.child.settled', 'runtime.child.close.requested', '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']>;
+export type RunLaunchedPayload = Schema.Schema.Type<(typeof protocolCatalog.entries)['run.launched']>;
 export type RunCompletedPayload = Schema.Schema.Type<(typeof protocolCatalog.entries)['run.completed']>;
 export type ThreadStartedPayload = Schema.Schema.Type<(typeof protocolCatalog.entries)['thread.started']>;
 export type ThreadCompletedPayload = Schema.Schema.Type<(typeof protocolCatalog.entries)['thread.completed']>;

package/dist/core/protocol.js

@@ -2,7 +2,10 @@ import { Effect, Schema } from 'effect';
 import { defineEventCatalog } from './catalog.js';
 import { WaitConditionSchema } from './effects.js';
 import { JsonValueSchema } from './envelope.js';
+import { RunLaunchSourceSchema } from './launcher.js';
 import { DEFAULT_DEFINITION_VERSION } from './module.js';
+import { RunAttributesSchema } from './run-context.js';
+import { TraceContextSchema } from './trace.js';
 const DefinitionVersionSchema = Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION)));
 export const protocolCatalog = defineEventCatalog('runtime', {
     'run.started': Schema.Struct({
@@ -12,6 +15,9 @@ export const protocolCatalog = defineEventCatalog('runtime', {
         definitionVersion: DefinitionVersionSchema,
         input: JsonValueSchema,
         requestedThreadId: Schema.optional(Schema.NullOr(Schema.String)),
+        launchedBy: Schema.optional(RunLaunchSourceSchema),
+        attributes: Schema.optional(RunAttributesSchema),
+        trace: Schema.optional(TraceContextSchema),
     }),
     'run.completed': Schema.Struct({
         output: Schema.NullOr(JsonValueSchema),
@@ -20,6 +26,28 @@ export const protocolCatalog = defineEventCatalog('runtime', {
     'run.cancelled': Schema.Struct({
         reason: Schema.optional(Schema.String),
     }),
+    'run.launched': Schema.Struct({
+        runId: Schema.String,
+        kind: Schema.String,
+        definitionName: Schema.String,
+        definitionVersion: DefinitionVersionSchema,
+        /** In the payload, not the envelope: an envelope `effectId` would complete the effect. */
+        effectId: Schema.String,
+        close: Schema.Union([Schema.Literal('terminate'), Schema.Literal('wait')]).pipe(Schema.withDecodingDefaultKey(Effect.succeed('terminate'))),
+    }),
+    'child.settled': Schema.Struct({
+        runId: Schema.String,
+        status: Schema.Union([
+            Schema.Literal('completed'),
+            Schema.Literal('failed'),
+            Schema.Literal('cancelled'),
+        ]),
+        output: Schema.NullOr(JsonValueSchema),
+        error: Schema.NullOr(Schema.String),
+    }),
+    'child.close.requested': Schema.Struct({
+        policy: Schema.Union([Schema.Literal('terminate'), Schema.Literal('wait')]),
+    }),
     'run.forked': Schema.Struct({
         sourceRunId: Schema.String,
         sourceSeq: Schema.Finite,
@@ -79,6 +107,8 @@ export const protocolCatalog = defineEventCatalog('runtime', {
     'effect.failed': Schema.Struct({
         effectId: Schema.String,
         error: Schema.String,
+        nonRetryable: Schema.optional(Schema.Boolean),
+        retryAfterMs: Schema.optional(Schema.Finite),
     }),
     'effect.attempt.started': Schema.Struct({
         effectId: Schema.String,
@@ -104,6 +134,8 @@ export const protocolCatalog = defineEventCatalog('runtime', {
         attempt: Schema.Finite,
         heartbeatAt: Schema.Finite,
         deadlineAt: Schema.NullOr(Schema.Finite),
+        /** Progress the next attempt should resume from. Absent on heartbeats that only extend the deadline. */
+        details: Schema.optional(JsonValueSchema),
     }),
     'effect.cancel.requested': Schema.Struct({
         effectId: Schema.String,
@@ -147,6 +179,9 @@ export const PROTOCOL_TYPES = [
     'runtime.run.started',
     'runtime.run.completed',
     'runtime.run.cancelled',
+    'runtime.run.launched',
+    'runtime.child.settled',
+    'runtime.child.close.requested',
     'runtime.run.forked',
     'runtime.fork.elided',
     'runtime.thread.started',

package/dist/core/published.d.ts

@@ -30,6 +30,7 @@ export declare const RunSummarySchema: Schema.Struct<{
     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>;
+    readonly attributes: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>;
 }>;
 export type RunSummary = Schema.Schema.Type<typeof RunSummarySchema>;
 export declare function summarizeRun(state: RunState): RunSummary;
@@ -39,5 +40,6 @@ export declare const RunSummariesSchema: Schema.Struct<{
         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>;
+        readonly attributes: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>;
     }>>;
 }>;

package/dist/core/published.js

@@ -1,5 +1,6 @@
-import { Schema } from 'effect';
+import { Effect, Schema } from 'effect';
 import { JsonValueSchema } from './envelope.js';
+import { RunAttributesSchema } from './run-context.js';
 import { jsonSchemaOfInput } from './schema.js';
 import { RunStateSchema } from './state.js';
 /** A registered definition as `GET /definitions` publishes it. */
@@ -30,6 +31,7 @@ export const RunSummarySchema = Schema.Struct({
     status: RunStateSchema.fields.status,
     kind: Schema.NullOr(Schema.String),
     definitionName: Schema.NullOr(Schema.String),
+    attributes: RunAttributesSchema.pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
 });
 export function summarizeRun(state) {
     return {
@@ -37,6 +39,7 @@ export function summarizeRun(state) {
         status: state.status,
         kind: state.startIdentity?.kind ?? null,
         definitionName: state.startIdentity?.definitionName ?? null,
+        attributes: state.attributes ?? {},
     };
 }
 export const RunSummariesSchema = Schema.Struct({

package/dist/{react → core}/register.d.ts

@@ -1,11 +1,12 @@
-import type { EventEnvelope, EventsOf } from '@swirls/looms/core';
+import type { EventsOf } from './compose';
+import type { EventEnvelope } from './envelope';
 /** Looser event bound so catalog-inferred payloads (including Schema.Type) are accepted. */
 export type AnyEventEnvelope = EventEnvelope<string, any>;
 /**
- * Application-level type registry for Looms React/client stores.
+ * Application-level type registry for Looms.
  *
- * Augment this interface in your app to bind the event catalog used by
- * `useRunEvents`, `createLoomsStore`, and related hooks:
+ * Augment this interface once to bind your event union. `defineProjection` reducers and the
+ * `@swirls/looms/react` hooks and stores use it as their default event type:
  *
  * ```ts
  * declare module '@swirls/looms/react' {
@@ -15,7 +16,7 @@ export type AnyEventEnvelope = EventEnvelope<string, any>;
  * }
  * ```
  *
- * You may register either:
+ * Augmenting `@swirls/looms/core` works the same way. You may register either:
  * - `events`: an explicit event union
  * - `modules`: a module array / creator function (via `EventsOf`)
  * - `catalog`: an event catalog or catalog array (via `EventsOf`)
@@ -24,8 +25,8 @@ export interface LoomsRegister {
 }
 export type RegisteredEvent = LoomsRegister extends {
     events: infer E;
-} ? E & AnyEventEnvelope : LoomsRegister extends {
+} ? Extract<E, AnyEventEnvelope> : LoomsRegister extends {
     modules: infer M;
-} ? EventsOf<M> & AnyEventEnvelope : LoomsRegister extends {
+} ? Extract<EventsOf<M>, AnyEventEnvelope> : LoomsRegister extends {
     catalog: infer C;
-} ? EventsOf<C> & AnyEventEnvelope : EventEnvelope;
+} ? Extract<EventsOf<C>, AnyEventEnvelope> : EventEnvelope;