@nimbus-sh/platform 0.8.2 → 0.14.0

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,11 +80,26 @@ 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).
+ */
+/**
+ * A time utimes and futimes set, as utimensat(2) takes it: ms since the
+ * epoch (explicit: only the owner may set it), 'now' (UTIME_NOW: the
+ * clock of the filesystem that commits the change, as it commits it) or
+ * 'omit' (UTIME_OMIT: left as it is then). 'now' and 'omit' need the owner or write
+ * permission. Carried as it is to the filesystem that commits the change,
+ * which alone resolves it (posix-access.ts, timeAt) and judges it
+ * (utimesRefusal, explicitTimes).
+ */
+export type FsTime = number | 'now' | 'omit';
+
 export type W7Attrs =
   | { mode: number }
-  | { uid: number; gid: number }
-  | { atime: number; mtime: number };
+  | { uid: number | null; gid: number | null }
+  | { atime: FsTime; mtime: FsTime };
 
 /**
  * A process's filesystem call as a record (v4), applied by the session's own
@@ -94,6 +110,36 @@ 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);
+}
+
+/**
+ * What a process decided a call on from its own view of the name: the file
+ * it expected there (its number on the session's filesystem), none (null),
+ * or the file its open of description `made` reached, for a file that open
+ * made and the process has no number of yet (it keeps that description
+ * open until it has). Where the name leads elsewhere now (a stale view: a
+ * peer replaced the name, or a link there leads to another file; or that
+ * open was refused), the session refuses the call before any effect:
+ * ENOENT where it expected a file, EEXIST where it expected none, EXDEV
+ * where the name leads to a mount.
+ */
+export type W7Expected = number | null | { readonly made: string };
+
 export type W7Call =
   /**
    * `ino`, on a call that makes a name (writeFile, appendFile, mkdir,
@@ -122,9 +168,17 @@ export type W7Call =
   | { call: 'ftruncate'; path: string; ino?: number; description?: string; size: number }
   /** `existing: 'ok'`: a directory already there answers success, as `mkdir -p` takes it (anything else there is still EEXIST). */
   | { call: 'mkdir'; path: string; mode: number; ino?: number; umask?: number; existing?: 'ok' }
-  | { call: 'unlink'; path: string }
-  | { call: 'rmdir'; path: string }
+  | { call: 'unlink'; path: string; expect?: W7Expected }
+  | { call: 'rmdir'; path: string; expect?: W7Expected }
   | { 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 +186,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; expect?: W7Expected }
   /** close(2) of the session's open description `description` (an `open` call's). */
   | { call: 'close'; path: string; description: string };
 
@@ -162,9 +221,11 @@ export type W7Op =
   | { type: 'directory'; inode: BatchInodeEntry }
   | { type: 'file'; inode: BatchInodeEntry; data: Uint8Array }
   | { type: 'file'; inode: BatchInodeEntry; source: AsyncIterable<Uint8Array> }
-  | { type: 'rename'; from: string; to: string }
+  /** `expect`, `expectTo`: the files the process expected at `from` and at `to` (W7Expected). */
+  | { type: 'rename'; from: string; to: string; expect?: W7Expected; expectTo?: W7Expected }
   | { type: 'truncate'; path: string; size: number }
-  | { type: 'setattr'; path: string; attrs: W7Attrs }
+  /** `description`: through the session's open description of that id (fchmod, fchown, futimens): its file, whatever names it now. */
+  | { type: 'setattr'; path: string; attrs: W7Attrs; description?: string; expect?: W7Expected }
   | { type: 'call'; call: W7Call };
 
 export const W7_MAGIC = new Uint8Array([0x4e, 0x57, 0x37, 0x04]);
@@ -315,9 +376,9 @@ export type W7DecodedRecord =
       chunkCount: number;
       check: number;
     }
-  | { type: 'rename'; from: string; to: string }
+  | { type: 'rename'; from: string; to: string; expect?: W7Expected; expectTo?: W7Expected }
   | { type: 'truncate'; path: string; size: number }
-  | { type: 'setattr'; path: string; attrs: W7Attrs }
+  | { type: 'setattr'; path: string; attrs: W7Attrs; description?: string; expect?: W7Expected }
   | { type: 'call'; call: W7PathCall }
   | { type: 'batch-end'; summary: W7BatchSummary };
 
@@ -332,9 +393,9 @@ type EncoderOp =
   | { kind: 'delete'; path: string }
   | { kind: 'directory'; inode: W7DirectoryInode }
   | { kind: 'file'; file: EncoderFile }
-  | { kind: 'rename'; from: string; to: string }
+  | { kind: 'rename'; from: string; to: string; expect?: W7Expected; expectTo?: W7Expected }
   | { kind: 'truncate'; path: string; size: number }
-  | { kind: 'setattr'; path: string; attrs: W7Attrs }
+  | { kind: 'setattr'; path: string; attrs: W7Attrs; description?: string; expect?: W7Expected }
   | { kind: 'call'; call: W7PathCall };
 
 interface EncoderFile {
@@ -677,7 +738,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', 'expect']);
           yield { type: 'call', call: parsePathCall(value, (path, label) => ownedPaths.claim(canonicalPath(path, label))) };
           break;
         }
@@ -688,18 +749,21 @@ async function* decodeRecords(
           summary.pathCount++;
           summary.opCount++;
           if (envelope.tag === RecordTag.Rename) {
-            const value = parseObject(payload, 'rename', ['from', 'to']);
+            const value = parseObject(payload, 'rename', ['from', 'to'], ['expect', 'expectTo']);
             const from = ownedPaths.claim(canonicalPath(value.from, 'rename source'));
             const to = ownedPaths.claim(canonicalPath(value.to, 'rename target'));
-            yield { type: 'rename', from, to };
+            yield { type: 'rename', from, to, ...expectations(value, 'rename') };
           } else if (envelope.tag === RecordTag.Truncate) {
             const value = parseObject(payload, 'truncate', ['path', 'size']);
             yield { type: 'truncate', path: ownedPaths.claim(canonicalPath(value.path, 'truncate path')), size: safeInteger(value.size, 'truncate size') };
           } else {
-            const value = parseObject(payload, 'setattr', ['path'], ['mode', 'uid', 'gid', 'atime', 'mtime']);
+            const value = parseObject(payload, 'setattr', ['path'], ['mode', 'uid', 'gid', 'atime', 'mtime', 'description', 'expect']);
             const path = ownedPaths.claim(canonicalPath(value.path, 'setattr path'));
-            const { path: _path, ...attrs } = value;
-            yield { type: 'setattr', path, attrs: parseAttrs(attrs, 'setattr') };
+            const { path: _path, description, expect: _expect, ...attrs } = value;
+            yield {
+              type: 'setattr', path, attrs: parseAttrs(attrs, 'setattr'),
+              ...(description === undefined ? {} : { description: descriptionId(description, 'setattr description') }), ...expectations(value, 'setattr'),
+            };
           }
           break;
         }
@@ -768,7 +832,7 @@ async function* encodeRecords(batchId: string, ops: readonly EncoderOp[]): Async
       case 'rename':
         state.summary.pathCount++;
         state.summary.opCount++;
-        yield encodeMetadataRecord(RecordTag.Rename, { from: op.from, to: op.to }, state);
+        yield encodeMetadataRecord(RecordTag.Rename, { from: op.from, to: op.to, ...expectations(op, 'rename') }, state);
         break;
       case 'truncate':
         state.summary.pathCount++;
@@ -778,7 +842,7 @@ async function* encodeRecords(batchId: string, ops: readonly EncoderOp[]): Async
       case 'setattr':
         state.summary.pathCount++;
         state.summary.opCount++;
-        yield encodeMetadataRecord(RecordTag.SetAttr, { path: op.path, ...op.attrs }, state);
+        yield encodeMetadataRecord(RecordTag.SetAttr, { path: op.path, ...op.attrs, ...(op.description === undefined ? {} : { description: op.description }), ...expectations(op, 'setattr') }, state);
         break;
       case 'call':
         state.summary.pathCount++;
@@ -812,8 +876,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 +944,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];
 }
 
 /**
@@ -981,11 +1049,16 @@ function prepareOps(payload: BatchWritePayload, batchId: string): EncoderOp[] {
           kind: 'rename',
           from: ownedPaths.claim(canonicalPath(op.from, 'rename source')),
           to: ownedPaths.claim(canonicalPath(op.to, 'rename target')),
+          ...expectations(op, 'rename'),
         };
       case 'truncate':
         return { kind: 'truncate', path: ownedPaths.claim(canonicalPath(op.path, 'truncate path')), size: safeInteger(op.size, 'truncate size') };
       case 'setattr':
-        return { kind: 'setattr', path: ownedPaths.claim(canonicalPath(op.path, 'setattr path')), attrs: parseAttrs(op.attrs as Record<string, unknown>, 'setattr') };
+        return {
+          kind: 'setattr', path: ownedPaths.claim(canonicalPath(op.path, 'setattr path')), attrs: parseAttrs(op.attrs as Record<string, unknown>, 'setattr'),
+          ...(op.description === undefined ? {} : { description: descriptionId(op.description, 'setattr description') }),
+          ...expectations(op, 'setattr'),
+        };
       case 'call': {
         const call = op.call;
         if ('data' in call) {
@@ -1020,11 +1093,18 @@ 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 === 'atime,mtime') return { atime: safeInteger(value.atime, `${label} atime`), mtime: safeInteger(value.mtime, `${label} mtime`) };
+  if (keys === 'gid,uid') return { uid: ownerId(value.uid, `${label} uid`), gid: ownerId(value.gid, `${label} gid`) };
+  if (keys === 'atime,mtime') return { atime: parseFsTime(value.atime, `w7-frame: ${label} atime`), mtime: parseFsTime(value.mtime, `w7-frame: ${label} mtime`) };
   throw new Error(`w7-frame: ${label} changes the mode, the owner or the times, one of them: got ${keys || 'nothing'}`);
 }
 
+/** `value` as an FsTime (a finite number of milliseconds, 'now' or 'omit'); else an error naming `label`. */
+export function parseFsTime(value: unknown, label: string): FsTime {
+  if (value === 'now' || value === 'omit') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  throw new Error(`${label} must be a time: milliseconds, 'now' or 'omit'`);
+}
+
 function parseDelete(bytes: Uint8Array): DeleteMetadata {
   const value = parseObject(bytes, 'delete', ['path']);
   return { path: canonicalPath(value.path, 'delete path') };
@@ -1100,14 +1180,17 @@ function parsePathCall(value: Record<string, unknown>, path: (value: unknown, la
     }
     case 'unlink':
     case 'rmdir':
-      if (keys !== 'call,path') break;
-      return { call: value.call, path: path(value.path, `${value.call} path`) };
+      if (keys !== 'call,path' && keys !== 'call,expect,path') break;
+      return { call: value.call, path: path(value.path, `${value.call} path`), ...expectations(value, value.call) };
     case 'symlink':
       if (keys !== 'call,path,target' && keys !== 'call,ino,path,target') break;
       return {
         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 +1214,28 @@ 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', 'expect', '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') }),
+        ...expectations(value, 'open'),
       };
     }
     case 'lutimes':
@@ -1224,6 +1310,22 @@ function inodeNumber(value: unknown, label: string): number {
   return ino;
 }
 
+/** A record's expectations (W7Expected), checked: `expect`, and a rename's `expectTo`. */
+function expectations(value: { expect?: unknown; expectTo?: unknown }, label: string): { expect?: W7Expected; expectTo?: W7Expected } {
+  const expected = (field: unknown, name: string): W7Expected => {
+    if (field === null) return null;
+    if (isObject(field) && !Array.isArray(field)) {
+      if (Object.keys(field).join(',') !== 'made') throw new Error(`w7-frame: ${label} ${name} is a number, null or { made }`);
+      return { made: descriptionId(field.made, `${label} ${name} made`) };
+    }
+    return inodeNumber(field, `${label} ${name}`);
+  };
+  return {
+    ...(value.expect === undefined ? {} : { expect: expected(value.expect, 'expect') }),
+    ...(value.expectTo === undefined ? {} : { expectTo: expected(value.expectTo, 'expectTo') }),
+  };
+}
+
 function parseObject(
   bytes: Uint8Array,
   label: string,
@@ -1384,15 +1486,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 +1509,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));