@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/rollup/RollupCachedModuleProof.d.cts

@@ -0,0 +1,104 @@
+import type { TtscRollupDelivery } from "./TtscRollupDelivery.cjs";
+/**
+ * How the adapter answers Rollup's cache for the modules it delivers
+ * (`createRollupCachedModuleProof`): each delivery leaves its project record's
+ * state in the module's `meta`, and cached-module judgment compares it with the
+ * pass's observed record digest. That reused observation is not a fresh
+ * filesystem read for every module; a matching record-less delivery has a
+ * separate no-project meaning.
+ *
+ * @evidence contracts/common.md#principled-implementation Delivery metadata preserves compiler-option identity and recorded project state, allowing Rollup's source-only cache to ask whether transformed output still holds.
+ * @evidence contracts/common.md#clear-and-simple-design Three operations separate pass reset, delivery recording, and cached-module judgment without exposing record proof internals to the host adapter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent or unprovable delivery metadata cannot certify cached output, and the adapter answers only modules it owns.
+ * @evidence contracts/common.md#meaningful-documentation The interface explains source-only host caching and each method's pass, metadata, or invalidation responsibility.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Typed deliveries carry native project-record filenames and separate option
+ *   identities/digests. The interface preserves that boundary without turning
+ *   host module ids or metadata keys into normalized physical identities.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The interface defines pass/delivery/judgment capabilities; native proof and
+ *   lookup algorithms are implemented by the returned owner.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The interface implements no sharing coordinator; the owning proof instance
+ *   establishes the per-pass tables and permitted digest observation window.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned owner controls pass tables; this capability carrier defines
+ *   no independent acquisition or retention implementation.
+ */
+export interface RollupCachedModuleProof {
+    /**
+     * Open a build: forget every record proven and read for the last one, since
+     * anything may have moved them since.
+     *
+     * @evidence contracts/common.md#principled-implementation Beginning a pass clears record proofs and digests whose observation window ended with the previous build.
+     * @evidence contracts/common.md#clear-and-simple-design The host declares one boundary instead of clearing proof state separately for each module.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A previous pass's unchanged digest cannot stand in for current recorded project state.
+     * @evidence contracts/common.md#meaningful-documentation The comment states which observations expire and why they cannot survive a new build unchecked.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of begin is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     */
+    begin(): void;
+    /**
+     * Take what one delivery was handed, and return the `meta` the module carries
+     * into Rollup's cache.
+     *
+     * @param delivery The options the delivery was compiled under and the record
+     *   it was handed, or `null` for a delivery no cache may serve.
+     * @evidence contracts/common.md#principled-implementation Delivery records the options and record bytes actually handed to that module, or null when no retained output can be proven.
+     * @evidence contracts/common.md#clear-and-simple-design The operation returns plain metadata in the host's existing format without another module cache.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A null delivery preserves uncacheability instead of inventing a digest or hiding volatile inputs.
+     * @evidence contracts/common.md#meaningful-documentation The native prose and parameter comment distinguish recorded delivery from the explicit no-cache case.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   Delivery preserves native record filename separately from option identity
+     *   and digest. The producer supplies its spelling; null and absent record
+     *   are different cache meanings, not native absence or alias proof.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     */
+    deliver(delivery: TtscRollupDelivery): Record<string, TtscRollupDelivery>;
+    /**
+     * Whether Rollup must transform a module it would otherwise serve from its
+     * cache, the answer of `shouldTransformCachedModule`. A module the adapter
+     * does not transform is not its to answer.
+     *
+     * @param module The module as Rollup's cache holds it.
+     * @evidence contracts/common.md#principled-implementation The predicate compares current option identity and pass-observed record bytes with delivered metadata; matching record-less delivery follows the separate no-project rule.
+     * @evidence contracts/common.md#clear-and-simple-design A boolean answers Rollup's own retransformation hook; the host retains ownership of its module cache.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported metadata requires retransformation, and modules outside the adapter's filter remain the host's responsibility.
+     * @evidence contracts/common.md#meaningful-documentation The comment defines the retransformation verdict and the filter's ownership boundary.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   The signature accepts an opaque host module id/meta, not a native record
+     *   path policy. Typed record naming belongs to TtscRollupDelivery and actual
+     *   native observation belongs to the proof implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     */
+    moved(module: {
+        id: string;
+        meta?: Record<string, unknown>;
+    }): boolean;
+}

package/lib/core/rollup/RollupCachedModuleProof.d.mts

@@ -0,0 +1,104 @@
+import type { TtscRollupDelivery } from "./TtscRollupDelivery.mjs";
+/**
+ * How the adapter answers Rollup's cache for the modules it delivers
+ * (`createRollupCachedModuleProof`): each delivery leaves its project record's
+ * state in the module's `meta`, and cached-module judgment compares it with the
+ * pass's observed record digest. That reused observation is not a fresh
+ * filesystem read for every module; a matching record-less delivery has a
+ * separate no-project meaning.
+ *
+ * @evidence contracts/common.md#principled-implementation Delivery metadata preserves compiler-option identity and recorded project state, allowing Rollup's source-only cache to ask whether transformed output still holds.
+ * @evidence contracts/common.md#clear-and-simple-design Three operations separate pass reset, delivery recording, and cached-module judgment without exposing record proof internals to the host adapter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent or unprovable delivery metadata cannot certify cached output, and the adapter answers only modules it owns.
+ * @evidence contracts/common.md#meaningful-documentation The interface explains source-only host caching and each method's pass, metadata, or invalidation responsibility.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Typed deliveries carry native project-record filenames and separate option
+ *   identities/digests. The interface preserves that boundary without turning
+ *   host module ids or metadata keys into normalized physical identities.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The interface defines pass/delivery/judgment capabilities; native proof and
+ *   lookup algorithms are implemented by the returned owner.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The interface implements no sharing coordinator; the owning proof instance
+ *   establishes the per-pass tables and permitted digest observation window.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned owner controls pass tables; this capability carrier defines
+ *   no independent acquisition or retention implementation.
+ */
+export interface RollupCachedModuleProof {
+    /**
+     * Open a build: forget every record proven and read for the last one, since
+     * anything may have moved them since.
+     *
+     * @evidence contracts/common.md#principled-implementation Beginning a pass clears record proofs and digests whose observation window ended with the previous build.
+     * @evidence contracts/common.md#clear-and-simple-design The host declares one boundary instead of clearing proof state separately for each module.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A previous pass's unchanged digest cannot stand in for current recorded project state.
+     * @evidence contracts/common.md#meaningful-documentation The comment states which observations expire and why they cannot survive a new build unchecked.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of begin is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     */
+    begin(): void;
+    /**
+     * Take what one delivery was handed, and return the `meta` the module carries
+     * into Rollup's cache.
+     *
+     * @param delivery The options the delivery was compiled under and the record
+     *   it was handed, or `null` for a delivery no cache may serve.
+     * @evidence contracts/common.md#principled-implementation Delivery records the options and record bytes actually handed to that module, or null when no retained output can be proven.
+     * @evidence contracts/common.md#clear-and-simple-design The operation returns plain metadata in the host's existing format without another module cache.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A null delivery preserves uncacheability instead of inventing a digest or hiding volatile inputs.
+     * @evidence contracts/common.md#meaningful-documentation The native prose and parameter comment distinguish recorded delivery from the explicit no-cache case.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   Delivery preserves native record filename separately from option identity
+     *   and digest. The producer supplies its spelling; null and absent record
+     *   are different cache meanings, not native absence or alias proof.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     */
+    deliver(delivery: TtscRollupDelivery): Record<string, TtscRollupDelivery>;
+    /**
+     * Whether Rollup must transform a module it would otherwise serve from its
+     * cache, the answer of `shouldTransformCachedModule`. A module the adapter
+     * does not transform is not its to answer.
+     *
+     * @param module The module as Rollup's cache holds it.
+     * @evidence contracts/common.md#principled-implementation The predicate compares current option identity and pass-observed record bytes with delivered metadata; matching record-less delivery follows the separate no-project rule.
+     * @evidence contracts/common.md#clear-and-simple-design A boolean answers Rollup's own retransformation hook; the host retains ownership of its module cache.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported metadata requires retransformation, and modules outside the adapter's filter remain the host's responsibility.
+     * @evidence contracts/common.md#meaningful-documentation The comment defines the retransformation verdict and the filter's ownership boundary.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   The signature accepts an opaque host module id/meta, not a native record
+     *   path policy. Typed record naming belongs to TtscRollupDelivery and actual
+     *   native observation belongs to the proof implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     */
+    moved(module: {
+        id: string;
+        meta?: Record<string, unknown>;
+    }): boolean;
+}

package/lib/core/rollup/RollupCachedModuleProof.d.ts

@@ -0,0 +1,104 @@
+import type { TtscRollupDelivery } from "./TtscRollupDelivery";
+/**
+ * How the adapter answers Rollup's cache for the modules it delivers
+ * (`createRollupCachedModuleProof`): each delivery leaves its project record's
+ * state in the module's `meta`, and cached-module judgment compares it with the
+ * pass's observed record digest. That reused observation is not a fresh
+ * filesystem read for every module; a matching record-less delivery has a
+ * separate no-project meaning.
+ *
+ * @evidence contracts/common.md#principled-implementation Delivery metadata preserves compiler-option identity and recorded project state, allowing Rollup's source-only cache to ask whether transformed output still holds.
+ * @evidence contracts/common.md#clear-and-simple-design Three operations separate pass reset, delivery recording, and cached-module judgment without exposing record proof internals to the host adapter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent or unprovable delivery metadata cannot certify cached output, and the adapter answers only modules it owns.
+ * @evidence contracts/common.md#meaningful-documentation The interface explains source-only host caching and each method's pass, metadata, or invalidation responsibility.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Typed deliveries carry native project-record filenames and separate option
+ *   identities/digests. The interface preserves that boundary without turning
+ *   host module ids or metadata keys into normalized physical identities.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The interface defines pass/delivery/judgment capabilities; native proof and
+ *   lookup algorithms are implemented by the returned owner.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The interface implements no sharing coordinator; the owning proof instance
+ *   establishes the per-pass tables and permitted digest observation window.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned owner controls pass tables; this capability carrier defines
+ *   no independent acquisition or retention implementation.
+ */
+export interface RollupCachedModuleProof {
+    /**
+     * Open a build: forget every record proven and read for the last one, since
+     * anything may have moved them since.
+     *
+     * @evidence contracts/common.md#principled-implementation Beginning a pass clears record proofs and digests whose observation window ended with the previous build.
+     * @evidence contracts/common.md#clear-and-simple-design The host declares one boundary instead of clearing proof state separately for each module.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A previous pass's unchanged digest cannot stand in for current recorded project state.
+     * @evidence contracts/common.md#meaningful-documentation The comment states which observations expire and why they cannot survive a new build unchecked.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   Only the signature of begin is declared here; the platform behaviour
+     *   belongs to its implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of begin is declared here; the cost belongs to its
+     *   implementation.
+     */
+    begin(): void;
+    /**
+     * Take what one delivery was handed, and return the `meta` the module carries
+     * into Rollup's cache.
+     *
+     * @param delivery The options the delivery was compiled under and the record
+     *   it was handed, or `null` for a delivery no cache may serve.
+     * @evidence contracts/common.md#principled-implementation Delivery records the options and record bytes actually handed to that module, or null when no retained output can be proven.
+     * @evidence contracts/common.md#clear-and-simple-design The operation returns plain metadata in the host's existing format without another module cache.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A null delivery preserves uncacheability instead of inventing a digest or hiding volatile inputs.
+     * @evidence contracts/common.md#meaningful-documentation The native prose and parameter comment distinguish recorded delivery from the explicit no-cache case.
+     * @evidence contracts/portability.md#os-neutral-implementation
+     *   Delivery preserves native record filename separately from option identity
+     *   and digest. The producer supplies its spelling; null and absent record
+     *   are different cache meanings, not native absence or alias proof.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of deliver is declared here; the cost belongs to its
+     *   implementation.
+     */
+    deliver(delivery: TtscRollupDelivery): Record<string, TtscRollupDelivery>;
+    /**
+     * Whether Rollup must transform a module it would otherwise serve from its
+     * cache, the answer of `shouldTransformCachedModule`. A module the adapter
+     * does not transform is not its to answer.
+     *
+     * @param module The module as Rollup's cache holds it.
+     * @evidence contracts/common.md#principled-implementation The predicate compares current option identity and pass-observed record bytes with delivered metadata; matching record-less delivery follows the separate no-project rule.
+     * @evidence contracts/common.md#clear-and-simple-design A boolean answers Rollup's own retransformation hook; the host retains ownership of its module cache.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported metadata requires retransformation, and modules outside the adapter's filter remain the host's responsibility.
+     * @evidence contracts/common.md#meaningful-documentation The comment defines the retransformation verdict and the filter's ownership boundary.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation
+     *   The signature accepts an opaque host module id/meta, not a native record
+     *   path policy. Typed record naming belongs to TtscRollupDelivery and actual
+     *   native observation belongs to the proof implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+     *   Only the signature of moved is declared here; the cost belongs to its
+     *   implementation.
+     */
+    moved(module: {
+        id: string;
+        meta?: Record<string, unknown>;
+    }): boolean;
+}

package/lib/core/rollup/TtscRollupDelivery.d.cts

@@ -0,0 +1,48 @@
+/**
+ * What a module the adapter delivered to Rollup carries in its `meta`, under
+ * the plugin's name, so that a later build handed Rollup's cache can tell
+ * whether the module's output still holds (`createRollupCachedModuleProof`).
+ *
+ * Host module caching does not independently validate this adapter's current
+ * project and options. A delivery therefore names its option identity
+ * (`rollupDeliveryOptions`) and the project record it was handed with the
+ * digest of the bytes its process wrote to it. A delivery that consulted no
+ * project, such as disabled plugins, names no record. A delivery no cache may
+ * serve carries `null`: one handed no record its process wrote, and one whose
+ * output the plugin declared volatile, which depends on inputs no file stands
+ * for.
+ *
+ * Rollup keeps a module's `meta` in its cache, and restores it with the module,
+ * so the value is plain JSON.
+ *
+ * @evidence contracts/common.md#principled-implementation Option identity and optional record digest preserve the configuration and input-state conditions under which this module was delivered; null explicitly denies cache reuse.
+ * @evidence contracts/common.md#clear-and-simple-design Plain JSON metadata stores only proof references rather than the generation or native observation resources.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing record and null have distinct meanings, so a volatile or unprovable delivery cannot masquerade as a disabled-plugin pass-through.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains host source-only caching, option identity, optional records, null, and serializable metadata ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Optional record.file carries the producer's native project-record filename.
+ *   It stays distinct from option identity/digest and host module id; no URL,
+ *   case normalization or physical alias inference changes its spelling.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The JSON carrier defines option/record fields; production and cache
+ *   judgment own encoding, native reads and comparisons.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The carrier implements no sharing coordinator; per-pass reuse belongs to
+ *   the proof instance that consumes these delivered facts.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Host module metadata owns this value's lifetime; the carrier defines no
+ *   independent handle/task acquisition or retention policy.
+ */
+export type TtscRollupDelivery = {
+    /** The identity of the options the delivery was compiled under. */
+    options: string;
+    /**
+     * The project record the delivery was handed (`projectRecordFile`), with the
+     * digest of the bytes its process wrote to it (`projectRecordDigest`); absent
+     * for a delivery that consulted no project.
+     */
+    record?: {
+        digest: string;
+        file: string;
+    };
+} | null;

package/lib/core/rollup/TtscRollupDelivery.d.mts

@@ -0,0 +1,48 @@
+/**
+ * What a module the adapter delivered to Rollup carries in its `meta`, under
+ * the plugin's name, so that a later build handed Rollup's cache can tell
+ * whether the module's output still holds (`createRollupCachedModuleProof`).
+ *
+ * Host module caching does not independently validate this adapter's current
+ * project and options. A delivery therefore names its option identity
+ * (`rollupDeliveryOptions`) and the project record it was handed with the
+ * digest of the bytes its process wrote to it. A delivery that consulted no
+ * project, such as disabled plugins, names no record. A delivery no cache may
+ * serve carries `null`: one handed no record its process wrote, and one whose
+ * output the plugin declared volatile, which depends on inputs no file stands
+ * for.
+ *
+ * Rollup keeps a module's `meta` in its cache, and restores it with the module,
+ * so the value is plain JSON.
+ *
+ * @evidence contracts/common.md#principled-implementation Option identity and optional record digest preserve the configuration and input-state conditions under which this module was delivered; null explicitly denies cache reuse.
+ * @evidence contracts/common.md#clear-and-simple-design Plain JSON metadata stores only proof references rather than the generation or native observation resources.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing record and null have distinct meanings, so a volatile or unprovable delivery cannot masquerade as a disabled-plugin pass-through.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains host source-only caching, option identity, optional records, null, and serializable metadata ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Optional record.file carries the producer's native project-record filename.
+ *   It stays distinct from option identity/digest and host module id; no URL,
+ *   case normalization or physical alias inference changes its spelling.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The JSON carrier defines option/record fields; production and cache
+ *   judgment own encoding, native reads and comparisons.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The carrier implements no sharing coordinator; per-pass reuse belongs to
+ *   the proof instance that consumes these delivered facts.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Host module metadata owns this value's lifetime; the carrier defines no
+ *   independent handle/task acquisition or retention policy.
+ */
+export type TtscRollupDelivery = {
+    /** The identity of the options the delivery was compiled under. */
+    options: string;
+    /**
+     * The project record the delivery was handed (`projectRecordFile`), with the
+     * digest of the bytes its process wrote to it (`projectRecordDigest`); absent
+     * for a delivery that consulted no project.
+     */
+    record?: {
+        digest: string;
+        file: string;
+    };
+} | null;

package/lib/core/rollup/TtscRollupDelivery.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a module the adapter delivered to Rollup carries in its `meta`, under
+ * the plugin's name, so that a later build handed Rollup's cache can tell
+ * whether the module's output still holds (`createRollupCachedModuleProof`).
+ *
+ * Host module caching does not independently validate this adapter's current
+ * project and options. A delivery therefore names its option identity
+ * (`rollupDeliveryOptions`) and the project record it was handed with the
+ * digest of the bytes its process wrote to it. A delivery that consulted no
+ * project, such as disabled plugins, names no record. A delivery no cache may
+ * serve carries `null`: one handed no record its process wrote, and one whose
+ * output the plugin declared volatile, which depends on inputs no file stands
+ * for.
+ *
+ * Rollup keeps a module's `meta` in its cache, and restores it with the module,
+ * so the value is plain JSON.
+ *
+ * @evidence contracts/common.md#principled-implementation Option identity and optional record digest preserve the configuration and input-state conditions under which this module was delivered; null explicitly denies cache reuse.
+ * @evidence contracts/common.md#clear-and-simple-design Plain JSON metadata stores only proof references rather than the generation or native observation resources.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing record and null have distinct meanings, so a volatile or unprovable delivery cannot masquerade as a disabled-plugin pass-through.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains host source-only caching, option identity, optional records, null, and serializable metadata ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Optional record.file carries the producer's native project-record filename.
+ *   It stays distinct from option identity/digest and host module id; no URL,
+ *   case normalization or physical alias inference changes its spelling.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The JSON carrier defines option/record fields; production and cache
+ *   judgment own encoding, native reads and comparisons.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The carrier implements no sharing coordinator; per-pass reuse belongs to
+ *   the proof instance that consumes these delivered facts.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Host module metadata owns this value's lifetime; the carrier defines no
+ *   independent handle/task acquisition or retention policy.
+ */
+export type TtscRollupDelivery = {
+    /** The identity of the options the delivery was compiled under. */
+    options: string;
+    /**
+     * The project record the delivery was handed (`projectRecordFile`), with the
+     * digest of the bytes its process wrote to it (`projectRecordDigest`); absent
+     * for a delivery that consulted no project.
+     */
+    record?: {
+        digest: string;
+        file: string;
+    };
+} | null;

package/lib/core/rollup/createRollupCachedModuleProof.d.cts

@@ -0,0 +1,60 @@
+import type { RollupCachedModuleProof } from "./RollupCachedModuleProof.cjs";
+/**
+ * Answer Rollup's cache for the modules the adapter delivers to it.
+ *
+ * When the host would otherwise restore a module from its supplied cache,
+ * shouldTransformCachedModule can request transformation again. This adapter
+ * uses that hook to compare its delivered options and project-record state,
+ * including a build that has no live watcher to hear earlier input edits
+ * (samchon/ttsc#1491).
+ *
+ * A delivery leaves the options it was compiled under, the record, and the
+ * digest of the bytes its process wrote to the record in the module's `meta`
+ * (`TtscRollupDelivery`), which Rollup keeps with the module. A module it would
+ * serve from its cache runs again unless it was compiled under the options the
+ * build runs with and its digest is the record's bytes now. A build that proves
+ * records proves each one once, as its first cached module names it
+ * (`refreshProjectRecordFile`), which moves it for a project that changed while
+ * nothing ran: Rollup reads the cache it was handed as it builds its graph, and
+ * says which modules it holds only by asking here, so the records proven are
+ * exactly those of the projects whose modules it is about to restore. A
+ * watching session proves none: its cache holds only what its own deliveries
+ * registered with the bridge, which moves their records as their inputs change.
+ * An owned module carrying no delivery, or one no cache may serve, runs again,
+ * since nothing proves its output.
+ *
+ * A record read is cached, including unavailable results, until begin clears it
+ * or a first proof attempt invalidates it. Deliveries replace the saved digest
+ * with their own recorded bytes. A later judgment need not reread a record
+ * moved by another process in mid-build; the next pass observes it. A changed
+ * proves callback can invalidate an already read digest within this pass.
+ * Refresh errors propagate after the key enters the attempted-proof set.
+ *
+ * @param name The plugin's name, the key of its entry in a module's `meta`.
+ * @param includes Whether the adapter transforms a module id.
+ * @param options The identity of the options the build runs with
+ *   (`rollupDeliveryOptions`).
+ * @param proves Whether the build proves the records its cached modules name,
+ *   which a build without a watching session's bridge does.
+ * @evidence contracts/common.md#principled-implementation Adapter-owned modules compare options and pass-observed record digest; matching record-less metadata follows the no-project rule. Missing delivery, malformed record, null or unreadable record requests retransformation.
+ * @evidence contracts/common.md#clear-and-simple-design Per-pass proven and digest tables back the existing begin/deliver/moved interface; shared record refresh owns filesystem-state proof.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter uses the host retransformation hook without patching its cache or inventing a record when no proof exists.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain optional record refresh, pass observation reuse and invalidation, including callback failure and record-less delivery semantics.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral record access uses producer-supplied native paths and the shared native record refresh operation, without universal path case normalization or fixed storage directories.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Judgment adds module filtering, current-option work and metadata/text
+ *   comparison. Each lexical record gets one refresh attempt per pass, including
+ *   native input/walk/record I/O work. Digest reads/hash follow record bytes
+ *   and can repeat after proof invalidation; delivery updates avoid a reread.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Modules with the same lexical record reuse a pass's refresh attempt and
+ *   observed digest. Begin ends the window; first refresh invalidates an older
+ *   read and delivery updates the digest. Quiet mid-pass observation is a
+ *   defined reuse window, not independently fresh native state for every module.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The returned proof owner retains attempted keys and optional digests for R
+ *   lexical records until begin clears them or the owner becomes unreachable.
+ *   There is no count/byte cap within a pass or dedicated close. Thrown refresh
+ *   leaves existing table state until that reset; no native handle/task is held.
+ */
+export declare function createRollupCachedModuleProof(name: string, includes: (id: string) => boolean, options: () => string, proves: () => boolean): RollupCachedModuleProof;

package/lib/core/rollup/createRollupCachedModuleProof.d.mts

@@ -0,0 +1,60 @@
+import type { RollupCachedModuleProof } from "./RollupCachedModuleProof.mjs";
+/**
+ * Answer Rollup's cache for the modules the adapter delivers to it.
+ *
+ * When the host would otherwise restore a module from its supplied cache,
+ * shouldTransformCachedModule can request transformation again. This adapter
+ * uses that hook to compare its delivered options and project-record state,
+ * including a build that has no live watcher to hear earlier input edits
+ * (samchon/ttsc#1491).
+ *
+ * A delivery leaves the options it was compiled under, the record, and the
+ * digest of the bytes its process wrote to the record in the module's `meta`
+ * (`TtscRollupDelivery`), which Rollup keeps with the module. A module it would
+ * serve from its cache runs again unless it was compiled under the options the
+ * build runs with and its digest is the record's bytes now. A build that proves
+ * records proves each one once, as its first cached module names it
+ * (`refreshProjectRecordFile`), which moves it for a project that changed while
+ * nothing ran: Rollup reads the cache it was handed as it builds its graph, and
+ * says which modules it holds only by asking here, so the records proven are
+ * exactly those of the projects whose modules it is about to restore. A
+ * watching session proves none: its cache holds only what its own deliveries
+ * registered with the bridge, which moves their records as their inputs change.
+ * An owned module carrying no delivery, or one no cache may serve, runs again,
+ * since nothing proves its output.
+ *
+ * A record read is cached, including unavailable results, until begin clears it
+ * or a first proof attempt invalidates it. Deliveries replace the saved digest
+ * with their own recorded bytes. A later judgment need not reread a record
+ * moved by another process in mid-build; the next pass observes it. A changed
+ * proves callback can invalidate an already read digest within this pass.
+ * Refresh errors propagate after the key enters the attempted-proof set.
+ *
+ * @param name The plugin's name, the key of its entry in a module's `meta`.
+ * @param includes Whether the adapter transforms a module id.
+ * @param options The identity of the options the build runs with
+ *   (`rollupDeliveryOptions`).
+ * @param proves Whether the build proves the records its cached modules name,
+ *   which a build without a watching session's bridge does.
+ * @evidence contracts/common.md#principled-implementation Adapter-owned modules compare options and pass-observed record digest; matching record-less metadata follows the no-project rule. Missing delivery, malformed record, null or unreadable record requests retransformation.
+ * @evidence contracts/common.md#clear-and-simple-design Per-pass proven and digest tables back the existing begin/deliver/moved interface; shared record refresh owns filesystem-state proof.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter uses the host retransformation hook without patching its cache or inventing a record when no proof exists.
+ * @evidence contracts/common.md#meaningful-documentation Paragraphs explain optional record refresh, pass observation reuse and invalidation, including callback failure and record-less delivery semantics.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral record access uses producer-supplied native paths and the shared native record refresh operation, without universal path case normalization or fixed storage directories.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Judgment adds module filtering, current-option work and metadata/text
+ *   comparison. Each lexical record gets one refresh attempt per pass, including
+ *   native input/walk/record I/O work. Digest reads/hash follow record bytes
+ *   and can repeat after proof invalidation; delivery updates avoid a reread.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Modules with the same lexical record reuse a pass's refresh attempt and
+ *   observed digest. Begin ends the window; first refresh invalidates an older
+ *   read and delivery updates the digest. Quiet mid-pass observation is a
+ *   defined reuse window, not independently fresh native state for every module.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The returned proof owner retains attempted keys and optional digests for R
+ *   lexical records until begin clears them or the owner becomes unreachable.
+ *   There is no count/byte cap within a pass or dedicated close. Thrown refresh
+ *   leaves existing table state until that reset; no native handle/task is held.
+ */
+export declare function createRollupCachedModuleProof(name: string, includes: (id: string) => boolean, options: () => string, proves: () => boolean): RollupCachedModuleProof;