@ttsc/metro 0.30.4 → 0.31.0

package/lib/core/fingerprint.d.ts

@@ -1,60 +1,23 @@
-/**
- * Project fingerprint and reference-graph snapshot for `@ttsc/metro`.
- *
- * Metro's transform cache keys each file on its own content plus one static
- * transformer key computed once per run (`getCacheKey`, called on the main
- * process at `Transformer` construction). A ttsc transform's output can depend
- * on inputs Metro never keys: other project sources reached through type-only
- * edges, `node_modules` declarations, monorepo sibling sources, and the
- * tsconfig `extends` ancestry. This module folds all of them into the static
- * key so the cache key incorporates every input that can influence a
- * transform's output:
- *
- * - **Project walk.** Every input file under the fingerprint roots (Metro's
- *   `projectRoot` plus the resolved tsconfig's directory when it lies outside),
- *   hashed with the exact walk universe the `@ttsc/unplugin` transform core
- *   validates its own cache against.
- * - **Recorded transform inputs.** The host-owned reference graph
- *   (samchon/ttsc#718) reports each transform's derived inputs. Workers retain
- *   them under `node_modules/.cache/ttsc-metro`, compare their generation state
- *   with the exact main-process key baseline, and batch one durable write per
- *   delivered module.
- *
- * Snapshot layout: one main file carrying a random epoch id plus per-worker
- * files with unique names, so concurrent workers never race a shared write.
- * `withTtsc` compacts worker files into the main file before its workers exist,
- * under a process-shared lock for builds using the same project cache. Readers
- * take the union of every file, reading the worker files strictly before the
- * main file: the compactor renames the merged main into place strictly before
- * deleting a worker file, so a worker file that disappears mid-read is always
- * already merged into the main the reader loads afterwards.
- *
- * Sound degradations, by design:
- *
- * - No readable snapshot (first run, wiped cache dir, unwritable filesystem)
- *   folds a random nonce: that run shares no cache entries with any other run.
- * - A failed snapshot write persists the pending observation beside the snapshot
- *   directory. While any such recovery document exists, readers fold a nonce;
- *   successful compaction merges it and mints a fresh epoch.
- * - A recreated snapshot carries a fresh epoch id, so it can never alias a key
- *   from an older epoch whose recorded set is unknown.
- * - A plugin-declared volatile output (non-file inputs; unrepresentable in any
- *   file fingerprint) marks the snapshot volatile, which also folds a nonce
- *   until a later run records the volatile declaration gone.
- * - A recorded input that disappears hashes as a stable `missing` marker, so
- *   deletion and reappearance both move the key.
- * - A worker state that differs from the static key's run baseline taints the
- *   observation; compaction rotates the epoch so even A -> B -> A cannot reuse
- *   output stored under the earlier A key.
- */
-import { readProjectMembershipPolicy } from "@ttsc/unplugin/api";
-import type { TtscProjectDiscoveryFilesystem, TtscProjectTreeDiscoveryFilesystem, TtscWatchInput } from "@ttsc/unplugin/api";
+import type { TtscProjectDiscoveryFilesystem, TtscProjectTreeDiscoveryFilesystem, TtscWatchInput, TtscWatchInputBaseline } from "@ttsc/unplugin/api";
+import type { SnapshotReadOperations } from "./SnapshotReadOperations";
+import type { TtscMetroProjectView } from "./TtscMetroProjectView";
+/** Requested native codecs, separate from compiler-accessible entry listings. */
+type NativeInputKind = keyof NonNullable<TtscWatchInputBaseline["nativePredicates"]>;
 /** Union of the snapshot state readable on disk. */
 interface SnapshotState {
+    /** Native version-one kinds to observe again for each recorded path. */
+    nativePredicates: Record<string, NativeInputKind[]>;
+    /** Paths whose compiler-visible immediate entry listings affect output. */
+    accessibleEntries: string[];
     /** Random epoch id minted when the main snapshot was created. */
     id: string;
     /** Absolute paths of every recorded derived transform input. */
     files: string[];
+    /**
+     * The recorded inputs that are plugin source directories, each also in
+     * `files`, whose state the static key carries (samchon/ttsc#1487).
+     */
+    trees: string[];
     /** Whether any recorded transform declared volatile output. */
     volatile: boolean;
     /** Whether a transform observed state different from its run's static key. */
@@ -66,52 +29,146 @@ interface SnapshotState {
  * from Metro's cache-key options, the transformer from each file's transform
  * options — all the same value in a real Metro run), else the working directory
  * Metro was launched from.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node path.resolve provides one agreed base for config preparation, static
+ *   keying and worker recording. A nonempty projectRoot wins; absent or empty
+ *   input uses cwd.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One helper defines the shared base fallback for preparation, keying and
+ *   worker recording instead of giving each boundary its own anchor policy.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   This operation delegates one path resolution and chooses a fallback; it
+ *   owns no collection-processing strategy.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The base depends on caller input and current cwd; this pure mapping
+ *   coordinates no shared computation.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   It returns a directory string and owns no retained state or handle.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   It computes a directory value without changing the filesystem, foreign
+ *   APIs or consumer-specific behavior.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node path.resolve and process.cwd handle native path roots and separators
+ *   on supported OSes. No URL conversion or process spawning occurs.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains shared base ownership and the absent/empty
+ *   projectRoot fallback. Checked against the documentation skill: separate
+ *   paragraphs state the contract and why its nonobvious boundary matters;
+ *   field comments retain their own useful facts.
  */
 export declare function resolveFingerprintBase(projectRoot: string | undefined): string;
 /**
- * The directories whose walk universes the fingerprint hashes: the base
- * directory, plus the resolved tsconfig's directory when the tsconfig is not
- * already inside the base walk (an explicit out-of-root `project`, or a
- * monorepo-root tsconfig discovered above the app). Matching the transform
- * core's own validation universe keeps the invariant simple: everything the
- * core treats as an input is fingerprinted by the walk, the recorded snapshot,
- * or both.
+ * The directories whose walk universes the fingerprint hashes. Implicit
+ * selection searches from the base upward, so a config at the base uses that
+ * walk and a config above it replaces the base walk with its own directory,
+ * which contains the base. An explicit project inside the base uses the base
+ * walk; one above the base replaces it; one elsewhere adds its directory. The
+ * separate per-file project view can select a nested config below the base.
+ * Matching the transform core's validation universe keeps the invariant simple:
+ * everything it treats as an input is fingerprinted by the walk, the recorded
+ * snapshot, or both.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The shared project resolver owns tsconfig selection; lexical path
+ *   containment is separate from program membership.
+ *   Blank explicit options mean implicit discovery. An in-root config avoids a
+ *   duplicate whole-tree walk; a config above the base walks its own directory,
+ *   which contains the base, instead of hashing the base subtree twice; an
+ *   unrelated out-of-root config adds its directory because it can supply
+ *   transform inputs.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Project selection delegates to the shared resolver and containment to
+ *   projectViewRoots, separating config ownership from walk-root choice.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   It delegates shared project discovery and computes at most two roots;
+ *   traversal cost belongs to that resolver and the fingerprint operation.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This mapping retains no discovery result between calls and coordinates
+ *   no completed or in-flight computation.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Roots transfer to the caller; no retained state or handle is acquired.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No fixture-specific roots or patched filesystem APIs are used.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node resolve and dirname handle Windows drives and POSIX roots. Lexical
+ *   containment compares complete path components with only volume-root case
+ *   normalization; it does not merge distinct native names by OS assumption.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains walk roots, implicit selection and why outside
+ *   configs extend coverage. Checked against the documentation skill:
+ *   separate paragraphs state the contract and why its nonobvious boundary
+ *   matters; field comments retain their own useful facts.
  */
 export declare function fingerprintRoots(base: string, explicitProject: string | undefined): string[];
-/**
- * One project, and the membership policy that describes it.
- *
- * The recorder's question is whether the project walk already covers an input,
- * so it needs both the walk's roots and the policy that walk used, and it is
- * wrong exactly when those two describe different projects. Passing them
- * separately made that mismatch expressible — the policy for one project
- * alongside the root of another — and passing the policy alone made it
- * expressible in a quieter way still, since a recorder that resolved its own
- * could describe a different program than the walk hashed. Both halves travel
- * together so neither can be supplied without the other (samchon/ttsc#1316).
- */
-export interface TtscMetroProjectView {
-    /** The base directory both fingerprint sides agree on. */
-    readonly base: string;
-    /** Config candidates observed while selecting this transform's project. */
-    readonly discoveryInputs: readonly TtscWatchInput[];
-    /** The caller's explicit `project`, if any. */
-    readonly explicitProject: string | undefined;
-    /** The membership policy resolved for that project. */
-    readonly policy: ReturnType<typeof readProjectMembershipPolicy>;
-    /** The policy used by the routed static walk. */
-    readonly walkPolicy: ReturnType<typeof readProjectMembershipPolicy>;
-    /** Lexical roots whose fingerprint uses this project's policy. */
-    readonly roots: readonly string[];
-    /** The exact config selected for this project. */
-    readonly tsconfig: string;
-}
 /**
  * Resolve one transform's project view, once, for every watch input it reports.
  *
- * Exported because the recorder is asked once per input while the answer is a
- * property of the project, and validating the memo means stat-ing the whole
- * `extends` chain (samchon/ttsc#1316).
+ * Discovery, referenced-project selection and membership policy are resolved
+ * once per delivered module and shared by its recorder batch. The policy is
+ * read from source rather than trusting a cached mtime/size observation, which
+ * could miss same-stamp edits.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Shared project discovery, reference selection and membership-policy APIs
+ *   select the same config as the transform core, retaining positive and
+ *   negative discovery predicates. Consulted routing configs retain current
+ *   content, since their references or admission rules can change the owner.
+ *   Compiler-option overlays are merged through that owner.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Selection records the predicates that chose the project, then one
+ *   createProjectView helper assembles its policy and roots for every input
+ *   in the module's recorder batch.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Discovery follows the ancestor candidates and reference graph; the
+ *   resulting policy and roots are assembled once for the delivered module.
+ *   Candidate predicates and consulted config content are captured once for
+ *   this view, with a lexical-key map merging their overlapping paths in
+ *   linear map operations. Capturing content performs the shared baseline's
+ *   two observations and scales with the consulted config bytes.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The returned view is reused by the module's recorder batch; its selected
+ *   tsconfig is passed to the transform options. Config sources are reread for
+ *   a later module because matching mtime and size cannot establish continued
+ *   equivalence.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Returned project data transfers to the caller. This operation retains no
+ *   process-wide state or handle after discovery completes.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The view is resolved once per module and shared with its batch, avoiding
+ *   independent recorder discovery without hardcoded project or test names.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node absolute paths and host discovery predicates retain native
+ *   filesystem identity. The injected discovery filesystem is an explicit
+ *   observation boundary, and path-relative helpers respect native roots; no
+ *   shell command or global filesystem patch is used.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains selection inputs, returned coupled view,
+ *   discovery evidence and per-module reuse. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
  */
 export declare function resolveProjectView(props: {
     compilerOptions?: Record<string, unknown>;
@@ -124,6 +181,63 @@ export declare function resolveProjectView(props: {
  * Compute the fingerprint `getCacheKey` folds into Metro's static transformer
  * key. Never throws: any failure degrades to a nonce, which soundly disables
  * cross-run cache reuse for this run instead of serving stale output.
+ *
+ * A successful call makes two complete observations of the routed projects,
+ * config sources and recorded inputs. Work scales with their files and bytes;
+ * it is paid at Metro's static-key boundary, not once per delivered module. The
+ * run baseline retains exact hashes, identities and discovery predicates so a
+ * worker can prove that its generation matches the state keyed here.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The shared project walker/policy and input-state APIs supply real file,
+ *   config, identity and recorded-input observations. Two complete
+ *   observations must agree before Node sha256 publishes the key and immutable
+ *   run baseline. Missing, volatile, incomplete or changing state yields
+ *   randomBytes nonce, a required withdrawal of reuse rather than a successful
+ *   stale fallback. Injected discovery changes observation only, not
+ *   production results.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The entry point compares two observations and publishes their baseline;
+ *   observeProjectFingerprint owns collecting the complete input universe.
+ *   Nonreusable state has one nonce exit rather than partial-success keys.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Two observations scan project files and recorded inputs, with time driven
+ *   by their bytes and config graph size. Overlapping lexical project walks
+ *   are excluded by routed roots; maps deduplicate config sources. Exact
+ *   content observations are necessary because timestamps do not prove state.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The static key shares transforms only for equal options, config contents,
+ *   file hashes, identities, recorded generation state and requested exact
+ *   compiler-accessible entry listings. Volatile, tainted
+ *   or unstable observations take a fresh nonce; a run baseline must be
+ *   immutable before workers can claim its coverage.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Observation maps are local to key computation and are released on return.
+ *   The persisted run baseline is owned by snapshot preparation, which sweeps
+ *   old baselines. A long-running worker can retain its loaded baseline until
+ *   worker termination; it owns no open handle here.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Decision values come from the documented inputs and product protocol
+ *   rather than expected test answers. No compensating path is introduced to
+ *   make a known example pass.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node paths/fs preserve native roots and physical identities, including
+ *   symlink-aware discovery. Sorted key representation is deterministic; file
+ *   bytes and host predicates remain inputs. Filesystem failure withdraws
+ *   reuse consistently instead of becoming an OS-specific successful key.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains hex digest versus nonce, repeated observation,
+ *   private baseline publication and failure policy. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
  */
 export declare function computeProjectFingerprint(props: {
     compilerOptions?: Record<string, unknown>;
@@ -148,24 +262,208 @@ export declare function computeProjectFingerprint(props: {
  * token crosses bundle and process boundaries, so `getCacheKey` degrades to a
  * nonce even when neither snapshot location can persist the failure and an old
  * main later reappears.
+ *
+ * Compaction reads the accumulated worker and recovery documents and unions
+ * their recorded paths. Workers have unique names; completed observations are
+ * published before removal. Locked claimed files remain until a later retry.
+ * Old temporary files and run baselines are swept, but recorded input paths
+ * accumulate in the main snapshot and dead-owner election directories remain to
+ * prevent delayed contenders from moving a newer lock. Those populations are
+ * not bounded by a fixed retention budget in this implementation.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node filesystem APIs atomically publish complete snapshot documents and a
+ *   token-owned compaction lock. Worker claims are merged before deletion;
+ *   retained claims are identified in the main document to prevent replay.
+ *   Definite dead-PID recovery preserves an election record; contention or
+ *   failed persistence returns a private nonreusable token.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Preparation owns one lock-protected main rewrite. Helpers separate worker
+ *   claims, document parsing, atomic publication and recovery storage, so
+ *   concurrent readers can use the same persisted protocol.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sets union recorded paths in time proportional to document paths, then
+ *   sorting gives deterministic output. Each claimed worker is merged once;
+ *   readdir and document parsing remain necessary to find pending publishers.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The main document records claimed worker names before removal, preventing
+ *   locked files from replaying completed compaction. The epoch survives only
+ *   trusted, untainted observations; corrupt or lost evidence rotates it.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Preparation owns its compaction lock and retires it in finally. Claimed
+ *   workers and recovery files are removed after publication; failed removals
+ *   stay represented for retry. Temporary files and baselines have age sweeps,
+ *   but cumulative input paths and stale-owner election records have no fixed
+ *   bound. Removing these without a generation protocol could erase evidence.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Retries serve locked-file/recovery contracts rather than masking an
+ *   uncorrected successful-state assumption.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node join, mkdir, rename and rm implement native cache paths.
+ *   Windows-locked files remain represented for a later removal attempt; only
+ *   a definite process-query absence permits dead-owner recovery. No shell
+ *   process checks or patched fs methods are used.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains new-run preparation, contention, epoch
+ *   rotation, recovery storage and nonreusable tokens. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
  */
 export declare function prepareSnapshot(projectRoot: string | undefined): string;
 /**
  * Read the unioned snapshot state, or `undefined` when the main snapshot is
- * missing or any snapshot file is corrupt (a torn or foreign write means the
- * recorded set cannot be trusted, so the caller degrades to a nonce).
+ * missing, any snapshot file is corrupt (a torn or foreign write means the
+ * recorded set cannot be trusted, so the caller degrades to a nonce), or a
+ * concurrent compaction keeps renaming worker files so the listing never
+ * settles or a compaction lock stays held.
+ *
+ * `operations` is the read boundary (existence, listing, file text); the
+ * default reads the real filesystem, and a test passes its own to interleave a
+ * compaction with a listing. A pass is retried at most
+ * {@link SNAPSHOT_LISTING_ATTEMPTS} (8) times with a 5 ms pause between passes,
+ * so a held lock costs a call at most about 40 ms before the state is reported
+ * untrusted; the retry is bounded and holds no resource between passes.
+ *
+ * The result contains sorted absolute file and tree paths, the epoch identity,
+ * and tainted/volatile flags. It reads persisted evidence without revalidating
+ * current file bytes; the fingerprint operation owns that validation. Reading
+ * costs the number and size of outstanding documents plus their unioned paths.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Strict snapshot parsing and Set union read worker documents before the
+ *   main publication, retaining file/tree/volatile/tainted state without
+ *   replaying already compacted claims. This is the owned persisted-input
+ *   protocol, not a separate compiler dependency model.
+ *   A pass is accepted only when no compaction lock existed before or after
+ *   it and the main file is unchanged, because a listing concurrent with a
+ *   rename can return the renamed entry under neither name.
+ *   The read boundary is an optional parameter, so the interleaving can be
+ *   driven deterministically while production reads the real filesystem.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This reader validates persisted documents and unions their paths without
+ *   recomputing file state. The fingerprint owner handles live validation;
+ *   both reader and compactor share uncompacted-worker classification.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Reading costs document bytes plus Set insertion and final path sorting.
+ *   The compacted-name Set avoids replay and avoids a linear search per worker.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This read must observe new worker publications; it coordinates no cache
+ *   between calls. Cross-run reuse belongs to computeProjectFingerprint.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Returned snapshot data transfers to the caller. This reader retains no
+ *   state or handle after synchronous reads finish.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Unknown, corrupt or recovery-pending state returns undefined, never an
+ *   invented complete empty set.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node path and fs read native snapshot locations. Locked or unreadable
+ *   directory/documents invalidate the proof on all supported OSes; sorted
+ *   lexical paths remain values, not shell arguments.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains unioned snapshot fields, read ordering and the
+ *   undefined result for untrusted state. Checked against the documentation
+ *   skill: separate paragraphs state the contract and why its nonobvious
+ *   boundary matters; field comments retain their own useful facts.
  */
-export declare function readSnapshotState(base: string): SnapshotState | undefined;
+export declare function readSnapshotState(base: string, operations?: SnapshotReadOperations): SnapshotState | undefined;
 /**
  * Recorder held by each Metro worker. It persists every derived watch input and
  * any volatile declaration, compares compiler-generation evidence with the
  * matching main-process run baseline, and marks any temporal mismatch tainted.
  * A clean transform also writes a document so it can clear a volatile
- * declaration from an earlier run. One cumulative document is flushed per
- * delivered module; the unique name makes worker writes race-free, and
- * `withTtsc` compacts the files on the next run.
+ * declaration from an earlier run. The first delivery, a delivery that adds a
+ * path, and every delivery once the state is tainted flush one cumulative
+ * document; the unique name makes worker writes race-free, and `withTtsc`
+ * compacts the files on the next run.
+ *
+ * `record` accepts one lexical path without generation evidence; `recordMany`
+ * accepts a module's generation evidence; `recordVolatile` withdraws the file
+ * proof for non-file inputs. Without a run identity every input is retained;
+ * production passes the identity whose immutable baseline was keyed in the main
+ * process. An unknown or mismatching baseline marks the snapshot tainted, and
+ * since `record` carries no evidence, a run identity always reads it as a
+ * mismatch. Listing predicates retain their paths for the next run's key
+ * observation; native kind requests survive the same persistence path without
+ * becoming compiler listings or gaining watch scope. The worker never adds a
+ * new disk read to its earlier immutable baseline.
+ *
+ * Sets and baseline maps live for the recorder's worker lifetime and grow with
+ * observed projects and distinct inputs. A flushing delivery serializes the
+ * cumulative recorded set once, not once per input, but a tainted state flushes
+ * on every delivery, so its cost grows with the recorded set for each module. A
+ * failed write remains dirty for retry and tries recovery storage. If both
+ * stores fail, a reusable run throws rather than publishing output backed by
+ * lost evidence.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   One worker closure retains derived inputs and compares their
+ *   compiler-generation evidence with its immutable run baseline through
+ *   shared validation APIs. Static coverage is omitted only after a matching
+ *   proof; unknown/volatile inputs persist taint.
+ *   Listing and plugin-tree paths stay in the retained file universe even
+ *   when a static proof already covers them, so optional payloads survive
+ *   subsequent compaction and key capture.
+ *   A first or changed module batch publishes one cumulative atomic document,
+ *   with recovery storage and AggregateError when a reusable generation cannot
+ *   persist either record.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One worker closure owns recorder state; shared recordMany owns evidence
+ *   comparison and batch publication for single and multiple inputs. flush
+ *   owns durability, so volatile observations use the same failure policy.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sets insert distinct inputs and a cached static-input Set checks coverage
+ *   without searching the whole baseline. A flushing module serializes the
+ *   cumulative paths once, costing their count and encoded bytes rather than
+ *   one cumulative serialization for every input. A tainted state flushes on
+ *   every module, so that cost recurs per delivery until the worker ends.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Each base loads its immutable run baseline once and shares it across
+ *   module batches. Only matching generation evidence authorizes omission of
+ *   static paths; missing or differing evidence records taint instead.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The worker owns maps of bases, baseline bytes and distinct recorded paths
+ *   until termination. Population grows with projects and inputs observed in
+ *   that worker; there is no fixed eviction budget. Persisted files transfer
+ *   to the next preparation's compactor. No native handle remains open.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The legacy no-run handshake records all paths without claiming static
+ *   coverage.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node resolve/join and atomic rename use native paths; unique PID/random
+ *   worker names separate publishers. Windows-locked claims remain readable
+ *   until later compaction, and persistence failures follow the same reuse
+ *   withdrawal contract. No foreign filesystem or process method is replaced.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains record, batch and volatile operations,
+ *   run-baseline matching, cumulative persistence and failure ownership.
+ *   Checked against the documentation skill: separate paragraphs state the
+ *   contract and why its nonobvious boundary matters; field comments retain
+ *   their own useful facts.
  */
 export declare function createSnapshotRecorder(runId?: string): {
+    /** Record one lexical input without claiming compiler-generation evidence. */
     record: (props: {
         input: string;
         /**
@@ -185,18 +483,65 @@ export declare function createSnapshotRecorder(runId?: string): {
          */
         project: TtscMetroProjectView;
     }) => void;
+    /** Record one module's input evidence and publish its cumulative snapshot. */
     recordMany: (props: {
         inputs: readonly TtscWatchInput[];
         project: TtscMetroProjectView;
     }) => void;
+    /** Persist that a project's output depends on inputs a file key cannot prove. */
     recordVolatile: (props: {
         project: TtscMetroProjectView;
     }) => void;
 };
 /**
- * JSON-serialise with object keys sorted recursively, so two semantically equal
- * records always hash to the same fingerprint regardless of property order.
+ * Represent acyclic JSON-like records with recursively sorted keys for hashing.
+ * Arrays preserve order and JSON primitives use JSON escaping. This is an
+ * internal key representation, not JSON for interchange.
+ *
+ * Undefined uses an unquoted marker and sparse array slots use a separate
+ * unquoted hole marker, preserving cardinality and the distinction from null
+ * and literal strings. Non-finite numbers, functions, symbols, BigInt and
+ * cyclic structures are unsupported and throw rather than supplying a key.
  * Shared with the transformer's option digest.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Recursive Object.entries sorting and JSON primitive escaping provide a
+ *   stable internal key representation, not another transport parser. The
+ *   undefined and hole markers cannot collide with quoted string values.
+ *   Array.from visits each slot, preserving length and explicit absence.
+ *   Unsupported primitive values fail instead of aliasing null or absence.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One recursive encoder owns array, record and primitive representations;
+ *   sorted record entries keep ordering policy in that one boundary.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Each visited value is encoded once. Each record sorts its own keys in
+ *   O(k log k), and encoding space follows output bytes plus recursion depth.
+ *   Sorting is necessary for insertion-order-independent record keys.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This encoder accepts potentially mutable caller records and coordinates
+ *   no cross-call computation; consumers own whether encoded values can recur.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The encoder returns its owned string and retains no caller data or handle
+ *   after return; temporary recursion state is computation space.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Absence is represented at its owning serializer rather than patched in
+ *   individual key consumers. Unsupported primitives fail explicitly.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   This operation sorts and encodes caller values for a key; it has no
+ *   native path, filesystem or process boundary.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains sorted keys, the acyclic value domain,
+ *   unsupported JSON interchange and explicit absence markers. Checked
+ *   against the documentation skill: separate paragraphs state the contract
+ *   and why its nonobvious boundary matters; field comments retain their own
+ *   useful facts.
  */
 export declare function stableStringify(value: unknown): string;
 export {};