@swirls/looms 0.0.1 → 0.1.0

package/dist/core/envelope.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from 'effect';
-import type { JsonValue } from './types';
+import { type JsonValue } from './types';
 export declare const JsonValueSchema: Schema.Codec<Schema.Json, Schema.Json, never, never>;
 export declare const EventOriginSchema: Schema.Union<readonly [Schema.Struct<{
     readonly type: Schema.Literal<"thread">;
@@ -14,8 +14,8 @@ export type EventOrigin = Schema.Schema.Type<typeof EventOriginSchema>;
 export declare const EventEnvelopeSchema: Schema.Struct<{
     readonly id: Schema.String;
     readonly runId: Schema.String;
-    readonly seq: Schema.Number;
-    readonly ts: Schema.Number;
+    readonly seq: Schema.Finite;
+    readonly ts: Schema.Finite;
     readonly type: Schema.String;
     readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly threadId: Schema.NullOr<Schema.String>;
@@ -35,6 +35,28 @@ export declare const EventEnvelopeSchema: Schema.Struct<{
     readonly ephemeral: Schema.optional<Schema.Boolean>;
     readonly idempotencyKey: Schema.optional<Schema.NullOr<Schema.String>>;
 }>;
+export declare const EventInputSchema: 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>>;
+}>;
 export type EventEnvelope<TType extends string = string, TPayload = JsonValue> = {
     id: string;
     runId: string;
@@ -71,9 +93,7 @@ export type AppendableEvent = Omit<EventEnvelope, 'seq'> & {
 };
 export declare function payloadAsJson(payload: JsonValue): JsonValue;
 export declare function withAssignedSeq(partial: AppendableEvent, runId: string, seq: number): EventEnvelope;
-export declare function createEvent<TType extends string>(runId: string, input: Omit<EventInput, 'type'> & {
-    type: TType;
-}, options?: {
+export declare function createEvent<TType extends string, TPayload = JsonValue>(runId: string, input: EventInput<TType, TPayload>, options?: {
     seq?: number;
-}): EventEnvelope<TType>;
+}): EventEnvelope<TType, TPayload>;
 export declare function fromWireEvent(wire: Schema.Schema.Type<typeof EventEnvelopeSchema>): EventEnvelope;

package/dist/core/envelope.js

@@ -1,5 +1,6 @@
-import { Schema } from 'effect';
+import { DateTime, Schema } from 'effect';
 import { createEventId } from './ids.js';
+import { cleanUndefined } from './types.js';
 export const JsonValueSchema = Schema.Json;
 export const EventOriginSchema = Schema.Union([
     Schema.Struct({
@@ -17,8 +18,8 @@ export const EventOriginSchema = Schema.Union([
 export const EventEnvelopeSchema = Schema.Struct({
     id: Schema.String,
     runId: Schema.String,
-    seq: Schema.Number,
-    ts: Schema.Number,
+    seq: Schema.Finite,
+    ts: Schema.Finite,
     type: Schema.String,
     payload: JsonValueSchema,
     threadId: Schema.NullOr(Schema.String),
@@ -30,9 +31,22 @@ export const EventEnvelopeSchema = Schema.Struct({
     ephemeral: Schema.optional(Schema.Boolean),
     idempotencyKey: Schema.optional(Schema.NullOr(Schema.String)),
 });
+export const EventInputSchema = Schema.Struct({
+    type: Schema.String,
+    payload: JsonValueSchema,
+    threadId: Schema.optional(Schema.NullOr(Schema.String)),
+    parentThreadId: Schema.optional(Schema.NullOr(Schema.String)),
+    causationId: Schema.optional(Schema.NullOr(Schema.String)),
+    correlationId: Schema.optional(Schema.NullOr(Schema.String)),
+    effectId: Schema.optional(Schema.NullOr(Schema.String)),
+    origin: Schema.optional(EventOriginSchema),
+    ephemeral: Schema.optional(Schema.Boolean),
+    id: Schema.optional(Schema.String),
+    ts: Schema.optional(Schema.Finite),
+    idempotencyKey: Schema.optional(Schema.NullOr(Schema.String)),
+});
 export function payloadAsJson(payload) {
-    // SAFETY: round-trip through JSON yields JsonValue.
-    return JSON.parse(JSON.stringify(payload));
+    return cleanUndefined(payload);
 }
 export function withAssignedSeq(partial, runId, seq) {
     return { ...partial, runId, seq };
@@ -44,7 +58,7 @@ export function createEvent(runId, input, options) {
         id: input.id ?? createEventId(),
         runId,
         seq: options?.seq ?? 0,
-        ts: input.ts ?? Date.now(),
+        ts: input.ts ?? DateTime.toEpochMillis(DateTime.nowUnsafe()),
         type: input.type,
         payload: input.payload,
         threadId,

package/dist/core/event-codec.d.ts

@@ -2,7 +2,9 @@ import type { AppendableEvent, EventEnvelope } from './envelope';
 import type { JsonValue } from './types';
 /** JSON-safe event envelope for SSE and pull responses. */
 export type EncodedLoomsEvent = EventEnvelope;
+type EventWireInput = JsonValue | Partial<EncodedLoomsEvent>;
 export declare function encodeLoomsEvent(event: EventEnvelope): EncodedLoomsEvent;
 export declare function encodeAppendableEvent(event: AppendableEvent): EncodedLoomsEvent;
-export declare function decodeLoomsEvent(raw: JsonValue | EncodedLoomsEvent, runId: string): EventEnvelope;
-export declare function decodeAppendableEvent(raw: JsonValue | EncodedLoomsEvent, runId: string): AppendableEvent | undefined;
+export declare function decodeLoomsEvent(raw: EventWireInput, runId: string): EventEnvelope;
+export declare function decodeAppendableEvent(raw: EventWireInput, runId: string): AppendableEvent | undefined;
+export {};

package/dist/core/event-codec.js

@@ -1,6 +1,7 @@
-import { Predicate } from 'effect';
+import { DateTime, Predicate, Schema } from 'effect';
 import { createEvent, payloadAsJson } from './envelope.js';
 import { createEventId } from './ids.js';
+const decodeJsonValue = Schema.decodeUnknownSync(Schema.Json);
 export function encodeLoomsEvent(event) {
     return {
         ...event,
@@ -12,7 +13,7 @@ export function encodeAppendableEvent(event) {
         id: event.id ?? createEventId(),
         runId: event.runId,
         seq: event.seq ?? 0,
-        ts: event.ts ?? Date.now(),
+        ts: event.ts ?? DateTime.toEpochMillis(DateTime.nowUnsafe()),
         type: event.type,
         payload: payloadAsJson(event.payload),
         threadId: event.threadId ?? null,
@@ -25,6 +26,9 @@ export function encodeAppendableEvent(event) {
     };
 }
 function readOrigin(raw) {
+    if (!Predicate.isReadonlyObject(raw)) {
+        return { type: 'system' };
+    }
     if ('type' in raw && raw.type === 'thread') {
         const threadId = 'threadId' in raw && Predicate.isString(raw.threadId) ? raw.threadId : '';
         return { type: 'thread', threadId };
@@ -41,10 +45,11 @@ export function decodeLoomsEvent(raw, runId) {
     }
     if ('type' in raw && Predicate.isString(raw.type)) {
         const rawPayload = 'payload' in raw ? raw.payload : {};
-        // SAFETY: payload is JSON-compatible.
-        const payload = rawPayload;
+        const payload = decodeJsonValue(rawPayload);
         const id = 'id' in raw && Predicate.isString(raw.id) ? raw.id : createEventId();
-        const ts = 'ts' in raw && Predicate.isNumber(raw.ts) ? raw.ts : Date.now();
+        const ts = 'ts' in raw && Predicate.isNumber(raw.ts)
+            ? raw.ts
+            : DateTime.toEpochMillis(DateTime.nowUnsafe());
         const seq = 'seq' in raw && Predicate.isNumber(raw.seq) ? raw.seq : 0;
         const ephemeral = 'ephemeral' in raw && Predicate.isBoolean(raw.ephemeral) ? raw.ephemeral : false;
         const itemRunId = 'runId' in raw && Predicate.isString(raw.runId) ? raw.runId : runId;

package/dist/core/event-index.js

@@ -1,4 +1,3 @@
-const EMPTY_EVENTS = Object.freeze([]);
 /** Thread bucket key used by run-tree counts (`threadId` or `'run'` for run-scoped). */
 export function eventThreadKey(event) {
     return event.threadId ?? 'run';
@@ -60,8 +59,7 @@ export class EventIndex {
     }
     getByThread(threadId) {
         this.publish();
-        // SAFETY: EMPTY_EVENTS is an empty frozen array compatible with any TEvent[].
-        return this.byThreadSnapshots.get(threadId) ?? EMPTY_EVENTS;
+        return this.byThreadSnapshots.get(threadId) ?? [];
     }
     getBySeq(seq) {
         return this.bySeqMap.get(seq);

package/dist/core/fold.d.ts

@@ -1,10 +1,13 @@
 import { Stream, type Effect } from 'effect';
+import { type RuntimeEffect } from './effects';
 import type { EventEnvelope } from './envelope';
 import type { RunState } from './state';
 import { type ThreadDefinition } from './thread';
 export interface FoldRegistry {
     readonly threads: ReadonlyMap<string, ThreadDefinition>;
 }
+/** The id an effect keeps across folds when it names itself by tag, wait id, or child thread. */
+export declare function stableEffectId(threadId: string, effect: RuntimeEffect): string | undefined;
 export declare function foldEvent(state: RunState, event: EventEnvelope, registry: FoldRegistry): RunState;
 export declare function foldRun(events: readonly EventEnvelope[], registry: FoldRegistry, options?: {
     runId?: string;

package/dist/core/fold.js

@@ -1,8 +1,10 @@
-import { Predicate, Stream } from 'effect';
-import { isWithdrawnError } from './effects.js';
+import { Option, Predicate, Schema, Stream } from 'effect';
+import { isWithdrawnError, WaitConditionSchema } from './effects.js';
 import { createEffectId } from './ids.js';
+import { DEFAULT_DEFINITION_VERSION } from './module.js';
 import { emptyRunState } from './state.js';
 import { isTerminalStatus } from './thread.js';
+const decodeWaitCondition = Schema.decodeUnknownOption(WaitConditionSchema);
 function payloadObject(event) {
     const payload = event.payload;
     if (payload === null || Array.isArray(payload)) {
@@ -22,9 +24,11 @@ function cloneState(state) {
         runId: state.runId,
         status: state.status,
         rootThreadId: state.rootThreadId,
+        startIdentity: state.startIdentity,
         threads: { ...state.threads },
         waits: { ...state.waits },
         outstandingEffects: [...state.outstandingEffects],
+        effectExecutions: { ...state.effectExecutions },
         completedEffectIds: state.completedEffectIds ? [...state.completedEffectIds] : [],
         processedIdempotencyKeys: state.processedIdempotencyKeys
             ? [...state.processedIdempotencyKeys]
@@ -33,9 +37,11 @@ function cloneState(state) {
 }
 function completeEffect(state, effectId) {
     const completed = state.completedEffectIds ?? [];
+    const { [effectId]: _completedExecution, ...effectExecutions } = state.effectExecutions ?? {};
     return {
         ...state,
         outstandingEffects: state.outstandingEffects.filter((item) => item.effectId !== effectId),
+        effectExecutions,
         completedEffectIds: completed.includes(effectId) ? completed : [...completed, effectId],
     };
 }
@@ -75,18 +81,41 @@ function applyProtocol(state, event, registry) {
     const payload = payloadObject(event);
     switch (event.type) {
         case 'runtime.run.started': {
-            const rootThreadId = readString(payload, 'rootThreadId') ?? null;
-            return { ...state, runId: event.runId, rootThreadId, status: 'running' };
+            const rootThreadId = readString(payload, 'rootThreadId');
+            const kind = readString(payload, 'kind');
+            const definitionName = readString(payload, 'definitionName');
+            const definitionVersion = readString(payload, 'definitionVersion') ?? DEFAULT_DEFINITION_VERSION;
+            const startIdentity = rootThreadId && kind && definitionName && definitionVersion
+                ? {
+                    kind,
+                    definitionName,
+                    definitionVersion,
+                    input: payload.input ?? null,
+                    requestedThreadId: readString(payload, 'requestedThreadId') ?? null,
+                    idempotencyKey: event.idempotencyKey ?? null,
+                    rootThreadId,
+                }
+                : null;
+            return {
+                ...state,
+                runId: event.runId,
+                rootThreadId: rootThreadId ?? null,
+                startIdentity,
+                status: 'running',
+            };
         }
         case 'runtime.run.completed': {
             const error = payload.error;
             const status = Predicate.isString(error) && error.length > 0 ? 'failed' : 'completed';
             return { ...state, status };
         }
+        case 'runtime.run.cancelled':
+            return { ...state, status: 'cancelled' };
         case 'runtime.thread.started': {
             const threadId = readString(payload, 'threadId') ?? event.threadId;
             const kind = readString(payload, 'kind');
             const definitionName = readString(payload, 'definitionName');
+            const definitionVersion = readString(payload, 'definitionVersion') ?? DEFAULT_DEFINITION_VERSION;
             if (!threadId || !kind || !definitionName) {
                 return state;
             }
@@ -98,6 +127,7 @@ function applyProtocol(state, event, registry) {
                 threadId,
                 kind,
                 definitionName,
+                definitionVersion,
                 parentThreadId,
                 status: definition ? 'running' : 'failed',
                 input,
@@ -109,6 +139,7 @@ function applyProtocol(state, event, registry) {
                         threadId,
                         parentThreadId,
                         definitionName,
+                        definitionVersion,
                         input,
                     })
                     : {},
@@ -156,7 +187,7 @@ function applyProtocol(state, event, registry) {
                 return state;
             }
             const existing = state.threads[threadId];
-            if (!existing) {
+            if (!existing || isTerminalStatus(existing.status)) {
                 return state;
             }
             return dropThreadWork(putThread(state, {
@@ -165,6 +196,111 @@ function applyProtocol(state, event, registry) {
                 error: readString(payload, 'reason') ?? existing.error,
             }), threadId);
         }
+        case 'runtime.effect.attempt.started': {
+            const effectId = readString(payload, 'effectId');
+            const attempt = payload.attempt;
+            if (!effectId || !Predicate.isNumber(attempt)) {
+                return state;
+            }
+            return {
+                ...state,
+                effectExecutions: {
+                    ...state.effectExecutions,
+                    [effectId]: {
+                        effectId,
+                        attempt,
+                        status: 'running',
+                        nextAttemptAt: null,
+                        deadlineAt: null,
+                        startedAt: event.ts,
+                        lastHeartbeatAt: null,
+                        lastError: null,
+                    },
+                },
+            };
+        }
+        case 'runtime.effect.queued':
+        case 'runtime.effect.dispatched':
+        case 'runtime.effect.worker.started':
+        case 'runtime.effect.heartbeat':
+        case 'runtime.effect.cancel.requested':
+        case 'runtime.effect.timed_out':
+        case 'runtime.effect.ambiguous': {
+            const effectId = readString(payload, 'effectId');
+            const attempt = payload.attempt;
+            if (!effectId || !Predicate.isNumber(attempt)) {
+                return state;
+            }
+            const status = event.type === 'runtime.effect.queued'
+                ? 'queued'
+                : event.type === 'runtime.effect.dispatched'
+                    ? 'dispatched'
+                    : event.type === 'runtime.effect.worker.started'
+                        ? 'started'
+                        : event.type === 'runtime.effect.heartbeat'
+                            ? 'heartbeat'
+                            : event.type === 'runtime.effect.cancel.requested'
+                                ? 'cancel_requested'
+                                : event.type === 'runtime.effect.timed_out'
+                                    ? 'timed_out'
+                                    : 'ambiguous';
+            const deadlineAt = payload.deadlineAt;
+            const heartbeatAt = payload.heartbeatAt;
+            const previous = state.effectExecutions[effectId];
+            const sameAttempt = previous?.attempt === attempt;
+            return {
+                ...state,
+                effectExecutions: {
+                    ...state.effectExecutions,
+                    [effectId]: {
+                        effectId,
+                        attempt,
+                        status,
+                        nextAttemptAt: null,
+                        deadlineAt: Predicate.isNumber(deadlineAt) ? deadlineAt : null,
+                        startedAt: event.type === 'runtime.effect.worker.started'
+                            ? event.ts
+                            : sameAttempt
+                                ? previous.startedAt
+                                : null,
+                        lastHeartbeatAt: Predicate.isNumber(heartbeatAt)
+                            ? heartbeatAt
+                            : sameAttempt
+                                ? previous.lastHeartbeatAt
+                                : null,
+                        lastError: readString(payload, 'error') ?? null,
+                    },
+                },
+            };
+        }
+        case 'runtime.effect.cancelled': {
+            const effectId = readString(payload, 'effectId');
+            return effectId ? completeEffect(state, effectId) : state;
+        }
+        case 'runtime.effect.retry.scheduled': {
+            const effectId = readString(payload, 'effectId');
+            const attempt = payload.attempt;
+            const nextAttemptAt = payload.nextAttemptAt;
+            if (!effectId || !Predicate.isNumber(attempt) || !Predicate.isNumber(nextAttemptAt)) {
+                return state;
+            }
+            return {
+                ...state,
+                effectExecutions: {
+                    ...state.effectExecutions,
+                    [effectId]: {
+                        effectId,
+                        attempt,
+                        status: 'retry_wait',
+                        nextAttemptAt,
+                        deadlineAt: nextAttemptAt,
+                        startedAt: null,
+                        lastHeartbeatAt: null,
+                        lastError: readString(payload, 'error') ?? 'effect failed',
+                    },
+                },
+            };
+        }
         case 'runtime.wait.registered': {
             const waitId = readString(payload, 'waitId');
             const threadId = readString(payload, 'threadId') ?? event.threadId;
@@ -172,11 +308,14 @@ function applyProtocol(state, event, registry) {
             if (!waitId || !threadId || !on || !Predicate.isObject(on)) {
                 return state;
             }
-            // SAFETY: wait.registered payload.on is a WaitCondition written by the runtime.
+            const waitCondition = decodeWaitCondition(on);
+            if (Option.isNone(waitCondition)) {
+                return state;
+            }
             const record = {
                 waitId,
                 threadId,
-                on: on,
+                on: waitCondition.value,
             };
             if (payload.tag !== undefined) {
                 record.tag = payload.tag;
@@ -195,6 +334,16 @@ function applyProtocol(state, event, registry) {
             }
             const existingWait = state.waits[waitId];
             let next = removeWait(state, waitId);
+            const existingTag = Predicate.isObject(existingWait?.tag) ? existingWait.tag : undefined;
+            const raceId = existingTag && Predicate.isString(existingTag.raceId) ? existingTag.raceId : undefined;
+            if (raceId) {
+                for (const sibling of Object.values(next.waits)) {
+                    const siblingTag = Predicate.isObject(sibling.tag) ? sibling.tag : undefined;
+                    if (siblingTag?.raceId === raceId) {
+                        next = removeWait(next, sibling.waitId);
+                    }
+                }
+            }
             const threadId = existingWait?.threadId ?? event.threadId;
             if (!threadId) {
                 return next;
@@ -206,16 +355,19 @@ function applyProtocol(state, event, registry) {
             return next;
         }
         case 'runtime.snapshot.taken':
+        case 'runtime.thread.cancel.requested':
         case 'runtime.timer.set':
         case 'runtime.timer.fired':
         case 'runtime.effect.failed':
+        case 'runtime.effect.completed':
         case 'runtime.signal.received':
             return state;
         default:
             return state;
     }
 }
-function deriveEffectId(threadId, causingSeq, index, effect, existingId) {
+/** The id an effect keeps across folds when it names itself by tag, wait id, or child thread. */
+export function stableEffectId(threadId, effect) {
     if ('tag' in effect && Predicate.isString(effect.tag)) {
         return createEffectId(threadId, effect.tag);
     }
@@ -225,29 +377,21 @@ function deriveEffectId(threadId, causingSeq, index, effect, existingId) {
     if ('childThreadId' in effect && Predicate.isString(effect.childThreadId)) {
         return createEffectId(threadId, `spawn_${effect.childThreadId}`);
     }
-    if (existingId) {
-        return existingId;
+    if (effect.type === 'runtime.cancel' &&
+        'threadId' in effect &&
+        Predicate.isString(effect.threadId)) {
+        return createEffectId(threadId, `cancel_${effect.threadId}`);
     }
-    return createEffectId(threadId, causingSeq, index);
+    return undefined;
 }
 function mapEffects(threadId, event, effects, completed, existingForThread) {
     const remainingExisting = [...existingForThread];
     return effects
         .map((effect, index) => {
-        const matchIndex = remainingExisting.findIndex((item) => {
-            if ('tag' in effect && Predicate.isString(effect.tag)) {
-                return item.effectId === createEffectId(threadId, effect.tag);
-            }
-            if ('waitId' in effect && Predicate.isString(effect.waitId)) {
-                return item.effectId === createEffectId(threadId, effect.waitId);
-            }
-            if ('childThreadId' in effect && Predicate.isString(effect.childThreadId)) {
-                return item.effectId === createEffectId(threadId, `spawn_${effect.childThreadId}`);
-            }
-            return item.effect.type === effect.type;
-        });
+        const stableId = stableEffectId(threadId, effect);
+        const matchIndex = remainingExisting.findIndex((item) => stableId === undefined ? item.effect.type === effect.type : item.effectId === stableId);
         const existing = matchIndex >= 0 ? remainingExisting.splice(matchIndex, 1)[0] : undefined;
-        const effectId = deriveEffectId(threadId, event.seq, index, effect, existing?.effectId);
+        const effectId = stableId ?? existing?.effectId ?? createEffectId(threadId, event.seq, index);
         return (existing ?? {
             effectId,
             threadId,
@@ -285,6 +429,9 @@ function deliver(state, event, registry) {
     if (!record) {
         return state;
     }
+    if (isTerminalStatus(record.status)) {
+        return state;
+    }
     const definition = registry.threads.get(record.kind);
     if (!definition) {
         return state;

package/dist/core/ids.d.ts

@@ -1,6 +1,11 @@
 export declare function createEventId(): string;
 export declare function createRunId(): string;
 export declare function createThreadId(): string;
+/**
+ * A UUID-shaped id derived only from `parts`, so a reducer that replays the same events names the same
+ * child thread every time.
+ */
+export declare function deterministicThreadId(...parts: readonly (string | number)[]): string;
 export declare function createWaitId(scope?: string, tag?: string | number): string;
 export declare function createEffectId(threadId: string, causingSeqOrTag: number | string, index?: number): string;
 export declare function parseEffectId(effectId: string): {

package/dist/core/ids.js

@@ -1,8 +1,12 @@
-import { Predicate } from 'effect';
+import { DateTime, Predicate } from 'effect';
 let counter = 0;
 function token() {
     counter += 1;
-    return `${Date.now().toString(36)}_${counter.toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+    const timestamp = DateTime.toEpochMillis(DateTime.nowUnsafe());
+    // Synchronous ID factories need process-independent entropy without an Effect runtime.
+    // oxlint-disable-next-line effecttsgo/crypto-random-uuid
+    const entropy = globalThis.crypto.randomUUID().replaceAll('-', '');
+    return `${timestamp.toString(36)}_${counter.toString(36)}_${entropy}`;
 }
 export function createEventId() {
     return `evt_${token()}`;
@@ -13,6 +17,35 @@ export function createRunId() {
 export function createThreadId() {
     return `thr_${token()}`;
 }
+function fnv1a32(value, seed) {
+    let hash = seed >>> 0;
+    for (let index = 0; index < value.length; index++) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * A UUID-shaped id derived only from `parts`, so a reducer that replays the same events names the same
+ * child thread every time.
+ */
+export function deterministicThreadId(...parts) {
+    const source = parts.join(':');
+    let reversed = '';
+    for (let index = source.length - 1; index >= 0; index--) {
+        reversed += source.charAt(index);
+    }
+    const hex = [
+        fnv1a32(source, 0x811c9dc5),
+        fnv1a32(source, 0x9e3779b9),
+        fnv1a32(reversed, 0x85ebca6b),
+        fnv1a32(reversed, 0xc2b2ae35),
+    ].join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-${((Number.parseInt(hex.slice(16, 18), 16) & 0x3f) |
+        0x80)
+        .toString(16)
+        .padStart(2, '0')}${hex.slice(18, 20)}-${hex.slice(20)}`;
+}
 export function createWaitId(scope, tag) {
     if (scope !== undefined && tag !== undefined) {
         return `wait_${scope}_${tag}`;

package/dist/core/index.d.ts

@@ -1,6 +1,7 @@
 export type * from './types';
-export { asJson, cleanUndefined, fromJsonStruct, isJsonNumber, isJsonObject, isJsonString, } from './types';
+export { asJson, cleanUndefined, isJsonNumber, isJsonObject, isJsonString, stringifyJson, stringifyJsonPretty, } from './types';
 export * from './ids';
+export * from './worker-callback';
 export * from './schema';
 export * from './validate-event';
 export * from './envelope';
@@ -14,6 +15,7 @@ export * from './fold';
 export * from './replay';
 export * from './projection';
 export * from './module';
+export * from './kind';
 export * from './module-scope';
 export * from './compose';
 export * from './store';
@@ -24,3 +26,5 @@ export * from './event-codec';
 export * from './serialize';
 export * from './coalesce';
 export * from './event-index';
+export * from './limits';
+export * from './definition-store';

package/dist/core/index.js

@@ -1,5 +1,6 @@
-export { asJson, cleanUndefined, fromJsonStruct, isJsonNumber, isJsonObject, isJsonString, } from './types.js';
+export { asJson, cleanUndefined, isJsonNumber, isJsonObject, isJsonString, stringifyJson, stringifyJsonPretty, } from './types.js';
 export * from './ids.js';
+export * from './worker-callback.js';
 export * from './schema.js';
 export * from './validate-event.js';
 export * from './envelope.js';
@@ -13,6 +14,7 @@ export * from './fold.js';
 export * from './replay.js';
 export * from './projection.js';
 export * from './module.js';
+export * from './kind.js';
 export * from './module-scope.js';
 export * from './compose.js';
 export * from './store.js';
@@ -23,3 +25,5 @@ export * from './event-codec.js';
 export * from './serialize.js';
 export * from './coalesce.js';
 export * from './event-index.js';
+export * from './limits.js';
+export * from './definition-store.js';

package/dist/core/kind.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stamp a startable `{ kind, name }` definition.
+ *
+ * `defineAgent` and `defineWorkflow` are specialized helpers for those kinds.
+ * Custom thread types should use `createKind` / `defineKind` instead of
+ * assembling the object by hand.
+ */
+export declare function defineKind<TKind extends string, TDef extends {
+    readonly name: string;
+}>(kind: TKind, def: TDef): TDef & {
+    readonly kind: TKind;
+};
+export interface KindBuilder<TKind extends string> {
+    readonly kind: TKind;
+    define<TDef extends {
+        readonly name: string;
+    }>(def: TDef): TDef & {
+        readonly kind: TKind;
+    };
+}
+/** Bind `define` to one kind so each custom type has a builder, like `defineAgent`. */
+export declare function createKind<TKind extends string>(kind: TKind): KindBuilder<TKind>;

package/dist/core/kind.js

@@ -0,0 +1,17 @@
+/**
+ * Stamp a startable `{ kind, name }` definition.
+ *
+ * `defineAgent` and `defineWorkflow` are specialized helpers for those kinds.
+ * Custom thread types should use `createKind` / `defineKind` instead of
+ * assembling the object by hand.
+ */
+export function defineKind(kind, def) {
+    return { ...def, kind };
+}
+/** Bind `define` to one kind so each custom type has a builder, like `defineAgent`. */
+export function createKind(kind) {
+    return {
+        kind,
+        define: (def) => defineKind(kind, def),
+    };
+}