ttsc 0.31.6 → 0.32.1

package/lib/launcher/internal/watch/AsyncWatchTopology.js

@@ -0,0 +1,232 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncWatchTopology = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const node_worker_threads_1 = require("node:worker_threads");
+const SidecarEnvironment_1 = require("../../../compiler/internal/sharedHost/SidecarEnvironment");
+const workerModuleUrl_1 = require("../../../internal/workerModuleUrl");
+/**
+ * Keep one watch topology and its native subscriptions on a worker thread.
+ *
+ * Case-policy probes, content digests and compiler listings must retain their
+ * actual observations. Replacing them with path-only case caches or size/mtime
+ * digests can miss directory replacements and source edits. They instead run
+ * off the launcher's loop so their cost cannot delay resident-host retirement
+ * or queued build decisions (#1758). This moves the cost; it does not remove
+ * it. Options and publications are cloned, while callbacks stay on the caller.
+ *
+ * Await a publication before the build reads its inputs. Moving that baseline
+ * past the build could absorb an intervening edit (#1728). Callback messages
+ * and completion replies share one FIFO channel, so whenIdle completes after
+ * the notifications its barrier observed have reached the launcher (#1756).
+ *
+ * @evidence contracts/common.md#principled-implementation A dedicated supported worker executes the unchanged topology algorithm on selected cloneable data while callbacks remain caller-owned; worker events and correlated replies settle actual operations, and one FIFO channel orders callbacks before completion.
+ * @evidence contracts/common.md#clear-and-simple-design The facade separates option capture, reply dispatch and worker lifetime; the synchronous core retains filesystem policy and watcher ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing native case observations, compiler membership and content proofs remain authoritative. The explicit worker factory supplies transport without replacing globals, and the default starts the actual packaged CommonJS entry without a synchronous barrier or metadata shortcut.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains off-thread cost, baseline-before-build ordering, FIFO replies and lifetime failures; constructor prose identifies data capture, callback ownership and the optional factory.
+ * @evidence contracts/portability.md#os-neutral-implementation Native joins locate the packaged CommonJS entry, and the supported module bootstrap loads it through createRequire while retaining Node-owned inherited execution options and loader hooks. Structured cloning preserves maps and bigint device references; SidecarEnvironment merges native environment names before startup.
+ * @evidence contracts/performance.md#efficient-algorithms One thread serves the topology lifetime. Construction copies fixed option references before cloning, with costs for option/environment bytes and module initialization; each operation clones its publication bytes and adds one pending entry while the core retains native costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work Construction starts a fresh worker lifetime; that worker retains current registrations, listing premises and baselines across requests, but completion grants no reuse for another filesystem generation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One referenced worker, listeners, exit promise and uncapped pending map belong to the facade; creation failure precedes ownership transfer. Replies prune entries and failure rejects all entries. Close joins worker exit after native subscription close; failed close terminates and joins the thread while retaining error. Requests have no implicit deadline.
+ */
+class AsyncWatchTopology {
+    callbacks;
+    worker;
+    exited;
+    pending = new Map();
+    sequence = 0;
+    failure;
+    failed = false;
+    terminating = false;
+    closing;
+    /**
+     * Capture data options and start the worker; callbacks remain caller-owned.
+     * The optional factory observes worker transport without replacing globals.
+     */
+    constructor(options, callbacks, createWorker = (selected) => new node_worker_threads_1.Worker((0, workerModuleUrl_1.workerModuleUrl)(node_path_1.default.join(__dirname, `watchTopologyWorker${node_path_1.default.extname(__filename)}`)), {
+        env: SidecarEnvironment_1.SidecarEnvironment.merge(process.env, selected.env),
+        workerData: selected,
+    })) {
+        this.callbacks = callbacks;
+        // Callers also carry build callbacks. Select only the core's data options:
+        // sending the invocation wholesale would attempt to clone those functions.
+        const { binary, compilerArgsCwd, compilerProjectSelections, cwd, emit, env, files, outDir, passthrough, pinCompilerProject, projectRoot, tsconfig, } = options;
+        this.worker = createWorker({
+            binary,
+            compilerArgsCwd,
+            compilerProjectSelections,
+            cwd,
+            emit,
+            env,
+            files,
+            outDir,
+            passthrough,
+            pinCompilerProject,
+            projectRoot,
+            tsconfig,
+        });
+        this.worker.on("message", (reply) => {
+            if ("id" in reply) {
+                const waiting = this.pending.get(reply.id);
+                if (waiting === undefined)
+                    return;
+                this.pending.delete(reply.id);
+                if (reply.ok)
+                    waiting.resolve();
+                else
+                    waiting.reject(reply.error);
+                return;
+            }
+            switch (reply.event) {
+                case "input":
+                    this.callbacks.onInputChange(reply.change);
+                    break;
+                case "topology":
+                    this.callbacks.onTopologyChange();
+                    break;
+                case "error":
+                    this.callbacks.onError(reply.location, reply.error);
+                    break;
+                case "roots":
+                    this.callbacks.onProjectInputWatchRoots?.(reply.roots);
+                    break;
+                case "unavailable":
+                    this.callbacks.onProjectInputWatchUnavailable?.(reply.roots);
+                    break;
+            }
+        });
+        this.worker.on("error", (error) => this.fail(error));
+        this.exited = new Promise((resolve) => {
+            this.worker.once("exit", (code) => {
+                if (this.closing === undefined ||
+                    this.pending.size !== 0 ||
+                    (code !== 0 && !this.terminating))
+                    this.fail(new Error(`ttsc: watch topology worker exited with code ${code}`));
+                resolve();
+            });
+        });
+    }
+    /**
+     * Reconcile actual compiler membership and wait for its publication.
+     *
+     * @evidence contracts/common.md#principled-implementation The worker executes the core's actual refresh before replying, so completion does not stand for a predicted membership.
+     * @evidence contracts/common.md#clear-and-simple-design This operation frames one refresh and delegates transport correlation to request.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Membership still comes from the core's native compiler-input reader.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the membership and publication boundary.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The method frames a boolean; the worker and core own native execution.
+     * @evidence contracts/performance.md#efficient-algorithms Fixed-size framing adds one pending entry; the core retains listing, traversal and hashing costs off-thread.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every requested refresh executes; listing reuse remains the core's decision.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Correlation remains live until reply or worker failure; no deadline is imposed.
+     */
+    refresh(notify) {
+        return this.request({ method: "refresh", notify });
+    }
+    /**
+     * Capture plugin baselines before the caller starts reading or building.
+     *
+     * @evidence contracts/common.md#principled-implementation Awaited completion follows the core's baseline capture and preserves the supplied record store's separability references through structured cloning.
+     * @evidence contracts/common.md#clear-and-simple-design One publication carries inputs and their existing proof store together.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual content identity owner still judges every record; transport invents no digest or metadata equivalence.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the required pre-build ordering.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Paths and bigint maps are cloned as data; the core owns native interpretation.
+     * @evidence contracts/performance.md#efficient-algorithms Framing is fixed structural work and cloning visits input paths and record references; digest and registration work stays with the core.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each publication reaches the core, which owns baseline and listing reuse premises.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Publication data and one pending correlation remain live through completion or worker failure without a size or deadline cap.
+     */
+    setExtraInputs(inputs, identities) {
+        return this.request({ method: "setExtraInputs", inputs, identities });
+    }
+    /**
+     * Capture rule-input baselines before the caller consumes those inputs.
+     *
+     * @evidence contracts/common.md#principled-implementation Completion follows actual declaration normalization, population capture and subscription reconciliation in the core.
+     * @evidence contracts/common.md#clear-and-simple-design One operation carries the complete declared snapshot without splitting population and baseline ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The core retains missing-path, alias and empty-population semantics; transport filters no inputs.
+     * @evidence contracts/common.md#meaningful-documentation Prose states capture timing relative to consumption.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The snapshot crosses as data; the core owns filesystem identity and case policy.
+     * @evidence contracts/performance.md#efficient-algorithms Cloning visits the snapshot's path text; matching, fingerprinting and registrations keep their owning core costs.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The core decides whether a publication is equivalent; transport reuses no earlier result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Snapshot bytes and one pending correlation remain live until reply or worker failure without a population cap.
+     */
+    setProjectInputs(inputs) {
+        return this.request({ method: "setProjectInputs", inputs });
+    }
+    /**
+     * Wait for delivered topology work and its preceding callback messages.
+     *
+     * @evidence contracts/common.md#principled-implementation The worker's core barrier observes its scheduled owners, and callbacks sent before the completion reply arrive first on the same FIFO channel.
+     * @evidence contracts/common.md#clear-and-simple-design One request exposes the core's complete queue ownership instead of duplicating queue flags here.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual queue completion replaces elapsed quiet-time estimates.
+     * @evidence contracts/common.md#meaningful-documentation Prose identifies delivered work and callback ordering.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The operation uses portable MessagePort ordering without a native path or process call.
+     * @evidence contracts/performance.md#efficient-algorithms Fixed-size framing adds one correlation; the core checks flags per yielded turn and still pays its pending operations' costs.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each barrier observes current pending work rather than a previous receipt.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources One request remains live until idle, close or failure; continuous new work can keep it pending without an implicit deadline.
+     */
+    whenIdle() {
+        return this.request({ method: "whenIdle" });
+    }
+    /**
+     * Close subscriptions and join the thread. Repeated calls share retirement;
+     * close or worker failures remain rejection even after thread termination.
+     *
+     * @evidence contracts/common.md#principled-implementation Successful close follows core subscription release, outstanding barrier answers and actual worker exit; failed close terminates and joins the thread while preserving rejection.
+     * @evidence contracts/common.md#clear-and-simple-design One retained promise owns idempotent shutdown and finishClose owns its two retirement paths.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown joins actual thread exit rather than treating a posted close as completion.
+     * @evidence contracts/common.md#meaningful-documentation Prose states joined completion, repeated-call sharing and failure retention.
+     * @evidence contracts/portability.md#os-neutral-implementation Node's supported worker exit and termination APIs own thread retirement; the core owns backend subscription closure.
+     * @evidence contracts/performance.md#efficient-algorithms One close message and shared promise add fixed structural work; subscription traversal, outstanding replies and thread retirement retain delegated costs.
+     * @evidence contracts/performance.md#reuse-equivalent-work Every repeated close shares this lifetime's single retirement result, including rejection.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Closure rejects new requests and joins the worker; pending requests settle by replies or terminal failure. Native FSEvents stop errors are suppressed by its existing backend, so thread joining alone cannot certify that optional binding's physical cleanup.
+     */
+    close() {
+        this.closing ??= this.finishClose();
+        return this.closing;
+    }
+    async finishClose() {
+        try {
+            await this.request({ method: "close" });
+        }
+        catch (error) {
+            this.terminating = true;
+            await this.worker.terminate();
+            await this.exited;
+            throw error;
+        }
+        await this.exited;
+        if (this.failed)
+            throw this.failure;
+    }
+    request(operation) {
+        if (this.failed)
+            return Promise.reject(this.failure);
+        if (this.closing !== undefined)
+            return Promise.reject(new Error("ttsc: watch topology is closing"));
+        const id = ++this.sequence;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { reject, resolve });
+            try {
+                this.worker.postMessage({ ...operation, id });
+            }
+            catch (error) {
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+    fail(error) {
+        if (this.failed)
+            return;
+        this.failed = true;
+        this.failure = error;
+        for (const waiting of this.pending.values())
+            waiting.reject(error);
+        this.pending.clear();
+        this.callbacks.onFailure(error);
+    }
+}
+exports.AsyncWatchTopology = AsyncWatchTopology;
+//# sourceMappingURL=AsyncWatchTopology.js.map

package/lib/launcher/internal/watch/AsyncWatchTopology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncWatchTopology.js","sourceRoot":"","sources":["../../../../src/launcher/internal/watch/AsyncWatchTopology.ts"],"names":[],"mappings":"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"}

package/lib/launcher/internal/watch/WatchSettlement.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Waits for an owner's idle observation without losing changes during that
+ * observation. The owner announces every scheduling and terminal transition.
+ *
+ * Elapsed silence cannot certify idle: a queued build or an asynchronous input
+ * decision can remain silent until it starts. A changed revision therefore
+ * requires another observation, even when the earlier one reported idle.
+ *
+ * @evidence contracts/common.md#principled-implementation A monotonic revision detects transitions across an asynchronous idle query; wait registration and the final revision comparison share one JavaScript turn, preventing a lost wake.
+ * @evidence contracts/common.md#clear-and-simple-design The owner supplies its actual idle predicate and announces state changes; this class owns only revision validation and waiting callbacks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No timeout, retry limit, process hook or consumer-specific decision substitutes for the owner's state.
+ * @evidence contracts/common.md#meaningful-documentation Prose defines idle-query ownership and why silent queued work and intervening changes require a fresh observation; methods describe notification and failure effects.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Revisions and promises have no native path, filesystem or process boundary.
+ * @evidence contracts/performance.md#efficient-algorithms Each transition visits current waiters once; each observation is constant bookkeeping plus the supplied owner's work, without polling.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each wait observes mutable owner state independently; no computed result is cached across transitions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources A non-idle wait registers one callback until the next transition; an in-flight idle query or publication retains its call closure until settlement. Errors reject directly. The owner must announce terminal transitions so registered callbacks can recheck and reject. Concurrent caller population has no fixed cap.
+ */
+export declare class WatchSettlement {
+    private revision;
+    private readonly waiters;
+    /**
+     * Announces a scheduling or terminal transition and releases current waits.
+     *
+     * @evidence contracts/common.md#principled-implementation Advancing the revision invalidates queries already in flight, and releasing the current callback population permits each pending wait to query again.
+     * @evidence contracts/common.md#clear-and-simple-design One notification handles both ordinary scheduling and terminal transitions without interpreting the owner's state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Callbacks observe a real owner transition without polling or replacing owner operations.
+     * @evidence contracts/common.md#meaningful-documentation The prose states which transitions callers announce and that current waits are released.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This in-memory notification has no native boundary.
+     * @evidence contracts/performance.md#efficient-algorithms Copying and waking current callbacks costs linear time and temporary space in pending waits.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effectful transition does not compute a reusable result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Clearing the set releases its references before callbacks run; each resumed wait owns any later registration.
+     */
+    changed(): void;
+    /**
+     * Publishes and resolves after an idle query spans no transition; errors
+     * reject. The owner must reject its query after shutdown and announce that
+     * shutdown. Publication starts in the same turn as the final revision check.
+     *
+     * @evidence contracts/common.md#principled-implementation The revision comparison validates the complete awaited observation; publication starts synchronously after that comparison, and a non-idle result registers its wake in the same turn, so neither path loses an intervening transition.
+     * @evidence contracts/common.md#clear-and-simple-design The loop retries only after a real transition and delegates all idle and terminal meaning to the supplied owner query.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No elapsed silence, deadline or fixed retry count stands for the owner's actual pending work.
+     * @evidence contracts/common.md#meaningful-documentation The prose describes successful observation, same-turn publication, error propagation and the terminal notification obligation.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Awaiting an owner query imposes no native path or process policy.
+     * @evidence contracts/performance.md#efficient-algorithms Each query adds constant revision bookkeeping and at most one callback; query work belongs to the supplied owner, and no timer polls state.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Queries observe mutable state and are not cached across transitions.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources A non-idle observation retains one resolver until changed clears it; successful and failed queries retain no registered callback, while an in-flight query or publication retains this call until settlement. Terminal wake and rejection are the owner's obligation.
+     */
+    wait(idle: () => Promise<boolean>, publish?: () => void | Promise<void>): Promise<void>;
+}

package/lib/launcher/internal/watch/WatchSettlement.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WatchSettlement = void 0;
+/**
+ * Waits for an owner's idle observation without losing changes during that
+ * observation. The owner announces every scheduling and terminal transition.
+ *
+ * Elapsed silence cannot certify idle: a queued build or an asynchronous input
+ * decision can remain silent until it starts. A changed revision therefore
+ * requires another observation, even when the earlier one reported idle.
+ *
+ * @evidence contracts/common.md#principled-implementation A monotonic revision detects transitions across an asynchronous idle query; wait registration and the final revision comparison share one JavaScript turn, preventing a lost wake.
+ * @evidence contracts/common.md#clear-and-simple-design The owner supplies its actual idle predicate and announces state changes; this class owns only revision validation and waiting callbacks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No timeout, retry limit, process hook or consumer-specific decision substitutes for the owner's state.
+ * @evidence contracts/common.md#meaningful-documentation Prose defines idle-query ownership and why silent queued work and intervening changes require a fresh observation; methods describe notification and failure effects.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Revisions and promises have no native path, filesystem or process boundary.
+ * @evidence contracts/performance.md#efficient-algorithms Each transition visits current waiters once; each observation is constant bookkeeping plus the supplied owner's work, without polling.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each wait observes mutable owner state independently; no computed result is cached across transitions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources A non-idle wait registers one callback until the next transition; an in-flight idle query or publication retains its call closure until settlement. Errors reject directly. The owner must announce terminal transitions so registered callbacks can recheck and reject. Concurrent caller population has no fixed cap.
+ */
+class WatchSettlement {
+    revision = 0;
+    waiters = new Set();
+    /**
+     * Announces a scheduling or terminal transition and releases current waits.
+     *
+     * @evidence contracts/common.md#principled-implementation Advancing the revision invalidates queries already in flight, and releasing the current callback population permits each pending wait to query again.
+     * @evidence contracts/common.md#clear-and-simple-design One notification handles both ordinary scheduling and terminal transitions without interpreting the owner's state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Callbacks observe a real owner transition without polling or replacing owner operations.
+     * @evidence contracts/common.md#meaningful-documentation The prose states which transitions callers announce and that current waits are released.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This in-memory notification has no native boundary.
+     * @evidence contracts/performance.md#efficient-algorithms Copying and waking current callbacks costs linear time and temporary space in pending waits.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effectful transition does not compute a reusable result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Clearing the set releases its references before callbacks run; each resumed wait owns any later registration.
+     */
+    changed() {
+        ++this.revision;
+        const waiters = [...this.waiters];
+        this.waiters.clear();
+        for (const wake of waiters)
+            wake();
+    }
+    /**
+     * Publishes and resolves after an idle query spans no transition; errors
+     * reject. The owner must reject its query after shutdown and announce that
+     * shutdown. Publication starts in the same turn as the final revision check.
+     *
+     * @evidence contracts/common.md#principled-implementation The revision comparison validates the complete awaited observation; publication starts synchronously after that comparison, and a non-idle result registers its wake in the same turn, so neither path loses an intervening transition.
+     * @evidence contracts/common.md#clear-and-simple-design The loop retries only after a real transition and delegates all idle and terminal meaning to the supplied owner query.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No elapsed silence, deadline or fixed retry count stands for the owner's actual pending work.
+     * @evidence contracts/common.md#meaningful-documentation The prose describes successful observation, same-turn publication, error propagation and the terminal notification obligation.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Awaiting an owner query imposes no native path or process policy.
+     * @evidence contracts/performance.md#efficient-algorithms Each query adds constant revision bookkeeping and at most one callback; query work belongs to the supplied owner, and no timer polls state.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Queries observe mutable state and are not cached across transitions.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources A non-idle observation retains one resolver until changed clears it; successful and failed queries retain no registered callback, while an in-flight query or publication retains this call until settlement. Terminal wake and rejection are the owner's obligation.
+     */
+    async wait(idle, publish = () => { }) {
+        for (;;) {
+            const revision = this.revision;
+            const observed = await idle();
+            if (revision !== this.revision)
+                continue;
+            if (observed)
+                return await publish();
+            await new Promise((resolve) => this.waiters.add(resolve));
+        }
+    }
+}
+exports.WatchSettlement = WatchSettlement;
+//# sourceMappingURL=WatchSettlement.js.map

package/lib/launcher/internal/watch/WatchSettlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WatchSettlement.js","sourceRoot":"","sources":["../../../../src/launcher/internal/watch/WatchSettlement.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;GAgBG;AACH;IACU,QAAQ,GAAG,CAAC,CAAC;IACJ,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;IAEjD;;;;;;;;;;;OAWG;IACI,OAAO;QACZ,EAAE,IAAI,CAAC,QAAQ,CAAC;QAChB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,MAAM,IAAI,IAAI,OAAO;YAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,KAAK,CAAC,IAAI,CACf,IAA4B,EAC5B,OAAO,GAA+B,GAAG,EAAE,GAAE,CAAC;QAE9C,SAAS,CAAC;YACR,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC/B,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;YAC9B,IAAI,QAAQ,KAAK,IAAI,CAAC,QAAQ;gBAAE,SAAS;YACzC,IAAI,QAAQ;gBAAE,OAAO,MAAM,OAAO,EAAE,CAAC;YACrC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;CACF"}

package/lib/launcher/internal/watch/WatchTopology.d.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { createCaseSensitivityObservations } from "../../../internal/pathIdentity/createCaseSensitivityObservations";
 import { PluginContentIdentities } from "../../../plugin/internal/source/PluginContentIdentities";
 import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
 import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
@@ -12,26 +13,26 @@ import { watchDirectory } from "./watchDirectory";
  * output for source and declaration membership. An explicit reader supplies the
  * same absolute-path membership and failure contract for each resolved project.
  * Configuration files, project-reference roots, output inference and native
- * filesystem identity remain this topology's responsibility.
- * Response frames are observed once per project refresh at its compiler cwd;
- * that option view serves all project-output queries while the original argv
- * reaches compiler membership. A second observation rejects response changes
- * across membership resolution. Response files join the config reload set;
- * these observations do not pin files or detect a change restored in between.
+ * filesystem identity remain this topology's responsibility. Response frames
+ * are observed once per project refresh at its compiler cwd; that option view
+ * serves all project-output queries while the original argv reaches compiler
+ * membership. A second observation rejects response changes across membership
+ * resolution. Response files join the config reload set; these observations do
+ * not pin files or detect a change restored in between.
  *
  * `TTSC_WATCH_DEBUG_INPUTS` reports the named event, observed population deltas
  * and reload decision. These diagnostics reuse the decision's existing inputs;
  * they perform no extra filesystem observations.
  *
  * @evidence contracts/common.md#principled-implementation The compiler-input operation's membership, published rule inputs and actual content fingerprints qualify notifications; its native default obtains the real compiler list. Post-registration reconciliation compares baselines to recover observed handoff changes, not an atomic guarantee against every transient mutation. Explicit operations preserve native defaults without replacing global filesystem or compiler methods. Project-input attribution: Observed member deltas establish attribution; stale selected names cannot override them, while directory names retain supported population causality and unrelated multiple members remain unnamed.
- * @evidence contracts/common.md#clear-and-simple-design Compiler, plugin and project-input watch populations keep their own baselines and callbacks under one topology owner; small classifiers separate membership, selection and handle replacement. Four distinct operations own directory subscriptions, file subscriptions, immediate reload-directory reads and compiler membership; existing callers need no new argument. Project-input attribution: One private reconciliation separates member deltas from immediate resolution-directory digests before choosing a supported event name or an observed single member.
+ * @evidence contracts/common.md#clear-and-simple-design Compiler, plugin and project-input watch populations keep their own baselines and callbacks under one topology owner; small classifiers separate membership, selection and handle replacement. Five distinct operations own directory subscriptions, file subscriptions, immediate reload-directory reads, compiler membership and each decision's case-policy observations; existing callers need no new argument. Project-input attribution: One private reconciliation separates member deltas from immediate resolution-directory digests before choosing a supported event name or an observed single member.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported native backends and explicit gap/replacement ownership replace foreign watcher patching; failed observation is reported rather than represented as complete coverage. The constructor manufactures no observations and bypasses no input or content proof; supplied operations retain the existing callback and result contracts. Project-input attribution: Native event names do not manufacture a delta; the current and previous physical membership identify already observed names without filename or fixture exceptions.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain membership authority, plugin fingerprinting, publication races, physical registration and public lifecycle operations following the documentation skill. Parameters identify each supplied operation and native default beside the constructor. Project-input attribution: Native paragraphs explain stale attention, directory causality, accompanying resolution digests and unselected immediate entries.
  * @evidence contracts/portability.md#os-neutral-implementation Native paths use Node APIs and registration uses realpath; compiler/plugin maps preserve lexical aliases and fold only measured insensitive ASCII components. Project inputs use physical identities, while unknown/native Unicode relations remain conservative event candidates rather than identity proof. Registration paths and read options are passed unchanged; compiler-input readers supply absolute membership paths without replacing the topology's native identity policy. Project-input attribution: The supplied filesystem identity transaction establishes selected names and ancestry without an OS-wide case assumption or lexical alias guess.
  *
- * @evidence contracts/performance.md#efficient-algorithms Identity-keyed maps separate membership, baselines and handle registries; reconciliation delegates project/config discovery, native compiler listing, filesystem traversal/hashing and backend callbacks, with costs described by its members. Construction retains operation references and empty indexes without a filesystem observation or build. Attribution indexed visits additionally pay path/key text, ancestor and native identity work; shared ancestor keys avoid repeating the same walk within a transaction.
- * @evidence contracts/performance.md#reuse-equivalent-work Current membership, content baselines and live registrations belong to one topology; reconciliation owners decide their reuse against fresh premises. Supplied operation identities are retained without adding an observation-result cache or assuming changed inputs remain equivalent. Project-input attribution: This classifier borrows one scan's deltas and identity transaction without retaining cross-event answers.
- * @evidence contracts/performance.md#bound-retention-and-release-resources Current and pending maps and live subscriptions remain topology-owned without a population cap; reconciliation attempts obsolete handle retirement. Constructor acquires no handle; directory arrays and attribution deltas are call-local. close invokes supplied close methods but does not await backend closure, and a thrown close can interrupt later map cleanup; retained snapshots remain until the facade is released.
+ * @evidence contracts/performance.md#efficient-algorithms Identity-keyed maps separate membership, baselines and handle registries; reconciliation delegates project/config discovery, native compiler listing, filesystem traversal/hashing and backend callbacks, with costs described by its members. A directory-triggered refresh additionally visits R active reload files even on failure and compares their metadata/owner snapshots, reading bytes only when those snapshots changed. Changed-owner and notification arrays and a reported-key set require O(R) references; moved owners share one existing watcher synchronization and post-registration reconciliation, whose selected-file traversal remains part of the operation. No additional compiler listing is requested. Construction retains operation references and empty indexes without a filesystem observation or build. Attribution indexed visits additionally pay path/key text, ancestor and native identity work; shared ancestor keys avoid repeating the same walk within a transaction.
+ * @evidence contracts/performance.md#reuse-equivalent-work Current membership, content baselines and live registrations belong to one topology; reconciliation owners decide their reuse against fresh premises. Supplied operation identities are retained without assuming changed inputs remain equivalent. Each project's last compiler listing is kept with its arguments and answers only a plugin-input change, which cannot move Program membership; every other refresh lists again. Notifications delivered in one poll iteration are decided together in the check phase, so one change lists and rescans once. Project-input attribution: This classifier borrows one scan's deltas and identity transaction without retaining cross-event answers.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Current and pending maps and live subscriptions remain topology-owned without a population cap; compiler listings are replaced by each resolution and hold only its projects; reconciliation attempts obsolete handle retirement. Constructor acquires no handle; directory arrays and attribution deltas are call-local. close invokes supplied close methods but does not await backend closure, and a thrown close can interrupt later map cleanup; retained snapshots remain until the facade is released.
  */
 export declare class WatchTopology {
     private readonly options;
@@ -40,6 +41,7 @@ export declare class WatchTopology {
     private readonly openFileWatch;
     private readonly readDirectory;
     private readonly getCompilerInputs;
+    private readonly observeCaseSensitivity;
     private analysisOnly;
     private closed;
     private compilerPostRegistrationMembershipRefresh;
@@ -70,13 +72,36 @@ export declare class WatchTopology {
     /** The plugin inputs whose directories the last sync already watched. */
     private watchedExtraInputs;
     private compilerFileSnapshots;
+    /**
+     * The last compiler listing of each project the topology resolved, by its
+     * config path, with the arguments it was asked under (`listingQuestion`). A
+     * change of plugin inputs reuses it (samchon/ttsc#1741).
+     */
+    private compilerListings;
+    /**
+     * Notifications the current poll iteration delivered, decided together in the
+     * check phase (`deferNotification`).
+     */
+    private pendingNotifications;
+    private notificationsScheduled;
     private files;
+    /**
+     * The current decision's directory case-policy observations, which every
+     * identity context the decision creates shares (samchon/ttsc#1742).
+     */
+    private caseObservations;
     private lexicalIdentities;
     private fileWatchers;
     private observedDirectories;
     private outputFiles;
     private outputs;
     private projectInputFingerprints;
+    /**
+     * The metadata and physical owner each matched project-input file had when
+     * its fingerprint was taken, by match key; a named notification re-reads only
+     * the files whose metadata moved (samchon/ttsc#1748).
+     */
+    private projectInputFileSnapshots;
     private projectInputMatches;
     private projectInputs;
     private declaredProjectInputs;
@@ -104,8 +129,10 @@ export declare class WatchTopology {
      *   membership; the default invokes the native compiler. Readers throw
      *   listing failures and retain ownership of their returned array, which this
      *   topology does not mutate.
+     * @param observeCaseSensitivity Create one decision's directory case-policy
+     *   observations; the default asks the native filesystem.
      */
-    constructor(options: WatchTopologyOptions, callbacks: WatchTopologyCallbacks, openDirectoryWatch?: typeof watchDirectory, openFileWatch?: typeof fs.watch, readDirectory?: typeof fs.readdirSync, getCompilerInputs?: typeof listCompilerInputs);
+    constructor(options: WatchTopologyOptions, callbacks: WatchTopologyCallbacks, openDirectoryWatch?: typeof watchDirectory, openFileWatch?: typeof fs.watch, readDirectory?: typeof fs.readdirSync, getCompilerInputs?: typeof listCompilerInputs, observeCaseSensitivity?: typeof createCaseSensitivityObservations);
     /**
      * Re-resolve compiler inputs and notify when the resolved topology changes,
      * including membership, output/configuration or analysis-mode changes. Errors
@@ -122,6 +149,30 @@ export declare class WatchTopology {
      * @evidence contracts/performance.md#bound-retention-and-release-resources Current snapshots prune removed members and synchronization attempts obsolete handle closure, keeping old coverage after incomplete registration. Current/recovery populations and observations have no size cap; supplied close/error callbacks can throw and close does not await backend completion. State remains owner-held until released.
      */
     refresh(notify: boolean): void;
+    /**
+     * Wait until delivered notifications and registration reconciliation finish.
+     *
+     * A completed build does not imply a quiet topology: its final refresh can
+     * queue another decision and another build (#1756). Yield through the check
+     * phase before inspecting every scheduled owner so a decision queued by
+     * another decision remains part of this barrier. Later filesystem changes
+     * belong to a later barrier; this does not freeze the filesystem.
+     *
+     * @evidence contracts/common.md#principled-implementation A check-phase observation follows delivered events, and every notification, recovery and registration queue must be empty before completion.
+     * @evidence contracts/common.md#clear-and-simple-design The topology owns the barrier because it alone owns all five scheduled queues.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Queue state establishes completion without a quiet-time estimate or an invented filesystem snapshot.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes delivered work from later mutations and explains the post-build queued-decision race.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The barrier observes owned JavaScript queues without a separate native operation.
+     * @evidence contracts/performance.md#efficient-algorithms Each check turn inspects five flags and two map sizes; notification processing retains its owning traversal and native-operation costs.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call observes current work rather than reusing an earlier completion.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources One immediate callback and promise remain live per waiting call; continuous new work can prevent completion and no deadline is imposed.
+     */
+    whenIdle(): Promise<void>;
+    /**
+     * @param reuseListings Answer each project's membership with its last listing
+     *   under the same arguments instead of asking the compiler again. Only a
+     *   refresh whose cause cannot move Program membership passes it.
+     */
     private refreshCompilerInputs;
     /**
      * Hand one Program-membership transition from the compiler lane to the
@@ -157,8 +208,8 @@ export declare class WatchTopology {
      * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual plugin source digest applies its owning source-selection and pruning policy; named plugins or fixture output do not replace observed input state.
      * @evidence contracts/common.md#meaningful-documentation Native prose explains baseline timing and why existing inputs are not restamped following the documentation skill.
      * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and canonical backend registration govern source trees; lexical keys preserve declarations and unknown names, folding ASCII only under measured insensitive parents rather than an OS-derived rule.
-     * @evidence contracts/performance.md#efficient-algorithms Input/path keys deduplicate with text and native case/ancestor work; only newly admitted inputs compute initial source digests, each proven from the selected files' metadata when the load's records hold and read from the selected pruned corpus otherwise; refresh(false) also pays project/compiler listing, directory traversal and watcher reconciliation; fixed publication count does not bound delegated bytes or backend work.
-     * @evidence contracts/performance.md#reuse-equivalent-work Unchanged ordered input sets return immediately; existing inputs reuse their recorded digest until actual notification processing establishes changed consumed state; a new input's digest is the one the load recorded while its metadata holds.
+     * @evidence contracts/performance.md#efficient-algorithms Input/path keys deduplicate with text and native case/ancestor work; only newly admitted inputs compute initial source digests, each proven from the selected files' metadata when the load's records hold and read from the selected pruned corpus otherwise; the following reconciliation pays project configuration, directory traversal and watcher work but answers membership from each project's last compiler listing; fixed publication count does not bound delegated bytes or backend work.
+     * @evidence contracts/performance.md#reuse-equivalent-work Unchanged ordered input sets return immediately; a changed set reuses each project's last compiler listing under the same arguments, since plugin inputs cannot move Program membership; existing inputs reuse their recorded digest until actual notification processing establishes changed consumed state; a new input's digest is the one the load recorded while its metadata holds.
      * @evidence contracts/performance.md#bound-retention-and-release-resources Publications replace input/digest populations and case-observation caches without a population cap; synchronization attempts obsolete watcher closure. Native/supplied closure has its own lifetime and can throw; owner close does not prove every backend has stopped or every retained snapshot byte was released.
      */
     setExtraInputs(inputs: readonly string[], identities?: PluginContentIdentities.Store): void;
@@ -197,6 +248,14 @@ export declare class WatchTopology {
     close(): void;
     /** Start fresh native case observations for one synchronous watch decision. */
     private beginLexicalTransaction;
+    /**
+     * A strict project-input identity context for the current decision. Its
+     * physical paths are resolved afresh, and its case answers are the
+     * decision's: one decision builds such contexts per declaration and per
+     * candidate, and each asked every directory again, which on Windows is an
+     * `fsutil` process per question (samchon/ttsc#1742).
+     */
+    private projectInputIdentities;
     /** Keep lexical alias ownership while sharing this decision's case probes. */
     private pathKey;
     private syncFileWatchers;
@@ -211,6 +270,22 @@ export declare class WatchTopology {
     /** A config's physical replacement can change resolution with equal bytes. */
     private compilerMovementReports;
     private syncDirectoryWatchers;
+    /**
+     * Decide a notification in the event loop's check phase, together with every
+     * other notification the same poll iteration delivered (samchon/ttsc#1741).
+     *
+     * One filesystem change usually arrives as several notifications, rename and
+     * change or create and modify, and each listed the compiler inputs or
+     * rescanned the project inputs again. Identical notifications of one lane,
+     * location and path merge, keeping a rename or a gap any of them carried, and
+     * the batch refreshes compiler membership once after deciding them all. The
+     * refresh therefore starts after every notification it absorbs, and one
+     * delivered later schedules another batch.
+     */
+    private deferNotification;
+    private decideNotifications;
+    /** Decide one merged directory notification of the compiler lane. */
+    private decideCompilerDirectoryNotification;
     /**
      * Reconcile tracked compiler files after a newly registered watcher returns.
      *
@@ -337,6 +412,21 @@ export declare class WatchTopology {
     private refreshProjectInputs;
     private collectProjectInputMatches;
     private refreshFromDirectory;
+    /**
+     * Refresh compiler membership once for every directory a decision asked
+     * about. A failed refresh still reports, once each, the reload inputs every
+     * requested change names.
+     *
+     * A replacement can be delivered under only its vanished temporary name,
+     * including when its malformed bytes prevent refresh. Reconcile active
+     * reload-file snapshots on either outcome, deduplicate failed-refresh
+     * recovery against actual reported movement, and preserve the original
+     * refresh error after recovery. Batch moved owners through the existing rearm
+     * operation before notifying, because a POSIX per-file handle still owns the
+     * old inode. Unchanged snapshots stay quiet unless the existing
+     * failed-refresh selector explicitly names or cannot find the reload input.
+     */
+    private refreshFromDirectories;
     private isCompilerOutputDirectory;
     private isCompilerOutput;
     private isProjectInputCompilerOutputDirectory;