@swirls/looms 0.3.0 → 0.4.0

package/dist/debugger/app/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Looms debugger</title>
-    <script type="module" crossorigin src="./assets/index-BevQYa-U.js"></script>
+    <script type="module" crossorigin src="./assets/index-D--9esm9.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/rolldown-runtime-CbXtAM7H.js">
     <link rel="stylesheet" crossorigin href="./assets/index-CgDzWJg7.css">
   </head>

package/dist/evaluator/effects.d.ts

@@ -6,39 +6,6 @@ export declare const evaluateEffect: NoInfer<import("@swirls/looms/core").Effect
     readonly definitionName?: string | undefined;
     readonly input?: Schema.Json | undefined;
 }, EvaluatorDefinitionsTag | EvaluatorTag, (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
-    readonly type: "evaluator.evaluated";
-    readonly payload: {
-        readonly evaluationId: string;
-        readonly definitionName?: string | undefined;
-        readonly answers: {
-            readonly [x: string]: {
-                readonly type: "boolean";
-                readonly value: boolean;
-                readonly probability: number;
-            } | {
-                readonly type: "choice";
-                readonly value: string;
-            } | {
-                readonly type: "score";
-                readonly value: number;
-            };
-        };
-        readonly route: string;
-        readonly reason: "model" | "skipped" | "unavailable" | "uncertain";
-        readonly usage?: {
-            readonly input: number;
-            readonly output: number;
-        } | undefined;
-    };
-}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
-    readonly type: "evaluator.requested";
-    readonly payload: {
-        readonly evaluationId: string;
-        readonly definitionName?: string | undefined;
-        readonly state: string;
-        readonly model?: string | undefined;
-    };
-}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.ambiguous";
     readonly payload: {
         readonly effectId: string;
@@ -235,4 +202,37 @@ export declare const evaluateEffect: NoInfer<import("@swirls/looms/core").Effect
             readonly payload: Schema.Json;
         };
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "evaluator.evaluated";
+    readonly payload: {
+        readonly evaluationId: string;
+        readonly definitionName?: string | undefined;
+        readonly answers: {
+            readonly [x: string]: {
+                readonly type: "boolean";
+                readonly value: boolean;
+                readonly probability: number;
+            } | {
+                readonly type: "choice";
+                readonly value: string;
+            } | {
+                readonly type: "score";
+                readonly value: number;
+            };
+        };
+        readonly route: string;
+        readonly reason: "model" | "skipped" | "unavailable" | "uncertain";
+        readonly usage?: {
+            readonly input: number;
+            readonly output: number;
+        } | undefined;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "evaluator.requested";
+    readonly payload: {
+        readonly evaluationId: string;
+        readonly definitionName?: string | undefined;
+        readonly state: string;
+        readonly model?: string | undefined;
+    };
 })>>;

package/dist/evaluator/module.d.ts

@@ -41,39 +41,6 @@ export declare function evaluator(options?: EvaluatorModuleOptions): import("@sw
         readonly definitionName?: string | undefined;
         readonly input?: import("effect/Schema").Json | undefined;
     }, import("./definitions-store").EvaluatorDefinitionsTag | EvaluatorTag, (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
-        readonly type: "evaluator.evaluated";
-        readonly payload: {
-            readonly evaluationId: string;
-            readonly definitionName?: string | undefined;
-            readonly answers: {
-                readonly [x: string]: {
-                    readonly type: "boolean";
-                    readonly value: boolean;
-                    readonly probability: number;
-                } | {
-                    readonly type: "choice";
-                    readonly value: string;
-                } | {
-                    readonly type: "score";
-                    readonly value: number;
-                };
-            };
-            readonly route: string;
-            readonly reason: "model" | "skipped" | "unavailable" | "uncertain";
-            readonly usage?: {
-                readonly input: number;
-                readonly output: number;
-            } | undefined;
-        };
-    }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
-        readonly type: "evaluator.requested";
-        readonly payload: {
-            readonly evaluationId: string;
-            readonly definitionName?: string | undefined;
-            readonly state: string;
-            readonly model?: string | undefined;
-        };
-    }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
         readonly type: "runtime.effect.ambiguous";
         readonly payload: {
             readonly effectId: string;
@@ -270,6 +237,39 @@ export declare function evaluator(options?: EvaluatorModuleOptions): import("@sw
                 readonly payload: import("effect/Schema").Json;
             };
         };
+    }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+        readonly type: "evaluator.evaluated";
+        readonly payload: {
+            readonly evaluationId: string;
+            readonly definitionName?: string | undefined;
+            readonly answers: {
+                readonly [x: string]: {
+                    readonly type: "boolean";
+                    readonly value: boolean;
+                    readonly probability: number;
+                } | {
+                    readonly type: "choice";
+                    readonly value: string;
+                } | {
+                    readonly type: "score";
+                    readonly value: number;
+                };
+            };
+            readonly route: string;
+            readonly reason: "model" | "skipped" | "unavailable" | "uncertain";
+            readonly usage?: {
+                readonly input: number;
+                readonly output: number;
+            } | undefined;
+        };
+    }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+        readonly type: "evaluator.requested";
+        readonly payload: {
+            readonly evaluationId: string;
+            readonly definitionName?: string | undefined;
+            readonly state: string;
+            readonly model?: string | undefined;
+        };
     })>;
 }, {
     evaluator: import("@swirls/looms/core").ThreadDefinition<{
@@ -336,39 +336,6 @@ export declare function evaluator(options?: EvaluatorModuleOptions): import("@sw
             readonly definitionName?: string | undefined;
             readonly input?: import("effect/Schema").Json | undefined;
         }, import("./definitions-store").EvaluatorDefinitionsTag | EvaluatorTag, (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
-            readonly type: "evaluator.evaluated";
-            readonly payload: {
-                readonly evaluationId: string;
-                readonly definitionName?: string | undefined;
-                readonly answers: {
-                    readonly [x: string]: {
-                        readonly type: "boolean";
-                        readonly value: boolean;
-                        readonly probability: number;
-                    } | {
-                        readonly type: "choice";
-                        readonly value: string;
-                    } | {
-                        readonly type: "score";
-                        readonly value: number;
-                    };
-                };
-                readonly route: string;
-                readonly reason: "model" | "skipped" | "unavailable" | "uncertain";
-                readonly usage?: {
-                    readonly input: number;
-                    readonly output: number;
-                } | undefined;
-            };
-        }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
-            readonly type: "evaluator.requested";
-            readonly payload: {
-                readonly evaluationId: string;
-                readonly definitionName?: string | undefined;
-                readonly state: string;
-                readonly model?: string | undefined;
-            };
-        }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
             readonly type: "runtime.effect.ambiguous";
             readonly payload: {
                 readonly effectId: string;
@@ -565,6 +532,39 @@ export declare function evaluator(options?: EvaluatorModuleOptions): import("@sw
                     readonly payload: import("effect/Schema").Json;
                 };
             };
+        }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+            readonly type: "evaluator.evaluated";
+            readonly payload: {
+                readonly evaluationId: string;
+                readonly definitionName?: string | undefined;
+                readonly answers: {
+                    readonly [x: string]: {
+                        readonly type: "boolean";
+                        readonly value: boolean;
+                        readonly probability: number;
+                    } | {
+                        readonly type: "choice";
+                        readonly value: string;
+                    } | {
+                        readonly type: "score";
+                        readonly value: number;
+                    };
+                };
+                readonly route: string;
+                readonly reason: "model" | "skipped" | "unavailable" | "uncertain";
+                readonly usage?: {
+                    readonly input: number;
+                    readonly output: number;
+                } | undefined;
+            };
+        }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+            readonly type: "evaluator.requested";
+            readonly payload: {
+                readonly evaluationId: string;
+                readonly definitionName?: string | undefined;
+                readonly state: string;
+                readonly model?: string | undefined;
+            };
         })>;
     };
     readonly threads: {

package/dist/react/derived.d.ts

@@ -1,19 +1,37 @@
-import { type EventEnvelope, type ProjectionDefinition } from '@swirls/looms/core';
-import type { AnyEventEnvelope, RegisteredEvent } from './register';
-export type { AnyEventEnvelope } from './register';
+import { type AnyEventEnvelope, type EventEnvelope, type InferSchemaOutput, type ProjectionDefinition, type RegisteredEvent, type SchemaInput } from '@swirls/looms/core';
 export { EventIndex, eventThreadKey } from '@swirls/looms/core';
-export interface EventFoldDefinition<S, TEvent extends AnyEventEnvelope = RegisteredEvent> {
+export interface LiveFoldDefinition<S, TEvent extends AnyEventEnvelope = RegisteredEvent> {
+    readonly kind: 'liveFold';
     readonly name?: string;
+    readonly shape?: unknown;
     readonly initialState: S;
     reduce(state: S, event: TEvent): S;
-    readonly includeEphemeral?: boolean;
 }
-export declare function createFold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(def: EventFoldDefinition<S, TEvent>): EventFoldDefinition<S, TEvent>;
-export declare function foldEvents<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(definition: EventFoldDefinition<S, TEvent>, events: readonly TEvent[], from?: S): S;
+/**
+ * Client-side fold that sees ephemeral events, which projections skip. Ephemeral events from an
+ * effect attempt that the runtime later retried never reach the reducer. The reducer still owns
+ * resets on domain events, such as the durable message that replaces streamed text. Use a
+ * projection for anything else.
+ */
+export declare function defineLiveFold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(def: {
+    readonly name?: string;
+    readonly shape?: undefined;
+    readonly initialState: S;
+    reduce(state: S, event: TEvent): S;
+}): LiveFoldDefinition<S, TEvent>;
+export declare function defineLiveFold<TShape extends SchemaInput, TEvent extends AnyEventEnvelope = RegisteredEvent>(def: {
+    readonly name?: string;
+    readonly shape: TShape;
+    readonly initialState: InferSchemaOutput<TShape>;
+    reduce(state: NoInfer<InferSchemaOutput<TShape>>, event: TEvent): InferSchemaOutput<TShape>;
+}): LiveFoldDefinition<InferSchemaOutput<TShape>, TEvent>;
+/** Fold events through a live fold, as `useLiveFold` does, including ephemeral events. */
+export declare function foldLive<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(definition: LiveFoldDefinition<S, TEvent>, events: readonly TEvent[]): S;
 export declare class ProjectionCache {
     private projectionCache;
     private foldCache;
     project<S>(definition: ProjectionDefinition<S>, events: readonly EventEnvelope[]): S;
-    fold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(definition: EventFoldDefinition<S, TEvent>, events: readonly TEvent[]): S;
+    /** A retry can supersede events already folded, so a batch containing one refolds from scratch. */
+    fold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(definition: LiveFoldDefinition<S, TEvent>, events: readonly TEvent[]): S;
     clear(): void;
 }

package/dist/react/derived.js

@@ -1,37 +1,33 @@
-import { project } from '@swirls/looms/core';
+import { dropSupersededAttempts, project, retriedEffectId, } from '@swirls/looms/core';
 export { EventIndex, eventThreadKey } from '@swirls/looms/core';
-export function createFold(def) {
-    return def;
+export function defineLiveFold(def) {
+    return { ...def, kind: 'liveFold' };
 }
-export function foldEvents(definition, events, from) {
-    let state = from !== undefined ? from : definition.initialState;
-    const includeEphemeral = definition.includeEphemeral ?? false;
-    for (const event of events) {
-        if (event.ephemeral && !includeEphemeral) {
-            continue;
-        }
+function foldFrom(definition, events, from) {
+    let state = from;
+    for (const event of dropSupersededAttempts(events)) {
         state = definition.reduce(state, event);
     }
     return state;
 }
-function advanceCache(cache, definition, events, compute) {
-    const total = events.length;
+/** Fold events through a live fold, as `useLiveFold` does, including ephemeral events. */
+export function foldLive(definition, events) {
+    return foldFrom(definition, events, definition.initialState);
+}
+function hasNoRetries(batch) {
+    return !batch.some((event) => retriedEffectId(event) !== undefined);
+}
+/** Folds only the events appended since the last call, unless `canAppend` rejects them. */
+function advanceCache(cache, definition, events, compute, canAppend = () => true) {
     const cached = cache.get(definition);
-    if (!cached) {
-        const state = compute(definition, events);
-        cache.set(definition, { state, upTo: total });
-        return state;
-    }
-    if (cached.upTo === total) {
+    if (cached?.upTo === events.length) {
         return cached.state;
     }
-    if (cached.upTo < total) {
-        const state = compute(definition, events.slice(cached.upTo), cached.state);
-        cache.set(definition, { state, upTo: total });
-        return state;
-    }
-    const state = compute(definition, events);
-    cache.set(definition, { state, upTo: total });
+    const batch = cached && cached.upTo < events.length ? events.slice(cached.upTo) : undefined;
+    const state = cached && batch && canAppend(batch)
+        ? compute(definition, batch, cached.state)
+        : compute(definition, events, definition.initialState);
+    cache.set(definition, { state, upTo: events.length });
     return state;
 }
 export class ProjectionCache {
@@ -40,8 +36,9 @@ export class ProjectionCache {
     project(definition, events) {
         return advanceCache(this.projectionCache, definition, events, project);
     }
+    /** A retry can supersede events already folded, so a batch containing one refolds from scratch. */
     fold(definition, events) {
-        return advanceCache(this.foldCache, definition, events, foldEvents);
+        return advanceCache(this.foldCache, definition, events, foldFrom, hasNoRetries);
     }
     clear() {
         this.projectionCache = new WeakMap();

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 export { createLoomsStore, type LoomsClientStore, type LoomsClientStoreOptions, type LoomsConnectionStatus, type LoomsStoreQuery, type CoalesceOption, type StoreListener, } from './store';
-export { createFold, foldEvents, EventIndex, eventThreadKey, type EventFoldDefinition, } from './derived';
+export { defineLiveFold, foldLive, EventIndex, eventThreadKey, type LiveFoldDefinition, } from './derived';
 export { materializeEvents } from './materialize';
 export { emptyTables, type MaterializedTables, type RunRow, type ThreadRow } from './tables';
-export type { LoomsRegister, RegisteredEvent, AnyEventEnvelope } from './register';
-export { LoomsProvider, useRunStore, useProjection, useRunSelector, useRunSummary, useRunEvents, useThreadTree, useEventCounts, useEventBySeq, useLatestEvent, useEventFold, type LoomsProviderProps, type UseRunStoreOptions, type RunSummary, } from './react';
+export type { LoomsRegister, RegisteredEvent, AnyEventEnvelope } from '@swirls/looms/core';
+export { LoomsProvider, useRunStore, useProjection, useRunSelector, useRunSummary, useRunEvents, useThreadTree, useEventCounts, useEventBySeq, useLatestEvent, useLiveFold, type LoomsProviderProps, type UseRunStoreOptions, type RunSummary, } from './react';

package/dist/react/index.js

@@ -1,5 +1,5 @@
 export { createLoomsStore, } from './store.js';
-export { createFold, foldEvents, EventIndex, eventThreadKey, } from './derived.js';
+export { defineLiveFold, foldLive, EventIndex, eventThreadKey, } from './derived.js';
 export { materializeEvents } from './materialize.js';
 export { emptyTables } from './tables.js';
-export { LoomsProvider, useRunStore, useProjection, useRunSelector, useRunSummary, useRunEvents, useThreadTree, useEventCounts, useEventBySeq, useLatestEvent, useEventFold, } from './react.js';
+export { LoomsProvider, useRunStore, useProjection, useRunSelector, useRunSummary, useRunEvents, useThreadTree, useEventCounts, useEventBySeq, useLatestEvent, useLiveFold, } from './react.js';

package/dist/react/react.d.ts

@@ -1,7 +1,6 @@
 import { type ReactNode } from 'react';
-import { type ProjectionDefinition, type RunStatus, type ThreadTree } from '@swirls/looms/core';
-import { createFold, foldEvents, type EventFoldDefinition } from './derived';
-import type { AnyEventEnvelope, RegisteredEvent } from './register';
+import { type AnyEventEnvelope, type ProjectionDefinition, type RegisteredEvent, type RunStatus, type ThreadTree } from '@swirls/looms/core';
+import { defineLiveFold, foldLive, type LiveFoldDefinition } from './derived';
 import { createLoomsStore, type CoalesceOption, type LoomsClientStore, type LoomsConnectionStatus } from './store';
 export interface LoomsProviderProps {
     children: ReactNode;
@@ -55,10 +54,10 @@ export declare function useEventCounts<TEvent extends AnyEventEnvelope = Registe
 export declare function useEventBySeq<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, seq: number | undefined): TEvent | undefined;
 /** Subscribe to the latest event of a given type. */
 export declare function useLatestEvent<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, type: string): TEvent | undefined;
-/** Subscribe to a custom incremental fold. */
-export declare function useEventFold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, fold: EventFoldDefinition<S, TEvent>): S;
+/** Subscribe to a live fold, which includes ephemeral events. */
+export declare function useLiveFold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, fold: LiveFoldDefinition<S, TEvent>): S;
 export { createLoomsStore };
-export { createFold, foldEvents };
+export { defineLiveFold, foldLive };
 export type { LoomsClientStore, LoomsClientStoreOptions, LoomsConnectionStatus, LoomsStoreQuery, CoalesceOption, StoreListener, } from './store';
-export type { EventFoldDefinition } from './derived';
-export type { LoomsRegister, RegisteredEvent, AnyEventEnvelope } from './register';
+export type { LiveFoldDefinition } from './derived';
+export type { LoomsRegister, RegisteredEvent, AnyEventEnvelope } from '@swirls/looms/core';

package/dist/react/react.js

@@ -1,7 +1,7 @@
 import { Effect, Fiber } from 'effect';
 import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
 import { isTerminalStatus, threadTree, toThreadTree, } from '@swirls/looms/core';
-import { createFold, foldEvents } from './derived.js';
+import { defineLiveFold, foldLive } from './derived.js';
 import { createLoomsStore, } from './store.js';
 const LoomsContext = createContext({ endpoint: '' });
 const GRACE_MS = 5_000;
@@ -165,10 +165,10 @@ export function useLatestEvent(store, type) {
     const selector = useCallback((s) => s.query.latest(type), [type]);
     return useRunSelector(store, selector);
 }
-/** Subscribe to a custom incremental fold. */
-export function useEventFold(store, fold) {
+/** Subscribe to a live fold, which includes ephemeral events. */
+export function useLiveFold(store, fold) {
     const getSnapshot = useCallback(() => store.fold(fold), [store, fold]);
     return useStoreSnapshot(store, getSnapshot);
 }
 export { createLoomsStore };
-export { createFold, foldEvents };
+export { defineLiveFold, foldLive };

package/dist/react/store.d.ts

@@ -1,7 +1,6 @@
-import { type EventInput, type ProjectionDefinition } from '@swirls/looms/core';
-import { type EventFoldDefinition } from './derived';
+import { type AnyEventEnvelope, type EventInput, type ProjectionDefinition, type RegisteredEvent } from '@swirls/looms/core';
+import { type LiveFoldDefinition } from './derived';
 import { type CoalesceOption } from './notify';
-import type { AnyEventEnvelope, RegisteredEvent } from './register';
 import { type MaterializedTables } from './tables';
 export type { CoalesceOption } from './notify';
 /** Fired after the store version bumps. Re-read via `events()` / `getState()` / `query`. */
@@ -30,7 +29,7 @@ export interface LoomsStoreQuery<TEvent extends AnyEventEnvelope = RegisteredEve
     bySeq: (seq: number) => TEvent | undefined;
     startedAt: () => number | undefined;
     latest: (type: string) => TEvent | undefined;
-    fold: <S>(def: EventFoldDefinition<S, TEvent>) => S;
+    fold: <S>(def: LiveFoldDefinition<S, TEvent>) => S;
 }
 export interface LoomsClientStore<TEvent extends AnyEventEnvelope = RegisteredEvent> {
     storeId: string;
@@ -43,7 +42,7 @@ export interface LoomsClientStore<TEvent extends AnyEventEnvelope = RegisteredEv
     query: LoomsStoreQuery<TEvent>;
     subscribe: (listener: StoreListener) => () => void;
     project<S>(definition: ProjectionDefinition<S>): S;
-    fold<S>(definition: EventFoldDefinition<S, TEvent>): S;
+    fold<S>(definition: LiveFoldDefinition<S, TEvent>): S;
     flush: () => void;
     commit: (event: EventInput | readonly EventInput[]) => Promise<void>;
     sync: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swirls/looms",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pluggable event-sourced runtime for durable agents and workflows",
   "homepage": "https://github.com/ByteSliceHQ/looms#readme",
   "bugs": {
@@ -137,7 +137,7 @@
   },
   "scripts": {
     "build": "bun run scripts/assemble.ts",
-    "check-types": "bun -e \"void 0\"",
+    "check-types": "bun x tsc -p type-tests/unregistered/tsconfig.json --noEmit && bun x tsc -p type-tests/registered/tsconfig.json --noEmit && bun x tsc -p type-tests/registered-core/tsconfig.json --noEmit",
     "test": "bun -e \"void 0\""
   },
   "dependencies": {