@ttsc/unplugin 0.30.4 → 0.31.1

package/lib/core/transform/inputs/validateGraphInputObservation.mjs

@@ -0,0 +1,28 @@
+import { normalizeGraphInputObservation } from '../envelope/normalizeGraphInputObservation.mjs';
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { createHostPathIdentityContext } from '../filesystem/createHostPathIdentityContext.mjs';
+import { graphInputObservationFailures } from './graphInputObservationFailures.mjs';
+
+/**
+ * Normalize and replay one compiler graph observation against a filesystem
+ * view. Invalid or contradictory proof shape returns proof-conflict; otherwise
+ * the returned strings identify recorded predicates that no longer hold.
+ *
+ * @evidence contracts/common.md#principled-implementation Normalization rejects unsupported proof combinations before replay, and a filesystem-derived identity context supplies target equivalence for valid observations.
+ * @evidence contracts/common.md#clear-and-simple-design Proof-shape validation, context creation and predicate replay each retain a single owner rather than duplicating their rules here.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Malformed observations cannot bypass normalization or acquire fabricated successful predicates to match a cache entry.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains conflict versus changed-predicate results, followed by a blank acknowledgment separator under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral normalization uses the supplied path dialect and constructs identity policy from that same filesystem's capabilities; recorded protocol paths are not blindly compared as native strings.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Normalized copies, returned mismatch names and one identity transaction are call-local or transferred to the caller; no persistent cache, native handle or running task is retained.
+ * @evidence contracts/performance.md#efficient-algorithms Malformed shape returns before native replay. Valid shape copies E supplied entry slots and normalizes supplied path/hash text once, then replays only recorded predicates with a shared kind stat and one call-local identity transaction. Selected native listing/link resolution, UTF-8 name sorting/serialization and B read-byte decoding/hashing retain their delegated costs and temporary buffers; normalized entry copies and identity observations add call-local storage. No project-wide enumeration is introduced.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A replay answers for the filesystem now; callers decide whether an earlier replay may be shared.
+ */
+function validateGraphInputObservation(file, observation, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const normalized = normalizeGraphInputObservation(observation, filesystem.platform);
+    if (normalized === undefined)
+        return ["proof-conflict"];
+    return graphInputObservationFailures(file, normalized, filesystem, createHostPathIdentityContext(filesystem));
+}
+
+export { validateGraphInputObservation };
+//# sourceMappingURL=validateGraphInputObservation.mjs.map

package/lib/core/transform/inputs/validateGraphInputObservation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateGraphInputObservation.mjs","sources":["../../../../src/core/transform/inputs/validateGraphInputObservation.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAQA;;;;;;;;;;;;;AAaG;AACG,SAAU,6BAA6B,CAC3C,IAAY,EACZ,WAA0D,EAC1D,aAAgD,6BAA6B,EAAA;IAE7E,MAAM,UAAU,GAAG,8BAA8B,CAC/C,WAAW,EACX,UAAU,CAAC,QAAQ,CACpB;IACD,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,CAAC,gBAAgB,CAAC;AACvD,IAAA,OAAO,6BAA6B,CAClC,IAAI,EACJ,UAAU,EACV,UAAU,EACV,6BAA6B,CAAC,UAAU,CAAC,CAC1C;AACH;;;;"}

package/lib/core/transform/project/TtscProjectDirectorySnapshot.d.cts

@@ -0,0 +1,47 @@
+/**
+ * One directory's project-membership identity at generation time.
+ *
+ * @evidence contracts/common.md#principled-implementation The lexical directory address, current admitted-file subtree relevance and filtered-entry signature distinguish membership meaning from metadata changes caused by irrelevant emitted files.
+ * @evidence contracts/common.md#clear-and-simple-design Three fields carry the walk's result without duplicating its traversal or invalidation policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Relevance follows admitted input kinds and the resolved membership policy rather than an expanding list of fixture or output-directory names.
+ * @evidence contracts/common.md#meaningful-documentation Field paragraphs explain why irrelevant directories remain watched and why filtered membership, rather than a directory timestamp, is compared.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The path member preserves the absolute native directory spelling used
+ *   by one project's walk. Signatures describe its observed entry names and
+ *   kinds; native platform and compiler admission policy belong to that walk.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no work to
+ *   reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectDirectorySnapshot {
+    /** Absolute directory spelling used by the project walk. */
+    path: string;
+    /**
+     * Whether this directory's subtree currently contains an admitted regular
+     * file.
+     *
+     * An admitted directory with no such file is still walked and watched, so a
+     * source appearing in it later is noticed, but it takes no part in the
+     * membership comparison. That is what lets a bundler create its output
+     * directory and fill it without voiding a generation no compiler input
+     * touched, for any output directory rather than for a fixed list of names.
+     */
+    relevant: boolean;
+    /**
+     * Digest of admitted, possible immediate entries and their kinds. A child
+     * directory contributes only when its subtree currently has an admitted
+     * regular file; an unstable enumeration carries a failure marker instead.
+     *
+     * Deliberately not the directory's own metadata. A directory's stamp moves
+     * whenever _any_ entry is added or removed, including the ones the walk
+     * exists to ignore. Comparing filtered membership avoids invalidation from
+     * unrelated output-directory creation or writes.
+     */
+    signature: string;
+}

package/lib/core/transform/project/TtscProjectDirectorySnapshot.d.mts

@@ -0,0 +1,47 @@
+/**
+ * One directory's project-membership identity at generation time.
+ *
+ * @evidence contracts/common.md#principled-implementation The lexical directory address, current admitted-file subtree relevance and filtered-entry signature distinguish membership meaning from metadata changes caused by irrelevant emitted files.
+ * @evidence contracts/common.md#clear-and-simple-design Three fields carry the walk's result without duplicating its traversal or invalidation policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Relevance follows admitted input kinds and the resolved membership policy rather than an expanding list of fixture or output-directory names.
+ * @evidence contracts/common.md#meaningful-documentation Field paragraphs explain why irrelevant directories remain watched and why filtered membership, rather than a directory timestamp, is compared.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The path member preserves the absolute native directory spelling used
+ *   by one project's walk. Signatures describe its observed entry names and
+ *   kinds; native platform and compiler admission policy belong to that walk.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no work to
+ *   reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectDirectorySnapshot {
+    /** Absolute directory spelling used by the project walk. */
+    path: string;
+    /**
+     * Whether this directory's subtree currently contains an admitted regular
+     * file.
+     *
+     * An admitted directory with no such file is still walked and watched, so a
+     * source appearing in it later is noticed, but it takes no part in the
+     * membership comparison. That is what lets a bundler create its output
+     * directory and fill it without voiding a generation no compiler input
+     * touched, for any output directory rather than for a fixed list of names.
+     */
+    relevant: boolean;
+    /**
+     * Digest of admitted, possible immediate entries and their kinds. A child
+     * directory contributes only when its subtree currently has an admitted
+     * regular file; an unstable enumeration carries a failure marker instead.
+     *
+     * Deliberately not the directory's own metadata. A directory's stamp moves
+     * whenever _any_ entry is added or removed, including the ones the walk
+     * exists to ignore. Comparing filtered membership avoids invalidation from
+     * unrelated output-directory creation or writes.
+     */
+    signature: string;
+}

package/lib/core/transform/project/TtscProjectDirectorySnapshot.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One directory's project-membership identity at generation time.
+ *
+ * @evidence contracts/common.md#principled-implementation The lexical directory address, current admitted-file subtree relevance and filtered-entry signature distinguish membership meaning from metadata changes caused by irrelevant emitted files.
+ * @evidence contracts/common.md#clear-and-simple-design Three fields carry the walk's result without duplicating its traversal or invalidation policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Relevance follows admitted input kinds and the resolved membership policy rather than an expanding list of fixture or output-directory names.
+ * @evidence contracts/common.md#meaningful-documentation Field paragraphs explain why irrelevant directories remain watched and why filtered membership, rather than a directory timestamp, is compared.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The path member preserves the absolute native directory spelling used
+ *   by one project's walk. Signatures describe its observed entry names and
+ *   kinds; native platform and compiler admission policy belong to that walk.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no work to
+ *   reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectDirectorySnapshot only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectDirectorySnapshot {
+    /** Absolute directory spelling used by the project walk. */
+    path: string;
+    /**
+     * Whether this directory's subtree currently contains an admitted regular
+     * file.
+     *
+     * An admitted directory with no such file is still walked and watched, so a
+     * source appearing in it later is noticed, but it takes no part in the
+     * membership comparison. That is what lets a bundler create its output
+     * directory and fill it without voiding a generation no compiler input
+     * touched, for any output directory rather than for a fixed list of names.
+     */
+    relevant: boolean;
+    /**
+     * Digest of admitted, possible immediate entries and their kinds. A child
+     * directory contributes only when its subtree currently has an admitted
+     * regular file; an unstable enumeration carries a failure marker instead.
+     *
+     * Deliberately not the directory's own metadata. A directory's stamp moves
+     * whenever _any_ entry is added or removed, including the ones the walk
+     * exists to ignore. Comparing filtered membership avoids invalidation from
+     * unrelated output-directory creation or writes.
+     */
+    signature: string;
+}

package/lib/core/transform/project/TtscProjectInputHashSnapshot.d.cts

@@ -0,0 +1,31 @@
+/**
+ * One project-walk hash set together with its completeness proof.
+ *
+ * @evidence contracts/common.md#principled-implementation The completeness flag carries the rejection evidence for partial admitted-file observations; consumers must check it. Slash-encoded identity keys are root-relative when contained and full addresses otherwise, describing the admitted walk rather than all compiler dependencies.
+ * @evidence contracts/common.md#clear-and-simple-design The container separates observation completeness from collected hashes without introducing another snapshot owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An unreadable input cannot disappear into an apparently complete successful snapshot merely because other file hashes were available.
+ * @evidence contracts/common.md#meaningful-documentation The native field comments identify the rejection requirement and hash-key encoding rather than restating their TypeScript types.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Hash keys carry native file identities encoded in the compiler's slash
+ *   protocol, root-relative when contained and full addresses otherwise.
+ *   The snapshot producer and supplied identity context own native root, link
+ *   and case interpretation; the container preserves their comparison boundary.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no work to
+ *   reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectInputHashSnapshot {
+    /**
+     * Whether every attempted directory and file was observed coherently;
+     * cache-key hosts must reject an incomplete set.
+     */
+    complete: boolean;
+    /** SHA-256 of admitted regular-file reads, keyed by slash-encoded identity. */
+    hashes: Record<string, string>;
+}

package/lib/core/transform/project/TtscProjectInputHashSnapshot.d.mts

@@ -0,0 +1,31 @@
+/**
+ * One project-walk hash set together with its completeness proof.
+ *
+ * @evidence contracts/common.md#principled-implementation The completeness flag carries the rejection evidence for partial admitted-file observations; consumers must check it. Slash-encoded identity keys are root-relative when contained and full addresses otherwise, describing the admitted walk rather than all compiler dependencies.
+ * @evidence contracts/common.md#clear-and-simple-design The container separates observation completeness from collected hashes without introducing another snapshot owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An unreadable input cannot disappear into an apparently complete successful snapshot merely because other file hashes were available.
+ * @evidence contracts/common.md#meaningful-documentation The native field comments identify the rejection requirement and hash-key encoding rather than restating their TypeScript types.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Hash keys carry native file identities encoded in the compiler's slash
+ *   protocol, root-relative when contained and full addresses otherwise.
+ *   The snapshot producer and supplied identity context own native root, link
+ *   and case interpretation; the container preserves their comparison boundary.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no work to
+ *   reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectInputHashSnapshot {
+    /**
+     * Whether every attempted directory and file was observed coherently;
+     * cache-key hosts must reject an incomplete set.
+     */
+    complete: boolean;
+    /** SHA-256 of admitted regular-file reads, keyed by slash-encoded identity. */
+    hashes: Record<string, string>;
+}

package/lib/core/transform/project/TtscProjectInputHashSnapshot.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One project-walk hash set together with its completeness proof.
+ *
+ * @evidence contracts/common.md#principled-implementation The completeness flag carries the rejection evidence for partial admitted-file observations; consumers must check it. Slash-encoded identity keys are root-relative when contained and full addresses otherwise, describing the admitted walk rather than all compiler dependencies.
+ * @evidence contracts/common.md#clear-and-simple-design The container separates observation completeness from collected hashes without introducing another snapshot owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An unreadable input cannot disappear into an apparently complete successful snapshot merely because other file hashes were available.
+ * @evidence contracts/common.md#meaningful-documentation The native field comments identify the rejection requirement and hash-key encoding rather than restating their TypeScript types.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Hash keys carry native file identities encoded in the compiler's slash
+ *   protocol, root-relative when contained and full addresses otherwise.
+ *   The snapshot producer and supplied identity context own native root, link
+ *   and case interpretation; the container preserves their comparison boundary.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no work to
+ *   reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectInputHashSnapshot only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectInputHashSnapshot {
+    /**
+     * Whether every attempted directory and file was observed coherently;
+     * cache-key hosts must reject an incomplete set.
+     */
+    complete: boolean;
+    /** SHA-256 of admitted regular-file reads, keyed by slash-encoded identity. */
+    hashes: Record<string, string>;
+}

package/lib/core/transform/project/TtscProjectWalkFailure.d.cts

@@ -0,0 +1,31 @@
+/**
+ * One project-walk observation that could not prove a coherent snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation A closed failure-kind union distinguishes metadata, enumeration and read failures while the lexical path names the exact observation that failed.
+ * @evidence contracts/common.md#clear-and-simple-design The value contains only the failed observation's kind and address; retry and generation decisions remain with the consuming proof owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failure kinds are structured observation outcomes rather than inferred message fragments or synthetic missing-file success.
+ * @evidence contracts/common.md#meaningful-documentation Field comments explain the observation categories and specify lexical absolute spelling, preserving the distinction from resolved identity.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The address preserves the walk's absolute native lexical spelling instead
+ *   of replacing it with a comparison key or protocol path. Producer outcomes
+ *   classify failed or changing native metadata, listings and file reads;
+ *   consumers retain those uncertainties without depending on OS error text.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectWalkFailure only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectWalkFailure only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectWalkFailure only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectWalkFailure {
+    /**
+     * How the observation failed: unreadable or changing metadata, a failed
+     * listing, or a file that failed or changed during its read.
+     */
+    kind: "directory-changed-during-walk" | "directory-metadata-unavailable" | "directory-read-failed" | "file-changed-during-read" | "file-read-failed";
+    /** Absolute lexical spelling observed by the walk. */
+    path: string;
+}

package/lib/core/transform/project/TtscProjectWalkFailure.d.mts

@@ -0,0 +1,31 @@
+/**
+ * One project-walk observation that could not prove a coherent snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation A closed failure-kind union distinguishes metadata, enumeration and read failures while the lexical path names the exact observation that failed.
+ * @evidence contracts/common.md#clear-and-simple-design The value contains only the failed observation's kind and address; retry and generation decisions remain with the consuming proof owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failure kinds are structured observation outcomes rather than inferred message fragments or synthetic missing-file success.
+ * @evidence contracts/common.md#meaningful-documentation Field comments explain the observation categories and specify lexical absolute spelling, preserving the distinction from resolved identity.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The address preserves the walk's absolute native lexical spelling instead
+ *   of replacing it with a comparison key or protocol path. Producer outcomes
+ *   classify failed or changing native metadata, listings and file reads;
+ *   consumers retain those uncertainties without depending on OS error text.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectWalkFailure only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectWalkFailure only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectWalkFailure only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectWalkFailure {
+    /**
+     * How the observation failed: unreadable or changing metadata, a failed
+     * listing, or a file that failed or changed during its read.
+     */
+    kind: "directory-changed-during-walk" | "directory-metadata-unavailable" | "directory-read-failed" | "file-changed-during-read" | "file-read-failed";
+    /** Absolute lexical spelling observed by the walk. */
+    path: string;
+}

package/lib/core/transform/project/TtscProjectWalkFailure.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One project-walk observation that could not prove a coherent snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation A closed failure-kind union distinguishes metadata, enumeration and read failures while the lexical path names the exact observation that failed.
+ * @evidence contracts/common.md#clear-and-simple-design The value contains only the failed observation's kind and address; retry and generation decisions remain with the consuming proof owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failure kinds are structured observation outcomes rather than inferred message fragments or synthetic missing-file success.
+ * @evidence contracts/common.md#meaningful-documentation Field comments explain the observation categories and specify lexical absolute spelling, preserving the distinction from resolved identity.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The address preserves the walk's absolute native lexical spelling instead
+ *   of replacing it with a comparison key or protocol path. Producer outcomes
+ *   classify failed or changing native metadata, listings and file reads;
+ *   consumers retain those uncertainties without depending on OS error text.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectWalkFailure only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectWalkFailure only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectWalkFailure only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectWalkFailure {
+    /**
+     * How the observation failed: unreadable or changing metadata, a failed
+     * listing, or a file that failed or changed during its read.
+     */
+    kind: "directory-changed-during-walk" | "directory-metadata-unavailable" | "directory-read-failed" | "file-changed-during-read" | "file-read-failed";
+    /** Absolute lexical spelling observed by the walk. */
+    path: string;
+}

package/lib/core/transform/project/collectExternalInputHashes.d.cts

@@ -0,0 +1,27 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
+ * readable file, a stable directory-kind digest for a directory candidate, and
+ * a stable `missing` marker otherwise. Keys use filesystem identity so
+ * equivalent spellings share one entry under the observed case/link policy,
+ * while the first observation retains the original path supplied by the
+ * compiler. The marker is state, not an error — a recorded input disappearing
+ * (or reappearing) must change the comparison exactly like a content edit.
+ * Unavailable content does not prove physical absence. The public core export
+ * supplies a physical-state dictionary; it does not preserve independent
+ * lexical predicates for every alias.
+ *
+ * @evidence contracts/common.md#principled-implementation One native identity context deduplicates addresses for this physical-state dictionary; the first spelling's read determines its value under a stable coherent view. Raw file bytes, observed directory kind and unavailable content remain distinct states, not per-alias predicate proofs.
+ * @evidence contracts/common.md#clear-and-simple-design A single loop delegates state hashing and identity rules to their existing owners, returning only the external snapshot dictionary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observations contribute an explicit state marker instead of disappearing into a partial snapshot that falsely matches an earlier generation.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain actual equivalence, first read spelling, unavailable-content state transitions and the public physical-dictionary boundary without inventing a current consumer.
+ * @evidence contracts/portability.md#os-neutral-implementation One context derived from the supplied native view applies actual directory case and link rules; case-sensitive spelling differences remain distinct and original addresses reach reads instead of globally lowercasing Windows paths.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function transfers a snapshot dictionary to its caller and owns no persistent state, native handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over all supplied paths resolves native identities before deduplication. Path/component/uncached ancestor and case observations, total unique readable bytes and failed-read kind probes drive work; result keys grow with unique identities while the call-local context also retains queried aliases and ancestors.
+ * @evidence contracts/performance.md#reuse-equivalent-work Equivalent native spellings share the same observation within this call; the context shares identity lookups, while fresh calls reobserve input state rather than persisting unvalidated content hashes.
+ */
+export declare function collectExternalInputHashes(
+/** Native spellings whose first observation per physical identity is retained. */
+paths: readonly string[], 
+/** Stable coherent native identity, read and kind view for this call. */
+filesystem?: TtscTransformFilesystemOperations): Record<string, string>;

package/lib/core/transform/project/collectExternalInputHashes.d.mts

@@ -0,0 +1,27 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
+ * readable file, a stable directory-kind digest for a directory candidate, and
+ * a stable `missing` marker otherwise. Keys use filesystem identity so
+ * equivalent spellings share one entry under the observed case/link policy,
+ * while the first observation retains the original path supplied by the
+ * compiler. The marker is state, not an error — a recorded input disappearing
+ * (or reappearing) must change the comparison exactly like a content edit.
+ * Unavailable content does not prove physical absence. The public core export
+ * supplies a physical-state dictionary; it does not preserve independent
+ * lexical predicates for every alias.
+ *
+ * @evidence contracts/common.md#principled-implementation One native identity context deduplicates addresses for this physical-state dictionary; the first spelling's read determines its value under a stable coherent view. Raw file bytes, observed directory kind and unavailable content remain distinct states, not per-alias predicate proofs.
+ * @evidence contracts/common.md#clear-and-simple-design A single loop delegates state hashing and identity rules to their existing owners, returning only the external snapshot dictionary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observations contribute an explicit state marker instead of disappearing into a partial snapshot that falsely matches an earlier generation.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain actual equivalence, first read spelling, unavailable-content state transitions and the public physical-dictionary boundary without inventing a current consumer.
+ * @evidence contracts/portability.md#os-neutral-implementation One context derived from the supplied native view applies actual directory case and link rules; case-sensitive spelling differences remain distinct and original addresses reach reads instead of globally lowercasing Windows paths.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function transfers a snapshot dictionary to its caller and owns no persistent state, native handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over all supplied paths resolves native identities before deduplication. Path/component/uncached ancestor and case observations, total unique readable bytes and failed-read kind probes drive work; result keys grow with unique identities while the call-local context also retains queried aliases and ancestors.
+ * @evidence contracts/performance.md#reuse-equivalent-work Equivalent native spellings share the same observation within this call; the context shares identity lookups, while fresh calls reobserve input state rather than persisting unvalidated content hashes.
+ */
+export declare function collectExternalInputHashes(
+/** Native spellings whose first observation per physical identity is retained. */
+paths: readonly string[], 
+/** Stable coherent native identity, read and kind view for this call. */
+filesystem?: TtscTransformFilesystemOperations): Record<string, string>;

package/lib/core/transform/project/collectExternalInputHashes.d.ts

@@ -0,0 +1,27 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
+ * readable file, a stable directory-kind digest for a directory candidate, and
+ * a stable `missing` marker otherwise. Keys use filesystem identity so
+ * equivalent spellings share one entry under the observed case/link policy,
+ * while the first observation retains the original path supplied by the
+ * compiler. The marker is state, not an error — a recorded input disappearing
+ * (or reappearing) must change the comparison exactly like a content edit.
+ * Unavailable content does not prove physical absence. The public core export
+ * supplies a physical-state dictionary; it does not preserve independent
+ * lexical predicates for every alias.
+ *
+ * @evidence contracts/common.md#principled-implementation One native identity context deduplicates addresses for this physical-state dictionary; the first spelling's read determines its value under a stable coherent view. Raw file bytes, observed directory kind and unavailable content remain distinct states, not per-alias predicate proofs.
+ * @evidence contracts/common.md#clear-and-simple-design A single loop delegates state hashing and identity rules to their existing owners, returning only the external snapshot dictionary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observations contribute an explicit state marker instead of disappearing into a partial snapshot that falsely matches an earlier generation.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain actual equivalence, first read spelling, unavailable-content state transitions and the public physical-dictionary boundary without inventing a current consumer.
+ * @evidence contracts/portability.md#os-neutral-implementation One context derived from the supplied native view applies actual directory case and link rules; case-sensitive spelling differences remain distinct and original addresses reach reads instead of globally lowercasing Windows paths.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function transfers a snapshot dictionary to its caller and owns no persistent state, native handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over all supplied paths resolves native identities before deduplication. Path/component/uncached ancestor and case observations, total unique readable bytes and failed-read kind probes drive work; result keys grow with unique identities while the call-local context also retains queried aliases and ancestors.
+ * @evidence contracts/performance.md#reuse-equivalent-work Equivalent native spellings share the same observation within this call; the context shares identity lookups, while fresh calls reobserve input state rather than persisting unvalidated content hashes.
+ */
+export declare function collectExternalInputHashes(
+/** Native spellings whose first observation per physical identity is retained. */
+paths: readonly string[], 
+/** Stable coherent native identity, read and kind view for this call. */
+filesystem?: TtscTransformFilesystemOperations): Record<string, string>;

package/lib/core/transform/project/collectExternalInputHashes.js

@@ -0,0 +1,49 @@
+'use strict';
+
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+var createHostPathIdentityContext = require('../filesystem/createHostPathIdentityContext.js');
+var pathIdentityKey = require('../filesystem/pathIdentityKey.js');
+var hostInputStateHash = require('../inputs/hostInputStateHash.js');
+var MISSING_INPUT_STATE = require('../validation/MISSING_INPUT_STATE.js');
+
+/**
+ * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
+ * readable file, a stable directory-kind digest for a directory candidate, and
+ * a stable `missing` marker otherwise. Keys use filesystem identity so
+ * equivalent spellings share one entry under the observed case/link policy,
+ * while the first observation retains the original path supplied by the
+ * compiler. The marker is state, not an error — a recorded input disappearing
+ * (or reappearing) must change the comparison exactly like a content edit.
+ * Unavailable content does not prove physical absence. The public core export
+ * supplies a physical-state dictionary; it does not preserve independent
+ * lexical predicates for every alias.
+ *
+ * @evidence contracts/common.md#principled-implementation One native identity context deduplicates addresses for this physical-state dictionary; the first spelling's read determines its value under a stable coherent view. Raw file bytes, observed directory kind and unavailable content remain distinct states, not per-alias predicate proofs.
+ * @evidence contracts/common.md#clear-and-simple-design A single loop delegates state hashing and identity rules to their existing owners, returning only the external snapshot dictionary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observations contribute an explicit state marker instead of disappearing into a partial snapshot that falsely matches an earlier generation.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain actual equivalence, first read spelling, unavailable-content state transitions and the public physical-dictionary boundary without inventing a current consumer.
+ * @evidence contracts/portability.md#os-neutral-implementation One context derived from the supplied native view applies actual directory case and link rules; case-sensitive spelling differences remain distinct and original addresses reach reads instead of globally lowercasing Windows paths.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function transfers a snapshot dictionary to its caller and owns no persistent state, native handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over all supplied paths resolves native identities before deduplication. Path/component/uncached ancestor and case observations, total unique readable bytes and failed-read kind probes drive work; result keys grow with unique identities while the call-local context also retains queried aliases and ancestors.
+ * @evidence contracts/performance.md#reuse-equivalent-work Equivalent native spellings share the same observation within this call; the context shares identity lookups, while fresh calls reobserve input state rather than persisting unvalidated content hashes.
+ */
+function collectExternalInputHashes(
+/** Native spellings whose first observation per physical identity is retained. */
+paths, 
+/** Stable coherent native identity, read and kind view for this call. */
+filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS) {
+    const hashes = {};
+    const identities = createHostPathIdentityContext.createHostPathIdentityContext(filesystem);
+    for (const file of paths) {
+        const identity = pathIdentityKey.pathIdentityKey(file, identities);
+        if (identity in hashes) {
+            continue;
+        }
+        hashes[identity] =
+            hostInputStateHash.hostInputStateHash(file, filesystem) ?? MISSING_INPUT_STATE.MISSING_INPUT_STATE;
+    }
+    return hashes;
+}
+
+exports.collectExternalInputHashes = collectExternalInputHashes;
+//# sourceMappingURL=collectExternalInputHashes.js.map

package/lib/core/transform/project/collectExternalInputHashes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectExternalInputHashes.js","sources":["../../../../src/core/transform/project/collectExternalInputHashes.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","createHostPathIdentityContext","pathIdentityKey","hostInputStateHash","MISSING_INPUT_STATE"],"mappings":";;;;;;;;AAOA;;;;;;;;;;;;;;;;;;;;AAoBG;SACa,0BAA0B;AACxC;AACA,KAAwB;AACxB;AACA,UAAA,GAAgDA,2DAA6B,EAAA;IAE7E,MAAM,MAAM,GAA2B,EAAE;AACzC,IAAA,MAAM,UAAU,GAAGC,2DAA6B,CAAC,UAAU,CAAC;AAC5D,IAAA,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;QACxB,MAAM,QAAQ,GAAGC,+BAAe,CAAC,IAAI,EAAE,UAAU,CAAC;AAClD,QAAA,IAAI,QAAQ,IAAI,MAAM,EAAE;YACtB;QACF;QACA,MAAM,CAAC,QAAQ,CAAC;AACd,YAAAC,qCAAkB,CAAC,IAAI,EAAE,UAAU,CAAC,IAAIC,uCAAmB;IAC/D;AACA,IAAA,OAAO,MAAM;AACf;;;;"}

package/lib/core/transform/project/collectExternalInputHashes.mjs

@@ -0,0 +1,47 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { createHostPathIdentityContext } from '../filesystem/createHostPathIdentityContext.mjs';
+import { pathIdentityKey } from '../filesystem/pathIdentityKey.mjs';
+import { hostInputStateHash } from '../inputs/hostInputStateHash.mjs';
+import { MISSING_INPUT_STATE } from '../validation/MISSING_INPUT_STATE.mjs';
+
+/**
+ * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
+ * readable file, a stable directory-kind digest for a directory candidate, and
+ * a stable `missing` marker otherwise. Keys use filesystem identity so
+ * equivalent spellings share one entry under the observed case/link policy,
+ * while the first observation retains the original path supplied by the
+ * compiler. The marker is state, not an error — a recorded input disappearing
+ * (or reappearing) must change the comparison exactly like a content edit.
+ * Unavailable content does not prove physical absence. The public core export
+ * supplies a physical-state dictionary; it does not preserve independent
+ * lexical predicates for every alias.
+ *
+ * @evidence contracts/common.md#principled-implementation One native identity context deduplicates addresses for this physical-state dictionary; the first spelling's read determines its value under a stable coherent view. Raw file bytes, observed directory kind and unavailable content remain distinct states, not per-alias predicate proofs.
+ * @evidence contracts/common.md#clear-and-simple-design A single loop delegates state hashing and identity rules to their existing owners, returning only the external snapshot dictionary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observations contribute an explicit state marker instead of disappearing into a partial snapshot that falsely matches an earlier generation.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain actual equivalence, first read spelling, unavailable-content state transitions and the public physical-dictionary boundary without inventing a current consumer.
+ * @evidence contracts/portability.md#os-neutral-implementation One context derived from the supplied native view applies actual directory case and link rules; case-sensitive spelling differences remain distinct and original addresses reach reads instead of globally lowercasing Windows paths.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function transfers a snapshot dictionary to its caller and owns no persistent state, native handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms One pass over all supplied paths resolves native identities before deduplication. Path/component/uncached ancestor and case observations, total unique readable bytes and failed-read kind probes drive work; result keys grow with unique identities while the call-local context also retains queried aliases and ancestors.
+ * @evidence contracts/performance.md#reuse-equivalent-work Equivalent native spellings share the same observation within this call; the context shares identity lookups, while fresh calls reobserve input state rather than persisting unvalidated content hashes.
+ */
+function collectExternalInputHashes(
+/** Native spellings whose first observation per physical identity is retained. */
+paths, 
+/** Stable coherent native identity, read and kind view for this call. */
+filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const hashes = {};
+    const identities = createHostPathIdentityContext(filesystem);
+    for (const file of paths) {
+        const identity = pathIdentityKey(file, identities);
+        if (identity in hashes) {
+            continue;
+        }
+        hashes[identity] =
+            hostInputStateHash(file, filesystem) ?? MISSING_INPUT_STATE;
+    }
+    return hashes;
+}
+
+export { collectExternalInputHashes };
+//# sourceMappingURL=collectExternalInputHashes.mjs.map

package/lib/core/transform/project/collectExternalInputHashes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectExternalInputHashes.mjs","sources":["../../../../src/core/transform/project/collectExternalInputHashes.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;AAOA;;;;;;;;;;;;;;;;;;;;AAoBG;SACa,0BAA0B;AACxC;AACA,KAAwB;AACxB;AACA,UAAA,GAAgD,6BAA6B,EAAA;IAE7E,MAAM,MAAM,GAA2B,EAAE;AACzC,IAAA,MAAM,UAAU,GAAG,6BAA6B,CAAC,UAAU,CAAC;AAC5D,IAAA,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;QACxB,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC;AAClD,QAAA,IAAI,QAAQ,IAAI,MAAM,EAAE;YACtB;QACF;QACA,MAAM,CAAC,QAAQ,CAAC;AACd,YAAA,kBAAkB,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,mBAAmB;IAC/D;AACA,IAAA,OAAO,MAAM;AACf;;;;"}

package/lib/core/transform/project/collectProjectInputHashSnapshot.d.cts

@@ -0,0 +1,29 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy.cjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+import type { TtscProjectInputHashSnapshot } from "./TtscProjectInputHashSnapshot.cjs";
+/**
+ * Hash admitted regular files and retain whether every attempted directory and
+ * selected file was observed coherently. Cache-key hosts must reject an
+ * incomplete set; this walk does not replace separate out-of-walk input proof.
+ *
+ * @evidence contracts/common.md#principled-implementation File-read and directory-enumeration completeness are jointly required before the hashes represent a reusable snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design The wrapper projects the detailed snapshot into the hash-plus-completeness shape needed by cache-key consumers rather than implementing another walk.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A readable subset cannot count as a complete program when enumeration or attribution failed.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explicitly requires cache-key hosts to reject incomplete observations, distinguishing this API from the hash-only convenience wrapper.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The selected root, membership policy, observing operations and native
+ *   identity context pass unchanged to the snapshot producer. Omitted context
+ *   uses host defaults; projection does not invent case/alias/backend policy.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Projection is fixed work after the required walk: directory enumeration,
+ *   admitted file reads/hashes and native identity/metadata observations scale
+ *   with selected entries, path text and content bytes. The producer's full
+ *   snapshot/witness storage is allocated even though this API returns two
+ *   fields; delegation does not make that computation constant.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function collectProjectInputHashSnapshot(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): TtscProjectInputHashSnapshot;