@ttsc/unplugin 0.30.4 → 0.31.1

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

@@ -0,0 +1,98 @@
+'use strict';
+
+var path = require('node:path');
+var recordProjectChange = require('../recordProjectChange.js');
+var recordProjectMutation = require('../recordProjectMutation.js');
+
+/**
+ * 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.
+ */
+function brokeredTrackerSink(tracker, filters = {}) {
+    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.recordProjectMutation(tracker, changed);
+                else if (verdict === "change")
+                    recordProjectChange.recordProjectChange(tracker, changed);
+                return;
+            }
+            if (filename !== null && filters.membership !== undefined) {
+                if (filters.membership(directory, filename) &&
+                    (eventType === "rename" ||
+                        filters.changeAddsMembership?.(directory, filename) === true)) {
+                    recordProjectMutation.recordProjectMutation(tracker, changed);
+                    return;
+                }
+                if (eventType !== "rename" &&
+                    filters.content?.(directory, filename) === true) {
+                    recordProjectChange.recordProjectChange(tracker, changed);
+                }
+                return;
+            }
+            recordProjectMutation.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;
+        },
+    };
+}
+
+exports.brokeredTrackerSink = brokeredTrackerSink;
+//# sourceMappingURL=brokeredTrackerSink.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brokeredTrackerSink.js","sources":["../../../../../src/core/transform/tracker/broker/brokeredTrackerSink.ts"],"sourcesContent":[null],"names":["recordProjectMutation","recordProjectChange"],"mappings":";;;;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CG;SACa,mBAAmB,CACjC,OAAmC,EACnC,UAuBI,EAAE,EAAA;IAEN,OAAO;AACL,QAAA,KAAK,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAA;YAClC,MAAM,OAAO,GACX,QAAQ,KAAK,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC;AAChE,YAAA,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE;AAClC,gBAAA,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC;gBAChE,IAAI,OAAO,KAAK,UAAU;AAAE,oBAAAA,2CAAqB,CAAC,OAAO,EAAE,OAAO,CAAC;qBAC9D,IAAI,OAAO,KAAK,QAAQ;AAAE,oBAAAC,uCAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;gBACpE;YACF;YACA,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE;AACzD,gBAAA,IACE,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,QAAQ,CAAC;qBACtC,SAAS,KAAK,QAAQ;AACrB,wBAAA,OAAO,CAAC,oBAAoB,GAAG,SAAS,EAAE,QAAQ,CAAC,KAAK,IAAI,CAAC,EAC/D;AACA,oBAAAD,2CAAqB,CAAC,OAAO,EAAE,OAAO,CAAC;oBACvC;gBACF;gBACA,IACE,SAAS,KAAK,QAAQ;oBACtB,OAAO,CAAC,OAAO,GAAG,SAAS,EAAE,QAAQ,CAAC,KAAK,IAAI,EAC/C;AACA,oBAAAC,uCAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;gBACvC;gBACA;YACF;AACA,YAAAD,2CAAqB,CAAC,OAAO,EAAE,OAAO,CAAC;QACzC,CAAC;QACD,MAAM,GAAA;AACJ,YAAA,OAAO,CAAC,MAAM,GAAG,IAAI;QACvB,CAAC;QACD,GAAG,GAAA;AACD,YAAA,OAAO,CAAC,UAAU,GAAG,IAAI;QAC3B,CAAC;QACD,YAAY,GAAA;AACV,YAAA,OAAO,CAAC,iBAAiB,GAAG,IAAI;QAClC,CAAC;AACD,QAAA,QAAQ,CAAC,WAAW,EAAA;YAClB,IAAI,WAAW,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,QAAQ;;AACjD,gBAAA,OAAO,CAAC,QAAQ,GAAG,WAAW;QACrC,CAAC;KACF;AACH;;;;"}

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

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { recordProjectChange } from '../recordProjectChange.mjs';
+import { recordProjectMutation } from '../recordProjectMutation.mjs';
+
+/**
+ * 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.
+ */
+function brokeredTrackerSink(tracker, filters = {}) {
+    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;
+        },
+    };
+}
+
+export { brokeredTrackerSink };
+//# sourceMappingURL=brokeredTrackerSink.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brokeredTrackerSink.mjs","sources":["../../../../../src/core/transform/tracker/broker/brokeredTrackerSink.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CG;SACa,mBAAmB,CACjC,OAAmC,EACnC,UAuBI,EAAE,EAAA;IAEN,OAAO;AACL,QAAA,KAAK,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAA;YAClC,MAAM,OAAO,GACX,QAAQ,KAAK,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC;AAChE,YAAA,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE;AAClC,gBAAA,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC;gBAChE,IAAI,OAAO,KAAK,UAAU;AAAE,oBAAA,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC;qBAC9D,IAAI,OAAO,KAAK,QAAQ;AAAE,oBAAA,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;gBACpE;YACF;YACA,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE;AACzD,gBAAA,IACE,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,QAAQ,CAAC;qBACtC,SAAS,KAAK,QAAQ;AACrB,wBAAA,OAAO,CAAC,oBAAoB,GAAG,SAAS,EAAE,QAAQ,CAAC,KAAK,IAAI,CAAC,EAC/D;AACA,oBAAA,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC;oBACvC;gBACF;gBACA,IACE,SAAS,KAAK,QAAQ;oBACtB,OAAO,CAAC,OAAO,GAAG,SAAS,EAAE,QAAQ,CAAC,KAAK,IAAI,EAC/C;AACA,oBAAA,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;gBACvC;gBACA;YACF;AACA,YAAA,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC;QACzC,CAAC;QACD,MAAM,GAAA;AACJ,YAAA,OAAO,CAAC,MAAM,GAAG,IAAI;QACvB,CAAC;QACD,GAAG,GAAA;AACD,YAAA,OAAO,CAAC,UAAU,GAAG,IAAI;QAC3B,CAAC;QACD,YAAY,GAAA;AACV,YAAA,OAAO,CAAC,iBAAiB,GAAG,IAAI;QAClC,CAAC;AACD,QAAA,QAAQ,CAAC,WAAW,EAAA;YAClB,IAAI,WAAW,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,QAAQ;;AACjD,gBAAA,OAAO,CAAC,QAAQ,GAAG,WAAW;QACrC,CAAC;KACF;AACH;;;;"}

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

@@ -0,0 +1,74 @@
+import type { WatchBroker } from "./WatchBroker.cjs";
+/**
+ * Ask the watch broker to acknowledge, and resolve with whether it did.
+ *
+ * Windows answers after consuming currently queued native completions to an
+ * observed empty port. macOS answers once each provable stream has delivered a
+ * probe, including the service's latency (#1453). Ordered transport applies
+ * every preceding event before the reply. These are current backend frontiers,
+ * not atomic timestamp classification of concurrent writes. The optional direct
+ * fs.watch program retains its explicit two-turn frontier for protocol tests;
+ * it does not supply Windows production proof (#1719).
+ *
+ * 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 completion-port drainage 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 declare function drainWatchBroker(broker: WatchBroker, timeout?: number, registration?: number): Promise<boolean>;

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

@@ -0,0 +1,74 @@
+import type { WatchBroker } from "./WatchBroker.mjs";
+/**
+ * Ask the watch broker to acknowledge, and resolve with whether it did.
+ *
+ * Windows answers after consuming currently queued native completions to an
+ * observed empty port. macOS answers once each provable stream has delivered a
+ * probe, including the service's latency (#1453). Ordered transport applies
+ * every preceding event before the reply. These are current backend frontiers,
+ * not atomic timestamp classification of concurrent writes. The optional direct
+ * fs.watch program retains its explicit two-turn frontier for protocol tests;
+ * it does not supply Windows production proof (#1719).
+ *
+ * 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 completion-port drainage 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 declare function drainWatchBroker(broker: WatchBroker, timeout?: number, registration?: number): Promise<boolean>;

package/lib/core/transform/tracker/broker/drainWatchBroker.d.ts

@@ -0,0 +1,74 @@
+import type { WatchBroker } from "./WatchBroker";
+/**
+ * Ask the watch broker to acknowledge, and resolve with whether it did.
+ *
+ * Windows answers after consuming currently queued native completions to an
+ * observed empty port. macOS answers once each provable stream has delivered a
+ * probe, including the service's latency (#1453). Ordered transport applies
+ * every preceding event before the reply. These are current backend frontiers,
+ * not atomic timestamp classification of concurrent writes. The optional direct
+ * fs.watch program retains its explicit two-turn frontier for protocol tests;
+ * it does not supply Windows production proof (#1719).
+ *
+ * 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 completion-port drainage 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 declare function drainWatchBroker(broker: WatchBroker, timeout?: number, registration?: number): Promise<boolean>;

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

@@ -0,0 +1,133 @@
+'use strict';
+
+var WATCH_PROBE_TIMEOUT_MS = require('./WATCH_PROBE_TIMEOUT_MS.js');
+var WatchBrokerTransport = require('./WatchBrokerTransport.js');
+
+/**
+ * Ask the watch broker to acknowledge, and resolve with whether it did.
+ *
+ * Windows answers after consuming currently queued native completions to an
+ * observed empty port. macOS answers once each provable stream has delivered a
+ * probe, including the service's latency (#1453). Ordered transport applies
+ * every preceding event before the reply. These are current backend frontiers,
+ * not atomic timestamp classification of concurrent writes. The optional direct
+ * fs.watch program retains its explicit two-turn frontier for protocol tests;
+ * it does not supply Windows production proof (#1719).
+ *
+ * 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 completion-port drainage 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.
+ */
+function drainWatchBroker(broker, timeout = 2 * WATCH_PROBE_TIMEOUT_MS.WATCH_PROBE_TIMEOUT_MS, registration) {
+    // 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 = 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, timeout, scope) {
+    return new Promise((resolve) => {
+        const id = broker.nextId++;
+        let settled = false;
+        const release = (answered) => {
+            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) {
+                WatchBrokerTransport.WatchBrokerTransport.reference(broker, false);
+            }
+            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;
+        WatchBrokerTransport.WatchBrokerTransport.reference(broker, true);
+        const timer = setTimeout(() => release(false), timeout);
+        broker.drains.set(id, release);
+        (broker.drainScopes ??= new Map()).set(id, scope);
+        if (WatchBrokerTransport.WatchBrokerTransport.send(broker, { id, op: "drain" }) !== true) {
+            release(false);
+        }
+    });
+}
+
+exports.drainWatchBroker = drainWatchBroker;
+//# sourceMappingURL=drainWatchBroker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"drainWatchBroker.js","sources":["../../../../../src/core/transform/tracker/broker/drainWatchBroker.ts"],"sourcesContent":[null],"names":["WATCH_PROBE_TIMEOUT_MS","WatchBrokerTransport"],"mappings":";;;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEG;AACG,SAAU,gBAAgB,CAC9B,MAAmB,EACnB,UAAkB,CAAC,GAAGA,6CAAsB,EAC5C,YAAqB,EAAA;;;AAIrB,IAAA,IACE,MAAM,CAAC,QAAQ,KAAK,SAAS;SAC5B,YAAY,KAAK,SAAS;YACzB,MAAM,CAAC,aAAa,EAAE,GAAG,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,EACnD;QACA,OAAO,MAAM,CAAC,QAAQ;IACxB;IACA,MAAM,KAAK,GAAG,IAAI,GAAG,CACnB,CAAC,GAAG,MAAM,CAAC,aAAa;AACrB,SAAA,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,KAAK,CAAC,MAAM;SAClC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CACrB;AACD,IAAA,MAAM,QAAQ,GAAqB,qBAAqB,CACtD,MAAM,EACN,OAAO,EACP,KAAK,CACN,CAAC,OAAO,CAAC,MAAK;AACb,QAAA,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE;AAChC,YAAA,MAAM,CAAC,QAAQ,GAAG,SAAS;AAC3B,YAAA,MAAM,CAAC,aAAa,GAAG,SAAS;QAClC;AACF,IAAA,CAAC,CAAC;AACF,IAAA,MAAM,CAAC,QAAQ,GAAG,QAAQ;AAC1B,IAAA,MAAM,CAAC,aAAa,GAAG,KAAK;AAC5B,IAAA,OAAO,QAAQ;AACjB;AAEA,SAAS,qBAAqB,CAC5B,MAAmB,EACnB,OAAe,EACf,KAA0B,EAAA;AAE1B,IAAA,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,KAAI;AACtC,QAAA,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE;QAC1B,IAAI,OAAO,GAAG,KAAK;AACnB,QAAA,MAAM,OAAO,GAAG,CAAC,QAAiB,KAAU;AAC1C,YAAA,IAAI,OAAO;gBAAE;YACb,OAAO,GAAG,IAAI;YACd,YAAY,CAAC,KAAK,CAAC;AACnB,YAAA,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;AACxB,YAAA,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,CAAC;AAC9B,YAAA,MAAM,CAAC,aAAa,IAAI,CAAC;AACzB,YAAA,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,IAAI,MAAM,CAAC,oBAAoB,KAAK,CAAC,EAAE;AACnE,gBAAAC,yCAAoB,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;YAC/C;YACA,OAAO,CAAC,QAAQ,CAAC;AACnB,QAAA,CAAC;;;;;;AAMD,QAAA,MAAM,CAAC,aAAa,IAAI,CAAC;AACzB,QAAAA,yCAAoB,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC;AAC5C,QAAA,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QACvD,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC;AAC9B,QAAA,CAAC,MAAM,CAAC,WAAW,KAAK,IAAI,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC;AACjD,QAAA,IAAIA,yCAAoB,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,KAAK,IAAI,EAAE;YACnE,OAAO,CAAC,KAAK,CAAC;QAChB;AACF,IAAA,CAAC,CAAC;AACJ;;;;"}