@swirls/looms 0.2.0 → 0.4.0

package/dist/projectors/index-model.d.ts

@@ -1,6 +1,8 @@
-import type { EventEnvelope } from '@swirls/looms/core';
+import { type EventEnvelope } from '@swirls/looms/core';
 import type { Projector } from './projector';
+/** A run (`actorId === runId`) or one of its threads. Thread ids are unique within a run. */
 export interface ActorIndexRow {
+    runId: string;
     actorId: string;
     kind: string | null;
     status: string | null;
@@ -9,14 +11,15 @@ export interface ActorIndexRow {
     updatedAt: number;
 }
 export interface ReviewIndexRow {
+    runId: string;
     reviewId: string;
-    actorId: string;
     status: string;
     title: string;
     updatedAt: number;
 }
 export type IndexOp = {
     type: 'upsertActor';
+    runId: string;
     actorId: string;
     kind: string | null;
     status: string | null;
@@ -25,32 +28,35 @@ export type IndexOp = {
     updatedAt: number;
 } | {
     type: 'setActorStatus';
+    runId: string;
     actorId: string;
     status: string;
     updatedAt: number;
 } | {
     type: 'upsertReview';
+    runId: string;
     reviewId: string;
-    actorId: string;
     status: string;
     title: string;
     updatedAt: number;
 } | {
     type: 'setReviewStatus';
+    runId: string;
     reviewId: string;
     status: string;
     updatedAt: number;
 };
 export interface IndexBackend {
     applyOps: (ops: ReadonlyArray<IndexOp>) => Promise<void>;
-    getActor: (actorId: string) => Promise<ActorIndexRow | null>;
-    listReviews: (actorId?: string) => Promise<ReviewIndexRow[]>;
+    getActor: (runId: string, actorId: string) => Promise<ActorIndexRow | null>;
+    listReviews: (runId?: string) => Promise<ReviewIndexRow[]>;
     init?: () => Promise<void>;
     dispose?: () => Promise<void>;
 }
 export interface IndexProjector extends Projector {
-    getActor: (actorId: string) => Promise<ActorIndexRow | null>;
-    listReviews: (actorId?: string) => Promise<ReviewIndexRow[]>;
+    /** The run's row, or one of its threads when `actorId` is given. */
+    getActor: (runId: string, actorId?: string) => Promise<ActorIndexRow | null>;
+    listReviews: (runId?: string) => Promise<ReviewIndexRow[]>;
 }
 export declare function indexOpsFor(event: EventEnvelope): IndexOp[];
 export declare function createIndexProjector(name: string, backend: IndexBackend, version?: string): IndexProjector;

package/dist/projectors/index-model.js

@@ -1,4 +1,5 @@
 import { Predicate } from 'effect';
+import { completedRunStatus } from '@swirls/looms/core';
 function payloadObject(event) {
     if (!Predicate.isObject(event.payload)) {
         return {};
@@ -11,12 +12,15 @@ function readString(obj, key) {
 }
 export function indexOpsFor(event) {
     const payload = payloadObject(event);
+    const runId = event.runId;
+    const actorId = readString(payload, 'threadId') ?? event.threadId ?? runId;
     switch (event.type) {
         case 'runtime.run.started':
             return [
                 {
                     type: 'upsertActor',
-                    actorId: event.runId,
+                    runId,
+                    actorId: runId,
                     kind: readString(payload, 'kind') ?? null,
                     status: 'running',
                     definitionName: readString(payload, 'definitionName') ?? null,
@@ -28,7 +32,8 @@ export function indexOpsFor(event) {
             return [
                 {
                     type: 'upsertActor',
-                    actorId: readString(payload, 'threadId') ?? event.threadId ?? event.runId,
+                    runId,
+                    actorId,
                     kind: readString(payload, 'kind') ?? null,
                     status: 'running',
                     definitionName: readString(payload, 'definitionName') ?? null,
@@ -37,39 +42,28 @@ export function indexOpsFor(event) {
                 },
             ];
         case 'runtime.run.completed':
-        case 'runtime.thread.completed':
             return [
                 {
                     type: 'setActorStatus',
-                    actorId: readString(payload, 'threadId') ?? event.threadId ?? event.runId,
-                    status: 'completed',
+                    runId,
+                    actorId: runId,
+                    status: completedRunStatus(event.payload),
                     updatedAt: event.ts,
                 },
             ];
+        case 'runtime.thread.completed':
+            return [{ type: 'setActorStatus', runId, actorId, status: 'completed', updatedAt: event.ts }];
         case 'runtime.thread.failed':
-            return [
-                {
-                    type: 'setActorStatus',
-                    actorId: readString(payload, 'threadId') ?? event.threadId ?? event.runId,
-                    status: 'failed',
-                    updatedAt: event.ts,
-                },
-            ];
+            return [{ type: 'setActorStatus', runId, actorId, status: 'failed', updatedAt: event.ts }];
+        case 'runtime.run.cancelled':
         case 'runtime.thread.cancelled':
-            return [
-                {
-                    type: 'setActorStatus',
-                    actorId: readString(payload, 'threadId') ?? event.threadId ?? event.runId,
-                    status: 'cancelled',
-                    updatedAt: event.ts,
-                },
-            ];
+            return [{ type: 'setActorStatus', runId, actorId, status: 'cancelled', updatedAt: event.ts }];
         case 'approval.requested':
             return [
                 {
                     type: 'upsertReview',
+                    runId,
                     reviewId: readString(payload, 'approvalId') ?? 'unknown',
-                    actorId: event.runId,
                     status: 'pending',
                     title: readString(payload, 'title') ?? 'Approval',
                     updatedAt: event.ts,
@@ -79,8 +73,8 @@ export function indexOpsFor(event) {
             return [
                 {
                     type: 'upsertReview',
+                    runId,
                     reviewId: readString(payload, 'approvalId') ?? 'unknown',
-                    actorId: event.runId,
                     status: payload.outcome === 'reject' ? 'rejected' : 'approved',
                     title: 'Approval',
                     updatedAt: event.ts,
@@ -90,6 +84,7 @@ export function indexOpsFor(event) {
             return [
                 {
                     type: 'setReviewStatus',
+                    runId,
                     reviewId: readString(payload, 'approvalId') ?? 'unknown',
                     status: 'timed_out',
                     updatedAt: event.ts,
@@ -99,7 +94,7 @@ export function indexOpsFor(event) {
             return [];
     }
 }
-export function createIndexProjector(name, backend, version = '1') {
+export function createIndexProjector(name, backend, version = '2') {
     return {
         name,
         version,
@@ -109,7 +104,7 @@ export function createIndexProjector(name, backend, version = '1') {
             const ops = events.flatMap(indexOpsFor);
             return ops.length === 0 ? Promise.resolve() : backend.applyOps(ops);
         },
-        getActor: (actorId) => backend.getActor(actorId),
-        listReviews: (actorId) => backend.listReviews(actorId),
+        getActor: (runId, actorId) => backend.getActor(runId, actorId ?? runId),
+        listReviews: (runId) => backend.listReviews(runId),
     };
 }

package/dist/projectors/memory.js

@@ -1,9 +1,13 @@
 import { createIndexProjector, } from './index-model.js';
 import { runProjectorSync } from './projector.js';
+function rowKey(runId, id) {
+    return `${runId}\0${id}`;
+}
 function applyOp(actors, reviews, op) {
     switch (op.type) {
         case 'upsertActor':
-            actors.set(op.actorId, {
+            actors.set(rowKey(op.runId, op.actorId), {
+                runId: op.runId,
                 actorId: op.actorId,
                 kind: op.kind,
                 status: op.status,
@@ -13,8 +17,10 @@ function applyOp(actors, reviews, op) {
             });
             return;
         case 'setActorStatus': {
-            const existing = actors.get(op.actorId);
-            actors.set(op.actorId, {
+            const key = rowKey(op.runId, op.actorId);
+            const existing = actors.get(key);
+            actors.set(key, {
+                runId: op.runId,
                 actorId: op.actorId,
                 kind: existing?.kind ?? null,
                 status: op.status,
@@ -25,10 +31,11 @@ function applyOp(actors, reviews, op) {
             return;
         }
         case 'upsertReview': {
-            const existing = reviews.get(op.reviewId);
-            reviews.set(op.reviewId, {
+            const key = rowKey(op.runId, op.reviewId);
+            const existing = reviews.get(key);
+            reviews.set(key, {
+                runId: op.runId,
                 reviewId: op.reviewId,
-                actorId: op.actorId,
                 status: op.status,
                 title: existing?.title ?? op.title,
                 updatedAt: op.updatedAt,
@@ -36,9 +43,10 @@ function applyOp(actors, reviews, op) {
             return;
         }
         case 'setReviewStatus': {
-            const existing = reviews.get(op.reviewId);
+            const key = rowKey(op.runId, op.reviewId);
+            const existing = reviews.get(key);
             if (existing) {
-                reviews.set(op.reviewId, { ...existing, status: op.status, updatedAt: op.updatedAt });
+                reviews.set(key, { ...existing, status: op.status, updatedAt: op.updatedAt });
             }
             return;
         }
@@ -57,10 +65,10 @@ export function memory() {
                 applyOp(actors, reviews, op);
             }
         }),
-        getActor: (actorId) => runProjectorSync('memory', () => actors.get(actorId) ?? null),
-        listReviews: (actorId) => runProjectorSync('memory', () => {
+        getActor: (runId, actorId) => runProjectorSync('memory', () => actors.get(rowKey(runId, actorId)) ?? null),
+        listReviews: (runId) => runProjectorSync('memory', () => {
             const rows = [...reviews.values()];
-            return actorId ? rows.filter((row) => row.actorId === actorId) : rows;
+            return runId ? rows.filter((row) => row.runId === runId) : rows;
         }),
         dispose: () => runProjectorSync('memory', () => {
             actors.clear();

package/dist/projectors/postgres.js

@@ -12,9 +12,9 @@ function applyOp(sql, op) {
     switch (op.type) {
         case 'upsertActor':
             return sql `
-        INSERT INTO looms_actors (actor_id, kind, status, definition_name, parent_actor_id, updated_at)
-        VALUES (${op.actorId}, ${op.kind}, ${op.status}, ${op.definitionName}, ${op.parentActorId}, ${date})
-        ON CONFLICT (actor_id) DO UPDATE SET
+        INSERT INTO looms_run_actors (run_id, actor_id, kind, status, definition_name, parent_actor_id, updated_at)
+        VALUES (${op.runId}, ${op.actorId}, ${op.kind}, ${op.status}, ${op.definitionName}, ${op.parentActorId}, ${date})
+        ON CONFLICT (run_id, actor_id) DO UPDATE SET
           kind = EXCLUDED.kind,
           status = EXCLUDED.status,
           definition_name = EXCLUDED.definition_name,
@@ -23,24 +23,24 @@ function applyOp(sql, op) {
       `;
         case 'setActorStatus':
             return sql `
-        INSERT INTO looms_actors (actor_id, status, updated_at)
-        VALUES (${op.actorId}, ${op.status}, ${date})
-        ON CONFLICT (actor_id) DO UPDATE SET
+        INSERT INTO looms_run_actors (run_id, actor_id, status, updated_at)
+        VALUES (${op.runId}, ${op.actorId}, ${op.status}, ${date})
+        ON CONFLICT (run_id, actor_id) DO UPDATE SET
           status = EXCLUDED.status,
           updated_at = EXCLUDED.updated_at
       `;
         case 'upsertReview':
             return sql `
-        INSERT INTO looms_reviews (review_id, actor_id, status, title, updated_at)
-        VALUES (${op.reviewId}, ${op.actorId}, ${op.status}, ${op.title}, ${date})
-        ON CONFLICT (review_id) DO UPDATE SET
+        INSERT INTO looms_run_reviews (run_id, review_id, status, title, updated_at)
+        VALUES (${op.runId}, ${op.reviewId}, ${op.status}, ${op.title}, ${date})
+        ON CONFLICT (run_id, review_id) DO UPDATE SET
           status = EXCLUDED.status,
           updated_at = EXCLUDED.updated_at
       `;
         case 'setReviewStatus':
             return sql `
-        UPDATE looms_reviews SET status = ${op.status}, updated_at = ${date}
-        WHERE review_id = ${op.reviewId}
+        UPDATE looms_run_reviews SET status = ${op.status}, updated_at = ${date}
+        WHERE run_id = ${op.runId} AND review_id = ${op.reviewId}
       `;
         default: {
             const exhaustiveCheck = op;
@@ -56,13 +56,14 @@ export function postgres(options) {
         applyOps: (ops) => runProjectorPromise('postgres', () => sql.begin((tx) => Effect.runPromise(Effect.forEach(ops, (op) => Effect.promise(() => Promise.resolve(applyOp(tx, op))), {
             discard: true,
         })))).then(() => undefined),
-        getActor: (actorId) => runProjectorPromise('postgres', () => sql `
-          SELECT actor_id, kind, status, definition_name, parent_actor_id, updated_at
-          FROM looms_actors WHERE actor_id = ${actorId}
+        getActor: (runId, actorId) => runProjectorPromise('postgres', () => sql `
+          SELECT run_id, actor_id, kind, status, definition_name, parent_actor_id, updated_at
+          FROM looms_run_actors WHERE run_id = ${runId} AND actor_id = ${actorId}
         `).then((rows) => {
             const row = rows[0];
             return row
                 ? {
+                    runId: row.run_id,
                     actorId: row.actor_id,
                     kind: row.kind,
                     status: row.status,
@@ -72,16 +73,16 @@ export function postgres(options) {
                 }
                 : null;
         }),
-        listReviews: (actorId) => runProjectorPromise('postgres', () => actorId
+        listReviews: (runId) => runProjectorPromise('postgres', () => runId
             ? sql `
-            SELECT review_id, actor_id, status, title, updated_at
-            FROM looms_reviews WHERE actor_id = ${actorId}
+            SELECT run_id, review_id, status, title, updated_at
+            FROM looms_run_reviews WHERE run_id = ${runId}
           `
             : sql `
-            SELECT review_id, actor_id, status, title, updated_at FROM looms_reviews
+            SELECT run_id, review_id, status, title, updated_at FROM looms_run_reviews
           `).then((rows) => rows.map((row) => ({
+            runId: row.run_id,
             reviewId: row.review_id,
-            actorId: row.actor_id,
             status: row.status,
             title: row.title,
             updatedAt: row.updated_at.getTime(),

package/dist/projectors/schema.js

@@ -2,42 +2,44 @@
  * SQL schema for the optional Looms secondary index.
  */
 export const POSTGRES_SCHEMA_SQL = `
-CREATE TABLE IF NOT EXISTS looms_actors (
-  actor_id TEXT PRIMARY KEY,
+CREATE TABLE IF NOT EXISTS looms_run_actors (
+  run_id TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
   kind TEXT,
   status TEXT,
   definition_name TEXT,
   parent_actor_id TEXT,
-  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (run_id, actor_id)
 );
 
-CREATE TABLE IF NOT EXISTS looms_reviews (
-  review_id TEXT PRIMARY KEY,
-  actor_id TEXT NOT NULL,
+CREATE TABLE IF NOT EXISTS looms_run_reviews (
+  run_id TEXT NOT NULL,
+  review_id TEXT NOT NULL,
   status TEXT NOT NULL,
   title TEXT NOT NULL,
-  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (run_id, review_id)
 );
-
-CREATE INDEX IF NOT EXISTS looms_reviews_actor_id_idx ON looms_reviews (actor_id);
 `.trim();
 export const SQLITE_SCHEMA_SQL = `
-CREATE TABLE IF NOT EXISTS looms_actors (
-  actor_id TEXT PRIMARY KEY,
+CREATE TABLE IF NOT EXISTS looms_run_actors (
+  run_id TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
   kind TEXT,
   status TEXT,
   definition_name TEXT,
   parent_actor_id TEXT,
-  updated_at INTEGER NOT NULL
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (run_id, actor_id)
 );
 
-CREATE TABLE IF NOT EXISTS looms_reviews (
-  review_id TEXT PRIMARY KEY,
-  actor_id TEXT NOT NULL,
+CREATE TABLE IF NOT EXISTS looms_run_reviews (
+  run_id TEXT NOT NULL,
+  review_id TEXT NOT NULL,
   status TEXT NOT NULL,
   title TEXT NOT NULL,
-  updated_at INTEGER NOT NULL
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (run_id, review_id)
 );
-
-CREATE INDEX IF NOT EXISTS looms_reviews_actor_id_idx ON looms_reviews (actor_id);
 `.trim();

package/dist/projectors/sqlite.js

@@ -9,35 +9,39 @@ function hasDb(options) {
 function applyOp(db, op) {
     switch (op.type) {
         case 'upsertActor':
-            db.run(`INSERT INTO looms_actors (actor_id, kind, status, definition_name, parent_actor_id, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)
-         ON CONFLICT (actor_id) DO UPDATE SET
+            db.run(`INSERT INTO looms_run_actors (run_id, actor_id, kind, status, definition_name, parent_actor_id, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (run_id, actor_id) DO UPDATE SET
            kind = excluded.kind,
            status = excluded.status,
            definition_name = excluded.definition_name,
            parent_actor_id = excluded.parent_actor_id,
-           updated_at = excluded.updated_at`, [op.actorId, op.kind, op.status, op.definitionName, op.parentActorId, op.updatedAt]);
+           updated_at = excluded.updated_at`, [
+                op.runId,
+                op.actorId,
+                op.kind,
+                op.status,
+                op.definitionName,
+                op.parentActorId,
+                op.updatedAt,
+            ]);
             return;
         case 'setActorStatus':
-            db.run(`INSERT INTO looms_actors (actor_id, status, updated_at)
-         VALUES (?, ?, ?)
-         ON CONFLICT (actor_id) DO UPDATE SET
+            db.run(`INSERT INTO looms_run_actors (run_id, actor_id, status, updated_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT (run_id, actor_id) DO UPDATE SET
            status = excluded.status,
-           updated_at = excluded.updated_at`, [op.actorId, op.status, op.updatedAt]);
+           updated_at = excluded.updated_at`, [op.runId, op.actorId, op.status, op.updatedAt]);
             return;
         case 'upsertReview':
-            db.run(`INSERT INTO looms_reviews (review_id, actor_id, status, title, updated_at)
+            db.run(`INSERT INTO looms_run_reviews (run_id, review_id, status, title, updated_at)
          VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT (review_id) DO UPDATE SET
+         ON CONFLICT (run_id, review_id) DO UPDATE SET
            status = excluded.status,
-           updated_at = excluded.updated_at`, [op.reviewId, op.actorId, op.status, op.title, op.updatedAt]);
+           updated_at = excluded.updated_at`, [op.runId, op.reviewId, op.status, op.title, op.updatedAt]);
             return;
         case 'setReviewStatus':
-            db.run(`UPDATE looms_reviews SET status = ?, updated_at = ? WHERE review_id = ?`, [
-                op.status,
-                op.updatedAt,
-                op.reviewId,
-            ]);
+            db.run(`UPDATE looms_run_reviews SET status = ?, updated_at = ? WHERE run_id = ? AND review_id = ?`, [op.status, op.updatedAt, op.runId, op.reviewId]);
             return;
         default: {
             const exhaustiveCheck = op;
@@ -60,13 +64,14 @@ export function sqlite(options = {}) {
             });
             apply(ops);
         }),
-        getActor: (actorId) => runProjectorSync('sqlite', () => {
+        getActor: (runId, actorId) => runProjectorSync('sqlite', () => {
             const row = db
-                .query(`SELECT actor_id, kind, status, definition_name, parent_actor_id, updated_at
-             FROM looms_actors WHERE actor_id = ?`)
-                .get(actorId);
+                .query(`SELECT run_id, actor_id, kind, status, definition_name, parent_actor_id, updated_at
+             FROM looms_run_actors WHERE run_id = ? AND actor_id = ?`)
+                .get(runId, actorId);
             return row
                 ? {
+                    runId: row.run_id,
                     actorId: row.actor_id,
                     kind: row.kind,
                     status: row.status,
@@ -76,18 +81,18 @@ export function sqlite(options = {}) {
                 }
                 : null;
         }),
-        listReviews: (actorId) => runProjectorSync('sqlite', () => {
-            const rows = actorId
+        listReviews: (runId) => runProjectorSync('sqlite', () => {
+            const rows = runId
                 ? db
-                    .query(`SELECT review_id, actor_id, status, title, updated_at
-                 FROM looms_reviews WHERE actor_id = ?`)
-                    .all(actorId)
+                    .query(`SELECT run_id, review_id, status, title, updated_at
+                 FROM looms_run_reviews WHERE run_id = ?`)
+                    .all(runId)
                 : db
-                    .query(`SELECT review_id, actor_id, status, title, updated_at FROM looms_reviews`)
+                    .query(`SELECT run_id, review_id, status, title, updated_at FROM looms_run_reviews`)
                     .all();
             return rows.map((row) => ({
+                runId: row.run_id,
                 reviewId: row.review_id,
-                actorId: row.actor_id,
                 status: row.status,
                 title: row.title,
                 updatedAt: row.updated_at,

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