superbee 0.4.3-pre.1 → 0.4.3-pre.2

package/dist/publication-bridge.mjs

@@ -4040,6 +4040,12 @@ async function probeSegment(port, candidate, rel, segment) {
 function hasExact(listing, segment) {
   return listing.some((entry) => entry.name === segment);
 }
+function freshListings(port) {
+  return async (dir) => {
+    const listing = await port.entries(dir);
+    return listing === null ? null : { has: (name) => hasExact(listing, name) };
+  };
+}
 async function walkExact(port, rootResolved, segments, rel) {
   let parent = rootResolved;
   for (let index = 0; index < segments.length; index++) {
@@ -4071,14 +4077,14 @@ async function recordWalk(port, rootResolved, segments, rel) {
   }
   return recorded;
 }
-async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle) {
+async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle, listings = freshListings(port)) {
   let parent = rootResolved;
   for (let index = 0; index < segments.length; index++) {
     const segment = segments[index];
     const candidate = path2.join(parent, segment);
-    const listing = await port.entries(parent);
+    const listing = await listings(parent);
     if (listing === null) return "absent";
-    const listed = hasExact(listing, segment);
+    const listed = listing.has(segment);
     if (handle !== null && index === segments.length - 1) {
       const verdict = classifyLeaf({ listed, probe: await probeSegment(port, candidate, rel, segment), handle });
       if (verdict === "aliased") throw new FilesystemIdentityAliasError(rel, segment);
@@ -4098,13 +4104,15 @@ function countRestart(restarts, rel) {
   return restarts + 1;
 }
 async function observeExact(port, root, rel, read) {
+  return observeWith(port, path2.resolve(root), rel, read, freshListings(port));
+}
+async function observeWith(port, rootResolved, rel, read, listings, onExact) {
   const segments = relSegments(rel);
-  const rootResolved = path2.resolve(root);
   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 verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null);
+    const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null, listings);
     if (verified === "absent") return { state: "absent" };
     if (verified === "restart") {
       restarts = countRestart(restarts, rel);
@@ -4126,11 +4134,14 @@ async function observeExact(port, root, rel, read) {
     try {
       value = await read(opened.handle, target);
       if (value === null) return { state: "absent" };
-      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened);
+      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened, listings);
     } finally {
       await port.close(opened.handle);
     }
-    if (verdict === "exact") return { state: "exact", value };
+    if (verdict === "exact") {
+      onExact?.(recorded, { dev: opened.dev, ino: opened.ino });
+      return { state: "exact", value };
+    }
     if (verdict === "absent") return { state: "absent" };
     restarts = countRestart(restarts, rel);
   }
@@ -4149,6 +4160,100 @@ async function probeExact(port, root, rel) {
     restarts = countRestart(restarts, rel);
   }
 }
+var SETTLED_AFTER_NS = 3000000000n;
+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);
+  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 };
+  };
+  return {
+    async observe(rel, read) {
+      const listings = listingsFor();
+      let exact;
+      let observed;
+      try {
+        observed = await observeWith(port, rootResolved, rel, read, listings.source, (recorded, handle) => {
+          exact = { rel, segments: relSegments(rel), recorded, handle };
+        });
+      } catch (error) {
+        if (!listings.reused()) throw error;
+        return observeExact(port, rootResolved, rel, read);
+      }
+      if (!listings.reused()) return observed;
+      if (observed.state === "absent") return observeExact(port, rootResolved, rel, read);
+      if (exact !== void 0) reusedVerdicts.push(exact);
+      return observed;
+    },
+    async finish() {
+      const retry = /* @__PURE__ */ new Set();
+      const endListings = /* @__PURE__ */ new Map();
+      const listedAtEnd = async (dir) => {
+        if (!endListings.has(dir)) {
+          const listing = await port.entries(dir);
+          endListings.set(dir, listing === null ? null : new Set(listing.map((entry) => entry.name)));
+        }
+        return endListings.get(dir);
+      };
+      try {
+        for (const verdict of reusedVerdicts) {
+          if (!await holdsAtEnd(port, rootResolved, verdict, listedAtEnd)) retry.add(verdict.rel);
+        }
+      } finally {
+        kept.clear();
+        reusedVerdicts.length = 0;
+      }
+      return [...retry];
+    }
+  };
+}
+async function holdsAtEnd(port, rootResolved, verdict, listedAtEnd) {
+  let parent = rootResolved;
+  for (let index = 0; index < verdict.segments.length; index++) {
+    const segment = verdict.segments[index];
+    const listing = await listedAtEnd(parent);
+    if (listing === null || !listing.has(segment)) return false;
+    const candidate = path2.join(parent, segment);
+    const probed = await port.probe(candidate);
+    const expected = index === verdict.segments.length - 1 ? verdict.handle : verdict.recorded[index];
+    if (probed === null || probed.kind === "symlink" || !sameWitness(probed, expected)) return false;
+    parent = candidate;
+  }
+  return true;
+}
 var linkUnsupportedRoots = /* @__PURE__ */ new WeakMap();
 function unsupportedLinkRoots(port) {
   let roots = linkUnsupportedRoots.get(port);
@@ -4302,8 +4407,56 @@ function kindOf(stats) {
   if (stats.isFile()) return "file";
   return "other";
 }
+var LOCAL_LINUX_FILESYSTEMS = /* @__PURE__ */ new Set([
+  61267,
+  // ext2/3/4
+  1481003842,
+  // xfs
+  2435016766,
+  // btrfs
+  16914836,
+  // tmpfs
+  2240043254,
+  // ramfs
+  2035054128,
+  // overlayfs
+  801189825,
+  // zfs
+  4076150800,
+  // f2fs
+  3393526350,
+  // bcachefs
+  19780,
+  // vfat
+  538032816,
+  // exfat
+  1936094318,
+  // ntfs3
+  18475
+  // hfsplus
+]);
+function directoryWitnessTrusted(platform, filesystemType) {
+  if (platform !== "linux") return true;
+  return filesystemType !== null && LOCAL_LINUX_FILESYSTEMS.has(filesystemType);
+}
+function witnessTrust() {
+  const devices = /* @__PURE__ */ new Map();
+  return (dev, dir) => {
+    if (process.platform !== "linux") return Promise.resolve(true);
+    let trusted = devices.get(dev);
+    if (trusted === void 0) {
+      trusted = fs2.statfs(dir).then(
+        (info) => directoryWitnessTrusted("linux", Number(info.type)),
+        () => false
+      );
+      devices.set(dev, trusted);
+    }
+    return trusted;
+  };
+}
 function createNodeFilesystemIdentityPort(hostPolicy) {
   const policy = captureFilesystemHostPolicy(hostPolicy);
+  const witnessTrustedOn = witnessTrust();
   return Object.freeze({
     isTransientOpenError: policy.isTransientOpenError,
     isReplacementConflict: policy.isReplacementConflict,
@@ -4326,6 +4479,17 @@ function createNodeFilesystemIdentityPort(hostPolicy) {
         throw err;
       }
     },
+    async directoryWitness(dir) {
+      let stats;
+      try {
+        stats = await fs2.stat(dir, { bigint: true });
+      } catch (err) {
+        if (isAbsentPathError(err)) return null;
+        throw err;
+      }
+      if (!await witnessTrustedOn(stats.dev, dir)) return null;
+      return { dev: stats.dev, ino: stats.ino, mtimeNs: stats.mtimeNs, ctimeNs: stats.ctimeNs };
+    },
     async open(target) {
       const handle = await fs2.open(target, "r");
       try {
@@ -4636,10 +4800,11 @@ var FilesystemBackend = class _FilesystemBackend {
       return void 0;
     }
   }
-  async #readWithEdition(id, edition) {
+  async #readWithEdition(id, edition, pass) {
     assertSafeConceptId(id);
     const rel = pathFromConceptId(id);
-    const observed = await observeExact(this.#port, this.#root, rel, (handle) => readBytes(this.#port, handle));
+    const read = (handle) => readBytes(this.#port, handle);
+    const observed = pass ? await pass.observe(rel, read) : await observeExact(this.#port, this.#root, rel, read);
     if (observed.state === "absent") throw notFound(this.#root, rel);
     const raw = observed.value.toString("utf8");
     const { frontmatter: frontmatter2, body } = parseMarkdown(raw, rel, { okfVersion: await edition() });
@@ -4654,7 +4819,12 @@ var FilesystemBackend = class _FilesystemBackend {
     }
     let editionPromise;
     const edition = () => editionPromise ??= this.#readEdition();
-    for (const id of ids) out.push(await this.#readWithEdition(id, edition));
+    const pass = openObservationPass(this.#port, this.#root);
+    for (const id of ids) out.push(await this.#readWithEdition(id, edition, pass));
+    const retry = new Set(await pass.finish());
+    for (let index = 0; index < ids.length; index++) {
+      if (retry.has(pathFromConceptId(ids[index]))) out[index] = await this.#readWithEdition(ids[index], edition);
+    }
     return out;
   }
   async write(id, doc, options = {}) {

package/dist/publication.mjs

@@ -31994,6 +31994,12 @@ async function probeSegment(port, candidate, rel, segment) {
 function hasExact(listing, segment) {
   return listing.some((entry) => entry.name === segment);
 }
+function freshListings(port) {
+  return async (dir) => {
+    const listing = await port.entries(dir);
+    return listing === null ? null : { has: (name) => hasExact(listing, name) };
+  };
+}
 async function walkExact(port, rootResolved, segments, rel) {
   let parent = rootResolved;
   for (let index2 = 0; index2 < segments.length; index2++) {
@@ -32025,14 +32031,14 @@ async function recordWalk(port, rootResolved, segments, rel) {
   }
   return recorded;
 }
-async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle) {
+async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle, listings = freshListings(port)) {
   let parent = rootResolved;
   for (let index2 = 0; index2 < segments.length; index2++) {
     const segment = segments[index2];
     const candidate = path2.join(parent, segment);
-    const listing = await port.entries(parent);
+    const listing = await listings(parent);
     if (listing === null) return "absent";
-    const listed = hasExact(listing, segment);
+    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);
@@ -32052,13 +32058,15 @@ function countRestart(restarts, rel) {
   return restarts + 1;
 }
 async function observeExact(port, root, rel, read) {
+  return observeWith(port, path2.resolve(root), rel, read, freshListings(port));
+}
+async function observeWith(port, rootResolved, rel, read, listings, onExact) {
   const segments = relSegments(rel);
-  const rootResolved = path2.resolve(root);
   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 verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null);
+    const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null, listings);
     if (verified === "absent") return { state: "absent" };
     if (verified === "restart") {
       restarts = countRestart(restarts, rel);
@@ -32080,11 +32088,14 @@ async function observeExact(port, root, rel, read) {
     try {
       value = await read(opened.handle, target);
       if (value === null) return { state: "absent" };
-      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened);
+      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened, listings);
     } finally {
       await port.close(opened.handle);
     }
-    if (verdict === "exact") return { state: "exact", value };
+    if (verdict === "exact") {
+      onExact?.(recorded, { dev: opened.dev, ino: opened.ino });
+      return { state: "exact", value };
+    }
     if (verdict === "absent") return { state: "absent" };
     restarts = countRestart(restarts, rel);
   }
@@ -32103,6 +32114,100 @@ async function probeExact(port, root, rel) {
     restarts = countRestart(restarts, rel);
   }
 }
+var SETTLED_AFTER_NS = 3000000000n;
+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);
+  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 };
+  };
+  return {
+    async observe(rel, read) {
+      const listings = listingsFor();
+      let exact;
+      let observed;
+      try {
+        observed = await observeWith(port, rootResolved, rel, read, listings.source, (recorded, handle) => {
+          exact = { rel, segments: relSegments(rel), recorded, handle };
+        });
+      } catch (error) {
+        if (!listings.reused()) throw error;
+        return observeExact(port, rootResolved, rel, read);
+      }
+      if (!listings.reused()) return observed;
+      if (observed.state === "absent") return observeExact(port, rootResolved, rel, read);
+      if (exact !== void 0) reusedVerdicts.push(exact);
+      return observed;
+    },
+    async finish() {
+      const retry = /* @__PURE__ */ new Set();
+      const endListings = /* @__PURE__ */ new Map();
+      const listedAtEnd = async (dir) => {
+        if (!endListings.has(dir)) {
+          const listing = await port.entries(dir);
+          endListings.set(dir, listing === null ? null : new Set(listing.map((entry) => entry.name)));
+        }
+        return endListings.get(dir);
+      };
+      try {
+        for (const verdict of reusedVerdicts) {
+          if (!await holdsAtEnd(port, rootResolved, verdict, listedAtEnd)) retry.add(verdict.rel);
+        }
+      } finally {
+        kept.clear();
+        reusedVerdicts.length = 0;
+      }
+      return [...retry];
+    }
+  };
+}
+async function holdsAtEnd(port, rootResolved, verdict, listedAtEnd) {
+  let parent = rootResolved;
+  for (let index2 = 0; index2 < verdict.segments.length; index2++) {
+    const segment = verdict.segments[index2];
+    const listing = await listedAtEnd(parent);
+    if (listing === null || !listing.has(segment)) return false;
+    const candidate = path2.join(parent, segment);
+    const probed = await port.probe(candidate);
+    const expected = index2 === verdict.segments.length - 1 ? verdict.handle : verdict.recorded[index2];
+    if (probed === null || probed.kind === "symlink" || !sameWitness(probed, expected)) return false;
+    parent = candidate;
+  }
+  return true;
+}
 var linkUnsupportedRoots = /* @__PURE__ */ new WeakMap();
 function unsupportedLinkRoots(port) {
   let roots = linkUnsupportedRoots.get(port);
@@ -32256,8 +32361,56 @@ function kindOf(stats) {
   if (stats.isFile()) return "file";
   return "other";
 }
+var LOCAL_LINUX_FILESYSTEMS = /* @__PURE__ */ new Set([
+  61267,
+  // ext2/3/4
+  1481003842,
+  // xfs
+  2435016766,
+  // btrfs
+  16914836,
+  // tmpfs
+  2240043254,
+  // ramfs
+  2035054128,
+  // overlayfs
+  801189825,
+  // zfs
+  4076150800,
+  // f2fs
+  3393526350,
+  // bcachefs
+  19780,
+  // vfat
+  538032816,
+  // exfat
+  1936094318,
+  // ntfs3
+  18475
+  // hfsplus
+]);
+function directoryWitnessTrusted(platform, filesystemType) {
+  if (platform !== "linux") return true;
+  return filesystemType !== null && LOCAL_LINUX_FILESYSTEMS.has(filesystemType);
+}
+function witnessTrust() {
+  const devices = /* @__PURE__ */ new Map();
+  return (dev, dir) => {
+    if (process.platform !== "linux") return Promise.resolve(true);
+    let trusted = devices.get(dev);
+    if (trusted === void 0) {
+      trusted = fs2.statfs(dir).then(
+        (info) => directoryWitnessTrusted("linux", Number(info.type)),
+        () => false
+      );
+      devices.set(dev, trusted);
+    }
+    return trusted;
+  };
+}
 function createNodeFilesystemIdentityPort(hostPolicy) {
   const policy = captureFilesystemHostPolicy(hostPolicy);
+  const witnessTrustedOn = witnessTrust();
   return Object.freeze({
     isTransientOpenError: policy.isTransientOpenError,
     isReplacementConflict: policy.isReplacementConflict,
@@ -32280,6 +32433,17 @@ function createNodeFilesystemIdentityPort(hostPolicy) {
         throw err;
       }
     },
+    async directoryWitness(dir) {
+      let stats;
+      try {
+        stats = await fs2.stat(dir, { bigint: true });
+      } catch (err) {
+        if (isAbsentPathError(err)) return null;
+        throw err;
+      }
+      if (!await witnessTrustedOn(stats.dev, dir)) return null;
+      return { dev: stats.dev, ino: stats.ino, mtimeNs: stats.mtimeNs, ctimeNs: stats.ctimeNs };
+    },
     async open(target) {
       const handle = await fs2.open(target, "r");
       try {
@@ -32590,10 +32754,11 @@ var FilesystemBackend = class _FilesystemBackend {
       return void 0;
     }
   }
-  async #readWithEdition(id, edition) {
+  async #readWithEdition(id, edition, pass) {
     assertSafeConceptId(id);
     const rel = pathFromConceptId(id);
-    const observed = await observeExact(this.#port, this.#root, rel, (handle) => readBytes(this.#port, handle));
+    const read = (handle) => readBytes(this.#port, handle);
+    const observed = pass ? await pass.observe(rel, read) : await observeExact(this.#port, this.#root, rel, read);
     if (observed.state === "absent") throw notFound(this.#root, rel);
     const raw = observed.value.toString("utf8");
     const { frontmatter: frontmatter2, body } = parseMarkdown(raw, rel, { okfVersion: await edition() });
@@ -32608,7 +32773,12 @@ var FilesystemBackend = class _FilesystemBackend {
     }
     let editionPromise;
     const edition = () => editionPromise ??= this.#readEdition();
-    for (const id of ids) out.push(await this.#readWithEdition(id, edition));
+    const pass = openObservationPass(this.#port, this.#root);
+    for (const id of ids) out.push(await this.#readWithEdition(id, edition, pass));
+    const retry = new Set(await pass.finish());
+    for (let index2 = 0; index2 < ids.length; index2++) {
+      if (retry.has(pathFromConceptId(ids[index2]))) out[index2] = await this.#readWithEdition(ids[index2], edition);
+    }
     return out;
   }
   async write(id, doc, options = {}) {
@@ -32768,14 +32938,36 @@ function publicationContext(backend) {
   return context;
 }
 async function readRawFilesystemDocument(backend, id) {
+  return readRawDocumentIn(backend, id);
+}
+async function readRawDocumentIn(backend, id, pass) {
   assertSafeConceptId(id);
   const { root, port } = publicationContext(backend);
   const rel = pathFromConceptId(id);
-  const observed = await observeExact(port, root, rel, (handle) => readBytes(port, handle));
+  const read = (handle) => readBytes(port, handle);
+  const observed = pass ? await pass.observe(rel, read) : await observeExact(port, root, rel, read);
   if (observed.state === "absent") throw notFound(root, rel);
   const raw = new TextDecoder("utf-8", { fatal: true }).decode(observed.value);
   return { bytes: observed.value.slice(), version: versionOfBytes(raw) };
 }
+function openRawFilesystemDocumentPass(backend) {
+  const { root, port } = publicationContext(backend);
+  const pass = openObservationPass(port, root);
+  const ids = /* @__PURE__ */ new Map();
+  return {
+    read(id) {
+      assertSafeConceptId(id);
+      ids.set(pathFromConceptId(id), id);
+      return readRawDocumentIn(backend, id, pass);
+    },
+    async finish() {
+      return (await pass.finish()).flatMap((rel) => {
+        const id = ids.get(rel);
+        return id === void 0 ? [] : [id];
+      });
+    }
+  };
+}
 async function readRawFilesystemReserved(backend, dir, name) {
   assertSafeReservedDir(dir);
   assertSafeReservedFilename(name);
@@ -43605,10 +43797,20 @@ async function readInventory(backend, limits) {
     return bytes;
   };
   const documents = [];
+  const documentPass = openRawFilesystemDocumentPass(backend);
   for (const id of documentIds) {
-    const row = await readRawFilesystemDocument(backend, id);
+    const row = await documentPass.read(id);
     documents.push({ id, version: row.version, bytes: admitBytes(row.bytes, id) });
   }
+  for (const id of await documentPass.finish()) {
+    const row = await readRawFilesystemDocument(backend, id).catch((error) => {
+      if (error?.code !== "ENOENT") throw error;
+      return null;
+    });
+    if (row === null || documents.some((document3) => document3.id === id && document3.version !== row.version)) {
+      throw new PublicationError("SOURCE_CHANGED", "a publication object changed during capture", { retryable: true });
+    }
+  }
   const reserved = [];
   for (const identity of reservedIds) {
     const row = await readRawFilesystemReserved(backend, identity.dir, identity.name);

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.1" }, source: { commit: "0c5c7f2b2437d3e33a4aa707f13704e9896482a6", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.2" }, source: { commit: "9a0a564d4096ec7fe51a7f337e7e001542e8e6d5", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -4943,6 +4943,12 @@ async function probeSegment(port, candidate, rel, segment) {
 function hasExact(listing, segment) {
   return listing.some((entry) => entry.name === segment);
 }
+function freshListings(port) {
+  return async (dir) => {
+    const listing = await port.entries(dir);
+    return listing === null ? null : { has: (name) => hasExact(listing, name) };
+  };
+}
 async function walkExact(port, rootResolved, segments, rel) {
   let parent = rootResolved;
   for (let index2 = 0; index2 < segments.length; index2++) {
@@ -4973,14 +4979,14 @@ async function recordWalk(port, rootResolved, segments, rel) {
   }
   return recorded;
 }
-async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle) {
+async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle, listings = freshListings(port)) {
   let parent = rootResolved;
   for (let index2 = 0; index2 < segments.length; index2++) {
     const segment = segments[index2];
     const candidate = path2.join(parent, segment);
-    const listing = await port.entries(parent);
+    const listing = await listings(parent);
     if (listing === null) return "absent";
-    const listed2 = hasExact(listing, segment);
+    const listed2 = listing.has(segment);
     if (handle !== null && index2 === segments.length - 1) {
       const verdict = classifyLeaf({ listed: listed2, probe: await probeSegment(port, candidate, rel, segment), handle });
       if (verdict === "aliased") throw new FilesystemIdentityAliasError(rel, segment);
@@ -5000,13 +5006,15 @@ function countRestart(restarts, rel) {
   return restarts + 1;
 }
 async function observeExact(port, root, rel, read) {
+  return observeWith(port, path2.resolve(root), rel, read, freshListings(port));
+}
+async function observeWith(port, rootResolved, rel, read, listings, onExact) {
   const segments = relSegments(rel);
-  const rootResolved = path2.resolve(root);
   const target3 = path2.join(rootResolved, ...segments);
   for (let restarts = 0; ; ) {
     const recorded = await recordWalk(port, rootResolved, segments, rel);
     if (recorded === null) return { state: "absent" };
-    const verified2 = await confirmedWalk(port, rootResolved, segments, rel, recorded, null);
+    const verified2 = await confirmedWalk(port, rootResolved, segments, rel, recorded, null, listings);
     if (verified2 === "absent") return { state: "absent" };
     if (verified2 === "restart") {
       restarts = countRestart(restarts, rel);
@@ -5028,11 +5036,14 @@ async function observeExact(port, root, rel, read) {
     try {
       value = await read(opened.handle, target3);
       if (value === null) return { state: "absent" };
-      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened);
+      verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened, listings);
     } finally {
       await port.close(opened.handle);
     }
-    if (verdict === "exact") return { state: "exact", value };
+    if (verdict === "exact") {
+      onExact?.(recorded, { dev: opened.dev, ino: opened.ino });
+      return { state: "exact", value };
+    }
     if (verdict === "absent") return { state: "absent" };
     restarts = countRestart(restarts, rel);
   }
@@ -5051,6 +5062,99 @@ async function probeExact(port, root, rel) {
     restarts = countRestart(restarts, rel);
   }
 }
+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);
+  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 };
+  };
+  return {
+    async observe(rel, read) {
+      const listings = listingsFor();
+      let exact;
+      let observed;
+      try {
+        observed = await observeWith(port, rootResolved, rel, read, listings.source, (recorded, handle) => {
+          exact = { rel, segments: relSegments(rel), recorded, handle };
+        });
+      } catch (error51) {
+        if (!listings.reused()) throw error51;
+        return observeExact(port, rootResolved, rel, read);
+      }
+      if (!listings.reused()) return observed;
+      if (observed.state === "absent") return observeExact(port, rootResolved, rel, read);
+      if (exact !== void 0) reusedVerdicts.push(exact);
+      return observed;
+    },
+    async finish() {
+      const retry = /* @__PURE__ */ new Set();
+      const endListings = /* @__PURE__ */ new Map();
+      const listedAtEnd = async (dir) => {
+        if (!endListings.has(dir)) {
+          const listing = await port.entries(dir);
+          endListings.set(dir, listing === null ? null : new Set(listing.map((entry) => entry.name)));
+        }
+        return endListings.get(dir);
+      };
+      try {
+        for (const verdict of reusedVerdicts) {
+          if (!await holdsAtEnd(port, rootResolved, verdict, listedAtEnd)) retry.add(verdict.rel);
+        }
+      } finally {
+        kept.clear();
+        reusedVerdicts.length = 0;
+      }
+      return [...retry];
+    }
+  };
+}
+async function holdsAtEnd(port, rootResolved, verdict, listedAtEnd) {
+  let parent = rootResolved;
+  for (let index2 = 0; index2 < verdict.segments.length; index2++) {
+    const segment = verdict.segments[index2];
+    const listing = await listedAtEnd(parent);
+    if (listing === null || !listing.has(segment)) return false;
+    const candidate = path2.join(parent, segment);
+    const probed = await port.probe(candidate);
+    const expected = index2 === verdict.segments.length - 1 ? verdict.handle : verdict.recorded[index2];
+    if (probed === null || probed.kind === "symlink" || !sameWitness(probed, expected)) return false;
+    parent = candidate;
+  }
+  return true;
+}
 function unsupportedLinkRoots(port) {
   let roots = linkUnsupportedRoots.get(port);
   if (!roots) {
@@ -5201,8 +5305,28 @@ function kindOf(stats) {
   if (stats.isFile()) return "file";
   return "other";
 }
+function directoryWitnessTrusted(platform, filesystemType) {
+  if (platform !== "linux") return true;
+  return filesystemType !== null && LOCAL_LINUX_FILESYSTEMS.has(filesystemType);
+}
+function witnessTrust() {
+  const devices = /* @__PURE__ */ new Map();
+  return (dev, dir) => {
+    if (process.platform !== "linux") return Promise.resolve(true);
+    let trusted = devices.get(dev);
+    if (trusted === void 0) {
+      trusted = fs2.statfs(dir).then(
+        (info) => directoryWitnessTrusted("linux", Number(info.type)),
+        () => false
+      );
+      devices.set(dev, trusted);
+    }
+    return trusted;
+  };
+}
 function createNodeFilesystemIdentityPort(hostPolicy) {
   const policy = captureFilesystemHostPolicy(hostPolicy);
+  const witnessTrustedOn = witnessTrust();
   return Object.freeze({
     isTransientOpenError: policy.isTransientOpenError,
     isReplacementConflict: policy.isReplacementConflict,
@@ -5225,6 +5349,17 @@ function createNodeFilesystemIdentityPort(hostPolicy) {
         throw err;
       }
     },
+    async directoryWitness(dir) {
+      let stats;
+      try {
+        stats = await fs2.stat(dir, { bigint: true });
+      } catch (err) {
+        if (isAbsentPathError(err)) return null;
+        throw err;
+      }
+      if (!await witnessTrustedOn(stats.dev, dir)) return null;
+      return { dev: stats.dev, ino: stats.ino, mtimeNs: stats.mtimeNs, ctimeNs: stats.ctimeNs };
+    },
     async open(target3) {
       const handle = await fs2.open(target3, "r");
       try {
@@ -5279,7 +5414,7 @@ function createNodeFilesystemIdentityPort(hostPolicy) {
     }
   });
 }
-var FilesystemSymlinkEntryError, FilesystemShapeMismatchError, ABSENT_PATH_CODES, MAX_RESTARTS, linkUnsupportedRoots, queues, ABSENT_FILE_CODES;
+var FilesystemSymlinkEntryError, FilesystemShapeMismatchError, ABSENT_PATH_CODES, MAX_RESTARTS, SETTLED_AFTER_NS, linkUnsupportedRoots, queues, ABSENT_FILE_CODES, LOCAL_LINUX_FILESYSTEMS;
 var init_filesystem_identity = __esm({
   "../core/src/filesystem-identity.ts"() {
     "use strict";
@@ -5310,9 +5445,38 @@ var init_filesystem_identity = __esm({
     };
     ABSENT_PATH_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
     MAX_RESTARTS = 3;
+    SETTLED_AFTER_NS = 3000000000n;
     linkUnsupportedRoots = /* @__PURE__ */ new WeakMap();
     queues = /* @__PURE__ */ new Map();
     ABSENT_FILE_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR", "EISDIR"]);
+    LOCAL_LINUX_FILESYSTEMS = /* @__PURE__ */ new Set([
+      61267,
+      // ext2/3/4
+      1481003842,
+      // xfs
+      2435016766,
+      // btrfs
+      16914836,
+      // tmpfs
+      2240043254,
+      // ramfs
+      2035054128,
+      // overlayfs
+      801189825,
+      // zfs
+      4076150800,
+      // f2fs
+      3393526350,
+      // bcachefs
+      19780,
+      // vfat
+      538032816,
+      // exfat
+      1936094318,
+      // ntfs3
+      18475
+      // hfsplus
+    ]);
   }
 });
 
@@ -5627,10 +5791,11 @@ var init_backend = __esm({
           return void 0;
         }
       }
-      async #readWithEdition(id, edition) {
+      async #readWithEdition(id, edition, pass) {
         assertSafeConceptId(id);
         const rel = pathFromConceptId(id);
-        const observed = await observeExact(this.#port, this.#root, rel, (handle) => readBytes(this.#port, handle));
+        const read = (handle) => readBytes(this.#port, handle);
+        const observed = pass ? await pass.observe(rel, read) : await observeExact(this.#port, this.#root, rel, read);
         if (observed.state === "absent") throw notFound(this.#root, rel);
         const raw = observed.value.toString("utf8");
         const { frontmatter, body } = parseMarkdown(raw, rel, { okfVersion: await edition() });
@@ -5645,7 +5810,12 @@ var init_backend = __esm({
         }
         let editionPromise;
         const edition = () => editionPromise ??= this.#readEdition();
-        for (const id of ids) out.push(await this.#readWithEdition(id, edition));
+        const pass = openObservationPass(this.#port, this.#root);
+        for (const id of ids) out.push(await this.#readWithEdition(id, edition, pass));
+        const retry = new Set(await pass.finish());
+        for (let index2 = 0; index2 < ids.length; index2++) {
+          if (retry.has(pathFromConceptId(ids[index2]))) out[index2] = await this.#readWithEdition(ids[index2], edition);
+        }
         return out;
       }
       async write(id, doc2, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.3-pre.1",
+  "version": "0.4.3-pre.2",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [