@ttsc/unplugin 0.30.3 → 0.31.0

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

@@ -0,0 +1,72 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * Reference-graph indexes shared by every watch-input derivation.
+ *
+ * Physical identities coalesce reachability vertices, while lexical spellings
+ * retain separate compiler predicate observations and alias-sensitive inputs.
+ * The builder validates observations; this interface only represents the
+ * result.
+ *
+ * @evidence contracts/common.md#principled-implementation Identity-keyed edges represent reachability independently of lexical proof keys; separate conflict sets retain contradictory observations instead of choosing an arbitrary usable proof.
+ * @evidence contracts/common.md#clear-and-simple-design Adjacency, universal inputs and predicate proof maps remain separate fields because their consumers ask different questions about the same generation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Speculative inputs and explicit failure/conflict sets represent supported weaker evidence without inventing content hashes or hiding contradictions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains identity versus spelling and the builder's validation responsibility; member comments define speculative inputs and proof states with blank member and tag separation under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Identity keys come from the envelope's filesystem context, while proof keys retain native absolute lexical spellings; this representation does not equate case folding with an operating-system name.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscEnvelopeGraphIndexes only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscEnvelopeGraphIndexes only declares a shape; it has no work to reuse
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscEnvelopeGraphIndexes only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscEnvelopeGraphIndexes {
+    /** Identity of each direct-edge source -> its resolved absolute targets. */
+    readonly edges: Map<string, string[]>;
+    /**
+     * Native identity -> selected absolute spelling for sources, targets and
+     * universal/candidate members. Later edge-source declarations replace that
+     * identity's spelling; other categories retain an existing choice.
+     */
+    readonly spellings: Map<string, string>;
+    /** Importer-owned resolver-input entries, sources pre-identified. */
+    readonly candidates: {
+        source: string;
+        files: string[];
+    }[];
+    /**
+     * Resolved absolute `graph.globals` members in the ordinary language bound;
+     * an admitted complete plugin declaration can replace this contribution.
+     */
+    readonly globals: string[];
+    /** Resolved absolute `graph.configs` members: the tsconfig `extends` chain. */
+    readonly configs: string[];
+    /** Resolver inputs whose state affects every source file. */
+    readonly resolutionInputs: string[];
+    /** Every realized or resolver-input path, keyed by lexical spelling. */
+    readonly memberSpellings: Set<string>;
+    /**
+     * Predicate-only resolver inputs, keyed by absolute lexical spelling. These
+     * are exact compiler calls but need not carry file content, for example a
+     * failed file predicate or automatic type-root directory enumeration. A path
+     * that is also a realized edge, global, config, or source keeps the stronger
+     * realized-file standard.
+     */
+    readonly speculative: Set<string>;
+    /** Compiler-time legacy proof keyed by absolute lexical spelling. */
+    readonly inputProofs: Map<string, {
+        hash: string | null;
+        path: string;
+        realpath: string | null;
+    }>;
+    /** Native compiler-observation failure keyed by absolute lexical spelling. */
+    readonly inputProofFailures: Map<string, string>;
+    /** Graph proof spellings that reported contradictory generation states. */
+    readonly inputProofConflicts: Set<string>;
+    /** Predicate-preserving proofs keyed by absolute lexical spelling. */
+    readonly inputObservations: Map<string, ITtscCompilerTransformation.IInputObservation>;
+    /** Absolute spellings whose predicate proof is malformed or contradictory. */
+    readonly inputObservationConflicts: Set<string>;
+}

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

@@ -0,0 +1,34 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * One module's entry in a transform envelope: its transformed text and, when
+ * the host supplied one, the source map from that text back to the text it was
+ * transformed from.
+ *
+ * @evidence contracts/common.md#principled-implementation Required text and an optional same-entry source map preserve the distinction between transformed code and available provenance; this container does not manufacture a map when the producer omitted it.
+ * @evidence contracts/common.md#clear-and-simple-design The two fields carry one module's transform artifact without embedding compiler diagnostics or watch state in a bundler result.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An absent map stays undefined; the shape contains no consumer-specific synthetic mapping or foreign mutation.
+ * @evidence contracts/common.md#meaningful-documentation The native description states mapping direction and member comments explain map origin, relative sources and absence; members and acknowledgment prose follow the documentation skill's spacing guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Optional map sources carry producer paths relative to the emitted module;
+ *   delivery resolves them through native path grammar and filesystem identity
+ *   before publishing absolute source-map paths. The shape supplies no case policy.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscTransformedOutput only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscTransformedOutput only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscTransformedOutput only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export interface TtscTransformedOutput {
+    /** Transformed TypeScript text of the module. */
+    code: string;
+    /**
+     * The envelope's source map for the module, as the host wrote it: `sources`
+     * relative to the module's directory. `undefined` when the host supplied
+     * none.
+     */
+    map?: ITtscCompilerTransformation.ISourceMap;
+}

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

@@ -0,0 +1,34 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * One module's entry in a transform envelope: its transformed text and, when
+ * the host supplied one, the source map from that text back to the text it was
+ * transformed from.
+ *
+ * @evidence contracts/common.md#principled-implementation Required text and an optional same-entry source map preserve the distinction between transformed code and available provenance; this container does not manufacture a map when the producer omitted it.
+ * @evidence contracts/common.md#clear-and-simple-design The two fields carry one module's transform artifact without embedding compiler diagnostics or watch state in a bundler result.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An absent map stays undefined; the shape contains no consumer-specific synthetic mapping or foreign mutation.
+ * @evidence contracts/common.md#meaningful-documentation The native description states mapping direction and member comments explain map origin, relative sources and absence; members and acknowledgment prose follow the documentation skill's spacing guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Optional map sources carry producer paths relative to the emitted module;
+ *   delivery resolves them through native path grammar and filesystem identity
+ *   before publishing absolute source-map paths. The shape supplies no case policy.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscTransformedOutput only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscTransformedOutput only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscTransformedOutput only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export interface TtscTransformedOutput {
+    /** Transformed TypeScript text of the module. */
+    code: string;
+    /**
+     * The envelope's source map for the module, as the host wrote it: `sources`
+     * relative to the module's directory. `undefined` when the host supplied
+     * none.
+     */
+    map?: ITtscCompilerTransformation.ISourceMap;
+}

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

@@ -0,0 +1,34 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+/**
+ * One module's entry in a transform envelope: its transformed text and, when
+ * the host supplied one, the source map from that text back to the text it was
+ * transformed from.
+ *
+ * @evidence contracts/common.md#principled-implementation Required text and an optional same-entry source map preserve the distinction between transformed code and available provenance; this container does not manufacture a map when the producer omitted it.
+ * @evidence contracts/common.md#clear-and-simple-design The two fields carry one module's transform artifact without embedding compiler diagnostics or watch state in a bundler result.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An absent map stays undefined; the shape contains no consumer-specific synthetic mapping or foreign mutation.
+ * @evidence contracts/common.md#meaningful-documentation The native description states mapping direction and member comments explain map origin, relative sources and absence; members and acknowledgment prose follow the documentation skill's spacing guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Optional map sources carry producer paths relative to the emitted module;
+ *   delivery resolves them through native path grammar and filesystem identity
+ *   before publishing absolute source-map paths. The shape supplies no case policy.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscTransformedOutput only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscTransformedOutput only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscTransformedOutput only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export interface TtscTransformedOutput {
+    /** Transformed TypeScript text of the module. */
+    code: string;
+    /**
+     * The envelope's source map for the module, as the host wrote it: `sources`
+     * relative to the module's directory. `undefined` when the host supplied
+     * none.
+     */
+    map?: ITtscCompilerTransformation.ISourceMap;
+}

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

@@ -0,0 +1,19 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.cjs";
+/**
+ * Fold one envelope member list (`volatile`, `dependenciesComplete`) into an
+ * identity set. Members are keyed like `typescript`, so a project-relative and
+ * an absolute spelling of the same file share one identity; a malformed member
+ * is ignored rather than fatal.
+ *
+ * @evidence contracts/common.md#principled-implementation Valid declaration strings resolve against the project root before physical identity lookup, so absolute and relative aliases enter one membership set; malformed entries assert no membership.
+ * @evidence contracts/common.md#clear-and-simple-design A single list-to-set adapter serves both volatility and completeness without duplicating their path identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Non-array values and empty or non-string members are rejected by protocol shape, not special-cased by consumer or expected output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains the shared declaration use, project-relative interpretation and malformed-entry handling; acknowledgment tags remain separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve interprets project-relative paths and the supplied envelope identity context handles filesystem case and realpath behavior without manually rewriting separators or guessing case by platform.
+ * @evidence contracts/performance.md#efficient-algorithms One pass examines every declaration entry and a Set coalesces equal identities. Native path resolution and key hashing cost each valid spelling's length; derivationIdentity reuses the generation transaction and first misses pay native identity and case observations. Temporary storage follows distinct identities rather than repeated aliases.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Builds its Set once per call from its argument and keeps no cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The output Set is local and handed to the caller.
+ */
+export declare function collectDeclaredIdentities(state: TtscEnvelopeDerivation, projectRoot: string, listed: unknown): Set<string>;

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

@@ -0,0 +1,19 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.mjs";
+/**
+ * Fold one envelope member list (`volatile`, `dependenciesComplete`) into an
+ * identity set. Members are keyed like `typescript`, so a project-relative and
+ * an absolute spelling of the same file share one identity; a malformed member
+ * is ignored rather than fatal.
+ *
+ * @evidence contracts/common.md#principled-implementation Valid declaration strings resolve against the project root before physical identity lookup, so absolute and relative aliases enter one membership set; malformed entries assert no membership.
+ * @evidence contracts/common.md#clear-and-simple-design A single list-to-set adapter serves both volatility and completeness without duplicating their path identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Non-array values and empty or non-string members are rejected by protocol shape, not special-cased by consumer or expected output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains the shared declaration use, project-relative interpretation and malformed-entry handling; acknowledgment tags remain separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve interprets project-relative paths and the supplied envelope identity context handles filesystem case and realpath behavior without manually rewriting separators or guessing case by platform.
+ * @evidence contracts/performance.md#efficient-algorithms One pass examines every declaration entry and a Set coalesces equal identities. Native path resolution and key hashing cost each valid spelling's length; derivationIdentity reuses the generation transaction and first misses pay native identity and case observations. Temporary storage follows distinct identities rather than repeated aliases.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Builds its Set once per call from its argument and keeps no cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The output Set is local and handed to the caller.
+ */
+export declare function collectDeclaredIdentities(state: TtscEnvelopeDerivation, projectRoot: string, listed: unknown): Set<string>;

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

@@ -0,0 +1,19 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation";
+/**
+ * Fold one envelope member list (`volatile`, `dependenciesComplete`) into an
+ * identity set. Members are keyed like `typescript`, so a project-relative and
+ * an absolute spelling of the same file share one identity; a malformed member
+ * is ignored rather than fatal.
+ *
+ * @evidence contracts/common.md#principled-implementation Valid declaration strings resolve against the project root before physical identity lookup, so absolute and relative aliases enter one membership set; malformed entries assert no membership.
+ * @evidence contracts/common.md#clear-and-simple-design A single list-to-set adapter serves both volatility and completeness without duplicating their path identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Non-array values and empty or non-string members are rejected by protocol shape, not special-cased by consumer or expected output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains the shared declaration use, project-relative interpretation and malformed-entry handling; acknowledgment tags remain separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve interprets project-relative paths and the supplied envelope identity context handles filesystem case and realpath behavior without manually rewriting separators or guessing case by platform.
+ * @evidence contracts/performance.md#efficient-algorithms One pass examines every declaration entry and a Set coalesces equal identities. Native path resolution and key hashing cost each valid spelling's length; derivationIdentity reuses the generation transaction and first misses pay native identity and case observations. Temporary storage follows distinct identities rather than repeated aliases.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Builds its Set once per call from its argument and keeps no cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The output Set is local and handed to the caller.
+ */
+export declare function collectDeclaredIdentities(state: TtscEnvelopeDerivation, projectRoot: string, listed: unknown): Set<string>;

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

@@ -0,0 +1,38 @@
+'use strict';
+
+var path = require('node:path');
+var derivationIdentity = require('./derivationIdentity.js');
+
+/**
+ * Fold one envelope member list (`volatile`, `dependenciesComplete`) into an
+ * identity set. Members are keyed like `typescript`, so a project-relative and
+ * an absolute spelling of the same file share one identity; a malformed member
+ * is ignored rather than fatal.
+ *
+ * @evidence contracts/common.md#principled-implementation Valid declaration strings resolve against the project root before physical identity lookup, so absolute and relative aliases enter one membership set; malformed entries assert no membership.
+ * @evidence contracts/common.md#clear-and-simple-design A single list-to-set adapter serves both volatility and completeness without duplicating their path identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Non-array values and empty or non-string members are rejected by protocol shape, not special-cased by consumer or expected output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains the shared declaration use, project-relative interpretation and malformed-entry handling; acknowledgment tags remain separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve interprets project-relative paths and the supplied envelope identity context handles filesystem case and realpath behavior without manually rewriting separators or guessing case by platform.
+ * @evidence contracts/performance.md#efficient-algorithms One pass examines every declaration entry and a Set coalesces equal identities. Native path resolution and key hashing cost each valid spelling's length; derivationIdentity reuses the generation transaction and first misses pay native identity and case observations. Temporary storage follows distinct identities rather than repeated aliases.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Builds its Set once per call from its argument and keeps no cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The output Set is local and handed to the caller.
+ */
+function collectDeclaredIdentities(state, projectRoot, listed) {
+    const output = new Set();
+    if (!Array.isArray(listed)) {
+        return output;
+    }
+    for (const entry of listed) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            continue;
+        }
+        output.add(derivationIdentity.derivationIdentity(state, path.resolve(projectRoot, entry)));
+    }
+    return output;
+}
+
+exports.collectDeclaredIdentities = collectDeclaredIdentities;
+//# sourceMappingURL=collectDeclaredIdentities.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collectDeclaredIdentities.js","sources":["../../../../src/core/transform/envelope/collectDeclaredIdentities.ts"],"sourcesContent":[null],"names":["derivationIdentity"],"mappings":";;;;;AAKA;;;;;;;;;;;;;;;;AAgBG;SACa,yBAAyB,CACvC,KAA6B,EAC7B,WAAmB,EACnB,MAAe,EAAA;AAEf,IAAA,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;AAC1B,QAAA,OAAO,MAAM;IACf;AACA,IAAA,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;QAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;YACnD;QACF;AACA,QAAA,MAAM,CAAC,GAAG,CAACA,qCAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IACzE;AACA,IAAA,OAAO,MAAM;AACf;;;;"}

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

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { derivationIdentity } from './derivationIdentity.mjs';
+
+/**
+ * Fold one envelope member list (`volatile`, `dependenciesComplete`) into an
+ * identity set. Members are keyed like `typescript`, so a project-relative and
+ * an absolute spelling of the same file share one identity; a malformed member
+ * is ignored rather than fatal.
+ *
+ * @evidence contracts/common.md#principled-implementation Valid declaration strings resolve against the project root before physical identity lookup, so absolute and relative aliases enter one membership set; malformed entries assert no membership.
+ * @evidence contracts/common.md#clear-and-simple-design A single list-to-set adapter serves both volatility and completeness without duplicating their path identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Non-array values and empty or non-string members are rejected by protocol shape, not special-cased by consumer or expected output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains the shared declaration use, project-relative interpretation and malformed-entry handling; acknowledgment tags remain separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve interprets project-relative paths and the supplied envelope identity context handles filesystem case and realpath behavior without manually rewriting separators or guessing case by platform.
+ * @evidence contracts/performance.md#efficient-algorithms One pass examines every declaration entry and a Set coalesces equal identities. Native path resolution and key hashing cost each valid spelling's length; derivationIdentity reuses the generation transaction and first misses pay native identity and case observations. Temporary storage follows distinct identities rather than repeated aliases.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Builds its Set once per call from its argument and keeps no cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The output Set is local and handed to the caller.
+ */
+function collectDeclaredIdentities(state, projectRoot, listed) {
+    const output = new Set();
+    if (!Array.isArray(listed)) {
+        return output;
+    }
+    for (const entry of listed) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            continue;
+        }
+        output.add(derivationIdentity(state, path.resolve(projectRoot, entry)));
+    }
+    return output;
+}
+
+export { collectDeclaredIdentities };
+//# sourceMappingURL=collectDeclaredIdentities.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collectDeclaredIdentities.mjs","sources":["../../../../src/core/transform/envelope/collectDeclaredIdentities.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;;;AAgBG;SACa,yBAAyB,CACvC,KAA6B,EAC7B,WAAmB,EACnB,MAAe,EAAA;AAEf,IAAA,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;AAC1B,QAAA,OAAO,MAAM;IACf;AACA,IAAA,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;QAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;YACnD;QACF;AACA,QAAA,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IACzE;AACA,IAAA,OAAO,MAAM;AACf;;;;"}

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

@@ -0,0 +1,34 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.cjs";
+/**
+ * Build a first-match identity index over one envelope key map (`typescript`,
+ * `dependencies`), mirroring the historical per-delivery scan that returned the
+ * first entry whose resolved key matched by filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolving every producer key against the same root and retaining the first value per physical identity preserves first-match lookup when distinct spellings name one file.
+ * @evidence contracts/common.md#clear-and-simple-design The generic key/value adapter isolates identity indexing from the output-key and dependency-array consumers that choose when to build it.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts First-match precedence is a supported lookup rule, not a special-case alias mapping; the input record is not rewritten to conceal ambiguous producer spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the supported key maps and duplicate precedence, with a blank line before acknowledgments following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Keys use native project-relative resolution and the supplied physical identity context, preserving filesystem-specific alias and case semantics without string-based OS guesses.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Materializes the input's entry pairs, then resolves each producer spelling
+ *   once in iteration order. Path text and uncached native identity/ancestor/
+ *   case observations precede expected-constant Map operations, whose key
+ *   hashing/comparison still processes text. Temporary pairs follow all keys;
+ *   the output holds at most one referenced value per resolved identity.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The immutable generation's callers retain the completed index instead of
+ *   rescanning the same keyed record/root; native observations share its
+ *   identity context. This builder retains no separate cross-call index.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The index is local to the call and handed to the caller.
+ */
+export declare function createEnvelopeKeyIndex<T>(
+/** Generation state whose identity observation memo qualifies producer keys. */
+state: TtscEnvelopeDerivation, 
+/** Stable native root used to expand this producer's relative keys. */
+projectRoot: string, 
+/**
+ * Immutable producer record; own enumeration order determines alias
+ * precedence.
+ */
+keyed: Record<string, T>): Map<string, T>;

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

@@ -0,0 +1,34 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.mjs";
+/**
+ * Build a first-match identity index over one envelope key map (`typescript`,
+ * `dependencies`), mirroring the historical per-delivery scan that returned the
+ * first entry whose resolved key matched by filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolving every producer key against the same root and retaining the first value per physical identity preserves first-match lookup when distinct spellings name one file.
+ * @evidence contracts/common.md#clear-and-simple-design The generic key/value adapter isolates identity indexing from the output-key and dependency-array consumers that choose when to build it.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts First-match precedence is a supported lookup rule, not a special-case alias mapping; the input record is not rewritten to conceal ambiguous producer spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the supported key maps and duplicate precedence, with a blank line before acknowledgments following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Keys use native project-relative resolution and the supplied physical identity context, preserving filesystem-specific alias and case semantics without string-based OS guesses.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Materializes the input's entry pairs, then resolves each producer spelling
+ *   once in iteration order. Path text and uncached native identity/ancestor/
+ *   case observations precede expected-constant Map operations, whose key
+ *   hashing/comparison still processes text. Temporary pairs follow all keys;
+ *   the output holds at most one referenced value per resolved identity.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The immutable generation's callers retain the completed index instead of
+ *   rescanning the same keyed record/root; native observations share its
+ *   identity context. This builder retains no separate cross-call index.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The index is local to the call and handed to the caller.
+ */
+export declare function createEnvelopeKeyIndex<T>(
+/** Generation state whose identity observation memo qualifies producer keys. */
+state: TtscEnvelopeDerivation, 
+/** Stable native root used to expand this producer's relative keys. */
+projectRoot: string, 
+/**
+ * Immutable producer record; own enumeration order determines alias
+ * precedence.
+ */
+keyed: Record<string, T>): Map<string, T>;

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

@@ -0,0 +1,34 @@
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation";
+/**
+ * Build a first-match identity index over one envelope key map (`typescript`,
+ * `dependencies`), mirroring the historical per-delivery scan that returned the
+ * first entry whose resolved key matched by filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolving every producer key against the same root and retaining the first value per physical identity preserves first-match lookup when distinct spellings name one file.
+ * @evidence contracts/common.md#clear-and-simple-design The generic key/value adapter isolates identity indexing from the output-key and dependency-array consumers that choose when to build it.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts First-match precedence is a supported lookup rule, not a special-case alias mapping; the input record is not rewritten to conceal ambiguous producer spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the supported key maps and duplicate precedence, with a blank line before acknowledgments following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Keys use native project-relative resolution and the supplied physical identity context, preserving filesystem-specific alias and case semantics without string-based OS guesses.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Materializes the input's entry pairs, then resolves each producer spelling
+ *   once in iteration order. Path text and uncached native identity/ancestor/
+ *   case observations precede expected-constant Map operations, whose key
+ *   hashing/comparison still processes text. Temporary pairs follow all keys;
+ *   the output holds at most one referenced value per resolved identity.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The immutable generation's callers retain the completed index instead of
+ *   rescanning the same keyed record/root; native observations share its
+ *   identity context. This builder retains no separate cross-call index.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The index is local to the call and handed to the caller.
+ */
+export declare function createEnvelopeKeyIndex<T>(
+/** Generation state whose identity observation memo qualifies producer keys. */
+state: TtscEnvelopeDerivation, 
+/** Stable native root used to expand this producer's relative keys. */
+projectRoot: string, 
+/**
+ * Immutable producer record; own enumeration order determines alias
+ * precedence.
+ */
+keyed: Record<string, T>): Map<string, T>;

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

@@ -0,0 +1,50 @@
+'use strict';
+
+var path = require('node:path');
+var derivationIdentity = require('./derivationIdentity.js');
+
+/**
+ * Build a first-match identity index over one envelope key map (`typescript`,
+ * `dependencies`), mirroring the historical per-delivery scan that returned the
+ * first entry whose resolved key matched by filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolving every producer key against the same root and retaining the first value per physical identity preserves first-match lookup when distinct spellings name one file.
+ * @evidence contracts/common.md#clear-and-simple-design The generic key/value adapter isolates identity indexing from the output-key and dependency-array consumers that choose when to build it.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts First-match precedence is a supported lookup rule, not a special-case alias mapping; the input record is not rewritten to conceal ambiguous producer spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the supported key maps and duplicate precedence, with a blank line before acknowledgments following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Keys use native project-relative resolution and the supplied physical identity context, preserving filesystem-specific alias and case semantics without string-based OS guesses.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Materializes the input's entry pairs, then resolves each producer spelling
+ *   once in iteration order. Path text and uncached native identity/ancestor/
+ *   case observations precede expected-constant Map operations, whose key
+ *   hashing/comparison still processes text. Temporary pairs follow all keys;
+ *   the output holds at most one referenced value per resolved identity.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The immutable generation's callers retain the completed index instead of
+ *   rescanning the same keyed record/root; native observations share its
+ *   identity context. This builder retains no separate cross-call index.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The index is local to the call and handed to the caller.
+ */
+function createEnvelopeKeyIndex(
+/** Generation state whose identity observation memo qualifies producer keys. */
+state, 
+/** Stable native root used to expand this producer's relative keys. */
+projectRoot, 
+/**
+ * Immutable producer record; own enumeration order determines alias
+ * precedence.
+ */
+keyed) {
+    const index = new Map();
+    for (const [candidate, value] of Object.entries(keyed)) {
+        const identity = derivationIdentity.derivationIdentity(state, path.resolve(projectRoot, candidate));
+        if (!index.has(identity)) {
+            index.set(identity, value);
+        }
+    }
+    return index;
+}
+
+exports.createEnvelopeKeyIndex = createEnvelopeKeyIndex;
+//# sourceMappingURL=createEnvelopeKeyIndex.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createEnvelopeKeyIndex.js","sources":["../../../../src/core/transform/envelope/createEnvelopeKeyIndex.ts"],"sourcesContent":[null],"names":["derivationIdentity"],"mappings":";;;;;AAKA;;;;;;;;;;;;;;;;;;;;;;AAsBG;SACa,sBAAsB;AACpC;AACA,KAA6B;AAC7B;AACA,WAAmB;AACnB;;;AAGG;AACH,KAAwB,EAAA;AAExB,IAAA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAa;AAClC,IAAA,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;AACtD,QAAA,MAAM,QAAQ,GAAGA,qCAAkB,CACjC,KAAK,EACL,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CACrC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;AACxB,YAAA,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC;QAC5B;IACF;AACA,IAAA,OAAO,KAAK;AACd;;;;"}

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

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { derivationIdentity } from './derivationIdentity.mjs';
+
+/**
+ * Build a first-match identity index over one envelope key map (`typescript`,
+ * `dependencies`), mirroring the historical per-delivery scan that returned the
+ * first entry whose resolved key matched by filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolving every producer key against the same root and retaining the first value per physical identity preserves first-match lookup when distinct spellings name one file.
+ * @evidence contracts/common.md#clear-and-simple-design The generic key/value adapter isolates identity indexing from the output-key and dependency-array consumers that choose when to build it.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts First-match precedence is a supported lookup rule, not a special-case alias mapping; the input record is not rewritten to conceal ambiguous producer spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the supported key maps and duplicate precedence, with a blank line before acknowledgments following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Keys use native project-relative resolution and the supplied physical identity context, preserving filesystem-specific alias and case semantics without string-based OS guesses.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Materializes the input's entry pairs, then resolves each producer spelling
+ *   once in iteration order. Path text and uncached native identity/ancestor/
+ *   case observations precede expected-constant Map operations, whose key
+ *   hashing/comparison still processes text. Temporary pairs follow all keys;
+ *   the output holds at most one referenced value per resolved identity.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The immutable generation's callers retain the completed index instead of
+ *   rescanning the same keyed record/root; native observations share its
+ *   identity context. This builder retains no separate cross-call index.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The index is local to the call and handed to the caller.
+ */
+function createEnvelopeKeyIndex(
+/** Generation state whose identity observation memo qualifies producer keys. */
+state, 
+/** Stable native root used to expand this producer's relative keys. */
+projectRoot, 
+/**
+ * Immutable producer record; own enumeration order determines alias
+ * precedence.
+ */
+keyed) {
+    const index = new Map();
+    for (const [candidate, value] of Object.entries(keyed)) {
+        const identity = derivationIdentity(state, path.resolve(projectRoot, candidate));
+        if (!index.has(identity)) {
+            index.set(identity, value);
+        }
+    }
+    return index;
+}
+
+export { createEnvelopeKeyIndex };
+//# sourceMappingURL=createEnvelopeKeyIndex.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createEnvelopeKeyIndex.mjs","sources":["../../../../src/core/transform/envelope/createEnvelopeKeyIndex.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;;;;;;;;;AAsBG;SACa,sBAAsB;AACpC;AACA,KAA6B;AAC7B;AACA,WAAmB;AACnB;;;AAGG;AACH,KAAwB,EAAA;AAExB,IAAA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAa;AAClC,IAAA,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;AACtD,QAAA,MAAM,QAAQ,GAAG,kBAAkB,CACjC,KAAK,EACL,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CACrC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;AACxB,YAAA,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC;QAC5B;IACF;AACA,IAAA,OAAO,KAAK;AACd;;;;"}

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

@@ -0,0 +1,27 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.cjs";
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.cjs";
+/**
+ * Memoize the declared project-walk keys for one envelope generation.
+ *
+ * A completed undefined result requests comparison of the whole project walk;
+ * the separate built flag prevents treating that result as an unbuilt cache.
+ * The cached project hashes, root and scratch policy must remain stable for the
+ * lifetime of this generation state.
+ *
+ * @evidence contracts/common.md#principled-implementation The built flag distinguishes a legitimate undefined whole-walk policy from an uncomputed selection, preserving conservative comparison for graph-free results.
+ * @evidence contracts/common.md#clear-and-simple-design Selection stays in selectDeclaredProjectInputKeys while this wrapper owns exactly its generation memo and completed-state marker.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Undefined remains the supported conservative policy instead of being replaced by an empty set that would silently authorize narrowing.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain completed undefined, the built flag and stable-generation premises; descriptive prose and tags are separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Selection receives the envelope's identity context and native project root, sharing filesystem-aware key matching rather than introducing its own separator or case policy.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One selected set and one built flag live in weakly owned envelope state; set population cannot exceed declared keys actually present in the project snapshot and no independent resources are acquired.
+ * @evidence contracts/performance.md#efficient-algorithms A cold state pays the selector's declaration populations, entry-array allocations and native project-key/path/ancestor/case costs; delegation does not reduce that selection to one field lookup. Completed states need fixed flag/result reads, including a completed undefined whole-walk policy.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reuse keys the envelope generation and requires unchanged project hashes, root and scratch exclusions; both a set and the whole-walk undefined outcome are reused.
+ */
+export declare function declaredProjectInputKeys(
+/**
+ * Generation state owning the completed selection and its separate built
+ * flag.
+ */
+state: TtscEnvelopeDerivation, 
+/** Stable generation root, project hashes, envelope and scratch exclusions. */
+cached: TtscCachedProjectTransform): Set<string> | undefined;

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

@@ -0,0 +1,27 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.mjs";
+import type { TtscEnvelopeDerivation } from "./TtscEnvelopeDerivation.mjs";
+/**
+ * Memoize the declared project-walk keys for one envelope generation.
+ *
+ * A completed undefined result requests comparison of the whole project walk;
+ * the separate built flag prevents treating that result as an unbuilt cache.
+ * The cached project hashes, root and scratch policy must remain stable for the
+ * lifetime of this generation state.
+ *
+ * @evidence contracts/common.md#principled-implementation The built flag distinguishes a legitimate undefined whole-walk policy from an uncomputed selection, preserving conservative comparison for graph-free results.
+ * @evidence contracts/common.md#clear-and-simple-design Selection stays in selectDeclaredProjectInputKeys while this wrapper owns exactly its generation memo and completed-state marker.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Undefined remains the supported conservative policy instead of being replaced by an empty set that would silently authorize narrowing.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain completed undefined, the built flag and stable-generation premises; descriptive prose and tags are separated under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Selection receives the envelope's identity context and native project root, sharing filesystem-aware key matching rather than introducing its own separator or case policy.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One selected set and one built flag live in weakly owned envelope state; set population cannot exceed declared keys actually present in the project snapshot and no independent resources are acquired.
+ * @evidence contracts/performance.md#efficient-algorithms A cold state pays the selector's declaration populations, entry-array allocations and native project-key/path/ancestor/case costs; delegation does not reduce that selection to one field lookup. Completed states need fixed flag/result reads, including a completed undefined whole-walk policy.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reuse keys the envelope generation and requires unchanged project hashes, root and scratch exclusions; both a set and the whole-walk undefined outcome are reused.
+ */
+export declare function declaredProjectInputKeys(
+/**
+ * Generation state owning the completed selection and its separate built
+ * flag.
+ */
+state: TtscEnvelopeDerivation, 
+/** Stable generation root, project hashes, envelope and scratch exclusions. */
+cached: TtscCachedProjectTransform): Set<string> | undefined;