@ttsc/unplugin 0.30.4 → 0.31.0

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

@@ -0,0 +1,180 @@
+import path from 'node:path';
+import { createHostPathIdentityContext } from '../filesystem/createHostPathIdentityContext.mjs';
+import { pathIdentityKey } from '../filesystem/pathIdentityKey.mjs';
+import { relativeToProject } from '../filesystem/relativeToProject.mjs';
+import { isTransformScratchInput } from '../tsconfig/isTransformScratchInput.mjs';
+import { envelopeDerivation } from './envelopeDerivation.mjs';
+import { envelopeGraphIndexes } from './envelopeGraphIndexes.mjs';
+
+/**
+ * The generation's resolution candidates recorded as not files, so its
+ * host-input watcher can be told to announce a later file-availability change.
+ *
+ * A failed file predicate supplies no readable-file byte signature. A retained
+ * candidate tracker can qualify the narrower unavailable-file comparison only
+ * while its native coverage and notification authority remain valid; selection
+ * alone does not acquire that permission. Universal absence validation retains
+ * its own native candidate probes.
+ *
+ * Compiler fileExists:false can describe either an absent path or a directory.
+ * Without a predicate observation, the fallback requires the host existence
+ * probe to fail. The returned candidates are the names whose probes may be
+ * replaced; watched also includes their project-local ancestor components so
+ * link retargeting cannot leave observers attached only to the old target.
+ *
+ * A chain that does not reach a captured project root before the
+ * filesystem-root stopping condition retains direct probing. More than 512
+ * distinct lexical parent locations rejects the whole selection after
+ * collection; this limits admitted directory locations, not candidate count,
+ * temporary memory or scan work. The tracker owns actual watcher acquisition,
+ * notifications and release.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact failed file predicates select unavailable resolver names, while the lexical ancestor chain witnesses component creation and retargeting; selections outside the root retain direct probes because their chain cannot be covered by project-local watchers.
+ * @evidence contracts/common.md#clear-and-simple-design Separate candidate and ancestor sets expose probe-replacement names versus required watcher paths; resource acquisition remains with the tracker instead of occurring during envelope selection.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The 512-location bound rejects the entire selection so direct validation remains active; it does not return an incomplete watch claim or special-case known candidate names to fit a measurement.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish not-file from missing, candidate versus watched lists, root coverage, the population bound and tracker ownership; acknowledgments are separate under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native dirname/resolve and lexical containment against captured named/physical roots derive ancestor spellings on the host. Path grammar containment is not a certificate of filesystem case or notification coverage; the tracker owns that native admission. Physical identity excludes the temporary input without collapsing alias watcher names, and supplied/result-derived views must remain coherent.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Cold graph construction and the materialized candidate-list array precede
+ *   a scan of every candidate occurrence. Path/predicate checks precede seen
+ *   rejection; each admitted candidate constructs its parent chain again before
+ *   chain deduplication limits appended components. Cost includes path/root
+ *   text, chain depth, cold native identity/existence work and two final string
+ *   sorts. Candidate, component and directory populations allocate storage
+ *   before the 512-directory rejection, so that limit does not bound scan cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Seen suppresses repeated candidate admission after predicate/path work;
+ *   chain suppresses repeated component output after constructing the chain.
+ *   Shared generation parsing and this call's identity context reuse qualified
+ *   observations under coherent supplied/result native views. No completed
+ *   selection is memoized here across calls.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Temporary collections retain no call history or native handles. Returned
+ *   candidate/watched arrays transfer to the caller; directory admission caps
+ *   neither candidate-name count nor bytes, and the tracker separately owns
+ *   actual subscriptions and release.
+ */
+function selectNotifiableAbsentInputs(props) {
+    const empty = { candidates: [], watched: [] };
+    if (props.result.type === "exception") {
+        return empty;
+    }
+    const graph = props.result.graph;
+    if (graph === undefined) {
+        return empty;
+    }
+    const identities = createHostPathIdentityContext(props.filesystem);
+    const graphState = envelopeDerivation({
+        projectRoot: props.projectRoot,
+        result: props.result,
+    });
+    const graphIndexes = envelopeGraphIndexes(graphState, {
+        projectRoot: props.projectRoot,
+        result: props.result,
+    });
+    const excluded = props.temporaryTsconfig === undefined
+        ? undefined
+        : pathIdentityKey(props.temporaryTsconfig, identities);
+    const output = [];
+    const watched = [];
+    const directories = new Set();
+    // Two namespaces, deliberately not one set: candidates are the paths a
+    // delivery may stop probing, while the chain holds the directories that carry
+    // them. Sharing a set would let one silently answer for the other.
+    const seen = new Set();
+    const chain = new Set();
+    for (const candidates of [
+        ...Object.values(graph.candidates ?? {}),
+        graph.resolutionInputs ?? [],
+    ]) {
+        if (!Array.isArray(candidates)) {
+            continue;
+        }
+        for (const candidate of candidates) {
+            if (typeof candidate !== "string" || candidate.length === 0) {
+                continue;
+            }
+            const absolute = path.resolve(props.projectRoot, candidate);
+            const spelling = path.resolve(absolute);
+            const observation = graphIndexes.inputObservations.get(spelling);
+            const absentAsFile = observation?.fileExists === false ||
+                (observation === undefined && !props.filesystem.exists(absolute));
+            if (seen.has(spelling) ||
+                isTransformScratchInput(absolute, props.scratchDirectory) ||
+                (excluded !== undefined &&
+                    pathIdentityKey(absolute, identities) === excluded) ||
+                !absentAsFile) {
+                continue;
+            }
+            seen.add(spelling);
+            // Collect the components of the lexical path, by the name each carries in
+            // its own parent. The watcher a missing path opens follows the spelling
+            // to a physical directory, so retargeting a link along the way moves the
+            // answer without touching what is watched: in a pnpm layout
+            // `node_modules/<pkg>` is exactly such a link, and reinstalling it makes
+            // a candidate appear behind a watch still looking at the old store
+            // directory. Watching `<pkg>` inside `node_modules` is what reports that.
+            //
+            // The collection stops at the project root, and a spelling that leaves
+            // the project subtree before reaching it is not claimed at all. Above
+            // that line the components are the machine's own layout rather than the
+            // project's, and watching those entries costs a generation whenever an
+            // unrelated process touches anything inside them; a candidate whose path
+            // runs outside the subtree therefore keeps the probe it always had rather
+            // than a proof this cannot complete.
+            const components = [];
+            let reachedProject = false;
+            for (let child = path.dirname(spelling), parent = path.dirname(child); parent !== child; child = parent, parent = path.dirname(child)) {
+                const below = relativeToProject(child, graphState.project);
+                if (below !== undefined && below !== "") {
+                    components.push(child);
+                    continue;
+                }
+                // Native lexical path grammar compares both captured root spellings.
+                // Its root match selects an ancestor chain, not an independent proof
+                // of filesystem case equivalence or healthy notification coverage.
+                reachedProject = below === "";
+                break;
+            }
+            if (!reachedProject) {
+                continue;
+            }
+            output.push(absolute);
+            watched.push(absolute);
+            for (const component of components) {
+                if (chain.has(component))
+                    break;
+                chain.add(component);
+                watched.push(component);
+                directories.add(path.dirname(component));
+            }
+            directories.add(path.dirname(spelling));
+        }
+    }
+    if (directories.size > NOTIFIABLE_ABSENCE_DIRECTORY_LIMIT) {
+        // Decline the whole candidate selection past the lexical directory policy
+        // limit. Returning partial names would claim only part of the intended
+        // chain; an empty selection leaves direct candidate validation active.
+        return empty;
+    }
+    output.sort();
+    watched.sort();
+    return { candidates: output, watched };
+}
+/**
+ * Distinct directories the absent-candidate watch may open before it declines.
+ *
+ * This admission policy declines a larger lexical directory population instead
+ * of claiming partial candidate coverage. It does not reserve descriptors or
+ * certify the native backend's available capacity.
+ *
+ * Counted lexically, over the parents of every watched name. A missing subtree
+ * collapses onto the one watch its nearest existing ancestor carries, so the
+ * count describes requested lexical parent locations, not an exact handle
+ * count. Native resolution, coverage and acquisition failures remain tracker
+ * responsibilities.
+ */
+const NOTIFIABLE_ABSENCE_DIRECTORY_LIMIT = 512;
+
+export { selectNotifiableAbsentInputs };
+//# sourceMappingURL=selectNotifiableAbsentInputs.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectNotifiableAbsentInputs.mjs","sources":["../../../../src/core/transform/envelope/selectNotifiableAbsentInputs.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

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

@@ -0,0 +1,24 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * The plugin source directories of a generation, each with the state the
+ * envelope reported for it, by absolute spelling (samchon/ttsc#1487).
+ *
+ * A plugin's binary is keyed on its Go source and the environment a build there
+ * runs in, so the generation's output is a function of these directories as
+ * much as of its host inputs: they are universal inputs of every module, proven
+ * by state (`pluginSourceHolds`, samchon/ttsc#1493) and observed as whole
+ * subtrees. A malformed entry is left out, since a state that is not a string
+ * proves nothing. Read once per envelope, since every watch input of every
+ * module asks it.
+ *
+ * @param result The generation's envelope.
+ * @evidence contracts/common.md#principled-implementation Each valid producer directory/digest pair records a universal plugin-build input; exceptions and malformed entries contribute no proven state rather than implying an empty subtree is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One weakly memoized map exposes absolute directory spellings and their reported states; subtree observation and digest validation remain with the consuming cache/watch owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Digest values come from the actual envelope and are not recomputed later to retroactively certify the compile; non-string values cannot masquerade as a source-state proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why plugin source trees are universal inputs, what malformed entries mean and generation memoization, with parameter and tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve supplies absolute source-directory spellings; no OS-specific directory names, separator rewriting or case assumptions are introduced by the map adapter.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap ownership releases the map with its result object; entries grow only with valid producer directories and this adapter does not acquire subtree observers or retain older generations.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over pluginSources builds the map once per result, and repeated module queries use the WeakMap instead of rescanning source directories.
+ * @evidence contracts/performance.md#reuse-equivalent-work The immutable result object identifies equivalent source-state requests; fresh generation objects build fresh maps, and consumers must not mutate the returned read-only map.
+ */
+export declare function selectPluginSourceInputs(result: ITtscCompilerTransformation): ReadonlyMap<string, string>;

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

@@ -0,0 +1,24 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * The plugin source directories of a generation, each with the state the
+ * envelope reported for it, by absolute spelling (samchon/ttsc#1487).
+ *
+ * A plugin's binary is keyed on its Go source and the environment a build there
+ * runs in, so the generation's output is a function of these directories as
+ * much as of its host inputs: they are universal inputs of every module, proven
+ * by state (`pluginSourceHolds`, samchon/ttsc#1493) and observed as whole
+ * subtrees. A malformed entry is left out, since a state that is not a string
+ * proves nothing. Read once per envelope, since every watch input of every
+ * module asks it.
+ *
+ * @param result The generation's envelope.
+ * @evidence contracts/common.md#principled-implementation Each valid producer directory/digest pair records a universal plugin-build input; exceptions and malformed entries contribute no proven state rather than implying an empty subtree is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One weakly memoized map exposes absolute directory spellings and their reported states; subtree observation and digest validation remain with the consuming cache/watch owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Digest values come from the actual envelope and are not recomputed later to retroactively certify the compile; non-string values cannot masquerade as a source-state proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why plugin source trees are universal inputs, what malformed entries mean and generation memoization, with parameter and tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve supplies absolute source-directory spellings; no OS-specific directory names, separator rewriting or case assumptions are introduced by the map adapter.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap ownership releases the map with its result object; entries grow only with valid producer directories and this adapter does not acquire subtree observers or retain older generations.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over pluginSources builds the map once per result, and repeated module queries use the WeakMap instead of rescanning source directories.
+ * @evidence contracts/performance.md#reuse-equivalent-work The immutable result object identifies equivalent source-state requests; fresh generation objects build fresh maps, and consumers must not mutate the returned read-only map.
+ */
+export declare function selectPluginSourceInputs(result: ITtscCompilerTransformation): ReadonlyMap<string, string>;

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

@@ -0,0 +1,24 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * The plugin source directories of a generation, each with the state the
+ * envelope reported for it, by absolute spelling (samchon/ttsc#1487).
+ *
+ * A plugin's binary is keyed on its Go source and the environment a build there
+ * runs in, so the generation's output is a function of these directories as
+ * much as of its host inputs: they are universal inputs of every module, proven
+ * by state (`pluginSourceHolds`, samchon/ttsc#1493) and observed as whole
+ * subtrees. A malformed entry is left out, since a state that is not a string
+ * proves nothing. Read once per envelope, since every watch input of every
+ * module asks it.
+ *
+ * @param result The generation's envelope.
+ * @evidence contracts/common.md#principled-implementation Each valid producer directory/digest pair records a universal plugin-build input; exceptions and malformed entries contribute no proven state rather than implying an empty subtree is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One weakly memoized map exposes absolute directory spellings and their reported states; subtree observation and digest validation remain with the consuming cache/watch owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Digest values come from the actual envelope and are not recomputed later to retroactively certify the compile; non-string values cannot masquerade as a source-state proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why plugin source trees are universal inputs, what malformed entries mean and generation memoization, with parameter and tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve supplies absolute source-directory spellings; no OS-specific directory names, separator rewriting or case assumptions are introduced by the map adapter.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap ownership releases the map with its result object; entries grow only with valid producer directories and this adapter does not acquire subtree observers or retain older generations.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over pluginSources builds the map once per result, and repeated module queries use the WeakMap instead of rescanning source directories.
+ * @evidence contracts/performance.md#reuse-equivalent-work The immutable result object identifies equivalent source-state requests; fresh generation objects build fresh maps, and consumers must not mutate the returned read-only map.
+ */
+export declare function selectPluginSourceInputs(result: ITtscCompilerTransformation): ReadonlyMap<string, string>;

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

@@ -0,0 +1,46 @@
+'use strict';
+
+var path = require('node:path');
+
+/**
+ * The plugin source directories of a generation, each with the state the
+ * envelope reported for it, by absolute spelling (samchon/ttsc#1487).
+ *
+ * A plugin's binary is keyed on its Go source and the environment a build there
+ * runs in, so the generation's output is a function of these directories as
+ * much as of its host inputs: they are universal inputs of every module, proven
+ * by state (`pluginSourceHolds`, samchon/ttsc#1493) and observed as whole
+ * subtrees. A malformed entry is left out, since a state that is not a string
+ * proves nothing. Read once per envelope, since every watch input of every
+ * module asks it.
+ *
+ * @param result The generation's envelope.
+ * @evidence contracts/common.md#principled-implementation Each valid producer directory/digest pair records a universal plugin-build input; exceptions and malformed entries contribute no proven state rather than implying an empty subtree is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One weakly memoized map exposes absolute directory spellings and their reported states; subtree observation and digest validation remain with the consuming cache/watch owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Digest values come from the actual envelope and are not recomputed later to retroactively certify the compile; non-string values cannot masquerade as a source-state proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why plugin source trees are universal inputs, what malformed entries mean and generation memoization, with parameter and tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve supplies absolute source-directory spellings; no OS-specific directory names, separator rewriting or case assumptions are introduced by the map adapter.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap ownership releases the map with its result object; entries grow only with valid producer directories and this adapter does not acquire subtree observers or retain older generations.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over pluginSources builds the map once per result, and repeated module queries use the WeakMap instead of rescanning source directories.
+ * @evidence contracts/performance.md#reuse-equivalent-work The immutable result object identifies equivalent source-state requests; fresh generation objects build fresh maps, and consumers must not mutate the returned read-only map.
+ */
+function selectPluginSourceInputs(result) {
+    const memo = PLUGIN_SOURCE_INPUTS.get(result);
+    if (memo !== undefined)
+        return memo;
+    const inputs = new Map();
+    PLUGIN_SOURCE_INPUTS.set(result, inputs);
+    if (result.type === "exception")
+        return inputs;
+    for (const [directory, digest] of Object.entries(result.pluginSources ?? {})) {
+        if (typeof digest !== "string" || directory.length === 0)
+            continue;
+        inputs.set(path.resolve(directory), digest);
+    }
+    return inputs;
+}
+/** The plugin source directories of each envelope, read once. */
+const PLUGIN_SOURCE_INPUTS = new WeakMap();
+
+exports.selectPluginSourceInputs = selectPluginSourceInputs;
+//# sourceMappingURL=selectPluginSourceInputs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectPluginSourceInputs.js","sources":["../../../../src/core/transform/envelope/selectPluginSourceInputs.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAGA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,SAAU,wBAAwB,CACtC,MAAmC,EAAA;IAEnC,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC;IAC7C,IAAI,IAAI,KAAK,SAAS;AAAE,QAAA,OAAO,IAAI;AACnC,IAAA,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB;AACxC,IAAA,oBAAoB,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;AACxC,IAAA,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW;AAAE,QAAA,OAAO,MAAM;AAC9C,IAAA,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAC9C,MAAM,CAAC,aAAa,IAAI,EAAE,CAC3B,EAAE;QACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE;AAC1D,QAAA,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC7C;AACA,IAAA,OAAO,MAAM;AACf;AAEA;AACA,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAGrC;;;;"}

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

@@ -0,0 +1,44 @@
+import path from 'node:path';
+
+/**
+ * The plugin source directories of a generation, each with the state the
+ * envelope reported for it, by absolute spelling (samchon/ttsc#1487).
+ *
+ * A plugin's binary is keyed on its Go source and the environment a build there
+ * runs in, so the generation's output is a function of these directories as
+ * much as of its host inputs: they are universal inputs of every module, proven
+ * by state (`pluginSourceHolds`, samchon/ttsc#1493) and observed as whole
+ * subtrees. A malformed entry is left out, since a state that is not a string
+ * proves nothing. Read once per envelope, since every watch input of every
+ * module asks it.
+ *
+ * @param result The generation's envelope.
+ * @evidence contracts/common.md#principled-implementation Each valid producer directory/digest pair records a universal plugin-build input; exceptions and malformed entries contribute no proven state rather than implying an empty subtree is unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design One weakly memoized map exposes absolute directory spellings and their reported states; subtree observation and digest validation remain with the consuming cache/watch owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Digest values come from the actual envelope and are not recomputed later to retroactively certify the compile; non-string values cannot masquerade as a source-state proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why plugin source trees are universal inputs, what malformed entries mean and generation memoization, with parameter and tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve supplies absolute source-directory spellings; no OS-specific directory names, separator rewriting or case assumptions are introduced by the map adapter.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap ownership releases the map with its result object; entries grow only with valid producer directories and this adapter does not acquire subtree observers or retain older generations.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over pluginSources builds the map once per result, and repeated module queries use the WeakMap instead of rescanning source directories.
+ * @evidence contracts/performance.md#reuse-equivalent-work The immutable result object identifies equivalent source-state requests; fresh generation objects build fresh maps, and consumers must not mutate the returned read-only map.
+ */
+function selectPluginSourceInputs(result) {
+    const memo = PLUGIN_SOURCE_INPUTS.get(result);
+    if (memo !== undefined)
+        return memo;
+    const inputs = new Map();
+    PLUGIN_SOURCE_INPUTS.set(result, inputs);
+    if (result.type === "exception")
+        return inputs;
+    for (const [directory, digest] of Object.entries(result.pluginSources ?? {})) {
+        if (typeof digest !== "string" || directory.length === 0)
+            continue;
+        inputs.set(path.resolve(directory), digest);
+    }
+    return inputs;
+}
+/** The plugin source directories of each envelope, read once. */
+const PLUGIN_SOURCE_INPUTS = new WeakMap();
+
+export { selectPluginSourceInputs };
+//# sourceMappingURL=selectPluginSourceInputs.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectPluginSourceInputs.mjs","sources":["../../../../src/core/transform/envelope/selectPluginSourceInputs.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,SAAU,wBAAwB,CACtC,MAAmC,EAAA;IAEnC,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC;IAC7C,IAAI,IAAI,KAAK,SAAS;AAAE,QAAA,OAAO,IAAI;AACnC,IAAA,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB;AACxC,IAAA,oBAAoB,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;AACxC,IAAA,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW;AAAE,QAAA,OAAO,MAAM;AAC9C,IAAA,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAC9C,MAAM,CAAC,aAAa,IAAI,EAAE,CAC3B,EAAE;QACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE;AAC1D,QAAA,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC7C;AACA,IAAA,OAAO,MAAM;AACf;AAEA;AACA,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAGrC;;;;"}

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

@@ -0,0 +1,22 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.cjs";
+import type { TtscEnvelopeGraphIndexes } from "./TtscEnvelopeGraphIndexes.cjs";
+/**
+ * Walk the reachability closure of the graph's direct `edges` from `file`,
+ * returning the absolute path of every file reached (the starting file itself
+ * excluded, even when a cycle points back at it). Reads the shared per-envelope
+ * edge index instead of rebuilding it per delivery.
+ *
+ * Traversal coalesces physical vertices using the supplied generation context;
+ * the first reached target spelling is retained. The starting identity is
+ * marked before traversal, so cycles never reintroduce it into the output.
+ *
+ * @evidence contracts/common.md#principled-implementation A depth-first worklist and identity visited set enumerate each reachable vertex once; premarking the start removes it even when a cycle returns to the same file through an alias.
+ * @evidence contracts/common.md#clear-and-simple-design One local stack, visited set and output array expose closure traversal over the already-built adjacency map; graph parsing and identity semantics remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cycle prevention follows visited identity rather than a depth cap, retry chain or special source name; target spellings are taken from actual graph edges.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state starting-file exclusion, shared indexing, physical vertex equivalence and first-target spelling, with acknowledgment separation under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Every queried source or target spelling passes through the generation's native identity context. Cold spellings can require realpath, ancestor and actual case observations; this traversal does not replace that boundary with lexical equality or an OS-name case rule. The supplied absolute spellings and context must describe the same stable generation view.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The traversal retains no history or handles; its returned array is caller-owned and its stack and visited set are local to one invocation.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached identity is popped once and each reached adjacency entry scanned once, giving V + E structural operations. Identity and Map/Set queries also pay spelling/key text hashing or comparison, and cold spellings add native path/ancestor/case observations. Stack, visited identities and output grow with reached vertices and retained text; duplicate edge spellings still require identity queries.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This closure operation owns no cross-request cache; selectWatchInputs owns final per-spelling reuse and envelopeGraphIndexes owns shared adjacency reuse.
+ */
+export declare function selectReachableEdges(graph: TtscEnvelopeGraphIndexes, state: TtscEnvelopeDerivation, file: string): string[];

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

@@ -0,0 +1,22 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.mjs";
+import type { TtscEnvelopeGraphIndexes } from "./TtscEnvelopeGraphIndexes.mjs";
+/**
+ * Walk the reachability closure of the graph's direct `edges` from `file`,
+ * returning the absolute path of every file reached (the starting file itself
+ * excluded, even when a cycle points back at it). Reads the shared per-envelope
+ * edge index instead of rebuilding it per delivery.
+ *
+ * Traversal coalesces physical vertices using the supplied generation context;
+ * the first reached target spelling is retained. The starting identity is
+ * marked before traversal, so cycles never reintroduce it into the output.
+ *
+ * @evidence contracts/common.md#principled-implementation A depth-first worklist and identity visited set enumerate each reachable vertex once; premarking the start removes it even when a cycle returns to the same file through an alias.
+ * @evidence contracts/common.md#clear-and-simple-design One local stack, visited set and output array expose closure traversal over the already-built adjacency map; graph parsing and identity semantics remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cycle prevention follows visited identity rather than a depth cap, retry chain or special source name; target spellings are taken from actual graph edges.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state starting-file exclusion, shared indexing, physical vertex equivalence and first-target spelling, with acknowledgment separation under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Every queried source or target spelling passes through the generation's native identity context. Cold spellings can require realpath, ancestor and actual case observations; this traversal does not replace that boundary with lexical equality or an OS-name case rule. The supplied absolute spellings and context must describe the same stable generation view.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The traversal retains no history or handles; its returned array is caller-owned and its stack and visited set are local to one invocation.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached identity is popped once and each reached adjacency entry scanned once, giving V + E structural operations. Identity and Map/Set queries also pay spelling/key text hashing or comparison, and cold spellings add native path/ancestor/case observations. Stack, visited identities and output grow with reached vertices and retained text; duplicate edge spellings still require identity queries.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This closure operation owns no cross-request cache; selectWatchInputs owns final per-spelling reuse and envelopeGraphIndexes owns shared adjacency reuse.
+ */
+export declare function selectReachableEdges(graph: TtscEnvelopeGraphIndexes, state: TtscEnvelopeDerivation, file: string): string[];

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

@@ -0,0 +1,22 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation";
+import type { TtscEnvelopeGraphIndexes } from "./TtscEnvelopeGraphIndexes";
+/**
+ * Walk the reachability closure of the graph's direct `edges` from `file`,
+ * returning the absolute path of every file reached (the starting file itself
+ * excluded, even when a cycle points back at it). Reads the shared per-envelope
+ * edge index instead of rebuilding it per delivery.
+ *
+ * Traversal coalesces physical vertices using the supplied generation context;
+ * the first reached target spelling is retained. The starting identity is
+ * marked before traversal, so cycles never reintroduce it into the output.
+ *
+ * @evidence contracts/common.md#principled-implementation A depth-first worklist and identity visited set enumerate each reachable vertex once; premarking the start removes it even when a cycle returns to the same file through an alias.
+ * @evidence contracts/common.md#clear-and-simple-design One local stack, visited set and output array expose closure traversal over the already-built adjacency map; graph parsing and identity semantics remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cycle prevention follows visited identity rather than a depth cap, retry chain or special source name; target spellings are taken from actual graph edges.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state starting-file exclusion, shared indexing, physical vertex equivalence and first-target spelling, with acknowledgment separation under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Every queried source or target spelling passes through the generation's native identity context. Cold spellings can require realpath, ancestor and actual case observations; this traversal does not replace that boundary with lexical equality or an OS-name case rule. The supplied absolute spellings and context must describe the same stable generation view.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The traversal retains no history or handles; its returned array is caller-owned and its stack and visited set are local to one invocation.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached identity is popped once and each reached adjacency entry scanned once, giving V + E structural operations. Identity and Map/Set queries also pay spelling/key text hashing or comparison, and cold spellings add native path/ancestor/case observations. Stack, visited identities and output grow with reached vertices and retained text; duplicate edge spellings still require identity queries.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This closure operation owns no cross-request cache; selectWatchInputs owns final per-spelling reuse and envelopeGraphIndexes owns shared adjacency reuse.
+ */
+export declare function selectReachableEdges(graph: TtscEnvelopeGraphIndexes, state: TtscEnvelopeDerivation, file: string): string[];

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

@@ -0,0 +1,45 @@
+'use strict';
+
+var derivationIdentity = require('./derivationIdentity.js');
+
+/**
+ * Walk the reachability closure of the graph's direct `edges` from `file`,
+ * returning the absolute path of every file reached (the starting file itself
+ * excluded, even when a cycle points back at it). Reads the shared per-envelope
+ * edge index instead of rebuilding it per delivery.
+ *
+ * Traversal coalesces physical vertices using the supplied generation context;
+ * the first reached target spelling is retained. The starting identity is
+ * marked before traversal, so cycles never reintroduce it into the output.
+ *
+ * @evidence contracts/common.md#principled-implementation A depth-first worklist and identity visited set enumerate each reachable vertex once; premarking the start removes it even when a cycle returns to the same file through an alias.
+ * @evidence contracts/common.md#clear-and-simple-design One local stack, visited set and output array expose closure traversal over the already-built adjacency map; graph parsing and identity semantics remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cycle prevention follows visited identity rather than a depth cap, retry chain or special source name; target spellings are taken from actual graph edges.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state starting-file exclusion, shared indexing, physical vertex equivalence and first-target spelling, with acknowledgment separation under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Every queried source or target spelling passes through the generation's native identity context. Cold spellings can require realpath, ancestor and actual case observations; this traversal does not replace that boundary with lexical equality or an OS-name case rule. The supplied absolute spellings and context must describe the same stable generation view.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The traversal retains no history or handles; its returned array is caller-owned and its stack and visited set are local to one invocation.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached identity is popped once and each reached adjacency entry scanned once, giving V + E structural operations. Identity and Map/Set queries also pay spelling/key text hashing or comparison, and cold spellings add native path/ancestor/case observations. Stack, visited identities and output grow with reached vertices and retained text; duplicate edge spellings still require identity queries.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This closure operation owns no cross-request cache; selectWatchInputs owns final per-spelling reuse and envelopeGraphIndexes owns shared adjacency reuse.
+ */
+function selectReachableEdges(graph, state, file) {
+    const output = [];
+    const visited = new Set([derivationIdentity.derivationIdentity(state, file)]);
+    const queue = [file];
+    while (queue.length !== 0) {
+        const current = queue.pop();
+        for (const target of graph.edges.get(derivationIdentity.derivationIdentity(state, current)) ??
+            []) {
+            const identity = derivationIdentity.derivationIdentity(state, target);
+            if (visited.has(identity)) {
+                continue;
+            }
+            visited.add(identity);
+            queue.push(target);
+            output.push(target);
+        }
+    }
+    return output;
+}
+
+exports.selectReachableEdges = selectReachableEdges;
+//# sourceMappingURL=selectReachableEdges.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectReachableEdges.js","sources":["../../../../src/core/transform/envelope/selectReachableEdges.ts"],"sourcesContent":[null],"names":["derivationIdentity"],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;;AAkBG;SACa,oBAAoB,CAClC,KAA+B,EAC/B,KAA6B,EAC7B,IAAY,EAAA;IAEZ,MAAM,MAAM,GAAa,EAAE;AAC3B,IAAA,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,CAACA,qCAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAClE,IAAA,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC;AACpB,IAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;AACzB,QAAA,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAG;AAC5B,QAAA,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAACA,qCAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACtE,YAAA,EAAE,EAAE;YACJ,MAAM,QAAQ,GAAGA,qCAAkB,CAAC,KAAK,EAAE,MAAM,CAAC;AAClD,YAAA,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;gBACzB;YACF;AACA,YAAA,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;AACrB,YAAA,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;AAClB,YAAA,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QACrB;IACF;AACA,IAAA,OAAO,MAAM;AACf;;;;"}

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

@@ -0,0 +1,43 @@
+import { derivationIdentity } from './derivationIdentity.mjs';
+
+/**
+ * Walk the reachability closure of the graph's direct `edges` from `file`,
+ * returning the absolute path of every file reached (the starting file itself
+ * excluded, even when a cycle points back at it). Reads the shared per-envelope
+ * edge index instead of rebuilding it per delivery.
+ *
+ * Traversal coalesces physical vertices using the supplied generation context;
+ * the first reached target spelling is retained. The starting identity is
+ * marked before traversal, so cycles never reintroduce it into the output.
+ *
+ * @evidence contracts/common.md#principled-implementation A depth-first worklist and identity visited set enumerate each reachable vertex once; premarking the start removes it even when a cycle returns to the same file through an alias.
+ * @evidence contracts/common.md#clear-and-simple-design One local stack, visited set and output array expose closure traversal over the already-built adjacency map; graph parsing and identity semantics remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cycle prevention follows visited identity rather than a depth cap, retry chain or special source name; target spellings are taken from actual graph edges.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state starting-file exclusion, shared indexing, physical vertex equivalence and first-target spelling, with acknowledgment separation under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Every queried source or target spelling passes through the generation's native identity context. Cold spellings can require realpath, ancestor and actual case observations; this traversal does not replace that boundary with lexical equality or an OS-name case rule. The supplied absolute spellings and context must describe the same stable generation view.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The traversal retains no history or handles; its returned array is caller-owned and its stack and visited set are local to one invocation.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached identity is popped once and each reached adjacency entry scanned once, giving V + E structural operations. Identity and Map/Set queries also pay spelling/key text hashing or comparison, and cold spellings add native path/ancestor/case observations. Stack, visited identities and output grow with reached vertices and retained text; duplicate edge spellings still require identity queries.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This closure operation owns no cross-request cache; selectWatchInputs owns final per-spelling reuse and envelopeGraphIndexes owns shared adjacency reuse.
+ */
+function selectReachableEdges(graph, state, file) {
+    const output = [];
+    const visited = new Set([derivationIdentity(state, file)]);
+    const queue = [file];
+    while (queue.length !== 0) {
+        const current = queue.pop();
+        for (const target of graph.edges.get(derivationIdentity(state, current)) ??
+            []) {
+            const identity = derivationIdentity(state, target);
+            if (visited.has(identity)) {
+                continue;
+            }
+            visited.add(identity);
+            queue.push(target);
+            output.push(target);
+        }
+    }
+    return output;
+}
+
+export { selectReachableEdges };
+//# sourceMappingURL=selectReachableEdges.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectReachableEdges.mjs","sources":["../../../../src/core/transform/envelope/selectReachableEdges.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;;;;AAkBG;SACa,oBAAoB,CAClC,KAA+B,EAC/B,KAA6B,EAC7B,IAAY,EAAA;IAEZ,MAAM,MAAM,GAAa,EAAE;AAC3B,IAAA,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAClE,IAAA,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC;AACpB,IAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;AACzB,QAAA,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAG;AAC5B,QAAA,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACtE,YAAA,EAAE,EAAE;YACJ,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC;AAClD,YAAA,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;gBACzB;YACF;AACA,YAAA,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;AACrB,YAAA,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;AAClB,YAAA,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QACrB;IACF;AACA,IAAA,OAAO,MAAM;AACf;;;;"}

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

@@ -0,0 +1,21 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.cjs";
+import type { TtscEnvelopeGraphIndexes } from "./TtscEnvelopeGraphIndexes.cjs";
+/**
+ * Return the source files whose direct graph edges are reachable from `file`,
+ * including `file` itself. Resolution candidates belong to importers rather
+ * than targets, so this is intentionally distinct from selectReachableEdges.
+ *
+ * The first element keeps the caller's spelling of `file`; newly reached
+ * identities use the graph's source spelling when available. This includes a
+ * source exactly once by physical identity even if cycles or aliases reach it.
+ *
+ * @evidence contracts/common.md#principled-implementation A depth-first visited-identity traversal includes the start and every reachable importer exactly once, using source spellings so candidate ownership is resolved from importer identity rather than target text.
+ * @evidence contracts/common.md#clear-and-simple-design The source-closure selector differs visibly from target-edge selection only in including the start and choosing source spellings, reflecting their distinct consumer semantics.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Physical visited identities handle cycles and aliases without arbitrary traversal cutoffs or importer-name exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain importer ownership, start inclusion, spelling choice and cycle/alias behavior with separate acknowledgment tags under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The start and queried edge spellings use the generation's native identity context, including cold realpath, ancestor and actual case observations. Graph source spellings select presentation after native identity admission; they do not establish identity by lexical text. The supplied absolute spellings and context must represent the same stable generation view.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the caller-owned output array escapes; the worklist and visited set are local, with no retained history, watchers or file handles.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached identity is popped once and each reached adjacency entry scanned once, giving V + E structural operations. Spelling/key text hashing or comparison and cold native path/ancestor/case observations add identity costs, including queries for duplicate edge spellings. Stack, visited identities and output retain reached-vertex populations and their text; source spelling selection is one additional Map query per newly reached identity.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This source closure is an invocation-local computation; per-delivery watch-list reuse belongs to selectWatchInputs and generation index reuse belongs to envelopeGraphIndexes.
+ */
+export declare function selectReachableSources(graph: TtscEnvelopeGraphIndexes, state: TtscEnvelopeDerivation, file: string): string[];

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

@@ -0,0 +1,21 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.mjs";
+import type { TtscEnvelopeGraphIndexes } from "./TtscEnvelopeGraphIndexes.mjs";
+/**
+ * Return the source files whose direct graph edges are reachable from `file`,
+ * including `file` itself. Resolution candidates belong to importers rather
+ * than targets, so this is intentionally distinct from selectReachableEdges.
+ *
+ * The first element keeps the caller's spelling of `file`; newly reached
+ * identities use the graph's source spelling when available. This includes a
+ * source exactly once by physical identity even if cycles or aliases reach it.
+ *
+ * @evidence contracts/common.md#principled-implementation A depth-first visited-identity traversal includes the start and every reachable importer exactly once, using source spellings so candidate ownership is resolved from importer identity rather than target text.
+ * @evidence contracts/common.md#clear-and-simple-design The source-closure selector differs visibly from target-edge selection only in including the start and choosing source spellings, reflecting their distinct consumer semantics.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Physical visited identities handle cycles and aliases without arbitrary traversal cutoffs or importer-name exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain importer ownership, start inclusion, spelling choice and cycle/alias behavior with separate acknowledgment tags under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The start and queried edge spellings use the generation's native identity context, including cold realpath, ancestor and actual case observations. Graph source spellings select presentation after native identity admission; they do not establish identity by lexical text. The supplied absolute spellings and context must represent the same stable generation view.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the caller-owned output array escapes; the worklist and visited set are local, with no retained history, watchers or file handles.
+ * @evidence contracts/performance.md#efficient-algorithms Each reached identity is popped once and each reached adjacency entry scanned once, giving V + E structural operations. Spelling/key text hashing or comparison and cold native path/ancestor/case observations add identity costs, including queries for duplicate edge spellings. Stack, visited identities and output retain reached-vertex populations and their text; source spelling selection is one additional Map query per newly reached identity.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This source closure is an invocation-local computation; per-delivery watch-list reuse belongs to selectWatchInputs and generation index reuse belongs to envelopeGraphIndexes.
+ */
+export declare function selectReachableSources(graph: TtscEnvelopeGraphIndexes, state: TtscEnvelopeDerivation, file: string): string[];