@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/inputs/preparePluginBuildEnvironments.js

@@ -0,0 +1,76 @@
+'use strict';
+
+var pluginSource = require('ttsc/plugin-source');
+var selectPluginSourceInputs = require('../envelope/selectPluginSourceInputs.js');
+var trackerProvesInputUnchanged = require('../validation/trackerProvesInputUnchanged.js');
+var pluginSourceHolds = require('./pluginSourceHolds.js');
+
+// A result's async owner records its execution responsibility even when native
+// preparation failed. Synchronous standalone clients keep their native API;
+// async proofs cannot silently fall back to it after an unavailable reading.
+const asyncResults = new WeakSet();
+/**
+ * Prepare actual plugin toolchain authority before synchronous input proofs.
+ * Cold Go/environment/SDK work stays off the host thread. A mismatch requests
+ * one fresh native environment reading; observation failure remains unavailable
+ * and the following admission or replay validator retains its failure policy. A
+ * resident generation can reuse its exact proven source state while healthy
+ * notifications and the still-qualified environment witness both hold. Native
+ * environment preparation remains mandatory; source events cannot prove it.
+ *
+ * @param cached Optional resident generation whose existing source-state and
+ *   environment witness may qualify source reuse. Other preparation owners
+ *   retain direct source comparison.
+ * @evidence contracts/common.md#principled-implementation Every reported plugin directory prepares its actual current environment. The same result's matching manifest state can share source proof only with a healthy exact-source tracker and the environment under which that tree was proven. Otherwise this operation compares source state once and a mismatch refreshes environment authority for the following owning validator to compare again; failed preparation cannot qualify an input.
+ * @evidence contracts/common.md#clear-and-simple-design One async boundary precedes existing synchronous generation, delivery and terminal proofs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observations stay unproved; reported binary state never substitutes for native environment preparation or source comparison.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies off-thread work, mismatch refresh and preserved downstream failure ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation The same native toolchain/environment reader and caller filesystem source digest qualify each directory without platform guesses.
+ * @evidence contracts/performance.md#efficient-algorithms The envelope selector builds its directory map once per result, and preparation visits each reported directory once. Environment requests build keys from effective variables and qualify native dependencies. A qualified source witness avoids enumeration; other source comparisons enumerate and sort files, check metadata and hash bytes when the digest cannot be reused. A mismatch requests one environment refresh rather than a second source comparison here.
+ * @evidence contracts/performance.md#reuse-equivalent-work The environment owner shares equivalent in-flight requests and still-qualified readings. Resident source proof is reused only for the exact result and manifest digest, unchanged qualified environment and currently healthy covered source notifications; absent, dirty, replaced or unavailable witnesses retain direct proof. No epoch or quiet watcher alone authorizes reuse, and subsequent admission still owns its current validation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This module records asynchronous execution ownership in a WeakSet before preparation, including failures, so disposed results are not retained. Requests and worker lifetimes remain with the environment owner; this sequential operation awaits each request and acquires no native observer or independent cancellation handle.
+ */
+async function preparePluginBuildEnvironments(result, filesystem, cached) {
+    asyncResults.add(result);
+    for (const [directory, state] of selectPluginSourceInputs.selectPluginSourceInputs(result)) {
+        try {
+            await pluginSource.PluginBuildEnvironmentReadings.prepare(directory);
+            const environment = pluginSource.PluginBuildEnvironmentReadings.cached(directory);
+            if (cached?.result === result &&
+                cached.hostInputValidation?.trees.get(directory) === state &&
+                environment !== undefined &&
+                cached.hostInputValidation.treeEnvironments?.get(directory) ===
+                    environment &&
+                trackerProvesInputUnchanged.trackerProvesInputUnchanged(cached.hostInputMutationTracker, directory))
+                continue;
+            if (!pluginSourceHolds.pluginSourceHolds(directory, state, filesystem, {
+                environment,
+            }))
+                await pluginSource.PluginBuildEnvironmentReadings.prepare(directory, true);
+        }
+        catch {
+            // Admission and terminal recovery interpret unavailable proof in their
+            // own domain; this boundary never upgrades it to a successful reading.
+        }
+    }
+}
+/**
+ * Whether this result's owner attempted asynchronous native preparation. This
+ * records execution ownership, never successful observation authority.
+ *
+ * @evidence contracts/common.md#principled-implementation Result identity distinguishes async-owned proof from a standalone synchronous observation; membership does not certify any environment reading.
+ * @evidence contracts/common.md#clear-and-simple-design One identity query selects which execution owner may prepare missing native authority.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed preparation also records async ownership, preventing an accidental cold synchronous fallback or fabricated successful proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates execution responsibility from reading validity.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Identity membership performs no native operation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The fixed identity query selects an existing execution policy; it chooses no traversal or processing strategy and performs no toolchain probe.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The query selects an execution policy, not a reusable native observation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The preparation operation owns weak identity registration; this query borrows that record and acquires or retains no additional resource.
+ */
+function usesPreparedPluginBuildEnvironments(result) {
+    return asyncResults.has(result);
+}
+
+exports.preparePluginBuildEnvironments = preparePluginBuildEnvironments;
+exports.usesPreparedPluginBuildEnvironments = usesPreparedPluginBuildEnvironments;
+//# sourceMappingURL=preparePluginBuildEnvironments.js.map

package/lib/core/transform/inputs/preparePluginBuildEnvironments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparePluginBuildEnvironments.js","sources":["../../../../src/core/transform/inputs/preparePluginBuildEnvironments.ts"],"sourcesContent":[null],"names":["selectPluginSourceInputs","PluginBuildEnvironmentReadings","trackerProvesInputUnchanged","pluginSourceHolds"],"mappings":";;;;;;;AAQA;AACA;AACA;AACA,MAAM,YAAY,GAAG,IAAI,OAAO,EAAU;AAE1C;;;;;;;;;;;;;;;;;;;;AAoBG;AACI,eAAe,8BAA8B,CAClD,MAA4C,EAC5C,UAA6C,EAC7C,MAAmC,EAAA;AAEnC,IAAA,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;AACxB,IAAA,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAIA,iDAAwB,CAAC,MAAM,CAAC,EAAE;AACjE,QAAA,IAAI;AACF,YAAA,MAAMC,2CAA8B,CAAC,OAAO,CAAC,SAAS,CAAC;YACvD,MAAM,WAAW,GAAGA,2CAA8B,CAAC,MAAM,CAAC,SAAS,CAAC;AACpE,YAAA,IACE,MAAM,EAAE,MAAM,KAAK,MAAM;gBACzB,MAAM,CAAC,mBAAmB,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,KAAK;AAC1D,gBAAA,WAAW,KAAK,SAAS;gBACzB,MAAM,CAAC,mBAAmB,CAAC,gBAAgB,EAAE,GAAG,CAAC,SAAS,CAAC;oBACzD,WAAW;AACb,gBAAAC,uDAA2B,CAAC,MAAM,CAAC,wBAAwB,EAAE,SAAS,CAAC;gBAEvE;YACF,IACE,CAACC,mCAAiB,CAAC,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE;gBAC/C,WAAW;aACZ,CAAC;gBAEF,MAAMF,2CAA8B,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;QACjE;AAAE,QAAA,MAAM;;;QAGR;IACF;AACF;AAEA;;;;;;;;;;;;AAYG;AACG,SAAU,mCAAmC,CACjD,MAA4C,EAAA;AAE5C,IAAA,OAAO,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;AACjC;;;;;"}

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

@@ -0,0 +1,73 @@
+import { PluginBuildEnvironmentReadings } from 'ttsc/plugin-source';
+import { selectPluginSourceInputs } from '../envelope/selectPluginSourceInputs.mjs';
+import { trackerProvesInputUnchanged } from '../validation/trackerProvesInputUnchanged.mjs';
+import { pluginSourceHolds } from './pluginSourceHolds.mjs';
+
+// A result's async owner records its execution responsibility even when native
+// preparation failed. Synchronous standalone clients keep their native API;
+// async proofs cannot silently fall back to it after an unavailable reading.
+const asyncResults = new WeakSet();
+/**
+ * Prepare actual plugin toolchain authority before synchronous input proofs.
+ * Cold Go/environment/SDK work stays off the host thread. A mismatch requests
+ * one fresh native environment reading; observation failure remains unavailable
+ * and the following admission or replay validator retains its failure policy. A
+ * resident generation can reuse its exact proven source state while healthy
+ * notifications and the still-qualified environment witness both hold. Native
+ * environment preparation remains mandatory; source events cannot prove it.
+ *
+ * @param cached Optional resident generation whose existing source-state and
+ *   environment witness may qualify source reuse. Other preparation owners
+ *   retain direct source comparison.
+ * @evidence contracts/common.md#principled-implementation Every reported plugin directory prepares its actual current environment. The same result's matching manifest state can share source proof only with a healthy exact-source tracker and the environment under which that tree was proven. Otherwise this operation compares source state once and a mismatch refreshes environment authority for the following owning validator to compare again; failed preparation cannot qualify an input.
+ * @evidence contracts/common.md#clear-and-simple-design One async boundary precedes existing synchronous generation, delivery and terminal proofs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observations stay unproved; reported binary state never substitutes for native environment preparation or source comparison.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies off-thread work, mismatch refresh and preserved downstream failure ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation The same native toolchain/environment reader and caller filesystem source digest qualify each directory without platform guesses.
+ * @evidence contracts/performance.md#efficient-algorithms The envelope selector builds its directory map once per result, and preparation visits each reported directory once. Environment requests build keys from effective variables and qualify native dependencies. A qualified source witness avoids enumeration; other source comparisons enumerate and sort files, check metadata and hash bytes when the digest cannot be reused. A mismatch requests one environment refresh rather than a second source comparison here.
+ * @evidence contracts/performance.md#reuse-equivalent-work The environment owner shares equivalent in-flight requests and still-qualified readings. Resident source proof is reused only for the exact result and manifest digest, unchanged qualified environment and currently healthy covered source notifications; absent, dirty, replaced or unavailable witnesses retain direct proof. No epoch or quiet watcher alone authorizes reuse, and subsequent admission still owns its current validation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This module records asynchronous execution ownership in a WeakSet before preparation, including failures, so disposed results are not retained. Requests and worker lifetimes remain with the environment owner; this sequential operation awaits each request and acquires no native observer or independent cancellation handle.
+ */
+async function preparePluginBuildEnvironments(result, filesystem, cached) {
+    asyncResults.add(result);
+    for (const [directory, state] of selectPluginSourceInputs(result)) {
+        try {
+            await PluginBuildEnvironmentReadings.prepare(directory);
+            const environment = PluginBuildEnvironmentReadings.cached(directory);
+            if (cached?.result === result &&
+                cached.hostInputValidation?.trees.get(directory) === state &&
+                environment !== undefined &&
+                cached.hostInputValidation.treeEnvironments?.get(directory) ===
+                    environment &&
+                trackerProvesInputUnchanged(cached.hostInputMutationTracker, directory))
+                continue;
+            if (!pluginSourceHolds(directory, state, filesystem, {
+                environment,
+            }))
+                await PluginBuildEnvironmentReadings.prepare(directory, true);
+        }
+        catch {
+            // Admission and terminal recovery interpret unavailable proof in their
+            // own domain; this boundary never upgrades it to a successful reading.
+        }
+    }
+}
+/**
+ * Whether this result's owner attempted asynchronous native preparation. This
+ * records execution ownership, never successful observation authority.
+ *
+ * @evidence contracts/common.md#principled-implementation Result identity distinguishes async-owned proof from a standalone synchronous observation; membership does not certify any environment reading.
+ * @evidence contracts/common.md#clear-and-simple-design One identity query selects which execution owner may prepare missing native authority.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed preparation also records async ownership, preventing an accidental cold synchronous fallback or fabricated successful proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates execution responsibility from reading validity.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Identity membership performs no native operation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The fixed identity query selects an existing execution policy; it chooses no traversal or processing strategy and performs no toolchain probe.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The query selects an execution policy, not a reusable native observation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The preparation operation owns weak identity registration; this query borrows that record and acquires or retains no additional resource.
+ */
+function usesPreparedPluginBuildEnvironments(result) {
+    return asyncResults.has(result);
+}
+
+export { preparePluginBuildEnvironments, usesPreparedPluginBuildEnvironments };
+//# sourceMappingURL=preparePluginBuildEnvironments.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preparePluginBuildEnvironments.mjs","sources":["../../../../src/core/transform/inputs/preparePluginBuildEnvironments.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAQA;AACA;AACA;AACA,MAAM,YAAY,GAAG,IAAI,OAAO,EAAU;AAE1C;;;;;;;;;;;;;;;;;;;;AAoBG;AACI,eAAe,8BAA8B,CAClD,MAA4C,EAC5C,UAA6C,EAC7C,MAAmC,EAAA;AAEnC,IAAA,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;AACxB,IAAA,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,wBAAwB,CAAC,MAAM,CAAC,EAAE;AACjE,QAAA,IAAI;AACF,YAAA,MAAM,8BAA8B,CAAC,OAAO,CAAC,SAAS,CAAC;YACvD,MAAM,WAAW,GAAG,8BAA8B,CAAC,MAAM,CAAC,SAAS,CAAC;AACpE,YAAA,IACE,MAAM,EAAE,MAAM,KAAK,MAAM;gBACzB,MAAM,CAAC,mBAAmB,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,KAAK;AAC1D,gBAAA,WAAW,KAAK,SAAS;gBACzB,MAAM,CAAC,mBAAmB,CAAC,gBAAgB,EAAE,GAAG,CAAC,SAAS,CAAC;oBACzD,WAAW;AACb,gBAAA,2BAA2B,CAAC,MAAM,CAAC,wBAAwB,EAAE,SAAS,CAAC;gBAEvE;YACF,IACE,CAAC,iBAAiB,CAAC,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE;gBAC/C,WAAW;aACZ,CAAC;gBAEF,MAAM,8BAA8B,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;QACjE;AAAE,QAAA,MAAM;;;QAGR;IACF;AACF;AAEA;;;;;;;;;;;;AAYG;AACG,SAAU,mCAAmC,CACjD,MAA4C,EAAA;AAE5C,IAAA,OAAO,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;AACjC;;;;"}

package/lib/core/transform/inputs/sameHostInputRealpath.d.cts

@@ -0,0 +1,20 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+/**
+ * Compare reported physical targets through the supplied filesystem identity
+ * context. Undefined recorded evidence never matches; two failed resolutions
+ * represented by null do match. Comparison does not rewrite delivered paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Absence, resolution failure and resolved identity are distinguished before comparing context-produced keys for two successful observations.
+ * @evidence contracts/common.md#clear-and-simple-design One shared identity context owns native equivalence; this adapter handles only optional-result states and key equality.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Realpath equality does not rely on blanket lowercase, removed separators or consumer-specific spelling exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states undefined and null meaning and separates comparison from rewriting, with a blank acknowledgment separator under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral comparison uses the context's native aliases and directory case policy rather than OS-name case rules; original resolver spelling remains intact.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   At most two context resolutions and key comparison process native path
+ *   components and text; uncached resolver observations remain part of this cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Both targets use the same supplied context's resolution memo. Its owner
+ *   controls the current observation lifetime; this predicate retains no verdict.
+ */
+export declare function sameHostInputRealpath(left: string | null | undefined, right: string | null, identities: FilesystemPathIdentityContext): boolean;

package/lib/core/transform/inputs/sameHostInputRealpath.d.mts

@@ -0,0 +1,20 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+/**
+ * Compare reported physical targets through the supplied filesystem identity
+ * context. Undefined recorded evidence never matches; two failed resolutions
+ * represented by null do match. Comparison does not rewrite delivered paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Absence, resolution failure and resolved identity are distinguished before comparing context-produced keys for two successful observations.
+ * @evidence contracts/common.md#clear-and-simple-design One shared identity context owns native equivalence; this adapter handles only optional-result states and key equality.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Realpath equality does not rely on blanket lowercase, removed separators or consumer-specific spelling exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states undefined and null meaning and separates comparison from rewriting, with a blank acknowledgment separator under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral comparison uses the context's native aliases and directory case policy rather than OS-name case rules; original resolver spelling remains intact.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   At most two context resolutions and key comparison process native path
+ *   components and text; uncached resolver observations remain part of this cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Both targets use the same supplied context's resolution memo. Its owner
+ *   controls the current observation lifetime; this predicate retains no verdict.
+ */
+export declare function sameHostInputRealpath(left: string | null | undefined, right: string | null, identities: FilesystemPathIdentityContext): boolean;

package/lib/core/transform/inputs/sameHostInputRealpath.d.ts

@@ -0,0 +1,20 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+/**
+ * Compare reported physical targets through the supplied filesystem identity
+ * context. Undefined recorded evidence never matches; two failed resolutions
+ * represented by null do match. Comparison does not rewrite delivered paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Absence, resolution failure and resolved identity are distinguished before comparing context-produced keys for two successful observations.
+ * @evidence contracts/common.md#clear-and-simple-design One shared identity context owns native equivalence; this adapter handles only optional-result states and key equality.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Realpath equality does not rely on blanket lowercase, removed separators or consumer-specific spelling exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states undefined and null meaning and separates comparison from rewriting, with a blank acknowledgment separator under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral comparison uses the context's native aliases and directory case policy rather than OS-name case rules; original resolver spelling remains intact.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   At most two context resolutions and key comparison process native path
+ *   components and text; uncached resolver observations remain part of this cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Both targets use the same supplied context's resolution memo. Its owner
+ *   controls the current observation lifetime; this predicate retains no verdict.
+ */
+export declare function sameHostInputRealpath(left: string | null | undefined, right: string | null, identities: FilesystemPathIdentityContext): boolean;

package/lib/core/transform/inputs/sameHostInputRealpath.js

@@ -0,0 +1,32 @@
+'use strict';
+
+var pathIdentityKey = require('../filesystem/pathIdentityKey.js');
+
+/**
+ * Compare reported physical targets through the supplied filesystem identity
+ * context. Undefined recorded evidence never matches; two failed resolutions
+ * represented by null do match. Comparison does not rewrite delivered paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Absence, resolution failure and resolved identity are distinguished before comparing context-produced keys for two successful observations.
+ * @evidence contracts/common.md#clear-and-simple-design One shared identity context owns native equivalence; this adapter handles only optional-result states and key equality.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Realpath equality does not rely on blanket lowercase, removed separators or consumer-specific spelling exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states undefined and null meaning and separates comparison from rewriting, with a blank acknowledgment separator under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral comparison uses the context's native aliases and directory case policy rather than OS-name case rules; original resolver spelling remains intact.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   At most two context resolutions and key comparison process native path
+ *   components and text; uncached resolver observations remain part of this cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Both targets use the same supplied context's resolution memo. Its owner
+ *   controls the current observation lifetime; this predicate retains no verdict.
+ */
+function sameHostInputRealpath(left, right, identities) {
+    if (left === undefined || (left === null) !== (right === null))
+        return false;
+    if (left === null || right === null)
+        return true;
+    return (pathIdentityKey.pathIdentityKey(left, identities) === pathIdentityKey.pathIdentityKey(right, identities));
+}
+
+exports.sameHostInputRealpath = sameHostInputRealpath;
+//# sourceMappingURL=sameHostInputRealpath.js.map

package/lib/core/transform/inputs/sameHostInputRealpath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sameHostInputRealpath.js","sources":["../../../../src/core/transform/inputs/sameHostInputRealpath.ts"],"sourcesContent":[null],"names":["pathIdentityKey"],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;AAiBG;SACa,qBAAqB,CACnC,IAA+B,EAC/B,KAAoB,EACpB,UAAyC,EAAA;AAEzC,IAAA,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,IAAI,CAAC;AAAE,QAAA,OAAO,KAAK;AAC5E,IAAA,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI;AAAE,QAAA,OAAO,IAAI;AAChD,IAAA,QACEA,+BAAe,CAAC,IAAI,EAAE,UAAU,CAAC,KAAKA,+BAAe,CAAC,KAAK,EAAE,UAAU,CAAC;AAE5E;;;;"}

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

@@ -0,0 +1,30 @@
+import { pathIdentityKey } from '../filesystem/pathIdentityKey.mjs';
+
+/**
+ * Compare reported physical targets through the supplied filesystem identity
+ * context. Undefined recorded evidence never matches; two failed resolutions
+ * represented by null do match. Comparison does not rewrite delivered paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Absence, resolution failure and resolved identity are distinguished before comparing context-produced keys for two successful observations.
+ * @evidence contracts/common.md#clear-and-simple-design One shared identity context owns native equivalence; this adapter handles only optional-result states and key equality.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Realpath equality does not rely on blanket lowercase, removed separators or consumer-specific spelling exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states undefined and null meaning and separates comparison from rewriting, with a blank acknowledgment separator under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral comparison uses the context's native aliases and directory case policy rather than OS-name case rules; original resolver spelling remains intact.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   At most two context resolutions and key comparison process native path
+ *   components and text; uncached resolver observations remain part of this cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Both targets use the same supplied context's resolution memo. Its owner
+ *   controls the current observation lifetime; this predicate retains no verdict.
+ */
+function sameHostInputRealpath(left, right, identities) {
+    if (left === undefined || (left === null) !== (right === null))
+        return false;
+    if (left === null || right === null)
+        return true;
+    return (pathIdentityKey(left, identities) === pathIdentityKey(right, identities));
+}
+
+export { sameHostInputRealpath };
+//# sourceMappingURL=sameHostInputRealpath.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sameHostInputRealpath.mjs","sources":["../../../../src/core/transform/inputs/sameHostInputRealpath.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;;;;;;AAiBG;SACa,qBAAqB,CACnC,IAA+B,EAC/B,KAAoB,EACpB,UAAyC,EAAA;AAEzC,IAAA,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,IAAI,CAAC;AAAE,QAAA,OAAO,KAAK;AAC5E,IAAA,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI;AAAE,QAAA,OAAO,IAAI;AAChD,IAAA,QACE,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC;AAE5E;;;;"}

package/lib/core/transform/inputs/validateGraphInputObservation.d.cts

@@ -0,0 +1,17 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * 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.
+ */
+export declare function validateGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem?: TtscTransformFilesystemOperations): string[];

package/lib/core/transform/inputs/validateGraphInputObservation.d.mts

@@ -0,0 +1,17 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.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.
+ */
+export declare function validateGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem?: TtscTransformFilesystemOperations): string[];

package/lib/core/transform/inputs/validateGraphInputObservation.d.ts

@@ -0,0 +1,17 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * 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.
+ */
+export declare function validateGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem?: TtscTransformFilesystemOperations): string[];

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

@@ -0,0 +1,30 @@
+'use strict';
+
+var normalizeGraphInputObservation = require('../envelope/normalizeGraphInputObservation.js');
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+var createHostPathIdentityContext = require('../filesystem/createHostPathIdentityContext.js');
+var graphInputObservationFailures = require('./graphInputObservationFailures.js');
+
+/**
+ * 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.DEFAULT_FILESYSTEM_OPERATIONS) {
+    const normalized = normalizeGraphInputObservation.normalizeGraphInputObservation(observation, filesystem.platform);
+    if (normalized === undefined)
+        return ["proof-conflict"];
+    return graphInputObservationFailures.graphInputObservationFailures(file, normalized, filesystem, createHostPathIdentityContext.createHostPathIdentityContext(filesystem));
+}
+
+exports.validateGraphInputObservation = validateGraphInputObservation;
+//# sourceMappingURL=validateGraphInputObservation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateGraphInputObservation.js","sources":["../../../../src/core/transform/inputs/validateGraphInputObservation.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","normalizeGraphInputObservation","graphInputObservationFailures","createHostPathIdentityContext"],"mappings":";;;;;;;AAQA;;;;;;;;;;;;;AAaG;AACG,SAAU,6BAA6B,CAC3C,IAAY,EACZ,WAA0D,EAC1D,aAAgDA,2DAA6B,EAAA;IAE7E,MAAM,UAAU,GAAGC,6DAA8B,CAC/C,WAAW,EACX,UAAU,CAAC,QAAQ,CACpB;IACD,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,CAAC,gBAAgB,CAAC;AACvD,IAAA,OAAOC,2DAA6B,CAClC,IAAI,EACJ,UAAU,EACV,UAAU,EACVC,2DAA6B,CAAC,UAAU,CAAC,CAC1C;AACH;;;;"}

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;
+}