@nimbus-sh/fabric 0.1.0 → 0.2.0

package/README.md

@@ -26,27 +26,50 @@ Where a specific date matters it is given.
 
 ## Importing it
 
+Your Worker must set `compatibility_flags: ["nodejs_compat"]`. The timer
+dispatcher imports `AsyncLocalStorage` from `node:async_hooks`, which workerd
+ships only under that flag. Without it the module fails to load, so the
+failure arrives at deploy time, not in production. The dispatcher needs
+async-local state because several Durable Objects from one script can share a
+V8 isolate, and a module-scoped variable would leak the dispatch context
+between them.
+
 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
+`@nimbus-sh/fabric/timers.js`, `@nimbus-sh/fabric/fenced-work.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:
+An embedder states its composition once, in its composition root:
 
 ```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);
 ```
 
+Both calls are first-write-wins.
+
+Before a release reaches the registry, consumers link it by packed tarball:
+`npm pack` here, a `file:` path there. One bun behavior to know when you do:
+bun pins a `file:` tarball by the integrity hash in its lockfile and keeps
+serving the extraction it already has, so repacking the tarball at the same
+path changes nothing at the consumer. After a repack, bump the version you
+pack or delete the tarball's lockfile entry; a plain `bun install` is not
+enough.
+
 ## One alarm, many reasons
 
 A Durable Object has ONE alarm, and a second `setAlarm()` silently overwrites
@@ -55,18 +78,18 @@ reason→deadline map in storage, with one dispatcher:
 
 ```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,8 +99,8 @@ 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
+`schedule` keeps the earliest deadline per reason and arms the real alarm
+at the minimum across all of them. `dispatch` 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
@@ -95,15 +118,12 @@ pid at or below the current generation's base was allocated by a previous
 incarnation.**
 
 ```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
   }
 }
 ```
@@ -124,13 +144,13 @@ 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';
+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),
@@ -159,7 +179,7 @@ Two details here cost us real incidents before they were mechanisms:
   went looking.
 
 Recovery applies the generation predicate (`pid <= generationBase()`), deletes
-each stale row, and re-drives once per record (`RESIDENT_LAUNCH_MAX_ATTEMPT` =
+each stale row, and re-drives once per record (`FENCED_WORK_MAX_ATTEMPT` =
 1) — a reset that recurs is not the transient kind.
 
 ## Pacing big work across turns
@@ -173,16 +193,17 @@ 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';
+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(),
 ```
@@ -190,22 +211,22 @@ await pacer.spend(bytesJustProcessed);   // suspends every LAUNCH_CHUNK_MAX_BYTE
 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"
+free, which makes `schedule(..., 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
+## Running programs: the isolate pool
 
-`LoaderPool` runs plain functions in warm dynamic-worker isolates over
+`IsolatePool` 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';
+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
@@ -236,14 +257,15 @@ 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
+`Fanout` 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
+coordinator through an `IsolatePool` 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
+Every fabric call into the loader lands on a per-DO ledger (`budgets.js`,
+which also owns the module-map ceiling and the facet-ID count): 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
@@ -256,9 +278,9 @@ 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:
+facet whose class comes from a dynamic worker. `processes(ctx, env).spawn` is
+the one way such a process comes into existence; `ProcessFabric` is the
+lifecycle around it:
 
 ```ts
 import { ProcessFabric, createProcessHost } from '@nimbus-sh/fabric';
@@ -341,7 +363,7 @@ for 1 GB — flat, because nothing is copied) but also shares the session's
 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
+EMPTIES the destination and reports success. `cloneStorage` 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
@@ -351,9 +373,9 @@ not a non-zero size.
 
 ## The image store
 
-`FacetImageStore` materializes generated boot images into a content-addressed
+`ImageStore` 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
+`ImageBlobStore` port — the embedder owns the disk, the store owns the
 protocol:
 
 - **Root before the first byte.** The whole root set is registered
@@ -402,6 +424,12 @@ 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.
 
+The tables are the short form. [PLATFORM.md](PLATFORM.md) is the full
+catalog: the same invariants merged with a sibling project's independent
+measurements, every entry graded by evidence (probe / source / production /
+documented), dated, and marked for whether this library enforces it or you
+handle it yourself.
+
 ### Durable Object storage
 
 | Invariant | Evidence |
@@ -409,7 +437,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 +446,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 +465,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 +488,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
 
@@ -472,9 +500,10 @@ production workerd, June–August 2026.
 
 ## 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/core` is the OS this machinery hosts; core never imports fabric.
+[`@nimbus-sh/platform`](https://www.npmjs.com/package/@nimbus-sh/platform) is
+the zero-dependency leaf under both: the measured 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

package/dist/bindings.js

@@ -24,10 +24,10 @@
  */
 import { WorkerEntrypoint } from 'cloudflare:workers';
 import { z } from 'zod/v4';
-import { disposeRpcResource, useRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { supervisorEntrypoint, supervisorEntrypointName } from './ctx-exports.js';
-import { requireStagedBootAssembler } from './process-fabric.js';
-import { assertModuleMapWithinCodeLimit } from './workerd-facet-host.js';
+import { disposeRpcResource, useRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { supervisorEntrypoint, supervisorEntrypointName } from './composition.js';
+import { stagedBootAssembler } from './composition.js';
+import { assertModuleMapWithinCodeLimit } from './budgets.js';
 /**
  * `ctx.exports` — workerd's loopback bag, which the installed
  * @cloudflare/workers-types does not put on `ExecutionContext`. Probed rather
@@ -448,7 +448,7 @@ export class NimbusLoadedEntrypoint extends WorkerEntrypoint {
             // alive.
             const stage = props.stage;
             outerStub = outerLoader.get(props.key, async () => {
-                const assembled = await requireStagedBootAssembler()(this.env, stage);
+                const assembled = await stagedBootAssembler()(this.env, stage);
                 assertModuleMapWithinCodeLimit(assembled.modules ?? {});
                 const supervisorBinding = await this._supervisorBinding(props);
                 if (!supervisorBinding)

package/dist/budgets.d.ts

@@ -0,0 +1,132 @@
+/**
+ * budgets.ts — per-DO accounting for the platform budgets the fabric spends:
+ * the Worker Loader's two caps, the facet-ID lifetime budget, and the
+ * dynamic-worker module-map ceiling.
+ *
+ * Measured on production workerd: a Durable Object admits ~5–6 concurrent
+ * dynamic workers before the platform refuses with "Too many concurrent
+ * dynamic workers", one DO method can drive at most 4 concurrent Loader
+ * fetches, and loader-cache entries are never released — every DISTINCT
+ * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
+ * the object's lifetime. Nimbus stays under the caps by construction
+ * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
+ * were counted in prose. This ledger counts them at the fabric's loader call
+ * sites instead — the loader pool's slots, a resident process's keyed worker,
+ * a one-shot's load — so proximity is measurable and a cap failure can name
+ * the ids actually holding slots.
+ *
+ * Measurement only: no admission control. The caps are the platform's, they
+ * are approximate ("~5–6"), and a gate on an approximate number would refuse
+ * work the platform would have run.
+ *
+ * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
+ * caps are per Durable Object, and dynamic workers die with the isolate that
+ * loaded them, so a ledger that goes away with its host describes nothing
+ * that still exists.
+ */
+/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
+export declare function recordLoaderId(ctx: object, id: string): void;
+/**
+ * Count one call into a dynamic worker as a live Loader fetch; the returned
+ * function ends it (idempotently), from the caller's own `finally`.
+ *
+ * A begin/end pair rather than a wrapper on purpose, and the shape is
+ * load-bearing: wrapping the stub call in a ledger-owned async frame
+ * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
+ * Durable Object poisoned after every pooled dispatch — the next fabric
+ * activity hung the object or reset the instance outright (pid base jumped,
+ * every attached WebSocket dropped with no close frame), measured 7/7 on
+ * staging and gone 3/3 with the direct call restored. Same seam-quirk class
+ * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
+ * workers: an RPC stub call must stay a direct property call awaited by the
+ * frame that made it, so the ledger only brackets it.
+ */
+export declare function beginLoaderFetch(ctx: object): () => void;
+/** Snapshot for the diag surface. Pure read; no I/O. */
+export declare function loaderLedgerStats(ctx: object): {
+    idsEverGotten: string[];
+    liveFetches: number;
+    peakLiveFetches: number;
+};
+/**
+ * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * failure; hand every other error back untouched. The platform's message
+ * says only that the cap was hit — which ids hold the slots, and that a
+ * keyed id can never give one back, is what the operator needs to know to
+ * shrink anything.
+ */
+export declare function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error;
+/**
+ * Total bytes a dynamic Worker's module map may carry, across every member of
+ * it. A hard platform limit, not a policy knob: 62 MiB lands and 64 MiB is
+ * refused with "Dynamic Worker code size (N bytes) exceeds the maximum allowed
+ * size of 67108864 bytes", confirmed at five sizes with two trials each. The
+ * budget is shared, so a ruby process is already 34.3 MiB down before its disk
+ * is counted.
+ */
+export declare const DYNAMIC_WORKER_CODE_LIMIT_BYTES = 67108864;
+/**
+ * Refuse a module map over {@link DYNAMIC_WORKER_CODE_LIMIT_BYTES}, naming
+ * the largest members. The platform's own refusal reports one number for a
+ * budget shared across every member of the map, which tells the operator
+ * nothing about WHAT to shrink — so every fabric seam that assembles a map
+ * runs this before the loader sees it.
+ *
+ * Costed to its two paths. Under the ceiling: one length read per member —
+ * UTF-16 code units for text, which equal UTF-8 bytes for the ASCII module
+ * text the generators emit and undercount otherwise; the platform's own
+ * refusal still backstops the exotic case, because this check exists to name
+ * members, not to be the ceiling. Over it: exact UTF-8 sizes, computed only
+ * then, sorted so the biggest lever is first.
+ */
+export declare function assertModuleMapWithinCodeLimit(modules: Record<string, unknown>): void;
+/**
+ * Facet IDs a Durable Object is granted over its LIFETIME. Append-only and
+ * never reclaimed, so crossing it is unrecoverable for the object — which is
+ * why the ledger below counts consumption durably instead of leaving the
+ * bound as prose the slot book merely respects.
+ */
+export declare const FACET_ID_LIFETIME_BUDGET = 65536;
+/** Where the ledger persists the count of facet names ever minted. */
+export declare const FACET_NAME_HIGH_WATER_KEY = "fabric_facet_name_high_water";
+/** The slice of storage the facet-name ledger persists through. */
+interface FacetNameLedgerStorage {
+    storage: {
+        get(key: string): Promise<unknown> | unknown;
+        put(key: string, value: unknown): Promise<void>;
+    };
+}
+/**
+ * Advance the durable ledger to this incarnation's name count, if it is a new
+ * lifetime high. Chained behind adoption so the comparison is always against
+ * the real persisted value; a failed write leaves the old link's count and the
+ * next mint tries again — the ledger may transiently undercount, never over.
+ */
+export declare function recordFacetNameMinted(ctx: FacetNameLedgerStorage, count: number): void;
+/** The best count available without awaiting storage: minted or adopted. */
+export declare function facetNameCount(ctx: FacetNameLedgerStorage): number;
+/** The count with adoption awaited, for a first failure on a fresh boot. */
+export declare function facetNameCountDurable(ctx: FacetNameLedgerStorage): Promise<number>;
+/**
+ * The lifetime facet-ID ledger: how many facet names this fabric has ever
+ * minted on the Durable Object, against the 65,536 the platform will ever
+ * grant it. `consumed` only ever counts FIRST uses — a reused name, in this
+ * incarnation or any earlier one, cost no new ID, which is the slot book's
+ * whole reason to exist. Surfaced so an operator can see proximity to a wall
+ * whose crossing is unrecoverable, instead of discovering it from the
+ * platform's opaque failure.
+ */
+export declare function facetIdBudget(ctx: FacetNameLedgerStorage): Promise<{
+    consumed: number;
+    budget: number;
+}>;
+/**
+ * Name the facet-ID budget on a creation failure at the wall; below it, hand
+ * the error back untouched. Exhaustion is the one failure here the platform
+ * reports opaquely AND that no teardown, retry or reset can undo, so the
+ * ledger — the only witness to the real cause — does the naming. Not a
+ * threshold: the comparison is against the budget itself.
+ */
+export declare function withFacetBudgetNamed(consumed: number, error: unknown): unknown;
+export {};
+//# sourceMappingURL=budgets.d.ts.map

package/dist/budgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgets.d.ts","sourceRoot":"","sources":["../src/budgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAwBH,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,IAAI,CAUxD;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC9C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,CAOA;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAW7E;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,WAAa,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAoBrF;AAuBD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,iCAAiC,CAAC;AAExE,mEAAmE;AACnE,UAAU,sBAAsB;IAC9B,OAAO,EAAE;QACP,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;QAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACjD,CAAC;CACH;AAqCD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAatF;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,EAAE,sBAAsB,GAAG,MAAM,CAGlE;AAED,4EAA4E;AAC5E,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxF;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAK/C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAU9E"}