@ttsc/unplugin 0.30.4 → 0.31.0

package/lib/core/transform/tracker/broker/openBrokeredWatch.js

@@ -0,0 +1,264 @@
+'use strict';
+
+var fs = require('node:fs');
+var path = require('node:path');
+var WATCH_BROKER = require('./WATCH_BROKER.js');
+var WATCH_PROBE_DIRECTORY_PREFIX = require('./WATCH_PROBE_DIRECTORY_PREFIX.js');
+var WATCH_PROBE_TIMEOUT_MS = require('./WATCH_PROBE_TIMEOUT_MS.js');
+var drainWatchBroker = require('./drainWatchBroker.js');
+var getWatchBroker = require('./getWatchBroker.js');
+var probeForLocation = require('./probeForLocation.js');
+var sweepAbandonedWatchProbes = require('./sweepAbandonedWatchProbes.js');
+
+/**
+ * Open directory watches in the isolated watch process for one sink, and report
+ * when they hear.
+ *
+ * On Windows, Node's fs-event backend can assert in native code when a watched
+ * temporary tree is deleted. Isolation turns that unrecoverable process abort
+ * into an ordinary broker exit and a conservative fallback in the host. On
+ * macOS, each registration's watches are streams of their own, started before
+ * the child reports ready, and a dropped event reaches the sink as a gap
+ * (samchon/ttsc#1425). A stream that can be probed reports ready only once its
+ * opening probe came back through it; the child suppresses ordinary callbacks
+ * received before that probe. This is its backend protocol, not a guarantee
+ * that every native mutation has a distinct or timely event.
+ *
+ * The one registration path of the broker. A generation's tracker registers
+ * through it with a sink that records witnesses (`brokeredTrackerSink`), and an
+ * input observer's scope with a sink that forwards events
+ * (`openIsolatedRecursiveWatch`); the child and the routing of its messages
+ * (`routeWatchBrokerMessage`) are the same for both.
+ *
+ * @param locations The directories to watch, as the caller spells them.
+ * @param options.allEvents Whether `change` events are wanted, or renames
+ *   alone.
+ * @param options.drains Whether the registration takes part in drains, and so
+ *   hears each drain's verdict on its watches.
+ * @param options.filesystem The filesystem the canonical directories are read
+ *   through.
+ * @param options.probeRoot The project root, below whose tool cache the broker
+ *   may write probes that prove a location's stream delivered
+ *   (samchon/ttsc#1453). A location outside it cannot be proven that way.
+ * @param options.sink Where the registration's messages go.
+ * @returns `ready`, which ends the opening wait on acknowledgment, failed
+ *   timeout or explicit closure without itself certifying success; `close`,
+ *   which removes the registration and retires the broker after its last one,
+ *   and throws the first cleanup failure; and `drain`, the broker's barrier.
+ * @evidence contracts/common.md#principled-implementation
+ *   Opening paths map back to caller spellings, using native realpath or lexical
+ *   fallback; duplicate resolved directories keep the last caller spelling.
+ *   Readiness completes a wait, while native probe/failure authority stays with
+ *   the child and sink rather than being certified by Promise resolution.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This single registration path serves trackers and forwarding observers;
+ *   child routing and owner event interpretation remain separate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Failed probe preparation withdraws only probe proof, not invented watch
+ *   success; native failures stay isolated rather than patching fs.watch.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs, parameters and return comments explain isolation, probe
+ *   eligibility, deadlines and cleanup failures under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Supplied realpath or native absolute fallback represents directories to the
+ *   child; callers must describe the same native view that child watches.
+ *   Fallback spelling is not physical proof. Optional IPC ref methods support
+ *   compatible runtimes without mutating their channel API.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   N locations are mapped with native realpath/fallback, spelling text and
+ *   optional root/probe eligibility work; repeated probe roots still resolve
+ *   before namespace memo lookup. Cold namespaces create cache parents and
+ *   sweep their entries/subtrees. Normalized locations/spelling maps and IPC
+ *   encoding grow with locations/names/text, while child startup and actual
+ *   backend watcher/probe work remain delegated costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   This loaded adapter's broker serves independent sinks. Exact lexical probe
+ *   roots share prepared namespace addresses, not proof of continued access or
+ *   successful native opening. Backend proof remains current, and drain sharing
+ *   uses each request's covered scope rather than registration existence alone.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A returned handle owns a registration/ready wait; completed acknowledgment,
+ *   timeout or close permits finally to clear the timer and pending reference.
+ *   Close removes registration then attempts send/disconnect/kill independently,
+ *   without certifying child exit. Synchronous setup/native or sink exceptions
+ *   can interrupt before a handle or settlement is returned; no rollback or
+ *   caller cancellation deadline is provided here. Namespace addresses persist
+ *   by distinct historical lexical roots until exit cleanup is attempted, with
+ *   no count/byte cap or guarantee under failed/abrupt native cleanup.
+ */
+function openBrokeredWatch(locations, options) {
+    const broker = getWatchBroker.getWatchBroker();
+    // The child watches canonical directories, and reports its events under that
+    // spelling. Everything else in the adapter speaks the caller's own spelling,
+    // which on Windows can be an 8.3 short form of the same directory, so keep
+    // the way back: a filter that compared the child's spelling against the
+    // configuration's would be comparing two names for one directory that share
+    // no common prefix (samchon/ttsc#1307).
+    const spellings = new Map();
+    const normalized = locations.map((location) => {
+        let directory;
+        try {
+            directory = options.filesystem.realpath(location.directory);
+        }
+        catch {
+            directory = path.resolve(location.directory);
+        }
+        spellings.set(directory, location.directory);
+        // A probe proves only a backend that writes one, FSEvents, and one whose
+        // directory cannot be prepared, below a read-only `node_modules`, leaves
+        // the location unproven rather than the watch failed, as a probe the child
+        // cannot write does (samchon/ttsc#1480).
+        let probe;
+        try {
+            probe = broker.probes
+                ? probeForLocation.probeForLocation(directory, options.probeRoot, probeDirectory, options.filesystem)
+                : undefined;
+        }
+        catch {
+            probe = undefined;
+        }
+        return {
+            directory,
+            ...(location.names === undefined ? {} : { names: location.names }),
+            ...(location.recursive === true ? { recursive: true } : {}),
+            ...(probe === undefined ? {} : { probe }),
+        };
+    });
+    broker.pendingRegistrations += 1;
+    broker.child.ref();
+    // Bun's IPC channel omits Node's Control.ref/unref methods. The child itself
+    // still owns the outstanding acknowledgement on that runtime.
+    broker.child.channel?.ref?.();
+    const id = broker.nextId++;
+    let resolveReady;
+    const answered = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    broker.registrations.set(id, {
+        drains: options.drains,
+        ready: resolveReady,
+        sink: options.sink,
+        spellings,
+    });
+    const close = () => {
+        const active = broker.registrations.get(id);
+        if (active === undefined)
+            return;
+        broker.registrations.delete(id);
+        active.ready();
+        let failed = false;
+        let failure;
+        try {
+            broker.child.send?.({ id, op: "remove" });
+        }
+        catch (error) {
+            failed = true;
+            failure = error;
+        }
+        if (broker.registrations.size === 0) {
+            if (WATCH_BROKER.WATCH_BROKER.current === broker) {
+                WATCH_BROKER.WATCH_BROKER.current = undefined;
+            }
+            try {
+                broker.child.disconnect?.();
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+            try {
+                broker.child.kill();
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+        if (failed)
+            throw failure;
+    };
+    broker.child.send?.({
+        allEvents: options.allEvents,
+        locations: normalized,
+        id,
+        op: "add",
+    });
+    let timer;
+    const ready = Promise.race([
+        answered,
+        new Promise((resolve) => {
+            timer = setTimeout(() => {
+                // Nothing heard within the probe timeout: the watches cannot prove
+                // they deliver, so they are given up rather than awaited further.
+                if (broker.registrations.get(id) !== undefined) {
+                    options.sink.failed();
+                    try {
+                        close();
+                    }
+                    catch {
+                        // The child is already gone; the watches are failed either way.
+                    }
+                }
+                resolve();
+            }, WATCH_PROBE_TIMEOUT_MS.WATCH_PROBE_TIMEOUT_MS);
+        }),
+    ]).finally(() => {
+        clearTimeout(timer);
+        broker.pendingRegistrations -= 1;
+        // `ref`/`unref` is a flag rather than a counter, so this must not clear a
+        // reference an in-flight acknowledgement is holding: a delivery waiting on
+        // a reply over an unreferenced channel lets the loop empty and the process
+        // exit mid-build.
+        if (broker.pendingRegistrations === 0 && broker.pendingDrains === 0) {
+            broker.child.unref();
+            broker.child.channel?.unref?.();
+        }
+    });
+    return {
+        close,
+        drain: () => drainWatchBroker.drainWatchBroker(broker, undefined, id),
+        ready,
+    };
+}
+/** Probe directories already prepared by this process, by project root. */
+const PROBE_DIRECTORIES = new Map();
+/**
+ * The directory below `probeRoot`'s tool cache where the broker writes its
+ * probes, named after this process so a later process can remove it once this
+ * one is gone (`WATCH_PROBE_DIRECTORY_PREFIX`). It is removed when this process
+ * exits, and a stale one is swept before it is named.
+ *
+ * One exit listener removes every probe directory of the process: a listener
+ * per project root would add one for each project a process watches, past the
+ * count at which Node warns of a leak.
+ */
+function probeDirectory(probeRoot) {
+    const existing = PROBE_DIRECTORIES.get(probeRoot);
+    if (existing !== undefined)
+        return existing;
+    const parent = path.join(probeRoot, "node_modules", ".cache", "ttsc");
+    fs.mkdirSync(parent, { recursive: true });
+    sweepAbandonedWatchProbes.sweepAbandonedWatchProbes(parent);
+    const directory = path.join(parent, `${WATCH_PROBE_DIRECTORY_PREFIX.WATCH_PROBE_DIRECTORY_PREFIX}${process.pid}`);
+    if (PROBE_DIRECTORIES.size === 0) {
+        process.once("exit", () => {
+            for (const opened of PROBE_DIRECTORIES.values()) {
+                try {
+                    fs.rmSync(opened, { force: true, recursive: true });
+                }
+                catch {
+                    // A directory left behind is swept by the next process to probe.
+                }
+            }
+        });
+    }
+    PROBE_DIRECTORIES.set(probeRoot, directory);
+    return directory;
+}
+
+exports.openBrokeredWatch = openBrokeredWatch;
+//# sourceMappingURL=openBrokeredWatch.js.map

package/lib/core/transform/tracker/broker/openBrokeredWatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openBrokeredWatch.js","sources":["../../../../../src/core/transform/tracker/broker/openBrokeredWatch.ts"],"sourcesContent":[null],"names":["getWatchBroker","probeForLocation","WATCH_BROKER","WATCH_PROBE_TIMEOUT_MS","drainWatchBroker","sweepAbandonedWatchProbes","WATCH_PROBE_DIRECTORY_PREFIX"],"mappings":";;;;;;;;;;;;AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EG;AACG,SAAU,iBAAiB,CAC/B,SAAyC,EACzC,OAMC,EAAA;AAMD,IAAA,MAAM,MAAM,GAAGA,6BAAc,EAAE;;;;;;;AAO/B,IAAA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB;IAC3C,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,KAAI;AAC5C,QAAA,IAAI,SAAiB;AACrB,QAAA,IAAI;YACF,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC7D;AAAE,QAAA,MAAM;YACN,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC9C;QACA,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC;;;;;AAK5C,QAAA,IAAI,KAA0C;AAC9C,QAAA,IAAI;YACF,KAAK,GAAG,MAAM,CAAC;AACb,kBAAEC,iCAAgB,CACd,SAAS,EACT,OAAO,CAAC,SAAS,EACjB,cAAc,EACd,OAAO,CAAC,UAAU;kBAEpB,SAAS;QACf;AAAE,QAAA,MAAM;YACN,KAAK,GAAG,SAAS;QACnB;QACA,OAAO;YACL,SAAS;YACT,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;AAClE,YAAA,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAC3D,YAAA,IAAI,KAAK,KAAK,SAAS,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;SAC1C;AACH,IAAA,CAAC,CAAC;AACF,IAAA,MAAM,CAAC,oBAAoB,IAAI,CAAC;AAChC,IAAA,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;;;IAGlB,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI;AAC7B,IAAA,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE;AAC1B,IAAA,IAAI,YAAyB;IAC7B,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,KAAI;QAC7C,YAAY,GAAG,OAAO;AACxB,IAAA,CAAC,CAAC;AACF,IAAA,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE;QAC3B,MAAM,EAAE,OAAO,CAAC,MAAM;AACtB,QAAA,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS;AACV,KAAA,CAAC;IACF,MAAM,KAAK,GAAG,MAAW;QACvB,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3C,IAAI,MAAM,KAAK,SAAS;YAAE;AAC1B,QAAA,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,EAAE;QACd,IAAI,MAAM,GAAG,KAAK;AAClB,QAAA,IAAI,OAAgB;AACpB,QAAA,IAAI;AACF,YAAA,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC;QAC3C;QAAE,OAAO,KAAK,EAAE;YACd,MAAM,GAAG,IAAI;YACb,OAAO,GAAG,KAAK;QACjB;QACA,IAAI,MAAM,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,EAAE;AACnC,YAAA,IAAIC,yBAAY,CAAC,OAAO,KAAK,MAAM,EAAE;AACnC,gBAAAA,yBAAY,CAAC,OAAO,GAAG,SAAS;YAClC;AACA,YAAA,IAAI;AACF,gBAAA,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI;YAC7B;YAAE,OAAO,KAAK,EAAE;gBACd,IAAI,CAAC,MAAM,EAAE;oBACX,MAAM,GAAG,IAAI;oBACb,OAAO,GAAG,KAAK;gBACjB;YACF;AACA,YAAA,IAAI;AACF,gBAAA,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE;YACrB;YAAE,OAAO,KAAK,EAAE;gBACd,IAAI,CAAC,MAAM,EAAE;oBACX,MAAM,GAAG,IAAI;oBACb,OAAO,GAAG,KAAK;gBACjB;YACF;QACF;AACA,QAAA,IAAI,MAAM;AAAE,YAAA,MAAM,OAAO;AAC3B,IAAA,CAAC;AACD,IAAA,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG;QAClB,SAAS,EAAE,OAAO,CAAC,SAAS;AAC5B,QAAA,SAAS,EAAE,UAAU;QACrB,EAAE;AACF,QAAA,EAAE,EAAE,KAAK;AACV,KAAA,CAAC;AACF,IAAA,IAAI,KAAiC;AACrC,IAAA,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,QAAQ;AACR,QAAA,IAAI,OAAO,CAAO,CAAC,OAAO,KAAI;AAC5B,YAAA,KAAK,GAAG,UAAU,CAAC,MAAK;;;gBAGtB,IAAI,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,SAAS,EAAE;AAC9C,oBAAA,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE;AACrB,oBAAA,IAAI;AACF,wBAAA,KAAK,EAAE;oBACT;AAAE,oBAAA,MAAM;;oBAER;gBACF;AACA,gBAAA,OAAO,EAAE;YACX,CAAC,EAAEC,6CAAsB,CAAC;AAC5B,QAAA,CAAC,CAAC;AACH,KAAA,CAAC,CAAC,OAAO,CAAC,MAAK;QACd,YAAY,CAAC,KAAK,CAAC;AACnB,QAAA,MAAM,CAAC,oBAAoB,IAAI,CAAC;;;;;AAKhC,QAAA,IAAI,MAAM,CAAC,oBAAoB,KAAK,CAAC,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,EAAE;AACnE,YAAA,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE;YACpB,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,IAAI;QACjC;AACF,IAAA,CAAC,CAAC;IACF,OAAO;QACL,KAAK;QACL,KAAK,EAAE,MAAMC,iCAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;QACpD,KAAK;KACN;AACH;AAEA;AACA,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB;AAEnD;;;;;;;;;AASG;AACH,SAAS,cAAc,CAAC,SAAiB,EAAA;IACvC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC;IACjD,IAAI,QAAQ,KAAK,SAAS;AAAE,QAAA,OAAO,QAAQ;AAC3C,IAAA,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,CAAC;IACrE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACzCC,mDAAyB,CAAC,MAAM,CAAC;AACjC,IAAA,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CACzB,MAAM,EACN,CAAA,EAAGC,yDAA4B,GAAG,OAAO,CAAC,GAAG,CAAA,CAAE,CAChD;AACD,IAAA,IAAI,iBAAiB,CAAC,IAAI,KAAK,CAAC,EAAE;AAChC,QAAA,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAK;YACxB,KAAK,MAAM,MAAM,IAAI,iBAAiB,CAAC,MAAM,EAAE,EAAE;AAC/C,gBAAA,IAAI;AACF,oBAAA,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;gBACrD;AAAE,gBAAA,MAAM;;gBAER;YACF;AACF,QAAA,CAAC,CAAC;IACJ;AACA,IAAA,iBAAiB,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC;AAC3C,IAAA,OAAO,SAAS;AAClB;;;;"}

package/lib/core/transform/tracker/broker/openBrokeredWatch.mjs

@@ -0,0 +1,262 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { WATCH_BROKER } from './WATCH_BROKER.mjs';
+import { WATCH_PROBE_DIRECTORY_PREFIX } from './WATCH_PROBE_DIRECTORY_PREFIX.mjs';
+import { WATCH_PROBE_TIMEOUT_MS } from './WATCH_PROBE_TIMEOUT_MS.mjs';
+import { drainWatchBroker } from './drainWatchBroker.mjs';
+import { getWatchBroker } from './getWatchBroker.mjs';
+import { probeForLocation } from './probeForLocation.mjs';
+import { sweepAbandonedWatchProbes } from './sweepAbandonedWatchProbes.mjs';
+
+/**
+ * Open directory watches in the isolated watch process for one sink, and report
+ * when they hear.
+ *
+ * On Windows, Node's fs-event backend can assert in native code when a watched
+ * temporary tree is deleted. Isolation turns that unrecoverable process abort
+ * into an ordinary broker exit and a conservative fallback in the host. On
+ * macOS, each registration's watches are streams of their own, started before
+ * the child reports ready, and a dropped event reaches the sink as a gap
+ * (samchon/ttsc#1425). A stream that can be probed reports ready only once its
+ * opening probe came back through it; the child suppresses ordinary callbacks
+ * received before that probe. This is its backend protocol, not a guarantee
+ * that every native mutation has a distinct or timely event.
+ *
+ * The one registration path of the broker. A generation's tracker registers
+ * through it with a sink that records witnesses (`brokeredTrackerSink`), and an
+ * input observer's scope with a sink that forwards events
+ * (`openIsolatedRecursiveWatch`); the child and the routing of its messages
+ * (`routeWatchBrokerMessage`) are the same for both.
+ *
+ * @param locations The directories to watch, as the caller spells them.
+ * @param options.allEvents Whether `change` events are wanted, or renames
+ *   alone.
+ * @param options.drains Whether the registration takes part in drains, and so
+ *   hears each drain's verdict on its watches.
+ * @param options.filesystem The filesystem the canonical directories are read
+ *   through.
+ * @param options.probeRoot The project root, below whose tool cache the broker
+ *   may write probes that prove a location's stream delivered
+ *   (samchon/ttsc#1453). A location outside it cannot be proven that way.
+ * @param options.sink Where the registration's messages go.
+ * @returns `ready`, which ends the opening wait on acknowledgment, failed
+ *   timeout or explicit closure without itself certifying success; `close`,
+ *   which removes the registration and retires the broker after its last one,
+ *   and throws the first cleanup failure; and `drain`, the broker's barrier.
+ * @evidence contracts/common.md#principled-implementation
+ *   Opening paths map back to caller spellings, using native realpath or lexical
+ *   fallback; duplicate resolved directories keep the last caller spelling.
+ *   Readiness completes a wait, while native probe/failure authority stays with
+ *   the child and sink rather than being certified by Promise resolution.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This single registration path serves trackers and forwarding observers;
+ *   child routing and owner event interpretation remain separate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Failed probe preparation withdraws only probe proof, not invented watch
+ *   success; native failures stay isolated rather than patching fs.watch.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs, parameters and return comments explain isolation, probe
+ *   eligibility, deadlines and cleanup failures under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Supplied realpath or native absolute fallback represents directories to the
+ *   child; callers must describe the same native view that child watches.
+ *   Fallback spelling is not physical proof. Optional IPC ref methods support
+ *   compatible runtimes without mutating their channel API.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   N locations are mapped with native realpath/fallback, spelling text and
+ *   optional root/probe eligibility work; repeated probe roots still resolve
+ *   before namespace memo lookup. Cold namespaces create cache parents and
+ *   sweep their entries/subtrees. Normalized locations/spelling maps and IPC
+ *   encoding grow with locations/names/text, while child startup and actual
+ *   backend watcher/probe work remain delegated costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   This loaded adapter's broker serves independent sinks. Exact lexical probe
+ *   roots share prepared namespace addresses, not proof of continued access or
+ *   successful native opening. Backend proof remains current, and drain sharing
+ *   uses each request's covered scope rather than registration existence alone.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A returned handle owns a registration/ready wait; completed acknowledgment,
+ *   timeout or close permits finally to clear the timer and pending reference.
+ *   Close removes registration then attempts send/disconnect/kill independently,
+ *   without certifying child exit. Synchronous setup/native or sink exceptions
+ *   can interrupt before a handle or settlement is returned; no rollback or
+ *   caller cancellation deadline is provided here. Namespace addresses persist
+ *   by distinct historical lexical roots until exit cleanup is attempted, with
+ *   no count/byte cap or guarantee under failed/abrupt native cleanup.
+ */
+function openBrokeredWatch(locations, options) {
+    const broker = getWatchBroker();
+    // The child watches canonical directories, and reports its events under that
+    // spelling. Everything else in the adapter speaks the caller's own spelling,
+    // which on Windows can be an 8.3 short form of the same directory, so keep
+    // the way back: a filter that compared the child's spelling against the
+    // configuration's would be comparing two names for one directory that share
+    // no common prefix (samchon/ttsc#1307).
+    const spellings = new Map();
+    const normalized = locations.map((location) => {
+        let directory;
+        try {
+            directory = options.filesystem.realpath(location.directory);
+        }
+        catch {
+            directory = path.resolve(location.directory);
+        }
+        spellings.set(directory, location.directory);
+        // A probe proves only a backend that writes one, FSEvents, and one whose
+        // directory cannot be prepared, below a read-only `node_modules`, leaves
+        // the location unproven rather than the watch failed, as a probe the child
+        // cannot write does (samchon/ttsc#1480).
+        let probe;
+        try {
+            probe = broker.probes
+                ? probeForLocation(directory, options.probeRoot, probeDirectory, options.filesystem)
+                : undefined;
+        }
+        catch {
+            probe = undefined;
+        }
+        return {
+            directory,
+            ...(location.names === undefined ? {} : { names: location.names }),
+            ...(location.recursive === true ? { recursive: true } : {}),
+            ...(probe === undefined ? {} : { probe }),
+        };
+    });
+    broker.pendingRegistrations += 1;
+    broker.child.ref();
+    // Bun's IPC channel omits Node's Control.ref/unref methods. The child itself
+    // still owns the outstanding acknowledgement on that runtime.
+    broker.child.channel?.ref?.();
+    const id = broker.nextId++;
+    let resolveReady;
+    const answered = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    broker.registrations.set(id, {
+        drains: options.drains,
+        ready: resolveReady,
+        sink: options.sink,
+        spellings,
+    });
+    const close = () => {
+        const active = broker.registrations.get(id);
+        if (active === undefined)
+            return;
+        broker.registrations.delete(id);
+        active.ready();
+        let failed = false;
+        let failure;
+        try {
+            broker.child.send?.({ id, op: "remove" });
+        }
+        catch (error) {
+            failed = true;
+            failure = error;
+        }
+        if (broker.registrations.size === 0) {
+            if (WATCH_BROKER.current === broker) {
+                WATCH_BROKER.current = undefined;
+            }
+            try {
+                broker.child.disconnect?.();
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+            try {
+                broker.child.kill();
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+        if (failed)
+            throw failure;
+    };
+    broker.child.send?.({
+        allEvents: options.allEvents,
+        locations: normalized,
+        id,
+        op: "add",
+    });
+    let timer;
+    const ready = Promise.race([
+        answered,
+        new Promise((resolve) => {
+            timer = setTimeout(() => {
+                // Nothing heard within the probe timeout: the watches cannot prove
+                // they deliver, so they are given up rather than awaited further.
+                if (broker.registrations.get(id) !== undefined) {
+                    options.sink.failed();
+                    try {
+                        close();
+                    }
+                    catch {
+                        // The child is already gone; the watches are failed either way.
+                    }
+                }
+                resolve();
+            }, WATCH_PROBE_TIMEOUT_MS);
+        }),
+    ]).finally(() => {
+        clearTimeout(timer);
+        broker.pendingRegistrations -= 1;
+        // `ref`/`unref` is a flag rather than a counter, so this must not clear a
+        // reference an in-flight acknowledgement is holding: a delivery waiting on
+        // a reply over an unreferenced channel lets the loop empty and the process
+        // exit mid-build.
+        if (broker.pendingRegistrations === 0 && broker.pendingDrains === 0) {
+            broker.child.unref();
+            broker.child.channel?.unref?.();
+        }
+    });
+    return {
+        close,
+        drain: () => drainWatchBroker(broker, undefined, id),
+        ready,
+    };
+}
+/** Probe directories already prepared by this process, by project root. */
+const PROBE_DIRECTORIES = new Map();
+/**
+ * The directory below `probeRoot`'s tool cache where the broker writes its
+ * probes, named after this process so a later process can remove it once this
+ * one is gone (`WATCH_PROBE_DIRECTORY_PREFIX`). It is removed when this process
+ * exits, and a stale one is swept before it is named.
+ *
+ * One exit listener removes every probe directory of the process: a listener
+ * per project root would add one for each project a process watches, past the
+ * count at which Node warns of a leak.
+ */
+function probeDirectory(probeRoot) {
+    const existing = PROBE_DIRECTORIES.get(probeRoot);
+    if (existing !== undefined)
+        return existing;
+    const parent = path.join(probeRoot, "node_modules", ".cache", "ttsc");
+    fs.mkdirSync(parent, { recursive: true });
+    sweepAbandonedWatchProbes(parent);
+    const directory = path.join(parent, `${WATCH_PROBE_DIRECTORY_PREFIX}${process.pid}`);
+    if (PROBE_DIRECTORIES.size === 0) {
+        process.once("exit", () => {
+            for (const opened of PROBE_DIRECTORIES.values()) {
+                try {
+                    fs.rmSync(opened, { force: true, recursive: true });
+                }
+                catch {
+                    // A directory left behind is swept by the next process to probe.
+                }
+            }
+        });
+    }
+    PROBE_DIRECTORIES.set(probeRoot, directory);
+    return directory;
+}
+
+export { openBrokeredWatch };
+//# sourceMappingURL=openBrokeredWatch.mjs.map

package/lib/core/transform/tracker/broker/openBrokeredWatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openBrokeredWatch.mjs","sources":["../../../../../src/core/transform/tracker/broker/openBrokeredWatch.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/lib/core/transform/tracker/broker/probeForLocation.d.cts

@@ -0,0 +1,42 @@
+import type { TtscTransformFilesystemOperations } from "../../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * The probe a brokered watch location carries, when the probe root contains it
+ * (samchon/ttsc#1453, samchon/ttsc#1454).
+ *
+ * The caller resolves each location when possible, while the project root can
+ * retain a linked workspace or temporary-directory spelling. Resolving the root
+ * as well permits containment comparison in the same native name domain. A
+ * failed root realpath falls back to native absolute spelling and does not
+ * establish physical containment. The returned address retains the root's
+ * spelling for the child's relative translation; preparing a namespace does not
+ * prove that the backend delivered its probe.
+ *
+ * @param directory The caller's resolved location, with its lexical fallback.
+ * @param probeRoot The project root as the adapter names it, or `undefined`
+ *   when the tracker has no root to probe below.
+ * @param probeDirectory The probe directory below `probeRoot`.
+ * @param filesystem The filesystem the canonical root is read through.
+ * @evidence contracts/common.md#principled-implementation
+ *   Root/location containment determines probe-address eligibility, not usable
+ *   backend authority. Canonical observations use the supplied native view;
+ *   lexical fallback and subsequent probe delivery still require their owners.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One containment boundary delegates namespace naming/preparation to its
+ *   supplied owner and preserves spelling for the child's relative translation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Missing realpath does not invent a foreign project root; the fallback only
+ *   compares resolved spelling and actual backend probing still must succeed.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs and parameter comments explain alias canonicalization and
+ *   probe ownership under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral code compares the supplied filesystem's realpaths and uses
+ *   node:path containment instead of assuming macOS aliases share a prefix.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; the probe directory it names is owned by openBrokeredWatch.
+ * @evidence contracts/performance.md#efficient-algorithms Root realpath or fallback resolution and containment retain native access/component/text costs. An eligible location also invokes the supplied namespace provider: a warm root lookup differs from cold directory creation, abandoned-probe sweeping and retained-address registration. This eligibility predicate performs no recursive location scan or probe IO itself.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The probe directory is prepared once per project root by openBrokeredWatch; this only decides eligibility.
+ */
+export declare function probeForLocation(directory: string, probeRoot: string | undefined, probeDirectory: (root: string) => string, filesystem: TtscTransformFilesystemOperations): {
+    directory: string;
+    root: string;
+} | undefined;

package/lib/core/transform/tracker/broker/probeForLocation.d.mts

@@ -0,0 +1,42 @@
+import type { TtscTransformFilesystemOperations } from "../../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * The probe a brokered watch location carries, when the probe root contains it
+ * (samchon/ttsc#1453, samchon/ttsc#1454).
+ *
+ * The caller resolves each location when possible, while the project root can
+ * retain a linked workspace or temporary-directory spelling. Resolving the root
+ * as well permits containment comparison in the same native name domain. A
+ * failed root realpath falls back to native absolute spelling and does not
+ * establish physical containment. The returned address retains the root's
+ * spelling for the child's relative translation; preparing a namespace does not
+ * prove that the backend delivered its probe.
+ *
+ * @param directory The caller's resolved location, with its lexical fallback.
+ * @param probeRoot The project root as the adapter names it, or `undefined`
+ *   when the tracker has no root to probe below.
+ * @param probeDirectory The probe directory below `probeRoot`.
+ * @param filesystem The filesystem the canonical root is read through.
+ * @evidence contracts/common.md#principled-implementation
+ *   Root/location containment determines probe-address eligibility, not usable
+ *   backend authority. Canonical observations use the supplied native view;
+ *   lexical fallback and subsequent probe delivery still require their owners.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One containment boundary delegates namespace naming/preparation to its
+ *   supplied owner and preserves spelling for the child's relative translation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Missing realpath does not invent a foreign project root; the fallback only
+ *   compares resolved spelling and actual backend probing still must succeed.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs and parameter comments explain alias canonicalization and
+ *   probe ownership under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral code compares the supplied filesystem's realpaths and uses
+ *   node:path containment instead of assuming macOS aliases share a prefix.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; the probe directory it names is owned by openBrokeredWatch.
+ * @evidence contracts/performance.md#efficient-algorithms Root realpath or fallback resolution and containment retain native access/component/text costs. An eligible location also invokes the supplied namespace provider: a warm root lookup differs from cold directory creation, abandoned-probe sweeping and retained-address registration. This eligibility predicate performs no recursive location scan or probe IO itself.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The probe directory is prepared once per project root by openBrokeredWatch; this only decides eligibility.
+ */
+export declare function probeForLocation(directory: string, probeRoot: string | undefined, probeDirectory: (root: string) => string, filesystem: TtscTransformFilesystemOperations): {
+    directory: string;
+    root: string;
+} | undefined;