@nimbus-sh/core 0.1.0

package/dist/_shared/typescript-specifiers.js

@@ -0,0 +1,84 @@
+/**
+ * typescript-specifiers.ts — the one definition of how a module specifier
+ * reaches a TypeScript source, shared by the install-time prefetch resolver
+ * and the `require()` inside a running facet.
+ *
+ * TypeScript's `"moduleResolution": "NodeNext"` requires authors to write the
+ * OUTPUT extension in a specifier that names a TypeScript source:
+ *
+ *     // packages/cli/bin/cli.ts
+ *     import '../src/program.js';        // means ../src/program.ts
+ *
+ * That is not one project's quirk, it is what every modern TS project on
+ * NodeNext looks like. Real bun resolves it; node does not.
+ *
+ * SCOPE — this resolver serves node as well, so the rule is deliberately a
+ * FALLBACK rather than a reordering: these candidates are probed only after
+ * every candidate node itself would try has missed, and they only ever name a
+ * TypeScript source. The inputs whose resolution changes are therefore exactly
+ * the inputs that resolve to nothing today, where node's own answer is
+ * "Cannot find module". No module graph that resolves now resolves
+ * differently, so nothing about node's semantics moves — while the TypeScript
+ * projects Nimbus already transforms and runs become resolvable.
+ *
+ * The one bun behaviour deliberately NOT adopted is its probe ORDER. Bun tries
+ * `.tsx, .ts, .jsx, .js`, so for `./m` with both `m.ts` and `m.js` present bun
+ * answers `m.ts` and node answers `m.js`. Preferring the TypeScript file there
+ * would change a specifier that already resolves, which is the one thing this
+ * scoping promises not to do.
+ *
+ * Mapping measured against bun 1.3.1, not recalled:
+ *   ./m.js   → m.ts, m.tsx      (and m.js itself still wins when it exists)
+ *   ./m.mjs  → m.mts
+ *   ./m.cjs  → nothing; bun does not map it to m.cts
+ *   ./m      → m.ts, m.tsx
+ *
+ * `getTypescriptSpecifiersJS()` emits the same mapping for the facet shim.
+ * The two bodies are checked against each other mechanically —
+ * tests/unit/typescript-specifier-resolution.mjs evaluates the emitted one and
+ * compares it to this one over the whole table — because a "keep in sync"
+ * comment has never once caught a drift.
+ */
+/** Files that are already a TypeScript source, or can never name one. */
+const NON_MAPPING_EXTENSION = /\.(ts|tsx|mts|cts|json|node|cjs)$/;
+/**
+ * TypeScript sources a specifier may name once every path node itself would
+ * take has missed. Empty when the specifier cannot name one.
+ */
+export function typescriptFallbackCandidates(base) {
+    if (NON_MAPPING_EXTENSION.test(base))
+        return [];
+    if (base.endsWith('.mjs'))
+        return [base.slice(0, -4) + '.mts'];
+    if (base.endsWith('.js')) {
+        const stem = base.slice(0, -3);
+        return [stem + '.ts', stem + '.tsx'];
+    }
+    return [base + '.ts', base + '.tsx'];
+}
+/** Directory entry points, probed after node's `index.{js,cjs,mjs,json}`. */
+export const TYPESCRIPT_INDEX_CANDIDATES = ['/index.ts', '/index.tsx'];
+/**
+ * The same mapping as raw JS, for embedding in the facet shim.
+ *
+ * The regex and the index list are interpolated from the definitions above so
+ * only the four-branch body is written twice, and the equivalence of the two
+ * bodies is asserted over the whole table by the unit test rather than
+ * asserted by a comment.
+ */
+export function getTypescriptSpecifiersJS() {
+    return `
+// ── typescript-specifiers (mirrors src/_shared/typescript-specifiers.ts) ──
+const __NON_MAPPING_EXTENSION = ${NON_MAPPING_EXTENSION.toString()};
+const __TYPESCRIPT_INDEX_CANDIDATES = ${JSON.stringify([...TYPESCRIPT_INDEX_CANDIDATES])};
+function __typescriptFallbackCandidates(base) {
+  if (__NON_MAPPING_EXTENSION.test(base)) return [];
+  if (base.endsWith(".mjs")) return [base.slice(0, -4) + ".mts"];
+  if (base.endsWith(".js")) {
+    const stem = base.slice(0, -3);
+    return [stem + ".ts", stem + ".tsx"];
+  }
+  return [base + ".ts", base + ".tsx"];
+}
+`;
+}

package/dist/_shared/untrusted-request.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The trust boundary between Nimbus and code running inside a session.
+ *
+ * Everything a session serves — port previews (both the `<port>--<sid>` host
+ * form and the `/s/<sid>/port/<n>/` path form), the Vite preview, the wrangler
+ * worker preview — is UNTRUSTED: it is whatever the user (or an agent acting
+ * for them) installed and ran. Nimbus's own credentials must never cross into
+ * it, so requests are sanitized here, once, by every caller that hands a
+ * Request to user code.
+ *
+ * Platform cookies are matched by NAMESPACE, not by an enumerated list. An
+ * explicit list is drift-prone in the way that matters most: it silently fails
+ * open. It also cannot work across layers — `NIMBUS_TOKEN_COOKIE` lives in
+ * this package, `nimbus_agent_oauth` in the session layer, and embedder
+ * cookies like `__Host-nimbus_demo_auth` in the app, which this package must
+ * not import. A namespace rule covers all three and any cookie added later.
+ */
+/** True if `name` is a Nimbus/embedder platform cookie (never for user code). */
+export declare function isPlatformCookie(name: string): boolean;
+/**
+ * Strip Nimbus credentials and internal routing headers from `headers`,
+ * in place. Cookies the user's own app set are preserved — only the platform
+ * namespace is removed.
+ */
+export declare function sanitizeUntrustedHeaders(headers: Headers): void;
+/**
+ * Clone `request` with credentials stripped, for callers that hand a whole
+ * Request to user code. Returns the original when there is nothing to remove,
+ * so the common case allocates nothing. WebSocket upgrades are passed through
+ * untouched: reconstructing them drops the `webSocket` handshake, and the
+ * upgrade itself is already authenticated upstream.
+ */
+export declare function sanitizeUntrustedRequest(request: Request): Request;
+//# sourceMappingURL=untrusted-request.d.ts.map

package/dist/_shared/untrusted-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted-request.d.ts","sourceRoot":"","sources":["../../src/_shared/untrusted-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqB/D;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAalE"}

package/dist/_shared/untrusted-request.js

@@ -0,0 +1,74 @@
+/**
+ * The trust boundary between Nimbus and code running inside a session.
+ *
+ * Everything a session serves — port previews (both the `<port>--<sid>` host
+ * form and the `/s/<sid>/port/<n>/` path form), the Vite preview, the wrangler
+ * worker preview — is UNTRUSTED: it is whatever the user (or an agent acting
+ * for them) installed and ran. Nimbus's own credentials must never cross into
+ * it, so requests are sanitized here, once, by every caller that hands a
+ * Request to user code.
+ *
+ * Platform cookies are matched by NAMESPACE, not by an enumerated list. An
+ * explicit list is drift-prone in the way that matters most: it silently fails
+ * open. It also cannot work across layers — `NIMBUS_TOKEN_COOKIE` lives in
+ * this package, `nimbus_agent_oauth` in the session layer, and embedder
+ * cookies like `__Host-nimbus_demo_auth` in the app, which this package must
+ * not import. A namespace rule covers all three and any cookie added later.
+ */
+/** Cookie-name prefixes reserved for Nimbus and its embedders. */
+const PLATFORM_COOKIE_PREFIXES = ['nimbus_', '__Host-nimbus', '__Secure-nimbus'];
+/** True if `name` is a Nimbus/embedder platform cookie (never for user code). */
+export function isPlatformCookie(name) {
+    return PLATFORM_COOKIE_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/**
+ * Strip Nimbus credentials and internal routing headers from `headers`,
+ * in place. Cookies the user's own app set are preserved — only the platform
+ * namespace is removed.
+ */
+export function sanitizeUntrustedHeaders(headers) {
+    for (const name of [...headers.keys()]) {
+        if (name.toLowerCase().startsWith('x-nimbus-'))
+            headers.delete(name);
+    }
+    // Both carry credentials and neither is meaningful to a sandboxed server.
+    headers.delete('Authorization');
+    headers.delete('Proxy-Authorization');
+    const cookie = headers.get('Cookie');
+    if (!cookie)
+        return;
+    const remaining = cookie
+        .split(';')
+        .map((entry) => entry.trim())
+        .filter((entry) => {
+        if (!entry)
+            return false;
+        const separator = entry.indexOf('=');
+        const name = separator === -1 ? entry : entry.slice(0, separator).trim();
+        return !isPlatformCookie(name);
+    });
+    if (remaining.length > 0)
+        headers.set('Cookie', remaining.join('; '));
+    else
+        headers.delete('Cookie');
+}
+/**
+ * Clone `request` with credentials stripped, for callers that hand a whole
+ * Request to user code. Returns the original when there is nothing to remove,
+ * so the common case allocates nothing. WebSocket upgrades are passed through
+ * untouched: reconstructing them drops the `webSocket` handshake, and the
+ * upgrade itself is already authenticated upstream.
+ */
+export function sanitizeUntrustedRequest(request) {
+    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket')
+        return request;
+    const headers = new Headers(request.headers);
+    sanitizeUntrustedHeaders(headers);
+    const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+    return new Request(request.url, {
+        method: request.method,
+        headers,
+        ...(hasBody ? { body: request.body, duplex: 'half' } : {}),
+        redirect: request.redirect,
+    });
+}

package/dist/_shared/vfs-write-ledger.d.ts

@@ -0,0 +1,3 @@
+export declare const VFS_WRITE_MUTATION_QUEUE_SOURCE: string;
+export declare const VFS_WRITE_LEDGER_SOURCE: string;
+//# sourceMappingURL=vfs-write-ledger.d.ts.map

package/dist/_shared/vfs-write-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs-write-ledger.d.ts","sourceRoot":"","sources":["../../src/_shared/vfs-write-ledger.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,QAqZpC,CAAC;AAET,eAAO,MAAM,uBAAuB,QAgC5B,CAAC"}

package/dist/_shared/vfs-write-ledger.js

@@ -0,0 +1,439 @@
+export const VFS_WRITE_MUTATION_QUEUE_SOURCE = `
+const __vfsMutationTails = new Map();
+const __nimbusPendingVfsMutations = new Set();
+let __nimbusPendingVfsMutationFailure;
+let __nimbusHasPendingVfsMutationFailure = false;
+const __vfsWriteClaims = new Map();
+const __nimbusVfsAppendRangeResult = {};
+// Operation sequences reset when this generated module is evaluated again.
+// The nonce namespaces those retries without pretending a new application
+// request is the same logical append. Minted lazily: this source is spliced
+// into the opencode runner's module scope, where workerd forbids global-scope
+// RNG; the first append always runs in handler context.
+let __nimbusVfsModuleIncarnationNonce;
+function __nimbusVfsModuleIncarnation() {
+  return (__nimbusVfsModuleIncarnationNonce ??= crypto.randomUUID());
+}
+let __nimbusVfsAppendOperationSequence = 0;
+
+function __nimbusVfsPathKey(path) {
+  return String(path).replace(/^\\/+/, "");
+}
+
+/**
+ * A supervisor round trip the ledger issues on its own account.
+ *
+ * A facet's event loop exits when no handle is live, and an in-flight
+ * supervisor RPC is one of the handles it counts — but the debounced
+ * write-back runs from a raw timer, outside any call the program is awaiting,
+ * so nothing else was counting it. Measured: a template copy parked a cell,
+ * the debounce fired 10ms later and issued the write, the explicit flush
+ * behind it joined that same in-flight promise rather than starting its own,
+ * and the loop saw zero handles and ended the program with two files copied
+ * out of twenty-eight — silently, exit 0. fs.promises.cp is how
+ * create-cloudflare copies its template.
+ *
+ * The counter is the shims' __nimbusPendingOps, reached through globalThis
+ * rather than by calling their RPC helper: this source is spliced ahead of
+ * them and into embeddings that are not the one-shot entrypoint, and an
+ * absent counter must not be an error.
+ */
+async function __nimbusVfsRpc(promise) {
+  if (typeof globalThis.__nimbusPendingOps !== "number") globalThis.__nimbusPendingOps = 0;
+  globalThis.__nimbusPendingOps++;
+  try { return await promise; }
+  finally { globalThis.__nimbusPendingOps--; }
+}
+
+/**
+ * Errno values that are the filesystem ANSWERING the syscall: the path is not
+ * there, it is a directory, the descriptor is closed. The operation did not
+ * apply, no bytes were in flight, and nothing the program believes is saved
+ * has been lost. Node hands these to the caller and lets it decide — which is
+ * why \`fs.truncate(missing).catch(() => {})\` is ordinary, correct code.
+ *
+ * Everything else — EIO, a dropped RPC, a quota, an authority that died, an
+ * error carrying no errno at all — is not an answer. It means the outcome of
+ * a write is UNKNOWN, and that is a durability event no matter what the
+ * program caught. Unrecognised is treated as durability-class on purpose: the
+ * safe direction is to surface.
+ */
+const __NIMBUS_SYSCALL_VERDICT_CODES = new Set([
+  "ENOENT", "EEXIST", "EISDIR", "ENOTDIR", "ENOTEMPTY",
+  "EBADF", "EINVAL", "EPERM", "EACCES", "ELOOP", "ENAMETOOLONG",
+]);
+
+function __nimbusIsDurabilityFailure(error) {
+  const code = error && typeof error === "object" ? error.code : undefined;
+  return typeof code !== "string" || !__NIMBUS_SYSCALL_VERDICT_CODES.has(code);
+}
+
+/**
+ * Order a mutation behind the others queued for the same path.
+ *
+ * A rejection is ALSO reported to the drain when it is durability-class. That
+ * second channel is not redundancy: the tail handler below marks \`result\`
+ * handled, which suppresses the platform's own \`unhandledrejection\` signal,
+ * so retention is the only thing that can reach a durability boundary. Losing
+ * it is how a handler whose write failed still answers 200 — silent wrong
+ * data, which is what this ledger exists to prevent.
+ *
+ * What must NOT be retained is a plain syscall verdict. The queue used to
+ * retain those too, so an error the program had already caught was delivered
+ * a second time at teardown and killed the process: \`opencode --help\`
+ * rendered its whole help surface and then exited 1 on the
+ * \`fs.truncate(logfile).catch(() => {})\` in its logger init.
+ *
+ * The seam is the ERROR, not the call site. The same source line —
+ * \`fs.promises.truncate(p).catch(() => {})\` — must exit 0 when the file was
+ * simply absent, and must fail the response when the authority could not say
+ * whether the write landed. No per-call-site flag can express that, because
+ * both cases arrive through the same call site.
+ */
+function __nimbusQueueVfsMutation(path, mutation, retainFailure = true) {
+  const key = __nimbusVfsPathKey(path);
+  const previous = __vfsMutationTails.get(key) || Promise.resolve();
+  const result = previous.then(mutation);
+  __nimbusPendingVfsMutations.add(result);
+  // A failed mutation rejects its own caller but must not poison later writes
+  // for the same path or become an unhandled queue-cleanup rejection.
+  let tail;
+  const clearTail = () => {
+    __nimbusPendingVfsMutations.delete(result);
+    if (__vfsMutationTails.get(key) === tail) {
+      __vfsMutationTails.delete(key);
+    }
+  };
+  tail = result.then(clearTail, (error) => {
+    if (retainFailure
+        && __nimbusIsDurabilityFailure(error)
+        && !__nimbusHasPendingVfsMutationFailure) {
+      __nimbusHasPendingVfsMutationFailure = true;
+      __nimbusPendingVfsMutationFailure = error;
+    }
+    clearTail();
+  });
+  __vfsMutationTails.set(key, tail);
+  return result;
+}
+
+async function __nimbusDrainVfsMutations() {
+  while (__nimbusPendingVfsMutations.size > 0) {
+    await Promise.allSettled([...__nimbusPendingVfsMutations]);
+  }
+  if (__nimbusHasPendingVfsMutationFailure) {
+    const failure = __nimbusPendingVfsMutationFailure;
+    __nimbusHasPendingVfsMutationFailure = false;
+    __nimbusPendingVfsMutationFailure = undefined;
+    throw failure;
+  }
+}
+
+function __nimbusCapturePendingVfsAppend(path) {
+  const key = __nimbusVfsPathKey(path);
+  const append = __vfsAppendWrites[key];
+  return append && append.generation === __vfsWriteGenerations[key]
+    ? append
+    : null;
+}
+
+function __nimbusConcatVfsBytes(left, right) {
+  const bytes = new Uint8Array(left.byteLength + right.byteLength);
+  bytes.set(left, 0);
+  bytes.set(right, left.byteLength);
+  return bytes;
+}
+
+function __nimbusRecordVfsAppend(path, delta, fragment, previous) {
+  const key = __nimbusVfsPathKey(path);
+  const chain = previous ? previous.chain : { pending: [] };
+  let operation;
+  if (previous &&
+      !previous.claimed &&
+      !chain.pending.includes(previous.operation)) {
+    operation = previous.operation;
+    operation.bytes = __nimbusConcatVfsBytes(operation.bytes, delta);
+  } else {
+    operation = {
+      id: String(++__nimbusVfsAppendOperationSequence),
+      bytes: delta.slice(),
+    };
+  }
+  __vfsAppendWrites[key] = {
+    generation: __vfsWriteGenerations[key],
+    fragment,
+    chain,
+    operation,
+    claimed: false,
+  };
+}
+
+function __nimbusCaptureVfsWrite(path) {
+  const key = __nimbusVfsPathKey(path);
+  if (!Object.prototype.hasOwnProperty.call(__vfsWrites, key)) return null;
+  return {
+    key,
+    content: __vfsWrites[key],
+    generation: __vfsWriteGenerations[key],
+    append: __nimbusCapturePendingVfsAppend(key),
+  };
+}
+
+function __nimbusVfsAppendOperations(snapshot) {
+  const operations = snapshot.append.chain.pending.slice();
+  if (!operations.includes(snapshot.append.operation)) {
+    operations.push(snapshot.append.operation);
+  }
+  return operations;
+}
+
+function __nimbusBeginVfsAppendOperation(snapshot, operation) {
+  if (!snapshot.append.chain.pending.includes(operation)) {
+    snapshot.append.chain.pending.push(operation);
+  }
+}
+
+function __nimbusCommitVfsAppendOperation(snapshot, operation) {
+  const index = snapshot.append.chain.pending.indexOf(operation);
+  if (index !== -1) snapshot.append.chain.pending.splice(index, 1);
+}
+
+function __nimbusUnsupportedVfsAppend(path) {
+  const error = new Error(
+    "ENOSYS: preserving a nonresident append requires fsAppend and fsAppendAck: " + path,
+  );
+  error.code = "ENOSYS";
+  return error;
+}
+
+function __nimbusRunVfsWriteMutation(snapshot, mutation, retainFailure) {
+  return __nimbusQueueVfsMutation(snapshot.key, async () => {
+    const value = await mutation(snapshot.content, snapshot);
+    if (__vfsWriteGenerations[snapshot.key] === snapshot.generation) {
+      if (snapshot.append &&
+          value === __nimbusVfsAppendRangeResult &&
+          typeof __vfsBundle !== "undefined" &&
+          __vfsBundle) {
+        delete __vfsBundle[snapshot.key];
+      }
+      delete __vfsWrites[snapshot.key];
+      __nimbusStampFlushedCell(snapshot, value);
+    }
+    return value;
+  }, retainFailure);
+}
+
+/**
+ * Record the authority revision a just-flushed cell is known-good at.
+ *
+ * The barrier reports back every path mutated since the facet's cursor,
+ * which includes the facet's OWN writes — the invalidation log has no way
+ * to know who caused an entry. Without a stamp the facet drops the cells it
+ * authored the instant it flushes them, and a resumption then refetches
+ * bytes it is already holding: a self-inflicted cold cache on exactly the
+ * files a scaffolder or a build just wrote.
+ *
+ * A "skip paths I wrote" rule would be unsound — a peer may write the same
+ * path after us, and that invalidation is real. The revision separates
+ * them: a report AT our revision is our own write coming back, a report
+ * ABOVE it is somebody else's and still evicts.
+ *
+ * Guarded on cell identity rather than on the flush alone. A read that
+ * raced the flush may have refilled the cell from an older revision, and
+ * stamping that with our newer one would pin a stale byte — the one
+ * outcome this whole protocol exists to prevent.
+ *
+ * Only the written path is stamped, never its parent — deliberately, and it
+ * is why a batch of writes still costs ONE invalidation rather than none.
+ * Every mutation reports its parent directory too, so stamping the parent
+ * here looks like the obvious way to reach zero. It is not: the same
+ * revision on the directory would also vouch for a peer's earlier change to
+ * the DIRECTORY ITSELF — a chmod at a revision this facet never acquired —
+ * and that stale mode would then survive the barrier. The write knows what
+ * it did to the file and nothing about the directory. Do not "finish" this
+ * by stamping the parent.
+ */
+function __nimbusStampFlushedCell(snapshot, revision) {
+  if (typeof revision !== "number") return;
+  if (typeof __vfsBundle === "undefined" || !__vfsBundle) return;
+  if (__vfsBundle[snapshot.key] !== snapshot.content) return;
+  __vfsBundleRevisions[snapshot.key] = revision;
+}
+
+function __nimbusFlushVfsWrite(path, mutation, retainFailure = true) {
+  const snapshot = __nimbusCaptureVfsWrite(path);
+  if (!snapshot) return Promise.resolve(undefined);
+  const existing = __vfsWriteClaims.get(snapshot.key);
+  if (existing && existing.generation === snapshot.generation) {
+    return existing.promise;
+  }
+  if (snapshot.append) snapshot.append.claimed = true;
+  const result = __nimbusRunVfsWriteMutation(snapshot, mutation, retainFailure);
+  const claim = { generation: snapshot.generation, promise: result };
+  __vfsWriteClaims.set(snapshot.key, claim);
+  const release = () => {
+    if (__vfsWriteClaims.get(snapshot.key) === claim) {
+      __vfsWriteClaims.delete(snapshot.key);
+    }
+  };
+  result.then(release, () => {
+    release();
+    if (snapshot.append &&
+        __vfsAppendWrites[snapshot.key] === snapshot.append) {
+      snapshot.append.claimed = false;
+    }
+  });
+  return result;
+}
+
+async function __nimbusPersistVfsWrite(supervisor, path, content, snapshot) {
+  if (snapshot.append) {
+    if (typeof supervisor.fsAppend !== "function" ||
+        typeof supervisor.fsAppendAck !== "function") {
+      throw __nimbusUnsupportedVfsAppend(path);
+    }
+    for (const operation of __nimbusVfsAppendOperations(snapshot)) {
+      __nimbusBeginVfsAppendOperation(snapshot, operation);
+      await __nimbusVfsRpc(supervisor.fsAppend(
+        path,
+        __nimbusVfsModuleIncarnation(),
+        operation.id,
+        operation.bytes,
+      ));
+      __nimbusCommitVfsAppendOperation(snapshot, operation);
+      try {
+        await __nimbusVfsRpc(supervisor.fsAppendAck(__nimbusVfsModuleIncarnation(), operation.id));
+      } catch {
+        // The client has already relinquished retry ownership after the
+        // append success. A lost acknowledgement may retain a receipt, but
+        // must never turn a committed append into a failed/retried write.
+      }
+    }
+    return __nimbusVfsAppendRangeResult;
+  }
+  // The revision this write produced. It is what lets the ACQUIRE barrier
+  // tell this facet's own mutation apart from a peer's.
+  return __nimbusVfsRpc(supervisor.writeFile(path, content));
+}
+
+/**
+ * Write back everything parked, keeping any failure for the exit drain.
+ *
+ * The write-back sites that are not the exit drain — the debounce below and
+ * the RELEASE barrier ahead of egress — have no caller who could act on a
+ * failure: there is no user frame to throw into, and rejecting the fetch that
+ * happened to trigger the flush would blame the wrong operation. Retaining
+ * the failure in the channel \`__nimbusDrainVfsMutations\` already drains means
+ * the exit path still reports it, so a lost write is loud exactly once and
+ * never silent.
+ */
+async function __nimbusFlushVfsWriteBack(supervisor) {
+  if (!supervisor) return;
+  try {
+    await __nimbusDrainVfsWrites(supervisor);
+  } catch (error) {
+    if (!__nimbusHasPendingVfsMutationFailure) {
+      __nimbusHasPendingVfsMutationFailure = true;
+      __nimbusPendingVfsMutationFailure = error;
+    }
+  }
+}
+
+/**
+ * A synchronous write can only park bytes in \`__vfsWrites\`: a sync syscall
+ * has no channel to the authority. Something else therefore has to carry
+ * them across, and the only thing that did was the drain at process exit —
+ * so a resident server that writes synchronously never wrote back at all,
+ * and a peer reading the same path got the pre-write bytes for the whole
+ * life of the process. Measured, not theorised: \`writeFileSync\` then 50 ms
+ * left the authority at null with zero write RPCs issued.
+ *
+ * Flushing on every write is not the repair — 500 sync writes would become
+ * 500 round trips, and an npm install writes thousands. Debounce instead:
+ * parking a cell schedules one write-back, and every write that lands before
+ * it fires joins that same batch. Steady state costs no more round trips
+ * than the exit drain already paid; what changes is when they happen.
+ *
+ * The timer is the raw platform one, captured before the shims wrap
+ * \`setTimeout\` with the VFS resumption barrier: a write-back is the shim's
+ * own infrastructure, not a user resumption, and must not pay an ACQUIRE to
+ * deliver an ACQUIRE.
+ */
+const __NIMBUS_VFS_WRITE_BACK_DELAY_MS = 10;
+const __nimbusRawTimer = globalThis.setTimeout;
+let __nimbusVfsWriteBackTimer = null;
+function __nimbusScheduleVfsWriteBack() {
+  if (__nimbusVfsWriteBackTimer !== null) return;
+  if (typeof __nimbusRawTimer !== 'function') return;
+  __nimbusVfsWriteBackTimer = __nimbusRawTimer(() => {
+    __nimbusVfsWriteBackTimer = null;
+    const supervisor = typeof __supervisor !== 'undefined' ? __supervisor : null;
+    if (!supervisor) return;
+    // Not registered in __nimbusPendingVfsMutations: each write it starts
+    // registers itself there through __nimbusQueueVfsMutation, so the exit
+    // drain already awaits the work. Registering the orchestration too would
+    // add an entry nothing ever removes, and that set is drained by a
+    // while-loop on its size.
+    void __nimbusFlushVfsWriteBack(supervisor);
+  }, __NIMBUS_VFS_WRITE_BACK_DELAY_MS);
+}
+
+async function __nimbusDrainVfsWrites(supervisor) {
+  const paths = Object.keys(__vfsWrites);
+  const outcomes = await Promise.allSettled([
+    ...paths.map(async (path) => {
+      const persist = () => __nimbusFlushVfsWrite(
+        path,
+        (content, snapshot) =>
+          __nimbusPersistVfsWrite(supervisor, path, content, snapshot),
+        false,
+      );
+      try {
+        await persist();
+      } catch (error) {
+        // The authority may have committed before the RPC response was lost.
+        // One retry is safe: full writes are idempotent, while appends retain
+        // the same module/operation identity and are deduplicated by authority.
+        if (error && typeof error.code === "string") throw error;
+        await persist();
+      }
+    }),
+    __nimbusDrainVfsMutations(),
+  ]);
+  const failure = outcomes.find((outcome) => outcome.status === "rejected");
+  if (failure) throw failure.reason;
+}
+`.trim();
+export const VFS_WRITE_LEDGER_SOURCE = `
+const __vfsWriteGenerations = Object.create(null);
+// Per-path: the authority revision the resident cell in __vfsBundle is
+// known-good at. Only a flush of this facet's own bytes sets one, and the
+// ACQUIRE barrier is the only reader. An unstamped cell is simply evicted,
+// so a mutation path that forgets to stamp costs a refetch and never a
+// stale byte.
+const __vfsBundleRevisions = Object.create(null);
+const __vfsAppendWrites = Object.create(null);
+const __vfsWrites = new Proxy(Object.create(null), {
+  set(target, path, value) {
+    target[path] = value;
+    delete __vfsAppendWrites[path];
+    __vfsWriteGenerations[path] = (__vfsWriteGenerations[path] || 0) + 1;
+    // Parking a cell is the only signal a synchronous write leaves. It is
+    // therefore the one place a write-back can be scheduled from, and it
+    // covers every sync mutation — writeFileSync, appendFileSync, the fd
+    // writes, rename — with no per-call-site duplication.
+    __nimbusScheduleVfsWriteBack();
+    return true;
+  },
+  deleteProperty(target, path) {
+    delete __vfsAppendWrites[path];
+    if (Object.prototype.hasOwnProperty.call(target, path)) {
+      delete target[path];
+      __vfsWriteGenerations[path] = (__vfsWriteGenerations[path] || 0) + 1;
+    }
+    return true;
+  },
+});
+
+${VFS_WRITE_MUTATION_QUEUE_SOURCE}
+`.trim();