@swirls/looms 0.0.2 → 0.1.0

package/dist/cloudflare/event-store.d.ts

@@ -1,10 +1,15 @@
+import type { Effect } from 'effect';
 import type { EventStore } from '@swirls/looms/core';
-import { type Projector } from '@swirls/looms/projectors';
+import { type Projector, type ProjectorDelivery } from '@swirls/looms/projectors';
 export interface DurableObjectStoreOptions {
     readonly projectors?: readonly Projector[];
+    readonly scheduleProjectorRetry?: (at: number) => Effect.Effect<void>;
+}
+export interface DurableObjectEventStore extends EventStore {
+    readonly projectorDelivery?: ProjectorDelivery;
 }
 /**
  * Creates an EventStore backed by a Durable Object's embedded SQLite database (`ctx.storage.sql`).
  * Optionally attaches asynchronous projectors (such as S2).
  */
-export declare function durableObjectEventStore(ctx: DurableObjectState, options?: DurableObjectStoreOptions): EventStore;
+export declare function durableObjectEventStore(ctx: DurableObjectState, options?: DurableObjectStoreOptions): DurableObjectEventStore;

package/dist/cloudflare/event-store.js

@@ -1,18 +1,19 @@
 import { sqliteEventStore, sqlStorageExec } from '@swirls/looms/core/sqlite-store';
-import { withProjectors } from '@swirls/looms/projectors';
+import { createProjectorDelivery, sqliteProjectorCursorStore, withProjectors, } from '@swirls/looms/projectors';
 /**
  * Creates an EventStore backed by a Durable Object's embedded SQLite database (`ctx.storage.sql`).
  * Optionally attaches asynchronous projectors (such as S2).
  */
 export function durableObjectEventStore(ctx, options = {}) {
-    const store = sqliteEventStore({
-        exec: sqlStorageExec(ctx.storage.sql, {
-            // DO SQLite rejects BEGIN/COMMIT/ROLLBACK; use the storage transaction API.
-            transaction: (fn) => ctx.storage.transactionSync(fn),
-        }),
+    const exec = sqlStorageExec(ctx.storage.sql, {
+        // DO SQLite rejects BEGIN/COMMIT/ROLLBACK; use the storage transaction API.
+        transaction: (fn) => ctx.storage.transactionSync(fn),
     });
+    const store = sqliteEventStore({ exec });
     if (options.projectors && options.projectors.length > 0) {
-        return withProjectors(store, options.projectors);
+        const delivery = createProjectorDelivery(store, options.projectors, sqliteProjectorCursorStore(exec), { scheduleRetry: options.scheduleProjectorRetry });
+        const wrapped = withProjectors(store, options.projectors, { delivery });
+        return Object.assign(wrapped, { projectorDelivery: delivery });
     }
     return store;
 }

package/dist/cloudflare/index.d.ts

@@ -1,4 +1,4 @@
-export { alarmScheduler, type AlarmStorage } from './alarm-scheduler';
-export { durableObjectEventStore, type DurableObjectStoreOptions } from './event-store';
+export { durableObjectAlarms, type AlarmStorage, type DurableObjectAlarms } from './alarm-scheduler';
+export { durableObjectEventStore, type DurableObjectEventStore, type DurableObjectStoreOptions, } from './event-store';
 export { LoomsDurableObject, type LoomsDurableObjectConfig } from './durable-object';
 export { routeToDurableObject, type DurableObjectNamespaceLike, type DurableObjectStubLike, } from './router';

package/dist/cloudflare/index.js

@@ -1,4 +1,4 @@
-export { alarmScheduler } from './alarm-scheduler.js';
-export { durableObjectEventStore } from './event-store.js';
+export { durableObjectAlarms } from './alarm-scheduler.js';
+export { durableObjectEventStore, } from './event-store.js';
 export { LoomsDurableObject } from './durable-object.js';
 export { routeToDurableObject, } from './router.js';

package/dist/cloudflare/router.js

@@ -1,26 +1,25 @@
-import { resolveRunTarget } from '@swirls/looms/actor';
+import { resolveRunTarget, RunTargetError } from '@swirls/looms/actor';
 /**
  * Routes incoming HTTP requests to the appropriate Durable Object actor cell.
  * Handles `/health` locally, returns 501 for global `GET /runs`, and forwards
  * all other run and event-stream requests to `namespace.getByName(runId)`.
  */
-export async function routeToDurableObject(namespace, req) {
+export function routeToDurableObject(namespace, req) {
     const url = new URL(req.url);
     if (url.pathname === '/health') {
-        return Response.json({ ok: true });
+        return Promise.resolve(Response.json({ ok: true }));
     }
     if (req.method === 'GET' && url.pathname === '/runs') {
-        return Response.json({
+        return Promise.resolve(Response.json({
             error: 'Global run listing is not supported in the Durable Object backend without a global index',
-        }, { status: 501 });
-    }
-    try {
-        const { runId, request } = await resolveRunTarget(req);
-        const stub = namespace.getByName(runId);
-        return stub.fetch(request);
-    }
-    catch {
-        // Paths without a resolvable runId (e.g. GET /) are not handled by this router.
-        return null;
+        }, { status: 501 }));
     }
+    return resolveRunTarget(req)
+        .then(({ runId, request }) => namespace.getByName(runId).fetch(request))
+        .catch((error) => {
+        if (error instanceof RunTargetError) {
+            return null;
+        }
+        return Promise.reject(error);
+    });
 }

package/dist/core/catalog.d.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Schema } from 'effect';
 import { type EventEnvelope, type EventInput, type TypedEvent } from './envelope';
-import { type JsonValue } from './types';
+import type { JsonValue } from './types';
 declare const catalogPayloadBrand: unique symbol;
 /** Type-only catalog entry. Carries a payload type without a runtime schema. */
 export type CatalogEventSpec<TPayload = object> = {
@@ -13,11 +13,11 @@ export type CatalogEventSpec<TPayload = object> = {
  * `payload<{ amount: number }>()` is a compile-time marker — not a cast of `{}`.
  */
 export declare function payload<TPayload>(): CatalogEventSpec<TPayload>;
-export type CatalogEntry = CatalogEventSpec | Schema.Top | StandardSchemaV1;
+export type CatalogEntry = CatalogEventSpec | Schema.ConstraintDecoder<unknown> | StandardSchemaV1;
 export type CatalogEntries = {
     readonly [key: string]: CatalogEntry;
 };
-export type InferPayload<T> = T extends CatalogEventSpec<infer P> ? P : T extends Schema.Top ? Schema.Schema.Type<T> : T extends StandardSchemaV1<infer _In, infer Out> ? Out : JsonValue;
+export type InferPayload<T> = T extends CatalogEventSpec<infer P> ? P : T extends Schema.ConstraintDecoder<unknown> ? Schema.Schema.Type<T> : T extends StandardSchemaV1<infer _In, infer Out> ? Out : JsonValue;
 export interface EventCatalog<TNamespace extends string = string, TEntries extends CatalogEntries = CatalogEntries> {
     readonly namespace: TNamespace;
     readonly entries: TEntries;

package/dist/core/catalog.js

@@ -1,5 +1,4 @@
 import { createEvent } from './envelope.js';
-import { asJson } from './types.js';
 /**
  * Declare a catalog event's payload type when you do not have a Zod / Standard Schema.
  *
@@ -17,19 +16,17 @@ export function defineEventCatalog(namespace, entries) {
         entries,
         event(key, eventPayload, meta) {
             const { runId, ...rest } = meta;
-            // SAFETY: createEvent returns EventEnvelope with inferred payload type.
             return createEvent(runId, {
                 ...rest,
                 type: eventType(namespace, key),
-                payload: asJson(eventPayload),
+                payload: eventPayload,
             });
         },
         input(key, eventPayload, meta) {
             return {
                 ...meta,
                 type: eventType(namespace, key),
-                // SAFETY: asJson returns typed payload for catalog event.
-                payload: asJson(eventPayload),
+                payload: eventPayload,
             };
         },
     };

package/dist/core/coalesce.js

@@ -90,7 +90,8 @@ export function createCoalescingAppender(flush, options) {
                 }
                 default: {
                     const exhaustiveCheck = taken;
-                    return exhaustiveCheck;
+                    void exhaustiveCheck;
+                    return;
                 }
             }
         }
@@ -135,11 +136,12 @@ export function createCoalescingAppender(flush, options) {
                 if (result.pending > maxPending) {
                     yield* Deferred.await(result.deferred);
                 }
-                return;
+                return undefined;
             }
             default: {
                 const exhaustiveCheck = result;
-                return exhaustiveCheck;
+                void exhaustiveCheck;
+                return undefined;
             }
         }
     });

package/dist/core/compose.d.ts

@@ -3,7 +3,7 @@ import type { CatalogEvent, EventCatalog } from './catalog';
 import type { EffectDefinition } from './effects';
 import type { EventEnvelope } from './envelope';
 import type { FoldRegistry } from './fold';
-import type { AnyRuntimeModule, EffectMiddleware, RuntimeModule, RegisteredDefinition } from './module';
+import type { AnyRuntimeModule, EffectMiddleware, RuntimeModule, RegisteredDefinition, SignalInterruptRule } from './module';
 import type { ProjectionDefinition } from './projection';
 import { protocolCatalog } from './protocol';
 import type { ThreadDefinition } from './thread';
@@ -22,6 +22,7 @@ export interface ComposedRegistry extends FoldRegistry {
     readonly projections: ReadonlyMap<string, ProjectionDefinition>;
     readonly catalogs: readonly EventCatalog[];
     readonly middleware: readonly EffectMiddleware[];
+    readonly interruptRules: readonly SignalInterruptRule[];
 }
 export declare function composeModules(modules: readonly AnyRuntimeModule[]): ComposedRegistry;
 export declare function composeModulesEffect(modules: readonly AnyRuntimeModule[]): Effect.Effect<ComposedRegistry, ModuleCompositionError>;

package/dist/core/compose.js

@@ -1,4 +1,5 @@
 import { Data, Effect } from 'effect';
+import { DEFAULT_DEFINITION_VERSION, definitionKey } from './module.js';
 import { protocolCatalog } from './protocol.js';
 export class ModuleCompositionError extends Data.TaggedError('ModuleCompositionError') {
     constructor(text) {
@@ -14,6 +15,7 @@ export function composeModules(modules) {
     const effects = new Map();
     const projections = new Map();
     const middleware = [];
+    const interruptRules = [];
     const catalogs = [protocolCatalog];
     for (const module of modules) {
         if (namespaces.has(module.namespace)) {
@@ -41,7 +43,8 @@ export function composeModules(modules) {
             }
         }
         for (const definition of module.definitions ?? []) {
-            const key = `${definition.kind}:${definition.name}`;
+            const version = definition.version ?? DEFAULT_DEFINITION_VERSION;
+            const key = definitionKey(definition.kind, definition.name, version);
             if (definitionKeys.has(key)) {
                 throw new ModuleCompositionError(`Duplicate definition: ${key}`);
             }
@@ -52,6 +55,7 @@ export function composeModules(modules) {
             definitions.push({
                 kind: definition.kind,
                 name: definition.name,
+                version,
                 input: definition.input,
                 value: definition,
             });
@@ -76,6 +80,9 @@ export function composeModules(modules) {
         if (module.middleware) {
             middleware.push(...module.middleware);
         }
+        if (module.interruptsOnSignal) {
+            interruptRules.push(module.interruptsOnSignal);
+        }
         if (module.projections) {
             for (const definition of Object.values(module.projections)) {
                 if (projections.has(definition.name)) {
@@ -85,7 +92,16 @@ export function composeModules(modules) {
             }
         }
     }
-    return { definitions, modules, threads, effects, projections, catalogs, middleware };
+    return {
+        definitions,
+        modules,
+        threads,
+        effects,
+        projections,
+        catalogs,
+        middleware,
+        interruptRules,
+    };
 }
 export function composeModulesEffect(modules) {
     return Effect.try({

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

@@ -0,0 +1,11 @@
+export interface VersionedDefinition {
+    readonly kind: string;
+    readonly name: string;
+    readonly version: string;
+}
+/** Lookup of one definition kind by name and version. */
+export interface DefinitionStore<TDefinition> {
+    get(name: string, version: string): TDefinition | undefined;
+}
+/** Indexes definitions of one kind by `definitionKey`. */
+export declare function makeDefinitionStore<TDefinition extends VersionedDefinition>(kind: TDefinition['kind'], definitions: ReadonlyArray<TDefinition>): DefinitionStore<TDefinition>;

package/dist/core/definition-store.js

@@ -0,0 +1,6 @@
+import { definitionKey } from './module.js';
+/** Indexes definitions of one kind by `definitionKey`. */
+export function makeDefinitionStore(kind, definitions) {
+    const byKey = new Map(definitions.map((definition) => [definitionKey(definition.kind, definition.name, definition.version), definition]));
+    return { get: (name, version) => byKey.get(definitionKey(kind, name, version)) };
+}

package/dist/core/effects.d.ts

@@ -1,6 +1,6 @@
-import { Effect } from 'effect';
-import type { EventInput } from './envelope';
-import { type InferDefinedSchema, type SchemaInput } from './schema';
+import { Effect, Schema, type Context } from 'effect';
+import { type EventInput } from './envelope';
+import { type InferDefinedSchema, type InvalidInputError, type SchemaInput } from './schema';
 import { type JsonValue } from './types';
 export type WaitOnEvent = {
     type: string | readonly string[];
@@ -15,6 +15,7 @@ export type SpawnEffect = {
     childThreadId: string;
     kind: string;
     definitionName: string;
+    definitionVersion: string;
     input: JsonValue;
 };
 export type WaitEffect = {
@@ -26,6 +27,8 @@ export type WaitEffect = {
 export type EmitEffect<E extends EventInput = EventInput> = {
     type: 'runtime.emit';
     event: E;
+    /** Stable identity, so the emit survives reordering of the thread's effects. */
+    tag?: string;
 };
 export type CompleteEffect = {
     type: 'runtime.complete';
@@ -38,11 +41,17 @@ export type FailEffect = {
 export type CancelEffect = {
     type: 'runtime.cancel';
     threadId: string;
+    tag?: string;
 };
 export interface RetryPolicy {
     readonly maxAttempts: number;
     readonly backoffMs?: number;
     readonly maxBackoffMs?: number;
+    readonly backoffMultiplier?: number;
+    readonly scheduleToStartTimeoutMs?: number;
+    readonly startToCloseTimeoutMs?: number;
+    readonly heartbeatTimeoutMs?: number;
+    readonly cancellationTimeoutMs?: number;
 }
 export type InvokeEffect = {
     type: string;
@@ -51,6 +60,69 @@ export type InvokeEffect = {
 };
 export type PrimitiveEffect = SpawnEffect | WaitEffect | EmitEffect | CompleteEffect | FailEffect | CancelEffect;
 export type RuntimeEffect = PrimitiveEffect | InvokeEffect;
+export declare const WaitConditionSchema: 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;
+}>]>;
+export declare const RuntimeEffectSchema: 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>;
+}>]>;
 export declare function isPrimitiveEffect(effect: RuntimeEffect): effect is PrimitiveEffect;
 export declare function isWaitOnTimer(on: WaitCondition): on is WaitOnTimer;
 export declare function isWaitOnEvent(on: WaitCondition): on is WaitOnEvent;
@@ -62,6 +134,7 @@ export interface EffectContext {
     readonly runId: string;
     readonly threadId: string;
     readonly causingEventId: string;
+    readonly signal: AbortSignal;
     emit(event: EventInput): Promise<void>;
 }
 export interface ScopedEffectContext<E extends EventInput = EventInput> {
@@ -69,32 +142,60 @@ export interface ScopedEffectContext<E extends EventInput = EventInput> {
     readonly runId: string;
     readonly threadId: string;
     readonly causingEventId: string;
+    readonly signal: AbortSignal;
     emit(event: E): Promise<void>;
 }
 export type EffectInputSchema = SchemaInput;
-export type EffectHandlerResult<R = never, E extends EventInput = EventInput> = ReadonlyArray<E> | Promise<ReadonlyArray<E>> | Effect.Effect<ReadonlyArray<E>, Error, R>;
-export interface EffectDefinition<TInput = JsonValue, R = any, E extends EventInput = EventInput> {
+declare const EffectHandlerError_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: "EffectHandlerError";
+} & Readonly<A>;
+export declare class EffectHandlerError extends EffectHandlerError_base<{
+    readonly cause: unknown;
+    readonly message: string;
+}> {
+    constructor(cause: unknown);
+}
+export type EffectHandlerResult<R = never, E extends EventInput = EventInput, HandlerError = never> = ReadonlyArray<E> | Promise<ReadonlyArray<E>> | Effect.Effect<ReadonlyArray<E>, HandlerError, R>;
+declare const effectInputType: unique symbol;
+export type EffectExecution = 'local' | 'worker';
+export interface EffectDefinition<TInput = JsonValue, R = Context.Service.Any, E extends EventInput = EventInput> {
     readonly type: string;
     readonly input?: SchemaInput;
     readonly retry?: RetryPolicy;
-    execute(input: TInput, ctx: EffectContext): Effect.Effect<ReadonlyArray<E>, Error, R>;
+    /** Forces where the effect runs. When omitted, the runtime decides from `hasHandler` and the configured worker. */
+    readonly execution?: EffectExecution;
+    /** Whether `execute` runs a user handler. Without one, the effect can only complete through a worker. */
+    readonly hasHandler: boolean;
+    readonly [effectInputType]?: (input: TInput) => TInput;
+    execute(input: JsonValue, ctx: EffectContext): Effect.Effect<ReadonlyArray<E>, InvalidInputError | EffectHandlerError, R>;
 }
 /**
- * Define an effect handler. A run's actor cell executes each effect at most
- * once while it is alive. If the cell dies mid-execution, the replacement
- * actor may re-run the handler (at-least-once across failover). Keep handlers
+ * Define an effect. With `execute`, a run's actor cell runs the handler at
+ * most once while it is alive; if the cell dies mid-execution, the replacement
+ * actor may re-run it (at-least-once across failover). Keep handlers
  * idempotent when they have external side effects.
+ *
+ * Omit `execute` to declare an effect that only an `EffectWorker` completes.
  */
-export declare function defineEffect<TSchema = undefined, TInput = InferDefinedSchema<TSchema>, R = never, E extends EventInput = EventInput>(def: {
+export declare function defineEffect<TSchema extends SchemaInput, R = never, E extends EventInput = EventInput, HandlerError = never>(def: {
+    type: string;
+    input: TSchema;
+    retry?: RetryPolicy;
+    execution?: EffectExecution;
+    execute?: (input: InferDefinedSchema<TSchema>, ctx: EffectContext) => EffectHandlerResult<R, E, HandlerError>;
+}): EffectDefinition<InferDefinedSchema<TSchema>, R, E>;
+export declare function defineEffect<R = never, E extends EventInput = EventInput, HandlerError = never>(def: {
     type: string;
-    input?: TSchema;
+    input?: undefined;
     retry?: RetryPolicy;
-    execute: (input: TInput, ctx: EffectContext) => EffectHandlerResult<R, E>;
-}): EffectDefinition<TInput, R, E>;
+    execution?: EffectExecution;
+    execute?: (input: JsonValue, ctx: EffectContext) => EffectHandlerResult<R, E, HandlerError>;
+}): EffectDefinition<JsonValue, R, E>;
 export declare function spawn(args: {
     childThreadId?: string;
     kind: string;
     definitionName: string;
+    definitionVersion?: string;
     input: JsonValue;
 }): SpawnEffect;
 export declare function wait(args: {
@@ -102,9 +203,20 @@ export declare function wait(args: {
     on: WaitCondition;
     tag?: JsonValue;
 }): WaitEffect;
-export declare function emit<E extends EventInput = EventInput>(event: E): EmitEffect<E>;
+export interface WaitOutcome {
+    readonly result: JsonValue | null;
+    readonly error: string | null;
+}
+/**
+ * Reads the outcome of a satisfied wait. The wait fails when the satisfying event's payload has an
+ * `error`, or when the waiter put an `error` on the wait's tag (such as a timeout that loses a
+ * race). Otherwise the result is the payload's `output`, else the whole payload.
+ */
+export declare function waitOutcome(satisfied: JsonValue | undefined, tag: JsonValue | undefined, fallback?: JsonValue | null): WaitOutcome;
+export declare function emit<E extends EventInput = EventInput>(event: E, tag?: string): EmitEffect<E>;
 export declare function complete(output: JsonValue): CompleteEffect;
 export declare function fail(error: string): FailEffect;
-export declare function cancel(threadId: string): CancelEffect;
+export declare function cancel(threadId: string, tag?: string): CancelEffect;
 export declare function invoke<TInput>(definition: EffectDefinition<TInput, any, any>, input: TInput, tag?: string): InvokeEffect;
 export declare function invoke(type: string, input: JsonValue, tag?: string): InvokeEffect;
+export {};

package/dist/core/effects.js

@@ -1,6 +1,54 @@
-import { Effect, Predicate } from 'effect';
-import { validateInputEffect } from './schema.js';
+import { Data, Effect, Predicate, Schema } from 'effect';
+import { EventInputSchema } from './envelope.js';
+import { DEFAULT_DEFINITION_VERSION } from './module.js';
+import { validateInputEffect, } from './schema.js';
 import { asJson } from './types.js';
+export const WaitConditionSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Union([Schema.String, Schema.Array(Schema.String)]),
+        match: Schema.optional(Schema.Json),
+    }),
+    Schema.Struct({ timerAt: Schema.Finite }),
+]);
+export const RuntimeEffectSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal('runtime.spawn'),
+        childThreadId: Schema.String,
+        kind: Schema.String,
+        definitionName: Schema.String,
+        definitionVersion: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION))),
+        input: Schema.Json,
+    }),
+    Schema.Struct({
+        type: Schema.Literal('runtime.wait'),
+        waitId: Schema.String,
+        on: WaitConditionSchema,
+        tag: Schema.optional(Schema.Json),
+    }),
+    Schema.Struct({
+        type: Schema.Literal('runtime.emit'),
+        event: EventInputSchema,
+        tag: Schema.optional(Schema.String),
+    }),
+    Schema.Struct({
+        type: Schema.Literal('runtime.complete'),
+        output: Schema.Json,
+    }),
+    Schema.Struct({
+        type: Schema.Literal('runtime.fail'),
+        error: Schema.String,
+    }),
+    Schema.Struct({
+        type: Schema.Literal('runtime.cancel'),
+        threadId: Schema.String,
+        tag: Schema.optional(Schema.String),
+    }),
+    Schema.Struct({
+        type: Schema.String,
+        input: Schema.Json,
+        tag: Schema.optional(Schema.String),
+    }),
+]);
 export function isPrimitiveEffect(effect) {
     switch (effect.type) {
         case 'runtime.spawn':
@@ -27,35 +75,40 @@ export function withdrawnError(siblingEffectId) {
 export function isWithdrawnError(error) {
     return error.startsWith(WITHDRAWN_ERROR_PREFIX);
 }
+export class EffectHandlerError extends Data.TaggedError('EffectHandlerError') {
+    constructor(cause) {
+        super({
+            cause,
+            message: cause instanceof Error ? cause.message : String(cause),
+        });
+        this.name = 'EffectHandlerError';
+    }
+}
 function liftHandlerResult(result) {
     if (Effect.isEffect(result)) {
-        return result;
+        return result.pipe(Effect.mapError((cause) => new EffectHandlerError(cause)));
     }
     if (result instanceof Promise) {
         return Effect.tryPromise({
             try: () => result,
-            catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+            catch: (cause) => new EffectHandlerError(cause),
         });
     }
     return Effect.succeed(result);
 }
-/**
- * Define an effect handler. A run's actor cell executes each effect at most
- * once while it is alive. If the cell dies mid-execution, the replacement
- * actor may re-run the handler (at-least-once across failover). Keep handlers
- * idempotent when they have external side effects.
- */
 export function defineEffect(def) {
     const schema = def.input;
-    // SAFETY: execute validates raw JsonValue against the optional schema before the typed handler.
+    const handler = def.execute;
+    const noOutput = [];
     return {
         type: def.type,
         input: schema,
         retry: def.retry,
+        execution: def.execution,
+        hasHandler: handler !== undefined,
         execute: (raw, ctx) => Effect.gen(function* () {
             const input = schema ? yield* validateInputEffect(schema, raw) : raw;
-            // SAFETY: input has been validated against schema or is unconstrained raw input
-            return yield* liftHandlerResult(def.execute(input, ctx));
+            return handler ? yield* liftHandlerResult(handler(input, ctx)) : noOutput;
         }),
     };
 }
@@ -66,6 +119,7 @@ export function spawn(args) {
         childThreadId,
         kind: args.kind,
         definitionName: args.definitionName,
+        definitionVersion: args.definitionVersion ?? DEFAULT_DEFINITION_VERSION,
         input: args.input,
     };
 }
@@ -80,8 +134,24 @@ export function wait(args) {
     }
     return effect;
 }
-export function emit(event) {
-    return { type: 'runtime.emit', event };
+/**
+ * Reads the outcome of a satisfied wait. The wait fails when the satisfying event's payload has an
+ * `error`, or when the waiter put an `error` on the wait's tag (such as a timeout that loses a
+ * race). Otherwise the result is the payload's `output`, else the whole payload.
+ */
+export function waitOutcome(satisfied, tag, fallback = null) {
+    const payload = Predicate.isObject(satisfied) && Predicate.isObject(satisfied.payload) ? satisfied.payload : {};
+    const tagError = Predicate.isObject(tag) && Predicate.isString(tag.error) ? tag.error : null;
+    const error = Predicate.isString(payload.error) ? payload.error : tagError;
+    if (error !== null) {
+        return { result: null, error };
+    }
+    const result = payload.output ?? (Predicate.isObject(satisfied) ? satisfied.payload : fallback);
+    // SAFETY: wait results are persisted JSON event payloads.
+    return { result: asJson(result) ?? null, error: null };
+}
+export function emit(event, tag) {
+    return tag === undefined ? { type: 'runtime.emit', event } : { type: 'runtime.emit', event, tag };
 }
 export function complete(output) {
     return { type: 'runtime.complete', output };
@@ -89,8 +159,10 @@ export function complete(output) {
 export function fail(error) {
     return { type: 'runtime.fail', error };
 }
-export function cancel(threadId) {
-    return { type: 'runtime.cancel', threadId };
+export function cancel(threadId, tag) {
+    return tag === undefined
+        ? { type: 'runtime.cancel', threadId }
+        : { type: 'runtime.cancel', threadId, tag };
 }
 export function invoke(typeOrDef, input, tag) {
     const type = Predicate.isString(typeOrDef) ? typeOrDef : typeOrDef.type;