@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/clock/refreshFilesystemClockReference.js

@@ -0,0 +1,69 @@
+'use strict';
+
+var fs = require('node:fs');
+var path = require('node:path');
+var filesystemClockReferences = require('./filesystemClockReferences.js');
+
+/**
+ * Replace every prior clock proof with one reference minted by a fresh write.
+ *
+ * The reference directory is storage the adapter already owns, deliberately
+ * outside the project root, so stamping a probe file there produces a
+ * freshly-minted "now" without touching the user's project — the analogue of
+ * git writing its index. The probe is observed through the cache-owned
+ * operations and keyed by the device those operations report, so it only ever
+ * separates stamps on the filesystem that actually minted it. When its volume
+ * differs from the inputs' volume, or the observed filesystem cannot see the
+ * probe at all, nothing is proven and content comparison continues. The write
+ * uses the native host filesystem; the supplied observing view must coherently
+ * observe that probe for its metadata to represent this mint. This function
+ * does not independently certify equivalence of a replaced view.
+ *
+ * Forcing the reference onto the inputs' volume would require writing into the
+ * user's project or an otherwise unowned neighboring directory. That is not a
+ * valid price for this optimization, so the cross-volume case degrades to more
+ * reads instead.
+ *
+ * @evidence contracts/common.md#principled-implementation Clearing old references before a fresh owned probe write prevents previous or rolled-back stamps from certifying content; only observed regular-file metadata establishes a same-device reference.
+ * @evidence contracts/common.md#clear-and-simple-design This operation mints and records one probe stamp; input metadata comparison remains in the separability consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed writes, inaccessible probes, or another device cannot be replaced by Date.now or a historical maximum; actual content proof remains necessary.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain owned storage, fresh-write evidence, and why cross-volume inputs require more reads.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral clock proof uses native owned-path writes and the observing view's bigint device/time metadata, preserving cross-volume and unavailable-probe behavior without a platform clock assumption.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Clear the view's prior entries, then an available directory performs native
+ *   path joining, one write of process-counter text and one observed metadata
+ *   read. Costs include path/counter text and native I/O; a missing directory
+ *   skips I/O. Clearing/recording follows the current reference population,
+ *   not a scan of project inputs.
+ * @evidence contracts/performance.md#reuse-equivalent-work The existing probe path and shared per-view reference table are reused; only a newly minted stamp can authorize signature reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Refresh clears history and retains at most one regular-file device stamp;
+ *   failure leaves an empty reference table. The single probe persists in its
+ *   generation/process-owned directory until that owner attempts cleanup;
+ *   this refresh acquires no separate handle or retry task.
+ */
+function refreshFilesystemClockReference(
+/** Owned probe storage, or unavailable storage requiring reference withdrawal. */
+referenceDirectory, 
+/** Coherent observing view whose device/time reference will be replaced. */
+filesystem) {
+    const references = filesystemClockReferences.filesystemClockReferences(filesystem);
+    references.clear();
+    if (referenceDirectory === undefined)
+        return;
+    try {
+        const probe = path.join(referenceDirectory, "clock-reference");
+        fs.writeFileSync(probe, `${process.hrtime.bigint()}\n`);
+        const stats = filesystem.lstat(probe);
+        if (stats.isFile()) {
+            references.set(stats.dev, stats.mtimeNs);
+        }
+    }
+    catch {
+        // A failed refresh leaves no reference, so content comparison continues.
+        references.clear();
+    }
+}
+
+exports.refreshFilesystemClockReference = refreshFilesystemClockReference;
+//# sourceMappingURL=refreshFilesystemClockReference.js.map

package/lib/core/transform/clock/refreshFilesystemClockReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshFilesystemClockReference.js","sources":["../../../../src/core/transform/clock/refreshFilesystemClockReference.ts"],"sourcesContent":[null],"names":["filesystemClockReferences"],"mappings":";;;;;;AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;SACa,+BAA+B;AAC7C;AACA,kBAAsC;AACtC;AACA,UAA6C,EAAA;AAE7C,IAAA,MAAM,UAAU,GAAGA,mDAAyB,CAAC,UAAU,CAAC;IACxD,UAAU,CAAC,KAAK,EAAE;IAClB,IAAI,kBAAkB,KAAK,SAAS;QAAE;AACtC,IAAA,IAAI;QACF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,iBAAiB,CAAC;AAC9D,QAAA,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,CAAA,EAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAA,EAAA,CAAI,CAAC;QACvD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;AACrC,QAAA,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE;YAClB,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC;QAC1C;IACF;AAAE,IAAA,MAAM;;QAEN,UAAU,CAAC,KAAK,EAAE;IACpB;AACF;;;;"}

package/lib/core/transform/clock/refreshFilesystemClockReference.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { filesystemClockReferences } from './filesystemClockReferences.mjs';
+
+/**
+ * Replace every prior clock proof with one reference minted by a fresh write.
+ *
+ * The reference directory is storage the adapter already owns, deliberately
+ * outside the project root, so stamping a probe file there produces a
+ * freshly-minted "now" without touching the user's project — the analogue of
+ * git writing its index. The probe is observed through the cache-owned
+ * operations and keyed by the device those operations report, so it only ever
+ * separates stamps on the filesystem that actually minted it. When its volume
+ * differs from the inputs' volume, or the observed filesystem cannot see the
+ * probe at all, nothing is proven and content comparison continues. The write
+ * uses the native host filesystem; the supplied observing view must coherently
+ * observe that probe for its metadata to represent this mint. This function
+ * does not independently certify equivalence of a replaced view.
+ *
+ * Forcing the reference onto the inputs' volume would require writing into the
+ * user's project or an otherwise unowned neighboring directory. That is not a
+ * valid price for this optimization, so the cross-volume case degrades to more
+ * reads instead.
+ *
+ * @evidence contracts/common.md#principled-implementation Clearing old references before a fresh owned probe write prevents previous or rolled-back stamps from certifying content; only observed regular-file metadata establishes a same-device reference.
+ * @evidence contracts/common.md#clear-and-simple-design This operation mints and records one probe stamp; input metadata comparison remains in the separability consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed writes, inaccessible probes, or another device cannot be replaced by Date.now or a historical maximum; actual content proof remains necessary.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain owned storage, fresh-write evidence, and why cross-volume inputs require more reads.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral clock proof uses native owned-path writes and the observing view's bigint device/time metadata, preserving cross-volume and unavailable-probe behavior without a platform clock assumption.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Clear the view's prior entries, then an available directory performs native
+ *   path joining, one write of process-counter text and one observed metadata
+ *   read. Costs include path/counter text and native I/O; a missing directory
+ *   skips I/O. Clearing/recording follows the current reference population,
+ *   not a scan of project inputs.
+ * @evidence contracts/performance.md#reuse-equivalent-work The existing probe path and shared per-view reference table are reused; only a newly minted stamp can authorize signature reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Refresh clears history and retains at most one regular-file device stamp;
+ *   failure leaves an empty reference table. The single probe persists in its
+ *   generation/process-owned directory until that owner attempts cleanup;
+ *   this refresh acquires no separate handle or retry task.
+ */
+function refreshFilesystemClockReference(
+/** Owned probe storage, or unavailable storage requiring reference withdrawal. */
+referenceDirectory, 
+/** Coherent observing view whose device/time reference will be replaced. */
+filesystem) {
+    const references = filesystemClockReferences(filesystem);
+    references.clear();
+    if (referenceDirectory === undefined)
+        return;
+    try {
+        const probe = path.join(referenceDirectory, "clock-reference");
+        fs.writeFileSync(probe, `${process.hrtime.bigint()}\n`);
+        const stats = filesystem.lstat(probe);
+        if (stats.isFile()) {
+            references.set(stats.dev, stats.mtimeNs);
+        }
+    }
+    catch {
+        // A failed refresh leaves no reference, so content comparison continues.
+        references.clear();
+    }
+}
+
+export { refreshFilesystemClockReference };
+//# sourceMappingURL=refreshFilesystemClockReference.mjs.map

package/lib/core/transform/clock/refreshFilesystemClockReference.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshFilesystemClockReference.mjs","sources":["../../../../src/core/transform/clock/refreshFilesystemClockReference.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;SACa,+BAA+B;AAC7C;AACA,kBAAsC;AACtC;AACA,UAA6C,EAAA;AAE7C,IAAA,MAAM,UAAU,GAAG,yBAAyB,CAAC,UAAU,CAAC;IACxD,UAAU,CAAC,KAAK,EAAE;IAClB,IAAI,kBAAkB,KAAK,SAAS;QAAE;AACtC,IAAA,IAAI;QACF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,iBAAiB,CAAC;AAC9D,QAAA,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,CAAA,EAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAA,EAAA,CAAI,CAAC;QACvD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;AACrC,QAAA,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE;YAClB,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC;QAC1C;IACF;AAAE,IAAA,MAAM;;QAEN,UAAU,CAAC,KAAK,EAAE;IACpB;AACF;;;;"}

package/lib/core/transform/clock/refreshProcessClockReference.d.cts

@@ -0,0 +1,46 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Replace every prior clock proof with one reference minted in the probe
+ * directory this process keeps for the proofs that hold no generation.
+ *
+ * A proof may let a separable signature stand for content only against a
+ * reference minted before its own reads (`filesystemClockReferences`): after a
+ * clock rollback a write can land in the tick of a recorded stamp, and only a
+ * reference minted since the rollback puts that stamp inside it. A generation's
+ * deliveries and capture mint in the probe directory the generation retains. A
+ * proof that holds no generation has none: a failed generation's replay, whose
+ * directory was released with it, a record's proof at a build start, and the
+ * observer's proof of a plugin source.
+ *
+ * Those proofs run at any moment, beside compiles that observe the directories
+ * around them, so minting may change nothing but the probe itself. Creating and
+ * removing a directory per proof would add and remove an entry in the shared
+ * temporary directory, whose metadata other observers read: the absence of a
+ * `package.json` there, for one, is proven by that directory's own metadata
+ * holding still while a plugin descriptor is evaluated. The probe therefore
+ * lives at a process-named directory below this user's current state root
+ * (`userStateDirectory`), whose provider rechecks the native layout on each
+ * call; the probe is rewritten in place. A later session attempts to reclaim
+ * dead-process entries when it scans that state root. The main thread registers
+ * best-effort exit removal for its first successfully obtained directory.
+ * Worker threads share the process id and so the directory: a probe another
+ * thread rewrites between this one's write and its read is still a stamp minted
+ * before this proof reads.
+ *
+ * Minting is an optimization's precondition, never a requirement. When the
+ * directory cannot be had, either physical address cannot be resolved, or the
+ * probe directory lies inside the physical `root`, every prior reference is
+ * cleared anyway, so no signature is separable and the proof reads content.
+ *
+ * @param root The project or source the probe must lie outside.
+ * @param filesystem The operations whose references the proof judges against.
+ * @evidence contracts/common.md#principled-implementation Detached proofs mint a fresh reference in a process-owned directory outside the observed root; unavailable or inside-root storage clears reference authority instead.
+ * @evidence contracts/common.md#clear-and-simple-design The operation selects process storage then delegates the actual mint to the same reference writer used by generations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No process timestamp substitutes for a filesystem stamp, and failure preserves real content comparison without writing into the user's source tree.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain rollback ordering, directory-entry interference, worker sharing, and exit ownership before stating unavailable-storage behavior.
+ * @evidence contracts/portability.md#os-neutral-implementation The native user-state provider selects process storage; physical root and probe-directory resolution through the supplied coherent native view prevents lexical aliases from concealing containment. Unknown physical identity withdraws reference authority; observed device/time metadata qualifies cross-volume applicability.
+ * @evidence contracts/performance.md#efficient-algorithms Each call pays the state provider's native path/ownership checks and two physical path resolutions before an admitted delegated probe write/lstat. Work includes path text and native observations, not a cached directory lookup; the probe is rewritten rather than opening a temporary tree per proof.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation-free proofs share the same process probe and per-operation reference table while still minting before every proof that depends on separability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The provider's process-named directory and one probe persist between detached proofs. One main-thread listener attempts removal of the first acquired directory, and later session scans attempt dead-process reclamation. Native refusal or changed state-root backing can leave entries; neither exit nor a future scan guarantees successful or timely removal.
+ */
+export declare function refreshProcessClockReference(root: string, filesystem: TtscTransformFilesystemOperations): void;

package/lib/core/transform/clock/refreshProcessClockReference.d.mts

@@ -0,0 +1,46 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Replace every prior clock proof with one reference minted in the probe
+ * directory this process keeps for the proofs that hold no generation.
+ *
+ * A proof may let a separable signature stand for content only against a
+ * reference minted before its own reads (`filesystemClockReferences`): after a
+ * clock rollback a write can land in the tick of a recorded stamp, and only a
+ * reference minted since the rollback puts that stamp inside it. A generation's
+ * deliveries and capture mint in the probe directory the generation retains. A
+ * proof that holds no generation has none: a failed generation's replay, whose
+ * directory was released with it, a record's proof at a build start, and the
+ * observer's proof of a plugin source.
+ *
+ * Those proofs run at any moment, beside compiles that observe the directories
+ * around them, so minting may change nothing but the probe itself. Creating and
+ * removing a directory per proof would add and remove an entry in the shared
+ * temporary directory, whose metadata other observers read: the absence of a
+ * `package.json` there, for one, is proven by that directory's own metadata
+ * holding still while a plugin descriptor is evaluated. The probe therefore
+ * lives at a process-named directory below this user's current state root
+ * (`userStateDirectory`), whose provider rechecks the native layout on each
+ * call; the probe is rewritten in place. A later session attempts to reclaim
+ * dead-process entries when it scans that state root. The main thread registers
+ * best-effort exit removal for its first successfully obtained directory.
+ * Worker threads share the process id and so the directory: a probe another
+ * thread rewrites between this one's write and its read is still a stamp minted
+ * before this proof reads.
+ *
+ * Minting is an optimization's precondition, never a requirement. When the
+ * directory cannot be had, either physical address cannot be resolved, or the
+ * probe directory lies inside the physical `root`, every prior reference is
+ * cleared anyway, so no signature is separable and the proof reads content.
+ *
+ * @param root The project or source the probe must lie outside.
+ * @param filesystem The operations whose references the proof judges against.
+ * @evidence contracts/common.md#principled-implementation Detached proofs mint a fresh reference in a process-owned directory outside the observed root; unavailable or inside-root storage clears reference authority instead.
+ * @evidence contracts/common.md#clear-and-simple-design The operation selects process storage then delegates the actual mint to the same reference writer used by generations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No process timestamp substitutes for a filesystem stamp, and failure preserves real content comparison without writing into the user's source tree.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain rollback ordering, directory-entry interference, worker sharing, and exit ownership before stating unavailable-storage behavior.
+ * @evidence contracts/portability.md#os-neutral-implementation The native user-state provider selects process storage; physical root and probe-directory resolution through the supplied coherent native view prevents lexical aliases from concealing containment. Unknown physical identity withdraws reference authority; observed device/time metadata qualifies cross-volume applicability.
+ * @evidence contracts/performance.md#efficient-algorithms Each call pays the state provider's native path/ownership checks and two physical path resolutions before an admitted delegated probe write/lstat. Work includes path text and native observations, not a cached directory lookup; the probe is rewritten rather than opening a temporary tree per proof.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation-free proofs share the same process probe and per-operation reference table while still minting before every proof that depends on separability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The provider's process-named directory and one probe persist between detached proofs. One main-thread listener attempts removal of the first acquired directory, and later session scans attempt dead-process reclamation. Native refusal or changed state-root backing can leave entries; neither exit nor a future scan guarantees successful or timely removal.
+ */
+export declare function refreshProcessClockReference(root: string, filesystem: TtscTransformFilesystemOperations): void;

package/lib/core/transform/clock/refreshProcessClockReference.d.ts

@@ -0,0 +1,46 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Replace every prior clock proof with one reference minted in the probe
+ * directory this process keeps for the proofs that hold no generation.
+ *
+ * A proof may let a separable signature stand for content only against a
+ * reference minted before its own reads (`filesystemClockReferences`): after a
+ * clock rollback a write can land in the tick of a recorded stamp, and only a
+ * reference minted since the rollback puts that stamp inside it. A generation's
+ * deliveries and capture mint in the probe directory the generation retains. A
+ * proof that holds no generation has none: a failed generation's replay, whose
+ * directory was released with it, a record's proof at a build start, and the
+ * observer's proof of a plugin source.
+ *
+ * Those proofs run at any moment, beside compiles that observe the directories
+ * around them, so minting may change nothing but the probe itself. Creating and
+ * removing a directory per proof would add and remove an entry in the shared
+ * temporary directory, whose metadata other observers read: the absence of a
+ * `package.json` there, for one, is proven by that directory's own metadata
+ * holding still while a plugin descriptor is evaluated. The probe therefore
+ * lives at a process-named directory below this user's current state root
+ * (`userStateDirectory`), whose provider rechecks the native layout on each
+ * call; the probe is rewritten in place. A later session attempts to reclaim
+ * dead-process entries when it scans that state root. The main thread registers
+ * best-effort exit removal for its first successfully obtained directory.
+ * Worker threads share the process id and so the directory: a probe another
+ * thread rewrites between this one's write and its read is still a stamp minted
+ * before this proof reads.
+ *
+ * Minting is an optimization's precondition, never a requirement. When the
+ * directory cannot be had, either physical address cannot be resolved, or the
+ * probe directory lies inside the physical `root`, every prior reference is
+ * cleared anyway, so no signature is separable and the proof reads content.
+ *
+ * @param root The project or source the probe must lie outside.
+ * @param filesystem The operations whose references the proof judges against.
+ * @evidence contracts/common.md#principled-implementation Detached proofs mint a fresh reference in a process-owned directory outside the observed root; unavailable or inside-root storage clears reference authority instead.
+ * @evidence contracts/common.md#clear-and-simple-design The operation selects process storage then delegates the actual mint to the same reference writer used by generations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No process timestamp substitutes for a filesystem stamp, and failure preserves real content comparison without writing into the user's source tree.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain rollback ordering, directory-entry interference, worker sharing, and exit ownership before stating unavailable-storage behavior.
+ * @evidence contracts/portability.md#os-neutral-implementation The native user-state provider selects process storage; physical root and probe-directory resolution through the supplied coherent native view prevents lexical aliases from concealing containment. Unknown physical identity withdraws reference authority; observed device/time metadata qualifies cross-volume applicability.
+ * @evidence contracts/performance.md#efficient-algorithms Each call pays the state provider's native path/ownership checks and two physical path resolutions before an admitted delegated probe write/lstat. Work includes path text and native observations, not a cached directory lookup; the probe is rewritten rather than opening a temporary tree per proof.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation-free proofs share the same process probe and per-operation reference table while still minting before every proof that depends on separability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The provider's process-named directory and one probe persist between detached proofs. One main-thread listener attempts removal of the first acquired directory, and later session scans attempt dead-process reclamation. Native refusal or changed state-root backing can leave entries; neither exit nor a future scan guarantees successful or timely removal.
+ */
+export declare function refreshProcessClockReference(root: string, filesystem: TtscTransformFilesystemOperations): void;

package/lib/core/transform/clock/refreshProcessClockReference.js

@@ -0,0 +1,87 @@
+'use strict';
+
+var path = require('node:path');
+var node_worker_threads = require('node:worker_threads');
+var pathIsWithin = require('../filesystem/pathIsWithin.js');
+var userStateDirectory = require('../filesystem/userStateDirectory.js');
+var disposeFilesystemClockReference = require('./disposeFilesystemClockReference.js');
+var refreshFilesystemClockReference = require('./refreshFilesystemClockReference.js');
+
+/**
+ * Replace every prior clock proof with one reference minted in the probe
+ * directory this process keeps for the proofs that hold no generation.
+ *
+ * A proof may let a separable signature stand for content only against a
+ * reference minted before its own reads (`filesystemClockReferences`): after a
+ * clock rollback a write can land in the tick of a recorded stamp, and only a
+ * reference minted since the rollback puts that stamp inside it. A generation's
+ * deliveries and capture mint in the probe directory the generation retains. A
+ * proof that holds no generation has none: a failed generation's replay, whose
+ * directory was released with it, a record's proof at a build start, and the
+ * observer's proof of a plugin source.
+ *
+ * Those proofs run at any moment, beside compiles that observe the directories
+ * around them, so minting may change nothing but the probe itself. Creating and
+ * removing a directory per proof would add and remove an entry in the shared
+ * temporary directory, whose metadata other observers read: the absence of a
+ * `package.json` there, for one, is proven by that directory's own metadata
+ * holding still while a plugin descriptor is evaluated. The probe therefore
+ * lives at a process-named directory below this user's current state root
+ * (`userStateDirectory`), whose provider rechecks the native layout on each
+ * call; the probe is rewritten in place. A later session attempts to reclaim
+ * dead-process entries when it scans that state root. The main thread registers
+ * best-effort exit removal for its first successfully obtained directory.
+ * Worker threads share the process id and so the directory: a probe another
+ * thread rewrites between this one's write and its read is still a stamp minted
+ * before this proof reads.
+ *
+ * Minting is an optimization's precondition, never a requirement. When the
+ * directory cannot be had, either physical address cannot be resolved, or the
+ * probe directory lies inside the physical `root`, every prior reference is
+ * cleared anyway, so no signature is separable and the proof reads content.
+ *
+ * @param root The project or source the probe must lie outside.
+ * @param filesystem The operations whose references the proof judges against.
+ * @evidence contracts/common.md#principled-implementation Detached proofs mint a fresh reference in a process-owned directory outside the observed root; unavailable or inside-root storage clears reference authority instead.
+ * @evidence contracts/common.md#clear-and-simple-design The operation selects process storage then delegates the actual mint to the same reference writer used by generations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No process timestamp substitutes for a filesystem stamp, and failure preserves real content comparison without writing into the user's source tree.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain rollback ordering, directory-entry interference, worker sharing, and exit ownership before stating unavailable-storage behavior.
+ * @evidence contracts/portability.md#os-neutral-implementation The native user-state provider selects process storage; physical root and probe-directory resolution through the supplied coherent native view prevents lexical aliases from concealing containment. Unknown physical identity withdraws reference authority; observed device/time metadata qualifies cross-volume applicability.
+ * @evidence contracts/performance.md#efficient-algorithms Each call pays the state provider's native path/ownership checks and two physical path resolutions before an admitted delegated probe write/lstat. Work includes path text and native observations, not a cached directory lookup; the probe is rewritten rather than opening a temporary tree per proof.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation-free proofs share the same process probe and per-operation reference table while still minting before every proof that depends on separability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The provider's process-named directory and one probe persist between detached proofs. One main-thread listener attempts removal of the first acquired directory, and later session scans attempt dead-process reclamation. Native refusal or changed state-root backing can leave entries; neither exit nor a future scan guarantees successful or timely removal.
+ */
+function refreshProcessClockReference(root, filesystem) {
+    const directory = processClockDirectory();
+    let admitted;
+    if (directory !== undefined) {
+        try {
+            const physicalRoot = filesystem.realpath(path.resolve(root));
+            const physicalDirectory = filesystem.realpath(directory);
+            if (!pathIsWithin.pathIsWithin(physicalDirectory, physicalRoot))
+                admitted = directory;
+        }
+        catch {
+            // Unknown native identity cannot establish outside-root storage.
+        }
+    }
+    refreshFilesystemClockReference.refreshFilesystemClockReference(admitted, filesystem);
+}
+/**
+ * This process's probe directory, created when absent, or `undefined` when the
+ * state root cannot hold it; its removal is registered on the main thread's
+ * exit the first time it is found.
+ */
+function processClockDirectory() {
+    const directory = userStateDirectory.userStateDirectory(`${process.pid}-clock`);
+    if (directory !== undefined && node_worker_threads.isMainThread && !exitCleanupRegistered) {
+        exitCleanupRegistered = true;
+        process.once("exit", () => disposeFilesystemClockReference.disposeFilesystemClockReference(directory));
+    }
+    return directory;
+}
+/** Whether the main thread already removes the directory on exit. */
+let exitCleanupRegistered = false;
+
+exports.refreshProcessClockReference = refreshProcessClockReference;
+//# sourceMappingURL=refreshProcessClockReference.js.map

package/lib/core/transform/clock/refreshProcessClockReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshProcessClockReference.js","sources":["../../../../src/core/transform/clock/refreshProcessClockReference.ts"],"sourcesContent":[null],"names":["pathIsWithin","refreshFilesystemClockReference","userStateDirectory","isMainThread","disposeFilesystemClockReference"],"mappings":";;;;;;;;;AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CG;AACG,SAAU,4BAA4B,CAC1C,IAAY,EACZ,UAA6C,EAAA;AAE7C,IAAA,MAAM,SAAS,GAAG,qBAAqB,EAAE;AACzC,IAAA,IAAI,QAA4B;AAChC,IAAA,IAAI,SAAS,KAAK,SAAS,EAAE;AAC3B,QAAA,IAAI;AACF,YAAA,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC5D,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;AACxD,YAAA,IAAI,CAACA,yBAAY,CAAC,iBAAiB,EAAE,YAAY,CAAC;gBAAE,QAAQ,GAAG,SAAS;QAC1E;AAAE,QAAA,MAAM;;QAER;IACF;AACA,IAAAC,+DAA+B,CAAC,QAAQ,EAAE,UAAU,CAAC;AACvD;AAEA;;;;AAIG;AACH,SAAS,qBAAqB,GAAA;IAC5B,MAAM,SAAS,GAAGC,qCAAkB,CAAC,CAAA,EAAG,OAAO,CAAC,GAAG,CAAA,MAAA,CAAQ,CAAC;IAC5D,IAAI,SAAS,KAAK,SAAS,IAAIC,gCAAY,IAAI,CAAC,qBAAqB,EAAE;QACrE,qBAAqB,GAAG,IAAI;AAC5B,QAAA,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAMC,+DAA+B,CAAC,SAAS,CAAC,CAAC;IACxE;AACA,IAAA,OAAO,SAAS;AAClB;AAEA;AACA,IAAI,qBAAqB,GAAG,KAAK;;;;"}

package/lib/core/transform/clock/refreshProcessClockReference.mjs

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { isMainThread } from 'node:worker_threads';
+import { pathIsWithin } from '../filesystem/pathIsWithin.mjs';
+import { userStateDirectory } from '../filesystem/userStateDirectory.mjs';
+import { disposeFilesystemClockReference } from './disposeFilesystemClockReference.mjs';
+import { refreshFilesystemClockReference } from './refreshFilesystemClockReference.mjs';
+
+/**
+ * Replace every prior clock proof with one reference minted in the probe
+ * directory this process keeps for the proofs that hold no generation.
+ *
+ * A proof may let a separable signature stand for content only against a
+ * reference minted before its own reads (`filesystemClockReferences`): after a
+ * clock rollback a write can land in the tick of a recorded stamp, and only a
+ * reference minted since the rollback puts that stamp inside it. A generation's
+ * deliveries and capture mint in the probe directory the generation retains. A
+ * proof that holds no generation has none: a failed generation's replay, whose
+ * directory was released with it, a record's proof at a build start, and the
+ * observer's proof of a plugin source.
+ *
+ * Those proofs run at any moment, beside compiles that observe the directories
+ * around them, so minting may change nothing but the probe itself. Creating and
+ * removing a directory per proof would add and remove an entry in the shared
+ * temporary directory, whose metadata other observers read: the absence of a
+ * `package.json` there, for one, is proven by that directory's own metadata
+ * holding still while a plugin descriptor is evaluated. The probe therefore
+ * lives at a process-named directory below this user's current state root
+ * (`userStateDirectory`), whose provider rechecks the native layout on each
+ * call; the probe is rewritten in place. A later session attempts to reclaim
+ * dead-process entries when it scans that state root. The main thread registers
+ * best-effort exit removal for its first successfully obtained directory.
+ * Worker threads share the process id and so the directory: a probe another
+ * thread rewrites between this one's write and its read is still a stamp minted
+ * before this proof reads.
+ *
+ * Minting is an optimization's precondition, never a requirement. When the
+ * directory cannot be had, either physical address cannot be resolved, or the
+ * probe directory lies inside the physical `root`, every prior reference is
+ * cleared anyway, so no signature is separable and the proof reads content.
+ *
+ * @param root The project or source the probe must lie outside.
+ * @param filesystem The operations whose references the proof judges against.
+ * @evidence contracts/common.md#principled-implementation Detached proofs mint a fresh reference in a process-owned directory outside the observed root; unavailable or inside-root storage clears reference authority instead.
+ * @evidence contracts/common.md#clear-and-simple-design The operation selects process storage then delegates the actual mint to the same reference writer used by generations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No process timestamp substitutes for a filesystem stamp, and failure preserves real content comparison without writing into the user's source tree.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain rollback ordering, directory-entry interference, worker sharing, and exit ownership before stating unavailable-storage behavior.
+ * @evidence contracts/portability.md#os-neutral-implementation The native user-state provider selects process storage; physical root and probe-directory resolution through the supplied coherent native view prevents lexical aliases from concealing containment. Unknown physical identity withdraws reference authority; observed device/time metadata qualifies cross-volume applicability.
+ * @evidence contracts/performance.md#efficient-algorithms Each call pays the state provider's native path/ownership checks and two physical path resolutions before an admitted delegated probe write/lstat. Work includes path text and native observations, not a cached directory lookup; the probe is rewritten rather than opening a temporary tree per proof.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation-free proofs share the same process probe and per-operation reference table while still minting before every proof that depends on separability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The provider's process-named directory and one probe persist between detached proofs. One main-thread listener attempts removal of the first acquired directory, and later session scans attempt dead-process reclamation. Native refusal or changed state-root backing can leave entries; neither exit nor a future scan guarantees successful or timely removal.
+ */
+function refreshProcessClockReference(root, filesystem) {
+    const directory = processClockDirectory();
+    let admitted;
+    if (directory !== undefined) {
+        try {
+            const physicalRoot = filesystem.realpath(path.resolve(root));
+            const physicalDirectory = filesystem.realpath(directory);
+            if (!pathIsWithin(physicalDirectory, physicalRoot))
+                admitted = directory;
+        }
+        catch {
+            // Unknown native identity cannot establish outside-root storage.
+        }
+    }
+    refreshFilesystemClockReference(admitted, filesystem);
+}
+/**
+ * This process's probe directory, created when absent, or `undefined` when the
+ * state root cannot hold it; its removal is registered on the main thread's
+ * exit the first time it is found.
+ */
+function processClockDirectory() {
+    const directory = userStateDirectory(`${process.pid}-clock`);
+    if (directory !== undefined && isMainThread && !exitCleanupRegistered) {
+        exitCleanupRegistered = true;
+        process.once("exit", () => disposeFilesystemClockReference(directory));
+    }
+    return directory;
+}
+/** Whether the main thread already removes the directory on exit. */
+let exitCleanupRegistered = false;
+
+export { refreshProcessClockReference };
+//# sourceMappingURL=refreshProcessClockReference.mjs.map

package/lib/core/transform/clock/refreshProcessClockReference.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshProcessClockReference.mjs","sources":["../../../../src/core/transform/clock/refreshProcessClockReference.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CG;AACG,SAAU,4BAA4B,CAC1C,IAAY,EACZ,UAA6C,EAAA;AAE7C,IAAA,MAAM,SAAS,GAAG,qBAAqB,EAAE;AACzC,IAAA,IAAI,QAA4B;AAChC,IAAA,IAAI,SAAS,KAAK,SAAS,EAAE;AAC3B,QAAA,IAAI;AACF,YAAA,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC5D,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;AACxD,YAAA,IAAI,CAAC,YAAY,CAAC,iBAAiB,EAAE,YAAY,CAAC;gBAAE,QAAQ,GAAG,SAAS;QAC1E;AAAE,QAAA,MAAM;;QAER;IACF;AACA,IAAA,+BAA+B,CAAC,QAAQ,EAAE,UAAU,CAAC;AACvD;AAEA;;;;AAIG;AACH,SAAS,qBAAqB,GAAA;IAC5B,MAAM,SAAS,GAAG,kBAAkB,CAAC,CAAA,EAAG,OAAO,CAAC,GAAG,CAAA,MAAA,CAAQ,CAAC;IAC5D,IAAI,SAAS,KAAK,SAAS,IAAI,YAAY,IAAI,CAAC,qBAAqB,EAAE;QACrE,qBAAqB,GAAG,IAAI;AAC5B,QAAA,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,+BAA+B,CAAC,SAAS,CAAC,CAAC;IACxE;AACA,IAAA,OAAO,SAAS;AAClB;AAEA;AACA,IAAI,qBAAqB,GAAG,KAAK;;;;"}

package/lib/core/transform/clock/stampSeparable.d.cts

@@ -0,0 +1,25 @@
+import type fs from "node:fs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Test the observed modification stamp against its device's current reference.
+ *
+ * A strictly newer minted reference is the separation criterion used by
+ * metadata-qualified content comparison. The caller owns fresh minting before
+ * the relevant read and coherence of the supplied metadata/view. This predicate
+ * only compares those values; it does not independently prove the mint/read
+ * ordering or guarantee unchanged state after the comparison.
+ *
+ * @evidence contracts/common.md#principled-implementation Only a strictly later reference from the same reporting device separates the recorded modification tick; equal or absent reference cannot certify metadata-only reuse.
+ * @evidence contracts/common.md#clear-and-simple-design One device lookup and bigint comparison implement the ordering criterion, leaving fresh minting and content reads with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Device metadata is not replaced by wall time, platform guesses, or a historical maximum that would miss same-tick writes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the strict observed ordering criterion from caller-owned mint/read ordering and filesystem coherence.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral separability uses the observing filesystem's bigint device and nanosecond stamp rather than assuming one timestamp granularity or system-clock origin.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Borrows the view's reference table; lazy table allocation and retained entries have the filesystemClockReferences owner, not independent state or handles here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One map lookup and one bigint comparison.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This scalar query selects no cached verdict or shared content computation; fresh-reference and content/signature reuse permission belong to the callers.
+ */
+export declare function stampSeparable(
+/** Coherent observing view that owns the current device reference. */
+filesystem: TtscTransformFilesystemOperations, 
+/** Observed metadata whose native device and modification stamp are compared. */
+stats: fs.BigIntStats): boolean;

package/lib/core/transform/clock/stampSeparable.d.mts

@@ -0,0 +1,25 @@
+import type fs from "node:fs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Test the observed modification stamp against its device's current reference.
+ *
+ * A strictly newer minted reference is the separation criterion used by
+ * metadata-qualified content comparison. The caller owns fresh minting before
+ * the relevant read and coherence of the supplied metadata/view. This predicate
+ * only compares those values; it does not independently prove the mint/read
+ * ordering or guarantee unchanged state after the comparison.
+ *
+ * @evidence contracts/common.md#principled-implementation Only a strictly later reference from the same reporting device separates the recorded modification tick; equal or absent reference cannot certify metadata-only reuse.
+ * @evidence contracts/common.md#clear-and-simple-design One device lookup and bigint comparison implement the ordering criterion, leaving fresh minting and content reads with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Device metadata is not replaced by wall time, platform guesses, or a historical maximum that would miss same-tick writes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the strict observed ordering criterion from caller-owned mint/read ordering and filesystem coherence.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral separability uses the observing filesystem's bigint device and nanosecond stamp rather than assuming one timestamp granularity or system-clock origin.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Borrows the view's reference table; lazy table allocation and retained entries have the filesystemClockReferences owner, not independent state or handles here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One map lookup and one bigint comparison.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This scalar query selects no cached verdict or shared content computation; fresh-reference and content/signature reuse permission belong to the callers.
+ */
+export declare function stampSeparable(
+/** Coherent observing view that owns the current device reference. */
+filesystem: TtscTransformFilesystemOperations, 
+/** Observed metadata whose native device and modification stamp are compared. */
+stats: fs.BigIntStats): boolean;

package/lib/core/transform/clock/stampSeparable.d.ts

@@ -0,0 +1,25 @@
+import type fs from "node:fs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Test the observed modification stamp against its device's current reference.
+ *
+ * A strictly newer minted reference is the separation criterion used by
+ * metadata-qualified content comparison. The caller owns fresh minting before
+ * the relevant read and coherence of the supplied metadata/view. This predicate
+ * only compares those values; it does not independently prove the mint/read
+ * ordering or guarantee unchanged state after the comparison.
+ *
+ * @evidence contracts/common.md#principled-implementation Only a strictly later reference from the same reporting device separates the recorded modification tick; equal or absent reference cannot certify metadata-only reuse.
+ * @evidence contracts/common.md#clear-and-simple-design One device lookup and bigint comparison implement the ordering criterion, leaving fresh minting and content reads with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Device metadata is not replaced by wall time, platform guesses, or a historical maximum that would miss same-tick writes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the strict observed ordering criterion from caller-owned mint/read ordering and filesystem coherence.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral separability uses the observing filesystem's bigint device and nanosecond stamp rather than assuming one timestamp granularity or system-clock origin.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Borrows the view's reference table; lazy table allocation and retained entries have the filesystemClockReferences owner, not independent state or handles here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One map lookup and one bigint comparison.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This scalar query selects no cached verdict or shared content computation; fresh-reference and content/signature reuse permission belong to the callers.
+ */
+export declare function stampSeparable(
+/** Coherent observing view that owns the current device reference. */
+filesystem: TtscTransformFilesystemOperations, 
+/** Observed metadata whose native device and modification stamp are compared. */
+stats: fs.BigIntStats): boolean;

package/lib/core/transform/clock/stampSeparable.js

@@ -0,0 +1,33 @@
+'use strict';
+
+var filesystemClockReferences = require('./filesystemClockReferences.js');
+
+/**
+ * Test the observed modification stamp against its device's current reference.
+ *
+ * A strictly newer minted reference is the separation criterion used by
+ * metadata-qualified content comparison. The caller owns fresh minting before
+ * the relevant read and coherence of the supplied metadata/view. This predicate
+ * only compares those values; it does not independently prove the mint/read
+ * ordering or guarantee unchanged state after the comparison.
+ *
+ * @evidence contracts/common.md#principled-implementation Only a strictly later reference from the same reporting device separates the recorded modification tick; equal or absent reference cannot certify metadata-only reuse.
+ * @evidence contracts/common.md#clear-and-simple-design One device lookup and bigint comparison implement the ordering criterion, leaving fresh minting and content reads with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Device metadata is not replaced by wall time, platform guesses, or a historical maximum that would miss same-tick writes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the strict observed ordering criterion from caller-owned mint/read ordering and filesystem coherence.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral separability uses the observing filesystem's bigint device and nanosecond stamp rather than assuming one timestamp granularity or system-clock origin.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Borrows the view's reference table; lazy table allocation and retained entries have the filesystemClockReferences owner, not independent state or handles here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One map lookup and one bigint comparison.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This scalar query selects no cached verdict or shared content computation; fresh-reference and content/signature reuse permission belong to the callers.
+ */
+function stampSeparable(
+/** Coherent observing view that owns the current device reference. */
+filesystem, 
+/** Observed metadata whose native device and modification stamp are compared. */
+stats) {
+    const reference = filesystemClockReferences.filesystemClockReferences(filesystem).get(stats.dev);
+    return reference !== undefined && stats.mtimeNs < reference;
+}
+
+exports.stampSeparable = stampSeparable;
+//# sourceMappingURL=stampSeparable.js.map

package/lib/core/transform/clock/stampSeparable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stampSeparable.js","sources":["../../../../src/core/transform/clock/stampSeparable.ts"],"sourcesContent":[null],"names":["filesystemClockReferences"],"mappings":";;;;AAKA;;;;;;;;;;;;;;;;;AAiBG;SACa,cAAc;AAC5B;AACA,UAA6C;AAC7C;AACA,KAAqB,EAAA;AAErB,IAAA,MAAM,SAAS,GAAGA,mDAAyB,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;IACtE,OAAO,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,GAAG,SAAS;AAC7D;;;;"}