@ttsc/unplugin 0.30.4 → 0.31.0

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

@@ -0,0 +1,68 @@
+/**
+ * One directory the watch broker watches for a registration.
+ *
+ * A location describes a native directory or, with `recursive`, its subtree.
+ * Exact-input callers can also send requested names, but the current child does
+ * not use that list as a basename filter: alternative native event names must
+ * reach the parent's identity/uncertainty classifier. The shape does not
+ * promise event traffic proportional to named input count.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Directory/subtree scope and caller-requested names remain distinct from
+ *   optional probe ownership. Requested spelling equality cannot establish
+ *   native alias inequality, so the child forwards names without this filter.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One location record supplies opening data; registration-level sinks and
+ *   lifetime state are not duplicated per location.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   A probe-dependent stream without usable probe capability stays unproven.
+ *   Other backend drain mechanisms belong to the child implementation, not a
+ *   universal latency or capability guarantee from this carrier.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs and separated member comments explain named scopes and
+ *   probe containment under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral callers supply paths in their own spelling; the broker translates
+ *   canonical native paths and confines probe semantics to capable backends.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   WatchBrokerLocation only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   WatchBrokerLocation only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   WatchBrokerLocation only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export interface WatchBrokerLocation {
+  /**
+   * Directory to watch, as the registering tracker spells it: the walk's
+   * spelling for the project tracker, the physical path for exact-input
+   * trackers.
+   */
+  directory: string;
+
+  /**
+   * Requested entry spellings from exact-input callers. Retained in the opening
+   * protocol, but not used by the current child as a native-name prefilter.
+   */
+  names?: string[];
+
+  /**
+   * Whether to watch the whole tree below the directory instead of named
+   * entries.
+   */
+  recursive?: boolean;
+
+  /**
+   * Where the broker may write a probe to prove this location's stream has
+   * delivered everything before a moment, on a backend that delivers with a
+   * latency (samchon/ttsc#1453): a directory the adapter owns, below `root`,
+   * which contains the location. The stream is then opened at `root`, reports
+   * ready once its opening probe came back, and answers each drain once that
+   * drain's probe did. When absent or unusable on a probe-dependent stream, a
+   * drain names the location unproven. Non-probe backend draining follows its
+   * own mechanism; this field alone does not certify delivery.
+   */
+  probe?: { directory: string; root: string };
+}

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

@@ -0,0 +1,84 @@
+import type { WatchBrokerSink } from "./WatchBrokerSink";
+
+/**
+ * One live registration of the isolated watch process: its watches' sink, and
+ * what routing a message to it needs.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Required canonical-to-owner spellings preserve alias identity for events;
+ *   drain participation is distinct from readiness and event forwarding.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One registration combines sink, translation and opening resolver without
+ *   duplicating the broker's process or outstanding drain maps.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Requiring a translation map makes routing ownership explicit but does not
+ *   prove every reported directory has an entry; unmatched directories retain
+ *   child spelling and the sink decides their meaning.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native type and separated member comments explain routing authority and
+ *   required translation under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral routing maps native canonical paths back to each owner's
+ *   spelling instead of lowercasing or assuming textual aliases are equal.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   WatchBrokerRegistration only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   WatchBrokerRegistration only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   WatchBrokerRegistration only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface WatchBrokerRegistration {
+  /**
+   * Whether the registration takes part in drains, and so hears each drain's
+   * verdict on its watches (`WatchBrokerSink.unproven`). A watch that only
+   * forwards events, such as an input observer's scope, does not.
+   */
+  drains: boolean;
+
+  /**
+   * Resolve the registration's wait for its watches to open.
+   *
+   * Reported opening failure reaches the sink separately before completion;
+   * explicit closure also ends this wait without certifying success.
+   */
+  ready: WatchBrokerOpeningComplete;
+
+  /** Where the registration's messages go. */
+  sink: WatchBrokerSink;
+
+  /**
+   * The registration's own spelling for each canonical directory the child
+   * watches, so a reported event is translated back before anything compares it
+   * with a path the registration produced.
+   *
+   * Required as routing state, but its entries are not completeness proof. A
+   * directory absent from this map is forwarded in child spelling; exact
+   * identity/relevance classification stays with the sink.
+   */
+  spellings: ReadonlyMap<string, string>;
+}
+
+/**
+ * End a registration's opening wait after any failure has reached its sink.
+ *
+ * Completion alone cannot certify watch success; the sink owns that verdict.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolution ends the wait independently of the sink's success or failure authority.
+ * @evidence contracts/common.md#clear-and-simple-design A parameterless callback preserves function-property variance and complements the separate failure channel.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Completion cannot erase failure or fabricate notification coverage.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish completion and success under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral opening waits finish through explicit backend acknowledgment rather than a platform startup timing assumption.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   WatchBrokerOpeningComplete only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   WatchBrokerOpeningComplete only declares a shape; it has no work to reuse
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   WatchBrokerOpeningComplete only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export type WatchBrokerOpeningComplete = () => void;

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

@@ -0,0 +1,182 @@
+/**
+ * What one registration of the isolated watch process is told
+ * (samchon/ttsc#1387): the events of its watches, and what befell the watches
+ * themselves.
+ *
+ * `routeWatchBrokerMessage` decides which call a message is, and translates the
+ * child's canonical directory back to the spelling the registration watched
+ * under, so a sink compares what it hears against its own paths. A sink decides
+ * only what the call means to its owner: a tracker records a witness or a flag
+ * (`brokeredTrackerSink`), and an input observer's scope hands the event on
+ * (`openIsolatedRecursiveWatch`). Neither needs the other's shape.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Events, failed registration, dropped delivery and per-location proof loss
+ *   remain independent messages with distinct authority consequences.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One callback interface separates routing from owner interpretation; trackers
+ *   and forwarding observers do not depend on each other's state representation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Lost attribution and delivery are explicit instead of invented filenames
+ *   or silently successful watcher states.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs and separated callback comments explain message meaning
+ *   and spelling ownership under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral consumers hear paths in their own registration spelling while
+ *   native canonicalization and drop signaling remain with routing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   WatchBrokerSink only declares a shape; it has no computation at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   WatchBrokerSink only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   WatchBrokerSink only declares a shape; it has no handle or retained state
+ *   at runtime.
+ */
+export interface WatchBrokerSink {
+  /**
+   * One event below a watched directory.
+   *
+   * @param directory The watched directory, in the registration's spelling.
+   * @param filename The entry the event names, relative to `directory`, or
+   *   `null` when the backend could not name it, which may then concern
+   *   anything below the directory (a Windows buffer overflow).
+   * @param eventType `"rename"` or `"change"`, as `fs.watch` names them.
+   * @evidence contracts/common.md#principled-implementation
+   *   Relative names and a nullable unknown name preserve event attribution.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One callback carries observation without choosing the owner's input scope.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   A backend overflow remains null instead of a fabricated exact path.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native parameter comments define spelling and null breadth under the
+   *   documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   OS-neutral owners receive translated directory spelling and native unknown
+   *   names without platform-wide path casing assumptions.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Only the signature of event is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Only the signature of event is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Only the signature of event is declared here; the cost belongs to its
+   *   implementation.
+   */
+  event(directory: string, filename: string | null, eventType: string): void;
+
+  /**
+   * An event the child could not place under any watched directory.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   Attribution loss is represented independently of named events and failure.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   A parameterless callback carries exactly the unavailable-attribution fact.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   The owner is told uncertainty rather than an arbitrary guessed directory.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native JSDoc names the attribution limit under the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   OS-neutral owners receive unknown attribution without guessing a native
+   *   path from the operating system or stream backend.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Only the signature of unattributed is declared here; the cost belongs to
+   *   its implementation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Only the signature of unattributed is declared here; the cost belongs to
+   *   its implementation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Only the signature of unattributed is declared here; the cost belongs to
+   *   its implementation.
+   */
+  unattributed(): void;
+
+  /**
+   * A watch of the registration failed or could not be opened.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   This terminal coverage failure is distinct from an observed mutation.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   A parameterless callback lets the owner withdraw its own authority.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   Registration failure cannot be represented as successfully quiet coverage.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native JSDoc includes both opening and later failure under the
+   *   documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   OS-neutral owners handle the failure contract without inspecting native
+   *   stream, descriptor or child-process details.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Only the signature of failed is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Only the signature of failed is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Only the signature of failed is declared here; the cost belongs to its
+   *   implementation.
+   */
+  failed(): void;
+
+  /**
+   * A native watch of the registration reported that events were dropped, so
+   * some may have been lost (samchon/ttsc#1425).
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   A drop notification withdraws completeness without ending future delivery.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One callback reports the gap independently of failure or exact event paths.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   Missing events cannot be silently ignored to preserve a quiet-state proof.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native JSDoc identifies the native dropped-event meaning under the
+   *   documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   OS-neutral owners consume explicit native loss capability instead of
+   *   assuming all watcher backends have equivalent delivery guarantees.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Only the signature of gap is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Only the signature of gap is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Only the signature of gap is declared here; the cost belongs to its
+   *   implementation.
+   */
+  gap(): void;
+
+  /**
+   * A drain's verdict on the registration's watches (samchon/ttsc#1453): the
+   * directories whose stream could not be proven to have delivered, in the
+   * registration's spelling, or `undefined` when every one was proven. Only a
+   * registration that drains is told.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   The optional directory Set expresses partial drain coverage in owner
+   *   spelling; undefined means no location remained unproven for that request.
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One scoped verdict callback keeps partial coverage separate from events.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   A drain cannot claim locations outside its registration coverage or replace
+   *   missing native proof with a guessed fixed delay.
+   * @evidence contracts/common.md#meaningful-documentation
+   *   Native JSDoc states Set, undefined and drain-participation meanings under
+   *   the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation
+   *   OS-neutral owners receive translated unproven locations rather than
+   *   applying FSEvents-specific latency assumptions themselves.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Only the signature of unproven is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Only the signature of unproven is declared here; the cost belongs to its
+   *   implementation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Only the signature of unproven is declared here; the cost belongs to its
+   *   implementation.
+   */
+  unproven(directories: ReadonlySet<string> | undefined): void;
+}

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

@@ -0,0 +1,123 @@
+import path from "node:path";
+
+import type { TtscProjectMutationTracker } from "../TtscProjectMutationTracker";
+import { recordProjectChange } from "../recordProjectChange";
+import { recordProjectMutation } from "../recordProjectMutation";
+import type { WatchBrokerSink } from "./WatchBrokerSink";
+
+/**
+ * The sink a tracker's brokered watches report to: what each message of the
+ * isolated watch process means to a generation's tracker.
+ *
+ * - An event is classified by the tracker's own filters. With the exact-input
+ *   trackers' shared classifier, it alone decides between a mutation, a content
+ *   change, and no recorded change; uncertain native aliases can independently
+ *   withdraw the tracker's verification authority. With the project-directory
+ *   tracker's filters, a named event records membership when admitted and
+ *   structural, or content for an admitted non-rename event. Rejected
+ *   membership can still withdraw authority through the owner filter. Events
+ *   without that filter are mutations.
+ * - An event the child could not place is a membership change of unknown kind.
+ * - A failed watch fails the tracker, so its silence is never read as proof.
+ * - A gap leaves the tracker hearing everything after it, so it is marked
+ *   unverified, and its silence proves nothing until a delivery proves the
+ *   recorded state again (samchon/ttsc#1425).
+ * - A drain's verdict replaces the tracker's unproven set (samchon/ttsc#1453).
+ *
+ * @param tracker The tracker the watches are registered for.
+ * @param filters The tracker's event decision: the exact-input trackers'
+ *   classifier, or the project-directory tracker's membership, content, and
+ *   new-membership filters.
+ * @evidence contracts/common.md#principled-implementation
+ *   Owner filters classify events; failed, gap and partial drain messages update
+ *   different authority fields rather than pretending they are mutations.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One sink adapts the broker protocol to tracker state and delegates exact
+ *   input classification wholesale, keeping backend policies equivalent.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Unattributed events remain structural witnesses and failed coverage remains failed;
+ *   the adapter neither suppresses events nor patches a foreign watcher.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native message list and parameter comments distinguish each verdict and
+ *   classifier precedence under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral event construction uses node:path and owner-translated directory
+ *   spellings; native drop and probe semantics are explicit protocol inputs.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The sink retains its tracker and owner filters until registration retirement.
+ *   A supplied unproven-directory Set transfers to the tracker and is replaced
+ *   by subsequent drain verdicts; the tracker close retires its registration.
+ * @evidence contracts/performance.md#efficient-algorithms Each message follows one handler; named events include native path construction, delegated owner classification and bounded witness recording. Those costs follow path text and the owner's scope indexes, not the adapter's statement count.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each tracker has its own sink, and events are effects rather than computations to share.
+ */
+export function brokeredTrackerSink(
+  tracker: TtscProjectMutationTracker,
+  filters: {
+    /** Whether a named `change` can add one unknown program path. */
+    changeAddsMembership?: (location: string, filename: string) => boolean;
+
+    /**
+     * The exact-input trackers' event decision. When present it is the only
+     * filter applied.
+     */
+    classify?: (
+      location: string,
+      filename: string | null,
+      eventType: string,
+    ) => "change" | "mutation" | undefined;
+
+    /** Whether a named event can change compiler-consumed content. */
+    content?: (location: string, filename: string) => boolean;
+
+    /**
+     * Whether a named event can be a program membership change, for the
+     * project-directory tracker, which watches whole directories and so has to
+     * narrow what it hears.
+     */
+    membership?: (location: string, filename: string) => boolean;
+  } = {},
+): WatchBrokerSink {
+  return {
+    event(directory, filename, eventType) {
+      const changed =
+        filename === null ? directory : path.join(directory, filename);
+      if (filters.classify !== undefined) {
+        const verdict = filters.classify(directory, filename, eventType);
+        if (verdict === "mutation") recordProjectMutation(tracker, changed);
+        else if (verdict === "change") recordProjectChange(tracker, changed);
+        return;
+      }
+      if (filename !== null && filters.membership !== undefined) {
+        if (
+          filters.membership(directory, filename) &&
+          (eventType === "rename" ||
+            filters.changeAddsMembership?.(directory, filename) === true)
+        ) {
+          recordProjectMutation(tracker, changed);
+          return;
+        }
+        if (
+          eventType !== "rename" &&
+          filters.content?.(directory, filename) === true
+        ) {
+          recordProjectChange(tracker, changed);
+        }
+        return;
+      }
+      recordProjectMutation(tracker, changed);
+    },
+    failed() {
+      tracker.failed = true;
+    },
+    gap() {
+      tracker.unverified = true;
+    },
+    unattributed() {
+      tracker.membershipChanged = true;
+    },
+    unproven(directories) {
+      if (directories === undefined) delete tracker.unproven;
+      else tracker.unproven = directories;
+    },
+  };
+}

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

@@ -0,0 +1,146 @@
+import { WATCH_PROBE_TIMEOUT_MS } from "./WATCH_PROBE_TIMEOUT_MS";
+import type { WatchBroker } from "./WatchBroker";
+
+/**
+ * Ask the watch broker to acknowledge, and resolve with whether it did.
+ *
+ * The child answers after two turns of its own loop, so a watch callback it had
+ * already queued has run, and the ordered IPC channel puts every message it
+ * sent before the reply ahead of the reply. That is the same proof an
+ * in-process watcher gets from a macrotask turn, rather than the fixed wait
+ * this replaces, which guessed at the crossing (samchon/ttsc#1272). On macOS
+ * the child answers once each stream it can prove has delivered a probe, which
+ * takes the service's latency (samchon/ttsc#1453).
+ *
+ * A broker that never answers must not hold a delivery, so the wait gives up
+ * after a threshold of twice the probe timeout: the child itself gives up on a
+ * stream that does not deliver within one. Scheduling or IPC delay can also
+ * exhaust the parent's wait; timeout does not establish a dead child or a
+ * permanently incapable backend. It resolves `false` then, and when the broker
+ * dies, since an event may still be in flight: the caller must not read the
+ * trackers' silence as proof (samchon/ttsc#1428). It used to give up after 10
+ * ms and resolve as if answered, so a busy host or a child forwarding a burst
+ * lost the edit a delivery was about to serve.
+ *
+ * A reply speaks only for the registrations the child held when the request
+ * reached it, which are those registered before the request was sent. A
+ * registration opened after an in-flight drain was sent therefore does not
+ * share it: its watches were never probed by that drain, so it starts one that
+ * covers it (samchon/ttsc#1546). A caller without a registration id can join
+ * the current drain without this coverage check. Sharing keeps that request's
+ * original timeout; a later override does not reset it. Timer thresholds
+ * require event-loop progress and are not global wall-time guarantees.
+ * Exceptional native/ref/send work can reject the request rather than supplying
+ * an acknowledgment.
+ *
+ * @param timeout How long to wait for the reply; the default is what the child
+ *   is given plus the same again, and a test of the wait itself passes less.
+ * @param registration The registration asking, when one is; it shares the
+ *   in-flight drain only when that drain covers it.
+ * @evidence contracts/common.md#principled-implementation
+ *   Id-bound replies establish ordering only for the snapshot of registrations
+ *   held before submission; timeout withdraws proof rather than certifying silence.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One scope snapshot and shared promise represent the current barrier;
+ *   startWatchBrokerDrain owns request bookkeeping and idempotent release.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Later registrations need a covering drain; a deadline cannot manufacture
+ *   native acknowledgment or be replaced with an arbitrary fixed-delay success.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs and parameters explain ordering, coverage, sharing and
+ *   false deadlines under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral host delivery delegates Windows loop ordering and macOS stream
+ *   probing to the native broker rather than applying one universal timing guess.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   A covering memo query uses fixed identity/id lookup. New requests copy all N
+ *   registration pairs before filtering draining ids into a scope, then create
+ *   timer/promise/IPC state. The child still scans its registration streams and
+ *   writes shared namespace probes; reply routing scans unproven entries and
+ *   live registrations. Native/IPC/callback and total scope populations remain
+ *   delegated work beyond parent-map lookup; no project file walk occurs here.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Scoped callers share a current request only when its snapshot contains their
+ *   id; unscoped callers join without that check. The original request's timeout
+ *   governs all sharers. Ordered IPC and child proof own the acknowledgment;
+ *   finally clears only its still-current promise, preserving a newer request.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Each request retains an id/scope/timer/release closure and increments shared
+ *   pending demand; refs are flags, not independently counted native handles.
+ *   Completed reply/timeout/exit release clears scope/timer and permits unref
+ *   when all requests/openings finish. Uncovered calls can create uncapped
+ *   outstanding requests with storage driven by the sum of their scope sizes.
+ *   Scheduling/native or callback exceptions can delay/interrupt settlement;
+ *   there is no caller cancellation or hard wall-time guarantee here.
+ */
+export function drainWatchBroker(
+  broker: WatchBroker,
+  timeout: number = 2 * WATCH_PROBE_TIMEOUT_MS,
+  registration?: number,
+): Promise<boolean> {
+  // A covering registration shares the current round-trip. A later uncovered
+  // registration needs its own request rather than inheriting that proof.
+  if (
+    broker.draining !== undefined &&
+    (registration === undefined ||
+      broker.drainingScope?.has(registration) === true)
+  ) {
+    return broker.draining;
+  }
+  const scope = new Set(
+    [...broker.registrations]
+      .filter(([, entry]) => entry.drains)
+      .map(([id]) => id),
+  );
+  const draining: Promise<boolean> = startWatchBrokerDrain(
+    broker,
+    timeout,
+    scope,
+  ).finally(() => {
+    if (broker.draining === draining) {
+      broker.draining = undefined;
+      broker.drainingScope = undefined;
+    }
+  });
+  broker.draining = draining;
+  broker.drainingScope = scope;
+  return draining;
+}
+
+function startWatchBrokerDrain(
+  broker: WatchBroker,
+  timeout: number,
+  scope: ReadonlySet<number>,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const id = broker.nextId++;
+    let settled = false;
+    const release = (answered: boolean): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      broker.drains.delete(id);
+      broker.drainScopes?.delete(id);
+      broker.pendingDrains -= 1;
+      if (broker.pendingDrains === 0 && broker.pendingRegistrations === 0) {
+        broker.child.unref();
+        broker.child.channel?.unref?.();
+      }
+      resolve(answered);
+    };
+    // Hold the channel open while the acknowledgement is outstanding. The
+    // broker is unreferenced between requests so it never keeps a host alive,
+    // and a reply is the only thing this promise can be resolved by: without
+    // the reference the loop can empty while a delivery waits here, and the
+    // process exits mid-build with nothing to report.
+    broker.pendingDrains += 1;
+    broker.child.ref();
+    broker.child.channel?.ref?.();
+    const timer = setTimeout(() => release(false), timeout);
+    broker.drains.set(id, release);
+    (broker.drainScopes ??= new Map()).set(id, scope);
+    if (broker.child.send?.({ id, op: "drain" }) !== true) {
+      release(false);
+    }
+  });
+}

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

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+
+/**
+ * Where the `fsevents` binding the watch broker loads on macOS is, or `null`
+ * when resolution fails. This does not establish successful native loading or
+ * uniquely identify an omitted optional installation.
+ *
+ * The binding is an optional dependency of this package, which npm, pnpm, and
+ * Yarn install on macOS unless told to skip optional dependencies. It is
+ * resolved from this copy of the package, however the host loaded it, since
+ * Rollup rewrites `import.meta.url` for the CommonJS and ES module builds
+ * alike. The broker's child loads it by this path, and reports every macOS
+ * registration failed when there is none, since a watch through `fs.watch`
+ * there can lose events without notice.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Package-relative module resolution selects the optional binding installed
+ *   with this package; absence returns null rather than an untrusted fallback.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A single resolver boundary returns a path or absence; child startup owns
+ *   loading it and reporting unusable registrations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Resolution uses createRequire instead of assumed node_modules layouts or
+ *   a fallback watcher whose dropped-event contract cannot supply this proof.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain optional installation, package-relative
+ *   resolution and the refusal reason, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral resolution delegates installation layout and path spelling to
+ *   the module resolver; native FSEvents loading stays at the macOS boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; it returns a path or null.
+ * @evidence contracts/performance.md#efficient-algorithms Package-relative createRequire/resolve delegates module/export/layout lookup and native metadata/path work to Node's resolver. Search depth, package metadata and spelling bytes contribute to cold cost; resolver-owned caches can avoid repeated lookup work without a duration bound from one call. No project tree is enumerated here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Resolved once per broker start; the broker itself is process-wide.
+ */
+export function fseventsBindingPath(): string | null {
+  try {
+    return createRequire(import.meta.url).resolve("fsevents");
+  } catch {
+    return null;
+  }
+}