@ttsc/unplugin 0.30.4 → 0.31.1

package/lib/core/observer/WatchScope.d.ts

@@ -0,0 +1,69 @@
+import type { InputEntry } from "./InputEntry";
+/**
+ * One native recursive observer and the input entries it covers.
+ *
+ * The project root scope is pinned for the observer's lifetime. External scopes
+ * are bounded in number and close when their last entry leaves. `startedAt`
+ * records the opening boundary; readiness remains backend-owned. `lastEventAt`
+ * retains named-event uncertainty for registrations racing a compilation.
+ *
+ * @evidence contracts/common.md#principled-implementation Scope root, start sequence, capability failure, and covered entries describe the observation authority registration can actually rely on.
+ * @evidence contracts/common.md#clear-and-simple-design One scope owns its native handle while shared entries own conditions; native root identity supports topology checking for pinned and external scopes without duplicating each input's watch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed or newly opened scope cannot certify a prior compile's unchanged inputs solely because a handle exists.
+ * @evidence contracts/common.md#meaningful-documentation Member comments explain pinned ownership, directory admission, physical root identity, and the optional directory-backend track capability.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Native root identity, failure and optional directory-backend capabilities
+ *   remain explicit; event sequence does not certify canonical native naming.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   WatchScope only declares a shape; it has no computation at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   WatchScope only declares a shape; it has no work to reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   WatchScope only declares a shape; it has no handle or retained state at
+ *   runtime.
+ */
+export interface WatchScope {
+    /**
+     * Keys of the covered paths below `root` and the directories leading to them,
+     * the only ones a directory-level backend watches, each while it is a
+     * directory (samchon/ttsc#1389). Counts represent active input contributors;
+     * the last contributor removes the key and the backend can prune its watch.
+     */
+    directories: Map<string, number>;
+    /** Entries this observer covers; an unpinned scope closes when it empties. */
+    entries: Set<InputEntry>;
+    /**
+     * Whether the observer failed to open or errored, moving its entries to the
+     * poll.
+     */
+    failed: boolean;
+    /** Directory observed recursively. */
+    root: string;
+    /**
+     * The device and file id `root` resolved to when this observer opened,
+     * including the pinned project root. Absence cannot authorize coverage.
+     * Registration, native callbacks and the bounded poll verify this location:
+     * a moved watch can keep following the old directory while its spelling names
+     * a replacement. A mismatch fails the scope and hands its entries to the poll
+     * (samchon/ttsc#1384).
+     */
+    identity?: string;
+    /**
+     * Whether the scope lives for the observer's lifetime, as the project root
+     * does.
+     */
+    pinned: boolean;
+    /** Latest event sequence; a newer event requires current input validation. */
+    lastEventAt: number;
+    /** Sequence advanced before attempting native opening, not readiness proof. */
+    startedAt: number;
+    /**
+     * The native handle, absent once failed or closed. `track` exists only on a
+     * directory-level backend.
+     */
+    watcher?: {
+        close(): void;
+        track?(file: string, subtree?: boolean): void;
+        prune?(): void;
+    };
+}

package/lib/core/observer/containsPath.d.cts

@@ -0,0 +1,16 @@
+/**
+ * Whether `file` is `root` itself or lies below it, lexically.
+ *
+ * Decided through `path.relative` so that a sibling directory sharing a name
+ * prefix is never inside the root, and a path on another drive never is.
+ *
+ * @evidence contracts/common.md#principled-implementation Native relative-path boundaries distinguish descendants from prefix-sharing siblings and unrelated roots; containment is deliberately lexical.
+ * @evidence contracts/common.md#clear-and-simple-design One normalized relative path supplies all root, parent-escape, and cross-volume cases without a platform table.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts String-prefix matching and universal path lowercasing are absent; the result does not pretend lexical containment proves physical identity.
+ * @evidence contracts/common.md#meaningful-documentation The comment states lexical scope and explains both sibling prefixes and other-drive rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral containment uses native resolve, relative, separator, and absolute-root semantics, including Windows drive boundaries without a fixed drive or separator assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate acquires and retains no handle, task or state.
+ * @evidence contracts/performance.md#efficient-algorithms Native resolve/relative process the two path strings and allocate normalized/relative text; cost follows their lengths and components, not the fixed comparison count. Relative parent/absolute checks avoid scanning filesystem entries or confusing shared textual prefixes with descent.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure predicate recomputed per call.
+ */
+export declare function containsPath(root: string, file: string): boolean;

package/lib/core/observer/containsPath.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Whether `file` is `root` itself or lies below it, lexically.
+ *
+ * Decided through `path.relative` so that a sibling directory sharing a name
+ * prefix is never inside the root, and a path on another drive never is.
+ *
+ * @evidence contracts/common.md#principled-implementation Native relative-path boundaries distinguish descendants from prefix-sharing siblings and unrelated roots; containment is deliberately lexical.
+ * @evidence contracts/common.md#clear-and-simple-design One normalized relative path supplies all root, parent-escape, and cross-volume cases without a platform table.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts String-prefix matching and universal path lowercasing are absent; the result does not pretend lexical containment proves physical identity.
+ * @evidence contracts/common.md#meaningful-documentation The comment states lexical scope and explains both sibling prefixes and other-drive rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral containment uses native resolve, relative, separator, and absolute-root semantics, including Windows drive boundaries without a fixed drive or separator assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate acquires and retains no handle, task or state.
+ * @evidence contracts/performance.md#efficient-algorithms Native resolve/relative process the two path strings and allocate normalized/relative text; cost follows their lengths and components, not the fixed comparison count. Relative parent/absolute checks avoid scanning filesystem entries or confusing shared textual prefixes with descent.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure predicate recomputed per call.
+ */
+export declare function containsPath(root: string, file: string): boolean;

package/lib/core/observer/containsPath.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether `file` is `root` itself or lies below it, lexically.
+ *
+ * Decided through `path.relative` so that a sibling directory sharing a name
+ * prefix is never inside the root, and a path on another drive never is.
+ *
+ * @evidence contracts/common.md#principled-implementation Native relative-path boundaries distinguish descendants from prefix-sharing siblings and unrelated roots; containment is deliberately lexical.
+ * @evidence contracts/common.md#clear-and-simple-design One normalized relative path supplies all root, parent-escape, and cross-volume cases without a platform table.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts String-prefix matching and universal path lowercasing are absent; the result does not pretend lexical containment proves physical identity.
+ * @evidence contracts/common.md#meaningful-documentation The comment states lexical scope and explains both sibling prefixes and other-drive rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral containment uses native resolve, relative, separator, and absolute-root semantics, including Windows drive boundaries without a fixed drive or separator assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate acquires and retains no handle, task or state.
+ * @evidence contracts/performance.md#efficient-algorithms Native resolve/relative process the two path strings and allocate normalized/relative text; cost follows their lengths and components, not the fixed comparison count. Relative parent/absolute checks avoid scanning filesystem entries or confusing shared textual prefixes with descent.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure predicate recomputed per call.
+ */
+export declare function containsPath(root: string, file: string): boolean;

package/lib/core/observer/containsPath.js

@@ -0,0 +1,29 @@
+'use strict';
+
+var path = require('node:path');
+
+/**
+ * Whether `file` is `root` itself or lies below it, lexically.
+ *
+ * Decided through `path.relative` so that a sibling directory sharing a name
+ * prefix is never inside the root, and a path on another drive never is.
+ *
+ * @evidence contracts/common.md#principled-implementation Native relative-path boundaries distinguish descendants from prefix-sharing siblings and unrelated roots; containment is deliberately lexical.
+ * @evidence contracts/common.md#clear-and-simple-design One normalized relative path supplies all root, parent-escape, and cross-volume cases without a platform table.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts String-prefix matching and universal path lowercasing are absent; the result does not pretend lexical containment proves physical identity.
+ * @evidence contracts/common.md#meaningful-documentation The comment states lexical scope and explains both sibling prefixes and other-drive rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral containment uses native resolve, relative, separator, and absolute-root semantics, including Windows drive boundaries without a fixed drive or separator assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate acquires and retains no handle, task or state.
+ * @evidence contracts/performance.md#efficient-algorithms Native resolve/relative process the two path strings and allocate normalized/relative text; cost follows their lengths and components, not the fixed comparison count. Relative parent/absolute checks avoid scanning filesystem entries or confusing shared textual prefixes with descent.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure predicate recomputed per call.
+ */
+function containsPath(root, file) {
+    const relative = path.relative(path.resolve(root), path.resolve(file));
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)));
+}
+
+exports.containsPath = containsPath;
+//# sourceMappingURL=containsPath.js.map

package/lib/core/observer/containsPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containsPath.js","sources":["../../../src/core/observer/containsPath.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAEA;;;;;;;;;;;;;;AAcG;AACG,SAAU,YAAY,CAAC,IAAY,EAAE,IAAY,EAAA;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,QACE,QAAQ,KAAK,EAAE;SACd,QAAQ,KAAK,IAAI;YAChB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,CAAA,CAAE,CAAC;YACrC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AAEjC;;;;"}

package/lib/core/observer/containsPath.mjs

@@ -0,0 +1,27 @@
+import path from 'node:path';
+
+/**
+ * Whether `file` is `root` itself or lies below it, lexically.
+ *
+ * Decided through `path.relative` so that a sibling directory sharing a name
+ * prefix is never inside the root, and a path on another drive never is.
+ *
+ * @evidence contracts/common.md#principled-implementation Native relative-path boundaries distinguish descendants from prefix-sharing siblings and unrelated roots; containment is deliberately lexical.
+ * @evidence contracts/common.md#clear-and-simple-design One normalized relative path supplies all root, parent-escape, and cross-volume cases without a platform table.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts String-prefix matching and universal path lowercasing are absent; the result does not pretend lexical containment proves physical identity.
+ * @evidence contracts/common.md#meaningful-documentation The comment states lexical scope and explains both sibling prefixes and other-drive rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral containment uses native resolve, relative, separator, and absolute-root semantics, including Windows drive boundaries without a fixed drive or separator assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate acquires and retains no handle, task or state.
+ * @evidence contracts/performance.md#efficient-algorithms Native resolve/relative process the two path strings and allocate normalized/relative text; cost follows their lengths and components, not the fixed comparison count. Relative parent/absolute checks avoid scanning filesystem entries or confusing shared textual prefixes with descent.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure predicate recomputed per call.
+ */
+function containsPath(root, file) {
+    const relative = path.relative(path.resolve(root), path.resolve(file));
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)));
+}
+
+export { containsPath };
+//# sourceMappingURL=containsPath.mjs.map

package/lib/core/observer/containsPath.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"containsPath.mjs","sources":["../../../src/core/observer/containsPath.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;AAcG;AACG,SAAU,YAAY,CAAC,IAAY,EAAE,IAAY,EAAA;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,QACE,QAAQ,KAAK,EAAE;SACd,QAAQ,KAAK,IAAI;YAChB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,CAAA,CAAE,CAAC;YACrC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AAEjC;;;;"}

package/lib/core/observer/createInputObserver.d.cts

@@ -0,0 +1,147 @@
+import type { InputObserver } from "./InputObserver.cjs";
+import type { InputObserverChange } from "./InputObserverChange.cjs";
+import type { InputObserverOperations } from "./InputObserverOperations.cjs";
+/**
+ * The adapter's observer of compiler inputs, keyed by owner: each owner
+ * registers the inputs one delivery depended on, and hears which owners' inputs
+ * changed.
+ *
+ * Two owners use it. The Vite dev server's owners are its importers
+ * (`createViteServeInputWatch`), which it reloads or invalidates through Vite's
+ * own graph; a watching build's bridge's owners are project records
+ * (`openHostWatchBridge`), which it moves. Neither sees the other's shape: the
+ * observer reports through `onChanged` alone (samchon/ttsc#1485).
+ *
+ * One recursive scope observes the project root, pinned once the observer
+ * opens, and at most 16 external scopes the inputs outside it, each closed when
+ * its last input leaves. Every native scope retains authority only while its
+ * physical root still matches its configured spelling. A healthy external
+ * scope admits newly registered descendants while its root identity and
+ * physical containment still hold; the scope cap is checked only when no
+ * existing scope covers them.
+ * Ordinary files use events after their initial subscription is observed;
+ * one shared poll verifies each occupied scope's location, not each file.
+ * Missing spellings and directory predicates use the recursive observer for
+ * their nearest available scope. Inputs a native scope cannot safely cover
+ * share one bounded fallback poll; linked files also share topology checks
+ * because retargeting a junction need not emit events on its old descendants.
+ * Every event is re-checked against the input's recorded condition before an
+ * owner hears it, so an event that changed nothing the compile observed is
+ * silent. Native event names can have aliases missing from lexical indexes.
+ * Each settled event batch therefore rechecks all registered conditions of the
+ * reporting scope; directory admission still limits native watch coverage.
+ *
+ * Large event waves yield between bounded entry slices so native IPC and host
+ * requests can advance. Each slice reads current facts with its own fresh
+ * contexts; only callback results retain the registration they belong to.
+ *
+ * A project's root-file membership is one entry for the project root
+ * (samchon/ttsc#1419). Its scope admits every directory the project walk
+ * enters, and an event in its scope schedules a current policy-aware walk. Its
+ * owners are reported as invalidated rather than reloaded, since most new files
+ * change no other module.
+ *
+ * A plugin's Go source directory is one entry too (samchon/ttsc#1487). Its
+ * scope admits every directory below it but those the plugin build passes over
+ * (`pluginSourceCovers`), any event below it marks it, and its check proves the
+ * state the plugin build keyed the binary on, its files and the environment a
+ * build there runs in (`pluginSourceHolds`, samchon/ttsc#1493), trusting its
+ * files' metadata only against a clock reference the check mints first
+ * (`refreshProcessClockReference`). Its owners are reloaded, since the plugin's
+ * output can change for every module.
+ *
+ * @param onChanged Told, once per settled batch of events, which owners' inputs
+ *   changed: `reload` for a changed input, and `invalidate` for a membership
+ *   change alone.
+ * @param operations Watch/poll and identity-case capabilities. These do not
+ *   replace the native filesystem used to read input conditions or paths.
+ * @evidence contracts/common.md#principled-implementation
+ *   Owned registration maps and callbacks separate compiler-input conditions
+ *   from Vite importer or build-record policy.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One observer indexes input conditions and owners, while callback consumers
+ *   decide reload versus record signaling. Shared native scopes and one poller
+ *   cover capability boundaries without duplicating each owner's watcher tree.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The public filesystem identity helper and injected native watch seams
+ *   provide the implementation boundary; the observer does not patch either
+ *   consumer's methods.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the two owner kinds, why membership and plugin trees
+ *   need observation, and why links or uncovered scopes need polling. Separate
+ *   paragraphs give purpose and reasons under the documentation skill;
+ *   InputObserver documents the returned lifecycle contract.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Filesystem identity comes from ttsc/path-identity and directory
+ *   capabilities rather than a universal lowercase path. Unknown case policy
+ *   keeps exact identity, routes both case candidates and requires polling;
+ *   an observed or supplied insensitive-directory answer folds registration
+ *   aliases. Event history includes all alias key forms without claiming that
+ *   their spellings identify the same filesystem object.
+ *   The actual host chooses the default broker on Windows/macOS and Linux
+ *   recursive backend otherwise; the injected platform selects identity grammar,
+ *   not a foreign filesystem implementation. Native path reads remain native.
+ *   Native failures and uncovered link topology motivate the shared polling
+ *   boundary, whose behavior remains owned by the observer.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Identity maps index entries and their owners; settled events deduplicate
+ *   pending entries before rechecking all reporting-scope conditions. This
+ *   input-proportional validation is needed because lexical names cannot exclude
+ *   native aliases; unrelated scopes are not selected. Registration also builds
+ *   ancestor aliases/contributions and serializes nonmembership evidence. Native
+ *   identity queries, owner/condition fanout, membership walks, predicate lists
+ *   and plugin-tree proofs retain path/content/entry costs. Admission scans live
+ *   membership/tree conditions; one prune per changed scope avoids repeated
+ *   retirement scans. Poll slices bound selected probes, not dependent fanout,
+ *   native read bytes or proof duration.
+ *   Native event waves also bound entries per turn, retaining their fixed
+ *   population and owner-result maps until completion or disposal. Poll scope
+ *   and link fanout beyond the immediate slice joins that yielding queue.
+ *   Named-event history uses at most three lexical keys per path without native
+ *   namespace queries. Each replacement validates at most 17 native
+ *   roots once before binding inputs; each poll and native callback validates
+ *   its current locations afresh. An external registration scans the bounded scope
+ *   population for exact lexical ancestors, validating their current identity
+ *   and physical containment before sharing native coverage.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Owners with the same resolved lexical input and recorded condition key
+ *   share one entry/condition; event aliases help route native spellings but do
+ *   not merge every physical alias into one entry. Scopes and linked topology
+ *   probes are shared across contributors. Recursive external coverage is
+ *   shared only for exact lexical descendants still physically below a healthy
+ *   observer's unchanged root; failed or replaced roots confer no coverage.
+ *   Pinned roots follow the same identity rule. Same-root reattachment rebuilds
+ *   failed coverage while retaining owner conditions; until then one shared
+ *   fallback poll checks uncovered inputs.
+ *   Changed condition keys lose their
+ *   previous ownership, and rename/removal/reanchor boundaries retire stale
+ *   path memos. One clock reference is minted per selected plugin-tree batch.
+ *   Ordinary checks share namespace facts only within each fresh synchronous
+ *   phase, never between phases or turns. Delayed reports retain registration
+ *   identity, so a replaced or forgotten owner cannot receive an old effect.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Last-owner removal and dispose attempt watch/poll cleanup, suppressing close
+ *   failures; a thrown backend close is not certified as released. Conditions
+ *   remove their directory contributions when they leave; root or polling
+ *   policy changes and lost project-root authority rebuild scopes on attachment
+ *   without retaining old admission history. Failed scopes relinquish callback
+ *   authority before attempting close, even when close throws. Retired poll
+ *   callbacks cannot act on a later observer lifetime.
+ *   Conditions and owners still require input-proportional memory, and a capped
+ *   scope count does not bound the number of admitted descendant subscriptions
+ *   or input/path/evidence bytes. Change history clears above 100,000 keys;
+ *   unknown-case ancestor memos live until their reset boundary. Named events
+ *   retain history keys without adding unrelated directories to those memos.
+ *   Dispose clears registrations/timers but retains the opened root and permits
+ *   later delivery to reacquire scopes. Callback/proof/poll-construction
+ *   exceptions can escape; this operation provides no general rollback of
+ *   effects already performed.
+ */
+export declare function createInputObserver(onChanged: (change: InputObserverChange) => void, operations?: Partial<InputObserverOperations>): InputObserver;

package/lib/core/observer/createInputObserver.d.mts

@@ -0,0 +1,147 @@
+import type { InputObserver } from "./InputObserver.mjs";
+import type { InputObserverChange } from "./InputObserverChange.mjs";
+import type { InputObserverOperations } from "./InputObserverOperations.mjs";
+/**
+ * The adapter's observer of compiler inputs, keyed by owner: each owner
+ * registers the inputs one delivery depended on, and hears which owners' inputs
+ * changed.
+ *
+ * Two owners use it. The Vite dev server's owners are its importers
+ * (`createViteServeInputWatch`), which it reloads or invalidates through Vite's
+ * own graph; a watching build's bridge's owners are project records
+ * (`openHostWatchBridge`), which it moves. Neither sees the other's shape: the
+ * observer reports through `onChanged` alone (samchon/ttsc#1485).
+ *
+ * One recursive scope observes the project root, pinned once the observer
+ * opens, and at most 16 external scopes the inputs outside it, each closed when
+ * its last input leaves. Every native scope retains authority only while its
+ * physical root still matches its configured spelling. A healthy external
+ * scope admits newly registered descendants while its root identity and
+ * physical containment still hold; the scope cap is checked only when no
+ * existing scope covers them.
+ * Ordinary files use events after their initial subscription is observed;
+ * one shared poll verifies each occupied scope's location, not each file.
+ * Missing spellings and directory predicates use the recursive observer for
+ * their nearest available scope. Inputs a native scope cannot safely cover
+ * share one bounded fallback poll; linked files also share topology checks
+ * because retargeting a junction need not emit events on its old descendants.
+ * Every event is re-checked against the input's recorded condition before an
+ * owner hears it, so an event that changed nothing the compile observed is
+ * silent. Native event names can have aliases missing from lexical indexes.
+ * Each settled event batch therefore rechecks all registered conditions of the
+ * reporting scope; directory admission still limits native watch coverage.
+ *
+ * Large event waves yield between bounded entry slices so native IPC and host
+ * requests can advance. Each slice reads current facts with its own fresh
+ * contexts; only callback results retain the registration they belong to.
+ *
+ * A project's root-file membership is one entry for the project root
+ * (samchon/ttsc#1419). Its scope admits every directory the project walk
+ * enters, and an event in its scope schedules a current policy-aware walk. Its
+ * owners are reported as invalidated rather than reloaded, since most new files
+ * change no other module.
+ *
+ * A plugin's Go source directory is one entry too (samchon/ttsc#1487). Its
+ * scope admits every directory below it but those the plugin build passes over
+ * (`pluginSourceCovers`), any event below it marks it, and its check proves the
+ * state the plugin build keyed the binary on, its files and the environment a
+ * build there runs in (`pluginSourceHolds`, samchon/ttsc#1493), trusting its
+ * files' metadata only against a clock reference the check mints first
+ * (`refreshProcessClockReference`). Its owners are reloaded, since the plugin's
+ * output can change for every module.
+ *
+ * @param onChanged Told, once per settled batch of events, which owners' inputs
+ *   changed: `reload` for a changed input, and `invalidate` for a membership
+ *   change alone.
+ * @param operations Watch/poll and identity-case capabilities. These do not
+ *   replace the native filesystem used to read input conditions or paths.
+ * @evidence contracts/common.md#principled-implementation
+ *   Owned registration maps and callbacks separate compiler-input conditions
+ *   from Vite importer or build-record policy.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One observer indexes input conditions and owners, while callback consumers
+ *   decide reload versus record signaling. Shared native scopes and one poller
+ *   cover capability boundaries without duplicating each owner's watcher tree.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The public filesystem identity helper and injected native watch seams
+ *   provide the implementation boundary; the observer does not patch either
+ *   consumer's methods.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the two owner kinds, why membership and plugin trees
+ *   need observation, and why links or uncovered scopes need polling. Separate
+ *   paragraphs give purpose and reasons under the documentation skill;
+ *   InputObserver documents the returned lifecycle contract.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Filesystem identity comes from ttsc/path-identity and directory
+ *   capabilities rather than a universal lowercase path. Unknown case policy
+ *   keeps exact identity, routes both case candidates and requires polling;
+ *   an observed or supplied insensitive-directory answer folds registration
+ *   aliases. Event history includes all alias key forms without claiming that
+ *   their spellings identify the same filesystem object.
+ *   The actual host chooses the default broker on Windows/macOS and Linux
+ *   recursive backend otherwise; the injected platform selects identity grammar,
+ *   not a foreign filesystem implementation. Native path reads remain native.
+ *   Native failures and uncovered link topology motivate the shared polling
+ *   boundary, whose behavior remains owned by the observer.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Identity maps index entries and their owners; settled events deduplicate
+ *   pending entries before rechecking all reporting-scope conditions. This
+ *   input-proportional validation is needed because lexical names cannot exclude
+ *   native aliases; unrelated scopes are not selected. Registration also builds
+ *   ancestor aliases/contributions and serializes nonmembership evidence. Native
+ *   identity queries, owner/condition fanout, membership walks, predicate lists
+ *   and plugin-tree proofs retain path/content/entry costs. Admission scans live
+ *   membership/tree conditions; one prune per changed scope avoids repeated
+ *   retirement scans. Poll slices bound selected probes, not dependent fanout,
+ *   native read bytes or proof duration.
+ *   Native event waves also bound entries per turn, retaining their fixed
+ *   population and owner-result maps until completion or disposal. Poll scope
+ *   and link fanout beyond the immediate slice joins that yielding queue.
+ *   Named-event history uses at most three lexical keys per path without native
+ *   namespace queries. Each replacement validates at most 17 native
+ *   roots once before binding inputs; each poll and native callback validates
+ *   its current locations afresh. An external registration scans the bounded scope
+ *   population for exact lexical ancestors, validating their current identity
+ *   and physical containment before sharing native coverage.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Owners with the same resolved lexical input and recorded condition key
+ *   share one entry/condition; event aliases help route native spellings but do
+ *   not merge every physical alias into one entry. Scopes and linked topology
+ *   probes are shared across contributors. Recursive external coverage is
+ *   shared only for exact lexical descendants still physically below a healthy
+ *   observer's unchanged root; failed or replaced roots confer no coverage.
+ *   Pinned roots follow the same identity rule. Same-root reattachment rebuilds
+ *   failed coverage while retaining owner conditions; until then one shared
+ *   fallback poll checks uncovered inputs.
+ *   Changed condition keys lose their
+ *   previous ownership, and rename/removal/reanchor boundaries retire stale
+ *   path memos. One clock reference is minted per selected plugin-tree batch.
+ *   Ordinary checks share namespace facts only within each fresh synchronous
+ *   phase, never between phases or turns. Delayed reports retain registration
+ *   identity, so a replaced or forgotten owner cannot receive an old effect.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Last-owner removal and dispose attempt watch/poll cleanup, suppressing close
+ *   failures; a thrown backend close is not certified as released. Conditions
+ *   remove their directory contributions when they leave; root or polling
+ *   policy changes and lost project-root authority rebuild scopes on attachment
+ *   without retaining old admission history. Failed scopes relinquish callback
+ *   authority before attempting close, even when close throws. Retired poll
+ *   callbacks cannot act on a later observer lifetime.
+ *   Conditions and owners still require input-proportional memory, and a capped
+ *   scope count does not bound the number of admitted descendant subscriptions
+ *   or input/path/evidence bytes. Change history clears above 100,000 keys;
+ *   unknown-case ancestor memos live until their reset boundary. Named events
+ *   retain history keys without adding unrelated directories to those memos.
+ *   Dispose clears registrations/timers but retains the opened root and permits
+ *   later delivery to reacquire scopes. Callback/proof/poll-construction
+ *   exceptions can escape; this operation provides no general rollback of
+ *   effects already performed.
+ */
+export declare function createInputObserver(onChanged: (change: InputObserverChange) => void, operations?: Partial<InputObserverOperations>): InputObserver;

package/lib/core/observer/createInputObserver.d.ts

@@ -0,0 +1,147 @@
+import type { InputObserver } from "./InputObserver";
+import type { InputObserverChange } from "./InputObserverChange";
+import type { InputObserverOperations } from "./InputObserverOperations";
+/**
+ * The adapter's observer of compiler inputs, keyed by owner: each owner
+ * registers the inputs one delivery depended on, and hears which owners' inputs
+ * changed.
+ *
+ * Two owners use it. The Vite dev server's owners are its importers
+ * (`createViteServeInputWatch`), which it reloads or invalidates through Vite's
+ * own graph; a watching build's bridge's owners are project records
+ * (`openHostWatchBridge`), which it moves. Neither sees the other's shape: the
+ * observer reports through `onChanged` alone (samchon/ttsc#1485).
+ *
+ * One recursive scope observes the project root, pinned once the observer
+ * opens, and at most 16 external scopes the inputs outside it, each closed when
+ * its last input leaves. Every native scope retains authority only while its
+ * physical root still matches its configured spelling. A healthy external
+ * scope admits newly registered descendants while its root identity and
+ * physical containment still hold; the scope cap is checked only when no
+ * existing scope covers them.
+ * Ordinary files use events after their initial subscription is observed;
+ * one shared poll verifies each occupied scope's location, not each file.
+ * Missing spellings and directory predicates use the recursive observer for
+ * their nearest available scope. Inputs a native scope cannot safely cover
+ * share one bounded fallback poll; linked files also share topology checks
+ * because retargeting a junction need not emit events on its old descendants.
+ * Every event is re-checked against the input's recorded condition before an
+ * owner hears it, so an event that changed nothing the compile observed is
+ * silent. Native event names can have aliases missing from lexical indexes.
+ * Each settled event batch therefore rechecks all registered conditions of the
+ * reporting scope; directory admission still limits native watch coverage.
+ *
+ * Large event waves yield between bounded entry slices so native IPC and host
+ * requests can advance. Each slice reads current facts with its own fresh
+ * contexts; only callback results retain the registration they belong to.
+ *
+ * A project's root-file membership is one entry for the project root
+ * (samchon/ttsc#1419). Its scope admits every directory the project walk
+ * enters, and an event in its scope schedules a current policy-aware walk. Its
+ * owners are reported as invalidated rather than reloaded, since most new files
+ * change no other module.
+ *
+ * A plugin's Go source directory is one entry too (samchon/ttsc#1487). Its
+ * scope admits every directory below it but those the plugin build passes over
+ * (`pluginSourceCovers`), any event below it marks it, and its check proves the
+ * state the plugin build keyed the binary on, its files and the environment a
+ * build there runs in (`pluginSourceHolds`, samchon/ttsc#1493), trusting its
+ * files' metadata only against a clock reference the check mints first
+ * (`refreshProcessClockReference`). Its owners are reloaded, since the plugin's
+ * output can change for every module.
+ *
+ * @param onChanged Told, once per settled batch of events, which owners' inputs
+ *   changed: `reload` for a changed input, and `invalidate` for a membership
+ *   change alone.
+ * @param operations Watch/poll and identity-case capabilities. These do not
+ *   replace the native filesystem used to read input conditions or paths.
+ * @evidence contracts/common.md#principled-implementation
+ *   Owned registration maps and callbacks separate compiler-input conditions
+ *   from Vite importer or build-record policy.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One observer indexes input conditions and owners, while callback consumers
+ *   decide reload versus record signaling. Shared native scopes and one poller
+ *   cover capability boundaries without duplicating each owner's watcher tree.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The public filesystem identity helper and injected native watch seams
+ *   provide the implementation boundary; the observer does not patch either
+ *   consumer's methods.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the two owner kinds, why membership and plugin trees
+ *   need observation, and why links or uncovered scopes need polling. Separate
+ *   paragraphs give purpose and reasons under the documentation skill;
+ *   InputObserver documents the returned lifecycle contract.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Filesystem identity comes from ttsc/path-identity and directory
+ *   capabilities rather than a universal lowercase path. Unknown case policy
+ *   keeps exact identity, routes both case candidates and requires polling;
+ *   an observed or supplied insensitive-directory answer folds registration
+ *   aliases. Event history includes all alias key forms without claiming that
+ *   their spellings identify the same filesystem object.
+ *   The actual host chooses the default broker on Windows/macOS and Linux
+ *   recursive backend otherwise; the injected platform selects identity grammar,
+ *   not a foreign filesystem implementation. Native path reads remain native.
+ *   Native failures and uncovered link topology motivate the shared polling
+ *   boundary, whose behavior remains owned by the observer.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Identity maps index entries and their owners; settled events deduplicate
+ *   pending entries before rechecking all reporting-scope conditions. This
+ *   input-proportional validation is needed because lexical names cannot exclude
+ *   native aliases; unrelated scopes are not selected. Registration also builds
+ *   ancestor aliases/contributions and serializes nonmembership evidence. Native
+ *   identity queries, owner/condition fanout, membership walks, predicate lists
+ *   and plugin-tree proofs retain path/content/entry costs. Admission scans live
+ *   membership/tree conditions; one prune per changed scope avoids repeated
+ *   retirement scans. Poll slices bound selected probes, not dependent fanout,
+ *   native read bytes or proof duration.
+ *   Native event waves also bound entries per turn, retaining their fixed
+ *   population and owner-result maps until completion or disposal. Poll scope
+ *   and link fanout beyond the immediate slice joins that yielding queue.
+ *   Named-event history uses at most three lexical keys per path without native
+ *   namespace queries. Each replacement validates at most 17 native
+ *   roots once before binding inputs; each poll and native callback validates
+ *   its current locations afresh. An external registration scans the bounded scope
+ *   population for exact lexical ancestors, validating their current identity
+ *   and physical containment before sharing native coverage.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Owners with the same resolved lexical input and recorded condition key
+ *   share one entry/condition; event aliases help route native spellings but do
+ *   not merge every physical alias into one entry. Scopes and linked topology
+ *   probes are shared across contributors. Recursive external coverage is
+ *   shared only for exact lexical descendants still physically below a healthy
+ *   observer's unchanged root; failed or replaced roots confer no coverage.
+ *   Pinned roots follow the same identity rule. Same-root reattachment rebuilds
+ *   failed coverage while retaining owner conditions; until then one shared
+ *   fallback poll checks uncovered inputs.
+ *   Changed condition keys lose their
+ *   previous ownership, and rename/removal/reanchor boundaries retire stale
+ *   path memos. One clock reference is minted per selected plugin-tree batch.
+ *   Ordinary checks share namespace facts only within each fresh synchronous
+ *   phase, never between phases or turns. Delayed reports retain registration
+ *   identity, so a replaced or forgotten owner cannot receive an old effect.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Last-owner removal and dispose attempt watch/poll cleanup, suppressing close
+ *   failures; a thrown backend close is not certified as released. Conditions
+ *   remove their directory contributions when they leave; root or polling
+ *   policy changes and lost project-root authority rebuild scopes on attachment
+ *   without retaining old admission history. Failed scopes relinquish callback
+ *   authority before attempting close, even when close throws. Retired poll
+ *   callbacks cannot act on a later observer lifetime.
+ *   Conditions and owners still require input-proportional memory, and a capped
+ *   scope count does not bound the number of admitted descendant subscriptions
+ *   or input/path/evidence bytes. Change history clears above 100,000 keys;
+ *   unknown-case ancestor memos live until their reset boundary. Named events
+ *   retain history keys without adding unrelated directories to those memos.
+ *   Dispose clears registrations/timers but retains the opened root and permits
+ *   later delivery to reacquire scopes. Callback/proof/poll-construction
+ *   exceptions can escape; this operation provides no general rollback of
+ *   effects already performed.
+ */
+export declare function createInputObserver(onChanged: (change: InputObserverChange) => void, operations?: Partial<InputObserverOperations>): InputObserver;