@nimbus-sh/loom 0.1.0

package/dist/client.js

@@ -0,0 +1,98 @@
+/**
+ * client.ts — the caller's half of callable RPC: a promise per call, and a
+ * typed stub proxy that makes an actor's methods look local.
+ *
+ * Dependency-free and workerd-free on purpose: the socket is anything with
+ * `send` and message listeners — a browser WebSocket, a PartySocket, a
+ * server-side WebSocket from `fetch()` — so this module runs wherever the
+ * connection was made. Frames and defaults follow the Agents SDK client
+ * (verified in `agents` 0.20.1 dist, `client.js:129-151,217-248`): ids are
+ * `crypto.randomUUID()`, plain calls time out at 30 s by default, streamed
+ * calls (an `onChunk` listener) get no timeout unless one is passed.
+ */
+import { isRpcResponseFrame, RPC_FRAME_TYPE } from './protocol.js';
+export const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+/** Attach an RPC client to a socket. One message listener for all calls. */
+export function actorClient(socket, defaults = {}) {
+    const pending = new Map();
+    const onMessage = (event) => {
+        if (typeof event.data !== 'string')
+            return;
+        let frame;
+        try {
+            frame = JSON.parse(event.data);
+        }
+        catch {
+            return;
+        }
+        if (!isRpcResponseFrame(frame))
+            return;
+        const call = pending.get(frame.id);
+        if (!call)
+            return;
+        if (frame.success === false) {
+            settle(frame.id)?.reject(new Error(frame.error));
+            return;
+        }
+        if (frame.done === false) {
+            call.onChunk?.(frame.result);
+            return;
+        }
+        settle(frame.id)?.resolve(frame.result);
+    };
+    const settle = (id) => {
+        const call = pending.get(id);
+        if (!call)
+            return undefined;
+        pending.delete(id);
+        if (call.timer !== undefined)
+            clearTimeout(call.timer);
+        return call;
+    };
+    socket.addEventListener('message', onMessage);
+    const call = (method, args = [], options = {}) => {
+        const onChunk = options.onChunk ?? defaults.onChunk;
+        const timeoutMs = options.timeoutMs ?? defaults.timeoutMs ?? (onChunk ? undefined : DEFAULT_CALL_TIMEOUT_MS);
+        const id = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const entry = { resolve: resolve, reject, onChunk };
+            if (timeoutMs !== undefined) {
+                entry.timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(new Error(`RPC call '${method}' timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }
+            pending.set(id, entry);
+            try {
+                socket.send(JSON.stringify({ type: RPC_FRAME_TYPE, id, method, args }));
+            }
+            catch (e) {
+                settle(id);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+    };
+    return {
+        call,
+        stub(options) {
+            return new Proxy({}, {
+                get(_target, name) {
+                    if (typeof name !== 'string')
+                        return undefined;
+                    // `await stub` (or any promise resolution of the stub itself)
+                    // probes `.then`; answering with a caller would fire an RPC
+                    // literally named "then".
+                    if (name === 'then')
+                        return undefined;
+                    return (...args) => call(name, args, options);
+                },
+            });
+        },
+        close() {
+            socket.removeEventListener('message', onMessage);
+            for (const id of [...pending.keys()]) {
+                settle(id)?.reject(new Error('RPC client closed'));
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @nimbus-sh/loom — the actor framework of Nimbus: partyserver's surface on
+ * top, the @nimbus-sh/fabric floor pre-wired underneath.
+ *
+ * The root export pulls `partyserver`, which imports `cloudflare:workers`,
+ * so importing this module outside workerd fails at resolution. Non-workerd
+ * consumers (tests, browser clients) import the subpath modules they need —
+ * `@nimbus-sh/loom/client.js` is workerd-free by design.
+ */
+export * from './actor.js';
+export * from './callable.js';
+export * from './client.js';
+export * from './protocol.js';
+export * from './routing.js';
+export * from './rpc.js';
+export * from './schedules.js';
+export { Server } from 'partyserver';
+export type { Connection, ConnectionContext, WSMessage } from 'partyserver';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @nimbus-sh/loom — the actor framework of Nimbus: partyserver's surface on
+ * top, the @nimbus-sh/fabric floor pre-wired underneath.
+ *
+ * The root export pulls `partyserver`, which imports `cloudflare:workers`,
+ * so importing this module outside workerd fails at resolution. Non-workerd
+ * consumers (tests, browser clients) import the subpath modules they need —
+ * `@nimbus-sh/loom/client.js` is workerd-free by design.
+ */
+export * from './actor.js';
+export * from './callable.js';
+export * from './client.js';
+export * from './protocol.js';
+export * from './routing.js';
+export * from './rpc.js';
+export * from './schedules.js';
+export { Server } from 'partyserver';

package/dist/protocol.d.ts

@@ -0,0 +1,63 @@
+/**
+ * protocol.ts — the JSON frames loom speaks over a WebSocket connection.
+ *
+ * The frame shapes and type strings match the Cloudflare Agents SDK
+ * (`agents` 0.20.1, verified in its shipped dist: `types.js:5-15` for the
+ * type strings, `agent-tool-types` d.ts for the request/response shapes).
+ * Matching them is deliberate: a client written for an Agents server — the
+ * SDK's own `AgentClient` included — can drive a loom actor's state sync and
+ * RPC without translation. Only the frames loom implements are declared
+ * here; the Agents-product frames (MCP, identity, sessions) are not.
+ *
+ * A string message that parses as JSON and carries one of these `type`
+ * values is a protocol frame and never reaches the embedder's `onMessage`.
+ * Everything else — binary, non-JSON text, JSON with any other `type` —
+ * passes through untouched.
+ */
+/** State sync, both directions: `{ type, state }`. */
+export declare const STATE_FRAME_TYPE = "cf_agent_state";
+/** Server → client: a client state update was refused. */
+export declare const STATE_ERROR_FRAME_TYPE = "cf_agent_state_error";
+/** Callable RPC, both directions. */
+export declare const RPC_FRAME_TYPE = "rpc";
+/** Client → server: replace the actor's state. */
+export interface StateFrame<S = unknown> {
+    type: typeof STATE_FRAME_TYPE;
+    state: S;
+}
+/** Server → client: the refusal a rejected state update earns. */
+export interface StateErrorFrame {
+    type: typeof STATE_ERROR_FRAME_TYPE;
+    error: string;
+}
+/** Client → server: call one `callable()` method by name. */
+export interface RpcRequestFrame {
+    type: typeof RPC_FRAME_TYPE;
+    /** Correlates the response frames to the call. The client mints it. */
+    id: string;
+    method: string;
+    args: unknown[];
+}
+/**
+ * Server → client. A streamed reply is many `done: false` frames and one
+ * `done: true`; a plain reply is a single `done: true` frame. `done` absent
+ * means final (the Agents client treats it so; loom always sets it).
+ */
+export type RpcResponseFrame = {
+    type: typeof RPC_FRAME_TYPE;
+    id: string;
+} & ({
+    success: true;
+    result: unknown;
+    done?: boolean;
+} | {
+    success: false;
+    error: string;
+});
+/** Same guard the Agents server uses: `type` plus a `state` key. */
+export declare function isStateFrame(value: unknown): value is StateFrame;
+/** Same guard the Agents server uses: all four fields, `args` an array. */
+export declare function isRpcRequestFrame(value: unknown): value is RpcRequestFrame;
+/** The client-side guard for response frames. */
+export declare function isRpcResponseFrame(value: unknown): value is RpcResponseFrame;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,0DAA0D;AAC1D,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D,qCAAqC;AACrC,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,kDAAkD;AAClD,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,IAAI,EAAE,OAAO,gBAAgB,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC;CACV;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,sBAAsB,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,cAAc,CAAC;IAC5B,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,cAAc,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,CACzE;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAClD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CACpC,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAMhE;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAS1E;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAI5E"}

package/dist/protocol.js

@@ -0,0 +1,45 @@
+/**
+ * protocol.ts — the JSON frames loom speaks over a WebSocket connection.
+ *
+ * The frame shapes and type strings match the Cloudflare Agents SDK
+ * (`agents` 0.20.1, verified in its shipped dist: `types.js:5-15` for the
+ * type strings, `agent-tool-types` d.ts for the request/response shapes).
+ * Matching them is deliberate: a client written for an Agents server — the
+ * SDK's own `AgentClient` included — can drive a loom actor's state sync and
+ * RPC without translation. Only the frames loom implements are declared
+ * here; the Agents-product frames (MCP, identity, sessions) are not.
+ *
+ * A string message that parses as JSON and carries one of these `type`
+ * values is a protocol frame and never reaches the embedder's `onMessage`.
+ * Everything else — binary, non-JSON text, JSON with any other `type` —
+ * passes through untouched.
+ */
+/** State sync, both directions: `{ type, state }`. */
+export const STATE_FRAME_TYPE = 'cf_agent_state';
+/** Server → client: a client state update was refused. */
+export const STATE_ERROR_FRAME_TYPE = 'cf_agent_state_error';
+/** Callable RPC, both directions. */
+export const RPC_FRAME_TYPE = 'rpc';
+/** Same guard the Agents server uses: `type` plus a `state` key. */
+export function isStateFrame(value) {
+    return (typeof value === 'object' && value !== null
+        && value.type === STATE_FRAME_TYPE
+        && 'state' in value);
+}
+/** Same guard the Agents server uses: all four fields, `args` an array. */
+export function isRpcRequestFrame(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const frame = value;
+    return (frame.type === RPC_FRAME_TYPE
+        && typeof frame.id === 'string'
+        && typeof frame.method === 'string'
+        && Array.isArray(frame.args));
+}
+/** The client-side guard for response frames. */
+export function isRpcResponseFrame(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const frame = value;
+    return frame.type === RPC_FRAME_TYPE && typeof frame.id === 'string' && typeof frame.success === 'boolean';
+}

package/dist/routing.d.ts

@@ -0,0 +1,13 @@
+/**
+ * routing.ts — URL → binding → named actor instance.
+ *
+ * partyserver's router already is the mechanism loom wants: it maps
+ * `/${prefix}/<binding-kebab>/<name>` onto the Durable Object binding, with
+ * `onBeforeConnect`/`onBeforeRequest` gates, CORS, jurisdiction, location
+ * hints, and retry over transient DO routing errors. Wrapping it in a
+ * parallel implementation would be a drift channel, so loom re-exports it
+ * under its own names. The URL convention stays `/parties/...` by default —
+ * it is the wire contract PartySocket-family clients build URLs from.
+ */
+export { routePartykitRequest as routeActorRequest, getServerByName as getActorByName, type PartyServerOptions as ActorRoutingOptions, type Lobby, type RoutingRetryOptions, } from 'partyserver';
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,oBAAoB,IAAI,iBAAiB,EACzC,eAAe,IAAI,cAAc,EACjC,KAAK,kBAAkB,IAAI,mBAAmB,EAC9C,KAAK,KAAK,EACV,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC"}

package/dist/routing.js

@@ -0,0 +1,12 @@
+/**
+ * routing.ts — URL → binding → named actor instance.
+ *
+ * partyserver's router already is the mechanism loom wants: it maps
+ * `/${prefix}/<binding-kebab>/<name>` onto the Durable Object binding, with
+ * `onBeforeConnect`/`onBeforeRequest` gates, CORS, jurisdiction, location
+ * hints, and retry over transient DO routing errors. Wrapping it in a
+ * parallel implementation would be a drift channel, so loom re-exports it
+ * under its own names. The URL convention stays `/parties/...` by default —
+ * it is the wire contract PartySocket-family clients build URLs from.
+ */
+export { routePartykitRequest as routeActorRequest, getServerByName as getActorByName, } from 'partyserver';

package/dist/rpc.d.ts

@@ -0,0 +1,47 @@
+/**
+ * rpc.ts — the server half of callable RPC: dispatch one request frame to a
+ * marked method and answer over the connection.
+ *
+ * The dispatch contract mirrors the Agents SDK (verified in `agents` 0.20.1
+ * dist, `index.js:883-934`):
+ *   - the method must exist on the target AND carry the `callable()` mark;
+ *     either failure is an error frame, not a crash.
+ *   - a streaming method receives a {@link StreamingResponse} PREPENDED to
+ *     the caller's arguments and owns its own reply frames; if it throws
+ *     with the stream still open, the error closes the stream.
+ *   - a plain method's awaited return value goes back as one
+ *     `{ success: true, done: true }` frame; a throw becomes
+ *     `{ success: false, error }` carrying the message only, never the stack.
+ *
+ * Sends tolerate exactly one failure: workerd throws a TypeError containing
+ * "WebSocket send() after close" when the peer is gone, and a reply that
+ * cannot be delivered has no one waiting for it. Every other send error is
+ * a real bug and propagates.
+ */
+import { type RpcRequestFrame } from './protocol.js';
+/** The connection as RPC writes to it. partyserver's `Connection` satisfies it. */
+export interface RpcConnection {
+    send(message: string): void;
+}
+/**
+ * The reply channel a streaming callable writes through. One `end()` (or
+ * `error()`) closes it; every later write is a refused no-op that returns
+ * false, matching the Agents SDK's `StreamingResponse` (dist
+ * `index.js:7169-7233`).
+ */
+export declare class StreamingResponse {
+    #private;
+    private readonly connection;
+    private readonly id;
+    constructor(connection: RpcConnection, id: string);
+    get isClosed(): boolean;
+    /** One chunk. Returns false when the stream is closed or the peer is gone. */
+    send(chunk: unknown): boolean;
+    /** Close the stream, with an optional final chunk. */
+    end(finalChunk?: unknown): boolean;
+    /** Close the stream with an error the caller's promise rejects on. */
+    error(message: string): boolean;
+}
+/** Run one request frame against the target and reply on the connection. */
+export declare function dispatchRpc(target: object, connection: RpcConnection, frame: RpcRequestFrame): Promise<void>;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAkB,KAAK,eAAe,EAAyB,MAAM,eAAe,CAAC;AAE5F,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAYD;;;;;GAKG;AACH,qBAAa,iBAAiB;;IAI1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,EAAE;gBADF,UAAU,EAAE,aAAa,EACzB,EAAE,EAAE,MAAM;IAG7B,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,8EAA8E;IAC9E,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAQ7B,sDAAsD;IACtD,GAAG,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO;IAMlC,sEAAsE;IACtE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAKhC;AAED,4EAA4E;AAC5E,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,aAAa,EACzB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/rpc.js

@@ -0,0 +1,102 @@
+/**
+ * rpc.ts — the server half of callable RPC: dispatch one request frame to a
+ * marked method and answer over the connection.
+ *
+ * The dispatch contract mirrors the Agents SDK (verified in `agents` 0.20.1
+ * dist, `index.js:883-934`):
+ *   - the method must exist on the target AND carry the `callable()` mark;
+ *     either failure is an error frame, not a crash.
+ *   - a streaming method receives a {@link StreamingResponse} PREPENDED to
+ *     the caller's arguments and owns its own reply frames; if it throws
+ *     with the stream still open, the error closes the stream.
+ *   - a plain method's awaited return value goes back as one
+ *     `{ success: true, done: true }` frame; a throw becomes
+ *     `{ success: false, error }` carrying the message only, never the stack.
+ *
+ * Sends tolerate exactly one failure: workerd throws a TypeError containing
+ * "WebSocket send() after close" when the peer is gone, and a reply that
+ * cannot be delivered has no one waiting for it. Every other send error is
+ * a real bug and propagates.
+ */
+import { callableMetadata, isCallable } from './callable.js';
+import { RPC_FRAME_TYPE } from './protocol.js';
+function sendIfOpen(connection, frame) {
+    try {
+        connection.send(JSON.stringify(frame));
+        return true;
+    }
+    catch (e) {
+        if (e instanceof TypeError && e.message.includes('WebSocket send() after close'))
+            return false;
+        throw e;
+    }
+}
+/**
+ * The reply channel a streaming callable writes through. One `end()` (or
+ * `error()`) closes it; every later write is a refused no-op that returns
+ * false, matching the Agents SDK's `StreamingResponse` (dist
+ * `index.js:7169-7233`).
+ */
+export class StreamingResponse {
+    connection;
+    id;
+    #closed = false;
+    constructor(connection, id) {
+        this.connection = connection;
+        this.id = id;
+    }
+    get isClosed() {
+        return this.#closed;
+    }
+    /** One chunk. Returns false when the stream is closed or the peer is gone. */
+    send(chunk) {
+        if (this.#closed) {
+            console.warn('loom: StreamingResponse.send() after the stream was closed — chunk not sent');
+            return false;
+        }
+        return sendIfOpen(this.connection, { type: RPC_FRAME_TYPE, id: this.id, success: true, result: chunk, done: false });
+    }
+    /** Close the stream, with an optional final chunk. */
+    end(finalChunk) {
+        if (this.#closed)
+            return false;
+        this.#closed = true;
+        return sendIfOpen(this.connection, { type: RPC_FRAME_TYPE, id: this.id, success: true, result: finalChunk, done: true });
+    }
+    /** Close the stream with an error the caller's promise rejects on. */
+    error(message) {
+        if (this.#closed)
+            return false;
+        this.#closed = true;
+        return sendIfOpen(this.connection, { type: RPC_FRAME_TYPE, id: this.id, success: false, error: message });
+    }
+}
+/** Run one request frame against the target and reply on the connection. */
+export async function dispatchRpc(target, connection, frame) {
+    const method = target[frame.method];
+    try {
+        if (typeof method !== 'function')
+            throw new Error(`Method ${frame.method} does not exist`);
+        if (!isCallable(method))
+            throw new Error(`Method ${frame.method} is not callable`);
+        if (callableMetadata(method)?.streaming) {
+            const stream = new StreamingResponse(connection, frame.id);
+            try {
+                await method.apply(target, [stream, ...frame.args]);
+            }
+            catch (e) {
+                if (!stream.isClosed)
+                    stream.error(errorMessage(e));
+            }
+            return;
+        }
+        const result = await method.apply(target, frame.args);
+        sendIfOpen(connection, { type: RPC_FRAME_TYPE, id: frame.id, success: true, result, done: true });
+    }
+    catch (e) {
+        sendIfOpen(connection, { type: RPC_FRAME_TYPE, id: frame.id, success: false, error: errorMessage(e) });
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'Unknown error occurred';
+}

package/dist/schedules.d.ts

@@ -0,0 +1,150 @@
+/**
+ * schedules.ts — named-method schedules persisted in the actor's own SQLite,
+ * dispatched from ONE reason in fabric's timer map.
+ *
+ * The API shape follows the Agents SDK (`agents` 0.20.1, verified in its
+ * shipped dist): `when` is a delay in seconds, a Date, or a cron string;
+ * recurrence is either `cron` (recomputed per fire) or `interval` (fixed
+ * seconds); rows carry the callback METHOD NAME and a JSON payload, and
+ * dispatch resolves the method on the target at fire time. Where the two
+ * differ, fabric's mechanism is the reason:
+ *
+ *   - RETRIES ARE DURABLE. The Agents SDK retries a failed callback
+ *     in-process, sleeping inside the alarm turn (dist `retries.js`, "Full
+ *     Jitter"); an instance reset mid-backoff loses the remaining attempts.
+ *     Here a failed attempt writes the backed-off deadline into the row and
+ *     the alarm re-fires on it — the attempt budget survives the reset.
+ *     Backoff is `min(maxDelayMs, baseDelayMs * 2**(attempt-1))`, no jitter:
+ *     the contended resource jitter exists for is a shared endpoint, and one
+ *     actor's own alarm is not shared.
+ *   - `alarmInfo` REACHES THE CALLBACK. The platform reports alarm retries
+ *     (`isRetry`, `retryCount`); the Agents SDK drops the report (zero
+ *     references in its dist). Fabric's dispatcher forwards it, and every
+ *     schedule callback receives it in its invocation argument.
+ *   - NO INTERVAL MUTEX. The Agents SDK guards overlapping interval runs
+ *     with a `running` flag and a hung-run timeout. Fabric's timer chain
+ *     already serializes dispatches on the instance, so overlap cannot
+ *     happen and the flag would be dead state.
+ *
+ * Times are epoch MILLISECONDS everywhere, matching fabric's timer map (the
+ * Agents SDK stores unix seconds).
+ *
+ * This module is deliberately partyserver-free: it owns rows and dispatch,
+ * and the Actor owns the timer-reason wiring around it.
+ */
+import type { TimerAlarmInfo } from '@nimbus-sh/fabric/timers.js';
+/** Synchronous DO SQLite, as the store uses it. */
+export interface ScheduleSqlExec {
+    exec(query: string, ...bindings: Array<string | number | null>): Iterable<unknown>;
+}
+export interface ScheduleContext {
+    storage: {
+        sql: ScheduleSqlExec;
+    };
+}
+/**
+ * Attempts and backoff for one schedule's callback. Defaults match the
+ * Agents SDK's (`maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 3000`,
+ * dist `index.js:303-308`).
+ */
+export interface ScheduleRetryPolicy {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+export declare const SCHEDULE_RETRY_DEFAULTS: Required<ScheduleRetryPolicy>;
+export interface ScheduleOptions {
+    retry?: ScheduleRetryPolicy;
+}
+/** One schedule, as `getScheduleById`/`listSchedules` return it. */
+export type Schedule<T = unknown> = {
+    id: string;
+    /** The method name dispatch resolves on the actor at fire time. */
+    callback: string;
+    payload: T;
+    retry?: ScheduleRetryPolicy;
+} & ({
+    type: 'scheduled';
+    time: number;
+} | {
+    type: 'delayed';
+    time: number;
+    delayInSeconds: number;
+} | {
+    type: 'cron';
+    time: number;
+    cron: string;
+} | {
+    type: 'interval';
+    time: number;
+    intervalSeconds: number;
+});
+export type ScheduleType = Schedule['type'];
+export interface ScheduleCriteria {
+    id?: string;
+    type?: ScheduleType;
+    /** Bounds on the next fire time. */
+    timeRange?: {
+        start?: Date;
+        end?: Date;
+    };
+}
+/** The second argument every schedule callback receives. */
+export interface ScheduleInvocation<T = unknown> {
+    schedule: Schedule<T>;
+    /** 1 on the first try; grows with the durable retry rows. */
+    attempt: number;
+    /** The platform's alarm-invocation report, when the platform gave one. */
+    alarmInfo?: TimerAlarmInfo;
+}
+export interface ScheduleDispatchResult {
+    ran: number;
+    /** The earliest remaining deadline, for the timer handler's re-arm. */
+    rearmAt: number | null;
+}
+export declare class ScheduleStore {
+    private readonly ctx;
+    private schemaReady;
+    constructor(ctx: ScheduleContext);
+    private ensureSchema;
+    /**
+     * Persist one schedule. `when` selects the type: a non-negative number is
+     * a delay in seconds, a Date is an absolute fire time, a string is a cron
+     * expression (validated here; an invalid one throws now, not at the
+     * alarm).
+     */
+    create<T>(when: number | Date | string, callback: string, payload?: T, options?: ScheduleOptions & {
+        now?: number;
+    }): Schedule<T>;
+    /** Persist a fixed-interval schedule. First fire is one interval from now. */
+    every<T>(intervalSeconds: number, callback: string, payload?: T, options?: ScheduleOptions & {
+        now?: number;
+    }): Schedule<T>;
+    private insert;
+    byId<T = unknown>(id: string): Schedule<T> | undefined;
+    list<T = unknown>(criteria?: ScheduleCriteria): Array<Schedule<T>>;
+    /** True when the id existed and is now gone. */
+    cancel(id: string): boolean;
+    /** The earliest pending deadline, or null when nothing is scheduled. */
+    nextDue(): number | null;
+    /**
+     * Fire every due schedule against the target, in deadline order.
+     *
+     * Each callback is `target[callback](payload, invocation)`, awaited in
+     * place. The due set is snapshotted up front, and every row is re-read
+     * before it fires — a callback that cancels or reschedules a SIBLING due
+     * row must win over the snapshot, or `cancel()`'s true would be a lie.
+     * Success advances the row: a cron recomputes from its expression, an
+     * interval re-arms `intervalSeconds` from this dispatch, a one-shot row
+     * is deleted. Failure spends one attempt of the row's retry policy: with
+     * budget left, the row's deadline moves to the backed-off time and the
+     * row survives; with the budget spent — or on a failure no retry can fix
+     * (the callback is not a method on the target; the stored payload does
+     * not parse) — `onError` hears about it and the row advances as if it
+     * had run.
+     */
+    dispatchDue(target: object, now: number, alarmInfo?: TimerAlarmInfo, onError?: (schedule: Schedule, error: unknown) => void): Promise<ScheduleDispatchResult>;
+    /** Move a row past a completed (or abandoned) fire. */
+    private advance;
+}
+//# sourceMappingURL=schedules.d.ts.map

package/dist/schedules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedules.d.ts","sourceRoot":"","sources":["../src/schedules.ts"],"names":[],"mappings":"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"}