@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/generation/releaseCaptureResources.js

@@ -0,0 +1,93 @@
+'use strict';
+
+var disposeFilesystemClockReference = require('../clock/disposeFilesystemClockReference.js');
+var removeCaptureScratch = require('./removeCaptureScratch.js');
+
+/**
+ * Finish local capture cleanup before admitted resources can leave its owner.
+ *
+ * Independent untransferred trackers, scratch storage and the clock reference
+ * are attempted in their established finally order. A cleanup failure prevents
+ * transfer: waiting retained trackers and the retained reference are then also
+ * released. Secondary retained-close failures do not replace that cleanup
+ * failure, and an already failed capture keeps its original exception.
+ *
+ * The caller releases its shared claim first and registers the returned clock
+ * ownership only after this operation succeeds. Native close/removal failures
+ * can leave underlying resources; attempting every owner does not prove
+ * release.
+ *
+ * @evidence contracts/common.md#principled-implementation Nested finally attempts all unretained resources even after a tracker close throws. Failed local cleanup rolls back every waiting retained owner; the existing capture-error flag controls whether cleanup may replace the earlier exception.
+ * @evidence contracts/common.md#clear-and-simple-design One effectful release operation owns local cleanup and failed-transfer rollback; acquisition, retention admission, shared claim release and final clock registration remain with capture.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Uses the actual tracker close capabilities and native scratch/probe removers without test-only callbacks or fabricated release receipts. Cleanup failure cannot return a transferable generation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states cleanup order, error precedence, transfer ownership and the limits of native release attempts; props document individual retained owners.
+ * @evidence contracts/portability.md#os-neutral-implementation Invokes supplied native tracker close capabilities and shared native-path scratch/reference cleanup. No OS label guarantees watcher closure or removal of busy and permission-denied storage.
+ * @evidence contracts/performance.md#efficient-algorithms At most three local and three retained tracker close calls are attempted, plus scratch removal and clock disposal. Delegated work follows each tracker's watcher population and scratch descendants/native retries; fixed owner count does not bound native IO duration or resource bytes.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cleanup effects apply to this capture's owners; there is no reusable calculation or cross-capture cleanup cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Successful cleanup leaves only admitted owners for caller transfer. Failed cleanup attempts every waiting retained owner before rejecting or preserving the capture error. No retry task or history is stored here; native failures can leave watchers or storage after ownership cleanup.
+ */
+async function releaseCaptureResources(props) {
+    let cleanupFailed = false;
+    let cleanupFailure;
+    try {
+        try {
+            if (!props.retainProject && props.project !== undefined) {
+                props.project.close();
+            }
+        }
+        finally {
+            try {
+                if (!props.retainHost && props.host !== undefined) {
+                    props.host.close();
+                }
+            }
+            finally {
+                try {
+                    if (!props.retainCandidate && props.candidate !== undefined) {
+                        props.candidate.close();
+                    }
+                }
+                finally {
+                    try {
+                        await removeCaptureScratch.removeCaptureScratch(props.scratchDirectory);
+                    }
+                    finally {
+                        if (!props.retainClockReference &&
+                            props.clockReferenceDirectory !== undefined) {
+                            disposeFilesystemClockReference.disposeFilesystemClockReference(props.clockReferenceDirectory);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        cleanupFailed = true;
+        cleanupFailure = error;
+    }
+    if (cleanupFailed) {
+        // No generation can transfer after its local cleanup has failed. Preserve
+        // the selected cleanup failure while attempting every retained owner.
+        for (const retained of [
+            props.retainProject ? props.project : undefined,
+            props.retainHost ? props.host : undefined,
+            props.retainCandidate ? props.candidate : undefined,
+        ]) {
+            try {
+                retained?.close();
+            }
+            catch {
+                // Continue attempting independent generation-owned resources.
+            }
+        }
+        if (props.retainClockReference &&
+            props.clockReferenceDirectory !== undefined) {
+            disposeFilesystemClockReference.disposeFilesystemClockReference(props.clockReferenceDirectory);
+        }
+        if (!props.captureFailed)
+            throw cleanupFailure;
+    }
+}
+
+exports.releaseCaptureResources = releaseCaptureResources;
+//# sourceMappingURL=releaseCaptureResources.js.map

package/lib/core/transform/generation/releaseCaptureResources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"releaseCaptureResources.js","sources":["../../../../src/core/transform/generation/releaseCaptureResources.ts"],"sourcesContent":[null],"names":["removeCaptureScratch","disposeFilesystemClockReference"],"mappings":";;;;;AAIA;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACI,eAAe,uBAAuB,CAAC,KA8B7C,EAAA;IACC,IAAI,aAAa,GAAG,KAAK;AACzB,IAAA,IAAI,cAAuB;AAC3B,IAAA,IAAI;AACF,QAAA,IAAI;YACF,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE;AACvD,gBAAA,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE;YACvB;QACF;gBAAU;AACR,YAAA,IAAI;gBACF,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE;AACjD,oBAAA,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE;gBACpB;YACF;oBAAU;AACR,gBAAA,IAAI;oBACF,IAAI,CAAC,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE;AAC3D,wBAAA,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE;oBACzB;gBACF;wBAAU;AACR,oBAAA,IAAI;AACF,wBAAA,MAAMA,yCAAoB,CAAC,KAAK,CAAC,gBAAgB,CAAC;oBACpD;4BAAU;wBACR,IACE,CAAC,KAAK,CAAC,oBAAoB;AAC3B,4BAAA,KAAK,CAAC,uBAAuB,KAAK,SAAS,EAC3C;AACA,4BAAAC,+DAA+B,CAAC,KAAK,CAAC,uBAAuB,CAAC;wBAChE;oBACF;gBACF;YACF;QACF;IACF;IAAE,OAAO,KAAK,EAAE;QACd,aAAa,GAAG,IAAI;QACpB,cAAc,GAAG,KAAK;IACxB;IACA,IAAI,aAAa,EAAE;;;QAGjB,KAAK,MAAM,QAAQ,IAAI;YACrB,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,OAAO,GAAG,SAAS;YAC/C,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,IAAI,GAAG,SAAS;YACzC,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,SAAS,GAAG,SAAS;AACpD,SAAA,EAAE;AACD,YAAA,IAAI;gBACF,QAAQ,EAAE,KAAK,EAAE;YACnB;AAAE,YAAA,MAAM;;YAER;QACF;QACA,IACE,KAAK,CAAC,oBAAoB;AAC1B,YAAA,KAAK,CAAC,uBAAuB,KAAK,SAAS,EAC3C;AACA,YAAAA,+DAA+B,CAAC,KAAK,CAAC,uBAAuB,CAAC;QAChE;QACA,IAAI,CAAC,KAAK,CAAC,aAAa;AAAE,YAAA,MAAM,cAAc;IAChD;AACF;;;;"}

package/lib/core/transform/generation/releaseCaptureResources.mjs

@@ -0,0 +1,91 @@
+import { disposeFilesystemClockReference } from '../clock/disposeFilesystemClockReference.mjs';
+import { removeCaptureScratch } from './removeCaptureScratch.mjs';
+
+/**
+ * Finish local capture cleanup before admitted resources can leave its owner.
+ *
+ * Independent untransferred trackers, scratch storage and the clock reference
+ * are attempted in their established finally order. A cleanup failure prevents
+ * transfer: waiting retained trackers and the retained reference are then also
+ * released. Secondary retained-close failures do not replace that cleanup
+ * failure, and an already failed capture keeps its original exception.
+ *
+ * The caller releases its shared claim first and registers the returned clock
+ * ownership only after this operation succeeds. Native close/removal failures
+ * can leave underlying resources; attempting every owner does not prove
+ * release.
+ *
+ * @evidence contracts/common.md#principled-implementation Nested finally attempts all unretained resources even after a tracker close throws. Failed local cleanup rolls back every waiting retained owner; the existing capture-error flag controls whether cleanup may replace the earlier exception.
+ * @evidence contracts/common.md#clear-and-simple-design One effectful release operation owns local cleanup and failed-transfer rollback; acquisition, retention admission, shared claim release and final clock registration remain with capture.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Uses the actual tracker close capabilities and native scratch/probe removers without test-only callbacks or fabricated release receipts. Cleanup failure cannot return a transferable generation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states cleanup order, error precedence, transfer ownership and the limits of native release attempts; props document individual retained owners.
+ * @evidence contracts/portability.md#os-neutral-implementation Invokes supplied native tracker close capabilities and shared native-path scratch/reference cleanup. No OS label guarantees watcher closure or removal of busy and permission-denied storage.
+ * @evidence contracts/performance.md#efficient-algorithms At most three local and three retained tracker close calls are attempted, plus scratch removal and clock disposal. Delegated work follows each tracker's watcher population and scratch descendants/native retries; fixed owner count does not bound native IO duration or resource bytes.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cleanup effects apply to this capture's owners; there is no reusable calculation or cross-capture cleanup cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Successful cleanup leaves only admitted owners for caller transfer. Failed cleanup attempts every waiting retained owner before rejecting or preserving the capture error. No retry task or history is stored here; native failures can leave watchers or storage after ownership cleanup.
+ */
+async function releaseCaptureResources(props) {
+    let cleanupFailed = false;
+    let cleanupFailure;
+    try {
+        try {
+            if (!props.retainProject && props.project !== undefined) {
+                props.project.close();
+            }
+        }
+        finally {
+            try {
+                if (!props.retainHost && props.host !== undefined) {
+                    props.host.close();
+                }
+            }
+            finally {
+                try {
+                    if (!props.retainCandidate && props.candidate !== undefined) {
+                        props.candidate.close();
+                    }
+                }
+                finally {
+                    try {
+                        await removeCaptureScratch(props.scratchDirectory);
+                    }
+                    finally {
+                        if (!props.retainClockReference &&
+                            props.clockReferenceDirectory !== undefined) {
+                            disposeFilesystemClockReference(props.clockReferenceDirectory);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        cleanupFailed = true;
+        cleanupFailure = error;
+    }
+    if (cleanupFailed) {
+        // No generation can transfer after its local cleanup has failed. Preserve
+        // the selected cleanup failure while attempting every retained owner.
+        for (const retained of [
+            props.retainProject ? props.project : undefined,
+            props.retainHost ? props.host : undefined,
+            props.retainCandidate ? props.candidate : undefined,
+        ]) {
+            try {
+                retained?.close();
+            }
+            catch {
+                // Continue attempting independent generation-owned resources.
+            }
+        }
+        if (props.retainClockReference &&
+            props.clockReferenceDirectory !== undefined) {
+            disposeFilesystemClockReference(props.clockReferenceDirectory);
+        }
+        if (!props.captureFailed)
+            throw cleanupFailure;
+    }
+}
+
+export { releaseCaptureResources };
+//# sourceMappingURL=releaseCaptureResources.mjs.map

package/lib/core/transform/generation/releaseCaptureResources.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"releaseCaptureResources.mjs","sources":["../../../../src/core/transform/generation/releaseCaptureResources.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACI,eAAe,uBAAuB,CAAC,KA8B7C,EAAA;IACC,IAAI,aAAa,GAAG,KAAK;AACzB,IAAA,IAAI,cAAuB;AAC3B,IAAA,IAAI;AACF,QAAA,IAAI;YACF,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE;AACvD,gBAAA,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE;YACvB;QACF;gBAAU;AACR,YAAA,IAAI;gBACF,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE;AACjD,oBAAA,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE;gBACpB;YACF;oBAAU;AACR,gBAAA,IAAI;oBACF,IAAI,CAAC,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE;AAC3D,wBAAA,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE;oBACzB;gBACF;wBAAU;AACR,oBAAA,IAAI;AACF,wBAAA,MAAM,oBAAoB,CAAC,KAAK,CAAC,gBAAgB,CAAC;oBACpD;4BAAU;wBACR,IACE,CAAC,KAAK,CAAC,oBAAoB;AAC3B,4BAAA,KAAK,CAAC,uBAAuB,KAAK,SAAS,EAC3C;AACA,4BAAA,+BAA+B,CAAC,KAAK,CAAC,uBAAuB,CAAC;wBAChE;oBACF;gBACF;YACF;QACF;IACF;IAAE,OAAO,KAAK,EAAE;QACd,aAAa,GAAG,IAAI;QACpB,cAAc,GAAG,KAAK;IACxB;IACA,IAAI,aAAa,EAAE;;;QAGjB,KAAK,MAAM,QAAQ,IAAI;YACrB,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,OAAO,GAAG,SAAS;YAC/C,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,IAAI,GAAG,SAAS;YACzC,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,SAAS,GAAG,SAAS;AACpD,SAAA,EAAE;AACD,YAAA,IAAI;gBACF,QAAQ,EAAE,KAAK,EAAE;YACnB;AAAE,YAAA,MAAM;;YAER;QACF;QACA,IACE,KAAK,CAAC,oBAAoB;AAC1B,YAAA,KAAK,CAAC,uBAAuB,KAAK,SAAS,EAC3C;AACA,YAAA,+BAA+B,CAAC,KAAK,CAAC,uBAAuB,CAAC;QAChE;QACA,IAAI,CAAC,KAAK,CAAC,aAAa;AAAE,YAAA,MAAM,cAAc;IAChD;AACF;;;;"}

package/lib/core/transform/generation/removeCaptureScratch.d.cts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+/**
+ * Remove the scratch directory of one whole-project capture, retrying while a
+ * process still holds it.
+ *
+ * Windows refuses to remove a directory a process holds, its working directory
+ * or a file an indexer or a just-exiting plugin child has open, and the refusal
+ * can end once the holder lets go. The asynchronous operation avoids blocking
+ * the event loop during native removal and retry delays; synchronous removal
+ * also supports recursive retry options. Node retries supported busy/resource/
+ * permission errors with linear backoff, increasing delay by 100 ms per try,
+ * with maxRetries=10. A failure that outlasts the policy is a real failure and
+ * propagates to the caller, which decides whether it may replace an earlier
+ * error.
+ *
+ * The removal operation is a parameter so a caller can observe the retry
+ * request without a real locked directory. It must behave as `fs.promises.rm`
+ * does: resolve once the directory is gone, reject with the native error
+ * otherwise.
+ *
+ * @param directory The adapter-owned scratch directory the capture created.
+ * @param remove The removal operation; the native one by default.
+ * @evidence contracts/common.md#principled-implementation An asynchronous recursive removal with Node's retry options is the supported way to outlast a transient Windows hold, while a persistent failure is propagated instead of being reported as removed.
+ * @evidence contracts/common.md#clear-and-simple-design One awaited call states the scratch-removal policy; the supported operation parameter permits observation or alternate caller behavior, while capture owns cleanup timing/order and the supplied operation owns actual retry execution.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default operation is the native removal and a failure is never swallowed; injection is a parameter at this boundary rather than a replaced fs method, and no error is retried beyond the bound or masked as success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why the removal is asynchronous, the retry bound and the effect of a persistent failure, followed by parameter documentation and separated tags under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node recursive removal receives the native scratch path and handles supported EBUSY, EMFILE, ENFILE, ENOTEMPTY and EPERM retry conditions. Windows holds are one cause; no OS name guarantees first-attempt success or release behavior.
+ * @evidence contracts/performance.md#efficient-algorithms The native operation owns traversal and retries over the scratch subtree, so visited descendants, native errors and retried operations drive work/storage. maxRetries=10 bounds supported retry counts, with linear delay increments of 100 ms; it does not prove one visit per descendant or a global wall-time/tree-work bound. A supplied operation must implement the same requested policy to provide those retry semantics.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A removal is an effect on one capture's own directory; no completed computation is shared across requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This call waits for native recursive removal or rejection, and retains no historical cache or observer. Rejection can leave a partially removed tree; the capture owner decides subsequent error/cleanup handling. Supported retry count does not bound pending native IO duration or guarantee release, and injected operations own their actual task lifetime.
+ */
+export declare function removeCaptureScratch(directory: string, remove?: typeof fs.promises.rm): Promise<void>;

package/lib/core/transform/generation/removeCaptureScratch.d.mts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+/**
+ * Remove the scratch directory of one whole-project capture, retrying while a
+ * process still holds it.
+ *
+ * Windows refuses to remove a directory a process holds, its working directory
+ * or a file an indexer or a just-exiting plugin child has open, and the refusal
+ * can end once the holder lets go. The asynchronous operation avoids blocking
+ * the event loop during native removal and retry delays; synchronous removal
+ * also supports recursive retry options. Node retries supported busy/resource/
+ * permission errors with linear backoff, increasing delay by 100 ms per try,
+ * with maxRetries=10. A failure that outlasts the policy is a real failure and
+ * propagates to the caller, which decides whether it may replace an earlier
+ * error.
+ *
+ * The removal operation is a parameter so a caller can observe the retry
+ * request without a real locked directory. It must behave as `fs.promises.rm`
+ * does: resolve once the directory is gone, reject with the native error
+ * otherwise.
+ *
+ * @param directory The adapter-owned scratch directory the capture created.
+ * @param remove The removal operation; the native one by default.
+ * @evidence contracts/common.md#principled-implementation An asynchronous recursive removal with Node's retry options is the supported way to outlast a transient Windows hold, while a persistent failure is propagated instead of being reported as removed.
+ * @evidence contracts/common.md#clear-and-simple-design One awaited call states the scratch-removal policy; the supported operation parameter permits observation or alternate caller behavior, while capture owns cleanup timing/order and the supplied operation owns actual retry execution.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default operation is the native removal and a failure is never swallowed; injection is a parameter at this boundary rather than a replaced fs method, and no error is retried beyond the bound or masked as success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why the removal is asynchronous, the retry bound and the effect of a persistent failure, followed by parameter documentation and separated tags under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node recursive removal receives the native scratch path and handles supported EBUSY, EMFILE, ENFILE, ENOTEMPTY and EPERM retry conditions. Windows holds are one cause; no OS name guarantees first-attempt success or release behavior.
+ * @evidence contracts/performance.md#efficient-algorithms The native operation owns traversal and retries over the scratch subtree, so visited descendants, native errors and retried operations drive work/storage. maxRetries=10 bounds supported retry counts, with linear delay increments of 100 ms; it does not prove one visit per descendant or a global wall-time/tree-work bound. A supplied operation must implement the same requested policy to provide those retry semantics.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A removal is an effect on one capture's own directory; no completed computation is shared across requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This call waits for native recursive removal or rejection, and retains no historical cache or observer. Rejection can leave a partially removed tree; the capture owner decides subsequent error/cleanup handling. Supported retry count does not bound pending native IO duration or guarantee release, and injected operations own their actual task lifetime.
+ */
+export declare function removeCaptureScratch(directory: string, remove?: typeof fs.promises.rm): Promise<void>;

package/lib/core/transform/generation/removeCaptureScratch.d.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+/**
+ * Remove the scratch directory of one whole-project capture, retrying while a
+ * process still holds it.
+ *
+ * Windows refuses to remove a directory a process holds, its working directory
+ * or a file an indexer or a just-exiting plugin child has open, and the refusal
+ * can end once the holder lets go. The asynchronous operation avoids blocking
+ * the event loop during native removal and retry delays; synchronous removal
+ * also supports recursive retry options. Node retries supported busy/resource/
+ * permission errors with linear backoff, increasing delay by 100 ms per try,
+ * with maxRetries=10. A failure that outlasts the policy is a real failure and
+ * propagates to the caller, which decides whether it may replace an earlier
+ * error.
+ *
+ * The removal operation is a parameter so a caller can observe the retry
+ * request without a real locked directory. It must behave as `fs.promises.rm`
+ * does: resolve once the directory is gone, reject with the native error
+ * otherwise.
+ *
+ * @param directory The adapter-owned scratch directory the capture created.
+ * @param remove The removal operation; the native one by default.
+ * @evidence contracts/common.md#principled-implementation An asynchronous recursive removal with Node's retry options is the supported way to outlast a transient Windows hold, while a persistent failure is propagated instead of being reported as removed.
+ * @evidence contracts/common.md#clear-and-simple-design One awaited call states the scratch-removal policy; the supported operation parameter permits observation or alternate caller behavior, while capture owns cleanup timing/order and the supplied operation owns actual retry execution.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default operation is the native removal and a failure is never swallowed; injection is a parameter at this boundary rather than a replaced fs method, and no error is retried beyond the bound or masked as success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why the removal is asynchronous, the retry bound and the effect of a persistent failure, followed by parameter documentation and separated tags under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node recursive removal receives the native scratch path and handles supported EBUSY, EMFILE, ENFILE, ENOTEMPTY and EPERM retry conditions. Windows holds are one cause; no OS name guarantees first-attempt success or release behavior.
+ * @evidence contracts/performance.md#efficient-algorithms The native operation owns traversal and retries over the scratch subtree, so visited descendants, native errors and retried operations drive work/storage. maxRetries=10 bounds supported retry counts, with linear delay increments of 100 ms; it does not prove one visit per descendant or a global wall-time/tree-work bound. A supplied operation must implement the same requested policy to provide those retry semantics.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A removal is an effect on one capture's own directory; no completed computation is shared across requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This call waits for native recursive removal or rejection, and retains no historical cache or observer. Rejection can leave a partially removed tree; the capture owner decides subsequent error/cleanup handling. Supported retry count does not bound pending native IO duration or guarantee release, and injected operations own their actual task lifetime.
+ */
+export declare function removeCaptureScratch(directory: string, remove?: typeof fs.promises.rm): Promise<void>;

package/lib/core/transform/generation/removeCaptureScratch.js

@@ -0,0 +1,45 @@
+'use strict';
+
+var fs = require('node:fs');
+
+/**
+ * Remove the scratch directory of one whole-project capture, retrying while a
+ * process still holds it.
+ *
+ * Windows refuses to remove a directory a process holds, its working directory
+ * or a file an indexer or a just-exiting plugin child has open, and the refusal
+ * can end once the holder lets go. The asynchronous operation avoids blocking
+ * the event loop during native removal and retry delays; synchronous removal
+ * also supports recursive retry options. Node retries supported busy/resource/
+ * permission errors with linear backoff, increasing delay by 100 ms per try,
+ * with maxRetries=10. A failure that outlasts the policy is a real failure and
+ * propagates to the caller, which decides whether it may replace an earlier
+ * error.
+ *
+ * The removal operation is a parameter so a caller can observe the retry
+ * request without a real locked directory. It must behave as `fs.promises.rm`
+ * does: resolve once the directory is gone, reject with the native error
+ * otherwise.
+ *
+ * @param directory The adapter-owned scratch directory the capture created.
+ * @param remove The removal operation; the native one by default.
+ * @evidence contracts/common.md#principled-implementation An asynchronous recursive removal with Node's retry options is the supported way to outlast a transient Windows hold, while a persistent failure is propagated instead of being reported as removed.
+ * @evidence contracts/common.md#clear-and-simple-design One awaited call states the scratch-removal policy; the supported operation parameter permits observation or alternate caller behavior, while capture owns cleanup timing/order and the supplied operation owns actual retry execution.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default operation is the native removal and a failure is never swallowed; injection is a parameter at this boundary rather than a replaced fs method, and no error is retried beyond the bound or masked as success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why the removal is asynchronous, the retry bound and the effect of a persistent failure, followed by parameter documentation and separated tags under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node recursive removal receives the native scratch path and handles supported EBUSY, EMFILE, ENFILE, ENOTEMPTY and EPERM retry conditions. Windows holds are one cause; no OS name guarantees first-attempt success or release behavior.
+ * @evidence contracts/performance.md#efficient-algorithms The native operation owns traversal and retries over the scratch subtree, so visited descendants, native errors and retried operations drive work/storage. maxRetries=10 bounds supported retry counts, with linear delay increments of 100 ms; it does not prove one visit per descendant or a global wall-time/tree-work bound. A supplied operation must implement the same requested policy to provide those retry semantics.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A removal is an effect on one capture's own directory; no completed computation is shared across requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This call waits for native recursive removal or rejection, and retains no historical cache or observer. Rejection can leave a partially removed tree; the capture owner decides subsequent error/cleanup handling. Supported retry count does not bound pending native IO duration or guarantee release, and injected operations own their actual task lifetime.
+ */
+async function removeCaptureScratch(directory, remove = fs.promises.rm) {
+    await remove(directory, {
+        force: true,
+        maxRetries: 10,
+        recursive: true,
+        retryDelay: 100,
+    });
+}
+
+exports.removeCaptureScratch = removeCaptureScratch;
+//# sourceMappingURL=removeCaptureScratch.js.map

package/lib/core/transform/generation/removeCaptureScratch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"removeCaptureScratch.js","sources":["../../../../src/core/transform/generation/removeCaptureScratch.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;AACI,eAAe,oBAAoB,CACxC,SAAiB,EACjB,MAAA,GAAgC,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAA;IAE9C,MAAM,MAAM,CAAC,SAAS,EAAE;AACtB,QAAA,KAAK,EAAE,IAAI;AACX,QAAA,UAAU,EAAE,EAAE;AACd,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,UAAU,EAAE,GAAG;AAChB,KAAA,CAAC;AACJ;;;;"}

package/lib/core/transform/generation/removeCaptureScratch.mjs

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+
+/**
+ * Remove the scratch directory of one whole-project capture, retrying while a
+ * process still holds it.
+ *
+ * Windows refuses to remove a directory a process holds, its working directory
+ * or a file an indexer or a just-exiting plugin child has open, and the refusal
+ * can end once the holder lets go. The asynchronous operation avoids blocking
+ * the event loop during native removal and retry delays; synchronous removal
+ * also supports recursive retry options. Node retries supported busy/resource/
+ * permission errors with linear backoff, increasing delay by 100 ms per try,
+ * with maxRetries=10. A failure that outlasts the policy is a real failure and
+ * propagates to the caller, which decides whether it may replace an earlier
+ * error.
+ *
+ * The removal operation is a parameter so a caller can observe the retry
+ * request without a real locked directory. It must behave as `fs.promises.rm`
+ * does: resolve once the directory is gone, reject with the native error
+ * otherwise.
+ *
+ * @param directory The adapter-owned scratch directory the capture created.
+ * @param remove The removal operation; the native one by default.
+ * @evidence contracts/common.md#principled-implementation An asynchronous recursive removal with Node's retry options is the supported way to outlast a transient Windows hold, while a persistent failure is propagated instead of being reported as removed.
+ * @evidence contracts/common.md#clear-and-simple-design One awaited call states the scratch-removal policy; the supported operation parameter permits observation or alternate caller behavior, while capture owns cleanup timing/order and the supplied operation owns actual retry execution.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default operation is the native removal and a failure is never swallowed; injection is a parameter at this boundary rather than a replaced fs method, and no error is retried beyond the bound or masked as success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why the removal is asynchronous, the retry bound and the effect of a persistent failure, followed by parameter documentation and separated tags under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node recursive removal receives the native scratch path and handles supported EBUSY, EMFILE, ENFILE, ENOTEMPTY and EPERM retry conditions. Windows holds are one cause; no OS name guarantees first-attempt success or release behavior.
+ * @evidence contracts/performance.md#efficient-algorithms The native operation owns traversal and retries over the scratch subtree, so visited descendants, native errors and retried operations drive work/storage. maxRetries=10 bounds supported retry counts, with linear delay increments of 100 ms; it does not prove one visit per descendant or a global wall-time/tree-work bound. A supplied operation must implement the same requested policy to provide those retry semantics.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A removal is an effect on one capture's own directory; no completed computation is shared across requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This call waits for native recursive removal or rejection, and retains no historical cache or observer. Rejection can leave a partially removed tree; the capture owner decides subsequent error/cleanup handling. Supported retry count does not bound pending native IO duration or guarantee release, and injected operations own their actual task lifetime.
+ */
+async function removeCaptureScratch(directory, remove = fs.promises.rm) {
+    await remove(directory, {
+        force: true,
+        maxRetries: 10,
+        recursive: true,
+        retryDelay: 100,
+    });
+}
+
+export { removeCaptureScratch };
+//# sourceMappingURL=removeCaptureScratch.mjs.map

package/lib/core/transform/generation/removeCaptureScratch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"removeCaptureScratch.mjs","sources":["../../../../src/core/transform/generation/removeCaptureScratch.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;AACI,eAAe,oBAAoB,CACxC,SAAiB,EACjB,MAAA,GAAgC,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAA;IAE9C,MAAM,MAAM,CAAC,SAAS,EAAE;AACtB,QAAA,KAAK,EAAE,IAAI;AACX,QAAA,UAAU,EAAE,EAAE;AACd,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,UAAU,EAAE,GAAG;AAChB,KAAA,CAAC;AACJ;;;;"}

package/lib/core/transform/generation/retainGenerationNotifications.d.cts

@@ -0,0 +1,53 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.cjs";
+import type { TtscProjectMutationTracker } from "../tracker/TtscProjectMutationTracker.cjs";
+/**
+ * Sample notification availability after tracker settlement.
+ *
+ * Absence is permitted because recorded-state validation retains its proof; any
+ * present failed observer withdraws notification transfer as a whole. The
+ * caller samples this before subsequent proof admission, preserving the capture
+ * operation's established ordering.
+ *
+ * @evidence contracts/common.md#principled-implementation Every present project, host and candidate tracker must have settled without failure; an absent optional tracker does not invent a failure or coverage claim.
+ * @evidence contracts/common.md#clear-and-simple-design One three-field predicate owns the sampled availability verdict consumed by later retention admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No observer health is inferred from successful compilation or another healthy tracker, and this operation creates no tracker or native capability.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains absent versus failed state and the production caller's exact sampling point.
+ * @evidence contracts/portability.md#os-neutral-implementation The actual tracker interface supplies settled failure state independently of backend names and operating systems.
+ * @evidence contracts/performance.md#efficient-algorithms At most three constant-time field reads establish availability without probing the filesystem or native backend again.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call samples current tracker state; the capture caller controls how long that sampled verdict applies.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows tracker references without retaining or releasing their owned observers.
+ */
+export declare function generationNotificationsAvailable(project: TtscProjectMutationTracker | undefined, host: TtscProjectMutationTracker | undefined, candidate: TtscProjectMutationTracker | undefined): boolean;
+/**
+ * Transfer admitted notification authority to one captured generation.
+ *
+ * Actual observer creation, settlement and proof construction remain in the
+ * capture owner. This operation attaches only qualified handles and returns the
+ * exact ownership flags that its caller uses for finally cleanup. The caller
+ * supplies a newly captured generation without prior tracker ownership.
+ * Availability is its earlier settled sample, not a fresh health check
+ * performed here; live tracker consumers still qualify current authority.
+ *
+ * @evidence contracts/common.md#principled-implementation Retention requires the caller's membership and notification policies, complete generation proof and sampled observer availability together; failure of any premise leaves every tracker with its local cleanup owner.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous admission gate attaches three optional handles and returns their independent ownership flags; acquisition and finally cleanup stay with capture.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supplied availability sample must cover every present observer rather than infer health from a sibling; missing snapshot authority cannot be promoted to complete proof, and no tracker is manufactured. This gate does not refresh the earlier sample.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the caller-owned creation and settlement steps and the exact cleanup responsibility conveyed by the return value.
+ * @evidence contracts/portability.md#os-neutral-implementation Backend-independent tracker references transfer through their actual lifecycle interface; the gate adds no OS-name or path-case inference.
+ * @evidence contracts/performance.md#efficient-algorithms One Boolean gate and at most three assignments avoid additional native observations or project scans.
+ * @evidence contracts/performance.md#reuse-equivalent-work Qualified existing observers transfer with the generation instead of opening equivalent observers again; unavailable authority leaves recorded-state validation responsible for reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Returned flags identify each transferred observer independently, including a candidate when another tracker is absent. The fresh generation gains at most three tracker references, whose watch populations/lifecycle stay with the tracker and disposal owners; this gate does not replace or release pre-existing generation handles. Untransferred handles remain owned by capture finally cleanup attempts.
+ */
+export declare function retainGenerationNotifications(props: {
+    cached: TtscCachedProjectTransform;
+    project: TtscProjectMutationTracker | undefined;
+    host: TtscProjectMutationTracker | undefined;
+    candidate: TtscProjectMutationTracker | undefined;
+    retainProjectMembership: boolean;
+    retainNotifications: boolean;
+    stableProjectSnapshot: boolean;
+    notificationsAvailable: boolean;
+}): {
+    project: boolean;
+    host: boolean;
+    candidate: boolean;
+};

package/lib/core/transform/generation/retainGenerationNotifications.d.mts

@@ -0,0 +1,53 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.mjs";
+import type { TtscProjectMutationTracker } from "../tracker/TtscProjectMutationTracker.mjs";
+/**
+ * Sample notification availability after tracker settlement.
+ *
+ * Absence is permitted because recorded-state validation retains its proof; any
+ * present failed observer withdraws notification transfer as a whole. The
+ * caller samples this before subsequent proof admission, preserving the capture
+ * operation's established ordering.
+ *
+ * @evidence contracts/common.md#principled-implementation Every present project, host and candidate tracker must have settled without failure; an absent optional tracker does not invent a failure or coverage claim.
+ * @evidence contracts/common.md#clear-and-simple-design One three-field predicate owns the sampled availability verdict consumed by later retention admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No observer health is inferred from successful compilation or another healthy tracker, and this operation creates no tracker or native capability.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains absent versus failed state and the production caller's exact sampling point.
+ * @evidence contracts/portability.md#os-neutral-implementation The actual tracker interface supplies settled failure state independently of backend names and operating systems.
+ * @evidence contracts/performance.md#efficient-algorithms At most three constant-time field reads establish availability without probing the filesystem or native backend again.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call samples current tracker state; the capture caller controls how long that sampled verdict applies.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows tracker references without retaining or releasing their owned observers.
+ */
+export declare function generationNotificationsAvailable(project: TtscProjectMutationTracker | undefined, host: TtscProjectMutationTracker | undefined, candidate: TtscProjectMutationTracker | undefined): boolean;
+/**
+ * Transfer admitted notification authority to one captured generation.
+ *
+ * Actual observer creation, settlement and proof construction remain in the
+ * capture owner. This operation attaches only qualified handles and returns the
+ * exact ownership flags that its caller uses for finally cleanup. The caller
+ * supplies a newly captured generation without prior tracker ownership.
+ * Availability is its earlier settled sample, not a fresh health check
+ * performed here; live tracker consumers still qualify current authority.
+ *
+ * @evidence contracts/common.md#principled-implementation Retention requires the caller's membership and notification policies, complete generation proof and sampled observer availability together; failure of any premise leaves every tracker with its local cleanup owner.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous admission gate attaches three optional handles and returns their independent ownership flags; acquisition and finally cleanup stay with capture.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supplied availability sample must cover every present observer rather than infer health from a sibling; missing snapshot authority cannot be promoted to complete proof, and no tracker is manufactured. This gate does not refresh the earlier sample.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the caller-owned creation and settlement steps and the exact cleanup responsibility conveyed by the return value.
+ * @evidence contracts/portability.md#os-neutral-implementation Backend-independent tracker references transfer through their actual lifecycle interface; the gate adds no OS-name or path-case inference.
+ * @evidence contracts/performance.md#efficient-algorithms One Boolean gate and at most three assignments avoid additional native observations or project scans.
+ * @evidence contracts/performance.md#reuse-equivalent-work Qualified existing observers transfer with the generation instead of opening equivalent observers again; unavailable authority leaves recorded-state validation responsible for reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Returned flags identify each transferred observer independently, including a candidate when another tracker is absent. The fresh generation gains at most three tracker references, whose watch populations/lifecycle stay with the tracker and disposal owners; this gate does not replace or release pre-existing generation handles. Untransferred handles remain owned by capture finally cleanup attempts.
+ */
+export declare function retainGenerationNotifications(props: {
+    cached: TtscCachedProjectTransform;
+    project: TtscProjectMutationTracker | undefined;
+    host: TtscProjectMutationTracker | undefined;
+    candidate: TtscProjectMutationTracker | undefined;
+    retainProjectMembership: boolean;
+    retainNotifications: boolean;
+    stableProjectSnapshot: boolean;
+    notificationsAvailable: boolean;
+}): {
+    project: boolean;
+    host: boolean;
+    candidate: boolean;
+};

package/lib/core/transform/generation/retainGenerationNotifications.d.ts

@@ -0,0 +1,53 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscProjectMutationTracker } from "../tracker/TtscProjectMutationTracker";
+/**
+ * Sample notification availability after tracker settlement.
+ *
+ * Absence is permitted because recorded-state validation retains its proof; any
+ * present failed observer withdraws notification transfer as a whole. The
+ * caller samples this before subsequent proof admission, preserving the capture
+ * operation's established ordering.
+ *
+ * @evidence contracts/common.md#principled-implementation Every present project, host and candidate tracker must have settled without failure; an absent optional tracker does not invent a failure or coverage claim.
+ * @evidence contracts/common.md#clear-and-simple-design One three-field predicate owns the sampled availability verdict consumed by later retention admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No observer health is inferred from successful compilation or another healthy tracker, and this operation creates no tracker or native capability.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains absent versus failed state and the production caller's exact sampling point.
+ * @evidence contracts/portability.md#os-neutral-implementation The actual tracker interface supplies settled failure state independently of backend names and operating systems.
+ * @evidence contracts/performance.md#efficient-algorithms At most three constant-time field reads establish availability without probing the filesystem or native backend again.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call samples current tracker state; the capture caller controls how long that sampled verdict applies.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows tracker references without retaining or releasing their owned observers.
+ */
+export declare function generationNotificationsAvailable(project: TtscProjectMutationTracker | undefined, host: TtscProjectMutationTracker | undefined, candidate: TtscProjectMutationTracker | undefined): boolean;
+/**
+ * Transfer admitted notification authority to one captured generation.
+ *
+ * Actual observer creation, settlement and proof construction remain in the
+ * capture owner. This operation attaches only qualified handles and returns the
+ * exact ownership flags that its caller uses for finally cleanup. The caller
+ * supplies a newly captured generation without prior tracker ownership.
+ * Availability is its earlier settled sample, not a fresh health check
+ * performed here; live tracker consumers still qualify current authority.
+ *
+ * @evidence contracts/common.md#principled-implementation Retention requires the caller's membership and notification policies, complete generation proof and sampled observer availability together; failure of any premise leaves every tracker with its local cleanup owner.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous admission gate attaches three optional handles and returns their independent ownership flags; acquisition and finally cleanup stay with capture.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supplied availability sample must cover every present observer rather than infer health from a sibling; missing snapshot authority cannot be promoted to complete proof, and no tracker is manufactured. This gate does not refresh the earlier sample.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the caller-owned creation and settlement steps and the exact cleanup responsibility conveyed by the return value.
+ * @evidence contracts/portability.md#os-neutral-implementation Backend-independent tracker references transfer through their actual lifecycle interface; the gate adds no OS-name or path-case inference.
+ * @evidence contracts/performance.md#efficient-algorithms One Boolean gate and at most three assignments avoid additional native observations or project scans.
+ * @evidence contracts/performance.md#reuse-equivalent-work Qualified existing observers transfer with the generation instead of opening equivalent observers again; unavailable authority leaves recorded-state validation responsible for reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Returned flags identify each transferred observer independently, including a candidate when another tracker is absent. The fresh generation gains at most three tracker references, whose watch populations/lifecycle stay with the tracker and disposal owners; this gate does not replace or release pre-existing generation handles. Untransferred handles remain owned by capture finally cleanup attempts.
+ */
+export declare function retainGenerationNotifications(props: {
+    cached: TtscCachedProjectTransform;
+    project: TtscProjectMutationTracker | undefined;
+    host: TtscProjectMutationTracker | undefined;
+    candidate: TtscProjectMutationTracker | undefined;
+    retainProjectMembership: boolean;
+    retainNotifications: boolean;
+    stableProjectSnapshot: boolean;
+    notificationsAvailable: boolean;
+}): {
+    project: boolean;
+    host: boolean;
+    candidate: boolean;
+};