ttsc 0.31.0 → 0.31.2

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

@@ -0,0 +1,452 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginContentIdentities = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const SidecarEnvironment_1 = require("../../../compiler/internal/sharedHost/SidecarEnvironment");
+const E2ETrace_1 = require("../../../internal/E2ETrace");
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+const pluginSourceCovers_1 = require("./pluginSourceCovers");
+const pluginSourceDigest_1 = require("./pluginSourceDigest");
+const pluginSourceFilesSignature_1 = require("./pluginSourceFilesSignature");
+const recordCacheFileUse_1 = require("./recordCacheFileUse");
+const resolveSourceBuildCachePaths_1 = require("./resolveSourceBuildCachePaths");
+const ttscPackageVersion_1 = require("./ttscPackageVersion");
+/**
+ * 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.
+ */
+var PluginContentIdentities;
+(function (PluginContentIdentities) {
+    /**
+     * 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) {
+        try {
+            const selected = (0, resolveSourceBuildCachePaths_1.resolveSourceBuildCachePaths)(props.projectRoot, props.cacheDir, props.env).root;
+            if (coversRoot(selected, props.sources ?? []))
+                return undefined;
+            const root = props.cacheDir || SidecarEnvironment_1.SidecarEnvironment.read(props.env, "TTSC_CACHE_DIR")
+                ? selected
+                : SourceBuildCacheLayout_1.SourceBuildCacheLayout.markDefaultWorkspaceCacheRoot(selected);
+            const owned = mintReference(node_path_1.default.join(root, SourceBuildCacheLayout_1.SourceBuildCacheLayout.IDENTITY_CACHE_DIRNAME));
+            if (owned.size === 0)
+                return undefined;
+            // The cache root's device covers the project, its installed plugins and
+            // the toolchain bundled with them. A runtime or SDK installed elsewhere,
+            // typically on the system drive, is judged against a second reference
+            // minted in a per-user directory below the system temporary directory.
+            const references = new Map([...temporaryReference(), ...owned]);
+            // WARNING (#1726): resolve no module here. A descriptor evaluator opens a
+            // store under its resolution recorder, and any lookup becomes an input of
+            // the descriptor it did not read (`ttscPackageVersion`).
+            return { root, references, version: (0, ttscPackageVersion_1.ttscPackageVersion)() };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    PluginContentIdentities.open = open;
+    /**
+     * 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, sources) {
+        return store === undefined || coversRoot(store.root, sources)
+            ? undefined
+            : store;
+    }
+    PluginContentIdentities.outside = outside;
+    /**
+     * 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, kind, subject, observe, read) {
+        if (store === undefined ||
+            (0, pluginSourceCovers_1.pluginSourceCovers)(subject, store.root, "directory"))
+            return read();
+        const file = recordFile(store, kind, subject);
+        const before = observe(store.references);
+        if (before?.separable === true) {
+            const known = readRecord(file);
+            if (known !== undefined &&
+                known.signature === before.signature &&
+                known.version === store.version &&
+                known.kind === kind &&
+                known.subject === subject) {
+                (0, recordCacheFileUse_1.recordCacheFileUse)(file);
+                E2ETrace_1.E2ETrace.capabilityResolution("plugin-content-identity", {
+                    kind,
+                    subject,
+                    outcome: "reused",
+                });
+                return known.digest;
+            }
+        }
+        const value = read();
+        const after = observe(store.references);
+        const recorded = before?.separable === true &&
+            after?.separable === true &&
+            before.signature === after.signature;
+        if (recorded) {
+            try {
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+                SourceBuildCacheLayout_1.SourceBuildCacheLayout.replaceCacheMetadataFile(file, JSON.stringify({
+                    format: FORMAT,
+                    version: store.version,
+                    kind,
+                    subject,
+                    signature: after.signature,
+                    digest: value,
+                }));
+            }
+            catch {
+                // A record is an optimization; the digest just read stands.
+            }
+        }
+        E2ETrace_1.E2ETrace.capabilityResolution("plugin-content-identity", {
+            kind,
+            subject,
+            outcome: recorded ? "recorded" : "read",
+        });
+        return value;
+    }
+    PluginContentIdentities.digest = digest;
+    /**
+     * 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, directory) {
+        const resolved = node_path_1.default.resolve(directory);
+        return digest(store, "plugin-source", resolved, (references) => (0, pluginSourceFilesSignature_1.pluginSourceFilesSignature)(resolved, sourceEvidence(references)), () => (0, pluginSourceDigest_1.pluginSourceDigest)(resolved));
+    }
+    PluginContentIdentities.sourceDirectory = sourceDirectory;
+    /**
+     * 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, file) {
+        try {
+            const stats = node_fs_1.default.statSync(file, { bigint: true });
+            if (!stats.isFile())
+                return undefined;
+            return {
+                separable: separable(references, stats),
+                signature: [
+                    stats.dev,
+                    stats.ino,
+                    stats.mode,
+                    stats.size,
+                    stats.mtimeNs,
+                    stats.ctimeNs,
+                ].join(":"),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    PluginContentIdentities.fileObservation = fileObservation;
+    /**
+     * 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, stats) {
+        const minted = references.get(stats.dev);
+        return minted !== undefined && stats.mtimeNs < minted;
+    }
+    PluginContentIdentities.separable = separable;
+    /**
+     * 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) {
+        const references = new Map();
+        const probe = node_path_1.default.join(directory, `clock-${process.pid}-${node_crypto_1.default.randomUUID()}.probe`);
+        try {
+            node_fs_1.default.mkdirSync(directory, { recursive: true });
+            node_fs_1.default.writeFileSync(probe, `${process.hrtime.bigint()}\n`);
+            const stats = node_fs_1.default.lstatSync(probe, { bigint: true });
+            references.set(stats.dev, stats.mtimeNs);
+        }
+        catch {
+            references.clear();
+        }
+        finally {
+            try {
+                node_fs_1.default.rmSync(probe, { force: true });
+            }
+            catch {
+                // A leftover probe contains this call's hrtime text, not source data.
+            }
+        }
+        return references;
+    }
+    PluginContentIdentities.mintReference = mintReference;
+    /**
+     * 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) {
+        return (file) => {
+            try {
+                const stats = node_fs_1.default.lstatSync(file, { bigint: true });
+                return {
+                    separable: separable(references, stats),
+                    signature: [
+                        stats.dev,
+                        stats.ino,
+                        stats.nlink,
+                        stats.mode,
+                        stats.size,
+                        stats.mtimeNs,
+                        stats.ctimeNs,
+                    ].join(":"),
+                };
+            }
+            catch {
+                return undefined;
+            }
+        };
+    }
+    PluginContentIdentities.sourceEvidence = sourceEvidence;
+    /**
+     * Record format tag. Move it whenever the record shape or the meaning of a
+     * family's digest changes; the ttsc version already separates releases.
+     */
+    const FORMAT = "ttsc-content-identity-v1";
+    /** Directory below the system temporary directory that holds its probes. */
+    const TEMPORARY_REFERENCE_DIRNAME = "ttsc-clock-references";
+    // The temporary-volume reference lives in one directory reused by every
+    // load: creating and removing an entry of the temporary directory itself on
+    // each load would move that directory's metadata, which is the signature of
+    // every missing path below it a descriptor proof observed (#1721). A shared
+    // directory such as POSIX `/tmp` is writable by every user and a fixed name
+    // there could be another user's, so the directory is named for this user,
+    // created private, and used only while it is a real directory this user owns
+    // that nobody else can write to.
+    function temporaryReference() {
+        try {
+            const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+            const directory = node_path_1.default.join(node_os_1.default.tmpdir(), uid === undefined
+                ? TEMPORARY_REFERENCE_DIRNAME
+                : `${TEMPORARY_REFERENCE_DIRNAME}-${uid}`);
+            try {
+                node_fs_1.default.mkdirSync(directory, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    return new Map();
+            }
+            const stats = node_fs_1.default.lstatSync(directory);
+            if (!stats.isDirectory() ||
+                (uid !== undefined && (stats.uid !== uid || (stats.mode & 0o022) !== 0)))
+                return new Map();
+            return mintReference(directory);
+        }
+        catch {
+            return new Map();
+        }
+    }
+    function coversRoot(root, sources) {
+        const resolved = node_path_1.default.resolve(root);
+        return sources.some((source) => (0, pluginSourceCovers_1.pluginSourceCovers)(node_path_1.default.resolve(source), resolved, "directory"));
+    }
+    function recordFile(store, kind, subject) {
+        const key = node_crypto_1.default
+            .createHash("sha256")
+            .update(JSON.stringify([FORMAT, store.version, kind, subject]))
+            .digest("hex");
+        return node_path_1.default.join(store.root, SourceBuildCacheLayout_1.SourceBuildCacheLayout.IDENTITY_CACHE_DIRNAME, `${key}.json`);
+    }
+    function readRecord(file) {
+        try {
+            const value = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+            return value.format === FORMAT &&
+                typeof value.version === "string" &&
+                typeof value.kind === "string" &&
+                typeof value.subject === "string" &&
+                typeof value.signature === "string" &&
+                typeof value.digest === "string"
+                ? value
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+})(PluginContentIdentities || (exports.PluginContentIdentities = PluginContentIdentities = {}));
+//# sourceMappingURL=PluginContentIdentities.js.map

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

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

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

@@ -0,0 +1,63 @@
+import type { PluginContentIdentities } from "./PluginContentIdentities";
+/**
+ * Answers a plugin load computed from inputs it could identify by content, kept
+ * in the plugin cache root under that identity so a later process with equal
+ * inputs reads the answer instead of computing it again.
+ *
+ * WARNING (#1721, #1723): the key is the whole proof. A caller must fold into
+ * `identity` every input that can change the answer, as content identities
+ * (`PluginContentIdentities`) or the authoritative live probe results, never a
+ * path, a timestamp or a value it merely expects to be stable. An answer is
+ * written only after the computation succeeded on inputs the caller proved
+ * unchanged around it; a failed or unproved computation is never recorded,
+ * since a later process could not tell it from a current one.
+ *
+ * Entries are single files published by rename, aged out by the single-file
+ * collector and removed by `ttsc clean`. Their identity includes the format tag
+ * and the ttsc version, so another release never reads them.
+ *
+ * @evidence contracts/common.md#principled-implementation The content-addressed key carries every caller-declared input identity; reads accept only a matching format, version and kind, and writes are refused for unproved computations by the caller contract.
+ * @evidence contracts/common.md#clear-and-simple-design One owner stores and loads opaque answers; callers own key composition, validation of the answer shape and the decision to record.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No answer is guessed; a missing, corrupt or foreign entry is a miss and the caller computes.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the key contract that prevents stale answers, the recording rule and the storage lifetime.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path joins and same-directory rename publication; keys are hashed text, independent of path dialect.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members state their own costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members define reuse through the caller's identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Members state retention; the namespace holds no state.
+ */
+export declare namespace PluginLoadAnswers {
+    /**
+     * The answer recorded for `identity`, or `undefined` when none is.
+     *
+     * @param store The opened store, or `undefined` for no persistence.
+     * @param kind Answer family; families never share entries.
+     * @param identity Every input identity the answer depends on.
+     * @evidence contracts/common.md#principled-implementation An entry is returned only for the same format, version, kind and identity hash; the caller validates the value's shape.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup returns an opaque value or undefined.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unreadable or foreign entries are misses.
+     * @evidence contracts/common.md#meaningful-documentation Parameters describe the identity contract.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path join and file read.
+     * @evidence contracts/performance.md#efficient-algorithms Hashes the serialized identity and reads one small file; a hit refreshes its use time.
+     * @evidence contracts/performance.md#reuse-equivalent-work Processes share an answer only for an identical serialized identity under the same version.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Nothing is retained in memory; the collector owns entry lifetime.
+     */
+    function read(store: PluginContentIdentities.Store | undefined, kind: string, identity: unknown): unknown;
+    /**
+     * Record `value` as the answer for `identity`. Failures are ignored: the
+     * answer just computed stands, and the next process computes it again.
+     *
+     * @param store The opened store, or `undefined` for no persistence.
+     * @param kind Answer family.
+     * @param identity Every input identity the answer depends on.
+     * @param value JSON-serializable answer the caller proved for `identity`.
+     * @evidence contracts/common.md#principled-implementation Publication happens only when the caller decided the computation was proven; the entry records the same identity framing that read checks.
+     * @evidence contracts/common.md#clear-and-simple-design One atomic publication through the shared metadata writer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed write never fails the load or fabricates an entry.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states failure behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation Same-directory staging and rename through the shared writer.
+     * @evidence contracts/performance.md#efficient-algorithms Serializes the identity and value once and writes one small file.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Publication creates the reusable entry; read owns reuse.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources One file per identity, removed by the single-file collector or `ttsc clean`; staging cleanup belongs to the shared writer.
+     */
+    function write(store: PluginContentIdentities.Store | undefined, kind: string, identity: unknown, value: unknown): void;
+}