@ttsc/unplugin 0.31.0 → 0.31.2

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

@@ -1,27 +1,40 @@
 import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
 import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
 /**
- * Prepare actual plugin toolchain authority before synchronous input proofs.
+ * 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 preparation remains mandatory; source events cannot prove it.
+ * 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.
+ *
+ * The project root reaches ttsc's environment worker, so that isolate proves
+ * the Go SDK and executables from the plugin cache's records instead of reading
+ * 135 MB of SDK once per bundler or runtime process (samchon/ttsc#1722).
  *
  * @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.
+ * @param projectRoot Project whose plugin cache holds those records; the
+ *   resident generation's own root when omitted.
+ * @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 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#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>;
+export declare function preparePluginBuildEnvironments(result: TtscCachedProjectTransform["result"], filesystem: TtscTransformFilesystemOperations, cached?: TtscCachedProjectTransform, projectRoot?: string | undefined): Promise<void>;
 /**
  * Whether this result's owner attempted asynchronous native preparation. This
  * records execution ownership, never successful observation authority.

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

@@ -10,32 +10,67 @@ var pluginSourceHolds = require('./pluginSourceHolds.js');
 // 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.
+ * 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 preparation remains mandatory; source events cannot prove it.
+ * 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.
+ *
+ * The project root reaches ttsc's environment worker, so that isolate proves
+ * the Go SDK and executables from the plugin cache's records instead of reading
+ * 135 MB of SDK once per bundler or runtime process (samchon/ttsc#1722).
  *
  * @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.
+ * @param projectRoot Project whose plugin cache holds those records; the
+ *   resident generation's own root when omitted.
+ * @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 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#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) {
+async function preparePluginBuildEnvironments(result, filesystem, cached, projectRoot = cached?.projectRoot) {
     asyncResults.add(result);
-    for (const [directory, state] of selectPluginSourceInputs.selectPluginSourceInputs(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, false, projectRoot);
+        }
+        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 {
-            await pluginSource.PluginBuildEnvironmentReadings.prepare(directory);
-            const environment = pluginSource.PluginBuildEnvironmentReadings.cached(directory);
+            const environment = environments.get(directory);
             if (cached?.result === result &&
                 cached.hostInputValidation?.trees.get(directory) === state &&
                 environment !== undefined &&
@@ -43,16 +78,22 @@ async function preparePluginBuildEnvironments(result, filesystem, cached) {
                     environment &&
                 trackerProvesInputUnchanged.trackerProvesInputUnchanged(cached.hostInputMutationTracker, directory))
                 continue;
-            if (!pluginSourceHolds.pluginSourceHolds(directory, state, filesystem, {
-                environment,
-            }))
-                await pluginSource.PluginBuildEnvironmentReadings.prepare(directory, true);
+            if (!pluginSourceHolds.pluginSourceHolds(directory, state, filesystem, { environment }, projectRoot))
+                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, projectRoot);
+        }
+        catch {
+            // Synchronous admission requalifies after this asynchronous window.
+        }
+    }
 }
 /**
  * Whether this result's owner attempted asynchronous native preparation. This

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

@@ -1 +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;;;;;"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCG;AACI,eAAe,8BAA8B,CAClD,MAA4C,EAC5C,UAA6C,EAC7C,MAAmC,EACnC,WAAA,GAAkC,MAAM,EAAE,WAAW,EAAA;AAErD,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;YACF,MAAMA,2CAA8B,CAAC,OAAO,CAC1C,SAAS,EACT,KAAK,EACL,WAAW,CACZ;QACH;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;AACF,YAAA,IACE,CAACC,mCAAiB,CAChB,SAAS,EACT,KAAK,EACL,UAAU,EACV,EAAE,WAAW,EAAE,EACf,WAAW,CACZ;AAED,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,CAC1C,SAAS,EACT,IAAI,EACJ,WAAW,CACZ;QACH;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

@@ -8,32 +8,67 @@ import { pluginSourceHolds } from './pluginSourceHolds.mjs';
 // 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.
+ * 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 preparation remains mandatory; source events cannot prove it.
+ * 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.
+ *
+ * The project root reaches ttsc's environment worker, so that isolate proves
+ * the Go SDK and executables from the plugin cache's records instead of reading
+ * 135 MB of SDK once per bundler or runtime process (samchon/ttsc#1722).
  *
  * @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.
+ * @param projectRoot Project whose plugin cache holds those records; the
+ *   resident generation's own root when omitted.
+ * @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 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#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) {
+async function preparePluginBuildEnvironments(result, filesystem, cached, projectRoot = cached?.projectRoot) {
     asyncResults.add(result);
-    for (const [directory, state] of selectPluginSourceInputs(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, false, projectRoot);
+        }
+        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 {
-            await PluginBuildEnvironmentReadings.prepare(directory);
-            const environment = PluginBuildEnvironmentReadings.cached(directory);
+            const environment = environments.get(directory);
             if (cached?.result === result &&
                 cached.hostInputValidation?.trees.get(directory) === state &&
                 environment !== undefined &&
@@ -41,16 +76,22 @@ async function preparePluginBuildEnvironments(result, filesystem, cached) {
                     environment &&
                 trackerProvesInputUnchanged(cached.hostInputMutationTracker, directory))
                 continue;
-            if (!pluginSourceHolds(directory, state, filesystem, {
-                environment,
-            }))
-                await PluginBuildEnvironmentReadings.prepare(directory, true);
+            if (!pluginSourceHolds(directory, state, filesystem, { environment }, projectRoot))
+                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, projectRoot);
+        }
+        catch {
+            // Synchronous admission requalifies after this asynchronous window.
+        }
+    }
 }
 /**
  * Whether this result's owner attempted asynchronous native preparation. This

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

@@ -1 +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;;;;"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCG;AACI,eAAe,8BAA8B,CAClD,MAA4C,EAC5C,UAA6C,EAC7C,MAAmC,EACnC,WAAA,GAAkC,MAAM,EAAE,WAAW,EAAA;AAErD,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;YACF,MAAM,8BAA8B,CAAC,OAAO,CAC1C,SAAS,EACT,KAAK,EACL,WAAW,CACZ;QACH;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;AACF,YAAA,IACE,CAAC,iBAAiB,CAChB,SAAS,EACT,KAAK,EACL,UAAU,EACV,EAAE,WAAW,EAAE,EACf,WAAW,CACZ;AAED,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,CAC1C,SAAS,EACT,IAAI,EACJ,WAAW,CACZ;QACH;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/tracker/broker/WatchBroker.d.cts

@@ -4,10 +4,11 @@ import type { WatchBrokerRegistration } from "./WatchBrokerRegistration.cjs";
  * The live state of the isolated watch process.
  *
  * The broker multiplexes every Windows and macOS watch of the process over one
- * IPC channel, a tracker's and an input observer's scope's alike. Registrations
- * and drains are counted so the channel is referenced only while a reply is
- * outstanding, and each registration keeps the sink its messages go to and the
- * spelling map that translates the child's canonical paths back to its own.
+ * ordered transport, a tracker's and an input observer's scope's alike. Windows
+ * uses the native helper's stdio; macOS uses Node IPC. Registrations and drains
+ * are counted so the channel is referenced only while a reply is outstanding,
+ * and each registration keeps the sink its messages go to and the spelling map
+ * that translates the child's canonical paths back to its own.
  *
  * @evidence contracts/common.md#principled-implementation
  *   Registration and request ids distinguish multiplexed owners; drain scopes
@@ -35,6 +36,15 @@ import type { WatchBrokerRegistration } from "./WatchBrokerRegistration.cjs";
 export interface WatchBroker {
     /** The isolated watch process; unreferenced whenever no reply is outstanding. */
     child: ChildProcess;
+    /**
+     * Native stdio transport on Windows; absent for the macOS IPC broker and
+     * explicit test transports.
+     */
+    transport?: {
+        send(message: unknown): boolean;
+        reference(active: boolean): void;
+        close(): void;
+    };
     /**
      * Round-trips awaiting the child's reply, by request id, each released with
      * whether the child answered it.

package/lib/core/transform/tracker/broker/WatchBroker.d.mts

@@ -4,10 +4,11 @@ import type { WatchBrokerRegistration } from "./WatchBrokerRegistration.mjs";
  * The live state of the isolated watch process.
  *
  * The broker multiplexes every Windows and macOS watch of the process over one
- * IPC channel, a tracker's and an input observer's scope's alike. Registrations
- * and drains are counted so the channel is referenced only while a reply is
- * outstanding, and each registration keeps the sink its messages go to and the
- * spelling map that translates the child's canonical paths back to its own.
+ * ordered transport, a tracker's and an input observer's scope's alike. Windows
+ * uses the native helper's stdio; macOS uses Node IPC. Registrations and drains
+ * are counted so the channel is referenced only while a reply is outstanding,
+ * and each registration keeps the sink its messages go to and the spelling map
+ * that translates the child's canonical paths back to its own.
  *
  * @evidence contracts/common.md#principled-implementation
  *   Registration and request ids distinguish multiplexed owners; drain scopes
@@ -35,6 +36,15 @@ import type { WatchBrokerRegistration } from "./WatchBrokerRegistration.mjs";
 export interface WatchBroker {
     /** The isolated watch process; unreferenced whenever no reply is outstanding. */
     child: ChildProcess;
+    /**
+     * Native stdio transport on Windows; absent for the macOS IPC broker and
+     * explicit test transports.
+     */
+    transport?: {
+        send(message: unknown): boolean;
+        reference(active: boolean): void;
+        close(): void;
+    };
     /**
      * Round-trips awaiting the child's reply, by request id, each released with
      * whether the child answered it.

package/lib/core/transform/tracker/broker/WatchBroker.d.ts

@@ -4,10 +4,11 @@ import type { WatchBrokerRegistration } from "./WatchBrokerRegistration";
  * The live state of the isolated watch process.
  *
  * The broker multiplexes every Windows and macOS watch of the process over one
- * IPC channel, a tracker's and an input observer's scope's alike. Registrations
- * and drains are counted so the channel is referenced only while a reply is
- * outstanding, and each registration keeps the sink its messages go to and the
- * spelling map that translates the child's canonical paths back to its own.
+ * ordered transport, a tracker's and an input observer's scope's alike. Windows
+ * uses the native helper's stdio; macOS uses Node IPC. Registrations and drains
+ * are counted so the channel is referenced only while a reply is outstanding,
+ * and each registration keeps the sink its messages go to and the spelling map
+ * that translates the child's canonical paths back to its own.
  *
  * @evidence contracts/common.md#principled-implementation
  *   Registration and request ids distinguish multiplexed owners; drain scopes
@@ -35,6 +36,15 @@ import type { WatchBrokerRegistration } from "./WatchBrokerRegistration";
 export interface WatchBroker {
     /** The isolated watch process; unreferenced whenever no reply is outstanding. */
     child: ChildProcess;
+    /**
+     * Native stdio transport on Windows; absent for the macOS IPC broker and
+     * explicit test transports.
+     */
+    transport?: {
+        send(message: unknown): boolean;
+        reference(active: boolean): void;
+        close(): void;
+    };
     /**
      * Round-trips awaiting the child's reply, by request id, each released with
      * whether the child answered it.

package/lib/core/transform/tracker/broker/WatchBrokerTransport.d.cts

@@ -0,0 +1,63 @@
+import type { WatchBroker } from "./WatchBroker.cjs";
+/**
+ * Common lifecycle seam for the native Windows stdio broker and macOS IPC.
+ *
+ * The transport owns framing and demand references only. Ordered native
+ * notifications and per-registration readiness remain backend responsibilities;
+ * a successful send cannot certify coverage or cache reuse.
+ *
+ * @evidence contracts/common.md#principled-implementation One transport seam preserves explicit failure and reference ownership for both supported broker backends.
+ * @evidence contracts/common.md#clear-and-simple-design Callers express send, demand and retirement through this namespace instead of duplicating platform checks or modifying a ChildProcess.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported child streams and IPC APIs are used without replacing runtime methods.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates transport completion from native watch authority.
+ * @evidence contracts/portability.md#os-neutral-implementation Native selection stays at broker startup; all tracker and observer consumers share these operations.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Member operations own their delegated cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The broker owner selects transport and sharing lifetime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This namespace itself retains no transport registry.
+ */
+export declare namespace WatchBrokerTransport {
+    /**
+     * Queue a message on the selected transport. False refuses delivery; true
+     * only means queued, with actual acknowledgment or failure still
+     * outstanding.
+     *
+     * @evidence contracts/common.md#principled-implementation Native and IPC transports preserve separate queue acceptance and observed backend replies.
+     * @evidence contracts/common.md#clear-and-simple-design One selection delegates framing to the startup-owned transport.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No queue result is upgraded into readiness or a native drain.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the limited meaning of the returned boolean.
+     * @evidence contracts/portability.md#os-neutral-implementation Explicit stdio capability takes precedence over optional IPC.
+     * @evidence contracts/performance.md#efficient-algorithms Transport selection is fixed work; JSON framing, message bytes and pipe backpressure belong to the selected sender.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Sending an effect does not own computation reuse.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The selected sender and request owner retain queued bytes and outstanding acknowledgment state.
+     */
+    function send(broker: WatchBroker, message: unknown): boolean;
+    /**
+     * Keep the selected reply channel live exactly while caller demand exists.
+     * Counts belong to registration/drain owners; native references are flags.
+     *
+     * @evidence contracts/common.md#principled-implementation Outstanding requests retain both process and reply channel, preventing host exit before acknowledgment.
+     * @evidence contracts/common.md#clear-and-simple-design One operation applies the caller's aggregated demand to either transport.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional Bun IPC methods are used as capabilities without installing replacements.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies count ownership and flag semantics.
+     * @evidence contracts/portability.md#os-neutral-implementation Optional IPC methods and a selected native pipe capability express runtime differences.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Reference toggling selects no data-processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effect owns no shared computation.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller supplies aggregate demand; removing the last demand unreferences process and reply channel without asserting native termination.
+     */
+    function reference(broker: WatchBroker, active: boolean): void;
+    /**
+     * End this broker's request stream. The last-registration owner separately
+     * attempts process termination; closing a channel is not proof of child
+     * exit.
+     *
+     * @evidence contracts/common.md#principled-implementation Channel retirement is distinct from process exit and native resource closure.
+     * @evidence contracts/common.md#clear-and-simple-design Startup-owned transport closes its request stream without platform checks in consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported end/disconnect operations preserve native ownership without synthetic exit acknowledgment.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the independent termination attempt and limited closure meaning.
+     * @evidence contracts/portability.md#os-neutral-implementation Selected stream closure and optional IPC disconnection keep platform details behind the transport seam.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Closing one channel selects no processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Retirement owns no computation reuse.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The selected transport ends its input; process kill and actual native cleanup remain the broker and backend's responsibilities.
+     */
+    function close(broker: WatchBroker): void;
+}

package/lib/core/transform/tracker/broker/WatchBrokerTransport.d.mts

@@ -0,0 +1,63 @@
+import type { WatchBroker } from "./WatchBroker.mjs";
+/**
+ * Common lifecycle seam for the native Windows stdio broker and macOS IPC.
+ *
+ * The transport owns framing and demand references only. Ordered native
+ * notifications and per-registration readiness remain backend responsibilities;
+ * a successful send cannot certify coverage or cache reuse.
+ *
+ * @evidence contracts/common.md#principled-implementation One transport seam preserves explicit failure and reference ownership for both supported broker backends.
+ * @evidence contracts/common.md#clear-and-simple-design Callers express send, demand and retirement through this namespace instead of duplicating platform checks or modifying a ChildProcess.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported child streams and IPC APIs are used without replacing runtime methods.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates transport completion from native watch authority.
+ * @evidence contracts/portability.md#os-neutral-implementation Native selection stays at broker startup; all tracker and observer consumers share these operations.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Member operations own their delegated cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The broker owner selects transport and sharing lifetime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This namespace itself retains no transport registry.
+ */
+export declare namespace WatchBrokerTransport {
+    /**
+     * Queue a message on the selected transport. False refuses delivery; true
+     * only means queued, with actual acknowledgment or failure still
+     * outstanding.
+     *
+     * @evidence contracts/common.md#principled-implementation Native and IPC transports preserve separate queue acceptance and observed backend replies.
+     * @evidence contracts/common.md#clear-and-simple-design One selection delegates framing to the startup-owned transport.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No queue result is upgraded into readiness or a native drain.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the limited meaning of the returned boolean.
+     * @evidence contracts/portability.md#os-neutral-implementation Explicit stdio capability takes precedence over optional IPC.
+     * @evidence contracts/performance.md#efficient-algorithms Transport selection is fixed work; JSON framing, message bytes and pipe backpressure belong to the selected sender.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Sending an effect does not own computation reuse.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The selected sender and request owner retain queued bytes and outstanding acknowledgment state.
+     */
+    function send(broker: WatchBroker, message: unknown): boolean;
+    /**
+     * Keep the selected reply channel live exactly while caller demand exists.
+     * Counts belong to registration/drain owners; native references are flags.
+     *
+     * @evidence contracts/common.md#principled-implementation Outstanding requests retain both process and reply channel, preventing host exit before acknowledgment.
+     * @evidence contracts/common.md#clear-and-simple-design One operation applies the caller's aggregated demand to either transport.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional Bun IPC methods are used as capabilities without installing replacements.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies count ownership and flag semantics.
+     * @evidence contracts/portability.md#os-neutral-implementation Optional IPC methods and a selected native pipe capability express runtime differences.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Reference toggling selects no data-processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effect owns no shared computation.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller supplies aggregate demand; removing the last demand unreferences process and reply channel without asserting native termination.
+     */
+    function reference(broker: WatchBroker, active: boolean): void;
+    /**
+     * End this broker's request stream. The last-registration owner separately
+     * attempts process termination; closing a channel is not proof of child
+     * exit.
+     *
+     * @evidence contracts/common.md#principled-implementation Channel retirement is distinct from process exit and native resource closure.
+     * @evidence contracts/common.md#clear-and-simple-design Startup-owned transport closes its request stream without platform checks in consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported end/disconnect operations preserve native ownership without synthetic exit acknowledgment.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the independent termination attempt and limited closure meaning.
+     * @evidence contracts/portability.md#os-neutral-implementation Selected stream closure and optional IPC disconnection keep platform details behind the transport seam.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Closing one channel selects no processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Retirement owns no computation reuse.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The selected transport ends its input; process kill and actual native cleanup remain the broker and backend's responsibilities.
+     */
+    function close(broker: WatchBroker): void;
+}

package/lib/core/transform/tracker/broker/WatchBrokerTransport.d.ts

@@ -0,0 +1,63 @@
+import type { WatchBroker } from "./WatchBroker";
+/**
+ * Common lifecycle seam for the native Windows stdio broker and macOS IPC.
+ *
+ * The transport owns framing and demand references only. Ordered native
+ * notifications and per-registration readiness remain backend responsibilities;
+ * a successful send cannot certify coverage or cache reuse.
+ *
+ * @evidence contracts/common.md#principled-implementation One transport seam preserves explicit failure and reference ownership for both supported broker backends.
+ * @evidence contracts/common.md#clear-and-simple-design Callers express send, demand and retirement through this namespace instead of duplicating platform checks or modifying a ChildProcess.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported child streams and IPC APIs are used without replacing runtime methods.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates transport completion from native watch authority.
+ * @evidence contracts/portability.md#os-neutral-implementation Native selection stays at broker startup; all tracker and observer consumers share these operations.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Member operations own their delegated cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The broker owner selects transport and sharing lifetime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This namespace itself retains no transport registry.
+ */
+export declare namespace WatchBrokerTransport {
+    /**
+     * Queue a message on the selected transport. False refuses delivery; true
+     * only means queued, with actual acknowledgment or failure still
+     * outstanding.
+     *
+     * @evidence contracts/common.md#principled-implementation Native and IPC transports preserve separate queue acceptance and observed backend replies.
+     * @evidence contracts/common.md#clear-and-simple-design One selection delegates framing to the startup-owned transport.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No queue result is upgraded into readiness or a native drain.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the limited meaning of the returned boolean.
+     * @evidence contracts/portability.md#os-neutral-implementation Explicit stdio capability takes precedence over optional IPC.
+     * @evidence contracts/performance.md#efficient-algorithms Transport selection is fixed work; JSON framing, message bytes and pipe backpressure belong to the selected sender.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Sending an effect does not own computation reuse.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The selected sender and request owner retain queued bytes and outstanding acknowledgment state.
+     */
+    function send(broker: WatchBroker, message: unknown): boolean;
+    /**
+     * Keep the selected reply channel live exactly while caller demand exists.
+     * Counts belong to registration/drain owners; native references are flags.
+     *
+     * @evidence contracts/common.md#principled-implementation Outstanding requests retain both process and reply channel, preventing host exit before acknowledgment.
+     * @evidence contracts/common.md#clear-and-simple-design One operation applies the caller's aggregated demand to either transport.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional Bun IPC methods are used as capabilities without installing replacements.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies count ownership and flag semantics.
+     * @evidence contracts/portability.md#os-neutral-implementation Optional IPC methods and a selected native pipe capability express runtime differences.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Reference toggling selects no data-processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effect owns no shared computation.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller supplies aggregate demand; removing the last demand unreferences process and reply channel without asserting native termination.
+     */
+    function reference(broker: WatchBroker, active: boolean): void;
+    /**
+     * End this broker's request stream. The last-registration owner separately
+     * attempts process termination; closing a channel is not proof of child
+     * exit.
+     *
+     * @evidence contracts/common.md#principled-implementation Channel retirement is distinct from process exit and native resource closure.
+     * @evidence contracts/common.md#clear-and-simple-design Startup-owned transport closes its request stream without platform checks in consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported end/disconnect operations preserve native ownership without synthetic exit acknowledgment.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the independent termination attempt and limited closure meaning.
+     * @evidence contracts/portability.md#os-neutral-implementation Selected stream closure and optional IPC disconnection keep platform details behind the transport seam.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Closing one channel selects no processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Retirement owns no computation reuse.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The selected transport ends its input; process kill and actual native cleanup remain the broker and backend's responsibilities.
+     */
+    function close(broker: WatchBroker): void;
+}