superbee 0.4.6-pre.1 → 0.4.6-pre.2

package/dist/publication.mjs

@@ -30844,15 +30844,30 @@ var FrontmatterRefusedError = class extends InvalidInputError {
   }
 };
 var FilesystemIdentityAliasError = class extends InvalidInputError {
+  reason = "filesystem_alias";
   rel;
   segment;
-  constructor(rel, segment) {
+  existing;
+  suggestedPath;
+  /**
+   * `noun` names the existing entry ("folder" or "file"); `index` is the position of `segment`
+   * in `rel`. Both default from the position of the first segment spelled `segment`.
+   */
+  constructor(rel, segment, existing, noun, index2) {
+    const segments = rel.split("/").filter((part) => part !== "" && part !== ".");
+    const at = index2 ?? segments.indexOf(segment);
+    const kind2 = noun ?? (at === segments.length - 1 ? "file" : "folder");
+    const clash = existing === void 0 ? `but a ${kind2} with that name in a different case or Unicode form already exists` : existing.normalize("NFC") === segment.normalize("NFC") ? `but ${kind2} '${existing}' already exists, written in a different Unicode form` : `but ${kind2} '${existing}' already exists`;
+    const difference = existing === void 0 ? "case or Unicode form" : existing.normalize("NFC") === segment.normalize("NFC") ? "Unicode form" : existing.toLowerCase() === segment.toLowerCase() ? "case" : "case and Unicode form";
     super(
-      `Path '${rel}' does not match the exact spelling of an existing filesystem entry at segment '${segment}'; ids that differ only by case or Unicode normalization cannot share one file.`
+      `Path '${rel}' uses ${kind2} '${segment}', ${clash}, and this disk treats names that differ only by ${difference} as the same name. Use the existing spelling.`
     );
     this.name = "FilesystemIdentityAliasError";
     this.rel = rel;
     this.segment = segment;
+    this.existing = existing;
+    const unusable = existing === void 0 || at < 0 || segments[at] !== segment || kind2 === "file" && at < segments.length - 1 || existing.normalize("NFC") === segment.normalize("NFC");
+    this.suggestedPath = unusable ? void 0 : segments.map((part, position2) => position2 === at ? existing : part).join("/");
   }
 };
 var ConcurrentReplacementError = class extends Error {
@@ -31057,6 +31072,9 @@ function delimiterLineEnd(input, offset) {
   if (input[suffix] === "\r" && input[suffix + 1] === "\n") return suffix + 2;
   return null;
 }
+function startsWithFrontmatterSyntax(text4) {
+  return text4.startsWith("\uFEFF") || delimiterLineEnd(text4, 0) !== null;
+}
 function splitLeadingFrontmatter(raw, context) {
   const input = raw.startsWith("\uFEFF") ? raw.slice(1) : raw;
   const openingEnd = delimiterLineEnd(input, 0);
@@ -31162,7 +31180,10 @@ function stringifyWithSerializedFrontmatter(dumped, body) {
   const content3 = body ?? "";
   const newline = (value) => value.endsWith("\n") ? value : `${value}
 `;
-  if (dumped === "{}") return normalizeDocumentBodyForStorage(content3);
+  if (dumped === "{}") {
+    const stored = normalizeDocumentBodyForStorage(content3);
+    return `${startsWithFrontmatterSyntax(stored) ? "---\n---\n" : ""}${stored}`;
+  }
   return `---
 ${newline(dumped)}---
 ${normalizeDocumentBodyForStorage(content3)}`;
@@ -31980,36 +32001,57 @@ function hasSourceIdentity(sources, identity) {
   return Array.isArray(sources) && sources.some((entry) => matchesSourceIdentity(entry, identity));
 }
 
+// ../core/src/skip-reasons.ts
+var PERMISSION_DENIED_PREFIX = "permission denied (";
+function permissionDeniedReason(code2) {
+  return `${PERMISSION_DENIED_PREFIX}${code2})`;
+}
+function isPermissionDeniedSkip(skip) {
+  return skip.reason.startsWith(PERMISSION_DENIED_PREFIX);
+}
+
 // ../core/src/document-scan.ts
 function isEnoent(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
-async function readManyExisting(backend, ids, onMalformed, onAliased) {
-  try {
-    return await backend.readMany(ids);
-  } catch (err) {
-    const malformed = err instanceof MalformedDocumentError && onMalformed !== void 0;
-    const aliased = err instanceof FilesystemIdentityAliasError && onAliased !== void 0;
-    if (!isEnoent(err) && !malformed && !aliased) throw err;
-    const out = [];
-    for (const id of ids) {
-      try {
-        out.push(await backend.read(id));
-      } catch (candidate) {
-        if (isEnoent(candidate)) continue;
-        if (candidate instanceof MalformedDocumentError && onMalformed) {
-          onMalformed({ id, reason: candidate.detail });
-          continue;
-        }
-        if (candidate instanceof FilesystemIdentityAliasError && onAliased) {
-          onAliased({ id, reason: candidate.message });
-          continue;
-        }
-        throw candidate;
+function deniedReason(err) {
+  const code2 = typeof err === "object" && err !== null ? err.code : void 0;
+  return code2 === "EACCES" || code2 === "EPERM" ? permissionDeniedReason(code2) : void 0;
+}
+async function readManyExisting(backend, ids, onMalformed, onAliased, onDenied) {
+  const tolerated = (err) => isEnoent(err) || err instanceof MalformedDocumentError && onMalformed !== void 0 || err instanceof FilesystemIdentityAliasError && onAliased !== void 0 || deniedReason(err) !== void 0 && onDenied !== void 0;
+  const readOne = async (id) => {
+    try {
+      return [await backend.read(id)];
+    } catch (candidate) {
+      if (isEnoent(candidate)) return [];
+      if (candidate instanceof MalformedDocumentError && onMalformed) {
+        onMalformed({ id, reason: candidate.detail });
+        return [];
+      }
+      if (candidate instanceof FilesystemIdentityAliasError && onAliased) {
+        onAliased({ id, reason: candidate.message });
+        return [];
+      }
+      const reason = deniedReason(candidate);
+      if (reason !== void 0 && onDenied) {
+        onDenied({ id, reason });
+        return [];
       }
+      throw candidate;
     }
-    return out;
-  }
+  };
+  const readBatch = async (batch) => {
+    try {
+      return await backend.readMany(batch);
+    } catch (err) {
+      if (!tolerated(err)) throw err;
+      if (batch.length === 1) return readOne(batch[0]);
+      const half = Math.ceil(batch.length / 2);
+      return [...await readBatch(batch.slice(0, half)), ...await readBatch(batch.slice(half))];
+    }
+  };
+  return readBatch(ids);
 }
 
 // ../core/src/engine.ts
@@ -32033,7 +32075,7 @@ async function readDocVersioned(backend, id) {
 async function scanMatching(backend, filter, onSkip) {
   const ids = await backend.list(filter.prefix);
   const results = [];
-  for (const result of await readManyExisting(backend, ids, onSkip)) {
+  for (const result of await readManyExisting(backend, ids, onSkip, void 0, onSkip)) {
     if (matchesFilter(result.doc, filter)) results.push(result);
   }
   results.sort((a, b) => compareCodeUnits(a.doc.id, b.doc.id));
@@ -32158,7 +32200,7 @@ function assertStorableReservedWrite(dir, name, content3) {
 // ../core/src/filesystem-identity.ts
 import { promises as fs2 } from "node:fs";
 import path2 from "node:path";
-import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 
 // ../core/src/filesystem-lock.ts
 import { promises as fs, realpathSync } from "node:fs";
@@ -32213,6 +32255,8 @@ import { createHash, randomUUID } from "node:crypto";
 var OWNER_FILE = "owner.json";
 var DEFAULT_WAIT_MS = 5e3;
 var DEFAULT_POLL_MS = 25;
+var UNREADABLE_OWNER_POLL_MS = 2e3;
+var ABANDONED_CLAIM_AGE_MS = 2e3;
 var FilesystemMutationLockError = class extends Error {
   lockPath;
   owner;
@@ -32300,9 +32344,13 @@ async function readOwnerRecord(lockPath) {
   return owner === null ? { state: "absent" } : { state: "record", owner };
 }
 async function resolveOwnerRecord(lockPath, started, waitMs, pollMs) {
+  let firstUnreadable;
   while (true) {
     const record3 = await readOwnerRecord(lockPath);
-    if (record3.state !== "unreadable" || Date.now() - started >= waitMs) return record3;
+    if (record3.state !== "unreadable") return record3;
+    const now = Date.now();
+    firstUnreadable ??= now;
+    if (now - started >= waitMs || now - firstUnreadable >= UNREADABLE_OWNER_POLL_MS) return record3;
     await delay(pollMs);
   }
 }
@@ -32353,6 +32401,17 @@ async function quarantineStaleLock(lockPath, owner, policy) {
     throw err;
   }
 }
+async function removeAbandonedClaim(lockPath) {
+  try {
+    const info = await fs.lstat(lockPath);
+    const age = Date.now() - info.mtimeMs;
+    if (!info.isDirectory() || age < ABANDONED_CLAIM_AGE_MS) return false;
+    await fs.rmdir(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -32403,7 +32462,7 @@ async function timeoutError(lockPath, snapshot, guarded) {
   const sameHost = owner?.hostname === hostname();
   let message;
   if (malformed) {
-    message = `timed out waiting for filesystem mutation lock '${lockPath}'; its owner metadata is missing or malformed. Inspect and remove the lock only after confirming no process is mutating the target, then retry.`;
+    message = `timed out waiting for filesystem mutation lock '${lockPath}'; its owner metadata is missing or malformed. Remove the lock directory once no Superbee process is running, then retry.`;
   } else if (stale) {
     message = `stale filesystem mutation lock '${lockPath}' belongs to absent PID ${owner.pid} on ${owner.hostname}. Inspect and remove the lock, then retry.`;
   } else if (!sameHost) {
@@ -32452,7 +32511,9 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
       } else {
         unwitnessedRetryUsed = false;
       }
-      let existingOwner = await readOwner(lockPath);
+      const existing = await readOwnerRecord(lockPath);
+      let existingOwner = existing.state === "record" ? existing.owner : null;
+      if (existing.state === "absent" && await removeAbandonedClaim(lockPath)) continue;
       if (existingOwner !== null) {
         if (await quarantineStaleLock(lockPath, existingOwner, policy)) continue;
         existingOwner = await readOwner(lockPath);
@@ -32472,14 +32533,13 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
       });
     } catch (err) {
       const code2 = err.code;
-      if (code2 === "EEXIST") {
+      if (code2 === "EEXIST" || code2 === "ENOENT" || code2 === "ENOTDIR" || await claimDirectoryLost(lockPath, claimed)) {
         heldTokens.delete(owner.token);
         continue;
       }
       await rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy).catch(() => {
       });
       heldTokens.delete(owner.token);
-      if (code2 === "ENOENT" || code2 === "ENOTDIR") continue;
       throw err;
     }
     let inFlight;
@@ -32509,9 +32569,18 @@ async function rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy
     return;
   }
   if (record3.state === "unreadable" || !await isClaimedDirectory(lockPath, claimed)) return;
-  const remnant = releasedLockRemnantPath(lockPath, owner);
-  await fs.rename(lockPath, remnant);
-  await fs.rm(remnant, { recursive: true, force: true });
+  await fs.rmdir(lockPath);
+}
+async function claimDirectoryLost(lockPath, claimed) {
+  try {
+    const current = await fs.lstat(lockPath, { bigint: true });
+    if (claimed === null) return false;
+    const reborn = claimed.birthtimeNs > 0n && current.birthtimeNs > 0n && current.birthtimeNs !== claimed.birthtimeNs;
+    return current.dev !== claimed.dev || current.ino !== claimed.ino || reborn;
+  } catch (err) {
+    const code2 = err.code;
+    return code2 === "ENOENT" || code2 === "ENOTDIR";
+  }
 }
 async function isClaimedDirectory(lockPath, claimed) {
   if (claimed === null || claimed.birthtimeNs <= 0n) return false;
@@ -32613,6 +32682,12 @@ function foldSegment(segment) {
   return segment.normalize("NFKD").toLowerCase().toUpperCase().toLowerCase();
 }
 
+// ../core/src/filesystem-temp-name.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+function identityTempName(leaf) {
+  return `.${leaf}.${process.pid}.${Date.now()}.${randomUUID2()}.tmp`;
+}
+
 // ../core/src/filesystem-identity.ts
 async function replaceExistingLeaf(port, tmp, target, rel) {
   try {
@@ -32757,10 +32832,32 @@ async function probeSegment(port, candidate, rel, segment) {
 function hasExact(listing, segment) {
   return listing.some((entry) => entry.name === segment);
 }
+function existingSpelling(names, segment) {
+  const folded = foldSegment(segment);
+  const matches = [...names].filter((name) => name !== segment && foldSegment(name) === folded);
+  return matches.length === 1 ? matches[0] : void 0;
+}
+function entryNoun(kind2, leaf) {
+  if (kind2 === void 0) return leaf ? "file" : "folder";
+  return kind2 === "directory" ? "folder" : "file";
+}
+function aliasRefusal(rel, segments, index2, names, kind2) {
+  const segment = segments[index2];
+  return new FilesystemIdentityAliasError(rel, segment, existingSpelling(names, segment), entryNoun(kind2, index2 === segments.length - 1), index2);
+}
+function aliasRefusalFromListing(rel, index2, listing, leaf) {
+  const segment = relSegments(rel)[index2];
+  const existing = existingSpelling(listing.map((entry) => entry.name), segment);
+  const kind2 = existing === void 0 ? void 0 : listing.find((entry) => entry.name === existing)?.kind;
+  return new FilesystemIdentityAliasError(rel, segment, existing, entryNoun(kind2, leaf), index2);
+}
+function listingView(names) {
+  return { has: (name) => names.has(name), names: () => names };
+}
 function freshListings(port) {
   return async (dir) => {
     const listing = await port.entries(dir);
-    return listing === null ? null : { has: (name) => hasExact(listing, name) };
+    return listing === null ? null : { has: (name) => hasExact(listing, name), names: () => listing.map((entry) => entry.name) };
   };
 }
 async function walkExact(port, rootResolved, segments, rel) {
@@ -32772,7 +32869,7 @@ async function walkExact(port, rootResolved, segments, rel) {
     if (probed === null) return { state: "absent", depth: index2 };
     const listing = await port.entries(parent);
     if (listing === null) return { state: "absent", depth: index2 };
-    if (!hasExact(listing, segment)) throw new FilesystemIdentityAliasError(rel, segment);
+    if (!hasExact(listing, segment)) throw aliasRefusal(rel, segments, index2, listing.map((entry) => entry.name), probed.kind);
     if (index2 === segments.length - 1) return { state: "exact", leaf: probed };
     if (probed.kind !== "directory") return { state: "shape-mismatch", segment };
     parent = candidate;
@@ -32787,35 +32884,53 @@ async function recordWalk(port, rootResolved, segments, rel) {
     const segment = segments[index2];
     const candidate = path2.join(parent, segment);
     const probed = await probeSegment(port, candidate, rel, segment);
-    if (probed === null) return null;
-    if (index2 < segments.length - 1 && probed.kind !== "directory") return null;
+    if (probed === null) return { recorded, complete: false };
     recorded.push(probed);
+    if (index2 < segments.length - 1 && probed.kind !== "directory") return { recorded, complete: false };
     parent = candidate;
   }
-  return recorded;
+  return { recorded, complete: true };
 }
-async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle, listings = freshListings(port)) {
+async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle, listings = freshListings(port), stopAt = segments.length) {
   let parent = rootResolved;
-  for (let index2 = 0; index2 < segments.length; index2++) {
+  for (let index2 = 0; index2 < stopAt; index2++) {
     const segment = segments[index2];
     const candidate = path2.join(parent, segment);
     const listing = await listings(parent);
     if (listing === null) return "absent";
     const listed = listing.has(segment);
     if (handle !== null && index2 === segments.length - 1) {
-      const verdict = classifyLeaf({ listed, probe: await probeSegment(port, candidate, rel, segment), handle });
-      if (verdict === "aliased") throw new FilesystemIdentityAliasError(rel, segment);
+      const probe = await probeSegment(port, candidate, rel, segment);
+      const verdict = classifyLeaf({ listed, probe, handle });
+      if (verdict === "aliased") throw aliasRefusal(rel, segments, index2, listing.names(), probe?.kind);
       return verdict === "replaced" ? "restart" : verdict;
     }
     if (index2 < segments.length - 1 || !listed) {
-      const verdict = confirmAlias(listed, await probeSegment(port, candidate, rel, segment), recorded[index2]);
-      if (verdict === "aliased") throw new FilesystemIdentityAliasError(rel, segment);
+      const probe = await probeSegment(port, candidate, rel, segment);
+      const verdict = confirmAlias(listed, probe, recorded[index2]);
+      if (verdict === "aliased") throw aliasRefusal(rel, segments, index2, listing.names(), probe?.kind);
       if (verdict !== "continue") return verdict;
     }
     parent = candidate;
   }
   return "continue";
 }
+async function confirmPrefix(port, rootResolved, segments, rel, recorded) {
+  if (recorded.length === 0) return "absent";
+  let kept = prefixListings.get(port);
+  if (kept === void 0) prefixListings.set(port, kept = /* @__PURE__ */ new Map());
+  const cached = witnessedListings(port, kept, Date.now, PREFIX_LISTING_CAPACITY);
+  let verdict;
+  try {
+    verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, null, cached.source, recorded.length);
+  } catch (error) {
+    if (!cached.reused()) throw error;
+    kept.clear();
+    verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, null, freshListings(port), recorded.length);
+  }
+  if (verdict === "restart" && cached.reused()) kept.clear();
+  return verdict === "restart" ? "restart" : "absent";
+}
 function countRestart(restarts, rel) {
   if (restarts >= MAX_RESTARTS) throw new ConcurrentReplacementError(rel, restarts + 1);
   return restarts + 1;
@@ -32827,8 +32942,14 @@ async function observeWith(port, rootResolved, rel, read, listings, onExact) {
   const segments = relSegments(rel);
   const target = path2.join(rootResolved, ...segments);
   for (let restarts = 0; ; ) {
-    const recorded = await recordWalk(port, rootResolved, segments, rel);
-    if (recorded === null) return { state: "absent" };
+    const walk = await recordWalk(port, rootResolved, segments, rel);
+    if (!walk.complete) {
+      const prefix = await confirmPrefix(port, rootResolved, segments, rel, walk.recorded);
+      if (prefix === "absent") return { state: "absent" };
+      restarts = countRestart(restarts, rel);
+      continue;
+    }
+    const recorded = walk.recorded;
     const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null, listings);
     if (verified === "absent") return { state: "absent" };
     if (verified === "restart") {
@@ -32867,8 +32988,14 @@ async function probeExact(port, root, rel) {
   const segments = relSegments(rel);
   const rootResolved = path2.resolve(root);
   for (let restarts = 0; ; ) {
-    const recorded = await recordWalk(port, rootResolved, segments, rel);
-    if (recorded === null) return { state: "absent" };
+    const walk = await recordWalk(port, rootResolved, segments, rel);
+    if (!walk.complete) {
+      const prefix = await confirmPrefix(port, rootResolved, segments, rel, walk.recorded);
+      if (prefix === "absent") return { state: "absent" };
+      restarts = countRestart(restarts, rel);
+      continue;
+    }
+    const recorded = walk.recorded;
     const leaf = recorded[recorded.length - 1];
     const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null);
     const verdict = verified === "continue" ? await confirmedWalk(port, rootResolved, segments, rel, recorded, leaf) : verified;
@@ -32878,45 +33005,56 @@ async function probeExact(port, root, rel) {
   }
 }
 var SETTLED_AFTER_NS = 3000000000n;
+function witnessCanDetectChange(witness) {
+  return witness.mtimeNs > 0n && witness.ctimeNs > 0n;
+}
 function witnessKey(witness) {
   return `${witness.dev}:${witness.ino}:${witness.mtimeNs}:${witness.ctimeNs}`;
 }
-function openObservationPass(port, root, now = Date.now) {
-  const rootResolved = path2.resolve(root);
-  const kept = /* @__PURE__ */ new Map();
-  const reusedVerdicts = [];
-  const fresh = freshListings(port);
-  const witnessOf = port.directoryWitness?.bind(port);
+function witnessedListings(port, kept, now, capacity = Infinity) {
+  let reused = false;
+  const portWitness = port.directoryWitness?.bind(port);
+  if (portWitness === void 0) return { source: freshListings(port), reused: () => false };
+  const witnessOf = async (dir) => {
+    const witness = await portWitness(dir);
+    return witness !== null && witnessCanDetectChange(witness) ? witness : null;
+  };
   const settled = (witness) => {
     const nowNs = BigInt(Math.floor(now())) * 1000000n;
     const latest = witness.mtimeNs > witness.ctimeNs ? witness.mtimeNs : witness.ctimeNs;
     return nowNs - latest >= SETTLED_AFTER_NS;
   };
-  const listingsFor = () => {
-    let reused = false;
-    if (witnessOf === void 0) return { source: fresh, reused: () => false };
-    const source = async (dir) => {
-      const keep = kept.get(dir);
-      if (keep !== void 0) {
-        const current = await witnessOf(dir);
-        if (current !== null && witnessKey(current) === keep.witness) {
-          reused = true;
-          return keep.names;
-        }
-        kept.delete(dir);
-      }
-      const before = await witnessOf(dir);
-      const listing = await port.entries(dir);
-      if (listing === null) return null;
-      const names = new Set(listing.map((entry) => entry.name));
-      const after = await witnessOf(dir);
-      if (before !== null && after !== null && witnessKey(before) === witnessKey(after) && settled(after)) {
-        kept.set(dir, { witness: witnessKey(after), names });
-      }
-      return names;
-    };
-    return { source, reused: () => reused };
+  const source = async (dir) => {
+    const keep = kept.get(dir);
+    if (keep !== void 0) {
+      const current = await witnessOf(dir);
+      if (current !== null && witnessKey(current) === keep.witness) {
+        reused = true;
+        return listingView(keep.names);
+      }
+      kept.delete(dir);
+    }
+    const before = await witnessOf(dir);
+    const listing = await port.entries(dir);
+    if (listing === null) return null;
+    const names = new Set(listing.map((entry) => entry.name));
+    const after = await witnessOf(dir);
+    if (before !== null && after !== null && witnessKey(before) === witnessKey(after) && settled(after)) {
+      kept.delete(dir);
+      kept.set(dir, { witness: witnessKey(after), names });
+      while (kept.size > capacity) kept.delete(kept.keys().next().value);
+    }
+    return listingView(names);
   };
+  return { source, reused: () => reused };
+}
+var prefixListings = /* @__PURE__ */ new WeakMap();
+var PREFIX_LISTING_CAPACITY = 64;
+function openObservationPass(port, root, now = Date.now) {
+  const rootResolved = path2.resolve(root);
+  const kept = /* @__PURE__ */ new Map();
+  const reusedVerdicts = [];
+  const listingsFor = () => witnessedListings(port, kept, now);
   return {
     async observe(rel, read) {
       const listings = listingsFor();
@@ -33019,7 +33157,7 @@ async function readWhole(port, target) {
     await port.close(opened.handle);
   }
 }
-async function mkdirExact(port, parent, segment, isTail, rel) {
+async function mkdirExact(port, parent, segment, isTail, rel, index2 = -1) {
   const outcome = await port.mkdir(path2.join(parent, segment));
   if (outcome === "created") return;
   const listing = await port.entries(parent);
@@ -33028,7 +33166,9 @@ async function mkdirExact(port, parent, segment, isTail, rel) {
     throw new FilesystemSymlinkEntryError(rel, segment);
   }
   const verdict = classifyMkdir(outcome, listing, segment, isTail);
-  if (verdict === "aliased") throw new FilesystemIdentityAliasError(rel, segment);
+  if (verdict === "aliased") {
+    throw aliasRefusalFromListing(rel, index2, listing, false);
+  }
   if (verdict === "shape-mismatch") throw new FilesystemShapeMismatchError(rel, segment);
 }
 async function ensureExactDirectories(port, rootResolved, segments, existingDepth, rel) {
@@ -33048,8 +33188,9 @@ async function ensureExactDirectories(port, rootResolved, segments, existingDept
     }
   }
   let parent = path2.join(rootResolved, ...segments.slice(0, existingDepth));
-  for (const segment of segments.slice(existingDepth, -1)) {
-    await mkdirExact(port, parent, segment, false, rel);
+  for (let index2 = existingDepth; index2 < segments.length - 1; index2++) {
+    const segment = segments[index2];
+    await mkdirExact(port, parent, segment, false, rel, index2);
     parent = path2.join(parent, segment);
   }
 }
@@ -33067,7 +33208,7 @@ async function createExactLeaf(port, tmp, target, rel, leaf, rootResolved) {
   }
   const listing = await port.entries(path2.dirname(target)) ?? [];
   if (hasExact(listing, leaf)) throw new ConcurrentReplacementError(rel, 1);
-  throw new FilesystemIdentityAliasError(rel, leaf);
+  throw aliasRefusalFromListing(rel, relSegments(rel).length - 1, listing, true);
 }
 async function mutateExact(port, root, rel, body) {
   const segments = relSegments(rel);
@@ -33089,11 +33230,13 @@ async function mutateExact(port, root, rel, body) {
         async replace(bytes) {
           await ensureExactDirectories(port, rootResolved, segments, existingDepth, rel);
           const dir = path2.dirname(target);
-          const tmpName = `.${leaf}.${process.pid}.${Date.now()}.${randomUUID2()}.tmp`;
+          const tmpName = identityTempName(leaf);
           const tmp = path2.join(dir, tmpName);
           await port.writeTemp(dir, tmpName, bytes);
           try {
             if (realized.state === "exact") {
+              await port.copyMode?.(target, tmp).catch(() => {
+              });
               await replaceExistingLeaf(port, tmp, target, rel);
               return;
             }
@@ -33253,6 +33396,9 @@ function createNodeFilesystemIdentityPort(hostPolicy) {
     async rename(from, to) {
       await fs2.rename(from, to);
     },
+    async copyMode(from, to) {
+      await fs2.chmod(to, (await fs2.lstat(from)).mode & 511);
+    },
     async unlink(target) {
       await fs2.unlink(target);
     },
@@ -33275,6 +33421,7 @@ function blobVersion(bytes) {
 
 // ../core/src/backend.ts
 var publicationContexts = /* @__PURE__ */ new WeakMap();
+var fileMutations = /* @__PURE__ */ new WeakMap();
 function firstString(...vals) {
   for (const v of vals) {
     if (typeof v === "string" && v.trim() !== "") return v;
@@ -33391,6 +33538,7 @@ var FilesystemBackend = class _FilesystemBackend {
     this.#root = path3.resolve(root);
     this.#coordinator = createFilesystemMutationCoordinator(this.#port, this.#root, options.hostPolicy);
     publicationContexts.set(this, { root: this.#root, port: this.#port });
+    fileMutations.set(this, (rel, body) => this.#mutateExact(rel, body));
   }
   async read(id) {
     return this.#readWithEdition(id, () => this.#readEdition());
@@ -33776,6 +33924,7 @@ var KIND_FIELD_TYPE_SET = new Set(KIND_FIELD_TYPES);
 function isKindFieldType(value) {
   return typeof value === "string" && KIND_FIELD_TYPE_SET.has(value);
 }
+var UNDECLARED_FIELDS_POLICIES = ["warn", "error"];
 function buildKindRegistry(docs, initialWarnings = [], options = {}) {
   const accepted = /* @__PURE__ */ new Map();
   const warnings = [...initialWarnings];
@@ -34370,6 +34519,19 @@ function parseConventionDoc(doc, options = {}) {
       });
     }
   }
+  let undeclaredFields;
+  if (fm.undeclared_fields !== void 0) {
+    if (UNDECLARED_FIELDS_POLICIES.includes(fm.undeclared_fields)) {
+      undeclaredFields = fm.undeclared_fields;
+    } else {
+      warnings.push({
+        code: "KIND_CONVENTION_BAD_SHAPE",
+        message: `kind convention '${doc.id}' has an invalid 'undeclared_fields' (${describeShape(fm.undeclared_fields)}; expected warn or error); using warn.`,
+        field: "undeclared_fields",
+        severity: "warning"
+      });
+    }
+  }
   const kind2 = {
     id: doc.id,
     title,
@@ -34387,6 +34549,7 @@ function parseConventionDoc(doc, options = {}) {
   if (browseCollapsed !== void 0) kind2.browseCollapsed = browseCollapsed;
   if (order !== void 0) kind2.order = order;
   if (claim !== void 0) kind2.claim = claim;
+  if (undeclaredFields !== void 0) kind2.undeclaredFields = undeclaredFields;
   if (Object.hasOwn(fm, "deprecated")) {
     kind2.deprecated = parseKindDeprecation(fm.deprecated, kind2, RESERVED_KIND_FIELD_NAMES, claimCoordinates(options.okfVersion, kind2)?.fields ?? []);
     warnings.push(...kind2.deprecated.problems ?? []);
@@ -34463,7 +34626,7 @@ async function loadKinds(bundle) {
   const docs = await query2(bundle, { prefix: CONVENTIONS_PREFIX, type: CONVENTION_TYPE }, {
     onSkip: ({ id, reason }) => warnings.push({
       code: "KIND_CONVENTION_MALFORMED",
-      message: `skipped kind convention '${id}' with unparseable frontmatter: ${reason}`,
+      message: isPermissionDeniedSkip({ reason }) ? `skipped kind convention '${id}' that could not be read: ${reason}` : `skipped kind convention '${id}' with unparseable frontmatter: ${reason}`,
       field: id,
       severity: "warning"
     })
@@ -44601,12 +44764,27 @@ var CAPABILITIES = [
 ];
 async function authorizePublicationRoot(requested) {
   const entry = await lstat(requested);
-  if (entry.isSymbolicLink() || !entry.isDirectory()) {
+  if (entry.isSymbolicLink()) {
+    const target = await realpath(requested).catch(() => void 0);
+    if (target === void 0) {
+      throw new PublicationError("INVALID_OBJECT_IDENTITY", `the filesystem publication root ${JSON.stringify(requested)} is a symlink that does not resolve to a directory`, { actual: requested });
+    }
+    throw new PublicationError(
+      "INVALID_OBJECT_IDENTITY",
+      `the filesystem publication root ${JSON.stringify(requested)} is a symlink to ${JSON.stringify(target)}; capture does not follow symlinks, so pass the resolved path (await fs.realpath(root))`,
+      { expected: target, actual: requested }
+    );
+  }
+  if (!entry.isDirectory()) {
     throw new PublicationError("INVALID_OBJECT_IDENTITY", "the filesystem publication root must be a real directory");
   }
   const canonical2 = await realpath(requested);
   if (canonical2 !== requested) {
-    throw new PublicationError("INVALID_OBJECT_IDENTITY", "the filesystem publication root must not be a symlink or aliased path");
+    throw new PublicationError(
+      "INVALID_OBJECT_IDENTITY",
+      `the filesystem publication root ${JSON.stringify(requested)} is not in canonical form (it resolves to ${JSON.stringify(canonical2)}); capture does not follow symlinks or normalize paths, so pass the resolved path (await fs.realpath(root))`,
+      { expected: canonical2, actual: requested }
+    );
   }
   const identity = await stat(requested);
   return { requested, canonical: canonical2, dev: identity.dev, ino: identity.ino };