@nimbus-sh/platform 0.8.1 → 0.13.0

package/src/limits.ts

@@ -197,6 +197,26 @@ export const FACET_OWN_WRITE_MEMORY_BYTES = 32 * 1024 * 1024;
 // holds nothing more and the session answers.
 export const WASI_RESIDENT_STORE_BYTES = 32 * 1024 * 1024;
 
+// A file too big to hold whole (over WASI_RESIDENT_FILE_CAP_BYTES: a pack, a
+// deep history's .idx) is read through the resident store a page at a time:
+// git's own unit for a paged pack index, and a sixteenth of its 1 MiB pack
+// window, so one window is one batch read.
+export const RESIDENT_PAGE_BYTES = 64 * 1024;
+
+// The most a resident store holds of such pages, least recently used out
+// first; in a one-shot's heap, never more than half its budget. Measured on vscode's full history (2.18M objects):
+// a .idx of 57.5 MiB, of which every command touched ~49 MiB, and a .rev of
+// 8.6 MiB, so the bound keeps a deep history's index and its hot pack windows.
+export const RESIDENT_PAGE_CACHE_BYTES = 512 * 1024 * 1024;
+
+// The pages are a cache in the session's one storage limit (N18), which the
+// user's files share: they never hold more than this share of what they hold
+// plus what the ledger says is still free at the last grant, so a filling
+// session takes room from the cache, not from the user. Evicted pages are
+// reused by the same facet database; its size, which df counts, stays at its
+// high-water mark until the facet's storage is deleted.
+export const RESIDENT_PAGE_CACHE_FREE_SHARE = 0.25;
+
 // Shared allowance for transient allocations in the supervisor DO. With the
 // VFS LRU shrunk to 8 MiB during an active reservation, 40 MiB of admitted
 // payload plus the 9 MiB bundle baseline stays below the 64 MiB soft ceiling
@@ -204,6 +224,15 @@ export const WASI_RESIDENT_STORE_BYTES = 32 * 1024 * 1024;
 // This is 31.25% of the platform's 128 MiB hard isolate ceiling.
 export const SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES = 40 * 1024 * 1024;
 
+// The longest a facet's load waits for that allowance before it is refused
+// (acquireSupervisorLoadAllocation). The wait is FIFO, so a load waits only
+// for the holds ahead of it, each of which ends when its own work does. A
+// load is the one owner that waits while it holds a Dynamic Worker (the
+// loader asks for its code then), so a launch that holds credit while it
+// waits for a worker of the same Durable Object can close a cycle nothing
+// ends: the bound refuses the load, by name, instead of leaving both to hang.
+export const SUPERVISOR_LOAD_WAIT_MS = 60_000;
+
 // Reserved slice of that allowance for chunk-sized filesystem reads, so a
 // read is never queued behind a multi-megabyte owner for a wait that has
 // nothing to do with its own cost. A read only draws on this when the shared

package/src/module-source.ts

@@ -1,3 +1,5 @@
+import { utf8Length } from './utf8.js';
+
 /** A deployed source asset: its digest, not its pathname, is its identity. */
 export interface ModuleSourceAsset {
   path: string;
@@ -26,7 +28,7 @@ export class ModuleSource {
   private joined: string | undefined;
   readonly byteLength: number;
   constructor(readonly parts: readonly ModuleSourcePart[]) {
-    this.byteLength = parts.reduce((bytes, part) => bytes + (typeof part === 'string' ? new TextEncoder().encode(part).byteLength : part.byteLength), 0);
+    this.byteLength = parts.reduce((bytes, part) => bytes + (typeof part === 'string' ? utf8Length(part) : part.byteLength), 0);
   }
   get text(): string {
     return this.joined ??= this.parts.map((part) => typeof part === 'string' ? part : part.text).join('');

package/src/oom-classify.ts

@@ -194,7 +194,7 @@ export function classifyMessage(msg: string): OomCause {
  * why an object reset mid-write still failed a whole install. Nimbus has
  * measured the live-write wording twice: a 45.7 MB single-turn write reset the
  * object once and the same write then succeeded 12/12 on retry
- * (`vfs/facet-resident-store.ts`), and it reset a session DO mid-npm-install
+ * (`vfs/resident`), and it reset a session DO mid-npm-install
  * on 2026-08-10 (probe `agentic-cli/new/pi-official-installer`). Retrying is
  * bounded, so the one case that is NOT transient — crossing the object's
  * storage budget, which the platform also reports this way
@@ -273,6 +273,10 @@ export type DoCallClass =
   | 'storage_reset'
   /** The runtime flagged the error `retryable` itself. */
   | 'retryable_flag'
+  /** The platform failed the call without saying why ("internal error;
+   *  reference = …", isUnexplainedPlatformError): whether it ran is unknown.
+   *  Not a transient class: only a callee that converges repeats it. */
+  | 'platform_internal'
   /** The object shed the call under queue pressure. NEVER retried: retrying
    *  an overloaded object is what overloaded it. */
   | 'overloaded'
@@ -317,6 +321,7 @@ export function classifyDoCall(input: unknown): DoCallClass {
   const seen = new Set<Error>();
   const messages: string[] = [];
   let flagged = false;
+  let unexplained = false;
   let link: Error | null = input;
   while (link !== null && !seen.has(link)) {
     seen.add(link);
@@ -324,6 +329,7 @@ export function classifyDoCall(input: unknown): DoCallClass {
       || isDoOverloaded(link.message);
     if (overloaded) return 'overloaded';
     if ('retryable' in link && link.retryable === true) flagged = true;
+    if (isUnexplainedPlatformError(link)) unexplained = true;
     messages.push(link.message ?? '');
     const cause: unknown = link.cause;
     link = cause instanceof Error ? cause : null;
@@ -333,6 +339,8 @@ export function classifyDoCall(input: unknown): DoCallClass {
     if (pattern.test(chain)) return transient;
   }
   if (flagged) return 'retryable_flag';
+  // Only where nothing in the chain explains it: a wrapper's own words are not the platform's.
+  if (unexplained) return 'platform_internal';
   return 'permanent';
 }
 

package/src/realm-builtin.ts

@@ -0,0 +1,22 @@
+/**
+ * A Node builtin of the realm's own process (`process.getBuiltinModule`),
+ * never a program's: a Nimbus runtime that puts a program's process in front
+ * of the realm's (node-shims) records the realm's own under
+ * `Symbol.for('nimbus.fronts')`, and a warm isolate keeps the last program's
+ * process as the global after it ends. Its builtins carry Node's argument
+ * checks and errors for programs, which the runtime's own callers pay for
+ * on every call. Undefined where the realm has no such builtin.
+ */
+type BuiltinProcess = { getBuiltinModule?(id: string): unknown };
+type Fronts = WeakMap<object, { own: unknown }>;
+
+export function realmBuiltin<T>(id: string): T | undefined {
+  try {
+    const global = globalThis as { process?: BuiltinProcess } & Record<symbol, Fronts | undefined>;
+    const current = global.process;
+    const own = (current && global[Symbol.for('nimbus.fronts')]?.get(current)?.own) as BuiltinProcess | undefined;
+    return (own ?? current)?.getBuiltinModule?.(id) as T | undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/utf8.ts

@@ -1,5 +1,6 @@
 /**
- * utf8.ts — the UTF-8 length of a string, without encoding it.
+ * utf8.ts — the UTF-8 length of a string, and the order of two strings by
+ * their UTF-8 bytes, without encoding them.
  *
  * Bounds on names and payloads are in bytes, and the hot ones (every path a
  * W7 wave or a listing page carries) were measured by encoding the string
@@ -7,7 +8,15 @@
  * TextEncoder would write: one to four per code point, and three for a
  * lone surrogate, which it writes as U+FFFD.
  */
+
+/** From this many UTF-16 units, a string is counted natively (longUtf8Length). */
+const LONG_UNITS = 256;
+const encoder = new TextEncoder();
+/** Where longUtf8Length's encodes land: written, never read. */
+let scratch: Uint8Array | undefined;
+
 export function utf8Length(text: string): number {
+  if (text.length >= LONG_UNITS) return longUtf8Length(text);
   let bytes = text.length;
   for (let index = 0; index < text.length; index++) {
     const unit = text.charCodeAt(index);
@@ -29,3 +38,62 @@ export function utf8Length(text: string): number {
   }
   return bytes;
 }
+
+/**
+ * A long string's UTF-8 length at the engine's speed: encoded a slice at a
+ * time into one reused buffer, only the count kept. encodeInto never splits
+ * a surrogate pair, so each slice starts on a code point.
+ */
+function longUtf8Length(text: string): number {
+  scratch ??= new Uint8Array(256 * 1024);
+  let bytes = 0;
+  for (let read = 0; read < text.length;) {
+    const done = encoder.encodeInto(read === 0 ? text : text.slice(read), scratch);
+    read += done.read;
+    bytes += done.written;
+  }
+  return bytes;
+}
+
+/**
+ * The code point at `index` of `text`: a pair is one past U+FFFF, and a lone
+ * surrogate is its own (as WTF-8 writes it, between U+D7FF and U+E000).
+ */
+function codePointAt(text: string, index: number): number {
+  const unit = text.charCodeAt(index);
+  if (unit < 0xd800 || unit > 0xdbff || index + 1 >= text.length) return unit;
+  const next = text.charCodeAt(index + 1);
+  return next >= 0xdc00 && next <= 0xdfff ? 0x10000 + ((unit - 0xd800) << 10) + (next - 0xdc00) : unit;
+}
+
+/**
+ * `a` against `b` (negative, 0, positive) as their UTF-8 bytes order them,
+ * as SQLite's `ORDER BY` of a text column and git's index do: code point
+ * order. A string UTF-8 cannot write (a lone surrogate) is ordered as WTF-8
+ * writes it, its surrogate a code point of its own: the order is total, as a
+ * listing's cursor needs, and decided at the first code point that differs,
+ * so a directory's entries follow it together. Units equal in both are
+ * passed as they are; two that differ, neither a surrogate, are their own
+ * code points; the rest, rare in a path, is surrogatesAt's.
+ */
+export function compareUtf8(a: string, b: string): number {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const x = a.charCodeAt(i);
+    const y = b.charCodeAt(i);
+    if (x === y) continue;
+    if ((x < 0xd800 || x > 0xdfff) && (y < 0xd800 || y > 0xdfff)) return x - y;
+    return surrogatesAt(a, b, i);
+  }
+  return a.length - b.length;
+}
+
+/** compareUtf8 of `a` and `b`, equal before `i`, where they differ at `i` and one unit there is a surrogate. */
+function surrogatesAt(a: string, b: string, i: number): number {
+  // A low half after a high one the two share: the code points begin at the high one.
+  const before = i > 0 ? a.charCodeAt(i - 1) : 0;
+  const x = a.charCodeAt(i);
+  const y = b.charCodeAt(i);
+  const at = before >= 0xd800 && before <= 0xdbff && ((x >= 0xdc00 && x <= 0xdfff) || (y >= 0xdc00 && y <= 0xdfff)) ? i - 1 : i;
+  return codePointAt(a, at) - codePointAt(b, at);
+}

package/src/w7-frame.ts

@@ -16,6 +16,7 @@
 import { crc32 } from './crc32.js';
 import { CHUNK_SIZE } from './limits.js';
 import { utf8Length } from './utf8.js';
+import { rootClampedSegments } from './lexical-path.js';
 
 // The batch payload types live WITH the wire format that encodes them: every
 // producer and consumer of a W7 stream speaks exactly these records, and the
@@ -79,10 +80,14 @@ export interface BatchWritePayload {
   ops?: W7Op[];
 }
 
-/** One attribute change (setattr): the mode, the owner, or the times; what chmod, chown and utimes each make. */
+/**
+ * One attribute change (setattr): the mode, the owner, or the times; what
+ * chmod, chown and utimes each make. An owner side that is null keeps what
+ * the file has when the change lands (chown's -1).
+ */
 export type W7Attrs =
   | { mode: number }
-  | { uid: number; gid: number }
+  | { uid: number | null; gid: number | null }
   | { atime: number; mtime: number };
 
 /**
@@ -94,6 +99,23 @@ export type W7Attrs =
  * nothing makes a missing parent. The program-order counterpart of the
  * syscall, where `file` and `directory` are a checkout's upserts.
  */
+/** What a W7 open asks of its file, as open(2)'s O_ACCMODE: to read it, to write it, or both. */
+export type W7OpenAccess = 'read' | 'write' | 'readwrite';
+function isOpenAccess(value: unknown): value is W7OpenAccess {
+  return value === 'read' || value === 'write' || value === 'readwrite';
+}
+
+/** The rights an open's access grants its description: what a call through it may do. */
+export function openAccessRights(access: W7OpenAccess): { read: boolean; write: boolean } {
+  return { read: access !== 'write', write: access !== 'read' };
+}
+
+/** The permission bits an open asks of the file it reaches (4 read, 2 write): its access's, and write under `truncate`, as open(2)'s. */
+export function openAccessMask(call: { access: W7OpenAccess; truncate?: true }): number {
+  const rights = openAccessRights(call.access);
+  return (rights.read ? 4 : 0) | (rights.write || call.truncate === true ? 2 : 0);
+}
+
 export type W7Call =
   /**
    * `ino`, on a call that makes a name (writeFile, appendFile, mkdir,
@@ -125,6 +147,14 @@ export type W7Call =
   | { call: 'unlink'; path: string }
   | { call: 'rmdir'; path: string }
   | { call: 'symlink'; path: string; target: string; ino?: number }
+  /**
+   * copyfile as the session copies a file: the file \`from\` names (a link
+   * followed) to \`path\` (a link there followed, a file there replaced),
+   * by reference within one filesystem and by its bytes across, no byte of
+   * it in the wave. The copy's mode is a copy's there: a new file the
+   * source's less the umask, a file there its own.
+   */
+  | { call: 'copyFile'; path: string; from: string }
   /**
    * rm(1) as fs.rm makes it: a file or link unlinked, a directory with all
    * it holds when `recursive` (else EISDIR's refusal, as unlink's), and a
@@ -132,22 +162,27 @@ export type W7Call =
    */
   | { call: 'rm'; path: string; recursive?: true; force?: true }
   /** chown(2) of the link itself (lchown): the name's own entry, never what it names. */
-  | { call: 'lchown'; path: string; uid: number; gid: number }
+  | { call: 'lchown'; path: string; uid: number | null; gid: number | null }
   /** utimes of the link itself (lutimes). */
   | { call: 'lutimes'; path: string; atime: number; mtime: number }
   /**
-   * open(2) of a file to write it (and to read it when `read`), as the
-   * session's own open decides it: a name made (`create`, `mode` less
-   * `umask`) or refused (EEXIST when `exclusive`, ENOENT without `create`,
-   * EISDIR, EACCES for any access asked that the file's mode refuses),
+   * open(2) of a file with the access `access` asks, as O_ACCMODE does
+   * (W7OpenAccess), as the session's own open decides it: a name made
+   * (`create`, `mode` less `umask`) or refused (EEXIST when `exclusive`,
+   * ENOENT without `create`, EISDIR, EACCES for any access asked that the
+   * file's mode refuses, write too under `truncate`: openAccessMask),
    * emptied when `truncate`, a link at the name followed unless `nofollow`
    * (ELOOP). Its answer is the file's stat. With `description` (an id the
    * process chose), the session keeps the open description under it, its
-   * access fixed now; the description's write, append and ftruncate calls
-   * name it, and its `close` ends it. `ino`: the number a name it makes is
-   * given (a delegation's, as a mkdir's).
+   * rights the access's (openAccessRights); the description's write, append
+   * and ftruncate calls name it, and its `close` ends it. `ino`: the number
+   * a name it makes is given (a delegation's, as a mkdir's). `fchmod`: the
+   * file it opened then given exactly this mode (fchmod(2), as libuv's
+   * copyfile narrows its destination before a byte reaches it), part of the
+   * open: refused (EPERM: another's file), the open is refused and keeps no
+   * description, so a write through it is EBADF.
    */
-  | { call: 'open'; path: string; mode: number; ino?: number; umask?: number; read?: true; create?: true; truncate?: true; exclusive?: true; nofollow?: true; description?: string }
+  | { call: 'open'; path: string; mode: number; access: W7OpenAccess; ino?: number; umask?: number; create?: true; truncate?: true; exclusive?: true; nofollow?: true; description?: string; fchmod?: number }
   /** close(2) of the session's open description `description` (an `open` call's). */
   | { call: 'close'; path: string; description: string };
 
@@ -677,7 +712,7 @@ async function* decodeRecords(
           if (v3) throw new Error(`w7-frame: unknown record tag ${envelope.tag}`);
           summary.pathCount++;
           summary.opCount++;
-          const value = parseObject(payload, 'call', ['call', 'path'], ['mode', 'target', 'ino', 'size', 'existing', 'recursive', 'force', 'uid', 'gid', 'atime', 'mtime', 'umask', 'read', 'create', 'truncate', 'exclusive', 'nofollow', 'description']);
+          const value = parseObject(payload, 'call', ['call', 'path'], ['mode', 'target', 'from', 'ino', 'size', 'existing', 'recursive', 'force', 'uid', 'gid', 'atime', 'mtime', 'umask', 'access', 'create', 'truncate', 'exclusive', 'nofollow', 'description', 'fchmod']);
           yield { type: 'call', call: parsePathCall(value, (path, label) => ownedPaths.claim(canonicalPath(path, label))) };
           break;
         }
@@ -812,8 +847,8 @@ async function* encodeFile(file: EncoderFile, state: EncoderState): AsyncGenerat
   let fileCheck = 0;
   let chunkId = 0;
   const pieces = file.source === null ? givenChunks(file.chunks) : fixedChunks(file.inode, file.source);
+  const contentBytes = TEXT_ENCODER.encode(file.contentId);
   for await (const data of pieces) {
-    const contentBytes = new TextEncoder().encode(file.contentId);
     const prefix = new Uint8Array(4 + contentBytes.length + 8);
     writeU32LE(prefix, 0, contentBytes.length);
     prefix.set(contentBytes, 4);
@@ -880,16 +915,20 @@ function encodeMetadataRecord(
   value: object,
   state?: EncoderState,
 ): Uint8Array[] {
-  const payload = new TextEncoder().encode(JSON.stringify(value));
+  const payload = TEXT_ENCODER.encode(JSON.stringify(value));
   if (payload.byteLength > MAX_METADATA_BYTES) {
     throw new Error(`w7-frame: metadata record exceeds ${MAX_METADATA_BYTES} bytes`);
   }
-  const header = recordHeader(tag, payload.byteLength);
+  // The header and the payload in one buffer, checked as one (crc32 composes).
+  const record = new Uint8Array(5 + payload.byteLength);
+  record[0] = tag;
+  writeU32LE(record, 1, payload.byteLength);
+  record.set(payload, 5);
   if (state && tag !== RecordTag.BatchEnd) {
-    state.batchCheck = updateRecordCheck(state.batchCheck, header, payload);
+    state.batchCheck = updateRecordCheck(state.batchCheck, record);
     state.summary.recordCount++;
   }
-  return [concatBytes(header, payload)];
+  return [record];
 }
 
 /**
@@ -1020,7 +1059,7 @@ function parseBatchBegin(bytes: Uint8Array, mode: W7Mode): BatchBeginMetadata {
 function parseAttrs(value: Record<string, unknown>, label: string): W7Attrs {
   const keys = Object.keys(value).sort().join(',');
   if (keys === 'mode') return { mode: u32(value.mode, `${label} mode`) };
-  if (keys === 'gid,uid') return { uid: u32(value.uid, `${label} uid`), gid: u32(value.gid, `${label} gid`) };
+  if (keys === 'gid,uid') return { uid: ownerId(value.uid, `${label} uid`), gid: ownerId(value.gid, `${label} gid`) };
   if (keys === 'atime,mtime') return { atime: safeInteger(value.atime, `${label} atime`), mtime: safeInteger(value.mtime, `${label} mtime`) };
   throw new Error(`w7-frame: ${label} changes the mode, the owner or the times, one of them: got ${keys || 'nothing'}`);
 }
@@ -1108,6 +1147,9 @@ function parsePathCall(value: Record<string, unknown>, path: (value: unknown, la
         call: 'symlink', path: path(value.path, 'symlink path'), target: boundedString(value.target, 'symlink target', MAX_PATH_BYTES),
         ...(value.ino === undefined ? {} : { ino: inodeNumber(value.ino, 'symlink ino') }),
       };
+    case 'copyFile':
+      if (keys !== 'call,from,path') break;
+      return { call: 'copyFile', path: path(value.path, 'copyFile path'), from: path(value.from, 'copyFile from') };
     case 'ftruncate':
       if (keys.replace(',description', '').replace(',ino', '') !== 'call,path,size') break;
       return {
@@ -1131,25 +1173,27 @@ function parsePathCall(value: Record<string, unknown>, path: (value: unknown, la
     }
     case 'lchown':
       if (keys !== 'call,gid,path,uid') break;
-      return { call: 'lchown', path: path(value.path, 'lchown path'), uid: u32(value.uid, 'lchown uid'), gid: u32(value.gid, 'lchown gid') };
+      return { call: 'lchown', path: path(value.path, 'lchown path'), uid: ownerId(value.uid, 'lchown uid'), gid: ownerId(value.gid, 'lchown gid') };
     case 'open': {
-      const flags = ['create', 'exclusive', 'nofollow', 'read', 'truncate'] as const;
+      const flags = ['create', 'exclusive', 'nofollow', 'truncate'] as const;
       let required = keys;
-      for (const flag of ['create', 'description', 'exclusive', 'ino', 'nofollow', 'read', 'truncate', 'umask']) required = required.replace(`,${flag}`, '');
-      if (required !== 'call,mode,path') break;
+      for (const flag of ['create', 'description', 'exclusive', 'fchmod', 'ino', 'nofollow', 'truncate', 'umask']) required = required.replace(`,${flag}`, '');
+      if (required !== 'access,call,mode,path') break;
       for (const flag of flags) {
         if (value[flag] !== undefined && value[flag] !== true) throw new Error(`w7-frame: open ${flag} is true or absent`);
       }
+      const access = value.access;
+      if (!isOpenAccess(access)) throw new Error(`w7-frame: open access is 'read', 'write' or 'readwrite': got ${String(access)}`);
       return {
-        call: 'open', path: path(value.path, 'open path'), mode: u32(value.mode, 'open mode'),
+        call: 'open', path: path(value.path, 'open path'), mode: u32(value.mode, 'open mode'), access,
         ...(value.ino === undefined ? {} : { ino: inodeNumber(value.ino, 'open ino') }),
         ...(value.umask === undefined ? {} : { umask: umaskOf(value.umask, 'open umask') }),
         ...(value.create === true ? { create: true as const } : {}),
         ...(value.truncate === true ? { truncate: true as const } : {}),
         ...(value.exclusive === true ? { exclusive: true as const } : {}),
         ...(value.nofollow === true ? { nofollow: true as const } : {}),
-        ...(value.read === true ? { read: true as const } : {}),
         ...(value.description === undefined ? {} : { description: descriptionId(value.description, 'open description') }),
+        ...(value.fchmod === undefined ? {} : { fchmod: u32(value.fchmod, 'open fchmod') }),
       };
     }
     case 'lutimes':
@@ -1384,15 +1428,7 @@ class PathOwnership {
 }
 
 function normalizePath(path: string): string {
-  const out: string[] = [];
-  for (const segment of path.split('/')) {
-    if (segment === '..') {
-      if (out.length > 0) out.pop();
-    } else if (segment !== '' && segment !== '.') {
-      out.push(segment);
-    }
-  }
-  return out.join('/');
+  return rootClampedSegments(path).join('/');
 }
 
 function parentPath(path: string): string {
@@ -1415,6 +1451,11 @@ function safeInteger(value: unknown, label: string): number {
   return value as number;
 }
 
+/** A chown side: a uid or gid, or null, which keeps the file's. */
+function ownerId(value: unknown, label: string): number | null {
+  return value === null ? null : u32(value, label);
+}
+
 function u32(value: unknown, label: string): number {
   const integer = safeInteger(value, label);
   if (integer > 0xffff_ffff) throw new Error(`w7-frame: ${label} exceeds uint32`);

package/src/wave-writer.ts

@@ -164,7 +164,7 @@ export interface WaveWriterOptions<Meta = undefined> {
   root: string | null;
   /** An existing worktree: only directories strictly below it are published. */
   worktreeRoot?: string | null;
-  /** Record paths are relative to it (joined with '/'); omitted, they are VFS paths. */
+  /** Record paths are relative to it (joined with '/'; '' is the base itself); omitted, they are VFS paths. */
   base?: string;
   /** Wall-clock time (ms) after which no new wave starts. */
   deadline?: number | null;
@@ -300,7 +300,6 @@ export class WaveWriter<Meta = undefined> {
   private ownedPathBytes = 0;
   private pin: Pin | null = null;
   private inFlight: Promise<void> | null = null;
-  private cutQueue: Promise<unknown> = Promise.resolve();
   private sequence = 0;
   private failure: WaveFailure | null = null;
   /** Owners (records' `meta`) whose records a failed wave carried. */
@@ -532,7 +531,8 @@ export class WaveWriter<Meta = undefined> {
   // ── Internals ────────────────────────────────────────────────────────
 
   private key(path: string): string {
-    return this.options.base ? this.options.base + '/' + path : path;
+    if (!this.options.base) return path;
+    return path ? this.options.base + '/' + path : this.options.base;
   }
 
   private tally(): Tally {
@@ -551,13 +551,24 @@ export class WaveWriter<Meta = undefined> {
     if (admit) this.owned.add(path);
   }
 
-  /** collectDirectoryPaths' chain from `path` upward, to the first directory already owned. */
-  private walkChain(path: string, admit: boolean, tally: Tally): void {
+  /**
+   * The directories a wave publishes for something at or below `dir`:
+   * `dir` and each one above it, deepest first, up to the writer's root
+   * (included) and inside its worktree root.
+   */
+  private *chain(dir: string): Generator<string, void, undefined> {
     const { root, worktreeRoot = null } = this.options;
-    let current = path;
-    while (current) {
-      if (root && current !== root && !current.startsWith(root + '/')) break;
-      if (worktreeRoot !== null && !current.startsWith(worktreeRoot + '/')) break;
+    for (let current = dir; current; current = parentOf(current)) {
+      if (root && current !== root && !current.startsWith(root + '/')) return;
+      if (worktreeRoot !== null && !current.startsWith(worktreeRoot + '/')) return;
+      yield current;
+      if (current === root) return;
+    }
+  }
+
+  /** The chain from `path` upward, to the first directory already owned. */
+  private walkChain(path: string, admit: boolean, tally: Tally): void {
+    for (const current of this.chain(path)) {
       this.counters.ownershipVisits++;
       if (this.ownedDirectories.has(current)) break;
       if (admit) this.ownedDirectories.add(current);
@@ -566,8 +577,6 @@ export class WaveWriter<Meta = undefined> {
         tally.pathBytes += utf8Length(current);
         if (admit) this.owned.add(current);
       }
-      if (current === root) break;
-      current = parentOf(current);
     }
   }
 
@@ -636,16 +645,14 @@ export class WaveWriter<Meta = undefined> {
   }
 
   /**
-   * Send the buffered wave once the one in flight has published. Cuts are
-   * serialised, so at most one wave is in flight and one buffers.
+   * Send the buffered wave once the one in flight has published. Only a
+   * mutation cuts, and mutations run one at a time, so at most one wave is
+   * in flight and one buffers.
    */
-  private cut(): Promise<void> {
-    const run = this.cutQueue.then(() => this.cutNow());
-    this.cutQueue = run.catch(() => {});
-    return run;
-  }
-
-  private async cutNow(): Promise<void> {
+  private async cut(): Promise<void> {
+    // A later turn than the mutation that asks: a pin set or cleared by a
+    // microtask queued before the cut is the wave's.
+    await Promise.resolve();
     if (this.inFlight) {
       const waitStarted = Date.now();
       await this.inFlight.catch(() => {});
@@ -848,16 +855,10 @@ export class WaveWriter<Meta = undefined> {
   /** The directories the buffered records publish, shallowest first. */
   private publishedDirectories(): string[] {
     const dirs = new Set<string>();
-    const { root, worktreeRoot = null } = this.options;
     const collect = (path: string): void => {
-      let current = path;
-      while (current) {
-        if (root && current !== root && !current.startsWith(root + '/')) break;
-        if (worktreeRoot !== null && !current.startsWith(worktreeRoot + '/')) break;
+      for (const current of this.chain(path)) {
         if (dirs.has(current)) break;
         dirs.add(current);
-        if (current === root) break;
-        current = parentOf(current);
       }
     };
     for (const path of this.records.keys()) collect(parentOf(path));