@ttsc/unplugin 0.30.4 → 0.31.1

package/lib/core/bridge/buildHostDeclaresPolling.mjs

@@ -0,0 +1,32 @@
+import { hostDeclaresPolling } from '../transform/tracker/hostDeclaresPolling.mjs';
+
+/**
+ * Read a build host's active watch-session polling declaration.
+ *
+ * Webpack and Rspack accept options directly on compiler.watch(), so their
+ * public watching.watchOptions can differ from the compiler configuration. A
+ * closed session has no watching carrier. Other hosts retain environment
+ * declarations; Vite's resolved option remains with its lifecycle owner.
+ * Watchpack's environment declaration can force polling but cannot disable a
+ * polling session. Chokidar-specific flags do not govern these two hosts.
+ *
+ * @evidence contracts/common.md#principled-implementation Webpack/Rspack session polling and Watchpack's positive environment override independently require polling. Unrelated Chokidar settings cannot cancel or manufacture that declaration; other hosts retain the generic environment policy.
+ * @evidence contracts/common.md#clear-and-simple-design One capability read serves both compatible hosts and delegates environment interpretation to its existing owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No OS guess, private field or foreign method replacement stands in for a host declaration or native delivery proof.
+ * @evidence contracts/common.md#meaningful-documentation The prose distinguishes active session options, compiler configuration and closed sessions.
+ * @evidence contracts/portability.md#os-neutral-implementation Public host capabilities select polling independently of native paths or operating systems; a native declaration does not certify event delivery.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed set of optional property reads precedes delegated parsing of the relevant environment values; parsing cost depends on their text lengths.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each invocation reads current session/environment policy; no observation verdict is retained between sessions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The selector retains no session, cache, watcher or task.
+ */
+function buildHostDeclaresPolling(native, env = process.env) {
+    if (native?.framework !== "webpack" && native?.framework !== "rspack")
+        return hostDeclaresPolling(env);
+    const poll = native.compiler.watching?.watchOptions?.poll;
+    return (poll === true ||
+        (typeof poll === "number" && Boolean(poll)) ||
+        hostDeclaresPolling({ WATCHPACK_POLLING: env.WATCHPACK_POLLING }));
+}
+
+export { buildHostDeclaresPolling };
+//# sourceMappingURL=buildHostDeclaresPolling.mjs.map

package/lib/core/bridge/buildHostDeclaresPolling.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildHostDeclaresPolling.mjs","sources":["../../../src/core/bridge/buildHostDeclaresPolling.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;;;;AAkBG;AACG,SAAU,wBAAwB,CACtC,MAAsC,EACtC,GAAA,GAAyB,OAAO,CAAC,GAAG,EAAA;IAEpC,IAAI,MAAM,EAAE,SAAS,KAAK,SAAS,IAAI,MAAM,EAAE,SAAS,KAAK,QAAQ;AACnE,QAAA,OAAO,mBAAmB,CAAC,GAAG,CAAC;IACjC,MAAM,IAAI,GACR,MAAM,CAAC,QAGR,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI;IAC9B,QACE,IAAI,KAAK,IAAI;SACZ,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,EAAE,CAAC;AAErE;;;;"}

package/lib/core/bridge/buildHostRoot.d.cts

@@ -0,0 +1,30 @@
+/**
+ * Resolve a configured native host root when configuration is received. An
+ * omitted root stays omitted so the adapter can distinguish Farm's selected
+ * location from the generic fallback. Resolution preserves lexical alias
+ * spelling; it does not canonicalize the root through the filesystem.
+ *
+ * @evidence contracts/common.md#principled-implementation An explicit root is resolved using native path grammar and current configuration-time cwd; undefined remains the absence of a configured root.
+ * @evidence contracts/common.md#clear-and-simple-design Configuration-time path resolution is separate from later default-root selection, so relative roots are anchored once while an omitted root remains dynamic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native path.resolve supplies grammar without platform guesses, filesystem alias replacement or a fabricated host root.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states resolution timing, the omitted-root distinction and lexical rather than physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.resolve interprets volumes, separators and relative roots against actual cwd without changing a filesystem alias to its realpath.
+ * @evidence contracts/performance.md#efficient-algorithms Explicit root resolution scans and normalizes path text and allocates its absolute spelling, without filesystem enumeration or identity probing; undefined performs no resolution.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation resolves its argument per configuration call; the caller stores the selected spelling rather than this operation caching it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned path text transfers to the caller; no handle, watcher or retained state is acquired.
+ */
+export declare function resolveConfiguredHostRoot(root: string | undefined): string | undefined;
+/**
+ * Use a previously resolved configured root, or the process's current directory
+ * at this invocation. A configured spelling remains fixed across cwd changes.
+ *
+ * @evidence contracts/common.md#principled-implementation Nullish fallback reads actual process.cwd only when no configured root exists; the configured string is returned unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One selection supplies the root used by record locations and bridge admission without owning either resource or its proof.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback is the actual working directory, not a guessed project root or a fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes invocation-time cwd from a configuration-time selected spelling.
+ * @evidence contracts/portability.md#os-neutral-implementation Actual process.cwd supplies the native default; a selected volume and alias spelling pass through unchanged without filesystem canonicalization.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed optional-value selection chooses no population-processing algorithm; the fallback delegates one actual process.cwd query.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The default is queried on each invocation because cwd may change; no computed result is shared here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selection owns no retained state, watcher or handle; record and bridge lifetime remain with their callers.
+ */
+export declare function selectBuildHostRoot(configuredRoot: string | undefined): string;

package/lib/core/bridge/buildHostRoot.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Resolve a configured native host root when configuration is received. An
+ * omitted root stays omitted so the adapter can distinguish Farm's selected
+ * location from the generic fallback. Resolution preserves lexical alias
+ * spelling; it does not canonicalize the root through the filesystem.
+ *
+ * @evidence contracts/common.md#principled-implementation An explicit root is resolved using native path grammar and current configuration-time cwd; undefined remains the absence of a configured root.
+ * @evidence contracts/common.md#clear-and-simple-design Configuration-time path resolution is separate from later default-root selection, so relative roots are anchored once while an omitted root remains dynamic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native path.resolve supplies grammar without platform guesses, filesystem alias replacement or a fabricated host root.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states resolution timing, the omitted-root distinction and lexical rather than physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.resolve interprets volumes, separators and relative roots against actual cwd without changing a filesystem alias to its realpath.
+ * @evidence contracts/performance.md#efficient-algorithms Explicit root resolution scans and normalizes path text and allocates its absolute spelling, without filesystem enumeration or identity probing; undefined performs no resolution.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation resolves its argument per configuration call; the caller stores the selected spelling rather than this operation caching it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned path text transfers to the caller; no handle, watcher or retained state is acquired.
+ */
+export declare function resolveConfiguredHostRoot(root: string | undefined): string | undefined;
+/**
+ * Use a previously resolved configured root, or the process's current directory
+ * at this invocation. A configured spelling remains fixed across cwd changes.
+ *
+ * @evidence contracts/common.md#principled-implementation Nullish fallback reads actual process.cwd only when no configured root exists; the configured string is returned unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One selection supplies the root used by record locations and bridge admission without owning either resource or its proof.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback is the actual working directory, not a guessed project root or a fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes invocation-time cwd from a configuration-time selected spelling.
+ * @evidence contracts/portability.md#os-neutral-implementation Actual process.cwd supplies the native default; a selected volume and alias spelling pass through unchanged without filesystem canonicalization.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed optional-value selection chooses no population-processing algorithm; the fallback delegates one actual process.cwd query.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The default is queried on each invocation because cwd may change; no computed result is shared here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selection owns no retained state, watcher or handle; record and bridge lifetime remain with their callers.
+ */
+export declare function selectBuildHostRoot(configuredRoot: string | undefined): string;

package/lib/core/bridge/buildHostRoot.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolve a configured native host root when configuration is received. An
+ * omitted root stays omitted so the adapter can distinguish Farm's selected
+ * location from the generic fallback. Resolution preserves lexical alias
+ * spelling; it does not canonicalize the root through the filesystem.
+ *
+ * @evidence contracts/common.md#principled-implementation An explicit root is resolved using native path grammar and current configuration-time cwd; undefined remains the absence of a configured root.
+ * @evidence contracts/common.md#clear-and-simple-design Configuration-time path resolution is separate from later default-root selection, so relative roots are anchored once while an omitted root remains dynamic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native path.resolve supplies grammar without platform guesses, filesystem alias replacement or a fabricated host root.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states resolution timing, the omitted-root distinction and lexical rather than physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.resolve interprets volumes, separators and relative roots against actual cwd without changing a filesystem alias to its realpath.
+ * @evidence contracts/performance.md#efficient-algorithms Explicit root resolution scans and normalizes path text and allocates its absolute spelling, without filesystem enumeration or identity probing; undefined performs no resolution.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation resolves its argument per configuration call; the caller stores the selected spelling rather than this operation caching it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned path text transfers to the caller; no handle, watcher or retained state is acquired.
+ */
+export declare function resolveConfiguredHostRoot(root: string | undefined): string | undefined;
+/**
+ * Use a previously resolved configured root, or the process's current directory
+ * at this invocation. A configured spelling remains fixed across cwd changes.
+ *
+ * @evidence contracts/common.md#principled-implementation Nullish fallback reads actual process.cwd only when no configured root exists; the configured string is returned unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One selection supplies the root used by record locations and bridge admission without owning either resource or its proof.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback is the actual working directory, not a guessed project root or a fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes invocation-time cwd from a configuration-time selected spelling.
+ * @evidence contracts/portability.md#os-neutral-implementation Actual process.cwd supplies the native default; a selected volume and alias spelling pass through unchanged without filesystem canonicalization.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed optional-value selection chooses no population-processing algorithm; the fallback delegates one actual process.cwd query.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The default is queried on each invocation because cwd may change; no computed result is shared here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selection owns no retained state, watcher or handle; record and bridge lifetime remain with their callers.
+ */
+export declare function selectBuildHostRoot(configuredRoot: string | undefined): string;

package/lib/core/bridge/buildHostRoot.js

@@ -0,0 +1,42 @@
+'use strict';
+
+var path = require('node:path');
+
+/**
+ * Resolve a configured native host root when configuration is received. An
+ * omitted root stays omitted so the adapter can distinguish Farm's selected
+ * location from the generic fallback. Resolution preserves lexical alias
+ * spelling; it does not canonicalize the root through the filesystem.
+ *
+ * @evidence contracts/common.md#principled-implementation An explicit root is resolved using native path grammar and current configuration-time cwd; undefined remains the absence of a configured root.
+ * @evidence contracts/common.md#clear-and-simple-design Configuration-time path resolution is separate from later default-root selection, so relative roots are anchored once while an omitted root remains dynamic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native path.resolve supplies grammar without platform guesses, filesystem alias replacement or a fabricated host root.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states resolution timing, the omitted-root distinction and lexical rather than physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.resolve interprets volumes, separators and relative roots against actual cwd without changing a filesystem alias to its realpath.
+ * @evidence contracts/performance.md#efficient-algorithms Explicit root resolution scans and normalizes path text and allocates its absolute spelling, without filesystem enumeration or identity probing; undefined performs no resolution.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation resolves its argument per configuration call; the caller stores the selected spelling rather than this operation caching it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned path text transfers to the caller; no handle, watcher or retained state is acquired.
+ */
+function resolveConfiguredHostRoot(root) {
+    return root === undefined ? undefined : path.resolve(root);
+}
+/**
+ * Use a previously resolved configured root, or the process's current directory
+ * at this invocation. A configured spelling remains fixed across cwd changes.
+ *
+ * @evidence contracts/common.md#principled-implementation Nullish fallback reads actual process.cwd only when no configured root exists; the configured string is returned unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One selection supplies the root used by record locations and bridge admission without owning either resource or its proof.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback is the actual working directory, not a guessed project root or a fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes invocation-time cwd from a configuration-time selected spelling.
+ * @evidence contracts/portability.md#os-neutral-implementation Actual process.cwd supplies the native default; a selected volume and alias spelling pass through unchanged without filesystem canonicalization.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed optional-value selection chooses no population-processing algorithm; the fallback delegates one actual process.cwd query.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The default is queried on each invocation because cwd may change; no computed result is shared here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selection owns no retained state, watcher or handle; record and bridge lifetime remain with their callers.
+ */
+function selectBuildHostRoot(configuredRoot) {
+    return configuredRoot ?? process.cwd();
+}
+
+exports.resolveConfiguredHostRoot = resolveConfiguredHostRoot;
+exports.selectBuildHostRoot = selectBuildHostRoot;
+//# sourceMappingURL=buildHostRoot.js.map

package/lib/core/bridge/buildHostRoot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildHostRoot.js","sources":["../../../src/core/bridge/buildHostRoot.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAEA;;;;;;;;;;;;;;AAcG;AACG,SAAU,yBAAyB,CACvC,IAAwB,EAAA;AAExB,IAAA,OAAO,IAAI,KAAK,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;AAC5D;AAEA;;;;;;;;;;;;AAYG;AACG,SAAU,mBAAmB,CACjC,cAAkC,EAAA;AAElC,IAAA,OAAO,cAAc,IAAI,OAAO,CAAC,GAAG,EAAE;AACxC;;;;;"}

package/lib/core/bridge/buildHostRoot.mjs

@@ -0,0 +1,39 @@
+import path from 'node:path';
+
+/**
+ * Resolve a configured native host root when configuration is received. An
+ * omitted root stays omitted so the adapter can distinguish Farm's selected
+ * location from the generic fallback. Resolution preserves lexical alias
+ * spelling; it does not canonicalize the root through the filesystem.
+ *
+ * @evidence contracts/common.md#principled-implementation An explicit root is resolved using native path grammar and current configuration-time cwd; undefined remains the absence of a configured root.
+ * @evidence contracts/common.md#clear-and-simple-design Configuration-time path resolution is separate from later default-root selection, so relative roots are anchored once while an omitted root remains dynamic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native path.resolve supplies grammar without platform guesses, filesystem alias replacement or a fabricated host root.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states resolution timing, the omitted-root distinction and lexical rather than physical identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path.resolve interprets volumes, separators and relative roots against actual cwd without changing a filesystem alias to its realpath.
+ * @evidence contracts/performance.md#efficient-algorithms Explicit root resolution scans and normalizes path text and allocates its absolute spelling, without filesystem enumeration or identity probing; undefined performs no resolution.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation resolves its argument per configuration call; the caller stores the selected spelling rather than this operation caching it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned path text transfers to the caller; no handle, watcher or retained state is acquired.
+ */
+function resolveConfiguredHostRoot(root) {
+    return root === undefined ? undefined : path.resolve(root);
+}
+/**
+ * Use a previously resolved configured root, or the process's current directory
+ * at this invocation. A configured spelling remains fixed across cwd changes.
+ *
+ * @evidence contracts/common.md#principled-implementation Nullish fallback reads actual process.cwd only when no configured root exists; the configured string is returned unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One selection supplies the root used by record locations and bridge admission without owning either resource or its proof.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback is the actual working directory, not a guessed project root or a fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes invocation-time cwd from a configuration-time selected spelling.
+ * @evidence contracts/portability.md#os-neutral-implementation Actual process.cwd supplies the native default; a selected volume and alias spelling pass through unchanged without filesystem canonicalization.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed optional-value selection chooses no population-processing algorithm; the fallback delegates one actual process.cwd query.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The default is queried on each invocation because cwd may change; no computed result is shared here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selection owns no retained state, watcher or handle; record and bridge lifetime remain with their callers.
+ */
+function selectBuildHostRoot(configuredRoot) {
+    return configuredRoot ?? process.cwd();
+}
+
+export { resolveConfiguredHostRoot, selectBuildHostRoot };
+//# sourceMappingURL=buildHostRoot.mjs.map

package/lib/core/bridge/buildHostRoot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildHostRoot.mjs","sources":["../../../src/core/bridge/buildHostRoot.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;AAcG;AACG,SAAU,yBAAyB,CACvC,IAAwB,EAAA;AAExB,IAAA,OAAO,IAAI,KAAK,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;AAC5D;AAEA;;;;;;;;;;;;AAYG;AACG,SAAU,mBAAmB,CACjC,cAAkC,EAAA;AAElC,IAAA,OAAO,cAAc,IAAI,OAAO,CAAC,GAAG,EAAE;AACxC;;;;"}

package/lib/core/bridge/createBuildWatchFile.d.cts

@@ -0,0 +1,27 @@
+import type { NativeBuildContext, UnpluginBuildContext } from "unplugin";
+/**
+ * Select the build host's module-level file registration channel. Farm
+ * associates the input with the delivered module. Webpack and Rspack use their
+ * available loader context; without one, registration uses the generic context.
+ * The selected loader is also returned for the caller's cacheability decision,
+ * so its native property is read only once. The returned callback preserves
+ * each method's receiver and errors. Selecting a channel does not certify host
+ * receipt or watch coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Farm receives the delivered module and input; a present webpack/Rspack loader receives only the input through addDependency; other contexts use addWatchFile. No compilation-level, missing-file or directory channel substitutes for module registration.
+ * @evidence contracts/common.md#clear-and-simple-design One production-used factory owns channel selection, while registerProjectRecord owns record handoff and the host owns invalidation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported context methods are called with their original receivers; no foreign method replacement or private host mutation fabricates registration.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains module association, optional loader fallback, receiver/error preservation and the limit of channel selection.
+ * @evidence contracts/portability.md#os-neutral-implementation Delivered module and native input spellings cross the host registration boundary unchanged; the host controls filesystem interpretation and this operation asserts no native watch coverage.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed channel selection chooses no population-processing algorithm. Each invocation delegates one host registration effect whose cost belongs to that host.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Registration is a per-delivery effect and is not skipped or memoized on matching file strings.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The callback borrows context and module references for its caller-owned lifetime and acquires no watcher, handle or retained generation.
+ */
+export declare function createBuildWatchFile(context: Pick<UnpluginBuildContext, "addWatchFile">, native: NativeBuildContext | undefined, file: string): {
+    /** The selected module-level registration channel. */
+    addWatchFile: (input: string) => void;
+    /** The same optional loader used for the caller's cacheability capability. */
+    loaderContext: Extract<NativeBuildContext, {
+        framework: "webpack" | "rspack";
+    }>["loaderContext"];
+};

package/lib/core/bridge/createBuildWatchFile.d.mts

@@ -0,0 +1,27 @@
+import type { NativeBuildContext, UnpluginBuildContext } from "unplugin";
+/**
+ * Select the build host's module-level file registration channel. Farm
+ * associates the input with the delivered module. Webpack and Rspack use their
+ * available loader context; without one, registration uses the generic context.
+ * The selected loader is also returned for the caller's cacheability decision,
+ * so its native property is read only once. The returned callback preserves
+ * each method's receiver and errors. Selecting a channel does not certify host
+ * receipt or watch coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Farm receives the delivered module and input; a present webpack/Rspack loader receives only the input through addDependency; other contexts use addWatchFile. No compilation-level, missing-file or directory channel substitutes for module registration.
+ * @evidence contracts/common.md#clear-and-simple-design One production-used factory owns channel selection, while registerProjectRecord owns record handoff and the host owns invalidation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported context methods are called with their original receivers; no foreign method replacement or private host mutation fabricates registration.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains module association, optional loader fallback, receiver/error preservation and the limit of channel selection.
+ * @evidence contracts/portability.md#os-neutral-implementation Delivered module and native input spellings cross the host registration boundary unchanged; the host controls filesystem interpretation and this operation asserts no native watch coverage.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed channel selection chooses no population-processing algorithm. Each invocation delegates one host registration effect whose cost belongs to that host.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Registration is a per-delivery effect and is not skipped or memoized on matching file strings.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The callback borrows context and module references for its caller-owned lifetime and acquires no watcher, handle or retained generation.
+ */
+export declare function createBuildWatchFile(context: Pick<UnpluginBuildContext, "addWatchFile">, native: NativeBuildContext | undefined, file: string): {
+    /** The selected module-level registration channel. */
+    addWatchFile: (input: string) => void;
+    /** The same optional loader used for the caller's cacheability capability. */
+    loaderContext: Extract<NativeBuildContext, {
+        framework: "webpack" | "rspack";
+    }>["loaderContext"];
+};

package/lib/core/bridge/createBuildWatchFile.d.ts

@@ -0,0 +1,27 @@
+import type { NativeBuildContext, UnpluginBuildContext } from "unplugin";
+/**
+ * Select the build host's module-level file registration channel. Farm
+ * associates the input with the delivered module. Webpack and Rspack use their
+ * available loader context; without one, registration uses the generic context.
+ * The selected loader is also returned for the caller's cacheability decision,
+ * so its native property is read only once. The returned callback preserves
+ * each method's receiver and errors. Selecting a channel does not certify host
+ * receipt or watch coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Farm receives the delivered module and input; a present webpack/Rspack loader receives only the input through addDependency; other contexts use addWatchFile. No compilation-level, missing-file or directory channel substitutes for module registration.
+ * @evidence contracts/common.md#clear-and-simple-design One production-used factory owns channel selection, while registerProjectRecord owns record handoff and the host owns invalidation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported context methods are called with their original receivers; no foreign method replacement or private host mutation fabricates registration.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains module association, optional loader fallback, receiver/error preservation and the limit of channel selection.
+ * @evidence contracts/portability.md#os-neutral-implementation Delivered module and native input spellings cross the host registration boundary unchanged; the host controls filesystem interpretation and this operation asserts no native watch coverage.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed channel selection chooses no population-processing algorithm. Each invocation delegates one host registration effect whose cost belongs to that host.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Registration is a per-delivery effect and is not skipped or memoized on matching file strings.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The callback borrows context and module references for its caller-owned lifetime and acquires no watcher, handle or retained generation.
+ */
+export declare function createBuildWatchFile(context: Pick<UnpluginBuildContext, "addWatchFile">, native: NativeBuildContext | undefined, file: string): {
+    /** The selected module-level registration channel. */
+    addWatchFile: (input: string) => void;
+    /** The same optional loader used for the caller's cacheability capability. */
+    loaderContext: Extract<NativeBuildContext, {
+        framework: "webpack" | "rspack";
+    }>["loaderContext"];
+};

package/lib/core/bridge/createBuildWatchFile.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Select the build host's module-level file registration channel. Farm
+ * associates the input with the delivered module. Webpack and Rspack use their
+ * available loader context; without one, registration uses the generic context.
+ * The selected loader is also returned for the caller's cacheability decision,
+ * so its native property is read only once. The returned callback preserves
+ * each method's receiver and errors. Selecting a channel does not certify host
+ * receipt or watch coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Farm receives the delivered module and input; a present webpack/Rspack loader receives only the input through addDependency; other contexts use addWatchFile. No compilation-level, missing-file or directory channel substitutes for module registration.
+ * @evidence contracts/common.md#clear-and-simple-design One production-used factory owns channel selection, while registerProjectRecord owns record handoff and the host owns invalidation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported context methods are called with their original receivers; no foreign method replacement or private host mutation fabricates registration.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains module association, optional loader fallback, receiver/error preservation and the limit of channel selection.
+ * @evidence contracts/portability.md#os-neutral-implementation Delivered module and native input spellings cross the host registration boundary unchanged; the host controls filesystem interpretation and this operation asserts no native watch coverage.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed channel selection chooses no population-processing algorithm. Each invocation delegates one host registration effect whose cost belongs to that host.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Registration is a per-delivery effect and is not skipped or memoized on matching file strings.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The callback borrows context and module references for its caller-owned lifetime and acquires no watcher, handle or retained generation.
+ */
+function createBuildWatchFile(context, native, file) {
+    const loaderContext = native?.framework === "webpack" || native?.framework === "rspack"
+        ? native.loaderContext
+        : undefined;
+    return {
+        addWatchFile: native?.framework === "farm"
+            ? (input) => native.context.addWatchFile(file, input)
+            : loaderContext !== undefined
+                ? (input) => loaderContext.addDependency(input)
+                : (input) => context.addWatchFile(input),
+        loaderContext,
+    };
+}
+
+exports.createBuildWatchFile = createBuildWatchFile;
+//# sourceMappingURL=createBuildWatchFile.js.map

package/lib/core/bridge/createBuildWatchFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBuildWatchFile.js","sources":["../../../src/core/bridge/createBuildWatchFile.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;AAiBG;SACa,oBAAoB,CAClC,OAAmD,EACnD,MAAsC,EACtC,IAAY,EAAA;AAWZ,IAAA,MAAM,aAAa,GACjB,MAAM,EAAE,SAAS,KAAK,SAAS,IAAI,MAAM,EAAE,SAAS,KAAK;UACrD,MAAM,CAAC;UACP,SAAS;IACf,OAAO;AACL,QAAA,YAAY,EACV,MAAM,EAAE,SAAS,KAAK;AACpB,cAAE,CAAC,KAAK,KAAK,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK;cAClD,aAAa,KAAK;kBAChB,CAAC,KAAK,KAAK,aAAa,CAAC,aAAa,CAAC,KAAK;kBAC5C,CAAC,KAAK,KAAK,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC;QAC9C,aAAa;KACd;AACH;;;;"}

package/lib/core/bridge/createBuildWatchFile.mjs

@@ -0,0 +1,34 @@
+/**
+ * Select the build host's module-level file registration channel. Farm
+ * associates the input with the delivered module. Webpack and Rspack use their
+ * available loader context; without one, registration uses the generic context.
+ * The selected loader is also returned for the caller's cacheability decision,
+ * so its native property is read only once. The returned callback preserves
+ * each method's receiver and errors. Selecting a channel does not certify host
+ * receipt or watch coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Farm receives the delivered module and input; a present webpack/Rspack loader receives only the input through addDependency; other contexts use addWatchFile. No compilation-level, missing-file or directory channel substitutes for module registration.
+ * @evidence contracts/common.md#clear-and-simple-design One production-used factory owns channel selection, while registerProjectRecord owns record handoff and the host owns invalidation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported context methods are called with their original receivers; no foreign method replacement or private host mutation fabricates registration.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains module association, optional loader fallback, receiver/error preservation and the limit of channel selection.
+ * @evidence contracts/portability.md#os-neutral-implementation Delivered module and native input spellings cross the host registration boundary unchanged; the host controls filesystem interpretation and this operation asserts no native watch coverage.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed channel selection chooses no population-processing algorithm. Each invocation delegates one host registration effect whose cost belongs to that host.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Registration is a per-delivery effect and is not skipped or memoized on matching file strings.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The callback borrows context and module references for its caller-owned lifetime and acquires no watcher, handle or retained generation.
+ */
+function createBuildWatchFile(context, native, file) {
+    const loaderContext = native?.framework === "webpack" || native?.framework === "rspack"
+        ? native.loaderContext
+        : undefined;
+    return {
+        addWatchFile: native?.framework === "farm"
+            ? (input) => native.context.addWatchFile(file, input)
+            : loaderContext !== undefined
+                ? (input) => loaderContext.addDependency(input)
+                : (input) => context.addWatchFile(input),
+        loaderContext,
+    };
+}
+
+export { createBuildWatchFile };
+//# sourceMappingURL=createBuildWatchFile.mjs.map

package/lib/core/bridge/createBuildWatchFile.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBuildWatchFile.mjs","sources":["../../../src/core/bridge/createBuildWatchFile.ts"],"sourcesContent":[null],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;AAiBG;SACa,oBAAoB,CAClC,OAAmD,EACnD,MAAsC,EACtC,IAAY,EAAA;AAWZ,IAAA,MAAM,aAAa,GACjB,MAAM,EAAE,SAAS,KAAK,SAAS,IAAI,MAAM,EAAE,SAAS,KAAK;UACrD,MAAM,CAAC;UACP,SAAS;IACf,OAAO;AACL,QAAA,YAAY,EACV,MAAM,EAAE,SAAS,KAAK;AACpB,cAAE,CAAC,KAAK,KAAK,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK;cAClD,aAAa,KAAK;kBAChB,CAAC,KAAK,KAAK,aAAa,CAAC,aAAa,CAAC,KAAK;kBAC5C,CAAC,KAAK,KAAK,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC;QAC9C,aAAa;KACd;AACH;;;;"}

package/lib/core/bridge/fallbackToolDirectory.d.cts

@@ -0,0 +1,45 @@
+/**
+ * Where a host's project records live when its own tool directory
+ * (`hostToolDirectory`) cannot be written, or `undefined` when this user has no
+ * such place either (samchon/ttsc#1480).
+ *
+ * A module handed to a build host without its project's record depends on its
+ * own bytes alone: a watching session cannot tell the host that a type the
+ * module's output consulted changed, and a persistent cache restores it
+ * whatever its types did. A read-only checkout, a restricted sandbox, or a file
+ * standing where `.ttsc` would be leaves the root unwritable, so the record
+ * then lives below this user's own directory under the system temporary
+ * directory (`userStateDirectory`), one directory per host root.
+ *
+ * The place is the same for a host root in every process, since a persistent
+ * cache that recorded a record's path must find it at its next start, and the
+ * build start's proof and a watching session's bridge look there as well as
+ * below the root. It is spelled in its long form, which webpack and Rspack
+ * require of a watched directory on Windows. A host that accepts no record
+ * outside its root, Turbopack, or none it cannot relate to its root, Farm on
+ * another drive, does not take it (`hostToolDirectory`).
+ *
+ * @param root The host's root, as `hostToolDirectory` names it.
+ * @evidence contracts/common.md#principled-implementation
+ *   A resolved-root digest gives each host a stable directory beneath the
+ *   validated user state root; absence remains explicit when no safe root exists.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This helper owns root-to-fallback naming while userStateDirectory owns
+ *   directory trust and hosts decide whether outside-root dependencies are allowed.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The fallback handles actual unwritable roots using a product-owned user
+ *   directory, not an arbitrary globally writable or fixture-specific location.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain stable paths, Windows long spelling and hosts
+ *   that cannot accept the fallback, following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The validated user state boundary obtains a private native directory and long Windows spelling; native root resolution determines naming, while adapters separately reject fallback locations their host cannot watch.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Every call resolves and hashes the root's map key text. A cold name also
+ *   obtains the native temporary-root realpath, recursive state-directory
+ *   creation and directory-kind/available-uid checks, then hashes and joins
+ *   the fallback spelling. A warm name avoids those delegated checks and the
+ *   naming digest, not root resolution or map-key work.
+ * @evidence contracts/performance.md#reuse-equivalent-work A resolved host root shares its stable fallback naming within the process; actual write capability is checked by writers rather than certified by the cached name, and an unavailable initial user root remains unavailable here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The module map retains one optional naming result per distinct resolved root for the process lifetime, without an eviction bound; no native handle is retained, and record-directory persistence belongs to the host cache protocol.
+ */
+export declare function fallbackToolDirectory(root: string): string | undefined;

package/lib/core/bridge/fallbackToolDirectory.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Where a host's project records live when its own tool directory
+ * (`hostToolDirectory`) cannot be written, or `undefined` when this user has no
+ * such place either (samchon/ttsc#1480).
+ *
+ * A module handed to a build host without its project's record depends on its
+ * own bytes alone: a watching session cannot tell the host that a type the
+ * module's output consulted changed, and a persistent cache restores it
+ * whatever its types did. A read-only checkout, a restricted sandbox, or a file
+ * standing where `.ttsc` would be leaves the root unwritable, so the record
+ * then lives below this user's own directory under the system temporary
+ * directory (`userStateDirectory`), one directory per host root.
+ *
+ * The place is the same for a host root in every process, since a persistent
+ * cache that recorded a record's path must find it at its next start, and the
+ * build start's proof and a watching session's bridge look there as well as
+ * below the root. It is spelled in its long form, which webpack and Rspack
+ * require of a watched directory on Windows. A host that accepts no record
+ * outside its root, Turbopack, or none it cannot relate to its root, Farm on
+ * another drive, does not take it (`hostToolDirectory`).
+ *
+ * @param root The host's root, as `hostToolDirectory` names it.
+ * @evidence contracts/common.md#principled-implementation
+ *   A resolved-root digest gives each host a stable directory beneath the
+ *   validated user state root; absence remains explicit when no safe root exists.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This helper owns root-to-fallback naming while userStateDirectory owns
+ *   directory trust and hosts decide whether outside-root dependencies are allowed.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The fallback handles actual unwritable roots using a product-owned user
+ *   directory, not an arbitrary globally writable or fixture-specific location.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain stable paths, Windows long spelling and hosts
+ *   that cannot accept the fallback, following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The validated user state boundary obtains a private native directory and long Windows spelling; native root resolution determines naming, while adapters separately reject fallback locations their host cannot watch.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Every call resolves and hashes the root's map key text. A cold name also
+ *   obtains the native temporary-root realpath, recursive state-directory
+ *   creation and directory-kind/available-uid checks, then hashes and joins
+ *   the fallback spelling. A warm name avoids those delegated checks and the
+ *   naming digest, not root resolution or map-key work.
+ * @evidence contracts/performance.md#reuse-equivalent-work A resolved host root shares its stable fallback naming within the process; actual write capability is checked by writers rather than certified by the cached name, and an unavailable initial user root remains unavailable here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The module map retains one optional naming result per distinct resolved root for the process lifetime, without an eviction bound; no native handle is retained, and record-directory persistence belongs to the host cache protocol.
+ */
+export declare function fallbackToolDirectory(root: string): string | undefined;

package/lib/core/bridge/fallbackToolDirectory.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a host's project records live when its own tool directory
+ * (`hostToolDirectory`) cannot be written, or `undefined` when this user has no
+ * such place either (samchon/ttsc#1480).
+ *
+ * A module handed to a build host without its project's record depends on its
+ * own bytes alone: a watching session cannot tell the host that a type the
+ * module's output consulted changed, and a persistent cache restores it
+ * whatever its types did. A read-only checkout, a restricted sandbox, or a file
+ * standing where `.ttsc` would be leaves the root unwritable, so the record
+ * then lives below this user's own directory under the system temporary
+ * directory (`userStateDirectory`), one directory per host root.
+ *
+ * The place is the same for a host root in every process, since a persistent
+ * cache that recorded a record's path must find it at its next start, and the
+ * build start's proof and a watching session's bridge look there as well as
+ * below the root. It is spelled in its long form, which webpack and Rspack
+ * require of a watched directory on Windows. A host that accepts no record
+ * outside its root, Turbopack, or none it cannot relate to its root, Farm on
+ * another drive, does not take it (`hostToolDirectory`).
+ *
+ * @param root The host's root, as `hostToolDirectory` names it.
+ * @evidence contracts/common.md#principled-implementation
+ *   A resolved-root digest gives each host a stable directory beneath the
+ *   validated user state root; absence remains explicit when no safe root exists.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This helper owns root-to-fallback naming while userStateDirectory owns
+ *   directory trust and hosts decide whether outside-root dependencies are allowed.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The fallback handles actual unwritable roots using a product-owned user
+ *   directory, not an arbitrary globally writable or fixture-specific location.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain stable paths, Windows long spelling and hosts
+ *   that cannot accept the fallback, following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The validated user state boundary obtains a private native directory and long Windows spelling; native root resolution determines naming, while adapters separately reject fallback locations their host cannot watch.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Every call resolves and hashes the root's map key text. A cold name also
+ *   obtains the native temporary-root realpath, recursive state-directory
+ *   creation and directory-kind/available-uid checks, then hashes and joins
+ *   the fallback spelling. A warm name avoids those delegated checks and the
+ *   naming digest, not root resolution or map-key work.
+ * @evidence contracts/performance.md#reuse-equivalent-work A resolved host root shares its stable fallback naming within the process; actual write capability is checked by writers rather than certified by the cached name, and an unavailable initial user root remains unavailable here.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The module map retains one optional naming result per distinct resolved root for the process lifetime, without an eviction bound; no native handle is retained, and record-directory persistence belongs to the host cache protocol.
+ */
+export declare function fallbackToolDirectory(root: string): string | undefined;