@swirls/looms 0.3.0 → 0.5.0

package/dist/cloudflare/r2-blob-store.js

@@ -0,0 +1,60 @@
+import { Effect } from 'effect';
+import { blobStoreFromBytes, BlobStoreError } from '@swirls/looms/core';
+const PREFIX = 'looms/blobs/';
+/**
+ * Content-addressed blob store in R2 under `looms/blobs/`. Every run's Durable Object can
+ * share one bucket: each run writes its own reference markers, and a body is deleted only
+ * after no marker for it remains.
+ */
+export function r2BlobStore(bucket) {
+    return blobStoreFromBytes(r2BlobBytes(bucket));
+}
+function r2BlobBytes(bucket) {
+    const keyFor = (key) => `${PREFIX}${key}`;
+    return {
+        read: (key) => Effect.tryPromise({
+            try: () => bucket.get(keyFor(key)),
+            catch: (cause) => new BlobStoreError(`Unable to read blob key ${key}`, cause),
+        }).pipe(Effect.flatMap((object) => {
+            if (!object) {
+                return Effect.succeed(null);
+            }
+            return Effect.tryPromise({
+                try: () => object.arrayBuffer(),
+                catch: (cause) => new BlobStoreError(`Unable to read blob key ${key}`, cause),
+            }).pipe(Effect.map((buffer) => new Uint8Array(buffer)));
+        })),
+        write: (key, body) => Effect.tryPromise({
+            try: () => bucket.put(keyFor(key), body),
+            catch: (cause) => new BlobStoreError(`Unable to write blob key ${key}`, cause),
+        }).pipe(Effect.asVoid),
+        remove: (key) => Effect.tryPromise({
+            try: () => bucket.delete(keyFor(key)),
+            catch: (cause) => new BlobStoreError(`Unable to delete blob key ${key}`, cause),
+        }).pipe(Effect.asVoid),
+        exists: (key) => Effect.tryPromise({
+            try: () => bucket.head(keyFor(key)),
+            catch: (cause) => new BlobStoreError(`Unable to check blob key ${key}`, cause),
+        }).pipe(Effect.map((object) => object !== null)),
+        list: (prefix) => listPrefixed(bucket, `${PREFIX}${prefix}`),
+    };
+}
+function listPrefixed(bucket, prefix) {
+    return Effect.gen(function* () {
+        const keys = [];
+        let cursor;
+        for (;;) {
+            const page = yield* Effect.tryPromise({
+                try: () => cursor === undefined ? bucket.list({ prefix }) : bucket.list({ prefix, cursor }),
+                catch: (cause) => new BlobStoreError(`Unable to list blob keys ${prefix}`, cause),
+            });
+            for (const object of page.objects) {
+                keys.push(object.key.slice(PREFIX.length));
+            }
+            if (!page.truncated || page.cursor === undefined || page.cursor === cursor) {
+                return keys;
+            }
+            cursor = page.cursor;
+        }
+    });
+}

package/dist/cloudflare/router.d.ts

@@ -1,3 +1,4 @@
+import type { AnyRuntimeModule } from '@swirls/looms/core';
 export interface DurableObjectStubLike {
     fetch(request: Request): Promise<Response>;
 }
@@ -9,4 +10,6 @@ export interface DurableObjectNamespaceLike<T extends DurableObjectStubLike = Du
  * Handles `/health` locally, returns 501 for global run lists and forks, and forwards
  * all other run and event-stream requests to `namespace.getByName(runId)`.
  */
-export declare function routeToDurableObject(namespace: DurableObjectNamespaceLike, req: Request): Promise<Response | null>;
+export declare function routeToDurableObject(namespace: DurableObjectNamespaceLike, req: Request, options?: {
+    readonly modules?: readonly AnyRuntimeModule[] | (() => readonly AnyRuntimeModule[]);
+}): Promise<Response | null>;

package/dist/cloudflare/router.js

@@ -1,13 +1,18 @@
-import { crossRunResponse, resolveRunTarget, RunTargetError } from '@swirls/looms/actor';
+import { crossRunResponse, definitionsResponse, resolveRunTarget, RunTargetError, } from '@swirls/looms/actor';
 /**
  * Routes incoming HTTP requests to the appropriate Durable Object actor cell.
  * Handles `/health` locally, returns 501 for global run lists and forks, and forwards
  * all other run and event-stream requests to `namespace.getByName(runId)`.
  */
-export function routeToDurableObject(namespace, req) {
-    if (new URL(req.url).pathname === '/health') {
+export function routeToDurableObject(namespace, req, options) {
+    const url = new URL(req.url);
+    if (url.pathname === '/health') {
         return Promise.resolve(Response.json({ ok: true }));
     }
+    const definitions = definitionsResponse(req, options?.modules);
+    if (definitions) {
+        return Promise.resolve(definitions);
+    }
     const unsupported = crossRunResponse(req, 'the Durable Object backend');
     if (unsupported) {
         return Promise.resolve(unsupported);

package/dist/cloudflare/websocket.d.ts

@@ -0,0 +1,27 @@
+import { Effect } from 'effect';
+import { type EventStore } from '@swirls/looms/core';
+import { type Authorize, type LoomsRuntime } from '@swirls/looms/runtime';
+export interface HibernatingSocketState {
+    acceptWebSocket(ws: WebSocket, tags?: string[]): void;
+    getWebSockets?(tag?: string): readonly WebSocket[];
+    setWebSocketAutoResponse?(pair: WebSocketRequestResponsePair): void;
+}
+export interface OpenRunSocketOptions {
+    readonly ctx: HibernatingSocketState;
+    readonly runtime: LoomsRuntime;
+    readonly store: EventStore;
+    readonly request: Request;
+    readonly runId: string;
+    readonly authorize?: Authorize;
+    readonly createPair?: () => {
+        readonly client: WebSocket;
+        readonly server: WebSocket;
+    } | undefined;
+}
+export declare function isRunSocketUpgrade(request: Request): boolean;
+/**
+ * Wakes on append, not on a socket subscription, so a hibernated object can sleep
+ * while its WebSockets stay accepted.
+ */
+export declare function attachSocketFanout(ctx: HibernatingSocketState, store: EventStore, runId: string): EventStore;
+export declare function openRunSocket(options: OpenRunSocketOptions): Effect.Effect<Response>;

package/dist/cloudflare/websocket.js

@@ -0,0 +1,215 @@
+import { Effect, Option, Predicate } from 'effect';
+import { attachmentFromFilter, fanoutSubscription, openSubscription, subscriptionFilter, subscriptionFromSeq, } from '@swirls/looms/core';
+import { authResponse, defaultAuthorize, grantSubprotocol, loadSubscriptionOpening, readSubscriptionBounds, runRouteInfo, } from '@swirls/looms/runtime';
+const EVENTS_PATH = /^\/runs\/([^/]+)\/events\/?$/;
+const autoResponseInstalled = new WeakSet();
+export function isRunSocketUpgrade(request) {
+    if (request.method !== 'GET') {
+        return false;
+    }
+    const upgrade = request.headers.get('upgrade');
+    if (upgrade === null || upgrade.toLowerCase() !== 'websocket') {
+        return false;
+    }
+    return runEventsPath(new URL(request.url)) !== undefined;
+}
+/**
+ * Wakes on append, not on a socket subscription, so a hibernated object can sleep
+ * while its WebSockets stay accepted.
+ */
+export function attachSocketFanout(ctx, store, runId) {
+    return tapAppend(store, (events) => readSubscriptionBounds(store, runId).pipe(Effect.map((bounds) => {
+        fanoutSubscription(acceptedSockets(ctx, runId), events, { head: bounds.head });
+    }), Effect.orElseSucceed(() => {
+        fanoutSubscription(acceptedSockets(ctx, runId), events, { head: 1 });
+    })));
+}
+export function openRunSocket(options) {
+    const url = new URL(options.request.url);
+    const requested = runEventsPath(url);
+    if (requested !== options.runId) {
+        return Effect.succeed(Response.json({ error: 'Run not found' }, { status: 404 }));
+    }
+    const authorize = options.authorize ?? defaultAuthorize;
+    return Effect.gen(function* () {
+        const route = yield* runRouteInfo(options.runtime, options.store, {
+            access: 'read',
+            name: 'runs.events',
+            runId: options.runId,
+        }).pipe(Effect.option);
+        if (Option.isNone(route)) {
+            return Response.json({ error: 'Event log is unavailable' }, { status: 500 });
+        }
+        const decision = yield* authorize(options.request, route.value);
+        const denied = authResponse(decision);
+        if (denied) {
+            return denied;
+        }
+        const cursor = subscriptionFromSeq(url, options.request.headers.get('last-event-id'));
+        if (!cursor.ok) {
+            return Response.json({ error: cursor.message }, { status: 400 });
+        }
+        const createPair = options.createPair ?? createWebSocketPair;
+        const pair = createPair();
+        if (!pair) {
+            return new Response('WebSocket upgrade is not available', { status: 426 });
+        }
+        installAutoResponse(options.ctx);
+        options.ctx.acceptWebSocket(pair.server, [options.runId]);
+        const filter = subscriptionFilter(url);
+        const attachment = attachmentFromFilter(filter, cursor.fromSeq, null);
+        const socket = wrapSocket(pair.server);
+        socket.setAttachment(attachment);
+        const loaded = yield* loadSubscriptionOpening(options.store, options.runId, cursor.fromSeq).pipe(Effect.option);
+        if (Option.isNone(loaded)) {
+            return Response.json({ error: 'Event log is unavailable' }, { status: 500 });
+        }
+        const current = socket.attachment() ?? attachment;
+        const next = openSubscription(socket, current, loaded.value);
+        if (next) {
+            socket.setAttachment(next);
+        }
+        const protocol = grantSubprotocol(options.request);
+        return new Response(null, {
+            status: 101,
+            webSocket: pair.client,
+            headers: protocol ? { 'sec-websocket-protocol': protocol } : undefined,
+        });
+    });
+}
+function tapAppend(store, onAppend) {
+    return {
+        ...store,
+        append: (runId, events, appendOptions) => Effect.gen(function* () {
+            const result = yield* store.append(runId, events, appendOptions);
+            const first = result.sequences[0];
+            if (first === undefined) {
+                return result;
+            }
+            yield* Effect.gen(function* () {
+                const appended = yield* store.read(runId, {
+                    fromSeq: first,
+                    limit: result.sequences.length,
+                });
+                if (appended.length === 0) {
+                    return;
+                }
+                yield* onAppend(appended);
+            }).pipe(Effect.ignore);
+            return result;
+        }),
+    };
+}
+function acceptedSockets(ctx, runId) {
+    if (!ctx.getWebSockets) {
+        return [];
+    }
+    return ctx.getWebSockets(runId).map(wrapSocket);
+}
+function wrapSocket(ws) {
+    return {
+        send: (data) => {
+            ws.send(data);
+        },
+        close: (code, reason) => {
+            ws.close(code, reason);
+        },
+        get bufferedAmount() {
+            return Predicate.isNumber(ws.bufferedAmount) ? ws.bufferedAmount : 0;
+        },
+        attachment: () => readAttachment(ws),
+        setAttachment: (attachment) => {
+            writeAttachment(ws, attachment);
+        },
+    };
+}
+function readAttachment(ws) {
+    if (!('deserializeAttachment' in ws)) {
+        return undefined;
+    }
+    // oxlint-disable-next-line typescript/unbound-method -- hibernation methods are own properties of the platform socket
+    const read = ws.deserializeAttachment;
+    if (!Predicate.isFunction(read)) {
+        return undefined;
+    }
+    const value = read.call(ws);
+    if (!Predicate.isObject(value) || !('cursor' in value) || !Predicate.isNumber(value.cursor)) {
+        return undefined;
+    }
+    const principal = 'principal' in value && (value.principal === null || Predicate.isString(value.principal))
+        ? value.principal
+        : null;
+    const threadId = 'threadId' in value && Predicate.isString(value.threadId) ? value.threadId : null;
+    const includeEphemeral = !('includeEphemeral' in value) || value.includeEphemeral !== false;
+    return {
+        principal,
+        cursor: value.cursor,
+        threadId,
+        includeEphemeral,
+    };
+}
+function writeAttachment(ws, attachment) {
+    if (!('serializeAttachment' in ws)) {
+        return;
+    }
+    // oxlint-disable-next-line typescript/unbound-method -- hibernation methods are own properties of the platform socket
+    const write = ws.serializeAttachment;
+    if (!Predicate.isFunction(write)) {
+        return;
+    }
+    write.call(ws, attachment);
+}
+function installAutoResponse(ctx) {
+    if (autoResponseInstalled.has(ctx) || !ctx.setWebSocketAutoResponse) {
+        return;
+    }
+    try {
+        ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair('ping', 'pong'));
+        autoResponseInstalled.add(ctx);
+    }
+    catch {
+        // Hosts without the hibernation helper still accept the socket.
+    }
+}
+function createWebSocketPair() {
+    // SAFETY: Workers adds WebSocketPair to the global object. Other hosts leave it absent.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    const candidate = globalThis.WebSocketPair;
+    if (!Predicate.isFunction(candidate)) {
+        return undefined;
+    }
+    let pair;
+    try {
+        pair = Reflect.construct(candidate, []);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isSocketPair(pair)) {
+        return undefined;
+    }
+    return { client: pair[0], server: pair[1] };
+}
+function isSocket(value) {
+    return (Predicate.isObject(value) &&
+        'send' in value &&
+        Predicate.isFunction(value.send) &&
+        'close' in value &&
+        Predicate.isFunction(value.close));
+}
+function isSocketPair(value) {
+    return Predicate.isObject(value) && isSocket(value[0]) && isSocket(value[1]);
+}
+function runEventsPath(url) {
+    const match = EVENTS_PATH.exec(url.pathname);
+    const raw = match?.[1];
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/attempts.d.ts

@@ -0,0 +1,8 @@
+import type { AnyEventEnvelope } from './register';
+/** The effect a `runtime.effect.retry.scheduled` event retries, or `undefined` for other events. */
+export declare function retriedEffectId(event: AnyEventEnvelope): string | undefined;
+/**
+ * Drops ephemeral events from effect attempts that a later retry in `events` superseded. Durable
+ * events and ephemeral events from the current attempt are kept.
+ */
+export declare function dropSupersededAttempts<E extends AnyEventEnvelope>(events: readonly E[]): readonly E[];

package/dist/core/attempts.js

@@ -0,0 +1,27 @@
+import { Schema } from 'effect';
+import { protocolCatalog } from './protocol.js';
+const RETRY_SCHEDULED = 'runtime.effect.retry.scheduled';
+const isRetryPayload = Schema.is(protocolCatalog.entries['effect.retry.scheduled']);
+/** The effect a `runtime.effect.retry.scheduled` event retries, or `undefined` for other events. */
+export function retriedEffectId(event) {
+    return event.type === RETRY_SCHEDULED && isRetryPayload(event.payload)
+        ? event.payload.effectId
+        : undefined;
+}
+/**
+ * Drops ephemeral events from effect attempts that a later retry in `events` superseded. Durable
+ * events and ephemeral events from the current attempt are kept.
+ */
+export function dropSupersededAttempts(events) {
+    const lastRetry = new Map();
+    events.forEach((event, index) => {
+        const effectId = retriedEffectId(event);
+        if (effectId !== undefined) {
+            lastRetry.set(effectId, index);
+        }
+    });
+    if (lastRetry.size === 0) {
+        return events;
+    }
+    return events.filter((event, index) => !event.ephemeral || !event.effectId || (lastRetry.get(event.effectId) ?? -1) < index);
+}

package/dist/core/blob-offload.d.ts

@@ -0,0 +1,21 @@
+import { type BlobStore } from './blob-store';
+import { type SnapshotStore } from './snapshot-store';
+import { type EventStore } from './store';
+export interface BlobOffloadOptions {
+    /** Snapshot store to offload and resolve. Trim keeps digests referenced by its latest snapshot. */
+    readonly snapshots?: SnapshotStore;
+    /** UTF-8 JSON size above which a string is stored by hash. Default 64 KiB. */
+    readonly thresholdBytes?: number;
+    /** Serialized event size that claims the whole payload. Default 1 MiB. */
+    readonly maxEventBytes?: number;
+}
+/**
+ * Store oversized JSON outside the event log.
+ *
+ * Append replaces values over the threshold with a content-addressed reference before the
+ * event byte limit runs. `read`, `readStream`, and `subscribe` resolve those references, so
+ * folds, projections, and callers see the original values. The stored log keeps the references.
+ * When `snapshots` is set, snapshot save and load do the same, and trim deletes a body only
+ * once no retained event and no latest snapshot in any run still needs it.
+ */
+export declare function withBlobOffload(store: EventStore, blobs: BlobStore, options?: BlobOffloadOptions): EventStore;

package/dist/core/blob-offload.js

@@ -0,0 +1,143 @@
+import { Effect, Option, Schema, Stream } from 'effect';
+import { BlobStoreError } from './blob-store.js';
+import { DEFAULT_BLOB_THRESHOLD_BYTES, claimJson, collectBlobDigests, expandBlobDigests, offloadJson, resolveJson, } from './blobs.js';
+import { DEFAULT_MAX_EVENT_BYTES, utf8JsonBytes } from './limits.js';
+import { SnapshotStoreError, withSnapshotStore } from './snapshot-store.js';
+import { RunStateSchema } from './state.js';
+import { EventStoreError } from './store.js';
+const decodeJsonText = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Json));
+const decodeRunState = Schema.decodeUnknownEffect(RunStateSchema);
+/**
+ * Store oversized JSON outside the event log.
+ *
+ * Append replaces values over the threshold with a content-addressed reference before the
+ * event byte limit runs. `read`, `readStream`, and `subscribe` resolve those references, so
+ * folds, projections, and callers see the original values. The stored log keeps the references.
+ * When `snapshots` is set, snapshot save and load do the same, and trim deletes a body only
+ * once no retained event and no latest snapshot in any run still needs it.
+ */
+export function withBlobOffload(store, blobs, options) {
+    const thresholdBytes = options?.thresholdBytes ?? DEFAULT_BLOB_THRESHOLD_BYTES;
+    const maxEventBytes = options?.maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES;
+    const snapshots = options?.snapshots;
+    const wrappedSnapshots = snapshots
+        ? wrapSnapshots(snapshots, store, blobs, thresholdBytes)
+        : undefined;
+    const release = (runId) => keepDigests(store, snapshots, blobs, runId).pipe(Effect.flatMap((keep) => blobs.replaceRefs(runId, keep)), Effect.mapError(asEventError));
+    const wrapped = {
+        append: (runId, events, appendOptions) => Effect.gen(function* () {
+            const stored = yield* Effect.forEach(events, (event) => offloadAppendable(runId, event, blobs, thresholdBytes, maxEventBytes)).pipe(Effect.mapError(asEventError));
+            const seeds = digestsOf(stored.map((event) => event.payload));
+            const expanded = yield* expandBlobDigests(blobs, seeds).pipe(Effect.mapError(asEventError));
+            yield* blobs.retain(runId, [...expanded]).pipe(Effect.mapError(asEventError));
+            return yield* store.append(runId, stored, appendOptions);
+        }),
+        read: (runId, readOptions) => store
+            .read(runId, readOptions)
+            .pipe(Effect.flatMap((events) => Effect.forEach(events, (event) => resolveEnvelope(event, blobs).pipe(Effect.mapError(asEventError))))),
+        readStream: store.readStream
+            ? (runId, readOptions) => store.readStream(runId, readOptions).pipe(Stream.mapEffect((event) => resolveEnvelope(event, blobs).pipe(Effect.mapError(asEventError))))
+            : undefined,
+        tail: (runId) => store.tail(runId),
+        bounds: store.bounds ? (runId) => store.bounds(runId) : undefined,
+        trim: store.trim
+            ? (runId, beforeSeq) => store.trim(runId, beforeSeq).pipe(Effect.andThen(release(runId)))
+            : undefined,
+        subscribe: (runId, subscribeOptions) => store
+            .subscribe(runId, subscribeOptions)
+            .pipe(Stream.mapEffect((event) => resolveEnvelope(event, blobs).pipe(Effect.mapError(asEventError)))),
+        listRuns: store.listRuns,
+    };
+    if (!wrappedSnapshots) {
+        return wrapped;
+    }
+    return withSnapshotStore(wrapped, wrappedSnapshots);
+}
+function offloadAppendable(runId, event, blobs, thresholdBytes, maxEventBytes) {
+    return Effect.gen(function* () {
+        const payload = yield* offloadJson(event.payload, blobs, { thresholdBytes });
+        const offloaded = { ...event, payload };
+        if (eventBytes(runId, offloaded) <= maxEventBytes) {
+            return offloaded;
+        }
+        const ref = yield* claimJson(payload, blobs);
+        return { ...event, payload: ref };
+    });
+}
+function eventBytes(runId, event) {
+    return utf8JsonBytes({ ...event, runId, seq: event.seq ?? 0 });
+}
+function resolveEnvelope(event, blobs) {
+    return resolveJson(event.payload, blobs).pipe(Effect.map((payload) => ({ ...event, payload })));
+}
+function digestsOf(values) {
+    const seeds = new Set();
+    for (const value of values) {
+        collectBlobDigests(value, seeds);
+    }
+    return seeds;
+}
+function keepDigests(store, snapshots, blobs, runId) {
+    return Effect.gen(function* () {
+        const events = yield* store.read(runId);
+        const seeds = digestsOf(events.map((event) => event.payload));
+        if (snapshots) {
+            const latest = yield* snapshots
+                .loadLatest(runId)
+                .pipe(Effect.mapError((cause) => new EventStoreError(cause.message, cause)));
+            if (Option.isSome(latest)) {
+                const encoded = yield* jsonValue(latest.value.state).pipe(Effect.mapError((cause) => new EventStoreError(cause.message, cause)));
+                collectBlobDigests(encoded, seeds);
+            }
+        }
+        return yield* expandBlobDigests(blobs, seeds);
+    });
+}
+function wrapSnapshots(snapshots, store, blobs, thresholdBytes) {
+    const release = (runId) => keepDigests(store, snapshots, blobs, runId).pipe(Effect.flatMap((keep) => blobs.replaceRefs(runId, keep)), Effect.mapError((cause) => new SnapshotStoreError(cause.message, cause)));
+    return {
+        loadLatest: (runId) => Effect.gen(function* () {
+            const loaded = yield* snapshots.loadLatest(runId);
+            if (Option.isNone(loaded)) {
+                return loaded;
+            }
+            const encoded = yield* jsonValue(loaded.value.state).pipe(Effect.mapError(asSnapshotError));
+            const resolved = yield* resolveJson(encoded, blobs).pipe(Effect.mapError(asSnapshotError));
+            const state = yield* decodeRunState(resolved).pipe(Effect.mapError((cause) => new SnapshotStoreError('snapshot state did not match RunState', cause)));
+            return Option.some({ ...loaded.value, state });
+        }),
+        save: (snapshot) => Effect.gen(function* () {
+            const encoded = yield* jsonValue(snapshot.state).pipe(Effect.mapError(asSnapshotError));
+            const offloaded = yield* offloadJson(encoded, blobs, {
+                thresholdBytes,
+                claimRoot: false,
+            }).pipe(Effect.mapError(asSnapshotError));
+            const state = yield* decodeRunState(offloaded).pipe(Effect.mapError((cause) => new SnapshotStoreError('snapshot state did not match RunState', cause)));
+            const seeds = digestsOf([offloaded]);
+            const expanded = yield* expandBlobDigests(blobs, seeds).pipe(Effect.mapError(asSnapshotError));
+            yield* blobs.retain(snapshot.runId, [...expanded]).pipe(Effect.mapError(asSnapshotError));
+            return yield* snapshots.save({
+                runId: snapshot.runId,
+                cursor: snapshot.cursor,
+                stateHash: snapshot.stateHash,
+                takenAt: snapshot.takenAt,
+                state,
+            });
+        }),
+        listCursors: snapshots.listCursors ? (runId) => snapshots.listCursors(runId) : undefined,
+        prune: snapshots.prune
+            ? (runId, keepLatest) => snapshots.prune(runId, keepLatest).pipe(Effect.andThen(release(runId)))
+            : undefined,
+        saveHeader: (header) => snapshots.saveHeader(header),
+        listHeaders: snapshots.listHeaders,
+    };
+}
+function jsonValue(state) {
+    return decodeJsonText(JSON.stringify(state)).pipe(Effect.mapError((cause) => new BlobStoreError('snapshot state is not JSON', cause)));
+}
+function asEventError(cause) {
+    return new EventStoreError(cause.message, cause);
+}
+function asSnapshotError(cause) {
+    return new SnapshotStoreError(cause.message, cause);
+}

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

@@ -0,0 +1,45 @@
+import { Effect } from 'effect';
+declare const BlobStoreError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BlobStoreError";
+} & Readonly<A>;
+export declare class BlobStoreError extends BlobStoreError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+declare const BlobNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BlobNotFoundError";
+} & Readonly<A>;
+export declare class BlobNotFoundError extends BlobNotFoundError_base<{
+    readonly digest: string;
+    readonly message: string;
+}> {
+    constructor(digest: string);
+}
+export type BlobStoreFailure = BlobStoreError | BlobNotFoundError;
+/**
+ * Content-addressed bytes. `put` is idempotent: the same digest stores one body.
+ * `retain` and `replaceRefs` record which digests a run still needs. A body is deleted only
+ * when no run references it. Many runs may share one store, each writing its own references.
+ */
+export interface BlobStore {
+    readonly put: (digest: string, body: Uint8Array) => Effect.Effect<void, BlobStoreError>;
+    readonly get: (digest: string) => Effect.Effect<Uint8Array, BlobStoreFailure>;
+    readonly retain: (runId: string, digests: ReadonlyArray<string>) => Effect.Effect<void, BlobStoreError>;
+    readonly replaceRefs: (runId: string, keep: ReadonlySet<string>) => Effect.Effect<void, BlobStoreError>;
+}
+export declare function isSha256Digest(value: string): boolean;
+/** Byte operations behind {@link blobStoreFromBytes}. Keys are store-relative, not run ids. */
+export interface BlobBytes {
+    readonly read: (key: string) => Effect.Effect<Uint8Array | null, BlobStoreError>;
+    readonly write: (key: string, body: Uint8Array) => Effect.Effect<void, BlobStoreError>;
+    readonly remove: (key: string) => Effect.Effect<void, BlobStoreError>;
+    readonly exists: (key: string) => Effect.Effect<boolean, BlobStoreError>;
+    readonly list: (prefix: string) => Effect.Effect<ReadonlyArray<string>, BlobStoreError>;
+}
+export declare function memoryBlobStore(): BlobStore;
+export declare function blobStoreFromBytes(bytes: BlobBytes): BlobStore;
+export declare function sha256Hex(body: Uint8Array): Effect.Effect<string, BlobStoreError>;
+export {};