@amalgm/shell 0.1.164-preview.36061234379 → 0.1.164-preview.36809057014

package/dist/watching/host.js

@@ -1,10 +1,22 @@
 import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { channel } from "node:diagnostics_channel";
 import { lstatSync, readdirSync, realpathSync, watch as openNodeWatch } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createSuspicionScope, watchOwnerOf, } from "@amalgm/live";
 import { openFsEvents } from "./fsevents.js";
 const DEFAULT_RETRY_MINIMUM_MS = 250;
+/** At most this many native notices are admitted per event-loop turn, and a
+ * turn's admissions stop once they have held the main thread for the budget.
+ * A burst of thousands (a Git checkout) is admitted in arrival order across
+ * turns, so no burst holds the main thread for more than one slice, while a
+ * quiet notice is admitted at once. Waiting notices stay owed (hasPending). */
+const WATCH_ADMISSION_SLICE = 256;
+const WATCH_ADMISSION_BUDGET_MS = 1.5;
 const DEFAULT_RETRY_MAXIMUM_MS = 30_000;
+/** Examiners hear each root's oldest unproved ring whenever it moves: a ring
+ * starts it, a proof advances or clears it, unbinding clears it. */
+const obligations = channel("amalgm:watch-obligation");
 /** macOS gets one FSEvents stream per handle. Node's own watcher serves every
  * handle in the process from one stream that it recreates, resuming from the
  * present, whenever a handle opens or closes, losing the events in between. */
@@ -16,13 +28,20 @@ function nativeOpenFor(platform) {
     return (directory, options, listener) => openNodeWatch(realpathSync.native(directory), options, listener);
 }
 /** Linux has no recursive inotify primitive. This one logical handle expands
- * to exactly one non-recursive fs.watch handle per directory, never per file. */
+ * to exactly one non-recursive fs.watch handle per directory, never per file.
+ *
+ * A descendant the tree cannot enter is its parent's to hear, never a lost
+ * tree: one that vanished needs no handle, and one this process may not read
+ * is withheld, keeping any handle it already had, until an event on its name
+ * asks again. Detect names withheld ground unavailable meanwhile. Entering it
+ * later ends an interval no handle heard, so it suspects everything. */
 class LinuxDirectoryTreeWatch extends EventEmitter {
     root;
     open;
     listener;
     excluded;
     handles = new Map();
+    withheld = new Set();
     closed = false;
     constructor(root, open, listener, excluded) {
         super();
@@ -50,30 +69,64 @@ class LinuxDirectoryTreeWatch extends EventEmitter {
         this.closeAll();
         this.emit("close");
     }
-    openTree(directory) {
+    /** Opens every directory the tree can enter at or below this one. `reached`
+     * collects each directory the walk stood on, entered or withheld. */
+    openTree(directory, reached) {
         if (this.closed || this.isExcluded(directory) || !nativeDirectory(directory))
             return;
-        this.openDirectory(directory);
-        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        let entries;
+        try {
+            this.openDirectory(directory);
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (!this.cannotEnter(directory, error))
+                throw error;
+            if (this.withheld.has(directory))
+                reached?.add(directory);
+            return;
+        }
+        reached?.add(directory);
+        for (const entry of entries) {
             if (!entry.isDirectory() || entry.isSymbolicLink())
                 continue;
-            this.openTree(join(directory, entry.name));
+            this.openTree(join(directory, entry.name), reached);
         }
+        if (this.withheld.delete(directory))
+            this.listener("rename", null);
+    }
+    /** Whether a failure to enter this directory is ground its parent hears,
+     * rather than coverage the tree lost. The root is never its parent's. */
+    cannotEnter(directory, error) {
+        if (directory === this.root)
+            return false;
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            this.closeSubtree(directory);
+            return true;
+        }
+        if (code === "EACCES" || code === "EPERM") {
+            this.withheld.add(directory);
+            return true;
+        }
+        return false;
     }
     openDirectory(directory) {
         if (this.handles.has(directory))
             return;
-        const handle = this.open(directory, { recursive: false }, (event, filename) => {
+        const localDirectory = localPath(this.root, directory);
+        const handle = this.open(directory, { recursive: false }, (event, filename, evidence) => {
             if (this.closed)
                 return;
-            const localDirectory = slash(relative(this.root, directory));
             const hint = normalizedHint(filename);
-            const rootedHint = hint === null
+            const rootedHint = hint === null || localDirectory === null
                 ? null
-                : [localDirectory, hint].filter(Boolean).join("/");
-            this.listener(event, rootedHint);
-            if (event === "rename")
+                : localDirectory ? `${localDirectory}/${hint}` : hint;
+            this.listener(event, rootedHint, evidence);
+            // Access returning to withheld ground changes only its attributes.
+            if (event === "rename" || (hint !== null && this.withheld.has(below(directory, hint)))) {
                 this.refresh(directory, hint);
+            }
         });
         const record = { handle, intentional: false };
         this.handles.set(directory, record);
@@ -89,7 +142,7 @@ class LinuxDirectoryTreeWatch extends EventEmitter {
                     this.reconcileTree();
                     return;
                 }
-                const candidate = resolve(directory, ...hint.split("/"));
+                const candidate = below(directory, hint);
                 if (!within(this.root, candidate) || this.isExcluded(candidate))
                     return;
                 if (nativeDirectory(candidate))
@@ -102,23 +155,19 @@ class LinuxDirectoryTreeWatch extends EventEmitter {
             }
         });
     }
+    /** Handles below withheld ground stay: no walk can prove them gone. */
     reconcileTree() {
-        const wanted = new Set();
-        const collect = (directory) => {
-            if (this.isExcluded(directory) || !nativeDirectory(directory))
-                return;
-            wanted.add(directory);
-            for (const entry of readdirSync(directory, { withFileTypes: true })) {
-                if (entry.isDirectory() && !entry.isSymbolicLink())
-                    collect(join(directory, entry.name));
-            }
-        };
-        collect(this.root);
-        for (const directory of wanted)
-            this.openDirectory(directory);
-        for (const directory of this.handles.keys()) {
-            if (!wanted.has(directory))
-                this.closeOne(directory);
+        const reached = new Set();
+        this.openTree(this.root, reached);
+        for (const directory of [...this.withheld]) {
+            if (!reached.has(directory))
+                this.withheld.delete(directory);
+        }
+        const withheld = [...this.withheld];
+        for (const directory of [...this.handles.keys()]) {
+            if (reached.has(directory) || withheld.some((held) => within(held, directory)))
+                continue;
+            this.closeOne(directory);
         }
     }
     closeSubtree(directory) {
@@ -126,6 +175,10 @@ class LinuxDirectoryTreeWatch extends EventEmitter {
             if (within(directory, watched))
                 this.closeOne(watched);
         }
+        for (const held of [...this.withheld]) {
+            if (within(directory, held))
+                this.withheld.delete(held);
+        }
     }
     closeOne(directory) {
         const record = this.handles.get(directory);
@@ -174,9 +227,22 @@ export class NodeWatchHost {
     stopErrors = [];
     closeTask = null;
     plan = emptyPlan();
+    domainOwner = randomUUID();
+    bindingGeneration = 0;
+    domainGeneration = 0;
+    resolvedDomainGeneration = 0;
+    coverageGap = false;
     retryTimer = null;
     retryAttempt = 0;
     closed = false;
+    finalCutoff = false;
+    /** Native notices beyond this turn's slice, in arrival order. */
+    backlog = [];
+    backlogHead = 0;
+    sliceLeft = WATCH_ADMISSION_SLICE;
+    /** When this turn's budget ends; set by the turn's first admission. */
+    sliceEnds = Infinity;
+    turnScheduled = false;
     currentHealth = {
         state: "degraded",
         logicalRoots: 0,
@@ -226,6 +292,8 @@ export class NodeWatchHost {
         const next = buildPlan(grounds, previous.roots);
         if (samePlan(previous, next))
             return this.currentHealth;
+        this.bindingGeneration += 1;
+        const domainPending = this.domainGeneration > this.resolvedDomainGeneration;
         this.cancelRetry();
         const changed = changedRoots(previous, next);
         const authoritativeBaselines = new Set(options.authoritativeBaselineRootIds ?? []);
@@ -239,17 +307,26 @@ export class NodeWatchHost {
             if (!root.materialized) {
                 throw new Error(`authoritative Watch baseline is not materialized: ${rootId}`);
             }
-            const baseline = root.suspicion.snapshot();
+            const baseline = root.suspicion.freeze(null);
             root.suspicion.settle(baseline);
-            root.settledGeneration = baseline.generation;
+            root.suspicion.release(baseline);
         }
         this.plan = next;
+        for (const root of previous.roots.values())
+            if (!next.roots.has(root.rootId))
+                this.observeObligation(root, false);
+        for (const root of next.roots.values())
+            this.observeObligation(root);
         const health = this.establish(next, authoritativeBaselines);
         const unknownChanges = changed.filter((rootId) => !authoritativeBaselines.has(rootId));
         if (health.state === "healthy" && unknownChanges.length > 0) {
             this.suspectRoots(unknownChanges);
             this.signal();
         }
+        // This is the caller's declared binding set, including temporarily missing
+        // ground. A changed set cannot inherit a proof against its predecessor.
+        if (domainPending)
+            this.suspectDomain();
         return health;
     }
     /** Retry the retained desired topology immediately. Useful to supervisors and deterministic tests. */
@@ -272,7 +349,7 @@ export class NodeWatchHost {
                 rootId: root.rootId,
                 directory: root.directory,
                 materialized: root.materialized,
-                currency: root.suspicion.size > 0 ? "catching-up" : "current",
+                currency: root.suspicion.owes ? "catching-up" : "current",
                 contentOwner: (() => {
                     const ownerId = this.plan.ownerByRoot.get(root.rootId);
                     return ownerId ? this.plan.roots.get(ownerId)?.directory ?? null : null;
@@ -287,38 +364,211 @@ export class NodeWatchHost {
                 .sort((left, right) => left.directory.localeCompare(right.directory)),
         };
     }
-    observations() {
+    /** What every root still owes. Scheduling reads this; only a cut proves. */
+    pending() {
         return [...this.plan.roots.values()]
-            .map((root) => ({
-            rootId: root.rootId,
-            directory: root.directory,
-            suspicion: root.suspicion.snapshot(),
-        }))
+            .map(root => ({ rootId: root.rootId, directory: root.directory, pending: root.suspicion.pending() }))
             .sort((left, right) => left.rootId.localeCompare(right.rootId));
     }
+    /** Cut every root at what it owes now; an owed domain cuts all roots
+     * together. Native cutoffs are never widened by the passage of time. */
+    freeze() {
+        return this.domainGeneration === this.resolvedDomainGeneration
+            ? this.freezeRoots(() => true, "owed")
+            : this.domainObservations(this.freezeRoots(() => true, "complete"));
+    }
+    /** Cut the selected roots alone. A partial cut never carries the domain.
+     * "escalated" cuts the rings a named proof escalated while no ring owes
+     * the complete root; otherwise the complete root. */
+    freezeRoots(select, scope) {
+        return [...this.plan.roots.values()]
+            .filter(root => select(root))
+            .sort((left, right) => left.rootId.localeCompare(right.rootId))
+            .map(root => {
+            const owed = root.suspicion.pending();
+            return this.cut(root, scope === "escalated" ? owed.escalated
+                : scope === "complete" || owed.complete ? null : owed.paths);
+        });
+    }
+    /** Cut one root at exactly these named rings. A lane that proves part of a
+     * root's names cuts only its own; the rest stay owed to their lane. */
+    freezePaths(rootId, paths) {
+        const root = this.plan.roots.get(rootId);
+        return root ? this.cut(root, paths) : null;
+    }
+    /** A ticket for exact addresses: each root waits only for the named
+     * addresses inside it. A root inside an address, or an address outside
+     * every root, needs that complete proof — the scope `suspect` rang. */
+    freezeAddresses(absolutePaths) {
+        const roots = [...this.plan.roots.values()].sort((left, right) => left.rootId.localeCompare(right.rootId));
+        const addresses = absolutePaths.map(path => resolve(path));
+        const unbound = addresses.length === 0 || addresses.some(address => !roots.some(root => localPath(root.directory, address) !== null));
+        return roots.flatMap(root => {
+            if (unbound || addresses.some(address => localPath(address, root.directory) !== null)) {
+                return [this.cut(root, null)];
+            }
+            const named = addresses.map(address => localPath(root.directory, address))
+                .filter((local) => local !== null);
+            return named.length ? [this.cut(root, named)] : [];
+        });
+    }
+    cut(root, paths) {
+        return Object.freeze({ rootId: root.rootId, directory: root.directory, suspicion: root.suspicion.freeze(paths) });
+    }
+    /** Every participant is one root's complete cut. */
+    domainObservations(complete) {
+        const domain = Object.freeze({
+            owner: this.domainOwner, generation: this.domainGeneration, bindings: this.bindingGeneration,
+            participants: Object.freeze(complete.map(observation => Object.freeze({
+                rootId: observation.rootId, directory: observation.directory, generation: observation.suspicion.generation,
+            }))),
+        });
+        return complete.map(observation => Object.freeze({ ...observation, domain }));
+    }
+    /** One finite complete-lane batch: an owed domain, else the roots owing a
+     * complete-root or escalated proof. Named rings are not complete work;
+     * their own lanes serve them. A root whose ground is `held` is not cut: it
+     * is `withheld`. A `parked` root is not cut either; its park's own cause
+     * wakes it. A domain, which cuts every root together, waits whole. */
+    selectComplete(held, parked) {
+        const roots = [...this.plan.roots.values()];
+        if (this.domainGeneration > this.resolvedDomainGeneration) {
+            const withheld = roots.map(root => root.directory).filter(held);
+            const waits = withheld.length > 0 || roots.some(root => parked(root.rootId));
+            return { cuts: waits ? [] : this.domainObservations(this.freezeRoots(() => true, "complete")), withheld };
+        }
+        const owing = new Set(roots.filter(root => root.suspicion.pending().complete && !parked(root.rootId))
+            .map(root => root.directory));
+        const withheld = [...owing].filter(held);
+        return { cuts: this.freezeRoots(root => owing.has(root.directory) && !withheld.includes(root.directory), "escalated"),
+            withheld };
+    }
+    /** The binding world a turn begins in; a later rebinding invalidates it. */
+    boundary() {
+        return Object.freeze({ owner: this.domainOwner, bindings: this.bindingGeneration });
+    }
+    boundaryCurrent(boundary) {
+        return boundary.owner === this.domainOwner && boundary.bindings === this.bindingGeneration;
+    }
+    /** A named cut widened: its rings keep their generations and are now owed
+     * a complete-root proof. The cut itself stays live until released. */
+    escalate(observation) {
+        const root = this.plan.roots.get(observation.rootId);
+        if (root?.suspicion.holds(observation.suspicion))
+            root.suspicion.escalate(observation.suspicion);
+    }
+    /** Names another examiner found (the sweep) that a named proof could not
+     * settle. Watch never rang them, so they are rung here and escalated at
+     * once: owed the same scoped wider proof as a widened native ring, never
+     * the complete root merely because Watch did not hear them. */
+    escalatePaths(rootId, paths) {
+        const root = this.plan.roots.get(rootId);
+        if (this.closed || !root || paths.length === 0)
+            return;
+        // The root itself is only ever owed its complete proof.
+        if (paths.includes("")) {
+            this.ring(root, null);
+            return;
+        }
+        for (const path of paths)
+            this.ring(root, path);
+        const cut = root.suspicion.freeze(paths);
+        root.suspicion.escalate(cut);
+        root.suspicion.release(cut);
+    }
+    /** Every cut must be released by its owner, proved or not. */
+    release(observations) {
+        for (const observation of observations) {
+            const root = this.plan.roots.get(observation.rootId);
+            if (root?.suspicion.holds(observation.suspicion))
+                root.suspicion.release(observation.suspicion);
+        }
+    }
+    completeDomain(observations) {
+        const domain = observations[0]?.domain;
+        if (!domain || observations.length !== this.plan.roots.size || observations.length === 0
+            || domain.participants.length !== observations.length
+            || new Set(domain.participants.map(item => item.rootId)).size !== observations.length
+            || new Set(observations.map(item => item.rootId)).size !== observations.length
+            || domain.owner !== this.domainOwner || domain.bindings !== this.bindingGeneration
+            || !this.continuous())
+            return false;
+        return domain.participants.every(({ rootId, directory, generation }) => {
+            const root = this.plan.roots.get(rootId);
+            return root?.directory === directory && root.materialized
+                && observations.some(item => item.rootId === rootId && item.directory === directory
+                    && item.domain === domain && item.suspicion.paths === null
+                    && item.suspicion.generation === generation
+                    && root.suspicion.holds(item.suspicion));
+        });
+    }
     settle(observations) {
+        const domain = observations.find(observation => observation.domain)?.domain;
+        if (domain && !this.completeDomain(observations))
+            return;
         for (const observation of observations) {
             const root = this.plan.roots.get(observation.rootId);
-            if (root?.directory === observation.directory) {
+            if (root?.directory === observation.directory && root.suspicion.holds(observation.suspicion)) {
                 root.suspicion.settle(observation.suspicion);
-                root.settledGeneration = Math.max(root.settledGeneration, observation.suspicion.generation);
+                this.observeObligation(root);
             }
         }
+        if (domain)
+            this.resolvedDomainGeneration = Math.max(this.resolvedDomainGeneration, domain.generation);
     }
-    /** True only when every generation frozen by this observation has been
-     * proved. Newer rings do not change the answer and retain their own pass. */
+    /** True only when everything each cut scoped at or before its generation
+     * has been proved, by any proof. Newer rings keep their own pass. A root
+     * no longer bound owes this caller nothing. */
     settled(observations) {
         return observations.every((observation) => {
             const root = this.plan.roots.get(observation.rootId);
-            return root?.directory === observation.directory
-                && root.settledGeneration >= observation.suspicion.generation;
+            if (!root?.suspicion.holds(observation.suspicion))
+                return true;
+            return (!observation.domain || (observation.domain.owner === this.domainOwner
+                && observation.domain.bindings === this.bindingGeneration
+                && this.resolvedDomainGeneration >= observation.domain.generation))
+                && root.suspicion.settled(observation.suspicion);
         });
     }
+    /** A capture may depend on another root's unfinished observation. Return
+     * scopes only; Apply ownership and recovery decisions remain with the host. */
+    dependencies(observations) {
+        const directories = new Set(observations.flatMap(observation => observation.domain?.participants.map(participant => participant.directory) ?? [observation.directory]));
+        if (this.domainGeneration > this.resolvedDomainGeneration) {
+            for (const root of this.plan.roots.values())
+                directories.add(root.directory);
+        }
+        return [...directories];
+    }
+    /** Coverage is continuous while healthy. A catch-up close is a final cutoff,
+     * not a gap: it suspects every root before retiring its handles, and every
+     * later change belongs to the next startup's blind interval. */
+    continuous() {
+        return !this.coverageGap && (this.currentHealth.state === "healthy" || this.finalCutoff);
+    }
+    bindingsCurrent(observations) {
+        return observations.every(observation => !observation.domain
+            || (this.continuous()
+                && observation.domain.owner === this.domainOwner
+                && observation.domain.bindings === this.bindingGeneration));
+    }
     suspectAll() {
         if (this.closed)
             return;
         for (const root of this.plan.roots.values())
-            root.suspicion.suspectAll();
+            this.ring(root, null);
+    }
+    /** One ambiguous effect can reach another root through a historical alias.
+     * Keep one bounded obligation, not a history of native notifications. */
+    suspectDomain() {
+        if (this.closed)
+            return;
+        this.suspectAll();
+        this.domainGeneration += 1;
+        if (this.plan.roots.size === 0) {
+            this.resolvedDomainGeneration = this.domainGeneration;
+        }
+        this.signal();
     }
     /** A host effect that touched exact ground rings the same named suspicion a
      * native callback would: each root containing the address suspects that
@@ -333,26 +583,27 @@ export class NodeWatchHost {
             const local = localPath(root.directory, absolute);
             if (local === null)
                 continue;
-            if (local === "")
-                root.suspicion.suspectAll();
-            else
-                root.suspicion.ring(local);
+            this.ring(root, local === "" ? null : local);
             named = true;
         }
         if (!named)
             this.suspectRoots(this.plan.roots.keys());
     }
     get hasPending() {
-        return [...this.plan.roots.values()].some((root) => root.suspicion.size > 0);
+        return this.backlogHead < this.backlog.length
+            || [...this.plan.roots.values()].some((root) => root.suspicion.owes);
     }
     close(options = {}) {
         if (this.closeTask)
             return this.closeTask;
         if (options.catchUp !== false) {
             for (const root of this.plan.roots.values())
-                root.suspicion.suspectAll();
+                this.ring(root, null);
+            this.finalCutoff = true;
         }
         this.closed = true;
+        this.backlog = [];
+        this.backlogHead = 0;
         this.cancelRetry();
         closeRecords(this.content);
         closeRecords(this.addresses);
@@ -377,7 +628,7 @@ export class NodeWatchHost {
             for (const directory of wantedContent) {
                 if (this.content.has(directory))
                     continue;
-                this.content.set(directory, this.openHandle("content", directory, true, (filename) => this.routeContent(directory, filename)));
+                this.content.set(directory, this.openHandle("content", directory, true, (filename, evidence) => this.routeContent(directory, filename, evidence)));
                 openedContent.push(directory);
             }
             for (const directory of wantedAddresses) {
@@ -390,9 +641,7 @@ export class NodeWatchHost {
         catch (error) {
             closeSelected(this.content, openedContent);
             closeSelected(this.addresses, openedAddresses);
-            this.suspectRoots(plan.roots.keys());
-            const health = this.degrade(errorMessage(error));
-            this.signal();
+            const health = this.loseCoverage(errorMessage(error));
             this.scheduleRetry();
             return health;
         }
@@ -420,15 +669,38 @@ export class NodeWatchHost {
             contentHandles: this.content.size,
             addressHandles: this.addresses.size,
         };
+        const recovered = this.coverageGap;
+        if (recovered) {
+            this.coverageGap = false;
+            // An examination acquired inside the blind interval cannot prove
+            // recovery. The still-pending cohort must be read under new coverage.
+            this.bindingGeneration += 1;
+        }
         this.publishHealth(health);
-        if (introducedSuspicion)
+        if (introducedSuspicion || recovered)
             this.signal();
         return health;
     }
     openHandle(kind, directory, recursive, route) {
+        const deliver = (event, filename, native) => {
+            if (this.closed)
+                return;
+            const at = Date.now();
+            this.admit(() => {
+                // Evidence is built within the admitted slice, dated at arrival.
+                this.onEvent?.({ kind, directory, path: normalizedHint(filename), event, ...(native ? { native } : {}), at });
+                // Preserve scope before ignored/control paths, repository routing, or
+                // current path lookup can discard the reason for wider examination.
+                if (native?.scope === "domain")
+                    this.suspectDomain();
+                else
+                    route(filename, native?.alias
+                        ? { alias: true, ...(native.file === null ? {} : { object: native.file }) } : undefined);
+            });
+        };
         const handle = recursive && this.platform === "linux"
-            ? new LinuxDirectoryTreeWatch(directory, this.open, (_event, filename) => route(filename), this.plan.exclusions.filter((excluded) => within(directory, excluded)))
-            : this.open(directory, { recursive }, (_event, filename) => route(filename));
+            ? new LinuxDirectoryTreeWatch(directory, this.open, (event, filename, evidence) => deliver(event, filename, evidence), this.plan.exclusions.filter((excluded) => within(directory, excluded)))
+            : this.open(directory, { recursive }, (event, filename, evidence) => deliver(event, filename, evidence));
         const record = {
             handle,
             identity: directoryIdentity(directory),
@@ -452,15 +724,12 @@ export class NodeWatchHost {
         catch {
             // The handle is already unusable; coverage loss is recorded below.
         }
-        const roots = kind === "content"
-            ? this.plan.membersByContent.get(directory)
-            : this.plan.targetsByAddress.get(directory);
-        this.suspectRoots(roots ?? []);
-        this.degrade(`${kind} watcher ${directory}: ${reason}`);
-        this.signal();
+        // The lost interval could contain an edit through an alias in another
+        // root. Reopening this handle repairs coverage, not that attribution.
+        this.loseCoverage(`${kind} watcher ${directory}: ${reason}`);
         this.scheduleRetry();
     }
-    routeContent(directory, filename) {
+    routeContent(directory, filename, evidence) {
         if (this.closed)
             return;
         const members = this.plan.membersByContent.get(directory);
@@ -470,9 +739,8 @@ export class NodeWatchHost {
             return;
         }
         const hint = normalizedHint(filename);
-        this.onEvent?.({ kind: "content", directory, path: hint, at: Date.now() });
         if (hint !== null) {
-            const absolute = resolve(directory, ...hint.split("/"));
+            const absolute = below(directory, hint);
             if (this.plan.exclusions.some((excluded) => within(excluded, absolute)))
                 return;
             let signaled = false;
@@ -482,11 +750,11 @@ export class NodeWatchHost {
                     continue;
                 const local = localPath(root.directory, absolute);
                 if (local !== null && local !== "") {
-                    root.suspicion.ring(local);
+                    this.ring(root, local, evidence);
                     signaled = true;
                 }
                 else if (local === "" || within(absolute, root.directory)) {
-                    root.suspicion.suspectAll();
+                    this.ring(root, null);
                     signaled = true;
                 }
             }
@@ -507,7 +775,6 @@ export class NodeWatchHost {
             return;
         }
         const hint = normalizedHint(filename);
-        this.onEvent?.({ kind: "address", directory, path: hint, at: Date.now() });
         if (hint === null) {
             this.suspectRoots(targets);
             this.rearmAddressedContent(targets);
@@ -553,13 +820,46 @@ export class NodeWatchHost {
             closeRecord(record);
             this.content.delete(directory);
         }
-        if (addressed)
+        if (addressed) {
+            this.loseCoverage("content directory identity changed");
             this.establish(this.plan);
+        }
         return suspects;
     }
     suspectRoots(rootIds) {
-        for (const rootId of rootIds)
-            this.plan.roots.get(rootId)?.suspicion.suspectAll();
+        for (const rootId of rootIds) {
+            const root = this.plan.roots.get(rootId);
+            if (root)
+                this.ring(root, null);
+        }
+    }
+    /** Every doorbell enters here; null suspects the complete root. A ring can
+     * only start an obligation, so examiners hear it only when none was owed. */
+    ring(root, local, evidence) {
+        if (local === null)
+            root.suspicion.suspectAll();
+        else
+            root.suspicion.ring(local, evidence);
+        if (root.oldest === null)
+            this.observeObligation(root);
+    }
+    observeObligation(root, bound = true) {
+        if (!obligations.hasSubscribers)
+            return;
+        const oldest = bound ? root.suspicion.pending().oldest : null;
+        if (oldest === root.oldest)
+            return;
+        root.oldest = oldest;
+        obligations.publish({ rootId: root.rootId, oldest, at: performance.now() });
+    }
+    loseCoverage(reason) {
+        const health = this.degrade(reason);
+        if (!this.coverageGap) {
+            this.coverageGap = true;
+            this.bindingGeneration += 1;
+            this.suspectDomain();
+        }
+        return health;
     }
     degrade(reason) {
         const health = {
@@ -581,6 +881,47 @@ export class NodeWatchHost {
     signal() {
         this.onSignal();
     }
+    /** Admit a notice now while this turn's slice lasts and nothing earlier
+     * waits; otherwise after every earlier notice, in a later turn. */
+    admit(notice) {
+        this.nextTurn();
+        if (this.backlogHead === this.backlog.length && this.sliceLeft > 0) {
+            this.admitNow(notice);
+            return;
+        }
+        this.backlog.push(notice);
+    }
+    admitNow(notice) {
+        if (this.sliceEnds === Infinity)
+            this.sliceEnds = performance.now() + WATCH_ADMISSION_BUDGET_MS;
+        this.sliceLeft -= 1;
+        notice();
+        if (performance.now() >= this.sliceEnds)
+            this.sliceLeft = 0;
+    }
+    /** Each turn renews the slice and admits the oldest waiting notices. */
+    nextTurn() {
+        if (this.turnScheduled || this.closed)
+            return;
+        this.turnScheduled = true;
+        setImmediate(() => {
+            this.turnScheduled = false;
+            this.sliceLeft = WATCH_ADMISSION_SLICE;
+            this.sliceEnds = Infinity;
+            while (this.sliceLeft > 0 && this.backlogHead < this.backlog.length && !this.closed) {
+                const notice = this.backlog[this.backlogHead];
+                this.backlogHead += 1;
+                this.admitNow(notice);
+            }
+            if (this.backlogHead < this.backlog.length) {
+                this.nextTurn();
+            }
+            else {
+                this.backlog = [];
+                this.backlogHead = 0;
+            }
+        });
+    }
     scheduleRetry() {
         if (this.closed || this.retryTimer)
             return;
@@ -614,7 +955,7 @@ function buildPlan(grounds, previous) {
         paths.add(directory);
         const excludedSubtrees = [...new Set((ground.excludedSubtrees ?? []).map((path) => resolve(path)))].sort();
         const prior = previous.get(rootId);
-        const suspicion = prior?.suspicion ?? createSuspicionScope();
+        const suspicion = prior?.suspicion ?? createSuspicionScope(() => performance.now());
         if (!prior || prior.directory !== directory)
             suspicion.suspectAll();
         roots.set(rootId, {
@@ -623,7 +964,7 @@ function buildPlan(grounds, previous) {
             materialized: ground.materialized !== false,
             excludedSubtrees,
             suspicion,
-            settledGeneration: prior?.settledGeneration ?? 0,
+            oldest: prior?.oldest ?? null,
         });
     }
     const exclusions = [...new Set([...roots.values()].flatMap((root) => root.excludedSubtrees))].sort();
@@ -735,13 +1076,25 @@ function normalizedHint(filename) {
         return null;
     return segments.join("/");
 }
+/** A canonical path's address below a canonical root: "" for the root itself,
+ * null outside it. Plan paths are resolved once when the plan is built and
+ * event paths are built from normalized hints, so routing an event costs one
+ * prefix comparison, never a normalization. A path that is not canonical can
+ * only fail to match, which widens its ring. Windows compares names without
+ * case, as its path relation does. */
 function localPath(root, path) {
-    const result = relative(root, path);
-    if (result === "")
+    const folded = sep === "\\";
+    const base = folded ? root.toLowerCase() : root;
+    const candidate = folded ? path.toLowerCase() : path;
+    if (candidate === base)
         return "";
-    if (result === ".." || result.startsWith(`..${sep}`) || isAbsolute(result))
-        return null;
-    return slash(result);
+    const prefix = base.endsWith(sep) ? base : base + sep;
+    return candidate.startsWith(prefix) ? slash(path.slice(prefix.length)) : null;
+}
+/** One canonical address from a canonical directory and a normalized hint. */
+function below(directory, hint) {
+    const native = sep === "/" ? hint : hint.replaceAll("/", sep);
+    return directory.endsWith(sep) ? directory + native : directory + sep + native;
 }
 function within(parent, child) {
     return localPath(parent, child) !== null;