@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/envelope/selectTransformedSource.mjs

@@ -0,0 +1,73 @@
+import { searchedReferencedProjects } from '../../tsconfig/searchedReferencedProjects.mjs';
+import { formatDiagnostics } from '../diagnostics/formatDiagnostics.mjs';
+import { formatUnknownError } from '../diagnostics/formatUnknownError.mjs';
+import { TtscCompileFailureError } from '../errors/TtscCompileFailureError.mjs';
+import { TtscMissingProgramOutputError } from '../errors/TtscMissingProgramOutputError.mjs';
+import { toProjectKey } from '../project/toProjectKey.mjs';
+import { createEnvelopeKeyIndex } from './createEnvelopeKeyIndex.mjs';
+import { derivationIdentity } from './derivationIdentity.mjs';
+import { envelopeDerivation } from './envelopeDerivation.mjs';
+
+/**
+ * Extract the transformed source for a single file from the compiler result,
+ * with the source map the envelope carries for the same key.
+ *
+ * Throws on compiler exception or hard failure so the bundler surfaces the
+ * error to the user. On success, tries a fast exact-match lookup by
+ * project-relative key first, then falls back to a lazy first-match identity
+ * index when the key in `result.typescript` uses an absolute or
+ * differently-cased path. The map is read under the key the text was found
+ * under, so the two always describe the same envelope entry
+ * (samchon/ttsc#1392).
+ *
+ * @evidence contracts/common.md#principled-implementation The matched producer key selects both transformed text and its own source map, preventing provenance from another alias entry; exception/failure results and missing program output raise their distinct supported errors.
+ * @evidence contracts/common.md#clear-and-simple-design Result discrimination precedes lookup, a local output adapter binds code to map, and the shared identity index isolates alternate-spelling lookup from error reporting.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback supports real producer key spelling differences with first-match precedence; absent output is reported rather than synthesized from original source or a different module's map.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe source/map coupling, error behavior and exact versus identity lookup; the acknowledgment block follows the documentation skill's spacing guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Project key matching and alternate key identities use the envelope's filesystem context, so physical aliases and native case behavior are not guessed from lowercased strings.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One key per physical output identity is retained in weakly owned envelope state; returned artifacts reference generation output, and this selector owns no independent handle or cross-generation history.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Successful lookup pays native project-key/path/identity work before an own
+ *   record probe. A first miss materializes output keys, key/value pairs and the
+ *   identity index, paying every key's text and uncached native observations;
+ *   later misses reuse it. Error routes format diagnostic/unknown-value text;
+ *   missing output also traverses reachable config references, reads their
+ *   selection data and constructs the path-list message. Costs follow those
+ *   populations, paths and content, not only the number of output keys.
+ * @evidence contracts/performance.md#reuse-equivalent-work The output index is reused only for the same immutable generation and project root; text and maps remain coupled by the saved producer key, not by an inferred equality of their contents.
+ */
+function selectTransformedSource(props) {
+    if (props.result.type === "exception") {
+        throw new TtscCompileFailureError(formatUnknownError(props.result.error));
+    }
+    if (props.result.type === "failure") {
+        throw new TtscCompileFailureError(formatDiagnostics(props.result.diagnostics));
+    }
+    // Fast path: the compiler key matches the normalised project-relative path.
+    const state = envelopeDerivation(props);
+    const key = toProjectKey(props.projectRoot, props.file, state.identityContext);
+    const { sourceMaps, typescript } = props.result;
+    const output = (found) => {
+        const map = sourceMaps !== undefined &&
+            Object.prototype.hasOwnProperty.call(sourceMaps, found)
+            ? sourceMaps[found]
+            : undefined;
+        return map === undefined
+            ? { code: typescript[found] }
+            : { code: typescript[found], map };
+    };
+    if (Object.prototype.hasOwnProperty.call(typescript, key)) {
+        return output(key);
+    }
+    // Slow path: the first-match identity index of the envelope's `typescript`
+    // keys, built once per generation instead of scanned per delivery.
+    const index = (state.outputIndex ??= createEnvelopeKeyIndex(state, props.projectRoot, Object.fromEntries(Object.keys(typescript).map((entry) => [entry, entry]))));
+    const found = index.get(derivationIdentity(state, props.file));
+    if (found !== undefined) {
+        return output(found);
+    }
+    throw new TtscMissingProgramOutputError(props.file, props.tsconfig, searchedReferencedProjects(props.tsconfig));
+}
+
+export { selectTransformedSource };
+//# sourceMappingURL=selectTransformedSource.mjs.map

package/lib/core/transform/envelope/selectTransformedSource.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectTransformedSource.mjs","sources":["../../../../src/core/transform/envelope/selectTransformedSource.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;;;AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,uBAAuB,CAAC,KAYvC,EAAA;IACC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE;AACrC,QAAA,MAAM,IAAI,uBAAuB,CAAC,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3E;IACA,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE;AACnC,QAAA,MAAM,IAAI,uBAAuB,CAC/B,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAC5C;IACH;;AAGA,IAAA,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC;AACvC,IAAA,MAAM,GAAG,GAAG,YAAY,CACtB,KAAK,CAAC,WAAW,EACjB,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,eAAe,CACtB;IACD,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,MAAM;AAC/C,IAAA,MAAM,MAAM,GAAG,CAAC,KAAa,KAA2B;AACtD,QAAA,MAAM,GAAG,GACP,UAAU,KAAK,SAAS;YACxB,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK;AACpD,cAAE,UAAU,CAAC,KAAK;cAChB,SAAS;QACf,OAAO,GAAG,KAAK;cACX,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAE;cAC1B,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAE,EAAE,GAAG,EAAE;AACvC,IAAA,CAAC;AACD,IAAA,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE;AACzD,QAAA,OAAO,MAAM,CAAC,GAAG,CAAC;IACpB;;;AAGA,IAAA,MAAM,KAAK,IAAI,KAAK,CAAC,WAAW,KAAK,sBAAsB,CACzD,KAAK,EACL,KAAK,CAAC,WAAW,EACjB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAC3E,CAAC;AACF,IAAA,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AAC9D,IAAA,IAAI,KAAK,KAAK,SAAS,EAAE;AACvB,QAAA,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB;AACA,IAAA,MAAM,IAAI,6BAA6B,CACrC,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,QAAQ,EACd,0BAA0B,CAAC,KAAK,CAAC,QAAQ,CAAC,CAC3C;AACH;;;;"}

package/lib/core/transform/envelope/selectWatchInputs.d.cts

@@ -0,0 +1,49 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * Derive the absolute, deduplicated watch-input list for a single file.
+ *
+ * By default the derivation unions plugin dependencies, the reachable graph,
+ * globals, configs, importer resolver inputs, and universal resolver inputs.
+ * The plugin-reported list can only widen the host-owned language-semantic
+ * bound, never narrow it. Resolver inputs remain in that bound in both modes.
+ *
+ * An envelope that lists `file` in `dependenciesComplete` narrows it to
+ * `dependencies[file] ∪ configs`: the plugin declared its reported list the
+ * complete input set for that file, which transfers responsibility for the
+ * dropped `reach(edges, file) ∪ globals` bound to the plugin (see the protocol
+ * page's completeness contract). The config chain stays universal regardless,
+ * because compiler options reach generated code through the host rather than
+ * through any file a plugin could consult. A file the plugin also declared
+ * volatile keeps the baseline: the two declarations contradict, so the
+ * conservative one wins.
+ *
+ * The derived list uses the envelope, fixed project/options and the
+ * generation's observed native identity view, keyed by the delivered file's
+ * normalized lexical spelling. Graph traversal uses its filesystem identity,
+ * but lexical inputs exclude only that exact spelling, so two aliases of one
+ * source require distinct lists. Repeated deliveries of one spelling replay the
+ * per-envelope memo ({@link envelopeDerivation}) instead of re-walking the
+ * graph. Returns an empty list on exceptions.
+ *
+ * The returned array is the generation's cached list and must not be mutated.
+ * Project root, scratch exclusions and temporary config options must stay fixed
+ * for the result object's lifetime, since the memo key includes only module
+ * spelling within that generation. The native identity view must remain valid
+ * for that generation; this memo does not independently prove current inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation The final list follows deriveWatchInputs' conservative union and conditional completeness rule; exact lexical module keys keep alias-sensitive exclusions distinct even when graph identity is shared.
+ * @evidence contracts/common.md#clear-and-simple-design This entry point owns final-list memoization and delegates input policy and merging to deriveWatchInputs, sharing state through envelopeDerivation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Completeness cannot remove host-owned resolver inputs, and volatility retains the baseline; exceptions produce no fabricated watch list or guessed substitute dependency.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain baseline and narrowed bounds, contradictory declarations, lexical memo keys and exception results with documentation-skill paragraph and tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native absolute lexical spellings key alias-sensitive lists, while the envelope context supplies physical identity to graph traversal; these domains remain distinct instead of using manual case or separator normalization.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One array and lexical key per requested module spelling is retained in envelope state, alongside shared indexes and native context observations. List members follow selected generation inputs, but distinct requested spellings and their text have no capacity or byte cap. Weak association does not keep the envelope alive; a borrower retaining returned state or arrays can extend storage lifetime. No watcher handle is opened here.
+ * @evidence contracts/performance.md#efficient-algorithms Even a cached list request selects envelope state, queries the delivered path identity and resolves its lexical spelling before the final Map lookup, paying path/key text and any cold native identity observations. A first list additionally derives the dependency/graph/resolver union and deduplication with their visited/selected/index populations; later identical spellings avoid that derivation, not all path work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reuse requires one immutable envelope/root, stable scratch and temporary-config options and a still-valid native identity view. The key is lexical module spelling because different aliases exclude different paths; final lists do not certify current filesystem freshness. Callers must treat the returned cached array as read-only.
+ */
+export declare function selectWatchInputs(props: {
+    file: string;
+    projectRoot: string;
+    result: ITtscCompilerTransformation;
+    scratchDirectory?: string;
+    temporaryTsconfig?: string;
+}): string[];

package/lib/core/transform/envelope/selectWatchInputs.d.mts

@@ -0,0 +1,49 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * Derive the absolute, deduplicated watch-input list for a single file.
+ *
+ * By default the derivation unions plugin dependencies, the reachable graph,
+ * globals, configs, importer resolver inputs, and universal resolver inputs.
+ * The plugin-reported list can only widen the host-owned language-semantic
+ * bound, never narrow it. Resolver inputs remain in that bound in both modes.
+ *
+ * An envelope that lists `file` in `dependenciesComplete` narrows it to
+ * `dependencies[file] ∪ configs`: the plugin declared its reported list the
+ * complete input set for that file, which transfers responsibility for the
+ * dropped `reach(edges, file) ∪ globals` bound to the plugin (see the protocol
+ * page's completeness contract). The config chain stays universal regardless,
+ * because compiler options reach generated code through the host rather than
+ * through any file a plugin could consult. A file the plugin also declared
+ * volatile keeps the baseline: the two declarations contradict, so the
+ * conservative one wins.
+ *
+ * The derived list uses the envelope, fixed project/options and the
+ * generation's observed native identity view, keyed by the delivered file's
+ * normalized lexical spelling. Graph traversal uses its filesystem identity,
+ * but lexical inputs exclude only that exact spelling, so two aliases of one
+ * source require distinct lists. Repeated deliveries of one spelling replay the
+ * per-envelope memo ({@link envelopeDerivation}) instead of re-walking the
+ * graph. Returns an empty list on exceptions.
+ *
+ * The returned array is the generation's cached list and must not be mutated.
+ * Project root, scratch exclusions and temporary config options must stay fixed
+ * for the result object's lifetime, since the memo key includes only module
+ * spelling within that generation. The native identity view must remain valid
+ * for that generation; this memo does not independently prove current inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation The final list follows deriveWatchInputs' conservative union and conditional completeness rule; exact lexical module keys keep alias-sensitive exclusions distinct even when graph identity is shared.
+ * @evidence contracts/common.md#clear-and-simple-design This entry point owns final-list memoization and delegates input policy and merging to deriveWatchInputs, sharing state through envelopeDerivation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Completeness cannot remove host-owned resolver inputs, and volatility retains the baseline; exceptions produce no fabricated watch list or guessed substitute dependency.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain baseline and narrowed bounds, contradictory declarations, lexical memo keys and exception results with documentation-skill paragraph and tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native absolute lexical spellings key alias-sensitive lists, while the envelope context supplies physical identity to graph traversal; these domains remain distinct instead of using manual case or separator normalization.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One array and lexical key per requested module spelling is retained in envelope state, alongside shared indexes and native context observations. List members follow selected generation inputs, but distinct requested spellings and their text have no capacity or byte cap. Weak association does not keep the envelope alive; a borrower retaining returned state or arrays can extend storage lifetime. No watcher handle is opened here.
+ * @evidence contracts/performance.md#efficient-algorithms Even a cached list request selects envelope state, queries the delivered path identity and resolves its lexical spelling before the final Map lookup, paying path/key text and any cold native identity observations. A first list additionally derives the dependency/graph/resolver union and deduplication with their visited/selected/index populations; later identical spellings avoid that derivation, not all path work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reuse requires one immutable envelope/root, stable scratch and temporary-config options and a still-valid native identity view. The key is lexical module spelling because different aliases exclude different paths; final lists do not certify current filesystem freshness. Callers must treat the returned cached array as read-only.
+ */
+export declare function selectWatchInputs(props: {
+    file: string;
+    projectRoot: string;
+    result: ITtscCompilerTransformation;
+    scratchDirectory?: string;
+    temporaryTsconfig?: string;
+}): string[];

package/lib/core/transform/envelope/selectWatchInputs.d.ts

@@ -0,0 +1,49 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * Derive the absolute, deduplicated watch-input list for a single file.
+ *
+ * By default the derivation unions plugin dependencies, the reachable graph,
+ * globals, configs, importer resolver inputs, and universal resolver inputs.
+ * The plugin-reported list can only widen the host-owned language-semantic
+ * bound, never narrow it. Resolver inputs remain in that bound in both modes.
+ *
+ * An envelope that lists `file` in `dependenciesComplete` narrows it to
+ * `dependencies[file] ∪ configs`: the plugin declared its reported list the
+ * complete input set for that file, which transfers responsibility for the
+ * dropped `reach(edges, file) ∪ globals` bound to the plugin (see the protocol
+ * page's completeness contract). The config chain stays universal regardless,
+ * because compiler options reach generated code through the host rather than
+ * through any file a plugin could consult. A file the plugin also declared
+ * volatile keeps the baseline: the two declarations contradict, so the
+ * conservative one wins.
+ *
+ * The derived list uses the envelope, fixed project/options and the
+ * generation's observed native identity view, keyed by the delivered file's
+ * normalized lexical spelling. Graph traversal uses its filesystem identity,
+ * but lexical inputs exclude only that exact spelling, so two aliases of one
+ * source require distinct lists. Repeated deliveries of one spelling replay the
+ * per-envelope memo ({@link envelopeDerivation}) instead of re-walking the
+ * graph. Returns an empty list on exceptions.
+ *
+ * The returned array is the generation's cached list and must not be mutated.
+ * Project root, scratch exclusions and temporary config options must stay fixed
+ * for the result object's lifetime, since the memo key includes only module
+ * spelling within that generation. The native identity view must remain valid
+ * for that generation; this memo does not independently prove current inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation The final list follows deriveWatchInputs' conservative union and conditional completeness rule; exact lexical module keys keep alias-sensitive exclusions distinct even when graph identity is shared.
+ * @evidence contracts/common.md#clear-and-simple-design This entry point owns final-list memoization and delegates input policy and merging to deriveWatchInputs, sharing state through envelopeDerivation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Completeness cannot remove host-owned resolver inputs, and volatility retains the baseline; exceptions produce no fabricated watch list or guessed substitute dependency.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain baseline and narrowed bounds, contradictory declarations, lexical memo keys and exception results with documentation-skill paragraph and tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native absolute lexical spellings key alias-sensitive lists, while the envelope context supplies physical identity to graph traversal; these domains remain distinct instead of using manual case or separator normalization.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One array and lexical key per requested module spelling is retained in envelope state, alongside shared indexes and native context observations. List members follow selected generation inputs, but distinct requested spellings and their text have no capacity or byte cap. Weak association does not keep the envelope alive; a borrower retaining returned state or arrays can extend storage lifetime. No watcher handle is opened here.
+ * @evidence contracts/performance.md#efficient-algorithms Even a cached list request selects envelope state, queries the delivered path identity and resolves its lexical spelling before the final Map lookup, paying path/key text and any cold native identity observations. A first list additionally derives the dependency/graph/resolver union and deduplication with their visited/selected/index populations; later identical spellings avoid that derivation, not all path work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reuse requires one immutable envelope/root, stable scratch and temporary-config options and a still-valid native identity view. The key is lexical module spelling because different aliases exclude different paths; final lists do not certify current filesystem freshness. Callers must treat the returned cached array as read-only.
+ */
+export declare function selectWatchInputs(props: {
+    file: string;
+    projectRoot: string;
+    result: ITtscCompilerTransformation;
+    scratchDirectory?: string;
+    temporaryTsconfig?: string;
+}): string[];

package/lib/core/transform/envelope/selectWatchInputs.js

@@ -0,0 +1,66 @@
+'use strict';
+
+var path = require('node:path');
+var derivationIdentity = require('./derivationIdentity.js');
+var deriveWatchInputs = require('./deriveWatchInputs.js');
+var envelopeDerivation = require('./envelopeDerivation.js');
+
+/**
+ * Derive the absolute, deduplicated watch-input list for a single file.
+ *
+ * By default the derivation unions plugin dependencies, the reachable graph,
+ * globals, configs, importer resolver inputs, and universal resolver inputs.
+ * The plugin-reported list can only widen the host-owned language-semantic
+ * bound, never narrow it. Resolver inputs remain in that bound in both modes.
+ *
+ * An envelope that lists `file` in `dependenciesComplete` narrows it to
+ * `dependencies[file] ∪ configs`: the plugin declared its reported list the
+ * complete input set for that file, which transfers responsibility for the
+ * dropped `reach(edges, file) ∪ globals` bound to the plugin (see the protocol
+ * page's completeness contract). The config chain stays universal regardless,
+ * because compiler options reach generated code through the host rather than
+ * through any file a plugin could consult. A file the plugin also declared
+ * volatile keeps the baseline: the two declarations contradict, so the
+ * conservative one wins.
+ *
+ * The derived list uses the envelope, fixed project/options and the
+ * generation's observed native identity view, keyed by the delivered file's
+ * normalized lexical spelling. Graph traversal uses its filesystem identity,
+ * but lexical inputs exclude only that exact spelling, so two aliases of one
+ * source require distinct lists. Repeated deliveries of one spelling replay the
+ * per-envelope memo ({@link envelopeDerivation}) instead of re-walking the
+ * graph. Returns an empty list on exceptions.
+ *
+ * The returned array is the generation's cached list and must not be mutated.
+ * Project root, scratch exclusions and temporary config options must stay fixed
+ * for the result object's lifetime, since the memo key includes only module
+ * spelling within that generation. The native identity view must remain valid
+ * for that generation; this memo does not independently prove current inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation The final list follows deriveWatchInputs' conservative union and conditional completeness rule; exact lexical module keys keep alias-sensitive exclusions distinct even when graph identity is shared.
+ * @evidence contracts/common.md#clear-and-simple-design This entry point owns final-list memoization and delegates input policy and merging to deriveWatchInputs, sharing state through envelopeDerivation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Completeness cannot remove host-owned resolver inputs, and volatility retains the baseline; exceptions produce no fabricated watch list or guessed substitute dependency.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain baseline and narrowed bounds, contradictory declarations, lexical memo keys and exception results with documentation-skill paragraph and tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native absolute lexical spellings key alias-sensitive lists, while the envelope context supplies physical identity to graph traversal; these domains remain distinct instead of using manual case or separator normalization.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One array and lexical key per requested module spelling is retained in envelope state, alongside shared indexes and native context observations. List members follow selected generation inputs, but distinct requested spellings and their text have no capacity or byte cap. Weak association does not keep the envelope alive; a borrower retaining returned state or arrays can extend storage lifetime. No watcher handle is opened here.
+ * @evidence contracts/performance.md#efficient-algorithms Even a cached list request selects envelope state, queries the delivered path identity and resolves its lexical spelling before the final Map lookup, paying path/key text and any cold native identity observations. A first list additionally derives the dependency/graph/resolver union and deduplication with their visited/selected/index populations; later identical spellings avoid that derivation, not all path work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reuse requires one immutable envelope/root, stable scratch and temporary-config options and a still-valid native identity view. The key is lexical module spelling because different aliases exclude different paths; final lists do not certify current filesystem freshness. Callers must treat the returned cached array as read-only.
+ */
+function selectWatchInputs(props) {
+    if (props.result.type === "exception") {
+        return [];
+    }
+    const state = envelopeDerivation.envelopeDerivation(props);
+    const fileIdentity = derivationIdentity.derivationIdentity(state, props.file);
+    const fileSpelling = path.resolve(props.file);
+    const memoized = state.watchInputs.get(fileSpelling);
+    if (memoized !== undefined) {
+        return memoized;
+    }
+    const derived = deriveWatchInputs.deriveWatchInputs(state, props, fileIdentity);
+    state.watchInputs.set(fileSpelling, derived);
+    return derived;
+}
+
+exports.selectWatchInputs = selectWatchInputs;
+//# sourceMappingURL=selectWatchInputs.js.map

package/lib/core/transform/envelope/selectWatchInputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectWatchInputs.js","sources":["../../../../src/core/transform/envelope/selectWatchInputs.ts"],"sourcesContent":[null],"names":["envelopeDerivation","derivationIdentity","deriveWatchInputs"],"mappings":";;;;;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCG;AACG,SAAU,iBAAiB,CAAC,KAMjC,EAAA;IACC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE;AACrC,QAAA,OAAO,EAAE;IACX;AACA,IAAA,MAAM,KAAK,GAAGA,qCAAkB,CAAC,KAAK,CAAC;IACvC,MAAM,YAAY,GAAGC,qCAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;IAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC;AACpD,IAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,QAAA,OAAO,QAAQ;IACjB;IACA,MAAM,OAAO,GAAGC,mCAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC;IAC7D,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC;AAC5C,IAAA,OAAO,OAAO;AAChB;;;;"}

package/lib/core/transform/envelope/selectWatchInputs.mjs

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { derivationIdentity } from './derivationIdentity.mjs';
+import { deriveWatchInputs } from './deriveWatchInputs.mjs';
+import { envelopeDerivation } from './envelopeDerivation.mjs';
+
+/**
+ * Derive the absolute, deduplicated watch-input list for a single file.
+ *
+ * By default the derivation unions plugin dependencies, the reachable graph,
+ * globals, configs, importer resolver inputs, and universal resolver inputs.
+ * The plugin-reported list can only widen the host-owned language-semantic
+ * bound, never narrow it. Resolver inputs remain in that bound in both modes.
+ *
+ * An envelope that lists `file` in `dependenciesComplete` narrows it to
+ * `dependencies[file] ∪ configs`: the plugin declared its reported list the
+ * complete input set for that file, which transfers responsibility for the
+ * dropped `reach(edges, file) ∪ globals` bound to the plugin (see the protocol
+ * page's completeness contract). The config chain stays universal regardless,
+ * because compiler options reach generated code through the host rather than
+ * through any file a plugin could consult. A file the plugin also declared
+ * volatile keeps the baseline: the two declarations contradict, so the
+ * conservative one wins.
+ *
+ * The derived list uses the envelope, fixed project/options and the
+ * generation's observed native identity view, keyed by the delivered file's
+ * normalized lexical spelling. Graph traversal uses its filesystem identity,
+ * but lexical inputs exclude only that exact spelling, so two aliases of one
+ * source require distinct lists. Repeated deliveries of one spelling replay the
+ * per-envelope memo ({@link envelopeDerivation}) instead of re-walking the
+ * graph. Returns an empty list on exceptions.
+ *
+ * The returned array is the generation's cached list and must not be mutated.
+ * Project root, scratch exclusions and temporary config options must stay fixed
+ * for the result object's lifetime, since the memo key includes only module
+ * spelling within that generation. The native identity view must remain valid
+ * for that generation; this memo does not independently prove current inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation The final list follows deriveWatchInputs' conservative union and conditional completeness rule; exact lexical module keys keep alias-sensitive exclusions distinct even when graph identity is shared.
+ * @evidence contracts/common.md#clear-and-simple-design This entry point owns final-list memoization and delegates input policy and merging to deriveWatchInputs, sharing state through envelopeDerivation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Completeness cannot remove host-owned resolver inputs, and volatility retains the baseline; exceptions produce no fabricated watch list or guessed substitute dependency.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain baseline and narrowed bounds, contradictory declarations, lexical memo keys and exception results with documentation-skill paragraph and tag separation.
+ * @evidence contracts/portability.md#os-neutral-implementation Native absolute lexical spellings key alias-sensitive lists, while the envelope context supplies physical identity to graph traversal; these domains remain distinct instead of using manual case or separator normalization.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One array and lexical key per requested module spelling is retained in envelope state, alongside shared indexes and native context observations. List members follow selected generation inputs, but distinct requested spellings and their text have no capacity or byte cap. Weak association does not keep the envelope alive; a borrower retaining returned state or arrays can extend storage lifetime. No watcher handle is opened here.
+ * @evidence contracts/performance.md#efficient-algorithms Even a cached list request selects envelope state, queries the delivered path identity and resolves its lexical spelling before the final Map lookup, paying path/key text and any cold native identity observations. A first list additionally derives the dependency/graph/resolver union and deduplication with their visited/selected/index populations; later identical spellings avoid that derivation, not all path work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reuse requires one immutable envelope/root, stable scratch and temporary-config options and a still-valid native identity view. The key is lexical module spelling because different aliases exclude different paths; final lists do not certify current filesystem freshness. Callers must treat the returned cached array as read-only.
+ */
+function selectWatchInputs(props) {
+    if (props.result.type === "exception") {
+        return [];
+    }
+    const state = envelopeDerivation(props);
+    const fileIdentity = derivationIdentity(state, props.file);
+    const fileSpelling = path.resolve(props.file);
+    const memoized = state.watchInputs.get(fileSpelling);
+    if (memoized !== undefined) {
+        return memoized;
+    }
+    const derived = deriveWatchInputs(state, props, fileIdentity);
+    state.watchInputs.set(fileSpelling, derived);
+    return derived;
+}
+
+export { selectWatchInputs };
+//# sourceMappingURL=selectWatchInputs.mjs.map

package/lib/core/transform/envelope/selectWatchInputs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectWatchInputs.mjs","sources":["../../../../src/core/transform/envelope/selectWatchInputs.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCG;AACG,SAAU,iBAAiB,CAAC,KAMjC,EAAA;IACC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE;AACrC,QAAA,OAAO,EAAE;IACX;AACA,IAAA,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC;IACvC,MAAM,YAAY,GAAG,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;IAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC;AACpD,IAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,QAAA,OAAO,QAAQ;IACjB;IACA,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC;IAC7D,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC;AAC5C,IAAA,OAAO,OAAO;AAChB;;;;"}

package/lib/core/transform/errors/TtscCompileFailureError.d.cts

@@ -0,0 +1,36 @@
+/**
+ * A compile that ended in diagnostics, or in an exception the compiler reported
+ * during the project attempt. Hosts distinguish this compiler-reported failure
+ * from errors in adapter setup or snapshot acquisition.
+ *
+ * It is told apart from every other way a delivery can fail, an adapter error
+ * before any compile, a generation the adapter could not capture while its
+ * inputs kept changing, because a host may keep this verdict as the module's
+ * output until its inputs change, the way it keeps a transformed module, while
+ * it must not keep those: they say nothing about the state, and only running
+ * the module again can answer. A development session under Turbopack delivers
+ * this verdict as a module that throws it, and fails the loader run for the
+ * others.
+ *
+ * The message retains the compiler's rendered diagnostics or exception. The
+ * type does not assert that arbitrary plugin exceptions are deterministic;
+ * retry and retention authority belong to the host's declared pass lifecycle.
+ *
+ * @evidence contracts/common.md#principled-implementation A distinct Error subclass represents the compiler-reported verdict, allowing delivery code to distinguish its origin from adapter or snapshot acquisition failure without inspecting text or asserting deterministic exception behavior.
+ * @evidence contracts/common.md#clear-and-simple-design The class adds only typed identity; the compiler message and Error behavior stay native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No message fragment, fixture name or fabricated successful module determines the failure category.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain which failures this type represents and why hosts may retain this verdict differently from setup failures.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   An error class that carries a message and fields only; it touches no
+ *   filesystem, path or process.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The constructor assigns its fields; constant work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Computes nothing that could be reused.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Adds no independent cache, handle or running task; the supplied message
+ *   and native Error data follow the caller-owned error object's lifetime.
+ */
+export declare class TtscCompileFailureError extends Error {
+    constructor(message: string);
+}

package/lib/core/transform/errors/TtscCompileFailureError.d.mts

@@ -0,0 +1,36 @@
+/**
+ * A compile that ended in diagnostics, or in an exception the compiler reported
+ * during the project attempt. Hosts distinguish this compiler-reported failure
+ * from errors in adapter setup or snapshot acquisition.
+ *
+ * It is told apart from every other way a delivery can fail, an adapter error
+ * before any compile, a generation the adapter could not capture while its
+ * inputs kept changing, because a host may keep this verdict as the module's
+ * output until its inputs change, the way it keeps a transformed module, while
+ * it must not keep those: they say nothing about the state, and only running
+ * the module again can answer. A development session under Turbopack delivers
+ * this verdict as a module that throws it, and fails the loader run for the
+ * others.
+ *
+ * The message retains the compiler's rendered diagnostics or exception. The
+ * type does not assert that arbitrary plugin exceptions are deterministic;
+ * retry and retention authority belong to the host's declared pass lifecycle.
+ *
+ * @evidence contracts/common.md#principled-implementation A distinct Error subclass represents the compiler-reported verdict, allowing delivery code to distinguish its origin from adapter or snapshot acquisition failure without inspecting text or asserting deterministic exception behavior.
+ * @evidence contracts/common.md#clear-and-simple-design The class adds only typed identity; the compiler message and Error behavior stay native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No message fragment, fixture name or fabricated successful module determines the failure category.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain which failures this type represents and why hosts may retain this verdict differently from setup failures.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   An error class that carries a message and fields only; it touches no
+ *   filesystem, path or process.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The constructor assigns its fields; constant work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Computes nothing that could be reused.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Adds no independent cache, handle or running task; the supplied message
+ *   and native Error data follow the caller-owned error object's lifetime.
+ */
+export declare class TtscCompileFailureError extends Error {
+    constructor(message: string);
+}

package/lib/core/transform/errors/TtscCompileFailureError.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A compile that ended in diagnostics, or in an exception the compiler reported
+ * during the project attempt. Hosts distinguish this compiler-reported failure
+ * from errors in adapter setup or snapshot acquisition.
+ *
+ * It is told apart from every other way a delivery can fail, an adapter error
+ * before any compile, a generation the adapter could not capture while its
+ * inputs kept changing, because a host may keep this verdict as the module's
+ * output until its inputs change, the way it keeps a transformed module, while
+ * it must not keep those: they say nothing about the state, and only running
+ * the module again can answer. A development session under Turbopack delivers
+ * this verdict as a module that throws it, and fails the loader run for the
+ * others.
+ *
+ * The message retains the compiler's rendered diagnostics or exception. The
+ * type does not assert that arbitrary plugin exceptions are deterministic;
+ * retry and retention authority belong to the host's declared pass lifecycle.
+ *
+ * @evidence contracts/common.md#principled-implementation A distinct Error subclass represents the compiler-reported verdict, allowing delivery code to distinguish its origin from adapter or snapshot acquisition failure without inspecting text or asserting deterministic exception behavior.
+ * @evidence contracts/common.md#clear-and-simple-design The class adds only typed identity; the compiler message and Error behavior stay native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No message fragment, fixture name or fabricated successful module determines the failure category.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain which failures this type represents and why hosts may retain this verdict differently from setup failures.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   An error class that carries a message and fields only; it touches no
+ *   filesystem, path or process.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The constructor assigns its fields; constant work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Computes nothing that could be reused.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Adds no independent cache, handle or running task; the supplied message
+ *   and native Error data follow the caller-owned error object's lifetime.
+ */
+export declare class TtscCompileFailureError extends Error {
+    constructor(message: string);
+}

package/lib/core/transform/errors/TtscCompileFailureError.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * A compile that ended in diagnostics, or in an exception the compiler reported
+ * during the project attempt. Hosts distinguish this compiler-reported failure
+ * from errors in adapter setup or snapshot acquisition.
+ *
+ * It is told apart from every other way a delivery can fail, an adapter error
+ * before any compile, a generation the adapter could not capture while its
+ * inputs kept changing, because a host may keep this verdict as the module's
+ * output until its inputs change, the way it keeps a transformed module, while
+ * it must not keep those: they say nothing about the state, and only running
+ * the module again can answer. A development session under Turbopack delivers
+ * this verdict as a module that throws it, and fails the loader run for the
+ * others.
+ *
+ * The message retains the compiler's rendered diagnostics or exception. The
+ * type does not assert that arbitrary plugin exceptions are deterministic;
+ * retry and retention authority belong to the host's declared pass lifecycle.
+ *
+ * @evidence contracts/common.md#principled-implementation A distinct Error subclass represents the compiler-reported verdict, allowing delivery code to distinguish its origin from adapter or snapshot acquisition failure without inspecting text or asserting deterministic exception behavior.
+ * @evidence contracts/common.md#clear-and-simple-design The class adds only typed identity; the compiler message and Error behavior stay native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No message fragment, fixture name or fabricated successful module determines the failure category.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain which failures this type represents and why hosts may retain this verdict differently from setup failures.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   An error class that carries a message and fields only; it touches no
+ *   filesystem, path or process.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The constructor assigns its fields; constant work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Computes nothing that could be reused.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Adds no independent cache, handle or running task; the supplied message
+ *   and native Error data follow the caller-owned error object's lifetime.
+ */
+class TtscCompileFailureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TtscCompileFailureError";
+    }
+}
+
+exports.TtscCompileFailureError = TtscCompileFailureError;
+//# sourceMappingURL=TtscCompileFailureError.js.map

package/lib/core/transform/errors/TtscCompileFailureError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscCompileFailureError.js","sources":["../../../../src/core/transform/errors/TtscCompileFailureError.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;AACG,MAAO,uBAAwB,SAAQ,KAAK,CAAA;AAChD,IAAA,WAAA,CAAmB,OAAe,EAAA;QAChC,KAAK,CAAC,OAAO,CAAC;AACd,QAAA,IAAI,CAAC,IAAI,GAAG,yBAAyB;IACvC;AACD;;;;"}

package/lib/core/transform/errors/TtscCompileFailureError.mjs

@@ -0,0 +1,42 @@
+/**
+ * A compile that ended in diagnostics, or in an exception the compiler reported
+ * during the project attempt. Hosts distinguish this compiler-reported failure
+ * from errors in adapter setup or snapshot acquisition.
+ *
+ * It is told apart from every other way a delivery can fail, an adapter error
+ * before any compile, a generation the adapter could not capture while its
+ * inputs kept changing, because a host may keep this verdict as the module's
+ * output until its inputs change, the way it keeps a transformed module, while
+ * it must not keep those: they say nothing about the state, and only running
+ * the module again can answer. A development session under Turbopack delivers
+ * this verdict as a module that throws it, and fails the loader run for the
+ * others.
+ *
+ * The message retains the compiler's rendered diagnostics or exception. The
+ * type does not assert that arbitrary plugin exceptions are deterministic;
+ * retry and retention authority belong to the host's declared pass lifecycle.
+ *
+ * @evidence contracts/common.md#principled-implementation A distinct Error subclass represents the compiler-reported verdict, allowing delivery code to distinguish its origin from adapter or snapshot acquisition failure without inspecting text or asserting deterministic exception behavior.
+ * @evidence contracts/common.md#clear-and-simple-design The class adds only typed identity; the compiler message and Error behavior stay native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No message fragment, fixture name or fabricated successful module determines the failure category.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain which failures this type represents and why hosts may retain this verdict differently from setup failures.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   An error class that carries a message and fields only; it touches no
+ *   filesystem, path or process.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The constructor assigns its fields; constant work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Computes nothing that could be reused.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Adds no independent cache, handle or running task; the supplied message
+ *   and native Error data follow the caller-owned error object's lifetime.
+ */
+class TtscCompileFailureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TtscCompileFailureError";
+    }
+}
+
+export { TtscCompileFailureError };
+//# sourceMappingURL=TtscCompileFailureError.mjs.map

package/lib/core/transform/errors/TtscCompileFailureError.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscCompileFailureError.mjs","sources":["../../../../src/core/transform/errors/TtscCompileFailureError.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;AACG,MAAO,uBAAwB,SAAQ,KAAK,CAAA;AAChD,IAAA,WAAA,CAAmB,OAAe,EAAA;QAChC,KAAK,CAAC,OAAO,CAAC;AACd,QAAA,IAAI,CAAC,IAAI,GAAG,yBAAyB;IACvC;AACD;;;;"}