@nimbus-sh/fabric 0.7.1 → 0.9.0

package/src/budgets.ts

@@ -1,39 +1,46 @@
 /**
  * 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.
+ * the Durable Object's Dynamic Worker concurrency limit, 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.
+ * The Dynamic Worker model is Cloudflare's documented one
+ * ({@link DO_DYNAMIC_WORKER_LIMIT}): a Durable Object may have a fixed number
+ * of DISTINCT Dynamic Workers with in-flight requests at once, shared across
+ * every concurrent request to that object (one I/O context), and any number
+ * of in-flight requests to the same Dynamic Worker count as one. Only
+ * in-flight requests count: a loader id with nothing in flight holds nothing.
  *
- * 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.
+ * The ledger counts, per hosting actor, the distinct workers that are in
+ * flight right now, keyed by loader id (a fresh key per unkeyed `load`), plus
+ * the width fan-outs have claimed and not yet released. A fan-out spends only
+ * the {@link dynamicWorkerHeadroom} that leaves, so work a Durable Object
+ * already has in flight — a resident process, the esbuild facet, a git
+ * network op, another fan-out — keeps its slots.
  *
  * 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
+ * limit is 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.
  */
 
 import { classifyError } from '@nimbus-sh/platform/oom-classify.js';
+import { hostWasmIdentity } from './host-wasm.js';
+
+/**
+ * Distinct Dynamic Workers one Durable Object may have with in-flight
+ * requests at once, shared across all concurrent requests to that object;
+ * multiple in-flight requests to one Dynamic Worker count once.
+ * https://developers.cloudflare.com/changelog/post/2026-08-28-durable-objects-dynamic-workers-limit/
+ */
+export const DO_DYNAMIC_WORKER_LIMIT = 10;
 
 interface LoaderLedger {
-  /** Distinct loader ids ever gotten — each one a permanently consumed slot. */
-  ids: Set<string>;
-  /** In-flight calls into dynamic workers, right now. */
-  liveFetches: number;
-  /** The most that were ever in flight at once. */
-  peakLiveFetches: number;
+  /** Loader id → open holds on it. A key is present only while held. */
+  inFlight: Map<string, number>;
+  /** Width claimed by fan-outs that have not released it. */
+  claimed: number;
+  /** The most distinct workers (holds plus claims) ever counted at once. */
+  peak: number;
 }
 
 const ledgers = new WeakMap<object, LoaderLedger>();
@@ -41,20 +48,21 @@ const ledgers = new WeakMap<object, LoaderLedger>();
 function ledger(ctx: object): LoaderLedger {
   let entry = ledgers.get(ctx);
   if (!entry) {
-    entry = { ids: new Set(), liveFetches: 0, peakLiveFetches: 0 };
+    entry = { inFlight: new Map(), claimed: 0, peak: 0 };
     ledgers.set(ctx, entry);
   }
   return entry;
 }
 
-/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
-export function recordLoaderId(ctx: object, id: string): void {
-  ledger(ctx).ids.add(id);
+function inUse(entry: LoaderLedger): number {
+  return entry.inFlight.size + entry.claimed;
 }
 
 /**
- * Count one call into a dynamic worker as a live Loader fetch; the returned
- * function ends it (idempotently), from the caller's own `finally`.
+ * Hold the Dynamic Worker `workerKey` in flight on this actor's ledger; the
+ * returned function ends the hold (idempotently), from the caller's own
+ * `finally`. Holds on one key nest: the worker counts once until the last
+ * one ends, as the platform counts it.
  *
  * 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
@@ -67,48 +75,82 @@ export function recordLoaderId(ctx: object, id: string): void {
  * 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 function beginLoaderFetch(ctx: object): () => void {
+export function beginLoaderFetch(ctx: object, workerKey: string): () => void {
   const entry = ledger(ctx);
-  entry.liveFetches++;
-  entry.peakLiveFetches = Math.max(entry.peakLiveFetches, entry.liveFetches);
+  entry.inFlight.set(workerKey, (entry.inFlight.get(workerKey) ?? 0) + 1);
+  entry.peak = Math.max(entry.peak, inUse(entry));
   let ended = false;
   return () => {
     if (ended) return;
     ended = true;
-    entry.liveFetches--;
+    const open = (entry.inFlight.get(workerKey) ?? 1) - 1;
+    if (open > 0) entry.inFlight.set(workerKey, open);
+    else entry.inFlight.delete(workerKey);
+  };
+}
+
+/**
+ * Distinct Dynamic Workers this actor may still put in flight: the limit
+ * less what is held and claimed right now. Never negative.
+ */
+export function dynamicWorkerHeadroom(ctx: object): number {
+  return Math.max(0, DO_DYNAMIC_WORKER_LIMIT - inUse(ledger(ctx)));
+}
+
+/**
+ * Claim `width` distinct Dynamic Workers for one fan-out, or null when the
+ * headroom cannot hold it. The claim counts until `release` (idempotent), so
+ * a second fan-out sizing itself meanwhile sees it; the claimant's own
+ * dispatches are held as well while they run, which only ever over-counts
+ * toward sending that second fan-out elsewhere.
+ */
+export function claimDynamicWorkers(ctx: object, width: number): { release(): void } | null {
+  const entry = ledger(ctx);
+  if (width < 1 || width > DO_DYNAMIC_WORKER_LIMIT - inUse(entry)) return null;
+  entry.claimed += width;
+  entry.peak = Math.max(entry.peak, inUse(entry));
+  let released = false;
+  return {
+    release() {
+      if (released) return;
+      released = true;
+      entry.claimed -= width;
+    },
   };
 }
 
 /** Snapshot for the diag surface. Pure read; no I/O. */
 export function loaderLedgerStats(ctx: object): {
-  idsEverGotten: string[];
-  liveFetches: number;
-  peakLiveFetches: number;
+  limit: number;
+  inFlightWorkers: string[];
+  claimed: number;
+  headroom: number;
+  peak: number;
 } {
   const entry = ledger(ctx);
   return {
-    idsEverGotten: [...entry.ids],
-    liveFetches: entry.liveFetches,
-    peakLiveFetches: entry.peakLiveFetches,
+    limit: DO_DYNAMIC_WORKER_LIMIT,
+    inFlightWorkers: [...entry.inFlight.keys()],
+    claimed: entry.claimed,
+    headroom: dynamicWorkerHeadroom(ctx),
+    peak: entry.peak,
   };
 }
 
 /**
- * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * Name the per-DO accounting on a "Dynamic worker concurrency limit exceeded"
  * 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.
+ * says only that the limit was hit — which workers were in flight, and what
+ * fan-outs had claimed, is what the operator needs to know to shrink anything.
  */
 export function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error {
   if (classifyError(error) !== 'dynamic_worker_cap') return error;
   const entry = ledger(ctx);
   const platform = error instanceof Error ? error.message : String(error);
   return new Error(
-    `${platform} — this Durable Object has ${entry.ids.size} loader id(s) permanently `
-      + `holding dynamic-worker slots (a loader.get id is never released): `
-      + `${[...entry.ids].join(', ') || '(none recorded)'}; live Loader fetches ${entry.liveFetches}, `
-      + `peak ${entry.peakLiveFetches}`,
+    `${platform} — this Durable Object had ${entry.inFlight.size} distinct dynamic worker(s) in flight `
+      + `(${[...entry.inFlight.keys()].join(', ') || 'none recorded'}) and ${entry.claimed} claimed by fan-outs, `
+      + `against a limit of ${DO_DYNAMIC_WORKER_LIMIT}; peak ${entry.peak}`,
     { cause: error },
   );
 }
@@ -163,18 +205,23 @@ export function assertModuleMapWithinCodeLimit(modules: Record<string, unknown>)
 
 /**
  * Bytes one module-map member carries, across the loader's content kinds
- * (plain string, `{ js | cjs | py | text }`, `{ wasm | data }`). With an
- * encoder, text is measured exactly; without one, by code-unit length.
+ * (plain string, `{ js | cjs | py | text }`, `{ wasm | data }`, a bare
+ * WebAssembly.Module). With an encoder, text is measured exactly; without
+ * one, by code-unit length. A compiled module counts the wire size its host
+ * described (host-wasm.ts); one nobody described counts nothing here and is
+ * left to the platform's own refusal, as the text undercount is.
  */
 function memberBytes(content: unknown, encoder: TextEncoder | null): number {
   const textBytes = (text: string): number =>
     encoder ? encoder.encode(text).byteLength : text.length;
   if (typeof content === 'string') return textBytes(content);
+  if (content instanceof WebAssembly.Module) return hostWasmIdentity(content)?.bytes ?? 0;
   if (content !== null && typeof content === 'object') {
     for (const value of Object.values(content)) {
       if (typeof value === 'string') return textBytes(value);
       if (value instanceof ArrayBuffer) return value.byteLength;
       if (ArrayBuffer.isView(value)) return value.byteLength;
+      if (value instanceof WebAssembly.Module) return hostWasmIdentity(value)?.bytes ?? 0;
     }
   }
   return 0;

package/src/connections.ts

@@ -3,7 +3,7 @@
  * state over the WebSocket attachment.
  *
  * Specified from Proteus's DeviceSocketHub (`cf-backend/src/user/device-hub.ts`)
- * and CLI rpc gate (`cf-backend/src/cli/rpc-gate.ts`), which split the
+ * and its original CLI rpc gate (`cf-backend/src/cli/rpc-gate.ts`), which split the
  * pattern into its two halves:
  *   - a TAG is the immutable-at-accept lookup key and authorization — it
  *     rides the hibernation state, which is why the rpc gate persists auth

package/src/do-calls.ts

@@ -3,12 +3,14 @@
  * the one property that decides whether a retry is safe.
  *
  * Both consumers asked for this. Proteus hand-wrote the retry
- * (`cf-backend/src/lib/do-rpc.ts`) with the rule its header states:
+ * (originally `cf-backend/src/lib/do-rpc.ts`) with the rule its header states:
  * "An operation that appends, sends, charges or mints is never wrapped: a
  * dropped call there may already have run, so a retry is a correctness bug
  * wearing resilience as a costume." agent-core has no retry machinery at all
  * and its backlog calls the gap "the most production-proven gap in the
  * corpus". Here the rule is a type: `idempotent` retries, `mutating` cannot.
+ * A mutation earns a retry only by carrying an identity its callee applies
+ * at most once; it is then `idempotent` by construction (see `mutating`).
  *
  * What the platform contract requires, and this keeps:
  *   - a FRESH stub per attempt. Cloudflare documents that many exceptions
@@ -20,6 +22,11 @@
  *     object is what overloaded it.
  *   - attempts and backoff are the consumer-proven bounds: 3 attempts total,
  *     full-jitter delays in [0, 2**attempt * 60ms).
+ *   - an `idempotent` call may also be HEDGED (`hedgeAfterMs`): an attempt
+ *     that has not answered by then is joined by the same call on a fresh
+ *     stub, both left running, the first success taken. Hedges count
+ *     against the attempts, and a callee that joins a repeat to the call it
+ *     is already serving makes one that did arrive cost nothing.
  *
  * The resolver MINTS a stub per call and the verb disposes each one it
  * minted — that ownership is what makes the fresh-stub retry real.
@@ -35,6 +42,7 @@
 
 import { classifyDoCall, isRetryableDoCall, type DoCallClass } from '@nimbus-sh/platform/oom-classify.js';
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { untraced, type SpanRecorder } from '@nimbus-sh/platform/tracing.js';
 
 /** Total attempts. Two retries is what a dropped connection or a deploy
  *  bounce needs; beyond that the object is not coming back inside this
@@ -47,20 +55,71 @@ export interface DoCallRetryPolicy {
   maxAttempts?: number;
   baseDelayMs?: number;
   /**
-   * Called once per retry, before its backoff delay, with the failure the
-   * retry is answering. The consumer's logging seam: Proteus's hand-rolled
-   * predecessor logged every retry so a flaky object is visible in Workers
-   * Logs rather than silently absorbed, and `operation` names it there.
+   * No repeat — retry or hedge — starts once this long has passed since the
+   * first attempt did; the failure in hand surfaces instead. A mutation made
+   * repeatable by an identity its callee dedupes needs it: the callee keeps
+   * what answers a repeat for a bounded time, so the caller's repeats must
+   * stop well inside it. Unbounded when absent.
+   */
+  retryWindowMs?: number;
+  /**
+   * Hedge an attempt that has not answered after this long: send the same
+   * call again on a fresh stub while the first stays in flight. The caller
+   * gets the first success; an answer after it is disposed and dropped. That
+   * is only harmless when a second delivery of the call changes nothing — a
+   * read — and cheap only when the callee joins a repeat to the call it is
+   * already serving. A hedge is an attempt: it counts against `maxAttempts`,
+   * and has its own deadline. Never hedged when absent.
+   *
+   * With attempts overlapping, a failure decides less. A retryable one is
+   * retried after its backoff while attempts remain, and `overloaded` stops
+   * every further repeat; either way the call keeps waiting on the attempts
+   * still in flight, and fails with the last failure only once none is. Any
+   * other failure is the callee's answer — the call ran — and is the call's
+   * at once.
+   */
+  hedgeAfterMs?: number;
+  /**
+   * Called once per retry, as it starts — after its backoff delay — with the
+   * failure the retry is answering. A retry a hedge made unnecessary, or
+   * that no attempt is left for, is never announced. The consumer's logging
+   * seam: Proteus's hand-rolled predecessor logged every retry so a flaky
+   * object is visible in Workers Logs rather than silently absorbed, and
+   * `operation` names it there. A callback that throws fails the call with
+   * its error.
    */
   onRetry?(info: DoCallRetryInfo): void;
+  /**
+   * Where the call's telemetry goes: its span's recorder. Each attempt lost
+   * to a transient or overloaded failure is recorded as an exception whose
+   * `code` is the failure's class, and once the call has settled it gets
+   * `do_call.attempts` (started), `do_call.hedges` (started by a hedge),
+   * `do_call.answered_by` (the attempt whose answer the call took, absent
+   * when none answered) and `do_call.outcome` ({@link DoCallOutcome}).
+   * Nothing recorded can change the call's answer. Records nothing when
+   * absent.
+   */
+  span?: SpanRecorder;
 }
 
+/**
+ * How an `idempotent` call ended: `answered` (an attempt succeeded),
+ * `callee_error` (the callee's own failure, which is an answer),
+ * `exhausted` (the last transient failure, no repeat left), `overloaded`
+ * (shed, nothing repeated after it), or `caller_error` (the resolver or
+ * `onRetry` threw).
+ */
+export type DoCallOutcome = 'answered' | 'callee_error' | 'exhausted' | 'overloaded' | 'caller_error';
+
 /** What one retry is answering: which call, which platform class, which
  *  attempt just failed out of how many. */
 export interface DoCallRetryInfo {
   operation: string;
   classification: DoCallClass;
-  /** The 1-based attempt that failed; the retry about to run is attempt+1. */
+  /**
+   * The 1-based number of the attempt that failed. Without hedging the retry
+   * is attempt+1; with it, other attempts may have started in between.
+   */
   attempt: number;
   maxAttempts: number;
   error: unknown;
@@ -102,11 +161,20 @@ export class DoCallError extends Error {
 
 /**
  * Call another Durable Object with an operation that is safe to repeat: a
- * read, or a converge-to-a-value write. Transient failures retry on a fresh
- * stub with full-jitter backoff; overloaded and permanent failures surface
- * unchanged, as does the last error at exhaustion.
+ * read, a converge-to-a-value write, or a mutation carrying an identity its
+ * callee applies at most once (see {@link mutating}). Transient failures
+ * retry on a fresh stub with full-jitter backoff; overloaded and permanent
+ * failures surface unchanged, as does the last error once no attempt may be
+ * repeated — attempts spent, or the policy's retry window closed. With
+ * `hedgeAfterMs`, an attempt still unanswered by then is joined by another
+ * on a fresh stub, and the first answer is taken: a success, or the
+ * callee's own error. A transient or overloaded failure then ends the call
+ * only once no attempt is left in flight.
+ *
+ * A failure of the resolver or of `onRetry` is the caller's own, and fails
+ * the call with it at once.
  */
-export async function idempotent<S, T>(
+export function idempotent<S, T>(
   operation: string,
   stub: DoStubResolver<S>,
   call: (stub: S) => Promise<T>,
@@ -114,23 +182,131 @@ export async function idempotent<S, T>(
 ): Promise<T> {
   const maxAttempts = policy.maxAttempts ?? MAX_ATTEMPTS;
   const baseDelayMs = policy.baseDelayMs ?? BASE_DELAY_MS;
-  for (let attempt = 1; ; attempt++) {
-    const minted = await stub();
-    try {
-      const result = await call(minted);
-      disposeRpcResource(minted);
-      return result;
-    } catch (error) {
-      // A stub that threw may be permanently broken; it is never reused.
-      disposeRpcResource(minted);
+  const { hedgeAfterMs, retryWindowMs, span = untraced } = policy;
+  const startedAt = Date.now();
+  // The executor form: fabric's library target predates Promise.withResolvers.
+  return new Promise<T>((resolve, reject) => {
+    const hedges = new Set<ReturnType<typeof setTimeout>>();
+    let started = 0;
+    // Attempts in flight, or backing off before their retry: while one is,
+    // a failure is not the call's answer.
+    let live = 0;
+    // An attempt was shed as overloaded: nothing is repeated after it.
+    let refused = false;
+    let settled = false;
+    // Attempts a hedge started rather than a retry or the first send.
+    let hedged = 0;
+
+    const settle = (outcome: DoCallOutcome, answeredBy: number | undefined, answer: () => void): void => {
+      if (settled) return;
+      settled = true;
+      for (const timer of hedges) clearTimeout(timer);
+      hedges.clear();
+      answer();
+      span.set({
+        'do_call.attempts': started,
+        'do_call.hedges': hedged,
+        'do_call.answered_by': answeredBy,
+        'do_call.outcome': outcome,
+      });
+    };
+    /** May another attempt start at `at`? */
+    const canRepeat = (at: number): boolean =>
+      !settled && !refused && started < maxAttempts
+      && (retryWindowMs === undefined || at - startedAt <= retryWindowMs);
+    /** `error` ended an attempt that will not be repeated: the call's answer, once nothing else is live. */
+    const exhausted = <E>(error: E): void => {
+      if (live === 0) settle(refused ? 'overloaded' : 'exhausted', undefined, () => reject(error));
+    };
+
+    /** A failed attempt, numbered: repeat it after its backoff, or let it stand. */
+    const failed = async <E>(number: number, error: E): Promise<void> => {
+      if (settled) return;
       const classification = classifyDoCall(error);
-      if (!isRetryableDoCall(classification) || attempt >= maxAttempts) throw error;
-      policy.onRetry?.({ operation, classification, attempt, maxAttempts, error });
-      await new Promise<void>((resolve) => {
-        setTimeout(resolve, Math.floor(Math.random() * 2 ** attempt * baseDelayMs));
+      if (!isRetryableDoCall(classification) && classification !== 'overloaded') {
+        // The call ran and its answer is this error — ENOENT is a read's answer as much as bytes are.
+        settle('callee_error', number, () => reject(error));
+        return;
+      }
+      // A lost attempt: the call's span says which, and why.
+      span.exception(error, classification, `attempt ${number} of ${maxAttempts}: `);
+      if (classification === 'overloaded') {
+        // A shed call is no answer: nothing more is sent, and an attempt
+        // still in flight may yet answer.
+        refused = true;
+        exhausted(error);
+        return;
+      }
+      const delayMs = Math.floor(Math.random() * 2 ** number * baseDelayMs);
+      if (!canRepeat(Date.now() + delayMs)) {
+        exhausted(error);
+        return;
+      }
+      live++;
+      await new Promise<void>((wake) => {
+        setTimeout(wake, delayMs);
       });
-    }
-  }
+      live--;
+      // A hedge may have taken the last attempt, or answered, meanwhile.
+      if (!canRepeat(Date.now())) {
+        exhausted(error);
+        return;
+      }
+      policy.onRetry?.({ operation, classification, attempt: number, maxAttempts, error });
+      attempt();
+    };
+
+    const run = async (): Promise<void> => {
+      const number = ++started;
+      live++;
+      const minted = await stub();
+      if (settled) {
+        live--;
+        disposeRpcResource(minted);
+        return;
+      }
+      const hedge = hedgeAfterMs === undefined ? undefined : setTimeout(() => {
+        if (hedge !== undefined) hedges.delete(hedge);
+        if (canRepeat(Date.now())) {
+          hedged++;
+          attempt();
+        }
+      }, hedgeAfterMs);
+      if (hedge !== undefined) hedges.add(hedge);
+      /** This attempt has its answer: it hedges no more, and its stub goes. */
+      const answered = (): void => {
+        if (hedge !== undefined) {
+          clearTimeout(hedge);
+          hedges.delete(hedge);
+        }
+        live--;
+        // A stub that threw may be permanently broken; none is ever reused.
+        disposeRpcResource(minted);
+      };
+      let result: T;
+      try {
+        result = await call(minted);
+      } catch (error) {
+        answered();
+        await failed(number, error);
+        return;
+      }
+      answered();
+      if (settled) {
+        // Another attempt answered first: this answer is dropped, so nothing of it is kept.
+        disposeRpcResource(result);
+        return;
+      }
+      settle('answered', number, () => resolve(result));
+    };
+
+    /** Start an attempt. Whatever it throws outside the call itself fails the call. */
+    const attempt = (): void => {
+      run().catch((error) => settle('caller_error', undefined, () => reject(error)));
+    };
+
+    attempt();
+  });
 }
 
 /**
@@ -138,6 +314,21 @@ export async function idempotent<S, T>(
  * or mints. NEVER retried — a dropped call may already have run. Failure
  * surfaces as a {@link DoCallError} carrying the classification, so the
  * caller can tell a refusal from an indeterminate drop.
+ *
+ * The rule is about the call as sent, not the operation's kind. A mutation
+ * the callee applies at most once per identity the call carries is
+ * repeatable by construction: a repeat of one that already ran is answered
+ * from the callee's record and applies nothing. Nimbus has two:
+ *   - delivered filesystem mutations (@nimbus-sh/core supervisor-delivery):
+ *     a delivery id plus the callee INSTANCE's incarnation. The record lives
+ *     in that instance's memory, and any other instance — or a callee that
+ *     predates delivery — refuses the call permanently rather than apply it
+ *     without one;
+ *   - appends: writer, module incarnation and operation sequence, recorded
+ *     durably until acknowledged.
+ * Such a call goes through {@link idempotent}, re-sending the same identity
+ * on every attempt, with a `retryWindowMs` inside the callee's retention of
+ * that record. Without such an identity, a mutation stays here.
  */
 export async function mutating<S, T>(
   operation: string,

package/src/facet-pool.ts

@@ -42,6 +42,8 @@
  * and the facet-id ledger here counts only the names this pool minted.
  */
 
+import { forgetFacetStorage } from '@nimbus-sh/core/runtime/storage-ledger.js';
+import type { SqlDatabase } from '@nimbus-sh/core/runtime/os-contracts.js';
 import {
   FACET_ID_LIFETIME_BUDGET,
   facetNameCount,
@@ -63,6 +65,8 @@ export interface FacetPoolContext {
   storage: {
     get(key: string): Promise<unknown> | unknown;
     put(key: string, value: unknown): Promise<void>;
+    /** The session's SQL, where the storage ledger (N18) records facet databases. */
+    sql?: SqlDatabase;
   };
 }
 
@@ -134,6 +138,7 @@ export class FacetPool {
       if (keepStorage) return;
       try {
         facets.delete(name);
+        if (this.ctx.storage.sql) forgetFacetStorage(this.ctx.storage.sql, name);
       } catch (e) {
         throw new Error(
           `fabric: facet '${name}' was evicted but its storage was not reclaimed — `