@swirls/looms 0.3.0 → 0.5.0

package/dist/projectors/sqlite.js

@@ -1,21 +1,54 @@
 import { Database } from 'bun:sqlite';
 import { createIndexProjector, } from './index-model.js';
 import { runProjectorSync } from './projector.js';
-import { SQLITE_SCHEMA_SQL } from './schema.js';
+import { SQLITE_ADDED_ACTOR_COLUMNS, SQLITE_INDEXES_SQL, SQLITE_TABLES_SQL } from './schema.js';
 export { SQLITE_SCHEMA_SQL } from './schema.js';
+const ACTOR_COLUMNS = `run_id, actor_id, kind, status, definition_name, parent_actor_id,
+  launched_by_run_id, launched_by_effect_id, correlation_id, updated_at`;
 function hasDb(options) {
     return 'db' in options;
 }
+function actorFromRow(row) {
+    return {
+        runId: row.run_id,
+        actorId: row.actor_id,
+        kind: row.kind,
+        status: row.status,
+        definitionName: row.definition_name,
+        parentActorId: row.parent_actor_id,
+        launchedByRunId: row.launched_by_run_id,
+        launchedByEffectId: row.launched_by_effect_id,
+        correlationId: row.correlation_id,
+        updatedAt: row.updated_at,
+    };
+}
+/** Creates the tables, adds columns a database from an earlier release lacks, then indexes them. */
+function migrate(db) {
+    db.exec(SQLITE_TABLES_SQL);
+    const existing = new Set(db
+        .query('PRAGMA table_info(looms_run_actors)')
+        .all()
+        .map((column) => column.name));
+    for (const column of SQLITE_ADDED_ACTOR_COLUMNS) {
+        if (!existing.has(column)) {
+            db.exec(`ALTER TABLE looms_run_actors ADD COLUMN ${column} TEXT`);
+        }
+    }
+    db.exec(SQLITE_INDEXES_SQL);
+}
 function applyOp(db, op) {
     switch (op.type) {
         case 'upsertActor':
-            db.run(`INSERT INTO looms_run_actors (run_id, actor_id, kind, status, definition_name, parent_actor_id, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?)
+            db.run(`INSERT INTO looms_run_actors (${ACTOR_COLUMNS})
+         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,
+           launched_by_run_id = excluded.launched_by_run_id,
+           launched_by_effect_id = excluded.launched_by_effect_id,
+           correlation_id = excluded.correlation_id,
            updated_at = excluded.updated_at`, [
                 op.runId,
                 op.actorId,
@@ -23,6 +56,9 @@ function applyOp(db, op) {
                 op.status,
                 op.definitionName,
                 op.parentActorId,
+                op.launchedByRunId,
+                op.launchedByEffectId,
+                op.correlationId,
                 op.updatedAt,
             ]);
             return;
@@ -53,9 +89,7 @@ export function sqlite(options = {}) {
     const createdDb = !hasDb(options);
     const db = hasDb(options) ? options.db : new Database(options.path ?? ':memory:');
     const backend = {
-        init: () => runProjectorSync('sqlite', () => {
-            db.exec(SQLITE_SCHEMA_SQL);
-        }),
+        init: () => runProjectorSync('sqlite', () => migrate(db)),
         applyOps: (ops) => runProjectorSync('sqlite', () => {
             const apply = db.transaction((batch) => {
                 for (const op of batch) {
@@ -66,21 +100,15 @@ export function sqlite(options = {}) {
         }),
         getActor: (runId, actorId) => runProjectorSync('sqlite', () => {
             const row = db
-                .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 = ?`)
+                .query(`SELECT ${ACTOR_COLUMNS} 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,
-                    definitionName: row.definition_name,
-                    parentActorId: row.parent_actor_id,
-                    updatedAt: row.updated_at,
-                }
-                : null;
+            return row ? actorFromRow(row) : null;
         }),
+        listLaunched: (runId) => runProjectorSync('sqlite', () => db
+            .query(`SELECT ${ACTOR_COLUMNS} FROM looms_run_actors
+             WHERE launched_by_run_id = ? AND actor_id = run_id ORDER BY updated_at`)
+            .all(runId)
+            .map(actorFromRow)),
         listReviews: (runId) => runProjectorSync('sqlite', () => {
             const rows = runId
                 ? db

package/dist/projectors/with-projectors.d.ts

@@ -1,4 +1,4 @@
-import { Layer } from 'effect';
+import { Effect, Layer } from 'effect';
 import { EventStoreTag, type EventStore, type EventEnvelope } from '@swirls/looms/core';
 import type { ProjectorDelivery } from './delivery';
 import { type Projector, type ProjectorErrorHandler } from './projector';
@@ -6,6 +6,12 @@ export interface WithProjectorsOptions {
     onError?: ProjectorErrorHandler;
     /** Durable cursor runner. When present, appends trigger catch-up from its persisted cursor. */
     delivery?: ProjectorDelivery;
+    /**
+     * Runs projection after the append commits, without making the append wait.
+     * The callback has to keep the effect alive, for example with a Durable Object's `waitUntil`.
+     * Without it, projection still finishes before `append` returns.
+     */
+    scheduleDelivery?: (runId: string, delivery: Effect.Effect<void>) => void;
 }
 /**
  * Wrap an EventStore so every successful append is also projected.

package/dist/projectors/with-projectors.js

@@ -16,6 +16,7 @@ function logDeliveryFailure(runId, cause) {
 export function withProjectors(store, projectors, options) {
     const onError = options?.onError ?? defaultOnError;
     const delivery = options?.delivery;
+    const scheduleDelivery = options?.scheduleDelivery;
     const project = (runId, sequences) => {
         if (delivery) {
             return delivery.deliver(runId).pipe(Effect.catch((cause) => logDeliveryFailure(runId, cause)));
@@ -29,9 +30,18 @@ export function withProjectors(store, projectors, options) {
         }))), { concurrency: 'unbounded', discard: true })), Effect.catch((cause) => logDeliveryFailure(runId, cause)));
     };
     const wrapped = {
-        append: (runId, events, appendOptions) => store
-            .append(runId, events, appendOptions)
-            .pipe(Effect.tap((result) => projectors.length === 0 ? Effect.void : project(runId, result.sequences))),
+        append: (runId, events, appendOptions) => store.append(runId, events, appendOptions).pipe(Effect.tap((result) => {
+            if (projectors.length === 0) {
+                return Effect.void;
+            }
+            const work = project(runId, result.sequences);
+            if (!scheduleDelivery) {
+                return work;
+            }
+            return Effect.sync(() => {
+                scheduleDelivery(runId, work);
+            });
+        })),
         read: (runId, readOptions) => store.read(runId, readOptions),
         tail: (runId) => store.tail(runId),
         bounds: store.bounds ? (runId) => store.bounds(runId) : undefined,

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/materialize.js

@@ -1,4 +1,4 @@
-import { completedRunStatus, isJsonObject, isJsonString, } from '@swirls/looms/core';
+import { completedRunStatus, isJsonObject, isJsonString, readAttributes, readRunLaunchSource, } from '@swirls/looms/core';
 import { emptyTables } from './tables.js';
 function payloadObject(event) {
     return isJsonObject(event.payload) ? event.payload : {};
@@ -15,6 +15,8 @@ function setRunStatus(tables, runId, status) {
         rootThreadId: existing?.rootThreadId ?? null,
         kind: existing?.kind ?? null,
         definitionName: existing?.definitionName ?? null,
+        launchedBy: existing?.launchedBy ?? null,
+        attributes: existing?.attributes ?? {},
     });
 }
 export function materializeEvents(events, from = emptyTables()) {
@@ -34,6 +36,8 @@ export function materializeEvents(events, from = emptyTables()) {
                     rootThreadId,
                     kind: readString(payload, 'kind') ?? existing?.kind ?? null,
                     definitionName: readString(payload, 'definitionName') ?? existing?.definitionName ?? null,
+                    launchedBy: readRunLaunchSource(payload.launchedBy) ?? existing?.launchedBy ?? null,
+                    attributes: readAttributes(payload.attributes),
                 };
                 tables.runs.set(event.runId, next);
                 break;

package/dist/react/react.d.ts

@@ -1,23 +1,27 @@
 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 RunAttributes, type RunLaunchSource, type RunStatus, type SubscriptionTransport, 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;
     endpoint?: string;
     coalesce?: CoalesceOption;
+    transport?: SubscriptionTransport;
 }
 interface ProviderContextValue {
     endpoint: string;
     coalesce?: CoalesceOption;
+    transport?: SubscriptionTransport;
 }
 /** Root provider that supplies the Looms host endpoint to run stores. */
-export declare function LoomsProvider({ children, endpoint, coalesce }: LoomsProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<ProviderContextValue>>;
+export declare function LoomsProvider({ children, endpoint, coalesce, transport, }: LoomsProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<ProviderContextValue>>;
 export interface UseRunStoreOptions {
     endpoint?: string;
     reconnectDelayMs?: number;
     coalesce?: CoalesceOption;
+    transport?: SubscriptionTransport;
+    threadId?: string;
+    includeEphemeral?: boolean;
 }
 /**
  * Acquires a non-subscribing handle to the run store.
@@ -39,6 +43,9 @@ export interface RunSummary {
     readonly definitionName: string | undefined;
     readonly rootThreadId: string | undefined;
     readonly startedAt: number | undefined;
+    /** The effect in another run that launched this one. */
+    readonly launchedBy: RunLaunchSource | undefined;
+    readonly attributes: RunAttributes;
     readonly connection: LoomsConnectionStatus;
 }
 /** Lightweight subscription to top-level run metadata and connection status. */
@@ -55,10 +62,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,13 +1,19 @@
 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 { isTerminalStatus, sameStringRecord, threadTree, toThreadTree, } from '@swirls/looms/core';
+import { defineLiveFold, foldLive } from './derived.js';
 import { createLoomsStore, } from './store.js';
 const LoomsContext = createContext({ endpoint: '' });
 const GRACE_MS = 5_000;
 const registry = new Map();
-function registryKey(endpoint, runId) {
-    return `${endpoint}\0${runId}`;
+function registryKey(runId, identity) {
+    return [
+        identity.endpoint,
+        runId,
+        identity.transport ?? '',
+        identity.threadId ?? '',
+        identity.includeEphemeral === false ? '0' : '1',
+    ].join('\0');
 }
 function disposeEntry(key) {
     const entry = registry.get(key);
@@ -20,17 +26,20 @@ function disposeEntry(key) {
 function scheduleDisposal(key) {
     return Effect.runFork(Effect.sleep(GRACE_MS).pipe(Effect.andThen(Effect.sync(() => disposeEntry(key)))));
 }
-function peekStore(runId, endpoint, reconnectDelayMs, coalesce) {
-    const key = registryKey(endpoint, runId);
+function peekStore(runId, identity) {
+    const key = registryKey(runId, identity);
     const existing = registry.get(key);
     if (existing) {
         return existing.store;
     }
     const store = createLoomsStore({
         storeId: runId,
-        endpoint,
-        reconnectDelayMs,
-        coalesce,
+        endpoint: identity.endpoint,
+        reconnectDelayMs: identity.reconnectDelayMs,
+        coalesce: identity.coalesce,
+        transport: identity.transport,
+        threadId: identity.threadId,
+        includeEphemeral: identity.includeEphemeral,
     });
     registry.set(key, {
         store,
@@ -39,9 +48,9 @@ function peekStore(runId, endpoint, reconnectDelayMs, coalesce) {
     });
     return store;
 }
-function retainStore(runId, endpoint, reconnectDelayMs, coalesce) {
-    const key = registryKey(endpoint, runId);
-    peekStore(runId, endpoint, reconnectDelayMs, coalesce);
+function retainStore(runId, identity) {
+    const key = registryKey(runId, identity);
+    peekStore(runId, identity);
     const entry = registry.get(key);
     if (!entry) {
         return;
@@ -52,8 +61,8 @@ function retainStore(runId, endpoint, reconnectDelayMs, coalesce) {
         entry.disposal = undefined;
     }
 }
-function releaseStore(runId, endpoint) {
-    const key = registryKey(endpoint, runId);
+function releaseStore(runId, identity) {
+    const key = registryKey(runId, identity);
     const entry = registry.get(key);
     if (!entry) {
         return;
@@ -64,8 +73,8 @@ function releaseStore(runId, endpoint) {
     }
 }
 /** Root provider that supplies the Looms host endpoint to run stores. */
-export function LoomsProvider({ children, endpoint = '', coalesce }) {
-    const value = useMemo(() => ({ endpoint, coalesce }), [endpoint, coalesce]);
+export function LoomsProvider({ children, endpoint = '', coalesce, transport, }) {
+    const value = useMemo(() => ({ endpoint, coalesce, transport }), [endpoint, coalesce, transport]);
     return createElement(LoomsContext.Provider, { value, children });
 }
 /**
@@ -78,11 +87,22 @@ export function useRunStore(runId, options) {
     const endpoint = options?.endpoint ?? context.endpoint;
     const reconnectDelayMs = options?.reconnectDelayMs;
     const coalesce = options?.coalesce ?? context.coalesce;
-    const store = peekStore(runId, endpoint, reconnectDelayMs, coalesce);
+    const transport = options?.transport ?? context.transport;
+    const threadId = options?.threadId;
+    const includeEphemeral = options?.includeEphemeral;
+    const identity = {
+        endpoint,
+        reconnectDelayMs,
+        coalesce,
+        transport,
+        threadId,
+        includeEphemeral,
+    };
+    const store = peekStore(runId, identity);
     useEffect(() => {
-        retainStore(runId, endpoint, reconnectDelayMs, coalesce);
-        return () => releaseStore(runId, endpoint);
-    }, [runId, endpoint, reconnectDelayMs, coalesce]);
+        retainStore(runId, identity);
+        return () => releaseStore(runId, identity);
+    }, [runId, endpoint, reconnectDelayMs, coalesce, transport, threadId, includeEphemeral]);
     return store;
 }
 function useStoreSnapshot(store, getSnapshot) {
@@ -119,6 +139,8 @@ function shallowEqualSummary(a, b) {
         a.definitionName === b.definitionName &&
         a.rootThreadId === b.rootThreadId &&
         a.startedAt === b.startedAt &&
+        a.launchedBy === b.launchedBy &&
+        sameStringRecord(a.attributes, b.attributes) &&
         a.connection === b.connection);
 }
 /** Lightweight subscription to top-level run metadata and connection status. */
@@ -134,6 +156,8 @@ export function useRunSummary(store) {
             definitionName: run?.definitionName ?? undefined,
             rootThreadId: run?.rootThreadId ?? undefined,
             startedAt: s.query.startedAt(),
+            launchedBy: run?.launchedBy ?? undefined,
+            attributes: run?.attributes ?? {},
             connection: s.status(),
         };
     }, []);
@@ -165,10 +189,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,7 @@
-import { type EventInput, type ProjectionDefinition } from '@swirls/looms/core';
-import { type EventFoldDefinition } from './derived';
+import type { SubscriptionSocketConstructor } from '@swirls/looms/client';
+import { type AnyEventEnvelope, type EventInput, type ProjectionDefinition, type RegisteredEvent, type SubscriptionTransport } 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`. */
@@ -15,10 +15,18 @@ export interface LoomsClientStoreOptions {
      * Opens `${endpoint}/runs/:id/events?live=true` as an SSE stream.
      */
     endpoint: string;
-    /** Backoff between SSE reconnects. */
+    /** Backoff between reconnects. The delay stays fixed, matching the SSE client. */
     reconnectDelayMs?: number;
     fetch?: typeof fetch;
     coalesce?: CoalesceOption;
+    /**
+     * `undefined` keeps the current SSE path. `websocket` and `auto` use a hibernating
+     * socket when a constructor is available.
+     */
+    transport?: SubscriptionTransport;
+    threadId?: string;
+    includeEphemeral?: boolean;
+    webSocket?: SubscriptionSocketConstructor;
 }
 export interface LoomsStoreQuery<TEvent extends AnyEventEnvelope = RegisteredEvent> {
     events: (options?: {
@@ -30,7 +38,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 +51,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>;