ttsc 0.31.5 → 0.32.0

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#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,11 @@ 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;
+    /**
+     * @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 +189,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 +229,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 +251,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 +393,12 @@ 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.
+     */
+    private refreshFromDirectories;
     private isCompilerOutputDirectory;
     private isCompilerOutput;
     private isProjectInputCompilerOutputDirectory;