ttsc 0.31.1 → 0.31.2

package/lib/plugin/internal/source/PluginBuildEnvironmentReadings.d.ts

@@ -79,16 +79,26 @@ export declare namespace PluginBuildEnvironmentReadings {
      * Read synchronously for clients whose API owns synchronous native work.
      * Explicit refresh preserves the original fresh-comparison semantics.
      *
+     * WARNING (#1725): the map above ends with the process, and every consumer
+     * that proves a plugin-source state starts a new one: a bundler worker, a
+     * capability host, the language server. Without the project's record store
+     * each of them walked and hashed the whole GOROOT (1.7 s for the bundled
+     * toolchain) on its first proof. A caller that names its project lets a miss
+     * prove the SDK and executables from the plugin cache's records.
+     *
+     * @param directory Plugin source directory whose build environment is read.
+     * @param refresh Bypass a cached reading.
+     * @param projectRoot Project whose plugin cache root holds the records.
      * @evidence contracts/common.md#principled-implementation The same native reader constructs a digest paired with its pre-read witness; optional cached reuse validates current variables/metadata. A fresh synchronous reading is published without a separate post-read qualification here and relies on the native reader's premises.
      * @evidence contracts/common.md#clear-and-simple-design The synchronous boundary shares cached authority and delegates fresh observation to its owning reader.
      * @evidence contracts/common.md#prohibited-implementation-shortcuts A requested refresh actually probes the selected native toolchain.
      * @evidence contracts/common.md#meaningful-documentation Native prose identifies the synchronous execution owner and explicit refresh meaning.
      * @evidence contracts/portability.md#os-neutral-implementation Native Go selection and filesystem witnesses remain delegated to the shared reader.
      * @evidence contracts/performance.md#efficient-algorithms Hits pay complete variable-text indexing and native witness queries. Misses/refresh merge environment values, perform actual toolchain/SDK/content work, then rebuild the full variable-text key for publication; native/path/file/name/value bytes contribute cost beyond invocation count.
-     * @evidence contracts/performance.md#reuse-equivalent-work Synchronous and asynchronous clients share the same qualified readings.
+     * @evidence contracts/performance.md#reuse-equivalent-work Synchronous and asynchronous clients share the same qualified readings; a miss of a caller naming its project takes SDK and executable digests from the record store across processes.
      * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retention belongs to the namespace; this call publishes one replacement record.
      */
-    function read(directory: string, refresh?: boolean): string;
+    function read(directory: string, refresh?: boolean, projectRoot?: string): string;
     /**
      * Prepare native authority off the host thread, sharing equivalent concurrent
      * requests. A changed environment or witness during transfer refuses the
@@ -98,6 +108,14 @@ export declare namespace PluginBuildEnvironmentReadings {
      * requests can create a worker after retirement. Refresh bypasses a cached
      * reading but can still share an equivalent in-flight request.
      *
+     * A caller that names its project lets the worker prove the SDK and
+     * executables from the plugin cache's records (#1722). The worker is its own
+     * isolate, so without them it reads the whole GOROOT once per process, which
+     * a bundler or runtime restarting on every edit pays every time.
+     *
+     * @param directory Plugin source directory whose build environment is read.
+     * @param refresh Bypass a cached reading.
+     * @param projectRoot Project whose plugin cache root holds the records.
      * @evidence contracts/common.md#principled-implementation Worker results publish only under their exact current variable identity and still-current native pre-read witness; changed or unwitnessable transfer windows reject instead of publishing authority or retrying indefinitely.
      * @evidence contracts/common.md#clear-and-simple-design Qualified hits return immediately; equivalent misses share one pending promise and exclusive queued worker request.
      * @evidence contracts/common.md#prohibited-implementation-shortcuts Go/environment/SDK preparation occurs in the worker rather than blocking the async host or fabricating a digest from compiler output.
@@ -107,5 +125,5 @@ export declare namespace PluginBuildEnvironmentReadings {
      * @evidence contracts/performance.md#reuse-equivalent-work Pending identity is directory plus complete variables; the warm worker shares native toolchain memos while published authority still requires fresh witness validation.
      * @evidence contracts/performance.md#bound-retention-and-release-resources Pending identity entries are removed in finally at settlement and per-request worker listeners are removed by the terminal path. Idle worker remains unreferenced with lifetime retirement listeners; worker failure initiates termination without awaiting completion. Distinct queued contexts retain environment/witness/promise data without a population bound or timeout, and a stalled producer blocks later queued work.
      */
-    function prepare(directory: string, refresh?: boolean): Promise<string>;
+    function prepare(directory: string, refresh?: boolean, projectRoot?: string): Promise<string>;
 }

package/lib/plugin/internal/source/PluginBuildEnvironmentReadings.js

@@ -9,6 +9,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_worker_threads_1 = require("node:worker_threads");
 const SidecarEnvironment_1 = require("../../../compiler/internal/sharedHost/SidecarEnvironment");
 const PluginBuildEnvironmentWitness_1 = require("./PluginBuildEnvironmentWitness");
+const PluginContentIdentities_1 = require("./PluginContentIdentities");
 const pluginBuildEnvironment_1 = require("./pluginBuildEnvironment");
 /**
  * Share native build-environment observations between synchronous clients and
@@ -101,22 +102,38 @@ var PluginBuildEnvironmentReadings;
      * Read synchronously for clients whose API owns synchronous native work.
      * Explicit refresh preserves the original fresh-comparison semantics.
      *
+     * WARNING (#1725): the map above ends with the process, and every consumer
+     * that proves a plugin-source state starts a new one: a bundler worker, a
+     * capability host, the language server. Without the project's record store
+     * each of them walked and hashed the whole GOROOT (1.7 s for the bundled
+     * toolchain) on its first proof. A caller that names its project lets a miss
+     * prove the SDK and executables from the plugin cache's records.
+     *
+     * @param directory Plugin source directory whose build environment is read.
+     * @param refresh Bypass a cached reading.
+     * @param projectRoot Project whose plugin cache root holds the records.
      * @evidence contracts/common.md#principled-implementation The same native reader constructs a digest paired with its pre-read witness; optional cached reuse validates current variables/metadata. A fresh synchronous reading is published without a separate post-read qualification here and relies on the native reader's premises.
      * @evidence contracts/common.md#clear-and-simple-design The synchronous boundary shares cached authority and delegates fresh observation to its owning reader.
      * @evidence contracts/common.md#prohibited-implementation-shortcuts A requested refresh actually probes the selected native toolchain.
      * @evidence contracts/common.md#meaningful-documentation Native prose identifies the synchronous execution owner and explicit refresh meaning.
      * @evidence contracts/portability.md#os-neutral-implementation Native Go selection and filesystem witnesses remain delegated to the shared reader.
      * @evidence contracts/performance.md#efficient-algorithms Hits pay complete variable-text indexing and native witness queries. Misses/refresh merge environment values, perform actual toolchain/SDK/content work, then rebuild the full variable-text key for publication; native/path/file/name/value bytes contribute cost beyond invocation count.
-     * @evidence contracts/performance.md#reuse-equivalent-work Synchronous and asynchronous clients share the same qualified readings.
+     * @evidence contracts/performance.md#reuse-equivalent-work Synchronous and asynchronous clients share the same qualified readings; a miss of a caller naming its project takes SDK and executable digests from the record store across processes.
      * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retention belongs to the namespace; this call publishes one replacement record.
      */
-    function read(directory, refresh = false) {
+    function read(directory, refresh = false, projectRoot) {
         const known = refresh ? undefined : cached(directory);
         if (known !== undefined)
             return known;
         const env = SidecarEnvironment_1.SidecarEnvironment.merge(process.env);
         const witness = new Map();
-        const environment = (0, pluginBuildEnvironment_1.pluginBuildEnvironment)(directory, env, witness);
+        const environment = (0, pluginBuildEnvironment_1.pluginBuildEnvironment)(directory, env, witness, projectRoot === undefined
+            ? undefined
+            : PluginContentIdentities_1.PluginContentIdentities.open({
+                projectRoot,
+                env,
+                sources: [directory],
+            }));
         readings.set(key(directory, env), { environment, witness });
         return environment;
     }
@@ -130,6 +147,14 @@ var PluginBuildEnvironmentReadings;
      * requests can create a worker after retirement. Refresh bypasses a cached
      * reading but can still share an equivalent in-flight request.
      *
+     * A caller that names its project lets the worker prove the SDK and
+     * executables from the plugin cache's records (#1722). The worker is its own
+     * isolate, so without them it reads the whole GOROOT once per process, which
+     * a bundler or runtime restarting on every edit pays every time.
+     *
+     * @param directory Plugin source directory whose build environment is read.
+     * @param refresh Bypass a cached reading.
+     * @param projectRoot Project whose plugin cache root holds the records.
      * @evidence contracts/common.md#principled-implementation Worker results publish only under their exact current variable identity and still-current native pre-read witness; changed or unwitnessable transfer windows reject instead of publishing authority or retrying indefinitely.
      * @evidence contracts/common.md#clear-and-simple-design Qualified hits return immediately; equivalent misses share one pending promise and exclusive queued worker request.
      * @evidence contracts/common.md#prohibited-implementation-shortcuts Go/environment/SDK preparation occurs in the worker rather than blocking the async host or fabricating a digest from compiler output.
@@ -139,7 +164,7 @@ var PluginBuildEnvironmentReadings;
      * @evidence contracts/performance.md#reuse-equivalent-work Pending identity is directory plus complete variables; the warm worker shares native toolchain memos while published authority still requires fresh witness validation.
      * @evidence contracts/performance.md#bound-retention-and-release-resources Pending identity entries are removed in finally at settlement and per-request worker listeners are removed by the terminal path. Idle worker remains unreferenced with lifetime retirement listeners; worker failure initiates termination without awaiting completion. Distinct queued contexts retain environment/witness/promise data without a population bound or timeout, and a stalled producer blocks later queued work.
      */
-    async function prepare(directory, refresh = false) {
+    async function prepare(directory, refresh = false, projectRoot) {
         const known = refresh ? undefined : cached(directory);
         if (known !== undefined)
             return known;
@@ -149,7 +174,7 @@ var PluginBuildEnvironmentReadings;
         if (existing !== undefined)
             return existing;
         const request = (async () => {
-            const reading = await observe(directory, env);
+            const reading = await observe(directory, env, projectRoot);
             if (identity !== key(directory, process.env) ||
                 !PluginBuildEnvironmentWitness_1.PluginBuildEnvironmentWitness.holds(reading.witness))
                 throw new Error(`ttsc: plugin build environment could not be qualified for ${directory}`);
@@ -173,7 +198,7 @@ var PluginBuildEnvironmentReadings;
                 variables.update(`${name.length}:${name}${value.length}:${value}\0`);
         return `${directory}\0${variables.digest("hex")}`;
     }
-    function observe(directory, env) {
+    function observe(directory, env, projectRoot) {
         const request = queue.then(() => new Promise((resolve, reject) => {
             const current = acquireWorker();
             current.ref();
@@ -214,7 +239,7 @@ var PluginBuildEnvironmentReadings;
             current.on("error", onError);
             current.on("exit", onExit);
             try {
-                current.postMessage({ directory, env });
+                current.postMessage({ directory, env, projectRoot });
             }
             catch (error) {
                 release(false);

package/lib/plugin/internal/source/PluginBuildEnvironmentReadings.js.map

@@ -1 +1 @@
-{"version":3,"file":"PluginBuildEnvironmentReadings.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildEnvironmentReadings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PluginBuildEnvironmentReadings.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildEnvironmentReadings.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/source/PluginContentIdentities.d.ts

@@ -0,0 +1,265 @@
+import fs from "node:fs";
+/**
+ * Content identities a plugin load proves from metadata instead of bytes, kept
+ * in the plugin cache root so they outlive the process that read them.
+ *
+ * WARNING (#1721, #1722, #1723): a warm plugin load must not pay for its
+ * inputs' bytes. Before this owner existed, every launch, every `ttsx` process,
+ * every `@ttsc/unplugin` worker and the build-environment worker re-read the
+ * plugin module, the ttsc overlays, the whole GOROOT and the Go and JavaScript
+ * runtimes, because each earlier fix (#1186, #1712) kept its reuse inside one
+ * process. A process is not the unit of reuse: a CLI launch is one process. Any
+ * new content identity on the load path belongs here, and a memo that only
+ * lives in module state is not a fix for this class.
+ *
+ * A record pairs the digest of a selected population with the metadata
+ * signature of that population, and is trusted only under the separable-stamp
+ * rule settled by #1227 and #1344: every stamp must be strictly older than a
+ * reference minted on the same device by this store's own write, so no later
+ * write can share a recorded tick. References are minted on the cache root's
+ * volume and on the system temporary directory's volume, which together hold
+ * the project, its plugins and toolchain, and a system-installed runtime. A
+ * record is written only when the signature observed before the content read
+ * equals the one observed after it and both are separable. Reuse still assumes
+ * the filesystem reports writes in its metadata (identity, size, modification
+ * and change times); change time moves on every write and cannot be restored by
+ * an ordinary process. A population on a device without a reference, an
+ * unseparable stamp, a missing or foreign record, or any observation failure
+ * falls back to reading content, exactly as before this owner.
+ *
+ * Records live in single-file cache parts (`SourceBuildCacheLayout`), so the
+ * opportunistic collector ages them out and `ttsc clean` removes them. Their
+ * identity includes the record format and the ttsc version, so a release that
+ * changes a digest rule never reads another release's records.
+ *
+ * @evidence contracts/common.md#principled-implementation Metadata stands for recorded content only under the established separable-stamp rule, with before/after agreement around the content read; every unproved premise falls back to the content reader.
+ * @evidence contracts/common.md#clear-and-simple-design One store owns opening, record identity, reuse and publication; callers supply only the population observation and the content reader they already own.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No path-only or process-permanent memo stands for content; failures and unseparable stamps cause the real read rather than a guessed digest.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the regression this owner prevents, the proof premises, the fallback and the storage lifetime.
+ * @evidence contracts/portability.md#os-neutral-implementation References are keyed by the native device that minted them and stamps are compared per device; no timestamp precision or platform name is assumed.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups operations; each member states its own work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members define the reuse identity and its validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Members define what they retain; the namespace holds no state.
+ */
+export declare namespace PluginContentIdentities {
+    /**
+     * One opened record store: the physical cache root and the clock references
+     * minted when it was opened.
+     *
+     * @evidence contracts/common.md#principled-implementation The reference is minted by this store's own write before any observation it judges, so stamps strictly older than it cannot share a later write's tick.
+     * @evidence contracts/common.md#clear-and-simple-design Root, references and version travel together so every record of one load is judged against the references minted for it and one product version.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The record stores observed state, not an expected digest.
+     * @evidence contracts/common.md#meaningful-documentation Members document their provenance and lifetime.
+     * @evidence contracts/portability.md#os-neutral-implementation The reference map is keyed by native device identifiers.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms A record type runs no algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The type grants no reuse by itself; digest owns it.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The opener owns the store for one load or one build; at most two device references are retained.
+     */
+    interface Store {
+        /** Physical cache root that holds the identity and answer parts. */
+        readonly root: string;
+        /**
+         * Modification stamp of a probe written by this store, by device. A stamp
+         * on a device absent here is never separable.
+         */
+        readonly references: ReadonlyMap<bigint, bigint>;
+        /** Ttsc package version entering every record identity. */
+        readonly version: string;
+    }
+    /**
+     * One population's metadata signature and whether every stamp in it is
+     * separable from the store's reference.
+     *
+     * @evidence contracts/common.md#principled-implementation Signature and separability are observed together from the same metadata reading.
+     * @evidence contracts/common.md#clear-and-simple-design Two fields carry exactly what digest compares and admits.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The signature is never treated as content; only the paired record digest is.
+     * @evidence contracts/common.md#meaningful-documentation Members state their meaning.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The observer that builds it owns native metadata semantics.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms A record type runs no algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The type grants no reuse by itself.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns its short lifetime.
+     */
+    interface Observation {
+        /** Whether every stamp precedes the reference of its own device. */
+        readonly separable: boolean;
+        /** Metadata signature of the whole selected population. */
+        readonly signature: string;
+    }
+    /**
+     * Open the store under a plugin cache root and mint its clock reference, or
+     * return `undefined` when the root cannot hold records, so callers read
+     * content as they did without one.
+     *
+     * The root follows the plugin cache policy (`resolveSourceBuildCachePaths`):
+     * an explicit `cacheDir`, `TTSC_CACHE_DIR`, or the workspace-local default. A
+     * default root is marked as selected before its first write, as every other
+     * default writer does, so a later root search never mistakes the new payload
+     * for an older orphan. One reference is minted in the root's identity
+     * directory, and the store exists only when that write succeeds. Another is
+     * minted in a private per-user directory below the system temporary
+     * directory, so an executable or SDK on the system volume is separable even
+     * when the project lives on another volume.
+     *
+     * A root inside any of `sources` is refused before anything is written: the
+     * build rejects such a cache (`SourcePluginAdmission`), and a record written
+     * there would change the very source it describes.
+     *
+     * @param props.projectRoot Project whose cache root is selected.
+     * @param props.cacheDir Explicit caller cache root, when one was given.
+     * @param props.env Effective environment selecting `TTSC_CACHE_DIR`.
+     * @param props.sources Plugin source directories the root must lie outside.
+     * @evidence contracts/common.md#principled-implementation The plugin cache policy selects the root, default roots are marked before payload, and the reference comes from a fresh owned probe; any failure withholds the store so callers keep the content path.
+     * @evidence contracts/common.md#clear-and-simple-design Root policy and the probe are delegated to their existing owners; this function composes them once per load.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No wall clock or historical stamp substitutes for the minted reference.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs state root selection, the marker ordering and the undefined fallback.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and the probe's device identity carry platform semantics; Windows environment names are read case-insensitively by the shared reader.
+     * @evidence contracts/performance.md#efficient-algorithms Root selection can walk ancestors and read manifests; each of the two probes performs one directory creation, one write, one lstat and one removal; the temporary one also checks its directory's ownership. No plugin source is read.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each load needs a freshly minted reference; reusing an older one would defeat the separation premise.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Each probe is removed in its owner's finally; the per-user temporary directory stays, empty, for later loads so the temporary directory itself does not move. The returned store retains at most two device references and two strings.
+     */
+    function open(props: {
+        projectRoot: string;
+        cacheDir?: string;
+        env: NodeJS.ProcessEnv;
+        sources?: readonly string[];
+    }): Store | undefined;
+    /**
+     * The store when its root lies outside every one of `sources`, otherwise
+     * `undefined`. A loader opens its store before descriptor evaluation names
+     * the plugin sources, then narrows it here before any source is proven, so a
+     * misplaced cache, which the build rejects, never receives records inside a
+     * user's source tree.
+     *
+     * @param store The opened store, if any.
+     * @param sources Plugin source directories the root must lie outside.
+     * @evidence contracts/common.md#principled-implementation The build's own containment predicate (`pluginSourceCovers`) decides, so a root below a pruned directory is admitted exactly as the build admits it.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate shared by open and late narrowing.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A covered root withdraws persistence rather than writing into a source.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains the two-phase opening.
+     * @evidence contracts/portability.md#os-neutral-implementation Containment uses native path grammar.
+     * @evidence contracts/performance.md#efficient-algorithms One relative-path check per source.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A predicate over current arguments.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Nothing is retained.
+     */
+    function outside(store: Store | undefined, sources: readonly string[]): Store | undefined;
+    /**
+     * The digest of one population: the recorded one while its metadata still
+     * holds and is separable, otherwise a fresh content reading, recorded when
+     * its metadata held still and separable around the read.
+     *
+     * A population whose selection would include the store's own root is never
+     * recorded, since writing a record would change what it describes; a root
+     * below a pruned directory such as `node_modules` is outside every
+     * selection.
+     *
+     * @param store The opened store, or `undefined` to read content only.
+     * @param kind Population family; records of different families never mix.
+     * @param subject Absolute population path identifying the record.
+     * @param observe Current signature of the population against references.
+     * @param read The owning content reader; its result is the digest.
+     * @evidence contracts/common.md#principled-implementation A record is used only when the current separable signature equals the recorded one; publication requires equal separable signatures before and after the actual content read.
+     * @evidence contracts/common.md#clear-and-simple-design The caller keeps population selection and content hashing; this function owns only lookup, admission and publication.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Corrupt, foreign or unproved records cause the real read; the record cannot widen what the caller's reader covers.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the reuse condition and the self-containment exclusion; parameters describe their roles.
+     * @evidence contracts/portability.md#os-neutral-implementation Separability is the observer's per-device judgement; record files use native path joins and atomic same-directory replacement.
+     * @evidence contracts/performance.md#efficient-algorithms A hit costs one population observation and one small record read; a miss adds the content read and a second observation. Record identity hashes fixed framing text.
+     * @evidence contracts/performance.md#reuse-equivalent-work Processes share a digest only for the same family, subject, version and current separable signature that the producing read was bracketed by.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources One small file per subject is published atomically and aged out by the single-file collector; hits refresh its use time; nothing is retained in memory.
+     */
+    function digest(store: Store | undefined, kind: string, subject: string, observe: (references: ReadonlyMap<bigint, bigint>) => Observation | undefined, read: () => string): string;
+    /**
+     * The `pluginSourceDigest` of a plugin source directory, proven from the
+     * metadata of exactly the files that digest reads.
+     *
+     * @param store The opened store, or `undefined` to read content only.
+     * @param directory The source directory.
+     * @evidence contracts/common.md#principled-implementation The signature walks the same `collectPluginSourceFiles` population the digest reads, with the capability cache's separable-stamp evidence; additions, removals and renames change that population.
+     * @evidence contracts/common.md#clear-and-simple-design Selection and hashing remain with their owners; this adapter only names the family and subject.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Links and unreadable files fail as the content reader would; no metadata stands for a file the digest does not read.
+     * @evidence contracts/common.md#meaningful-documentation Native prose names the shared population.
+     * @evidence contracts/portability.md#os-neutral-implementation Native lstat device/inode/link/mode/size/stamps form each file's signature.
+     * @evidence contracts/performance.md#efficient-algorithms A hit enumerates and stats F files without reading content; a miss also reads B bytes and stats again.
+     * @evidence contracts/performance.md#reuse-equivalent-work Loads in any process share a directory digest while its separable signature holds.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Storage belongs to digest.
+     */
+    function sourceDirectory(store: Store | undefined, directory: string): string;
+    /**
+     * One regular file's metadata signature, following links, and whether its
+     * stamp is separable; `undefined` when it cannot be stated.
+     *
+     * @param references The store's device references.
+     * @param file The file, normally already resolved to its physical path.
+     * @evidence contracts/common.md#principled-implementation Device, inode, mode, size and both stamps move on replacement or write; separability requires a same-device reference strictly newer than the modification stamp.
+     * @evidence contracts/common.md#clear-and-simple-design One stat produces both fields used by digest.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A non-regular or unreadable file yields no observation, so the content reader decides.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the following-link semantics and undefined meaning.
+     * @evidence contracts/portability.md#os-neutral-implementation Node bigint stat supplies native identity and nanosecond stamps.
+     * @evidence contracts/performance.md#efficient-algorithms One native stat and fixed numeric formatting.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is a fresh observation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Nothing is retained.
+     */
+    function fileObservation(references: ReadonlyMap<bigint, bigint>, file: string): Observation | undefined;
+    /**
+     * Whether a stamp is strictly older than the reference its device minted.
+     *
+     * @param references The store's device references.
+     * @param stats Observed metadata.
+     * @evidence contracts/common.md#principled-implementation Only a strictly newer same-device reference separates the recorded modification tick.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup and one comparison.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing reference is never replaced by wall time.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the strict ordering.
+     * @evidence contracts/portability.md#os-neutral-implementation References are matched by native device identifier.
+     * @evidence contracts/performance.md#efficient-algorithms One map lookup and one bigint comparison.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A scalar predicate.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Nothing is retained.
+     */
+    function separable(references: ReadonlyMap<bigint, bigint>, stats: fs.BigIntStats): boolean;
+    /**
+     * A clock reference minted by a write of the cache's own: the modification
+     * stamp a fresh probe file got in `directory`, by the device that reported
+     * it.
+     *
+     * A stamp strictly older than the same device's fresh reference satisfies the
+     * separation policy. Reuse still assumes the filesystem's reported metadata
+     * reflects writes; the comparison cannot certify arbitrary timestamp
+     * restoration or future clock behavior. The probe is the cache's own file,
+     * named for this call, and removal is attempted at once, so concurrent
+     * readers never lend each other a reference. A failed write, or a population
+     * on another device, leaves nothing separable, and the proof reads the
+     * files.
+     *
+     * @param directory Cache-owned directory the probe is written in.
+     * @evidence contracts/common.md#principled-implementation A unique freshly-written file supplies its native device/mtime reference; acquisition failure clears the witness, and observers require a matching device and strictly older reported stamp under the metadata policy.
+     * @evidence contracts/common.md#clear-and-simple-design The function returns only device-to-stamp evidence and owns its transient probe from creation through cleanup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Random probe identity avoids borrowing a concurrent call's witness; failed acquisition does not substitute wall-clock guesses for device evidence.
+     * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains ended ticks, cross-device refusal and probe lifetime in separate paragraphs; tag separation follows the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Native joins and bigint lstat use the actual filesystem's device/stamp values; no fixed timestamp precision or OS-specific temp path is assumed.
+     * @evidence contracts/performance.md#efficient-algorithms Probe path/UUID/hrtime text construction and mkdir/write/lstat/removal queries produce a witness without reading any population bytes.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each proof needs a fresh clock reference; sharing an earlier probe would defeat the rollback/separation premise.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The unique call-owned probe is removed in finally even after acquisition failure; removal is best effort and the returned map contains at most its single observed device.
+     */
+    function mintReference(directory: string): ReadonlyMap<bigint, bigint>;
+    /**
+     * One plugin source file's metadata signature, and whether its stamp is
+     * separable from `references`, for `pluginSourceFilesSignature`.
+     *
+     * The files the digest reads are regular files (`collectPluginSourceFiles`),
+     * so these fields are the observer's metadata signature. Native metadata
+     * reflecting a write/replacement is a reuse premise; the signature is not
+     * itself a content hash or proof against arbitrary timestamp restoration.
+     *
+     * @param references The clock references minted for this proof.
+     * @evidence contracts/common.md#principled-implementation lstat device/inode/link/mode/size/timestamps form the regular-file metadata signature; strict mtime-before-reference marks separation for a matching device under the native metadata policy, without observing content.
+     * @evidence contracts/common.md#clear-and-simple-design A closure carries one proof's device references and maps each requested file to signature/separation together.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unreadable files return no witness, and unmatched device or same/newer stamps cannot authorize digest reuse.
+     * @evidence contracts/common.md#meaningful-documentation Native JSDoc states the regular-file premise and reference origin, with separate acknowledgment prose following the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Metadata comes from native bigint lstat and actual device IDs; separators join numeric fields only and no host path is manually parsed.
+     * @evidence contracts/performance.md#efficient-algorithms Each invocation performs native path/lstat work and formats seven bigint fields without reading content.
+     * @evidence contracts/performance.md#reuse-equivalent-work The closure reuses one reference map across files in the same proof, while each file's current metadata is read anew.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The closure retains the supplied reference map until its consumer releases it; no file handle or global population is retained.
+     */
+    function sourceEvidence(references: ReadonlyMap<bigint, bigint>): (file: string) => {
+        separable: boolean;
+        signature: string;
+    } | undefined;
+}