@ttsc/unplugin 0.30.4 → 0.31.1

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

@@ -0,0 +1,45 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.mjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Qualify 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 authority remains mandatory; source events cannot prove it.
+ *
+ * WARNING (#1712): yield before observing queued source changes, then qualify
+ * all current readings in one synchronous batch. Missing readings require an
+ * await and a fresh batch afterward. Source comparisons may request native
+ * refreshes; the caller must establish another current proof after those
+ * awaits. Never preserve a positive batch across an await or replay the SDK
+ * witness independently for every plugin and nested validator.
+ *
+ * @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 qualifies current environment authority; only missing readings require asynchronous preparation. 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 indexes directories once per result. Linear directory passes batch-qualify current readings, prepare missing authority, compare source state and refresh mismatches. Each synchronous batch hashes variables once and shares distinct native dependencies; any preparation await requires another current batch. 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.
+ */
+export declare function preparePluginBuildEnvironments(result: TtscCachedProjectTransform["result"], filesystem: TtscTransformFilesystemOperations, cached?: TtscCachedProjectTransform): Promise<void>;
+/**
+ * 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.
+ */
+export declare function usesPreparedPluginBuildEnvironments(result: TtscCachedProjectTransform["result"]): boolean;

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

@@ -0,0 +1,45 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Qualify 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 authority remains mandatory; source events cannot prove it.
+ *
+ * WARNING (#1712): yield before observing queued source changes, then qualify
+ * all current readings in one synchronous batch. Missing readings require an
+ * await and a fresh batch afterward. Source comparisons may request native
+ * refreshes; the caller must establish another current proof after those
+ * awaits. Never preserve a positive batch across an await or replay the SDK
+ * witness independently for every plugin and nested validator.
+ *
+ * @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 qualifies current environment authority; only missing readings require asynchronous preparation. 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 indexes directories once per result. Linear directory passes batch-qualify current readings, prepare missing authority, compare source state and refresh mismatches. Each synchronous batch hashes variables once and shares distinct native dependencies; any preparation await requires another current batch. 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.
+ */
+export declare function preparePluginBuildEnvironments(result: TtscCachedProjectTransform["result"], filesystem: TtscTransformFilesystemOperations, cached?: TtscCachedProjectTransform): Promise<void>;
+/**
+ * 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.
+ */
+export declare function usesPreparedPluginBuildEnvironments(result: TtscCachedProjectTransform["result"]): boolean;

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

@@ -0,0 +1,113 @@
+'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();
+/**
+ * Qualify 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 authority remains mandatory; source events cannot prove it.
+ *
+ * WARNING (#1712): yield before observing queued source changes, then qualify
+ * all current readings in one synchronous batch. Missing readings require an
+ * await and a fresh batch afterward. Source comparisons may request native
+ * refreshes; the caller must establish another current proof after those
+ * awaits. Never preserve a positive batch across an await or replay the SDK
+ * witness independently for every plugin and nested validator.
+ *
+ * @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 qualifies current environment authority; only missing readings require asynchronous preparation. 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 indexes directories once per result. Linear directory passes batch-qualify current readings, prepare missing authority, compare source state and refresh mismatches. Each synchronous batch hashes variables once and shares distinct native dependencies; any preparation await requires another current batch. 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);
+    const sources = selectPluginSourceInputs.selectPluginSourceInputs(result);
+    // Preserve the async preparation boundary even for warm environments.
+    // Events queued by the caller before awaiting preparation must participate
+    // in the source witness below. Observe the batch after this yield, never
+    // carry a positive environment observation across it (#1712).
+    await Promise.resolve();
+    const current = pluginSource.PluginBuildEnvironmentReadings.cachedAll(sources.keys());
+    let awaited = false;
+    for (const directory of sources.keys()) {
+        if (current.get(directory) !== undefined)
+            continue;
+        awaited = true;
+        try {
+            await pluginSource.PluginBuildEnvironmentReadings.prepare(directory);
+        }
+        catch {
+            // Keep unavailable authority for admission rather than cold fallback.
+        }
+    }
+    const environments = awaited
+        ? pluginSource.PluginBuildEnvironmentReadings.cachedAll(sources.keys())
+        : current;
+    const refresh = [];
+    for (const [directory, state] of sources) {
+        try {
+            const environment = environments.get(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,
+            }))
+                refresh.push(directory);
+        }
+        catch {
+            // Admission and terminal recovery interpret unavailable proof in their
+            // own domain; this boundary never upgrades it to a successful reading.
+        }
+    }
+    for (const directory of refresh) {
+        try {
+            await pluginSource.PluginBuildEnvironmentReadings.prepare(directory, true);
+        }
+        catch {
+            // Synchronous admission requalifies after this asynchronous window.
+        }
+    }
+}
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACI,eAAe,8BAA8B,CAClD,MAA4C,EAC5C,UAA6C,EAC7C,MAAmC,EAAA;AAEnC,IAAA,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;AACxB,IAAA,MAAM,OAAO,GAAGA,iDAAwB,CAAC,MAAM,CAAC;;;;;AAKhD,IAAA,MAAM,OAAO,CAAC,OAAO,EAAE;IACvB,MAAM,OAAO,GAAGC,2CAA8B,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACxE,IAAI,OAAO,GAAG,KAAK;IACnB,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE;AACtC,QAAA,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,SAAS;YAAE;QAC1C,OAAO,GAAG,IAAI;AACd,QAAA,IAAI;AACF,YAAA,MAAMA,2CAA8B,CAAC,OAAO,CAAC,SAAS,CAAC;QACzD;AAAE,QAAA,MAAM;;QAER;IACF;IACA,MAAM,YAAY,GAAG;UACjBA,2CAA8B,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE;UACvD,OAAO;IACX,MAAM,OAAO,GAAa,EAAE;IAC5B,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE;AACxC,QAAA,IAAI;YACF,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC;AAC/C,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;AAEF,gBAAA,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;QAC3B;AAAE,QAAA,MAAM;;;QAGR;IACF;AACA,IAAA,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE;AAC/B,QAAA,IAAI;YACF,MAAMF,2CAA8B,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;QAC/D;AAAE,QAAA,MAAM;;QAER;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,110 @@
+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();
+/**
+ * Qualify 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 authority remains mandatory; source events cannot prove it.
+ *
+ * WARNING (#1712): yield before observing queued source changes, then qualify
+ * all current readings in one synchronous batch. Missing readings require an
+ * await and a fresh batch afterward. Source comparisons may request native
+ * refreshes; the caller must establish another current proof after those
+ * awaits. Never preserve a positive batch across an await or replay the SDK
+ * witness independently for every plugin and nested validator.
+ *
+ * @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 qualifies current environment authority; only missing readings require asynchronous preparation. 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 indexes directories once per result. Linear directory passes batch-qualify current readings, prepare missing authority, compare source state and refresh mismatches. Each synchronous batch hashes variables once and shares distinct native dependencies; any preparation await requires another current batch. 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);
+    const sources = selectPluginSourceInputs(result);
+    // Preserve the async preparation boundary even for warm environments.
+    // Events queued by the caller before awaiting preparation must participate
+    // in the source witness below. Observe the batch after this yield, never
+    // carry a positive environment observation across it (#1712).
+    await Promise.resolve();
+    const current = PluginBuildEnvironmentReadings.cachedAll(sources.keys());
+    let awaited = false;
+    for (const directory of sources.keys()) {
+        if (current.get(directory) !== undefined)
+            continue;
+        awaited = true;
+        try {
+            await PluginBuildEnvironmentReadings.prepare(directory);
+        }
+        catch {
+            // Keep unavailable authority for admission rather than cold fallback.
+        }
+    }
+    const environments = awaited
+        ? PluginBuildEnvironmentReadings.cachedAll(sources.keys())
+        : current;
+    const refresh = [];
+    for (const [directory, state] of sources) {
+        try {
+            const environment = environments.get(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,
+            }))
+                refresh.push(directory);
+        }
+        catch {
+            // Admission and terminal recovery interpret unavailable proof in their
+            // own domain; this boundary never upgrades it to a successful reading.
+        }
+    }
+    for (const directory of refresh) {
+        try {
+            await PluginBuildEnvironmentReadings.prepare(directory, true);
+        }
+        catch {
+            // Synchronous admission requalifies after this asynchronous window.
+        }
+    }
+}
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACI,eAAe,8BAA8B,CAClD,MAA4C,EAC5C,UAA6C,EAC7C,MAAmC,EAAA;AAEnC,IAAA,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;AACxB,IAAA,MAAM,OAAO,GAAG,wBAAwB,CAAC,MAAM,CAAC;;;;;AAKhD,IAAA,MAAM,OAAO,CAAC,OAAO,EAAE;IACvB,MAAM,OAAO,GAAG,8BAA8B,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACxE,IAAI,OAAO,GAAG,KAAK;IACnB,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE;AACtC,QAAA,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,SAAS;YAAE;QAC1C,OAAO,GAAG,IAAI;AACd,QAAA,IAAI;AACF,YAAA,MAAM,8BAA8B,CAAC,OAAO,CAAC,SAAS,CAAC;QACzD;AAAE,QAAA,MAAM;;QAER;IACF;IACA,MAAM,YAAY,GAAG;UACjB,8BAA8B,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE;UACvD,OAAO;IACX,MAAM,OAAO,GAAa,EAAE;IAC5B,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE;AACxC,QAAA,IAAI;YACF,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC;AAC/C,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;AAEF,gBAAA,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;QAC3B;AAAE,QAAA,MAAM;;;QAGR;IACF;AACA,IAAA,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE;AAC/B,QAAA,IAAI;YACF,MAAM,8BAA8B,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;QAC/D;AAAE,QAAA,MAAM;;QAER;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;;;;"}