@nimbus-sh/fabric 0.1.0 → 0.3.0

package/README.md

@@ -4,69 +4,74 @@
 > 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:
+Run long-lived programs on Cloudflare Durable Objects.
+
+A Durable Object gives you one alarm, one 128 MiB isolate, a 30-second CPU
+turn, and storage that can reset under you. This package turns those into
+things you can build on: many timers on the one alarm, work that survives a
+reset, CPU work that spans turns, and real processes in their own isolates.
+
+Use it if you host something that outlives a request. A dev server, a build,
+an agent, a terminal session.
+
+## Install
+
+```bash
+npm install @nimbus-sh/fabric
+```
+
+## Requirements
+
+Set `compatibility_flags: ["nodejs_compat"]` in your Worker. The timer
+dispatcher needs `AsyncLocalStorage`, which workerd ships only under that
+flag. Without it the module fails to load at deploy time.
+
+Import the root inside a Worker. Outside workerd, import subpaths such as
+`@nimbus-sh/fabric/timers.js`, which are typed against plain objects and run
+in bun or node.
+
+## Setup
+
+Declare your composition once, in your Worker's entry module.
 
 ```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));
+import { composeFabric, adoptCtxExports } from '@nimbus-sh/fabric';
+
+// Module scope of the Worker entry, once per isolate:
+composeFabric({
+  // The name of your supervisor WorkerEntrypoint export. The fabric mints one
+  // binding per hosted program from it (env.SUPERVISOR inside the facet).
+  supervisorEntrypoint: 'MySupervisorRPC',
+  // Only if you use 'staged' boot specs; 'code' boots need no assembler.
+  stagedBootAssembler: async (env, stage) => assembleLoaderConfig(env, stage),
+});
+
+// ctx.exports is runtime state, not composition. Capture it where the
+// platform hands it over — the first fetch, or the DO constructor:
+adoptCtxExports(ctx.exports);
 ```
 
-## One alarm, many reasons
+Both calls take the first value they are given.
 
-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:
+## Timers
+
+A Durable Object has one alarm, and a second `setAlarm()` overwrites the
+first. Route every timer through one dispatcher instead.
 
 ```ts
 import { DurableObject } from 'cloudflare:workers';
-import { scheduleAlarm, dispatchAlarm } from '@nimbus-sh/fabric';
+import { timers } from '@nimbus-sh/fabric';
 
 export class MySession extends DurableObject {
-  _alarmChain?: Promise<unknown>;   // serializes the map's read-modify-write
+  _timerChain?: 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);
+    await timers(this, this.ctx).schedule('janitor', Date.now() + 60_000);
     return new Response('ok');
   }
 
   async alarm(): Promise<void> {
-    await dispatchAlarm(this, this.ctx, {
+    await timers(this, this.ctx).dispatch({
       janitor: async (now) => {
         await this.cleanUp();
         return { rearmAt: now + 60_000 };   // re-arm through the return value
@@ -76,61 +81,49 @@ export class MySession extends DurableObject {
 }
 ```
 
-`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.
+`schedule` stores a deadline per reason and arms the alarm at the earliest
+one. `dispatch` runs the reasons that are due, ignores reasons it does not
+know, and stops re-arming when none are left, which lets the object
+hibernate. A handler re-arms itself by returning `{ rearmAt }`.
 
-## Knowing which incarnation you are
+## Generations and reset detection
 
-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.**
+Workerd hands you a fresh isolate on cold starts, hibernation wakes, and
+resets. The generation counter tells you which incarnation you are in, and
+process IDs derive from it.
 
 ```ts
-import { maybeBumpIsolateGen } from '@nimbus-sh/fabric';
+import { adoptGeneration, generation } 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
+    await adoptGeneration(this.ctx);   // idempotent per instance
+    // generation(this.ctx) 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.
+This gives you one reliable test for stale state: **an ID at or below the
+current generation's base came from a previous incarnation.**
 
-## The launch journal: surviving resets
+Adopt the persisted value before bumping it. `await put()` returning is not
+durability, so a bump that has not landed can be re-issued to the next boot,
+and two instances would share a generation.
 
-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:
+## Fenced work
+
+A reset destroys whatever the current turn had in flight, including a
+half-built process. Journal the work first, and a later instance can finish
+it.
 
 ```ts
-import { ResidentLaunchJournal, type ResidentLaunchRecord } from '@nimbus-sh/fabric';
+import { FencedWork, type FencedWorkRecord } from '@nimbus-sh/fabric';
 
-interface MyLaunch extends ResidentLaunchRecord {
+interface MyLaunch extends FencedWorkRecord {
   argv: string[];   // whatever your redrive needs; the journal never reads it
 }
 
-const journal = new ResidentLaunchJournal<MyLaunch>(this.ctx.storage, {
+const journal = new FencedWork<MyLaunch>(this.ctx.storage, {
   generationBase: () => this.pidBase,
   waitUntil: (p) => this.ctx.waitUntil(p),
   redrive: (record, attempt) => this.launch(record.argv, attempt),
@@ -144,68 +137,47 @@ await journal.release(pid);
 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**:
+Write the row before the work starts and release it when the process ends,
+not when the launch ends. Resets usually arrive after a launch settles, so a
+launch-scoped row is already gone when recovery looks for it.
+
+The journal writes through `ctx.storage.sync()`, because `await put()`
+resolves before the write is durable. Recovery re-drives each stale row once.
+
+## Turn pacing
+
+One turn gets about 30 seconds of CPU. Yielding inside a turn does not help,
+because CPU accrues to the invocation. Only re-entering the object resets the
+budget, and a long turn also blocks the actor's thread and drops WebSockets.
 
 ```ts
-import { LaunchPacer, LaunchTurnPump, scheduleAlarm } from '@nimbus-sh/fabric';
+import { TurnBudget, PacedWork, onColdStart, timers } from '@nimbus-sh/fabric';
 
-const pump = new LaunchTurnPump({
-  requestTurn: () => { void scheduleAlarm(this, this.ctx, 'launch-turn', Date.now()); },
-  recover: () => journal.recoverInterrupted(),
+const pump = new PacedWork(this.ctx, {
+  requestTurn: () => { void timers(this, this.ctx).schedule('launch-turn', Date.now()); },
 });
-const pacer = new LaunchPacer(pump);
+// Deferred reconciliation rides the first pump, off the init gate:
+onColdStart(this.ctx, () => journal.recoverInterrupted());
+const budget = new TurnBudget(pump);
 
 // Inside the launch, after each unit of work:
-await pacer.spend(bytesJustProcessed);   // suspends every LAUNCH_CHUNK_MAX_BYTES (2 MB)
+await budget.spend(bytesJustProcessed);   // suspends every TURN_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.
+Account in bytes, not milliseconds: the in-DO clock does not advance without
+I/O. `spend()` suspends every 2 MB and resumes on a fresh turn. Scheduling a
+past deadline re-enters the object immediately.
 
-## Running programs: the loader pool
+## Isolate 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.
+Run plain functions in warm dynamic-worker isolates.
 
 ```ts
-import { LoaderPool } from '@nimbus-sh/fabric';
+import { IsolatePool } from '@nimbus-sh/fabric';
 
-const pool = new LoaderPool(env, this.ctx, {
+const pool = new IsolatePool(env, this.ctx, {
   concurrency: 4,
   tag: 'checksum',
   omitSupervisor: true,   // this pool needs no callback into the DO
@@ -220,45 +192,32 @@ try {
 }
 ```
 
-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:
+Functions are serialized with `fn.toString()`, so they must be
+self-contained: no captured variables, no `this`. Bindings arrive as the last
+parameter. Slots are stable, so a batch of 67 tasks reuses 4 warm isolates
+instead of paying 67 cold starts.
+
+Ship wasm through the loader's modules map as `{ wasm: ArrayBuffer }`. It is
+the only path that works. Request-time `WebAssembly.compile` is blocked by
+CSP, structured clone refuses a compiled `Module`, and inlining bytes into
+the source exhausts the supervisor's memory.
+
+Warm isolates are scoped to one session. A pool may opt into
+`cacheScope: 'global'` only if it takes no supervisor binding and keeps no
+user state.
+
+`Fanout` handles wider batches. One DO method can drive at most 4 concurrent
+loader fetches, so batches under 5 run in the coordinator and larger ones
+shard across up to 32 sibling objects, 4 at a time.
+
+Each keyed `loader.get(id)` permanently holds one of roughly 5–6
+dynamic-worker slots. `loaderLedgerStats(ctx)` reports what you have
+consumed, and a cap refusal names the IDs holding slots.
+
+## Process fabric
+
+A resident process is a Durable Object facet running a class from a dynamic
+worker.
 
 ```ts
 import { ProcessFabric, createProcessHost } from '@nimbus-sh/fabric';
@@ -283,124 +242,81 @@ 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:
+The worker exports a Durable Object class named `NimbusProcess` with
+`startProcess(args)` and `handleHttpRequest(request)`. `startProcess`
+declares one of two contracts. Use `'lifetime'` when the call should stay
+open for the process's life, as an attached terminal does. Use `'boot'` when
+it should return once the process is up and leave the facet resident, as a
+server does.
+
+**Facet names come from a free list.** A Durable Object allows 65,536 facets
+over its lifetime, and IDs are never reclaimed, so the limit counts facets
+ever created. Reusing a name costs no new ID. `facetIdBudget(ctx)` reports
+`{ consumed, budget }`.
+
+**Large boot members travel as VFS paths.** A structured-clone RPC value caps
+at 32 MiB. Use `vfsWasmModules` and `vfsTextModules`; the host reads the
+bytes during the load and verifies each image against the digest its path
+claims.
+
+**The substrate is one deployment-wide setting**, `'facet'` or `'peer'`,
+never a per-spawn choice.
 
 | | spawn | memory | CPU | SQLite |
 |---|---|---|---|---|
-| facet | 8–16 ms | independent (~208 MiB each) | SHARED | own |
+| 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
+Facets are separate isolates in one actor thread, so they scale memory but
+not CPU. Awaiting I/O yields the thread; a 9,956 ms CPU burn stalled a
+sibling for 9,966 ms. A peer costs about 20× the spawn time and buys real CPU
+isolation, and it verifies it did not co-locate.
+
+A facet shares its session's object, so it can copy the session's store by
+reflink (`ctx.facets.clone`, 18–31 ms for 45.73 MB, 34–54 ms for 1 GB) and
+shares the session's ~10 GiB budget. A peer brings its own storage and cannot
+reflink.
+
+Call clone through `cloneStorage`. An unresolvable `src` empties the
+destination and reports success, so the wrapper checks the source before the
+call and the destination after. An emptied facet still shows a 4,096-byte
+database, so check for your own data rather than a non-zero size.
+
+## Image store
+
+`ImageStore` writes generated boot images into a content-addressed store at
+`var/lib/nimbus/facet-images/<sha256>.js`, through an `ImageBlobStore` port
+you implement.
+
+It registers the whole root set before writing any byte, so a sweep never
+sees an unclaimed image. Writes are sliced to stay inside the 1 MiB
+transaction bound; a 22.9 MB map written in one turn reset the session about
+a quarter of the time. Because a write only grows the file from offset zero,
+matching size means a complete write, and the reader verifies the digest
+before the loader sees the bytes. Images stay live while a process boots from
+them, rooted in the process table, with no TTL.
+
+## Binding shims
 
 `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.
+dynamically-loaded inner Worker working `env` bindings.
+
+Three platform rules shape them. A `WorkerStub` does not serialize, so each
+hop is its own `WorkerEntrypoint` class. A stub belongs to the request that
+minted it, so the shims store code rather than stubs and re-resolve through
+`LOADER.get(id, cb)`; workerd caches by ID, and the code map is capped at 32
+entries. An RPC method is a wildcard property, so call `ep.method(request)`
+and never `method.call(ep, request)`, which workerd refuses.
+
+Nesting is capped at depth 4. Raise it with `NIMBUS_INNER_LOADER_DEPTH`.
+
+## Measured platform limits
+
+Figures below come from production workerd, June to August 2026. The code
+above enforces them where it can. [PLATFORM.md](PLATFORM.md) is the full
+catalog: every entry dated, graded by evidence, and marked as enforced here
+or left to you.
 
 ### Durable Object storage
 
@@ -409,7 +325,7 @@ production workerd, June–August 2026.
 | `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 |
+| One alarm per object; a second `setAlarm()` silently overwrites | why `TIMER_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 |
@@ -418,11 +334,11 @@ production workerd, June–August 2026.
 
 | Invariant | Evidence |
 |---|---|
-| No pending alarm ⇒ hibernation-eligible after ~10 s idle | why `dispatchAlarm` deletes the map when nothing remains |
+| No pending alarm ⇒ hibernation-eligible after ~10 s idle | why `timers.dispatch` 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 |
+| Isolate generation increments on EVERY fresh isolate: cold start and hibernation wake, not only resets | `adoptGeneration` 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 |
 
@@ -437,7 +353,7 @@ production workerd, June–August 2026.
 | 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 |
+| `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 — `cloneStorage` 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 |
 
@@ -460,7 +376,7 @@ production workerd, June–August 2026.
 |---|---|
 | 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 |
+| A WebSocket upgrade cannot ride the RPC hop a resident's HTTP takes | a 101 owns a live socket and RPC reconstructs values rather than handing sockets over; an upgrade takes the separate fetch-semantic entrypoint and stays on `fetch` for every hop (a facet is fetched directly; a peer fetches its own facet), and a target without that entrypoint answers 501 |
 
 ### Sharing an isolate
 
@@ -470,17 +386,16 @@ production workerd, June–August 2026.
 | `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
+## Related 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/core`](https://www.npmjs.com/package/@nimbus-sh/core) is the
+backend-agnostic OS: filesystem, shell, process contracts.
+[`@nimbus-sh/platform`](https://www.npmjs.com/package/@nimbus-sh/platform)
+holds the limits tables, the error taxonomy, RPC disposal, and the supervisor
+budget machinery.
 [`@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.
+reference embedder, with the supervisor entrypoint and the session protocol.
+For the full hosted product, start from `npx create-nimbus-app`.
 
 ## License