@nimbus-sh/fabric 0.1.0 → 0.3.0

package/dist/sealed.d.ts

@@ -0,0 +1,78 @@
+/**
+ * sealed.ts — prototype-chain RPC sealing, and the versioned surface
+ * constants that make it safe to run over the Agents SDK.
+ *
+ * Cloudflare resolves `stub.foo(...)` on the receiver's PROTOTYPE CHAIN.
+ * Proteus verified the three consequences against real workerd
+ * (`cf-backend/src/rpc-surface.ts:4-22`, catalog `rpc.prototype_chain`,
+ * proven-by-probe): TypeScript `private` is erased, so private methods ARE
+ * callable over RPC; superclass methods are reachable too — inherited
+ * `Agent.sql` hands any stub-holder arbitrary SQL against the receiver's
+ * storage, and `Agent` + `Server` alone contribute hundreds of reachable
+ * names; and OWN instance properties are NOT reachable — workerd rejects
+ * them exactly as it rejects a missing name, including when the own
+ * property shadows a prototype method.
+ *
+ * That third consequence is the primitive: {@link sealRpcSurface} copies
+ * every reachable member that is NOT on the declared surface down onto the
+ * instance as a non-enumerable own property. In-process behaviour is
+ * unchanged — `this.x(...)` finds the same function object, `super.x()`
+ * still reaches the prototype, accessors stay accessors. From outside, the
+ * name has ceased to exist. Call it as the LAST statement of the
+ * constructor, after every base class installed its wrappers.
+ *
+ * The surface constants are the part that breaks whenever the SDK moves,
+ * which is why fabric owns them: Proteus reverse-engineered its facet
+ * surface from `agents/dist` by hand, and a fabric test diffs these
+ * constants against the INSTALLED packages so drift is caught by CI, not by
+ * a leak. Verified against agents@0.20.1 and partyserver@0.5.10
+ * (2026-08-19); an SDK upgrade that changes the cross-stub set fails that
+ * test and demands re-derivation, which is the intended failure.
+ */
+/**
+ * Every name RPC can resolve on `target`: own property names of every
+ * prototype up to (and excluding) Object.prototype, minus `constructor` and
+ * minus anything `target` already carries as an own property — own
+ * properties are not RPC-reachable, so they need no seal. The single
+ * definition {@link sealRpcSurface} and its tests both work from.
+ */
+export declare function rpcReachableNames(target: object): string[];
+/**
+ * Shadow every RPC-reachable member not on `surface` with a non-enumerable
+ * own property carrying the SAME descriptor — the same function object, the
+ * same accessor pair — so in-process behaviour cannot change while the name
+ * stops resolving over RPC. Surface names the class lacks are ignored: a
+ * surface is a ceiling, and the runtime already denies what does not exist.
+ */
+export declare function sealRpcSurface<Instance extends object>(instance: Instance, surface: readonly string[]): void;
+/**
+ * The platform half of any surface built on partyserver's `Server` (and
+ * therefore the Agents SDK's `Agent`): what the RUNTIME and the SDK's own
+ * routing must still reach after sealing. From the consumer's verified list
+ * (`rpc-surface.ts:63-86`): `setName` is called by `getServerByName` before
+ * the stub is returned; `_initAndFetch` is `setName` plus `fetch`, so it
+ * exposes nothing new; the WebSocket handlers' arguments cannot cross an
+ * RPC boundary anyway.
+ */
+export declare const PLATFORM_RPC_SURFACE: readonly ["fetch", "setName", "_initAndFetch", "alarm", "webSocketMessage", "webSocketClose", "webSocketError"];
+/**
+ * The Agents SDK's own cross-stub facet protocol at agents@0.20.1: every
+ * `_cf_` method the SDK calls on a receiver that is not `this`, derived
+ * from `agents/dist` (the SDK's ACTUAL cross-stub surface, not a prefix
+ * rule — Agent's prototype defines 58 `_cf_` methods and only these are
+ * cross-called). An Agent that hosts SDK facets must keep these; one that
+ * does not (Proteus's UserDO) should not carry them at all.
+ */
+export declare const AGENTS_FACET_RPC_SURFACE: readonly ["_cf_acquireFacetKeepAlive", "_cf_broadcastToSubAgent", "_cf_cancelScheduleForFacet", "_cf_checkRunFibersForFacet", "_cf_cleanupFacetPrefix", "_cf_closeSubAgentConnection", "_cf_destroyDescendantFacet", "_cf_dispatchScheduledCallback", "_cf_getScheduleForFacet", "_cf_handleSubAgentWebSocketClose", "_cf_handleSubAgentWebSocketConnect", "_cf_handleSubAgentWebSocketMessage", "_cf_initAsFacet", "_cf_listSchedulesForFacet", "_cf_registerFacetRun", "_cf_releaseFacetKeepAlive", "_cf_scheduleEveryForFacet", "_cf_scheduleForFacet", "_cf_sendToSubAgentConnection", "_cf_setSubAgentConnectionState", "_cf_subAgentConnectionMetas", "_cf_unregisterFacetRun"];
+/**
+ * Cross-stub `_cf_` members deliberately absent from EVERY surface: each
+ * takes a method NAME and calls it on the receiver, which would re-open
+ * everything sealing closes. Sealing them fail-closes the SDK features
+ * built on them (`parentAgent()` proxies, workflow-to-agent bridges) — the
+ * consumer accepts exactly that cost, and fail-closed is the right default
+ * for a bridge that dispatches arbitrary names. (`_cf_invokeStubMethod` is
+ * only ever self-called in the pinned dist, but it is prototype-defined, so
+ * it is named here and sealed.)
+ */
+export declare const AGENTS_INVOKE_BRIDGES: readonly ["_cf_invokeAgentPath", "_cf_invokeStubMethod", "_cf_invokeSubAgent", "_cf_invokeSubAgentPath"];
+//# sourceMappingURL=sealed.d.ts.map

package/dist/sealed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed.d.ts","sourceRoot":"","sources":["../src/sealed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAY1D;AAYD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAS,MAAM,EACpD,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,IAAI,CAON;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,iHAQvB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,upBAuB3B,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,0GAKxB,CAAC"}

package/dist/sealed.js

@@ -0,0 +1,145 @@
+/**
+ * sealed.ts — prototype-chain RPC sealing, and the versioned surface
+ * constants that make it safe to run over the Agents SDK.
+ *
+ * Cloudflare resolves `stub.foo(...)` on the receiver's PROTOTYPE CHAIN.
+ * Proteus verified the three consequences against real workerd
+ * (`cf-backend/src/rpc-surface.ts:4-22`, catalog `rpc.prototype_chain`,
+ * proven-by-probe): TypeScript `private` is erased, so private methods ARE
+ * callable over RPC; superclass methods are reachable too — inherited
+ * `Agent.sql` hands any stub-holder arbitrary SQL against the receiver's
+ * storage, and `Agent` + `Server` alone contribute hundreds of reachable
+ * names; and OWN instance properties are NOT reachable — workerd rejects
+ * them exactly as it rejects a missing name, including when the own
+ * property shadows a prototype method.
+ *
+ * That third consequence is the primitive: {@link sealRpcSurface} copies
+ * every reachable member that is NOT on the declared surface down onto the
+ * instance as a non-enumerable own property. In-process behaviour is
+ * unchanged — `this.x(...)` finds the same function object, `super.x()`
+ * still reaches the prototype, accessors stay accessors. From outside, the
+ * name has ceased to exist. Call it as the LAST statement of the
+ * constructor, after every base class installed its wrappers.
+ *
+ * The surface constants are the part that breaks whenever the SDK moves,
+ * which is why fabric owns them: Proteus reverse-engineered its facet
+ * surface from `agents/dist` by hand, and a fabric test diffs these
+ * constants against the INSTALLED packages so drift is caught by CI, not by
+ * a leak. Verified against agents@0.20.1 and partyserver@0.5.10
+ * (2026-08-19); an SDK upgrade that changes the cross-stub set fails that
+ * test and demands re-derivation, which is the intended failure.
+ */
+/**
+ * Every name RPC can resolve on `target`: own property names of every
+ * prototype up to (and excluding) Object.prototype, minus `constructor` and
+ * minus anything `target` already carries as an own property — own
+ * properties are not RPC-reachable, so they need no seal. The single
+ * definition {@link sealRpcSurface} and its tests both work from.
+ */
+export function rpcReachableNames(target) {
+    const names = new Set();
+    const own = new Set(Object.getOwnPropertyNames(target));
+    let proto = Object.getPrototypeOf(target);
+    while (proto !== null && proto !== Object.prototype) {
+        for (const name of Object.getOwnPropertyNames(proto)) {
+            if (name === 'constructor' || own.has(name))
+                continue;
+            names.add(name);
+        }
+        proto = Object.getPrototypeOf(proto);
+    }
+    return [...names].sort();
+}
+function inheritedDescriptor(target, name) {
+    let proto = Object.getPrototypeOf(target);
+    while (proto !== null && proto !== Object.prototype) {
+        const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+        if (descriptor)
+            return descriptor;
+        proto = Object.getPrototypeOf(proto);
+    }
+    return undefined;
+}
+/**
+ * Shadow every RPC-reachable member not on `surface` with a non-enumerable
+ * own property carrying the SAME descriptor — the same function object, the
+ * same accessor pair — so in-process behaviour cannot change while the name
+ * stops resolving over RPC. Surface names the class lacks are ignored: a
+ * surface is a ceiling, and the runtime already denies what does not exist.
+ */
+export function sealRpcSurface(instance, surface) {
+    const allowed = new Set(surface);
+    for (const name of rpcReachableNames(instance)) {
+        if (allowed.has(name))
+            continue;
+        const descriptor = inheritedDescriptor(instance, name);
+        if (descriptor)
+            Object.defineProperty(instance, name, { ...descriptor, enumerable: false });
+    }
+}
+/**
+ * The platform half of any surface built on partyserver's `Server` (and
+ * therefore the Agents SDK's `Agent`): what the RUNTIME and the SDK's own
+ * routing must still reach after sealing. From the consumer's verified list
+ * (`rpc-surface.ts:63-86`): `setName` is called by `getServerByName` before
+ * the stub is returned; `_initAndFetch` is `setName` plus `fetch`, so it
+ * exposes nothing new; the WebSocket handlers' arguments cannot cross an
+ * RPC boundary anyway.
+ */
+export const PLATFORM_RPC_SURFACE = [
+    'fetch',
+    'setName',
+    '_initAndFetch',
+    'alarm',
+    'webSocketMessage',
+    'webSocketClose',
+    'webSocketError',
+];
+/**
+ * The Agents SDK's own cross-stub facet protocol at agents@0.20.1: every
+ * `_cf_` method the SDK calls on a receiver that is not `this`, derived
+ * from `agents/dist` (the SDK's ACTUAL cross-stub surface, not a prefix
+ * rule — Agent's prototype defines 58 `_cf_` methods and only these are
+ * cross-called). An Agent that hosts SDK facets must keep these; one that
+ * does not (Proteus's UserDO) should not carry them at all.
+ */
+export const AGENTS_FACET_RPC_SURFACE = [
+    '_cf_acquireFacetKeepAlive',
+    '_cf_broadcastToSubAgent',
+    '_cf_cancelScheduleForFacet',
+    '_cf_checkRunFibersForFacet',
+    '_cf_cleanupFacetPrefix',
+    '_cf_closeSubAgentConnection',
+    '_cf_destroyDescendantFacet',
+    '_cf_dispatchScheduledCallback',
+    '_cf_getScheduleForFacet',
+    '_cf_handleSubAgentWebSocketClose',
+    '_cf_handleSubAgentWebSocketConnect',
+    '_cf_handleSubAgentWebSocketMessage',
+    '_cf_initAsFacet',
+    '_cf_listSchedulesForFacet',
+    '_cf_registerFacetRun',
+    '_cf_releaseFacetKeepAlive',
+    '_cf_scheduleEveryForFacet',
+    '_cf_scheduleForFacet',
+    '_cf_sendToSubAgentConnection',
+    '_cf_setSubAgentConnectionState',
+    '_cf_subAgentConnectionMetas',
+    '_cf_unregisterFacetRun',
+];
+/**
+ * Cross-stub `_cf_` members deliberately absent from EVERY surface: each
+ * takes a method NAME and calls it on the receiver, which would re-open
+ * everything sealing closes. Sealing them fail-closes the SDK features
+ * built on them (`parentAgent()` proxies, workflow-to-agent bridges) — the
+ * consumer accepts exactly that cost, and fail-closed is the right default
+ * for a bridge that dispatches arbitrary names. (`_cf_invokeStubMethod` is
+ * only ever self-called in the pinned dist, but it is prototype-defined, so
+ * it is named here and sealed.)
+ */
+export const AGENTS_INVOKE_BRIDGES = [
+    '_cf_invokeAgentPath',
+    '_cf_invokeStubMethod',
+    '_cf_invokeSubAgent',
+    '_cf_invokeSubAgentPath',
+];

package/dist/timers.d.ts

@@ -0,0 +1,138 @@
+/**
+ * timers.ts — Durable Object alarm multiplexing, persisted across
+ * hibernation.
+ *
+ * A Durable Object has ONE alarm, and a second `setAlarm()` silently
+ * overwrites the first — so every alarm-driven subsystem coordinates through
+ * a single reason→deadline map and one dispatcher. Reasons are plain strings
+ * registered by the embedder: `timers(host, ctx).schedule` arms one, and
+ * `timers(host, ctx).dispatch` runs the embedder-supplied handler for every
+ * reason whose deadline has passed.
+ */
+/**
+ * The storage the timer map lives in. `setAlarm` is optional because
+ * `wrangler dev` serves a storage without it, which is the whole reason
+ * scheduling degrades to a no-op instead of throwing.
+ */
+export interface TimerStorage {
+    get(key: string): Promise<unknown>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    setAlarm?(scheduledTime: number): Promise<void>;
+}
+/** The hosting actor's context, as the timer coordination reads it. */
+export interface TimerContext {
+    storage: TimerStorage;
+}
+/**
+ * Multi-reason timer coordination map.
+ *
+ * JSON-serialised `Record<reason, deadlineMsEpoch>` where keys are the
+ * embedder's canonical reason strings (e.g. 'w9-flush', 'log-janitor'). The
+ * alarm() dispatcher reads this on fire, dispatches every reason whose
+ * deadline has passed, and re-arms `ctx.storage.setAlarm` at the earliest
+ * remaining deadline.
+ *
+ * Why a map (not a single nextAlarmAt + reason): two subsystems can have
+ * distinct deadlines. Without the map, the later setAlarm() call would
+ * overwrite the earlier reason silently, breaking whichever subsystem
+ * expected its deadline.
+ *
+ * Forward-compat: the dispatcher silently drops unknown reasons so a
+ * rollback from a future deploy that added new reasons doesn't leave the
+ * alarm stuck.
+ *
+ * The VALUE is live production DO storage ('w1_next_alarm_reasons', from the
+ * workstream that introduced it) and must never change — renaming a storage
+ * key is a migration, and orphaned rows are the least of what it breaks.
+ */
+export declare const TIMER_REASONS_KEY = "w1_next_alarm_reasons";
+/**
+ * The host instance carrying the per-instance timer chain. The field lives on
+ * the embedder's DO instance so one chain serializes every timer-map
+ * read-modify-write for that instance (see {@link Timers.schedule}).
+ */
+export interface TimerHost {
+    _timerChain?: Promise<unknown>;
+}
+/**
+ * What one timer handler may return: nothing, or a deadline this reason
+ * re-arms itself at. Re-arming through the return value keeps the map's
+ * read-modify-write inside the dispatcher, where it is serialized.
+ */
+export type TimerHandlerResult = void | {
+    rearmAt: number;
+};
+/**
+ * The platform's alarm-invocation report, forwarded to every handler: the
+ * platform retries a failed alarm() with backoff and abandons it after its
+ * retry budget, and `isRetry`/`retryCount` are the only way a handler can
+ * tell how close it is to that abandonment. Structurally identical to
+ * workers-types' AlarmInvocationInfo; declared here so the module stays
+ * usable without the ambient types.
+ */
+export interface TimerAlarmInfo {
+    readonly isRetry: boolean;
+    readonly retryCount: number;
+    readonly scheduledTime: number;
+}
+/** The embedder's reasons, each with the handler that answers it. */
+export type TimerHandlers = Record<string, (now: number, info?: TimerAlarmInfo) => TimerHandlerResult | Promise<TimerHandlerResult>>;
+/**
+ * One actor's timers: the reason map over its ONE platform alarm.
+ *
+ * A cheap accessor over `(host, ctx)` — the chain that serializes the map's
+ * read-modify-write lives on the host instance, so every `timers()` call for
+ * one instance coordinates through the same chain.
+ */
+export declare function timers(host: TimerHost, ctx: TimerContext): Timers;
+export declare class Timers {
+    private readonly host;
+    private readonly ctx;
+    constructor(host: TimerHost, ctx: TimerContext);
+    /**
+     * Schedule (or re-schedule) a timer reason. Coordinated via a single map in
+     * DO storage so multiple subsystems don't clobber each other's `setAlarm()`
+     * calls.
+     *
+     * Semantics:
+     *   - Reads the existing reasons map.
+     *   - Sets `map[reason] = whenMs` IF `whenMs` is sooner than the
+     *     currently-pending deadline for that reason (or no entry exists).
+     *     Later-than-pending requests are silently ignored — the existing
+     *     alarm will fire and re-arm anyway.
+     *   - Writes the map back and calls `ctx.storage.setAlarm(min(deadlines))`.
+     *
+     * Cost: 1 storage read + 1 storage write + 1 setAlarm per call. setAlarm
+     * itself is billed as 1 row written per DO pricing. At a 60s janitor
+     * cadence, this is ~$0.05/mo/session at scale — dwarfed by the
+     * hibernation duration savings.
+     *
+     * Fail-soft: any throw is swallowed with a warn. On older runtimes /
+     * wrangler-dev where setAlarm is unavailable, this is a no-op (the
+     * subsystem's in-isolate setTimeout fallback continues to work).
+     */
+    schedule(reason: string, whenMs: number): Promise<boolean>;
+    /**
+     * Multi-reason timer dispatcher. Called from the DO's `alarm()` handler
+     * with the embedder's handler map.
+     *
+     * For each pending reason whose deadline has passed, run its handler.
+     * Handlers are awaited in place: the alarm invocation is the fresh turn a
+     * re-entering subsystem asked for, and it has to stay the one paying for the
+     * work it just released.
+     *
+     * After running fireable reasons, re-arms `ctx.storage.setAlarm` at the
+     * earliest remaining deadline. If no reasons remain, deletes the map key and
+     * does NOT call setAlarm — the DO becomes hibernation-eligible after the 10s
+     * idle window.
+     *
+     * Forward/back-compat: unknown reasons silently dropped. `onLegacyAlarm`
+     * covers an alarm that fires with no map at all — a deploy from before the
+     * map existed left a bare `setAlarm` behind, and the embedder decides what
+     * that one-time fire means (one dispatch later the map is populated by the
+     * next schedule call).
+     */
+    dispatch(handlers: TimerHandlers, onLegacyAlarm?: () => void, alarmInfo?: TimerAlarmInfo): Promise<void>;
+}
+//# sourceMappingURL=timers.d.ts.map

package/dist/timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../src/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,QAAQ,CAAC,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB,0BAA0B,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAChC;AAmBD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAChC,MAAM,EACN,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,KAAK,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CACzF,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,YAAY,GAAG,MAAM,CAEjE;AAED,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,YAAY;IAGpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4C1D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CACN,QAAQ,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,MAAM,IAAI,EAC1B,SAAS,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,IAAI,CAAC;CAWjB"}

package/dist/timers.js

@@ -0,0 +1,231 @@
+/**
+ * timers.ts — Durable Object alarm multiplexing, persisted across
+ * hibernation.
+ *
+ * A Durable Object has ONE alarm, and a second `setAlarm()` silently
+ * overwrites the first — so every alarm-driven subsystem coordinates through
+ * a single reason→deadline map and one dispatcher. Reasons are plain strings
+ * registered by the embedder: `timers(host, ctx).schedule` arms one, and
+ * `timers(host, ctx).dispatch` runs the embedder-supplied handler for every
+ * reason whose deadline has passed.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { errorText } from '@nimbus-sh/core/_shared/error-text.js';
+/**
+ * Multi-reason timer coordination map.
+ *
+ * JSON-serialised `Record<reason, deadlineMsEpoch>` where keys are the
+ * embedder's canonical reason strings (e.g. 'w9-flush', 'log-janitor'). The
+ * alarm() dispatcher reads this on fire, dispatches every reason whose
+ * deadline has passed, and re-arms `ctx.storage.setAlarm` at the earliest
+ * remaining deadline.
+ *
+ * Why a map (not a single nextAlarmAt + reason): two subsystems can have
+ * distinct deadlines. Without the map, the later setAlarm() call would
+ * overwrite the earlier reason silently, breaking whichever subsystem
+ * expected its deadline.
+ *
+ * Forward-compat: the dispatcher silently drops unknown reasons so a
+ * rollback from a future deploy that added new reasons doesn't leave the
+ * alarm stuck.
+ *
+ * The VALUE is live production DO storage ('w1_next_alarm_reasons', from the
+ * workstream that introduced it) and must never change — renaming a storage
+ * key is a migration, and orphaned rows are the least of what it breaks.
+ */
+export const TIMER_REASONS_KEY = 'w1_next_alarm_reasons';
+/**
+ * The async context of a running dispatch's handlers. A schedule request
+ * made inside it lands in the dispatch's arm collection instead of the
+ * chain — a handler that AWAITED a chained schedule would be waiting on an
+ * entry queued behind the dispatch it is running inside, which is a
+ * deadlock. `Outbox.queue` awaits `timers.schedule`, so any handler that
+ * queues into an outbox reaches this. The dispatcher folds the collected
+ * arms into the reason map before its own re-arm.
+ *
+ * AsyncLocalStorage, not a host field, so the redirect is scoped to the
+ * dispatch's OWN async context: a concurrent turn that schedules while a
+ * handler awaits external IO takes the normal chain path and keeps its own
+ * turn-gated persistence. Requires the `nodejs_compat` (or `nodejs_als`)
+ * compatibility flag on workerd.
+ */
+const dispatchArms = new AsyncLocalStorage();
+/**
+ * One actor's timers: the reason map over its ONE platform alarm.
+ *
+ * A cheap accessor over `(host, ctx)` — the chain that serializes the map's
+ * read-modify-write lives on the host instance, so every `timers()` call for
+ * one instance coordinates through the same chain.
+ */
+export function timers(host, ctx) {
+    return new Timers(host, ctx);
+}
+export class Timers {
+    host;
+    ctx;
+    constructor(host, ctx) {
+        this.host = host;
+        this.ctx = ctx;
+    }
+    /**
+     * Schedule (or re-schedule) a timer reason. Coordinated via a single map in
+     * DO storage so multiple subsystems don't clobber each other's `setAlarm()`
+     * calls.
+     *
+     * Semantics:
+     *   - Reads the existing reasons map.
+     *   - Sets `map[reason] = whenMs` IF `whenMs` is sooner than the
+     *     currently-pending deadline for that reason (or no entry exists).
+     *     Later-than-pending requests are silently ignored — the existing
+     *     alarm will fire and re-arm anyway.
+     *   - Writes the map back and calls `ctx.storage.setAlarm(min(deadlines))`.
+     *
+     * Cost: 1 storage read + 1 storage write + 1 setAlarm per call. setAlarm
+     * itself is billed as 1 row written per DO pricing. At a 60s janitor
+     * cadence, this is ~$0.05/mo/session at scale — dwarfed by the
+     * hibernation duration savings.
+     *
+     * Fail-soft: any throw is swallowed with a warn. On older runtimes /
+     * wrangler-dev where setAlarm is unavailable, this is a no-op (the
+     * subsystem's in-isolate setTimeout fallback continues to work).
+     */
+    schedule(reason, whenMs) {
+        const { host, ctx } = this;
+        // From inside a dispatch handler, hand the arm to the dispatcher
+        // instead of the chain (see dispatchArms): the fold keeps EDF
+        // semantics, and the dispatch's own write and re-arm carry it. The
+        // setAlarm gate matches the chain path's, so both paths refuse alike
+        // on a runtime without alarms.
+        const arms = dispatchArms.getStore();
+        if (arms) {
+            if (typeof ctx?.storage?.setAlarm !== 'function')
+                return Promise.resolve(false);
+            arms.push({ reason, whenMs });
+            return Promise.resolve(true);
+        }
+        // Serialize every read-modify-write of the reasons map through one
+        // per-instance chain: two schedulers firing back-to-back from one activity
+        // hook would otherwise interleave their get→put cycles and silently drop
+        // whichever reason wrote first.
+        const run = async () => {
+            try {
+                const setAlarmFn = ctx?.storage?.setAlarm;
+                if (typeof setAlarmFn !== 'function')
+                    return false;
+                const existing = (await ctx.storage.get(TIMER_REASONS_KEY));
+                const map = { ...(existing || {}) };
+                // Earliest-deadline-first: only update if new request is sooner or
+                // this reason has no pending entry.
+                if (!(reason in map) || whenMs < map[reason]) {
+                    map[reason] = whenMs;
+                    await ctx.storage.put(TIMER_REASONS_KEY, map);
+                }
+                const earliest = Math.min(...Object.values(map));
+                setAlarmFn.call(ctx.storage, earliest);
+                return true;
+            }
+            catch (e) {
+                console.warn('[nimbus/W1] timers.schedule threw:', errorText(e));
+                return false;
+            }
+        };
+        const chained = (host._timerChain ?? Promise.resolve()).then(run, run);
+        host._timerChain = chained;
+        return chained;
+    }
+    /**
+     * Multi-reason timer dispatcher. Called from the DO's `alarm()` handler
+     * with the embedder's handler map.
+     *
+     * For each pending reason whose deadline has passed, run its handler.
+     * Handlers are awaited in place: the alarm invocation is the fresh turn a
+     * re-entering subsystem asked for, and it has to stay the one paying for the
+     * work it just released.
+     *
+     * After running fireable reasons, re-arms `ctx.storage.setAlarm` at the
+     * earliest remaining deadline. If no reasons remain, deletes the map key and
+     * does NOT call setAlarm — the DO becomes hibernation-eligible after the 10s
+     * idle window.
+     *
+     * Forward/back-compat: unknown reasons silently dropped. `onLegacyAlarm`
+     * covers an alarm that fires with no map at all — a deploy from before the
+     * map existed left a bare `setAlarm` behind, and the embedder decides what
+     * that one-time fire means (one dispatch later the map is populated by the
+     * next schedule call).
+     */
+    dispatch(handlers, onLegacyAlarm, alarmInfo) {
+        const { host, ctx } = this;
+        // Same serialization as schedule: the dispatcher's read→handlers→write
+        // cycle must not interleave with an activity-hook schedule.
+        const chained = (host._timerChain ?? Promise.resolve()).then(() => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo), () => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo));
+        host._timerChain = chained;
+        return chained;
+    }
+}
+async function dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo) {
+    // Collect schedule requests made inside handler context (see
+    // dispatchArms) and fold them into the map below, so an in-dispatch arm
+    // neither deadlocks on the chain nor races the write.
+    const arms = [];
+    try {
+        const now = Date.now();
+        const existing = (await ctx?.storage?.get?.(TIMER_REASONS_KEY));
+        const map = { ...(existing || {}) };
+        const hadMap = Object.keys(map).length > 0;
+        if (!hadMap) {
+            dispatchArms.run(arms, () => onLegacyAlarm?.());
+        }
+        else {
+            // Snapshot fireable reasons BEFORE running any of them, so a
+            // handler that schedules itself for the next cycle doesn't get
+            // immediately re-fired in the same dispatch.
+            const fired = [];
+            for (const [reason, when] of Object.entries(map)) {
+                if (when <= now)
+                    fired.push(reason);
+            }
+            for (const reason of fired) {
+                delete map[reason];
+                const handler = handlers[reason];
+                // Unknown reasons silently dropped (forward-compat).
+                if (!handler)
+                    continue;
+                try {
+                    const result = await dispatchArms.run(arms, () => handler(now, alarmInfo));
+                    if (result && typeof result.rearmAt === 'number') {
+                        map[reason] = result.rearmAt;
+                    }
+                }
+                catch (e) {
+                    console.warn(`[nimbus/W1] dispatch ${reason} threw:`, errorText(e));
+                }
+            }
+        }
+        // Fold the in-dispatch arms, earliest-deadline-first per reason.
+        for (const arm of arms) {
+            if (!(arm.reason in map) || arm.whenMs < map[arm.reason]) {
+                map[arm.reason] = arm.whenMs;
+            }
+        }
+        // Re-arm or clear.
+        const setAlarmFn = ctx?.storage?.setAlarm;
+        if (Object.keys(map).length > 0) {
+            await ctx.storage.put(TIMER_REASONS_KEY, map);
+            const earliest = Math.min(...Object.values(map));
+            if (typeof setAlarmFn === 'function') {
+                setAlarmFn.call(ctx.storage, earliest);
+            }
+        }
+        else if (hadMap) {
+            try {
+                await ctx.storage.delete(TIMER_REASONS_KEY);
+            }
+            catch { }
+            // No remaining reasons → no setAlarm call → DO becomes
+            // hibernation-eligible after the 10s idle window.
+        }
+    }
+    catch (e) {
+        console.warn('[nimbus/W1] timers.dispatch threw:', errorText(e));
+    }
+}