@nimbus-sh/fabric 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Kumar Singh and Nimbus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,487 @@
+# @nimbus-sh/fabric
+
+> Part of [Nimbus](https://github.com/AshishKumar4/Nimbus), my hobby/research
+> cloud OS. This README is edited and maintained with Claude (AI) and
+> presented as-is.
+
+The Cloudflare-specific half of Nimbus: the machinery for running real
+programs on Durable Objects, DO facets, and the Worker Loader. Where
+[`@nimbus-sh/core`](https://www.npmjs.com/package/@nimbus-sh/core) is the
+backend-agnostic OS (filesystem, shell, process contracts), this package is
+what that OS stands on when the host is Cloudflare — and it never imports the
+OS's policy, only its shared primitives.
+
+I extracted it because almost none of it is specific to Nimbus. Anyone who
+hosts long-lived processes on Durable Objects meets the same platform
+behaviors we did: `await put()` resolving before durability, one alarm per
+object, a 65,536-facet lifetime budget, a frozen in-DO clock, RPC stubs that
+die with their request context. This package is the machinery we built against
+those behaviors, with the measured numbers that justified each mechanism
+carried in the doc comments — they are the design record, and they travel with
+the code on purpose.
+
+Everything below was measured on deployed production workerd, not on
+`wrangler dev` and not inferred from types, between June and August 2026.
+Where a specific date matters it is given.
+
+## Importing it
+
+The root export pulls `cloudflare:workers`, so `import ... from
+'@nimbus-sh/fabric'` resolves only inside a Worker. Outside workerd (unit
+tests, tooling) import the subpath modules directly —
+`@nimbus-sh/fabric/alarms.js`, `@nimbus-sh/fabric/launch-journal.js`, and so
+on. Most of the package is structurally typed against plain objects precisely
+so it can be tested in bun or node.
+
+An embedder wires three seams at composition time, each first-write-wins:
+
+```ts
+import { setCtxExports, setSupervisorEntrypointName, setStagedBootAssembler } from '@nimbus-sh/fabric';
+
+// In the Worker's fetch handler, once:
+setCtxExports(ctx.exports);
+// The name of your supervisor WorkerEntrypoint export. The fabric mints one
+// binding per hosted program from it (env.SUPERVISOR inside the facet).
+setSupervisorEntrypointName('MySupervisorRPC');
+// Only if you use 'staged' boot specs; 'code' boots need no assembler.
+setStagedBootAssembler(async (env, stage) => assembleLoaderConfig(env, stage));
+```
+
+## One alarm, many reasons
+
+A Durable Object has ONE alarm, and a second `setAlarm()` silently overwrites
+the first. Every alarm-driven subsystem therefore coordinates through a single
+reason→deadline map in storage, with one dispatcher:
+
+```ts
+import { DurableObject } from 'cloudflare:workers';
+import { scheduleAlarm, dispatchAlarm } from '@nimbus-sh/fabric';
+
+export class MySession extends DurableObject {
+  _alarmChain?: Promise<unknown>;   // serializes the map's read-modify-write
+
+  async fetch(request: Request): Promise<Response> {
+    await scheduleAlarm(this, this.ctx, 'janitor', Date.now() + 60_000);
+    return new Response('ok');
+  }
+
+  async alarm(): Promise<void> {
+    await dispatchAlarm(this, this.ctx, {
+      janitor: async (now) => {
+        await this.cleanUp();
+        return { rearmAt: now + 60_000 };   // re-arm through the return value
+      },
+    });
+  }
+}
+```
+
+`scheduleAlarm` keeps the earliest deadline per reason and arms the real alarm
+at the minimum across all of them. `dispatchAlarm` snapshots the fireable set
+before running any handler (so a handler that re-schedules itself is not
+re-fired in the same dispatch), silently drops unknown reasons (a rollback
+from a deploy that added reasons must not wedge the alarm), and when no
+reasons remain it deletes the map and does not re-arm — which is what lets the
+object hibernate.
+
+## Knowing which incarnation you are
+
+Workerd recycles isolates freely: cold starts, hibernation wakes, and resets
+all hand you a fresh module scope over the same storage. The isolate
+generation is a persisted counter that increments once per fresh isolate, and
+process IDs derive from it (`PID_GEN_STRIDE` = 1,000,000 in core's process
+table), which yields the one reset predicate everything else builds on: **a
+pid at or below the current generation's base was allocated by a previous
+incarnation.**
+
+```ts
+import { maybeBumpIsolateGen } from '@nimbus-sh/fabric';
+
+export class MySession extends DurableObject {
+  _isolateGen = 0;
+  _isolateGenPersisted = false;
+
+  async fetch(request: Request): Promise<Response> {
+    await maybeBumpIsolateGen(this, this.ctx);   // idempotent per instance
+    // this._isolateGen is now this incarnation's generation
+  }
+}
+```
+
+The ordering inside is deliberate: adopt the persisted value first, bump only
+after the `put` resolves. An unpersisted bump would be re-read by the next
+boot and re-issued — two instances sharing one generation is exactly the pid
+aliasing the counter exists to prevent. Note that `await put()` returning is
+not durability; the output gate is what keeps a pid from generation N from
+escaping before N is on disk.
+
+## The launch journal: surviving resets
+
+The platform resets a Durable Object over what one turn has outstanding in
+storage, and the reset destroys every write that turn had in flight. A
+long-running launch holds everything in memory, so the process it is building
+dies silently with the instance. The journal is what a later instance reads to
+know that happened:
+
+```ts
+import { ResidentLaunchJournal, type ResidentLaunchRecord } from '@nimbus-sh/fabric';
+
+interface MyLaunch extends ResidentLaunchRecord {
+  argv: string[];   // whatever your redrive needs; the journal never reads it
+}
+
+const journal = new ResidentLaunchJournal<MyLaunch>(this.ctx.storage, {
+  generationBase: () => this.pidBase,
+  waitUntil: (p) => this.ctx.waitUntil(p),
+  redrive: (record, attempt) => this.launch(record.argv, attempt),
+});
+
+// Before the launch's first byte of real work:
+await journal.journal({ pid, command, attempt: 0, phase: 'starting', argv });
+// When the PROCESS (not the launch) ends:
+await journal.release(pid);
+// On the first turn after any reset (the turn pump calls this):
+await journal.recoverInterrupted();
+```
+
+Two details here cost us real incidents before they were mechanisms:
+
+- **`put` then `sync()`.** `await storage.put()` resolves before durability.
+  Measured live: a launch killed in its first chunks left NO row for the
+  replacement instance to find, which is how the recovery this feeds sat inert
+  while its own test stayed green. `sync()` is the storage layer's durability
+  barrier; the journal writes through it on the way in and on the way out
+  (delete-then-sync, so a reset moments after release cannot resurrect a
+  process the user watched end).
+- **The row lives for the process's lifetime, not the launch's.** Measured on
+  staging, 2026-08-13: every observed reset struck seconds AFTER the launch
+  settled. A launch-scoped row would already have been deleted when recovery
+  went looking.
+
+Recovery applies the generation predicate (`pid <= generationBase()`), deletes
+each stale row, and re-drives once per record (`RESIDENT_LAUNCH_MAX_ATTEMPT` =
+1) — a reset that recurs is not the transient kind.
+
+## Pacing big work across turns
+
+One DO turn has a CPU budget of about 30 s (we were killed with `exceededCpu`
+at 31.8 s and 32.5 s), and yielding inside an invocation buys nothing — CPU
+accrues to the invocation, and only genuinely re-entering the object resets
+it. Worse, a long turn pins the actor's only thread, so the terminal WebSocket
+dies even when the work succeeds. And progress cannot be measured in
+milliseconds, because the in-DO clock does not advance without I/O (0 ms
+across 200,000 consecutive reads). So the pacer accounts **bytes**:
+
+```ts
+import { LaunchPacer, LaunchTurnPump, scheduleAlarm } from '@nimbus-sh/fabric';
+
+const pump = new LaunchTurnPump({
+  requestTurn: () => { void scheduleAlarm(this, this.ctx, 'launch-turn', Date.now()); },
+  recover: () => journal.recoverInterrupted(),
+});
+const pacer = new LaunchPacer(pump);
+
+// Inside the launch, after each unit of work:
+await pacer.spend(bytesJustProcessed);   // suspends every LAUNCH_CHUNK_MAX_BYTES (2 MB)
+// In alarm(), as one of the dispatcher's reasons:
+'launch-turn': () => pump.pump(),
+```
+
+The pump awaits each resumed chunk, so the invocation that granted the turn is
+the invocation that pays for the work — nothing runs detached in a handler's
+microtask drain. A past-deadline alarm is delivered as soon as the object is
+free, which makes `scheduleAlarm(..., Date.now())` a genuine "re-enter now"
+primitive. Without an alarm-capable host the pump degrades to a same-context
+timer: the single-turn behaviour this path always had, minus the
+responsiveness.
+
+## Running programs: the loader pool
+
+`LoaderPool` runs plain functions in warm dynamic-worker isolates over
+`env.LOADER`. Functions are serialized with `fn.toString()`, so they must be
+self-contained: no captured variables, no `this` (rejected at dispatch), and
+their last parameter receives the forwarded bindings.
+
+```ts
+import { LoaderPool } from '@nimbus-sh/fabric';
+
+const pool = new LoaderPool(env, this.ctx, {
+  concurrency: 4,
+  tag: 'checksum',
+  omitSupervisor: true,   // this pool needs no callback into the DO
+});
+try {
+  const sums = await pool.map(async (text: string) => {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+  }, inputs);
+} finally {
+  pool.dispose();   // releases the pool's long-lived RPC stubs
+}
+```
+
+Slots are stable (`slot = index % concurrency`) so a batch of 67 tarball
+extractions reuses 4 warm isolates instead of paying 67 cold starts. Wasm
+rides the loader's modules map as `{ wasm: ArrayBuffer }` — the only path that
+works, since request-time `WebAssembly.compile` is CSP-blocked, RPC of a
+compiled `Module` is refused by structured clone, and inlining bytes into the
+module source OOMs the supervisor.
+
+The cache key folds the function hash, the preamble hash, a wasm fingerprint,
+and **the first 12 characters of the owning DO's id**. That last term is a
+security lesson, not an optimization: without it, session B's pool reused
+session A's warm isolate — which still carried A's `env.SUPERVISOR` binding —
+and B's writes landed silently in A's filesystem while B's install reported
+success. Warm isolates are scoped to one session unless a pool explicitly opts
+into `cacheScope: 'global'`, which is reserved for stateless compute pools
+that take no supervisor binding and retain no user state.
+
+`FanoutPool` is the tier above: a single DO method can drive at most 4
+concurrent Worker Loader fetches, so batches of fewer than 5 tasks run in the
+coordinator through a `LoaderPool` and wider batches shard deterministically
+across sibling DOs (up to 32, dispatched in phases of 4 to bound simultaneous
+cold starts). Transient peer resets retry on a 250/750/1500 ms schedule; an
+overloaded peer gets the 1/3/6 s one.
+
+Every fabric call into the loader lands on a per-DO ledger: distinct ids ever
+gotten — each permanently holds one of the ~5–6 dynamic-worker slots, because
+a keyed `loader.get(id)` is never released — plus live and peak concurrent
+Loader fetches, read via `loaderLedgerStats(ctx)`. A "Too many concurrent
+dynamic workers" refusal classifies as `dynamic_worker_cap` and is annotated
+with the ids actually holding slots. Measurement and honest failure naming
+only — no admission control, because the cap is the platform's and
+approximate, and a gate on an approximate number would refuse work the
+platform would have run.
+
+## Running processes: the resident fabric
+
+A resident process — a dev server, a socket runner, an attached TUI — is a DO
+facet whose class comes from a dynamic worker. `openResidentFacet` is the one
+way such a process comes into existence; `ProcessFabric` is the lifecycle
+around it:
+
+```ts
+import { ProcessFabric, createProcessHost } from '@nimbus-sh/fabric';
+
+const fabric = new ProcessFabric(createProcessHost('facet', this.ctx, env, () => diskReader));
+
+const handle = await fabric.startResidentProcess({
+  startContract: 'boot',            // or 'lifetime' — see below
+  pid,
+  workerKey: `nimbus-process:${this.ctx.id}:${pid}`,
+  boot: { kind: 'code', code: spec },   // a ResidentCodeSpec
+  startArgs: { port: 3000 },
+  onWriterActivated: (writerId) => this.writers.add(writerId),
+  onWriterRetired: (writerId) => this.writers.delete(writerId),
+});
+
+const payload = await handle.booted();
+// Inbound HTTP for the process's ports:
+const response = await handle.routeTarget.handleHttpRequest(request);
+// Teardown:
+handle.kill();
+await handle.done;
+```
+
+The dynamic worker must export a Durable Object class named `NimbusProcess`
+(`RESIDENT_PROCESS_CLASS`) with `startProcess(args)` and
+`handleHttpRequest(request)`. Its `startProcess` declares one of two contracts:
+`'lifetime'` (the call is held open for the process's whole life and settles at
+exit — an attached TUI) or `'boot'` (the call returns a payload once the
+process is up and the facet stays resident — a server).
+
+Pieces worth knowing about, each earned the hard way:
+
+- **The slot book.** A Durable Object admits 65,536 facets over its LIFETIME —
+  the IDs are append-only and never reclaimed, so the bound is on facets ever
+  created. Naming facets after pids burned one ID per spawn with no way back.
+  Reusing a NAME costs no new ID, so facet names come from a per-DO free list
+  (`proc-slot-<n>`, lowest reused first), and a slot is released only after
+  `facets.abort` + `facets.delete` — a slot handed out during teardown would
+  put two processes on one name. The names the book does mint are counted
+  durably — `facetIdBudget(ctx)` reports `{ consumed, budget }`, first uses
+  only, adopted across resets — and a creation failure with the budget
+  consumed names the budget and the count instead of repeating the platform's
+  opaque message. Exhaustion is permanent for the object, so it is the one
+  failure worth naming precisely.
+- **At-most-once start.** The facet's start callback re-running would
+  re-execute the user's program, answering a request from a process the user
+  never started. Both re-entry cases (released, lost) throw instead.
+- **Boot specs name large members by VFS path.** A whole structured-clone RPC
+  value caps at 32 MiB, and one node snapshot alone serialized to 44,252,709
+  bytes. `vfsWasmModules` and `vfsTextModules` send paths; the hosting actor
+  reads the bytes through the `ResidentDiskReader` it was given, inside the
+  loader's cache-miss callback, so they exist only for the duration of the
+  load. Text images are verified against the digest their own path claims —
+  a truncated image would otherwise boot as silently-wrong code.
+- **The substrate is one deployment-wide value** (`createProcessHost`'s mode,
+  `'facet'` or `'peer'`), never per-spawn. No program name, mode, or payload
+  size reaches the choice.
+
+What each substrate costs, measured on the production shape:
+
+| | spawn | memory | CPU | SQLite |
+|---|---|---|---|---|
+| facet | 8–16 ms | independent (~208 MiB each) | SHARED | own |
+| peer | 242–359 ms | independent | independent | own |
+
+Facet CPU is shared because facets are separate isolates inside one actor
+thread: awaiting I/O yields it completely, but a deliberate 9,956 ms CPU burn
+stalled a sibling for 9,966 ms. A peer pays roughly 20× the spawn cost to buy
+that back, and verifies its placement rather than assuming it — a module-scope
+UUID token is compared across the hop, up to 4 sibling names tried, because a
+peer that co-located shares the CPU it was chosen to escape.
+
+The substrates also differ in image delivery, stated in the
+`ProcessImageDelivery` contract rather than smoothed over: a facet shares its
+session's Durable Object, so the session's store is reachable by
+copy-on-write (`ctx.facets.clone`: 18–31 ms for a 45.73 MB corpus, 34–54 ms
+for 1 GB — flat, because nothing is copied) but also shares the session's
+~10 GiB storage budget. A peer brings its own budget and no reflink: clone is
+same-object-only and workerd exposes no `VACUUM INTO`, `ATTACH`, or
+`sqlite3_backup` across objects. And a clone hazard we measured rather than
+assumed: ANY unresolvable `src` — a typo, a name not created yet — silently
+EMPTIES the destination and reports success. `cloneFacetStorage` is the one
+way the fabric calls clone: it takes the caller's `populated(name)` probe and
+asserts it positively on the source before the clone and on the destination
+after, so a typo is refused before the platform call and a wiped destination
+is never reported as success. An emptied facet still shows a 4,096-byte
+database — one page — which is why the probe must find the caller's own data,
+not a non-zero size.
+
+## The image store
+
+`FacetImageStore` materializes generated boot images into a content-addressed
+store (`var/lib/nimbus/facet-images/<sha256>.js`) through a small
+`FacetImageBlobStore` port — the embedder owns the disk, the store owns the
+protocol:
+
+- **Root before the first byte.** The whole root set is registered
+  synchronously before any byte lands, so the sweep can never observe a
+  written-but-unclaimed image, however many turns the write spans.
+- **Sliced writes.** One transaction takes `FACET_IMAGE_WRITE_SLICE_BYTES`
+  (a whole number of VFS chunks under the 1 MiB transaction bound — a slice
+  ending mid-chunk forces a read-back, and an oversize write falls back to
+  copy-on-write, which is quadratic). A 22.9 MB map written in one turn took
+  the session down with it about 25% of the time; sliced and paced, it
+  doesn't.
+- **Size equality is completeness.** A write only ever grows the file from
+  offset zero, so an interrupted write leaves a strictly shorter file; the
+  reader verifies the digest before the loader sees the bytes.
+- **The sweep roots off the process table.** An image is live for exactly as
+  long as a process boots from it. No TTL, no eviction heuristic; after a
+  reset the table is empty and every orphan goes.
+
+## Binding shims for inner workers
+
+`NimbusLoaderRPC`, `NimbusLoadedWorker`, `NimbusLoadedEntrypoint`,
+`NimbusAssetsRPC`, `NimbusDurableObjectNamespace`, and `NimbusDOStub` give a
+dynamically-loaded inner Worker working `env` bindings. They exist because of
+three platform behaviors, each of which cost a debugging session:
+
+- **`WorkerStub` does not serialize**, so each hop a caller makes
+  (`load → getEntrypoint → fetch`) is its own `WorkerEntrypoint` class.
+- **Stubs are I/O objects bound to the request that minted them** ("Cannot
+  perform I/O on behalf of a different request"), so the shims store CODE,
+  never stubs, and re-resolve through `LOADER.get(id, cb)` in the current
+  context — workerd caches by id, so repeated loads are close to free. The
+  code map is a hard-capped LRU of 32 entries: `wrangler dev`'s
+  rebuild-on-save loop once grew it without bound to a 128 MiB isolate crash.
+- **An RPC stub's method is a wildcard property**: `method.call(ep, request)`
+  builds the pipelined path `method.call` and serializes `ep` as an argument,
+  which workerd refuses ("Entrypoints to dynamically-loaded workers cannot be
+  transferred"). Calls must be written `ep.method(request)`.
+
+Nesting is capped at depth 4 (`NIMBUS_INNER_LOADER_DEPTH` raises it) —
+Nimbus-in-Nimbus is fine, five levels is a runaway.
+
+## The platform, measured
+
+These tables are the part of this package I most wanted to publish. They are
+enforced by the code above where code can enforce them; the rest is here so
+the next person does not have to measure them again. All figures are from
+production workerd, June–August 2026.
+
+### Durable Object storage
+
+| Invariant | Evidence |
+|---|---|
+| `await put()` resolves BEFORE durability; `ctx.storage.sync()` is the barrier; the output gate holds the guarantee | a launch killed in its first chunks left NO journal row (staging, 2026-08-13) |
+| A reset destroys every write its turn had outstanding; an alarm write rolls back with it and the platform re-delivers the alarm to the replacement instance | the first turn after a reset is a recovery turn, for free |
+| SQLite value cap is 2 MB per ROW, key length included | single-value ceiling 2,199,981 B with a 12-char key; overflow throws clean, catchable `SQLITE_TOOBIG` |
+| One alarm per object; a second `setAlarm()` silently overwrites | why `ALARM_REASONS_KEY` is a map |
+| Input gates stay closed across `get`/`put` | set-if-absent is atomic per DO with no CAS loop |
+| A facet's own SQLite survives a fresh module scope | 7,141 rows / 45.7 MB intact across recycling — keep provenance in rows, never heap |
+| ~10 GiB storage budget shared by the DO root and every facet and clone under it, with no copy-on-write credit | N clones of X bytes cost X·(N+1); crossing RESETS the object rather than raising an error |
+
+### Lifecycle and CPU
+
+| Invariant | Evidence |
+|---|---|
+| No pending alarm ⇒ hibernation-eligible after ~10 s idle | why `dispatchAlarm` deletes the map when nothing remains |
+| One-turn CPU budget ~30 s; yielding inside an invocation buys nothing; only genuine re-entry (an alarm) resets it | killed with `exceededCpu` at 31.8 s and 32.5 s |
+| A long turn drops the object's WebSockets even when the work succeeds | the launch turn finished `outcome=ok` and the terminal died anyway |
+| The in-DO clock does not advance without I/O | 0 ms across 200,000 consecutive `Time.now` reads — pace in bytes, hand deadlines to the host |
+| Isolate generation increments on EVERY fresh isolate: cold start and hibernation wake, not only resets | `maybeBumpIsolateGen` adopts persisted truth first |
+| `pid <= generation base` ⇒ previous generation | THE reset predicate; `PID_GEN_STRIDE` = 1,000,000 |
+| `setTimeout`/`setInterval` prevent hibernation | one-shot self-nulling timers only |
+
+### Facets and dynamic workers
+
+| Invariant | Evidence |
+|---|---|
+| Facet memory independent, ~208–256 MiB each; facet CPU SHARED across siblings | 9,956 ms burn stalled a sibling 9,966 ms; awaited I/O costs siblings 0 ms |
+| 65,536 facets per DO LIFETIME; IDs append-only, never reclaimed; reusing a NAME costs no new ID | the slot book exists for this; `facetIdBudget` counts consumption durably and a failure at the wall names the budget |
+| Dynamic-worker module map hard ceiling 67,108,864 bytes, shared across every member | 62 MiB lands, 64 MiB refused; boot cost roughly linear in map bytes and not the bottleneck (40 MiB → 1.42 s across 6,553 modules); every assembly seam refuses an over-ceiling map listing the largest members by size, because the platform's refusal names none |
+| Request-time `WebAssembly.compile`/`instantiate` CSP-blocked; wasm rides the loader modules map as `{ wasm: ArrayBuffer }`, compiled at module load | RPC of a compiled `Module` refused by structured clone; inlined bytes OOMed the supervisor |
+| Module scope bans I/O; `new Function` succeeds at module scope and throws at request time | code reaches a facet through the module map or not at all |
+| The facet start callback fires at most once | re-running it would re-execute the user's program |
+| ~5–6 concurrent dynamic workers per DO; at most 4 concurrent Loader fetches per DO method; loader-cache entries are never released | `IN_DO_THRESHOLD` = 5 sits under the fetch cap; every `loader.get(id)` permanently consumes a slot — counted per DO by the loader ledger, and a cap refusal names the ids holding them |
+| `ctx.facets.clone` is same-object only, absent from `@cloudflare/workers-types` and the pinned workerd, present in production | 18–31 ms / 45.7 MB, 34–54 ms / 1 GB; an unresolvable `src` silently EMPTIES the destination and reports success — `cloneFacetStorage` enforces the both-ends validation |
+| A DO dies at ~200 MiB of live wasm linear memory; reserved and written pages die at the same ceiling | lazy growth buys nothing; bound guest memory by rewriting the memory section |
+| A wasm stack suspended (JSPI) in one request cannot resume in another | 3 in-context resumes took 6 ms; the first cross-context one hit a 30 s timeout |
+
+### RPC and stubs
+
+| Invariant | Evidence |
+|---|---|
+| workerd constructs a NEW `WorkerEntrypoint` instance per RPC call | instance fields are write-only; fold state through return values |
+| A stub minted in one invocation throws in another ("Cannot perform I/O on behalf of a different request") | store CODE, not stubs; re-resolve via `LOADER.get(id, cb)` — cached by id, ~free |
+| `WorkerStub` does not serialize | one chained `WorkerEntrypoint` proxy class per hop |
+| An RPC method is a wildcard property: `method.call(ep, r)` serializes `ep` as an argument and is refused | always `ep.method(r)` |
+| Entrypoints to dynamically-loaded workers cannot transfer across Workers | HTTP travels as parts with plain `ReadableStream` bodies, re-piped through an identity stream this isolate owns |
+| Structured-clone RPC cap 32 MiB | ship ≤ 28 MiB (`~6%` clone overhead); clone refusal is classified distinctly |
+| RPC resources need explicit `Symbol.dispose`, including on error paths | a timeout's reject closure otherwise roots a 28 MiB payload for the full timeout |
+| A binding minted BY AN ACTOR lives as long as the process; nothing holds a call open | why the facet's `SUPERVISOR` binding comes from the DO, not a stateless entrypoint |
+
+### WebSockets
+
+| Invariant | Evidence |
+|---|---|
+| Without `setWebSocketAutoResponse(ping/pong)`, every idle-tab ping wakes the actor | ~2,880 wakes/day per idle tab; the config survives hibernation |
+| A hibernatable WS owned by a DO cannot be written from a sibling `WorkerEntrypoint` isolate | sends happen in the DO's own context (relay pattern) |
+| A resident process never receives a WebSocket | route targets are `handleHttpRequest` only; every socket terminates on the session DO |
+
+### Sharing an isolate
+
+| Invariant | Evidence |
+|---|---|
+| The isolate heap ceiling is 128 MiB, and multiple DOs from one script can SHARE one isolate | resets observed below any single object's apparent usage |
+| `exceededMemory` and `exceededCpu` are both uncatchable inside the dying isolate, observable only across an RPC boundary | absence of the error is not evidence of its absence |
+| `process.memoryUsage()` returns 0 in DO context | any heap estimate is a lower bound; say so |
+
+## Relation to the other packages
+
+`@nimbus-sh/core` is the OS this machinery hosts — fabric depends on it for
+shared primitives (constants, RPC disposal, error classification) and core
+never imports fabric.
+[`@nimbus-sh/worker`](https://www.npmjs.com/package/@nimbus-sh/worker) is the
+canonical embedder: it supplies the seams above, the supervisor entrypoint,
+the session protocol, and everything user-facing. If you want the full hosted
+product shape, start from `npx create-nimbus-app`; if you are building your
+own thing on Durable Objects, this package and its doc comments are the part
+of Nimbus you can take without taking Nimbus.
+
+## License
+
+MIT.

package/dist/alarms.d.ts

@@ -0,0 +1,134 @@
+/**
+ * alarms.ts — Durable Object alarm multiplexing + isolate-generation
+ * machinery, persisted across hibernation.
+ *
+ * Workerd hibernates Durable Objects between requests to free memory. On
+ * wake, the new isolate must rebuild its in-memory state from SQL — but it
+ * also needs to know "is this the same lifecycle as before, or did workerd
+ * recycle me?" That distinction matters for recovery (warmJoin vs cold init)
+ * and is captured by the isolate generation, a counter persisted across
+ * hibernations.
+ *
+ * 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: `scheduleAlarm` arms one, and `dispatchAlarm`
+ * runs the embedder-supplied handler for every reason whose deadline has
+ * passed.
+ */
+/**
+ * The storage the alarm 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 AlarmStorage {
+    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 alarm coordination reads it. */
+export interface AlarmContext {
+    storage: AlarmStorage;
+}
+/**
+ * Multi-reason alarm 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 ALARM_REASONS_KEY = "w1_next_alarm_reasons";
+/**
+ * Storage key for the isolate-generation counter (cold-start +
+ * post-hibernation wake; one increment per fresh isolate).
+ *
+ * The VALUE is live production DO storage ('w9_isolate_gen') and must never
+ * change, same contract as {@link ALARM_REASONS_KEY}.
+ */
+export declare const ISOLATE_GEN_KEY = "w9_isolate_gen";
+/**
+ * The host instance carrying the per-instance alarm chain. The field lives on
+ * the embedder's DO instance so one chain serializes every alarm-map
+ * read-modify-write for that instance (see {@link scheduleAlarm}).
+ */
+export interface AlarmHost {
+    _alarmChain?: Promise<unknown>;
+}
+/** The host instance carrying the isolate-generation state. */
+export interface IsolateGenHost {
+    _isolateGen: number;
+    _isolateGenPersisted: boolean;
+}
+/**
+ * Schedule (or re-schedule) an alarm 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).
+ */
+export declare function scheduleAlarm(host: AlarmHost, ctx: AlarmContext, reason: string, whenMs: number): Promise<boolean>;
+/**
+ * What one alarm 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 AlarmHandlerResult = void | {
+    rearmAt: number;
+};
+/** The embedder's reasons, each with the handler that answers it. */
+export type AlarmHandlers = Record<string, (now: number) => AlarmHandlerResult | Promise<AlarmHandlerResult>>;
+/**
+ * Multi-reason alarm 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 scheduleAlarm call).
+ */
+export declare function dispatchAlarm(host: AlarmHost, ctx: AlarmContext, handlers: AlarmHandlers, onLegacyAlarm?: () => void): Promise<void>;
+/** Increment + persist the isolate-gen counter once per fresh isolate. */
+export declare function maybeBumpIsolateGen(host: IsolateGenHost, ctx: AlarmContext): Promise<void>;
+//# sourceMappingURL=alarms.d.ts.map

package/dist/alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarms.d.ts","sourceRoot":"","sources":["../src/alarms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;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;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAChC;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CA8BlB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAChC,MAAM,EACN,CAAC,GAAG,EAAE,MAAM,KAAK,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAClE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,MAAM,IAAI,GACzB,OAAO,CAAC,IAAI,CAAC,CASf;AAwDD,0EAA0E;AAC1E,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhG"}