@ttsc/unplugin 0.19.0 → 0.19.2

package/README.md

@@ -302,9 +302,13 @@ const options: TtscUnpluginOptions = {
 - `compilerOptions`: temporary override layered on the selected project config.
 - `plugins`: direct `ttsc` plugin list override, or `false` to disable plugins.
 
-### Watch Mode and HMR
+### Cache and Watch Invalidation
 
-Transform plugins may report, per file, the source files they consulted (the transform envelope's `dependencies` field, see the [plugin protocol](https://ttsc.dev/docs/development/concepts/protocol#transform)). The adapter registers each reported path with the bundler via `addWatchFile`, so editing a type that only a generated validator depends on invalidates the module in watch mode even though the bundler erased the type-only import from its graph.
+The transform host reports the program's reference graph (the transform envelope's `graph` section: per-file direct resolved references with type-only edges included, global-scope files, and the tsconfig `extends` chain — see the [plugin protocol](https://ttsc.dev/docs/development/concepts/protocol#transform)). Per transformed file, the adapter registers the graph's reachability closure, the globals, and the configs with the bundler via `addWatchFile`, so editing a type that only a generated validator depends on invalidates the module — in watch mode, in webpack's filesystem cache, and in Turbopack's `fileDependencies` — even though the bundler erased the type-only import from its own graph.
+
+Transform plugins may additionally report, per file, the source files they consulted (the envelope's `dependencies` field); the adapter registers those as watch files too, union semantics. A plugin that declares such a list [complete](https://ttsc.dev/docs/development/concepts/protocol#dependency-completeness) for a file narrows the registration instead: only its own list plus the tsconfig chain, so files the transform never consulted stop invalidating it. Files a plugin declares `volatile` (output depending on non-file inputs such as environment or time) bypass the adapter's transform cache and are marked uncacheable where the bundler exposes that control.
+
+The transform cache itself validates against the same input set: every file under the project root plus the graph-reported inputs outside it (`node_modules` declarations, monorepo sibling sources, out-of-root `extends` ancestry). Hosts that keep one cache for the process lifetime instead of per build (Metro workers, the Turbopack loader, Bun) therefore recompile when any of those inputs changes, not only in-project ones.
 
 ## Sponsors
 

package/lib/api.js

@@ -8,7 +8,10 @@ var options = require('./core/options.js');
 
 exports.sourceFilePattern = index.sourceFilePattern;
 exports.unplugin = index.default;
+exports.collectExternalInputHashes = transform.collectExternalInputHashes;
+exports.collectProjectInputHashes = transform.collectProjectInputHashes;
 exports.createTtscTransformCache = transform.createTtscTransformCache;
+exports.isProjectWalkPath = transform.isProjectWalkPath;
 exports.transformTtsc = transform.transformTtsc;
 exports.resolveOptions = options.resolveOptions;
 //# sourceMappingURL=api.js.map

package/lib/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}
+{"version":3,"file":"api.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;"}

package/lib/api.mjs

@@ -1,4 +1,4 @@
 export { sourceFilePattern, default as unplugin } from './core/index.mjs';
-export { createTtscTransformCache, transformTtsc } from './core/transform.mjs';
+export { collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, transformTtsc } from './core/transform.mjs';
 export { resolveOptions } from './core/options.mjs';
 //# sourceMappingURL=api.mjs.map

package/lib/core/index.d.ts

@@ -1,7 +1,7 @@
 import type { UnpluginInstance } from "unplugin";
 import type { TtscUnpluginOptions } from "./options";
 import { resolveOptions } from "./options";
-import { createTtscTransformCache, transformTtsc } from "./transform";
+import { collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, transformTtsc } from "./transform";
 /**
  * Matches any TypeScript or JavaScript source extension (.ts, .tsx, .mts, .cts,
  * etc.). Shared with the Bun adapter (`bun.ts`) so the filter is defined once
@@ -11,5 +11,5 @@ export declare const sourceFilePattern: RegExp;
 declare const unplugin: UnpluginInstance<TtscUnpluginOptions | undefined, false>;
 export type { TtscUnpluginCompilerOptionsJson, TtscUnpluginOptions, } from "./options";
 export type { TtscTransformHooks } from "./transform";
-export { createTtscTransformCache, resolveOptions, transformTtsc, unplugin };
+export { collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, resolveOptions, transformTtsc, unplugin, };
 export default unplugin;

package/lib/core/index.js

@@ -55,11 +55,22 @@ const unpluginFactory = (rawOptions = {}) => {
                 return undefined;
             }
             return transform.transformTtsc(file, source, options$1, aliases, transformCache, {
-                // Register plugin-reported dependencies (the transform envelope's
-                // `dependencies` lists) so type-only inputs invalidate this module
-                // in watch mode; bundlers erase type-only imports from their own
-                // module graph and would otherwise serve stale generated code.
+                // Register the derived watch inputs (plugin-reported `dependencies`
+                // unioned with the host-owned reference graph) so type-only inputs
+                // invalidate this module in watch mode and persistent caches;
+                // bundlers erase type-only imports from their own module graph and
+                // would otherwise serve stale generated code.
                 addWatchFile: (watched) => this.addWatchFile(watched),
+                // A module the plugin declared volatile depends on non-file inputs,
+                // which no file-dependency snapshot can represent; mark it
+                // uncacheable where the bundler exposes that control.
+                markVolatile: () => {
+                    const native = this.getNativeBuildContext?.();
+                    if (native?.framework === "webpack" ||
+                        native?.framework === "rspack") {
+                        native.loaderContext?.cacheable?.(false);
+                    }
+                },
             });
         },
     };
@@ -80,7 +91,10 @@ function isTransformTarget(id) {
 }
 
 exports.resolveOptions = options.resolveOptions;
+exports.collectExternalInputHashes = transform.collectExternalInputHashes;
+exports.collectProjectInputHashes = transform.collectProjectInputHashes;
 exports.createTtscTransformCache = transform.createTtscTransformCache;
+exports.isProjectWalkPath = transform.isProjectWalkPath;
 exports.transformTtsc = transform.transformTtsc;
 exports.default = unplugin;
 exports.sourceFilePattern = sourceFilePattern;

package/lib/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/core/index.ts"],"sourcesContent":[null],"names":["options","resolveOptions","createTtscTransformCache","stripQuery","transformTtsc","createUnplugin","isDeclarationFile"],"mappings":";;;;;;;;AAYA,MAAM,IAAI,GAAG,eAAe;AAC5B;;;;AAIG;AACI,MAAM,iBAAiB,GAAG;AACjC;AACA,MAAM,kBAAkB,GAAG,oCAAoC;AAC/D;;;AAGG;AACH,MAAM,oBAAoB,GAAG,IAAI;AAEjC;;;;;;;;;AASG;AACH,MAAM,eAAe,GAGjB,CAAC,UAAU,GAAG,EAAE,KAAI;AACtB,IAAA,MAAMA,SAAO,GAAGC,sBAAc,CAAC,UAAU,CAAC;AAC1C,IAAA,MAAM,cAAc,GAAGC,kCAAwB,EAAE;AACjD,IAAA,IAAI,OAAgB;IAEpB,OAAO;QACL,IAAI;AACJ,QAAA,OAAO,EAAE,KAAK;AAEd,QAAA,IAAI,EAAE;AACJ,YAAA,cAAc,CAAC,MAAM,EAAA;AACnB,gBAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK;YAChC,CAAC;AACF,SAAA;QAED,UAAU,GAAA;YACR,cAAc,CAAC,KAAK,EAAE;QACxB,CAAC;AAED,QAAA,gBAAgB,CAAC,EAAE,EAAA;AACjB,YAAA,MAAM,IAAI,GAAGC,oBAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,OAAO,iBAAiB,CAAC,IAAI,CAAC;QAChC,CAAC;AAED,QAAA,MAAM,SAAS,CAAC,MAAM,EAAE,EAAE,EAAA;AACxB,YAAA,MAAM,IAAI,GAAGA,oBAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE;AAC5B,gBAAA,OAAO,SAAS;YAClB;YACA,OAAOC,uBAAa,CAAC,IAAI,EAAE,MAAM,EAAEJ,SAAO,EAAE,OAAO,EAAE,cAAc,EAAE;;;;;gBAKnE,YAAY,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;AACtD,aAAA,CAAC;QACJ,CAAC;KACF;AACH,CAAC;AAED,MAAM,QAAQ,GACZK,yBAAc,CAAC,eAAe;AAWhC;;;;;;AAMG;AACH,SAAS,iBAAiB,CAAC,EAAU,EAAA;AACnC,IAAA,QACE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1B,QAAA,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,CAACC,2BAAiB,CAAC,EAAE,CAAC;AACtB,QAAA,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;AAEhC;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":["../../src/core/index.ts"],"sourcesContent":[null],"names":["options","resolveOptions","createTtscTransformCache","stripQuery","transformTtsc","createUnplugin","isDeclarationFile"],"mappings":";;;;;;;;AAeA,MAAM,IAAI,GAAG,eAAe;AAC5B;;;;AAIG;AACI,MAAM,iBAAiB,GAAG;AACjC;AACA,MAAM,kBAAkB,GAAG,oCAAoC;AAC/D;;;AAGG;AACH,MAAM,oBAAoB,GAAG,IAAI;AAEjC;;;;;;;;;AASG;AACH,MAAM,eAAe,GAGjB,CAAC,UAAU,GAAG,EAAE,KAAI;AACtB,IAAA,MAAMA,SAAO,GAAGC,sBAAc,CAAC,UAAU,CAAC;AAC1C,IAAA,MAAM,cAAc,GAAGC,kCAAwB,EAAE;AACjD,IAAA,IAAI,OAAgB;IAEpB,OAAO;QACL,IAAI;AACJ,QAAA,OAAO,EAAE,KAAK;AAEd,QAAA,IAAI,EAAE;AACJ,YAAA,cAAc,CAAC,MAAM,EAAA;AACnB,gBAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK;YAChC,CAAC;AACF,SAAA;QAED,UAAU,GAAA;YACR,cAAc,CAAC,KAAK,EAAE;QACxB,CAAC;AAED,QAAA,gBAAgB,CAAC,EAAE,EAAA;AACjB,YAAA,MAAM,IAAI,GAAGC,oBAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,OAAO,iBAAiB,CAAC,IAAI,CAAC;QAChC,CAAC;AAED,QAAA,MAAM,SAAS,CAAC,MAAM,EAAE,EAAE,EAAA;AACxB,YAAA,MAAM,IAAI,GAAGA,oBAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE;AAC5B,gBAAA,OAAO,SAAS;YAClB;YACA,OAAOC,uBAAa,CAAC,IAAI,EAAE,MAAM,EAAEJ,SAAO,EAAE,OAAO,EAAE,cAAc,EAAE;;;;;;gBAMnE,YAAY,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;;;;gBAIrD,YAAY,EAAE,MAAK;AACjB,oBAAA,MAAM,MAAM,GAAG,IAAI,CAAC,qBAAqB,IAAI;AAC7C,oBAAA,IACE,MAAM,EAAE,SAAS,KAAK,SAAS;AAC/B,wBAAA,MAAM,EAAE,SAAS,KAAK,QAAQ,EAC9B;wBACA,MAAM,CAAC,aAAa,EAAE,SAAS,GAAG,KAAK,CAAC;oBAC1C;gBACF,CAAC;AACF,aAAA,CAAC;QACJ,CAAC;KACF;AACH,CAAC;AAED,MAAM,QAAQ,GACZK,yBAAc,CAAC,eAAe;AAmBhC;;;;;;AAMG;AACH,SAAS,iBAAiB,CAAC,EAAU,EAAA;AACnC,IAAA,QACE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1B,QAAA,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,CAACC,2BAAiB,CAAC,EAAE,CAAC;AACtB,QAAA,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;AAEhC;;;;;;;;;;;;"}

package/lib/core/index.mjs

@@ -1,6 +1,7 @@
 import { createUnplugin } from 'unplugin';
 import { resolveOptions } from './options.mjs';
 import { stripQuery, transformTtsc, isDeclarationFile, createTtscTransformCache } from './transform.mjs';
+export { collectExternalInputHashes, collectProjectInputHashes, isProjectWalkPath } from './transform.mjs';
 
 const name = "ttsc-unplugin";
 /**
@@ -51,11 +52,22 @@ const unpluginFactory = (rawOptions = {}) => {
                 return undefined;
             }
             return transformTtsc(file, source, options, aliases, transformCache, {
-                // Register plugin-reported dependencies (the transform envelope's
-                // `dependencies` lists) so type-only inputs invalidate this module
-                // in watch mode; bundlers erase type-only imports from their own
-                // module graph and would otherwise serve stale generated code.
+                // Register the derived watch inputs (plugin-reported `dependencies`
+                // unioned with the host-owned reference graph) so type-only inputs
+                // invalidate this module in watch mode and persistent caches;
+                // bundlers erase type-only imports from their own module graph and
+                // would otherwise serve stale generated code.
                 addWatchFile: (watched) => this.addWatchFile(watched),
+                // A module the plugin declared volatile depends on non-file inputs,
+                // which no file-dependency snapshot can represent; mark it
+                // uncacheable where the bundler exposes that control.
+                markVolatile: () => {
+                    const native = this.getNativeBuildContext?.();
+                    if (native?.framework === "webpack" ||
+                        native?.framework === "rspack") {
+                        native.loaderContext?.cacheable?.(false);
+                    }
+                },
             });
         },
     };

package/lib/core/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":["../../src/core/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAYA,MAAM,IAAI,GAAG,eAAe;AAC5B;;;;AAIG;AACI,MAAM,iBAAiB,GAAG;AACjC;AACA,MAAM,kBAAkB,GAAG,oCAAoC;AAC/D;;;AAGG;AACH,MAAM,oBAAoB,GAAG,IAAI;AAEjC;;;;;;;;;AASG;AACH,MAAM,eAAe,GAGjB,CAAC,UAAU,GAAG,EAAE,KAAI;AACtB,IAAA,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,CAAC;AAC1C,IAAA,MAAM,cAAc,GAAG,wBAAwB,EAAE;AACjD,IAAA,IAAI,OAAgB;IAEpB,OAAO;QACL,IAAI;AACJ,QAAA,OAAO,EAAE,KAAK;AAEd,QAAA,IAAI,EAAE;AACJ,YAAA,cAAc,CAAC,MAAM,EAAA;AACnB,gBAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK;YAChC,CAAC;AACF,SAAA;QAED,UAAU,GAAA;YACR,cAAc,CAAC,KAAK,EAAE;QACxB,CAAC;AAED,QAAA,gBAAgB,CAAC,EAAE,EAAA;AACjB,YAAA,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,OAAO,iBAAiB,CAAC,IAAI,CAAC;QAChC,CAAC;AAED,QAAA,MAAM,SAAS,CAAC,MAAM,EAAE,EAAE,EAAA;AACxB,YAAA,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE;AAC5B,gBAAA,OAAO,SAAS;YAClB;YACA,OAAO,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE;;;;;gBAKnE,YAAY,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;AACtD,aAAA,CAAC;QACJ,CAAC;KACF;AACH,CAAC;AAED,MAAM,QAAQ,GACZ,cAAc,CAAC,eAAe;AAWhC;;;;;;AAMG;AACH,SAAS,iBAAiB,CAAC,EAAU,EAAA;AACnC,IAAA,QACE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1B,QAAA,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,CAAC,iBAAiB,CAAC,EAAE,CAAC;AACtB,QAAA,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;AAEhC;;;;"}
+{"version":3,"file":"index.mjs","sources":["../../src/core/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAeA,MAAM,IAAI,GAAG,eAAe;AAC5B;;;;AAIG;AACI,MAAM,iBAAiB,GAAG;AACjC;AACA,MAAM,kBAAkB,GAAG,oCAAoC;AAC/D;;;AAGG;AACH,MAAM,oBAAoB,GAAG,IAAI;AAEjC;;;;;;;;;AASG;AACH,MAAM,eAAe,GAGjB,CAAC,UAAU,GAAG,EAAE,KAAI;AACtB,IAAA,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,CAAC;AAC1C,IAAA,MAAM,cAAc,GAAG,wBAAwB,EAAE;AACjD,IAAA,IAAI,OAAgB;IAEpB,OAAO;QACL,IAAI;AACJ,QAAA,OAAO,EAAE,KAAK;AAEd,QAAA,IAAI,EAAE;AACJ,YAAA,cAAc,CAAC,MAAM,EAAA;AACnB,gBAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK;YAChC,CAAC;AACF,SAAA;QAED,UAAU,GAAA;YACR,cAAc,CAAC,KAAK,EAAE;QACxB,CAAC;AAED,QAAA,gBAAgB,CAAC,EAAE,EAAA;AACjB,YAAA,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,OAAO,iBAAiB,CAAC,IAAI,CAAC;QAChC,CAAC;AAED,QAAA,MAAM,SAAS,CAAC,MAAM,EAAE,EAAE,EAAA;AACxB,YAAA,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC;AAC3B,YAAA,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE;AAC5B,gBAAA,OAAO,SAAS;YAClB;YACA,OAAO,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE;;;;;;gBAMnE,YAAY,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;;;;gBAIrD,YAAY,EAAE,MAAK;AACjB,oBAAA,MAAM,MAAM,GAAG,IAAI,CAAC,qBAAqB,IAAI;AAC7C,oBAAA,IACE,MAAM,EAAE,SAAS,KAAK,SAAS;AAC/B,wBAAA,MAAM,EAAE,SAAS,KAAK,QAAQ,EAC9B;wBACA,MAAM,CAAC,aAAa,EAAE,SAAS,GAAG,KAAK,CAAC;oBAC1C;gBACF,CAAC;AACF,aAAA,CAAC;QACJ,CAAC;KACF;AACH,CAAC;AAED,MAAM,QAAQ,GACZ,cAAc,CAAC,eAAe;AAmBhC;;;;;;AAMG;AACH,SAAS,iBAAiB,CAAC,EAAU,EAAA;AACnC,IAAA,QACE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1B,QAAA,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,CAAC,iBAAiB,CAAC,EAAE,CAAC;AACtB,QAAA,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;AAEhC;;;;"}

package/lib/core/transform.d.ts

@@ -32,6 +32,20 @@ export interface TtscTransformAlias {
  * miss on every module.
  */
 export interface TtscCachedProjectTransform {
+    /**
+     * SHA-256 hash of every input the compiler reported outside the project walk
+     * (keyed by absolute path), captured at the time of the transform.
+     *
+     * The project walk cannot see files outside the project root or under ignored
+     * directories (`node_modules` declarations, monorepo sibling sources,
+     * out-of-root tsconfig `extends` ancestry), yet the host-owned reference
+     * graph proves they are transform inputs. Long-lived hosts that never clear
+     * the cache between builds (Metro workers, the Turbopack loader, Bun) would
+     * otherwise replay a project transform computed against a stale out-of-walk
+     * input for the whole process lifetime; per-build hosts clear the cache on
+     * `buildStart` and never replay across edits.
+     */
+    externalInputHashes?: Record<string, string>;
     /**
      * SHA-256 hash of each project-relative input path at the time of the
      * transform.
@@ -41,6 +55,15 @@ export interface TtscCachedProjectTransform {
     projectRoot: string;
     /** Raw compiler output returned by {@link TtscCompiler.transform}. */
     result: ITtscCompilerTransformation;
+    /**
+     * Absolute path of the generated temp-dir tsconfig this compile ran against,
+     * when an alias/compiler-options overlay required one. The compiler reports
+     * it in the envelope's `graph.configs` chain, but it is disposed right after
+     * the compile, so registering it as a watch input would invalidate every
+     * bundler cache snapshot on the next build; watch derivation must skip
+     * exactly this path.
+     */
+    temporaryTsconfig?: string;
 }
 /**
  * Keyed by a stable JSON string that encodes the tsconfig path, compiler
@@ -58,12 +81,25 @@ export declare function createTtscTransformCache(): TtscTransformCache;
  */
 export interface TtscTransformHooks {
     /**
-     * Invoked once per absolute dependency path the plugin reported for the
-     * transformed file (`dependencies` in the transform envelope). Adapters
-     * forward this to the bundler's `addWatchFile` so type-only inputs
-     * participate in HMR invalidation.
+     * Invoked once per absolute watch-input path derived for the transformed file
+     * `F`: the plugin-reported `dependencies[F]` list unioned with the host-owned
+     * reference graph's contribution — the reachability closure of `graph.edges`
+     * from `F`, the `graph.globals` files, and the `graph.configs` chain — or,
+     * for a file the envelope declared `dependenciesComplete`, only
+     * `dependencies[F]` and the universal `graph.configs` chain. Adapters forward
+     * this to the bundler's `addWatchFile` so type-only inputs participate in
+     * watch-mode and persistent-cache invalidation. See {@link selectWatchInputs}
+     * for the exact derivation.
      */
     addWatchFile?: (file: string) => void;
+    /**
+     * Invoked when the plugin declared the transformed file volatile (the
+     * envelope's `volatile` list): its output depends on non-file inputs that no
+     * file-dependency snapshot can represent. Adapters should mark the module
+     * uncacheable where the bundler exposes that control (e.g. a webpack loader
+     * context's `cacheable(false)`).
+     */
+    markVolatile?: () => void;
 }
 /**
  * Apply the ttsc plugin transform to a single source file.
@@ -110,3 +146,27 @@ export declare function isDeclarationFile(id: string): boolean;
  * unnecessary module update and preserves the original source map.
  */
 export declare function createTransformResult(source: string, code: string): TtscTransformResult | undefined;
+/**
+ * Hash every input file under `projectRoot` (the same walk universe
+ * {@link matchesCachedSource} validates against), keyed by project-relative
+ * slash path. Exported so hosts without a per-build boundary (`@ttsc/metro`)
+ * can fold the identical input universe into their own cache fingerprints.
+ */
+export declare function collectProjectInputHashes(projectRoot: string): Record<string, string>;
+/**
+ * Report whether an absolute `file` belongs to the project walk universe of
+ * `root`: it lies under `root` and no segment of the relative path (including
+ * the basename) is an ignored directory name. The predicate mirrors
+ * {@link listProjectInputFiles} exactly, so "walk-visible" here means "hashed by
+ * {@link collectProjectInputHashes}". Anything else is an out-of-walk input that
+ * only the reference graph can prove relevant.
+ */
+export declare function isProjectWalkPath(root: string, file: string): boolean;
+/**
+ * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
+ * readable file, a stable `missing` marker otherwise. The marker is state, not
+ * an error — a recorded input disappearing (or reappearing) must change the
+ * comparison exactly like a content edit. Exported so `@ttsc/metro` can re-hash
+ * its recorded snapshot with identical semantics at cache-key time.
+ */
+export declare function collectExternalInputHashes(paths: readonly string[]): Record<string, string>;