@ttsc/unplugin 0.30.4 → 0.31.0

package/src/core/transform/tracker/broker/routeWatchBrokerMessage.ts

@@ -0,0 +1,133 @@
+import type { WatchBroker } from "./WatchBroker";
+
+/**
+ * Apply one message from the isolated watch process to the waiter or
+ * registration it names (samchon/ttsc#1387).
+ *
+ * The child multiplexes every registration of the process, and every drain,
+ * over one ordered IPC channel, so each message carries the request id it
+ * answers, and the decision is a table over what else it carries:
+ *
+ * - A nonobject message or one without a numeric id is ignored. Remaining
+ *   discriminants receive the checks below; this is not a complete schema
+ *   validator for arbitrary foreign objects.
+ * - A `drained` reply releases the drain waiting on that id. The channel is
+ *   ordered, so every event the child sent before it has already been applied.
+ *   Every draining registration the request covered is told which of its
+ *   watches the child could not prove delivered (samchon/ttsc#1453), in its own
+ *   spelling, or that none was unproven (samchon/ttsc#1546).
+ * - A message for an id with no live registration is ignored. It is the late
+ *   event of a registration already closed.
+ * - `gap` says a native watch of the registration reported that events were
+ *   dropped (samchon/ttsc#1425).
+ * - `failed` says a watch of the registration failed, and `ready` resolves its
+ *   wait. One message can carry both, when some of the watches could not be
+ *   opened.
+ * - An event without a directory is one the child could not place.
+ * - Every other message is an event of a watched directory, named by the child's
+ *   canonical spelling and translated back to the registration's own before its
+ *   sink hears it.
+ *
+ * What each call means is the sink's to decide (`WatchBrokerSink`). Sink
+ * exceptions propagate and can interrupt remaining dispatch/release work; drain
+ * timeout and child lifetime belong to the request/broker owners.
+ *
+ * @param broker The drains and registrations of the broker the child serves.
+ * @param message The message as the IPC channel delivered it.
+ * @evidence contracts/common.md#principled-implementation
+ *   Message discriminants route exact request and registration ids; each drain
+ *   snapshot determines which sinks may receive its partial-coverage verdict.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One IPC decoder translates canonical spellings and dispatches callbacks;
+ *   sinks own mutation interpretation and request owners own release state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Nonobject/nonnumeric-id and retired registration messages are ignored;
+ *   nonstring filenames remain null and failure stays explicit. Producer
+ *   eventType semantics are trusted when nonnull, rather than claiming a full
+ *   arbitrary-message schema validation.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs, message list and parameter comments explain precedence,
+ *   ordered delivery and owner spelling under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral consumers receive each registration's translated native spelling;
+ *   canonical child paths are not compared by universal lowercase or alias prefix.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Completed drain dispatch deletes its waiter and calls the owning release closure, which clears timeout/scope state and adjusts child references. Sink exceptions can interrupt this path; request timeout/failure handling remains separate. Temporary translated sets grow with unproven entries/spelling bytes, while this router retains no historical message or registration population.
+ * @evidence contracts/performance.md#efficient-algorithms Ordinary messages use numeric-id lookup plus reached native-spelling text lookup/callback effects. Drain replies scan U unproven entries into translated sets and all R live registrations for covered draining sinks, not just covered scope size. Cost includes string hashing/comparison and delegated sink/release work; no native watched-directory enumeration occurs here.
+ * @evidence contracts/performance.md#reuse-equivalent-work A supplied drain completion is distributed only to the request's covered draining registrations; deleting its waiter prevents duplicate replies from replaying that proof. Ordinary status/event invocations have no message deduplication. Child/probe computation sharing belongs to broker/drain owners, and this router does not independently validate the child's verdict.
+ */
+export function routeWatchBrokerMessage(
+  broker: Pick<WatchBroker, "drainScopes" | "drains" | "registrations">,
+  message: unknown,
+): void {
+  if (message === null || typeof message !== "object") return;
+  const record = message as {
+    directory?: string;
+    drained?: boolean;
+    unproven?: unknown;
+    failed?: boolean;
+    filename?: string | null;
+    gap?: boolean;
+    eventType?: string;
+    id?: number;
+    ready?: boolean;
+  };
+  if (typeof record.id !== "number") return;
+  if (record.drained === true) {
+    const release = broker.drains.get(record.id);
+    if (release === undefined) return;
+    const scope = broker.drainScopes?.get(record.id);
+    if (scope === undefined) {
+      broker.drains.delete(record.id);
+      release(false);
+      return;
+    }
+    // The reply is the whole verdict of this drain: a watch it does not name
+    // was proven, so every draining registration hears a verdict, the empty
+    // one where nothing of it is named.
+    const unproven = new Map<number, Set<string>>();
+    if (Array.isArray(record.unproven)) {
+      for (const entry of record.unproven as unknown[]) {
+        if (entry === null || typeof entry !== "object") continue;
+        const { directory, id } = entry as {
+          directory?: unknown;
+          id?: unknown;
+        };
+        if (typeof id !== "number" || typeof directory !== "string") continue;
+        const registration = broker.registrations.get(id);
+        if (registration === undefined) continue;
+        const directories = unproven.get(id) ?? new Set<string>();
+        directories.add(registration.spellings.get(directory) ?? directory);
+        unproven.set(id, directories);
+      }
+    }
+    // Only a registration the request covered hears it. One registered after
+    // the request was sent had no watch probed by it, and must keep waiting for
+    // a drain of its own rather than read this one's silence as proof.
+    for (const [id, registration] of broker.registrations) {
+      if (!registration.drains) continue;
+      if (!scope.has(id)) continue;
+      registration.sink.unproven(unproven.get(id));
+    }
+    broker.drains.delete(record.id);
+    release(true);
+    return;
+  }
+  const registration = broker.registrations.get(record.id);
+  if (registration === undefined) return;
+  if (record.gap === true) {
+    registration.sink.gap();
+    return;
+  }
+  if (record.failed === true) registration.sink.failed();
+  if (record.ready === true) registration.ready();
+  if (record.ready === true || record.failed === true) return;
+  if (typeof record.directory !== "string") {
+    registration.sink.unattributed();
+    return;
+  }
+  registration.sink.event(
+    registration.spellings.get(record.directory) ?? record.directory,
+    typeof record.filename === "string" ? record.filename : null,
+    record.eventType ?? "rename",
+  );
+}

package/src/core/transform/tracker/broker/sweepAbandonedWatchProbes.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { WATCH_PROBE_DIRECTORY_PREFIX } from "./WATCH_PROBE_DIRECTORY_PREFIX";
+
+/**
+ * Attempt removal of recognized probe-name entries below `parent` when their
+ * named process reports ESRCH.
+ *
+ * A process removes its own probe directory when it exits, but a killed process
+ * may not. Only a namespace entry named with a process id that the operating
+ * system reports as gone (`ESRCH`) is removed: a live owner, one this process
+ * may not signal, and a name without an id are left alone. Names follow the
+ * adapter's probe convention; this scan does not separately stat entry kind or
+ * prove filesystem ownership, and liveness/deletion are not one atomic
+ * operation.
+ *
+ * @param parent The tool cache the broker is about to name its own probe
+ *   directory in.
+ * @evidence contracts/common.md#principled-implementation
+ *   Probe namespace ownership and an ESRCH result authorize stale cleanup;
+ *   live or inaccessible process ids must retain their directory.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One directory scan applies namespace and process-liveness checks before
+ *   removing an entry; current process cleanup stays with its exit owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Cleanup does not treat arbitrary kill errors as death or delete the current
+ *   owner's probe namespace to disguise registration failures.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain killed-owner recovery and conservative liveness
+ *   conditions under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral cleanup uses node:path and the supported process liveness call;
+ *   permission denial remains non-removable rather than an OS-name assumption.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One scan materializes N names, checks prefix/decimal text and parses safe
+ *   integer PIDs. Each eligible candidate probes current liveness; selected
+ *   entries then delegate native recursive removal over their descendants.
+ *   Text/native access and removed subtree work remain beyond N, with O(N)
+ *   temporary name storage; no global PID population is enumerated.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Process liveness and stale-directory deletion are current external effects;
+ *   a previous sweep cannot authorize a later owner's cleanup.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Confirmed ESRCH permits best-effort recursive removal, not certified native
+ *   release. Failed listing/removal and live/denied/current/unrecognized owners
+ *   remain, so this scan imposes no count/byte bound or historical retry queue.
+ *   Only temporary names are held; active probe lifetime belongs to its opener.
+ */
+export function sweepAbandonedWatchProbes(parent: string): void {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(parent);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.startsWith(WATCH_PROBE_DIRECTORY_PREFIX)) continue;
+    const suffix = entry.slice(WATCH_PROBE_DIRECTORY_PREFIX.length);
+    if (!/^[1-9]\d*$/.test(suffix)) continue;
+    const owner = Number(suffix);
+    if (!Number.isSafeInteger(owner) || owner === process.pid) {
+      continue;
+    }
+    try {
+      process.kill(owner, 0);
+      continue;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ESRCH") continue;
+    }
+    try {
+      fs.rmSync(path.join(parent, entry), { force: true, recursive: true });
+    } catch {
+      // Another process may be removing it at the same moment.
+    }
+  }
+}

package/src/core/transform/tracker/broker/usesWatchBroker.ts

@@ -0,0 +1,43 @@
+import type { TtscTransformFilesystemOperations } from "../../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * Whether a tracker over `filesystem` opens its watches in the isolated watch
+ * broker rather than in this process.
+ *
+ * The host filesystem on Windows and macOS does: Windows so that a native
+ * fs-event abort cannot take the host down, and macOS so that each watch is its
+ * own FSEventStream, whose dropped events are reported, rather than one libuv
+ * re-creates whenever any watch in the host opens or closes, and whose drops it
+ * discards (samchon/ttsc#1418, samchon/ttsc#1425). An embedder that supplies
+ * its own `watch` retains that capability, including for a host-filesystem
+ * view.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A supplied filesystem watcher is authoritative; only the native host
+ *   implementation chooses isolated Windows or macOS notification ownership.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One capability guard and two platform names select the backend; opening
+ *   watches and managing child lifetime remain separate responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Isolation addresses native failure and stream continuity at their owner;
+ *   it does not replace a supplied watcher or patch host internals.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs state the backend selection and its distinct platform
+ *   reasons, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral callers delegate explicit native backend selection here.
+ *   Platform checks concern watcher capability, not path equality or casing.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Constant-time comparisons.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure predicate over the filesystem view and the platform.
+ */
+export function usesWatchBroker(
+  filesystem: TtscTransformFilesystemOperations,
+): boolean {
+  return (
+    filesystem.watch === undefined &&
+    (filesystem.platform === undefined ||
+      filesystem.platform === process.platform) &&
+    (process.platform === "win32" || process.platform === "darwin")
+  );
+}

package/src/core/transform/tracker/broker/warnMissingFseventsBinding.ts

@@ -0,0 +1,48 @@
+/** Whether this loaded module copy already requested its warning. */
+let warned = false;
+
+/**
+ * Request one warning for this loaded adapter copy when its macOS broker cannot
+ * resolve the optional `fsevents` binding.
+ *
+ * The watch broker watches macOS through that binding, since `fs.watch` there
+ * can lose events without notice. Missing resolution makes broker registrations
+ * fail rather than authorizing silence; custom watchers are separate. The
+ * binding is an optional dependency that package managers install on macOS
+ * unless told to omit optional dependencies, so the cause is named with its
+ * remedy, as a Node process warning, code `TTSC_FSEVENTS_MISSING`. Resolution
+ * failure need not mean the package was never installed, and actual child
+ * loading is checked later. The flag is set before emission and is not reset;
+ * host warning listeners and display policy own delivery, not this operation.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A stable process warning names failed optional binding resolution without
+ *   claiming installation absence was proven; watcher proof/fallback remains
+ *   with broker and validator owners.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One module-local bit deduplicates this diagnostic; binding resolution and
+ *   backend failure remain with their respective owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The stable warning code identifies the real remediation path, without
+ *   monkey-patching optional module loading or pretending a fallback is equivalent.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain cause, authority consequence and remedy under
+ *   the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral host code receives this explicit macOS capability diagnostic;
+ *   missing native support falls back to validation rather than unsafe silence.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One module-local bit retains completed emission admission for that copy's lifetime, with no reset/history population. Node owns warning construction, later dispatch and host listener/output retention; this function acquires no descriptor or watcher and does not guarantee display completion.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed bit guards at most one emission call per loaded copy. Warning Error/stack construction and host dispatch/output work remain delegated costs; the one-call count is not a fixed IO/handler-duration guarantee.
+ * @evidence contracts/performance.md#reuse-equivalent-work The flag prevents repeated warning requests from this loaded copy, not repeated binding resolution or native loading. Different module copies have independent flags, and warning suppression/display behavior is host-owned; no retry occurs after the flag is set.
+ */
+export function warnMissingFseventsBinding(): void {
+  if (warned) return;
+  warned = true;
+  process.emitWarning(
+    "@ttsc/unplugin: the optional dependency `fsevents` could not be resolved, so " +
+      "macOS file notifications cannot be trusted and every delivery " +
+      "validates its inputs against the disk instead. Check that optional " +
+      "dependencies are installed and that `fsevents` resolves from this package.",
+    { code: "TTSC_FSEVENTS_MISSING" },
+  );
+}

package/src/core/transform/tracker/broker/watchBrokerSource.ts

@@ -0,0 +1,371 @@
+import { WATCH_PROBE_TIMEOUT_MS } from "./WATCH_PROBE_TIMEOUT_MS";
+
+/**
+ * The program the isolated watch process runs.
+ *
+ * Each registration owns its opened watches and reports readiness or failure.
+ * Admitted events carry that registration's id. Drains use the native backend's
+ * frontier described below; a reply alone does not certify every scope, since
+ * probe-dependent streams can be named unproven and gaps withdraw authority.
+ *
+ * On Windows the watches are `fs.watch`. A drain yields through two immediate
+ * turns to allow the loop to poll and deliver queued callbacks before replying.
+ * The real Windows scenario checks two hundred synchronous write/drain pairs;
+ * the scripted unit checks this scheduling boundary separately. These checks
+ * are not a universal kernel-order proof: FIFO completion-port queueing alone
+ * does not guarantee dequeue order or establish when notification completion
+ * becomes observable relative to a write and IPC request.
+ *
+ * On macOS the watches go through the `fsevents` binding, one FSEventStream per
+ * location, instead of relying on `fs.watch` for stream and loss authority
+ * (samchon/ttsc#1418, samchon/ttsc#1425). The binding supplies a stream closer
+ * and native flags to this callback boundary, so the child:
+ *
+ * - Maps each event's flags to the event type libuv would report, and drops what
+ *   a non-recursive watch would not hear;
+ * - Sends `gap` to the registration whose stream reports a drop, a wrapped event
+ *   id, a changed root, a mount or unmount, or a path it cannot place, since
+ *   events of that stream may have been lost.
+ *
+ * FSEvents delivers with a latency, so turns of the loop prove nothing there,
+ * and a stream created now can still deliver events of writes made just before,
+ * which the service had not yet logged (samchon/ttsc#1453, samchon/ttsc#1454).
+ * Ordered delivery within one stream is the probe frontier's premise. A
+ * location naming a probe directory below the stream's root writes there and
+ * waits for clean delivery on that stream; loss flags still withdraw authority.
+ * This delivered frontier is not an atomic timestamp classification of every
+ * write. Such a stream is opened at the probe's root, not at the location, and
+ * its events are placed against the location. The child writes one probe when
+ * the stream opens, and reports `ready` only once it is heard, discarding what
+ * arrived before it as the past; and one per `drain`, answering once it is
+ * heard. A probe that is not heard within the timeout withdraws authority:
+ * delayed scheduling/delivery also expires it, without proving permanent
+ * inability. The child closes the registration and reports failure. A stream
+ * with no probe cannot be proven, and the drain names its location as
+ * unproven.
+ *
+ * When the requested macOS binding is unresolved or cannot be loaded, the child
+ * reports the registration failed instead of substituting fs.watch.
+ *
+ * Native event names reach the parent without a basename prefilter: neither
+ * backend supplies an alias-free name capability here. Parent classifiers own
+ * exact native identity and uncertainty; requested event kinds still filter
+ * content independently of native name equivalence.
+ *
+ * @param fsevents The resolved binding path for the macOS backend. `null` means
+ *   the parent could not resolve it; loading a supplied path can fail
+ *   separately. `undefined` selects the fs.watch backend.
+ * @evidence contracts/common.md#principled-implementation
+ *   The child protocol keeps per-registration streams and ordered drains;
+ *   macOS proof requires clean probe delivery. Loss flags withdraw coverage
+ *   before probe recognition, so matching a probe name cannot erase that warning.
+ *   The Windows two-turn frontier retains its runtime/backend ordering premise;
+ *   this source does not independently prove kernel completeness.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One maintained child program serves both native backends; this function only
+ *   injects resolved capability and the shared timeout, with JSON-safe path encoding.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Native flags and deadlines express backend contracts, not fixture-specific
+ *   repairs. Missing bindings and probes report uncertainty rather than silent success.
+ *   Name inequality cannot establish native alias inequality; native names
+ *   reach the owning parent classifier without a basename substitution.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain ordering, native loss, probe lifecycle and absence;
+ *   embedded-program comments identify state ownership under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral parent code delegates native flags and watcher capability to this
+ *   child boundary; node:path handles relative names and canonical stream roots.
+ *   Windows alternate event names and Unicode uncertainty reach the parent
+ *   instead of being interpreted as a universal lowercase identity rule.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Source construction copies fixed program text plus JSON-encoded binding
+ *   path bytes. The child stores R registrations and S streams; drain scans
+ *   every stream, retains per-stream expectations and unproven rows, and groups
+ *   writes by eligible probe directory. Native watch/realpath/mkdir/write/remove,
+ *   callbacks and encoded IPC path bytes remain part of the delegated cost.
+ *   Without basename filtering, admitted events carry their name text through
+ *   IPC for parent validation; subscription/event populations and message bytes
+ *   govern that additional routing work.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The constant program is reused for every child start; within a drain,
+ *   equivalent probe-directory work is shared while each stream must observe it.
+ *   Separate openings retain their own temporal probe boundary.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Source storage transfers to the spawn caller. The child owns registrations,
+ *   streams and per-opening/drain probe expectations/timers. Removal attempts
+ *   every acquired closer; heard/timeout requests file removal but ignores its
+ *   failure, and abandoned expectations can leave probe files for namespace
+ *   cleanup. Failed partial opening remains registered until parent removal.
+ *   Async stop/removal completion is not awaited; disconnect attempts retirement
+ *   then exits. R/S/outstanding probes, IPC queues and filesystem bytes have no
+ *   count/byte bound; process exit ends native handles, not retained disk files.
+ */
+export function watchBrokerSource(fsevents?: string | null): string {
+  return `const fseventsPath = ${fsevents === undefined ? "undefined" : JSON.stringify(fsevents)};\nconst probeTimeoutMs = ${WATCH_PROBE_TIMEOUT_MS};\n${WATCH_BROKER_PROGRAM}`;
+}
+
+/**
+ * The child program, as CommonJS text for `node -e`. It carries no template
+ * literal, so it can be embedded verbatim.
+ */
+const WATCH_BROKER_PROGRAM = String.raw`const fs = require("node:fs");
+const path = require("node:path");
+
+// Registration id -> { closers, opening, streams }.
+const registrations = new Map();
+// The fsevents flags (CoreServices' kFSEventStreamEventFlag* values). A stream
+// that reports any of DROPPED may have lost events. libuv reports CHANGE for an
+// event that modified an item without creating, removing, or renaming one, and
+// RENAME for every other.
+const DROPPED = 0x1 | 0x2 | 0x4 | 0x8 | 0x20 | 0x40 | 0x80;
+const MODIFIED = 0x400 | 0x1000 | 0x2000 | 0x4000 | 0x8000;
+const RENAMED = 0x100 | 0x200 | 0x800;
+const fsevents = load();
+let probeSequence = 0;
+
+process.on("message", (message) => {
+  if (message.op === "drain") {
+    drain(message.id);
+    return;
+  }
+  if (message.op === "remove") {
+    remove(message.id);
+    return;
+  }
+  if (message.op === "add") add(message);
+});
+process.on("disconnect", () => {
+  for (const id of [...registrations.keys()]) remove(id);
+  process.exit(0);
+});
+
+function load() {
+  if (typeof fseventsPath !== "string") return undefined;
+  try {
+    return require(fseventsPath);
+  } catch {
+    return undefined;
+  }
+}
+
+function subscriber(message, location) {
+  return (event, filename) => {
+    // An event without a name is a backend's notice that anything below the
+    // directory may have changed, such as a Windows buffer overflow, so every
+    // registration hears it, whichever events it asked for.
+    if (message.allEvents || event === "rename" || filename === null || location.recursive === true) {
+      process.send?.({ directory: location.directory, eventType: event, filename: filename === null ? null : String(filename), id: message.id });
+    }
+  };
+}
+
+function add(message) {
+  const registration = { closers: [], id: message.id, opening: 0, streams: [] };
+  registrations.set(message.id, registration);
+  // A macOS watch without the binding can lose events silently.
+  let failed = fseventsPath === null || (typeof fseventsPath === "string" && fsevents === undefined);
+  for (const location of message.locations) {
+    if (failed) break;
+    const deliver = subscriber(message, location);
+    try {
+      if (fsevents === undefined) {
+        registration.closers.push(watch(location, deliver, message.id));
+      } else {
+        const opened = stream(location, deliver, registration);
+        registration.closers.push(opened.close);
+        registration.streams.push(opened);
+      }
+    } catch {
+      failed = true;
+    }
+  }
+  // A probed stream reports ready once its opening probe is heard.
+  if (failed || registration.opening === 0) process.send?.({ failed, id: message.id, ready: true });
+}
+
+function watch(location, deliver, id) {
+  const watcher = fs.watch(location.directory, { persistent: false, recursive: location.recursive === true }, deliver);
+  watcher.on("error", () => process.send?.({ failed: true, id }));
+  return () => watcher.close();
+}
+
+// FSEvents reports the real path of what changed, so events are placed below
+// the real path of the location, and the stream is opened at the real path of
+// the probe's root when the location has one.
+function stream(location, deliver, registration) {
+  const id = registration.id;
+  const directory = fs.realpathSync.native(location.directory);
+  // The probe directory need not exist yet; it is placed below the root's real
+  // path by the same relative path.
+  const probe = location.probe === undefined ? undefined : (() => {
+    const root = fs.realpathSync.native(location.probe.root);
+    return { directory: path.join(root, path.relative(location.probe.root, location.probe.directory)), root };
+  })();
+  const root = probe === undefined ? directory : probe.root;
+  const within = (parent, file) => file === parent || file.startsWith(parent.endsWith("/") ? parent : parent + "/");
+  const opened = { close: undefined, location: location.directory, pending: new Map(), probe, proven: probe === undefined };
+  const stop = fsevents.watch(root, (file, flags) => {
+    // Loss authority is independent of the path, including our own probe.
+    if ((flags & DROPPED) !== 0) {
+      process.send?.({ gap: true, id });
+      return;
+    }
+    // A probe of this stream: everything before it has been delivered.
+    if (probe !== undefined && within(probe.directory, file)) {
+      const waiting = opened.pending.get(path.basename(file));
+      if (waiting !== undefined) {
+        opened.pending.delete(path.basename(file));
+        waiting.heard();
+      }
+      return;
+    }
+    // Before the opening probe, the stream still delivers the past.
+    if (!opened.proven) return;
+    // The watched directory's own events say nothing about its entries, and
+    // its replacement arrives as a changed root.
+    if (file === directory) return;
+    if (!within(directory, file)) {
+      // Below the stream's root but outside the location: another location's
+      // business, or the root's own event. Outside the root: the stream
+      // cannot place it.
+      if (!within(root, file)) process.send?.({ gap: true, id });
+      return;
+    }
+    const filename = file.slice(directory.length + 1);
+    if (location.recursive !== true && filename.includes("/")) return;
+    deliver((flags & MODIFIED) !== 0 && (flags & RENAMED) === 0 ? "change" : "rename", filename);
+  });
+  opened.close = () => {
+    const pending = [...opened.pending.values()];
+    opened.pending.clear();
+    for (const entry of pending) entry.abandon();
+    Promise.resolve(stop()).catch(() => undefined);
+  };
+  if (probe !== undefined) {
+    registration.opening += 1;
+    const written = writeProbe(opened, registration, () => {
+      opened.proven = true;
+      registration.opening -= 1;
+      if (registration.opening === 0) process.send?.({ failed: false, id, ready: true });
+    }, () => undefined);
+    // A probe that cannot be written leaves the stream unprovable: it opens
+    // all the same, and every drain names it unproven.
+    if (!written) {
+      registration.opening -= 1;
+      opened.probe = undefined;
+      opened.proven = true;
+    }
+  }
+  return opened;
+}
+
+// Expect one probe on a stream, and call heard() once the stream delivers it
+// or missed() after authority is withdrawn: the delivery threshold expired, so
+// the registration is reported failed and its streams are closed, or the stream
+// was closed first. Expiry is not proof of permanent native nondelivery.
+function expectProbe(opened, registration, name, heard, missed) {
+  const file = path.join(opened.probe.directory, name);
+  const entry = {
+    abandon: () => {
+      clearTimeout(entry.timer);
+      missed();
+    },
+    heard: () => {
+      clearTimeout(entry.timer);
+      fs.rm(file, { force: true }, () => undefined);
+      heard();
+    },
+    timer: setTimeout(() => {
+      if (opened.pending.get(name) !== entry) return;
+      opened.pending.delete(name);
+      fs.rm(file, { force: true }, () => undefined);
+      process.send?.({ failed: true, id: registration.id, ready: true });
+      remove(registration.id);
+      entry.abandon();
+    }, probeTimeoutMs),
+  };
+  entry.timer.unref?.();
+  opened.pending.set(name, entry);
+  return entry;
+}
+
+// Write one probe file below a probe directory, for every stream expecting it.
+function writeProbeFile(directory, name) {
+  try {
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(path.join(directory, name), String(process.pid));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Write one probe per stream at its opening; call back whether it was written.
+function writeProbe(opened, registration, heard, missed) {
+  probeSequence += 1;
+  const name = "probe-" + process.pid + "-" + probeSequence;
+  const entry = expectProbe(opened, registration, name, heard, missed);
+  if (writeProbeFile(opened.probe.directory, name)) return true;
+  clearTimeout(entry.timer);
+  opened.pending.delete(name);
+  return false;
+}
+
+// Answer once every stream that can be proven has delivered a probe written
+// now; name the locations of the streams that cannot. Streams rooted at one
+// probe directory, every tracker of a project among them, share one probe file,
+// which each of them hears on its own stream.
+function drain(requestId) {
+  const unproven = [];
+  let outstanding = 0;
+  const settle = () => {
+    outstanding -= 1;
+    if (outstanding === 0) process.send?.({ drained: true, id: requestId, unproven });
+  };
+  probeSequence += 1;
+  const name = "probe-" + process.pid + "-" + probeSequence;
+  const directories = new Map();
+  for (const [id, registration] of registrations) {
+    for (const opened of registration.streams) {
+      if (opened.probe === undefined) {
+        unproven.push({ directory: opened.location, id });
+        continue;
+      }
+      outstanding += 1;
+      const entry = expectProbe(opened, registration, name, settle, () => {
+        unproven.push({ directory: opened.location, id });
+        settle();
+      });
+      const expecting = directories.get(opened.probe.directory) ?? [];
+      expecting.push({ entry, name, opened });
+      directories.set(opened.probe.directory, expecting);
+    }
+  }
+  for (const [directory, expecting] of directories) {
+    if (writeProbeFile(directory, name)) continue;
+    // The probe cannot be written there, so these streams cannot be proven.
+    for (const { entry, opened } of expecting) {
+      clearTimeout(entry.timer);
+      opened.pending.delete(name);
+      opened.probe = undefined;
+      entry.abandon();
+    }
+  }
+  // Windows watches, and streams already proven, answer after two turns: the
+  // first lets the loop poll for completions the kernel had already queued,
+  // the second answers after their callbacks.
+  outstanding += 1;
+  setImmediate(() => setImmediate(settle));
+}
+
+function remove(id) {
+  const registration = registrations.get(id);
+  if (registration === undefined) return;
+  registrations.delete(id);
+  for (const close of registration.closers) {
+    try {
+      close();
+    } catch {}
+  }
+}
+`;