@gmickel/gno 1.34.6 → 1.35.0

package/src/serve/watch-snapshot-ops.ts

@@ -5,6 +5,7 @@
  * @module src/serve/watch-snapshot-ops
  */
 
+import type { DirectoryAvailabilityPort } from "../ingestion/source-availability";
 import type {
   DiffWorkResult,
   SnapshotEntryFingerprint,
@@ -15,12 +16,15 @@ import type {
   WatcherSnapshotOptions,
 } from "./watch-snapshot-types";
 
+import {
+  directoryAllowsDescent,
+  readAvailableDirectory,
+} from "./watch-snapshot-availability";
 import {
   cloneDirectoryMaps,
   defaultClock,
   defaultFs,
   freezeSnapshot,
-  readDirectChildren,
   removeSubtreeFromMaps,
   setDirectoryEntries,
   type MutableSnapshotMaps,
@@ -46,11 +50,25 @@ export async function buildWatcherSnapshot(
   const fs = options.fs ?? defaultFs;
   const clock = options.clock ?? defaultClock;
   const ceiling = options.entryCeiling ?? WATCHER_SNAPSHOT_ENTRY_CEILING;
+  const directoryAvailability = options.directoryAvailability;
   const started = clock.nowMs();
 
+  if (!(await directoryAllowsDescent(rootAbs, "", directoryAvailability))) {
+    // Root itself is unproven — fail closed without claiming an empty tree.
+    return {
+      status: "fallback",
+      reason: "scan_failed",
+      durationMs: clock.nowMs() - started,
+      cause: new Error(
+        "Collection root availability is unproven; refusing snapshot descent"
+      ),
+    };
+  }
+
   const state: MutableSnapshotMaps = {
     directories: new Map(),
     entryCount: 0,
+    unprovenSubtrees: new Set(),
   };
   // Cursor-index queue avoids O(n) shift on large directory sets.
   const queue: string[] = [""];
@@ -68,7 +86,27 @@ export async function buildWatcherSnapshot(
         durationMs: clock.nowMs() - started,
       };
     }
-    const scanned = await readDirectChildren(rootAbs, dirRel, fs, remaining);
+    const scanned = await readAvailableDirectory(
+      rootAbs,
+      dirRel,
+      fs,
+      remaining,
+      directoryAvailability
+    );
+    if (scanned.status === "unproven") {
+      if (dirRel === "") {
+        return {
+          status: "fallback",
+          reason: "scan_failed",
+          durationMs: clock.nowMs() - started,
+          cause: new Error(
+            "Collection root availability changed before snapshot enumeration"
+          ),
+        };
+      }
+      state.unprovenSubtrees.add(dirRel);
+      continue;
+    }
     if (scanned.status === "missing") {
       if (dirRel === "") {
         return {
@@ -107,7 +145,19 @@ export async function buildWatcherSnapshot(
     for (const [name, fingerprint] of scanned.entries) {
       // No-follow: never recurse through symlinks (even if they point inside root).
       if (fingerprint.kind === "directory") {
-        queue.push(joinWatcherRelPath(dirRel, name));
+        const childRel = joinWatcherRelPath(dirRel, name);
+        if (
+          !(await directoryAllowsDescent(
+            rootAbs,
+            childRel,
+            directoryAvailability
+          ))
+        ) {
+          // Refuse descent/enumeration; leave subtree absent from this build.
+          state.unprovenSubtrees.add(childRel);
+          continue;
+        }
+        queue.push(childRel);
       }
     }
   }
@@ -138,6 +188,7 @@ export async function diffWatcherSnapshot(
   const clock = options.clock ?? defaultClock;
   const ceiling = options.entryCeiling ?? WATCHER_SNAPSHOT_ENTRY_CEILING;
   const mapHooks = options.mapHooks;
+  const directoryAvailability = options.directoryAvailability;
   const started = clock.nowMs();
 
   const normalizedDirs: string[] = [];
@@ -179,19 +230,45 @@ export async function diffWatcherSnapshot(
     }
   };
 
+  const subtreeInventoryIsUnproven = (dirRel: string): boolean => {
+    const prefix = `${dirRel}/`;
+    for (const unproven of nextState.unprovenSubtrees) {
+      if (unproven === dirRel || unproven.startsWith(prefix)) {
+        return true;
+      }
+    }
+    return false;
+  };
+
   const diffDirectory = async (dirRel: string): Promise<DiffWorkResult> => {
     if (visited.has(dirRel)) {
       return { status: "ok" };
     }
     visited.add(dirRel);
 
+    if (
+      !(await directoryAllowsDescent(rootAbs, dirRel, directoryAvailability))
+    ) {
+      // Dirty target is unproven — keep prior subtree, prove nothing.
+      return { status: "ok" };
+    }
+
     // Replacement frees prior slots for this directory map before the new scan.
     const previousSize = nextState.directories.get(dirRel)?.size ?? 0;
     const remaining = ceiling - nextState.entryCount + previousSize;
     if (remaining < 0) {
       return { status: "overflow" };
     }
-    const scanned = await readDirectChildren(rootAbs, dirRel, fs, remaining);
+    const scanned = await readAvailableDirectory(
+      rootAbs,
+      dirRel,
+      fs,
+      remaining,
+      directoryAvailability
+    );
+    if (scanned.status === "unproven") {
+      return { status: "ok" };
+    }
     if (scanned.status === "missing") {
       // Open-time ENOENT/ENOTDIR is never directory-deletion proof.
       // A nested dirty target may have raced into a file/symlink/other after
@@ -217,6 +294,7 @@ export async function diffWatcherSnapshot(
       new Map<string, SnapshotEntryFingerprint>();
     const newEntries = scanned.entries;
     setDirectoryEntries(nextState, dirRel, new Map(newEntries));
+    nextState.unprovenSubtrees.delete(dirRel);
 
     if (nextState.entryCount > ceiling) {
       return { status: "overflow" };
@@ -232,6 +310,9 @@ export async function diffWatcherSnapshot(
         // Removed entry: expand prior subtree for directories; files/symlinks directly.
         // `other` was never an indexable source — drop fingerprint only.
         if (oldFp.kind === "directory") {
+          if (subtreeInventoryIsUnproven(childRel)) {
+            return { status: "unproven_subtree" };
+          }
           recordSubtreeRemovals(childRel);
         } else if (isWatcherSourceKind(oldFp.kind)) {
           removals.add(childRel);
@@ -242,13 +323,24 @@ export async function diffWatcherSnapshot(
       if (newFp && !oldFp) {
         // Added entry. Candidates are file/symlink only — ignore new FIFO/etc.
         if (newFp.kind === "directory") {
+          if (
+            !(await directoryAllowsDescent(
+              rootAbs,
+              childRel,
+              directoryAvailability
+            ))
+          ) {
+            // Unproven new directory: keep fingerprint, do not enumerate.
+            continue;
+          }
           const built = await scanNewSubtree(
             rootAbs,
             childRel,
             fs,
             nextState,
             candidates,
-            ceiling
+            ceiling,
+            directoryAvailability
           );
           if (built.status !== "ok") {
             return built;
@@ -264,6 +356,9 @@ export async function diffWatcherSnapshot(
         // Changed entry — handle kind transitions with the other-kind contract.
         if (oldFp.kind === "directory" && newFp.kind !== "directory") {
           // Directory → file/symlink/other: expand nested indexable removals.
+          if (subtreeInventoryIsUnproven(childRel)) {
+            return { status: "unproven_subtree" };
+          }
           recordSubtreeRemovals(childRel);
           if (isWatcherSourceKind(newFp.kind)) {
             candidates.add(childRel);
@@ -278,13 +373,23 @@ export async function diffWatcherSnapshot(
           if (isWatcherSourceKind(oldFp.kind)) {
             removals.add(childRel);
           }
+          if (
+            !(await directoryAllowsDescent(
+              rootAbs,
+              childRel,
+              directoryAvailability
+            ))
+          ) {
+            continue;
+          }
           const built = await scanNewSubtree(
             rootAbs,
             childRel,
             fs,
             nextState,
             candidates,
-            ceiling
+            ceiling,
+            directoryAvailability
           );
           if (built.status !== "ok") {
             return built;
@@ -293,7 +398,17 @@ export async function diffWatcherSnapshot(
         }
 
         if (newFp.kind === "directory") {
-          // Directory → directory (metadata change): recurse.
+          // Directory → directory (metadata change): recurse only when available.
+          if (
+            !(await directoryAllowsDescent(
+              rootAbs,
+              childRel,
+              directoryAvailability
+            ))
+          ) {
+            // Preserve prior subtree under unproven directory — do not re-scan.
+            continue;
+          }
           const nested = await diffDirectory(childRel);
           if (nested.status !== "ok") {
             return nested;
@@ -358,8 +473,14 @@ async function scanNewSubtree(
   fs: WatcherSnapshotFs,
   state: MutableSnapshotMaps,
   candidates: Set<string>,
-  ceiling: number
+  ceiling: number,
+  directoryAvailability?: DirectoryAvailabilityPort
 ): Promise<DiffWorkResult> {
+  if (!(await directoryAllowsDescent(rootAbs, dirRel, directoryAvailability))) {
+    // Keep the directory fingerprint from the parent listing; do not enumerate.
+    state.unprovenSubtrees.add(dirRel);
+    return { status: "ok" };
+  }
   const queue = [dirRel];
   let head = 0;
   while (head < queue.length) {
@@ -370,7 +491,17 @@ async function scanNewSubtree(
     if (remaining < 0) {
       return { status: "overflow" };
     }
-    const scanned = await readDirectChildren(rootAbs, current, fs, remaining);
+    const scanned = await readAvailableDirectory(
+      rootAbs,
+      current,
+      fs,
+      remaining,
+      directoryAvailability
+    );
+    if (scanned.status === "unproven") {
+      state.unprovenSubtrees.add(current);
+      continue;
+    }
     if (scanned.status === "missing") {
       // New directory vanished while scanning — fail closed.
       return {
@@ -382,12 +513,23 @@ async function scanNewSubtree(
       return scanned;
     }
     setDirectoryEntries(state, current, new Map(scanned.entries));
+    state.unprovenSubtrees.delete(current);
     if (state.entryCount > ceiling) {
       return { status: "overflow" };
     }
     for (const [name, fingerprint] of scanned.entries) {
       const childRel = joinWatcherRelPath(current, name);
       if (fingerprint.kind === "directory") {
+        if (
+          !(await directoryAllowsDescent(
+            rootAbs,
+            childRel,
+            directoryAvailability
+          ))
+        ) {
+          state.unprovenSubtrees.add(childRel);
+          continue;
+        }
         queue.push(childRel);
       } else if (isWatcherSourceKind(fingerprint.kind)) {
         candidates.add(childRel);

package/src/serve/watch-snapshot-scan.ts

@@ -35,6 +35,7 @@ export const defaultFs: WatcherSnapshotFs = createDefaultWatcherFs();
 export interface MutableSnapshotMaps {
   directories: Map<string, Map<string, SnapshotEntryFingerprint>>;
   entryCount: number;
+  unprovenSubtrees: Set<string>;
 }
 
 export function cloneDirectoryMaps(
@@ -47,6 +48,7 @@ export function cloneDirectoryMaps(
   return {
     directories,
     entryCount: source.entryCount,
+    unprovenSubtrees: new Set(source.unprovenSubtrees ?? []),
   };
 }
 
@@ -61,6 +63,7 @@ export function freezeSnapshot(state: MutableSnapshotMaps): WatcherSnapshot {
   return {
     directories: frozen,
     entryCount: state.entryCount,
+    unprovenSubtrees: new Set(state.unprovenSubtrees),
   };
 }
 

package/src/serve/watch-snapshot-types.ts

@@ -7,6 +7,8 @@
 // node:path — Bun has no path utilities
 import { isAbsolute } from "node:path";
 
+import type { DirectoryAvailabilityPort } from "../ingestion/source-availability";
+
 /** Fixed service-wide maximum entries retained in one collection snapshot. */
 export const WATCHER_SNAPSHOT_ENTRY_CEILING = 100_000;
 
@@ -44,6 +46,12 @@ export interface WatcherSnapshot {
   >;
   /** Total no-follow entries across every directory map. */
   readonly entryCount: number;
+  /**
+   * Directory roots observed in a parent listing but not enumerated because
+   * source availability was unproven. Their stored descendant inventory is
+   * incomplete, so a later proven removal requires full reconciliation.
+   */
+  readonly unprovenSubtrees?: ReadonlySet<string>;
 }
 
 /** Injectable lstat view. `unreliable` forces the correctness-preserving fallback. */
@@ -120,6 +128,26 @@ export interface WatcherSnapshotFs {
 
   /** Deterministic close; safe to call once per open. */
   closeDir(handle: WatcherDirHandle): Promise<void>;
+
+  /**
+   * Optional production-grade synchronous scan used only while a process-wide
+   * no-materialization policy is active. Missing support fails local mode closed.
+   */
+  readDirectChildrenSync?: (
+    rootAbs: string,
+    dirRel: string,
+    maxEntries: number
+  ) =>
+    | { status: "present"; entries: Map<string, SnapshotEntryFingerprint> }
+    | { status: "missing" }
+    | ScanFailure;
+
+  /** Synchronous anchored child lstat for guarded local-mode presence checks. */
+  lstatChildByRelSync?: (
+    rootAbs: string,
+    parentRel: string,
+    name: string
+  ) => WatcherSnapshotStat;
 }
 
 export interface WatcherSnapshotClock {
@@ -135,7 +163,8 @@ export interface SnapshotMapHooks {
 export type SnapshotFallbackReason =
   | "overflow"
   | "scan_failed"
-  | "unreliable_metadata";
+  | "unreliable_metadata"
+  | "unproven_subtree";
 
 export type WatcherSnapshotBuildResult =
   | {
@@ -191,6 +220,12 @@ export interface WatcherSnapshotOptions {
   entryCeiling?: number;
   /** Map-visit instrumentation (tests / complexity regression). */
   mapHooks?: SnapshotMapHooks;
+  /**
+   * Optional directory-availability classifier for local-mode collections.
+   * When set, dataless / availability-unknown directories are not descended;
+   * previously observed subtrees are preserved rather than proven removed.
+   */
+  directoryAvailability?: DirectoryAvailabilityPort;
 }
 
 export type ScanFailure =
@@ -198,7 +233,10 @@ export type ScanFailure =
   | { status: "scan_failed"; cause: unknown }
   | { status: "unreliable_metadata" };
 
-export type DiffWorkResult = { status: "ok" } | ScanFailure;
+export type DiffWorkResult =
+  | { status: "ok" }
+  | ScanFailure
+  | { status: "unproven_subtree" };
 
 export function toBigInt(value: number | bigint | undefined): bigint | null {
   if (value === undefined) {
@@ -332,7 +370,11 @@ export function joinWatcherRelPath(dir: string, name: string): string {
 }
 
 export function createEmptyWatcherSnapshot(): WatcherSnapshot {
-  return { directories: new Map(), entryCount: 0 };
+  return {
+    directories: new Map(),
+    entryCount: 0,
+    unprovenSubtrees: new Set(),
+  };
 }
 
 export function isMissingFsError(error: unknown): boolean {

package/browser-extension/artifacts/gno-browser-clipper-v1.34.6.zip.sha256

@@ -1 +0,0 @@
-76e1e560efa69f780e5e61130008e863cf8288a8ffe5cd82e16b48608c6c8578  gno-browser-clipper-v1.34.6.zip