@ttsc/unplugin 0.30.4 → 0.31.1

package/lib/core/transform/validation/TtscExternalDependencyWitness.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Endpoint observations of one plugin-reported dependency, taken before a
+ * compile and compared with postcompile observations during admission.
+ *
+ * The plugin reports a dependency path without recording its read contents.
+ * This witness supplies content/kind, physical target and observed metadata
+ * boundaries for the admission policy; it is not a compiler-time read proof or
+ * an atomic observation of every state during the interval.
+ *
+ * @evidence contracts/common.md#principled-implementation Content/kind, physical target, metadata and read stability retain distinct facts needed for a plugin-only precompile witness.
+ * @evidence contracts/common.md#clear-and-simple-design One record groups one dependency spelling observation without embedding its generation or validator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Metadata stability alone cannot substitute for an unobserved plugin read or a changed physical target.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain compiler-proof absence and precompile witnessing; member comments distinguish null state, unavailable metadata and raced reads.
+ * @evidence contracts/portability.md#os-neutral-implementation Physical targets, native metadata and content remain distinct representations of alias and clock behavior without OS-name assumptions.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   The carrier defines observed fields; witness capture and postcompile
+ *   validators own native reads and comparison algorithms.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The representation defines no sharing coordinator; the compile attempt
+ *   and admission owner establish the witness's valid observation window.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Attempt-owned witness maps control lifetime; this record defines no
+ *   independent handle/task acquisition or retention policy.
+ */
+export interface TtscExternalDependencyWitness {
+    /** Content or kind fingerprint, null when absent or unreadable. */
+    hash: string | null;
+    /** Physical target, null when native resolution could not select one. */
+    realpath: string | null;
+    /** Metadata signature, `undefined` when the path could not be stat'ed. */
+    signature: string | undefined;
+    /**
+     * Equality of the before/after observed signatures, including two undefined
+     * results. This flag alone proves neither usable metadata nor atomic
+     * content.
+     */
+    stable: boolean;
+}

package/lib/core/transform/validation/TtscGenerationProof.d.cts

@@ -0,0 +1,105 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.cjs";
+import type { TtscTransformCache } from "../cache/TtscTransformCache.cjs";
+import type { TtscTransformHooks } from "../watch/TtscTransformHooks.cjs";
+/**
+ * The shared ownership boundary for generation reuse in every adapter.
+ *
+ * WARNING (#1712, #1713): a module, a synchronous input-proof transaction, a
+ * delivery pass, and a persistent generation have different lifetimes. Keep
+ * those distinctions here. Do not add native preparation before every module,
+ * keep positive toolchain checks for a whole process, or make Bun's adapter
+ * invent its own cache policy. A proven pass shares its first deliveries;
+ * persistent/repeated deliveries require new current observations. Incomplete
+ * observations can share a coherent local result only inside an explicitly
+ * nonwatching pass with actual host-cache withdrawal, never a record or pool.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit pass identity, source baseline and first-delivery membership delimit sharing; synchronous transactions independently qualify current native inputs and incomplete local outputs retain stricter lifecycle admission.
+ * @evidence contracts/common.md#clear-and-simple-design One core owner supplies the same preparation, pass and fresh-only policies to every adapter instead of separate host-specific caches.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observation never becomes complete snapshot authority; watching, persistent, repeated and unknown boundaries cannot borrow an incomplete pass result.
+ * @evidence contracts/common.md#meaningful-documentation Native context names the four lifetimes and warns against the specific performance and stale-cache regressions they prevent.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Members delegate native observations to the generation's filesystem and the native environment owner.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own baseline lookup, batch qualification and admission.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members establish the distinct sharing boundaries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no registry; transactions and generations have explicit callers.
+ */
+export declare namespace TtscGenerationProof {
+    /**
+     * One synchronous admission after all asynchronous preparation has settled.
+     * Never retain this object in a generation or use it after an await.
+     *
+     * @evidence contracts/common.md#principled-implementation The exact cached owner prevents a proof of another result from supplying authority; optional native verdict is earned only by this synchronous transaction.
+     * @evidence contracts/common.md#clear-and-simple-design One transaction carries environment observations and the shared native predicate verdict.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent environment or predicate proof remains absent, never implied success.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the no-await lifetime and members distinguish owner, environment and predicate authority.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Native identity is retained by the referenced generation, not inferred by this carrier.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This carrier executes no computation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The creating operation and validators own sharing decisions.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous caller owns this handle-free carrier.
+     */
+    interface Transaction {
+        /** Exact generation being synchronously admitted. */
+        readonly cached: TtscCachedProjectTransform;
+        /** Current batch, absent when the pass already owns this input proof. */
+        readonly environments?: ReadonlyMap<string, string | undefined>;
+        /** Current native predicate verdict, unbuilt until its first gate. */
+        nativePredicates?: boolean;
+    }
+    /**
+     * Prepare native authority only when this delivery needs a new input proof.
+     * The caller must create its synchronous transaction after awaiting this.
+     *
+     * @evidence contracts/common.md#principled-implementation A qualified first-delivery pass already owns environment proof; all other requests prepare actual authority before synchronous admission.
+     * @evidence contracts/common.md#clear-and-simple-design One branch delegates native preparation rather than repeating it in adapters.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the existing explicit pass contract permits skipping preparation; no watcher silence or process lifetime substitutes for it.
+     * @evidence contracts/common.md#meaningful-documentation Prose states preparation versus transaction ordering.
+     * @evidence contracts/portability.md#os-neutral-implementation Preparation uses the actual generation filesystem and native toolchain reader.
+     * @evidence contracts/performance.md#efficient-algorithms Qualified first deliveries perform baseline/identity lookups; other deliveries delegate one preparation per unique plugin directory.
+     * @evidence contracts/performance.md#reuse-equivalent-work The pass shares its existing first-delivery proof; persistent and repeated deliveries establish new native authority.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Native requests belong to their environment owner; no transaction survives this await.
+     */
+    function prepare(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): Promise<void>;
+    /**
+     * Start fresh synchronous observation after notification and preparation
+     * awaits, sharing actual SDK queries and native predicate replay locally.
+     *
+     * @evidence contracts/common.md#principled-implementation Current environments are batch-qualified after asynchronous work; a qualified pass needs no redundant native environment observation.
+     * @evidence contracts/common.md#clear-and-simple-design One constructor binds observations to their exact generation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No current verdict is retained across deliveries or asynchronous boundaries.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the mandatory ordering and synchronous lifetime.
+     * @evidence contracts/portability.md#os-neutral-implementation Native observation remains with the environment witness owner and actual generation path identity.
+     * @evidence contracts/performance.md#efficient-algorithms Plugin selection is generation-indexed; one batch shares variable hashing and distinct SDK metadata queries.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only the following synchronous validators borrow this batch; pass sharing uses its independent first-delivery contract.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller releases the transaction at the end of synchronous admission; no registry or native handle is acquired.
+     */
+    function create(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): Transaction;
+    /**
+     * Whether this module's first delivery belongs to this generation's proven
+     * pass. A missing source baseline cannot acquire this permission.
+     *
+     * @evidence contracts/common.md#principled-implementation Epoch equality, coherent snapshot or admitted local-pass state, a recorded source and an unserved identity are all required.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate is shared by async preparation and synchronous source validation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An incomplete ordinary generation or absent module baseline cannot earn pass reuse.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the first-delivery and baseline restrictions.
+     * @evidence contracts/portability.md#os-neutral-implementation Baselines use the generation's actual identity and compiler project-key policy.
+     * @evidence contracts/performance.md#efficient-algorithms Baseline and served-set lookup avoid full input population traversal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only first deliveries in the same explicitly declared pass share its proof; repeated and later-pass requests do not.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows generation state without retaining another owner.
+     */
+    function sharesPass(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): boolean;
+    /**
+     * Admit and notify a fresh-only local delivery. A coherent pass-only success
+     * can keep its result inside this pass after releasing capture resources;
+     * every other fresh-only answer is detached before notifying the host.
+     * Callback failure always evicts the incomplete owner.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit nonwatching, consistent project lifecycle and cache-withdrawal capability are required on every successful incomplete delivery; retention additionally needs the compile's exact pass-only epoch.
+     * @evidence contracts/common.md#clear-and-simple-design One owner handles initial and cached fresh-only admission, resource release and host notification.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Incomplete output never acquires a persistent record or publication, and failed/unknown/watching capability cannot leave a reusable owner.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish local pass retention, resource release and callback failure effects.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This lifecycle operation delegates native resource release to the generation disposer.
+     * @evidence contracts/performance.md#efficient-algorithms Identity/epoch checks and one callback add no input scan; resource disposal visits the fixed tracker population.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only coherent locally admitted output in its exact nonwatching pass survives; a later pass or repeated module must obtain another result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Capture resources are released even when local output is kept; rejection and callback failure detach the owning Promise, and the cache lifecycle bounds retained result lifetime.
+     */
+    function admitFreshOnly(cached: TtscCachedProjectTransform, cache: TtscTransformCache | undefined, key: string, generation: Promise<TtscCachedProjectTransform>, epoch: number | undefined, hooks: TtscTransformHooks | undefined): void;
+}

package/lib/core/transform/validation/TtscGenerationProof.d.mts

@@ -0,0 +1,105 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform.mjs";
+import type { TtscTransformCache } from "../cache/TtscTransformCache.mjs";
+import type { TtscTransformHooks } from "../watch/TtscTransformHooks.mjs";
+/**
+ * The shared ownership boundary for generation reuse in every adapter.
+ *
+ * WARNING (#1712, #1713): a module, a synchronous input-proof transaction, a
+ * delivery pass, and a persistent generation have different lifetimes. Keep
+ * those distinctions here. Do not add native preparation before every module,
+ * keep positive toolchain checks for a whole process, or make Bun's adapter
+ * invent its own cache policy. A proven pass shares its first deliveries;
+ * persistent/repeated deliveries require new current observations. Incomplete
+ * observations can share a coherent local result only inside an explicitly
+ * nonwatching pass with actual host-cache withdrawal, never a record or pool.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit pass identity, source baseline and first-delivery membership delimit sharing; synchronous transactions independently qualify current native inputs and incomplete local outputs retain stricter lifecycle admission.
+ * @evidence contracts/common.md#clear-and-simple-design One core owner supplies the same preparation, pass and fresh-only policies to every adapter instead of separate host-specific caches.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observation never becomes complete snapshot authority; watching, persistent, repeated and unknown boundaries cannot borrow an incomplete pass result.
+ * @evidence contracts/common.md#meaningful-documentation Native context names the four lifetimes and warns against the specific performance and stale-cache regressions they prevent.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Members delegate native observations to the generation's filesystem and the native environment owner.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own baseline lookup, batch qualification and admission.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members establish the distinct sharing boundaries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no registry; transactions and generations have explicit callers.
+ */
+export declare namespace TtscGenerationProof {
+    /**
+     * One synchronous admission after all asynchronous preparation has settled.
+     * Never retain this object in a generation or use it after an await.
+     *
+     * @evidence contracts/common.md#principled-implementation The exact cached owner prevents a proof of another result from supplying authority; optional native verdict is earned only by this synchronous transaction.
+     * @evidence contracts/common.md#clear-and-simple-design One transaction carries environment observations and the shared native predicate verdict.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent environment or predicate proof remains absent, never implied success.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the no-await lifetime and members distinguish owner, environment and predicate authority.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Native identity is retained by the referenced generation, not inferred by this carrier.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This carrier executes no computation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The creating operation and validators own sharing decisions.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous caller owns this handle-free carrier.
+     */
+    interface Transaction {
+        /** Exact generation being synchronously admitted. */
+        readonly cached: TtscCachedProjectTransform;
+        /** Current batch, absent when the pass already owns this input proof. */
+        readonly environments?: ReadonlyMap<string, string | undefined>;
+        /** Current native predicate verdict, unbuilt until its first gate. */
+        nativePredicates?: boolean;
+    }
+    /**
+     * Prepare native authority only when this delivery needs a new input proof.
+     * The caller must create its synchronous transaction after awaiting this.
+     *
+     * @evidence contracts/common.md#principled-implementation A qualified first-delivery pass already owns environment proof; all other requests prepare actual authority before synchronous admission.
+     * @evidence contracts/common.md#clear-and-simple-design One branch delegates native preparation rather than repeating it in adapters.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the existing explicit pass contract permits skipping preparation; no watcher silence or process lifetime substitutes for it.
+     * @evidence contracts/common.md#meaningful-documentation Prose states preparation versus transaction ordering.
+     * @evidence contracts/portability.md#os-neutral-implementation Preparation uses the actual generation filesystem and native toolchain reader.
+     * @evidence contracts/performance.md#efficient-algorithms Qualified first deliveries perform baseline/identity lookups; other deliveries delegate one preparation per unique plugin directory.
+     * @evidence contracts/performance.md#reuse-equivalent-work The pass shares its existing first-delivery proof; persistent and repeated deliveries establish new native authority.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Native requests belong to their environment owner; no transaction survives this await.
+     */
+    function prepare(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): Promise<void>;
+    /**
+     * Start fresh synchronous observation after notification and preparation
+     * awaits, sharing actual SDK queries and native predicate replay locally.
+     *
+     * @evidence contracts/common.md#principled-implementation Current environments are batch-qualified after asynchronous work; a qualified pass needs no redundant native environment observation.
+     * @evidence contracts/common.md#clear-and-simple-design One constructor binds observations to their exact generation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No current verdict is retained across deliveries or asynchronous boundaries.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the mandatory ordering and synchronous lifetime.
+     * @evidence contracts/portability.md#os-neutral-implementation Native observation remains with the environment witness owner and actual generation path identity.
+     * @evidence contracts/performance.md#efficient-algorithms Plugin selection is generation-indexed; one batch shares variable hashing and distinct SDK metadata queries.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only the following synchronous validators borrow this batch; pass sharing uses its independent first-delivery contract.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller releases the transaction at the end of synchronous admission; no registry or native handle is acquired.
+     */
+    function create(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): Transaction;
+    /**
+     * Whether this module's first delivery belongs to this generation's proven
+     * pass. A missing source baseline cannot acquire this permission.
+     *
+     * @evidence contracts/common.md#principled-implementation Epoch equality, coherent snapshot or admitted local-pass state, a recorded source and an unserved identity are all required.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate is shared by async preparation and synchronous source validation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An incomplete ordinary generation or absent module baseline cannot earn pass reuse.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the first-delivery and baseline restrictions.
+     * @evidence contracts/portability.md#os-neutral-implementation Baselines use the generation's actual identity and compiler project-key policy.
+     * @evidence contracts/performance.md#efficient-algorithms Baseline and served-set lookup avoid full input population traversal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only first deliveries in the same explicitly declared pass share its proof; repeated and later-pass requests do not.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows generation state without retaining another owner.
+     */
+    function sharesPass(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): boolean;
+    /**
+     * Admit and notify a fresh-only local delivery. A coherent pass-only success
+     * can keep its result inside this pass after releasing capture resources;
+     * every other fresh-only answer is detached before notifying the host.
+     * Callback failure always evicts the incomplete owner.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit nonwatching, consistent project lifecycle and cache-withdrawal capability are required on every successful incomplete delivery; retention additionally needs the compile's exact pass-only epoch.
+     * @evidence contracts/common.md#clear-and-simple-design One owner handles initial and cached fresh-only admission, resource release and host notification.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Incomplete output never acquires a persistent record or publication, and failed/unknown/watching capability cannot leave a reusable owner.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish local pass retention, resource release and callback failure effects.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This lifecycle operation delegates native resource release to the generation disposer.
+     * @evidence contracts/performance.md#efficient-algorithms Identity/epoch checks and one callback add no input scan; resource disposal visits the fixed tracker population.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only coherent locally admitted output in its exact nonwatching pass survives; a later pass or repeated module must obtain another result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Capture resources are released even when local output is kept; rejection and callback failure detach the owning Promise, and the cache lifecycle bounds retained result lifetime.
+     */
+    function admitFreshOnly(cached: TtscCachedProjectTransform, cache: TtscTransformCache | undefined, key: string, generation: Promise<TtscCachedProjectTransform>, epoch: number | undefined, hooks: TtscTransformHooks | undefined): void;
+}

package/lib/core/transform/validation/TtscGenerationProof.d.ts

@@ -0,0 +1,105 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscTransformCache } from "../cache/TtscTransformCache";
+import type { TtscTransformHooks } from "../watch/TtscTransformHooks";
+/**
+ * The shared ownership boundary for generation reuse in every adapter.
+ *
+ * WARNING (#1712, #1713): a module, a synchronous input-proof transaction, a
+ * delivery pass, and a persistent generation have different lifetimes. Keep
+ * those distinctions here. Do not add native preparation before every module,
+ * keep positive toolchain checks for a whole process, or make Bun's adapter
+ * invent its own cache policy. A proven pass shares its first deliveries;
+ * persistent/repeated deliveries require new current observations. Incomplete
+ * observations can share a coherent local result only inside an explicitly
+ * nonwatching pass with actual host-cache withdrawal, never a record or pool.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit pass identity, source baseline and first-delivery membership delimit sharing; synchronous transactions independently qualify current native inputs and incomplete local outputs retain stricter lifecycle admission.
+ * @evidence contracts/common.md#clear-and-simple-design One core owner supplies the same preparation, pass and fresh-only policies to every adapter instead of separate host-specific caches.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observation never becomes complete snapshot authority; watching, persistent, repeated and unknown boundaries cannot borrow an incomplete pass result.
+ * @evidence contracts/common.md#meaningful-documentation Native context names the four lifetimes and warns against the specific performance and stale-cache regressions they prevent.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Members delegate native observations to the generation's filesystem and the native environment owner.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own baseline lookup, batch qualification and admission.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members establish the distinct sharing boundaries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no registry; transactions and generations have explicit callers.
+ */
+export declare namespace TtscGenerationProof {
+    /**
+     * One synchronous admission after all asynchronous preparation has settled.
+     * Never retain this object in a generation or use it after an await.
+     *
+     * @evidence contracts/common.md#principled-implementation The exact cached owner prevents a proof of another result from supplying authority; optional native verdict is earned only by this synchronous transaction.
+     * @evidence contracts/common.md#clear-and-simple-design One transaction carries environment observations and the shared native predicate verdict.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent environment or predicate proof remains absent, never implied success.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the no-await lifetime and members distinguish owner, environment and predicate authority.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Native identity is retained by the referenced generation, not inferred by this carrier.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This carrier executes no computation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The creating operation and validators own sharing decisions.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous caller owns this handle-free carrier.
+     */
+    interface Transaction {
+        /** Exact generation being synchronously admitted. */
+        readonly cached: TtscCachedProjectTransform;
+        /** Current batch, absent when the pass already owns this input proof. */
+        readonly environments?: ReadonlyMap<string, string | undefined>;
+        /** Current native predicate verdict, unbuilt until its first gate. */
+        nativePredicates?: boolean;
+    }
+    /**
+     * Prepare native authority only when this delivery needs a new input proof.
+     * The caller must create its synchronous transaction after awaiting this.
+     *
+     * @evidence contracts/common.md#principled-implementation A qualified first-delivery pass already owns environment proof; all other requests prepare actual authority before synchronous admission.
+     * @evidence contracts/common.md#clear-and-simple-design One branch delegates native preparation rather than repeating it in adapters.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the existing explicit pass contract permits skipping preparation; no watcher silence or process lifetime substitutes for it.
+     * @evidence contracts/common.md#meaningful-documentation Prose states preparation versus transaction ordering.
+     * @evidence contracts/portability.md#os-neutral-implementation Preparation uses the actual generation filesystem and native toolchain reader.
+     * @evidence contracts/performance.md#efficient-algorithms Qualified first deliveries perform baseline/identity lookups; other deliveries delegate one preparation per unique plugin directory.
+     * @evidence contracts/performance.md#reuse-equivalent-work The pass shares its existing first-delivery proof; persistent and repeated deliveries establish new native authority.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Native requests belong to their environment owner; no transaction survives this await.
+     */
+    function prepare(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): Promise<void>;
+    /**
+     * Start fresh synchronous observation after notification and preparation
+     * awaits, sharing actual SDK queries and native predicate replay locally.
+     *
+     * @evidence contracts/common.md#principled-implementation Current environments are batch-qualified after asynchronous work; a qualified pass needs no redundant native environment observation.
+     * @evidence contracts/common.md#clear-and-simple-design One constructor binds observations to their exact generation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No current verdict is retained across deliveries or asynchronous boundaries.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the mandatory ordering and synchronous lifetime.
+     * @evidence contracts/portability.md#os-neutral-implementation Native observation remains with the environment witness owner and actual generation path identity.
+     * @evidence contracts/performance.md#efficient-algorithms Plugin selection is generation-indexed; one batch shares variable hashing and distinct SDK metadata queries.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only the following synchronous validators borrow this batch; pass sharing uses its independent first-delivery contract.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller releases the transaction at the end of synchronous admission; no registry or native handle is acquired.
+     */
+    function create(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): Transaction;
+    /**
+     * Whether this module's first delivery belongs to this generation's proven
+     * pass. A missing source baseline cannot acquire this permission.
+     *
+     * @evidence contracts/common.md#principled-implementation Epoch equality, coherent snapshot or admitted local-pass state, a recorded source and an unserved identity are all required.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate is shared by async preparation and synchronous source validation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An incomplete ordinary generation or absent module baseline cannot earn pass reuse.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the first-delivery and baseline restrictions.
+     * @evidence contracts/portability.md#os-neutral-implementation Baselines use the generation's actual identity and compiler project-key policy.
+     * @evidence contracts/performance.md#efficient-algorithms Baseline and served-set lookup avoid full input population traversal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only first deliveries in the same explicitly declared pass share its proof; repeated and later-pass requests do not.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows generation state without retaining another owner.
+     */
+    function sharesPass(cached: TtscCachedProjectTransform, file: string, epoch: number | undefined): boolean;
+    /**
+     * Admit and notify a fresh-only local delivery. A coherent pass-only success
+     * can keep its result inside this pass after releasing capture resources;
+     * every other fresh-only answer is detached before notifying the host.
+     * Callback failure always evicts the incomplete owner.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit nonwatching, consistent project lifecycle and cache-withdrawal capability are required on every successful incomplete delivery; retention additionally needs the compile's exact pass-only epoch.
+     * @evidence contracts/common.md#clear-and-simple-design One owner handles initial and cached fresh-only admission, resource release and host notification.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Incomplete output never acquires a persistent record or publication, and failed/unknown/watching capability cannot leave a reusable owner.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish local pass retention, resource release and callback failure effects.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This lifecycle operation delegates native resource release to the generation disposer.
+     * @evidence contracts/performance.md#efficient-algorithms Identity/epoch checks and one callback add no input scan; resource disposal visits the fixed tracker population.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only coherent locally admitted output in its exact nonwatching pass survives; a later pass or repeated module must obtain another result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Capture resources are released even when local output is kept; rejection and callback failure detach the owning Promise, and the cache lifecycle bounds retained result lifetime.
+     */
+    function admitFreshOnly(cached: TtscCachedProjectTransform, cache: TtscTransformCache | undefined, key: string, generation: Promise<TtscCachedProjectTransform>, epoch: number | undefined, hooks: TtscTransformHooks | undefined): void;
+}

package/lib/core/transform/validation/TtscGenerationProof.js

@@ -0,0 +1,149 @@
+'use strict';
+
+var pluginSource = require('ttsc/plugin-source');
+var disposeCachedTransform = require('../cache/disposeCachedTransform.js');
+var evictGeneration = require('../cache/evictGeneration.js');
+var resultFilesystem = require('../cache/resultFilesystem.js');
+var envelopeDerivation = require('../envelope/envelopeDerivation.js');
+var selectPluginSourceInputs = require('../envelope/selectPluginSourceInputs.js');
+var pathIdentityKey = require('../filesystem/pathIdentityKey.js');
+var preparePluginBuildEnvironments = require('../inputs/preparePluginBuildEnvironments.js');
+var toProjectKey = require('../project/toProjectKey.js');
+
+/**
+ * The shared ownership boundary for generation reuse in every adapter.
+ *
+ * WARNING (#1712, #1713): a module, a synchronous input-proof transaction, a
+ * delivery pass, and a persistent generation have different lifetimes. Keep
+ * those distinctions here. Do not add native preparation before every module,
+ * keep positive toolchain checks for a whole process, or make Bun's adapter
+ * invent its own cache policy. A proven pass shares its first deliveries;
+ * persistent/repeated deliveries require new current observations. Incomplete
+ * observations can share a coherent local result only inside an explicitly
+ * nonwatching pass with actual host-cache withdrawal, never a record or pool.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit pass identity, source baseline and first-delivery membership delimit sharing; synchronous transactions independently qualify current native inputs and incomplete local outputs retain stricter lifecycle admission.
+ * @evidence contracts/common.md#clear-and-simple-design One core owner supplies the same preparation, pass and fresh-only policies to every adapter instead of separate host-specific caches.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing observation never becomes complete snapshot authority; watching, persistent, repeated and unknown boundaries cannot borrow an incomplete pass result.
+ * @evidence contracts/common.md#meaningful-documentation Native context names the four lifetimes and warns against the specific performance and stale-cache regressions they prevent.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Members delegate native observations to the generation's filesystem and the native environment owner.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own baseline lookup, batch qualification and admission.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Members establish the distinct sharing boundaries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no registry; transactions and generations have explicit callers.
+ */
+exports.TtscGenerationProof = void 0;
+(function (TtscGenerationProof) {
+    /**
+     * Prepare native authority only when this delivery needs a new input proof.
+     * The caller must create its synchronous transaction after awaiting this.
+     *
+     * @evidence contracts/common.md#principled-implementation A qualified first-delivery pass already owns environment proof; all other requests prepare actual authority before synchronous admission.
+     * @evidence contracts/common.md#clear-and-simple-design One branch delegates native preparation rather than repeating it in adapters.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the existing explicit pass contract permits skipping preparation; no watcher silence or process lifetime substitutes for it.
+     * @evidence contracts/common.md#meaningful-documentation Prose states preparation versus transaction ordering.
+     * @evidence contracts/portability.md#os-neutral-implementation Preparation uses the actual generation filesystem and native toolchain reader.
+     * @evidence contracts/performance.md#efficient-algorithms Qualified first deliveries perform baseline/identity lookups; other deliveries delegate one preparation per unique plugin directory.
+     * @evidence contracts/performance.md#reuse-equivalent-work The pass shares its existing first-delivery proof; persistent and repeated deliveries establish new native authority.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Native requests belong to their environment owner; no transaction survives this await.
+     */
+    async function prepare(cached, file, epoch) {
+        if (!sharesPass(cached, file, epoch))
+            await preparePluginBuildEnvironments.preparePluginBuildEnvironments(cached.result, resultFilesystem.resultFilesystem(cached.result), cached);
+    }
+    TtscGenerationProof.prepare = prepare;
+    /**
+     * Start fresh synchronous observation after notification and preparation
+     * awaits, sharing actual SDK queries and native predicate replay locally.
+     *
+     * @evidence contracts/common.md#principled-implementation Current environments are batch-qualified after asynchronous work; a qualified pass needs no redundant native environment observation.
+     * @evidence contracts/common.md#clear-and-simple-design One constructor binds observations to their exact generation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No current verdict is retained across deliveries or asynchronous boundaries.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the mandatory ordering and synchronous lifetime.
+     * @evidence contracts/portability.md#os-neutral-implementation Native observation remains with the environment witness owner and actual generation path identity.
+     * @evidence contracts/performance.md#efficient-algorithms Plugin selection is generation-indexed; one batch shares variable hashing and distinct SDK metadata queries.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only the following synchronous validators borrow this batch; pass sharing uses its independent first-delivery contract.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller releases the transaction at the end of synchronous admission; no registry or native handle is acquired.
+     */
+    function create(cached, file, epoch) {
+        return {
+            cached,
+            ...(sharesPass(cached, file, epoch)
+                ? {}
+                : {
+                    environments: pluginSource.PluginBuildEnvironmentReadings.cachedAll(selectPluginSourceInputs.selectPluginSourceInputs(cached.result).keys()),
+                }),
+        };
+    }
+    TtscGenerationProof.create = create;
+    /**
+     * Whether this module's first delivery belongs to this generation's proven
+     * pass. A missing source baseline cannot acquire this permission.
+     *
+     * @evidence contracts/common.md#principled-implementation Epoch equality, coherent snapshot or admitted local-pass state, a recorded source and an unserved identity are all required.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate is shared by async preparation and synchronous source validation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An incomplete ordinary generation or absent module baseline cannot earn pass reuse.
+     * @evidence contracts/common.md#meaningful-documentation Prose states the first-delivery and baseline restrictions.
+     * @evidence contracts/portability.md#os-neutral-implementation Baselines use the generation's actual identity and compiler project-key policy.
+     * @evidence contracts/performance.md#efficient-algorithms Baseline and served-set lookup avoid full input population traversal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only first deliveries in the same explicitly declared pass share its proof; repeated and later-pass requests do not.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows generation state without retaining another owner.
+     */
+    function sharesPass(cached, file, epoch) {
+        if (epoch === undefined ||
+            cached.deliveryEpoch !== epoch ||
+            (cached.projectSnapshotComplete !== true &&
+                cached.passDeliveryOnly !== true) ||
+            (cached.freshDeliveryOnly === true && cached.passDeliveryOnly !== true))
+            return false;
+        const identities = envelopeDerivation.envelopeDerivation(cached).identityContext;
+        const identity = pathIdentityKey.pathIdentityKey(file, identities);
+        if (cached.servedFiles?.has(identity))
+            return false;
+        const key = toProjectKey.toProjectKey(cached.projectRoot, file, identities);
+        return (cached.sourceHashes?.[identity] !== undefined ||
+            Object.hasOwn(cached.inputHashes, key) ||
+            cached.externalInputHashes?.[identity] !== undefined);
+    }
+    TtscGenerationProof.sharesPass = sharesPass;
+    /**
+     * Admit and notify a fresh-only local delivery. A coherent pass-only success
+     * can keep its result inside this pass after releasing capture resources;
+     * every other fresh-only answer is detached before notifying the host.
+     * Callback failure always evicts the incomplete owner.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit nonwatching, consistent project lifecycle and cache-withdrawal capability are required on every successful incomplete delivery; retention additionally needs the compile's exact pass-only epoch.
+     * @evidence contracts/common.md#clear-and-simple-design One owner handles initial and cached fresh-only admission, resource release and host notification.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Incomplete output never acquires a persistent record or publication, and failed/unknown/watching capability cannot leave a reusable owner.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish local pass retention, resource release and callback failure effects.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This lifecycle operation delegates native resource release to the generation disposer.
+     * @evidence contracts/performance.md#efficient-algorithms Identity/epoch checks and one callback add no input scan; resource disposal visits the fixed tracker population.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only coherent locally admitted output in its exact nonwatching pass survives; a later pass or repeated module must obtain another result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Capture resources are released even when local output is kept; rejection and callback failure detach the owning Promise, and the cache lifecycle bounds retained result lifetime.
+     */
+    function admitFreshOnly(cached, cache, key, generation, epoch, hooks) {
+        if (cached.freshDeliveryOnly !== true)
+            return;
+        const authorized = hooks?.watching === false &&
+            hooks.markVolatile !== undefined &&
+            (hooks.project?.watching === undefined ||
+                hooks.project.watching === false);
+        const retain = authorized &&
+            epoch !== undefined &&
+            cached.deliveryEpoch === epoch &&
+            cached.passDeliveryOnly === true;
+        disposeCachedTransform.disposeCachedTransform(cached);
+        if (!retain)
+            evictGeneration.evictGeneration(cache, key, generation);
+        if (cached.result.type === "success" && !authorized)
+            throw new Error("@ttsc/unplugin: plugin input observation is unavailable; fresh output requires an explicitly nonwatching host with supported cache withdrawal. Watching, unknown or contradictory lifecycles cannot safely observe its changes.");
+        try {
+            hooks?.markVolatile?.();
+        }
+        catch (error) {
+            evictGeneration.evictGeneration(cache, key, generation);
+            throw error;
+        }
+    }
+    TtscGenerationProof.admitFreshOnly = admitFreshOnly;
+})(exports.TtscGenerationProof || (exports.TtscGenerationProof = {}));
+//# sourceMappingURL=TtscGenerationProof.js.map

package/lib/core/transform/validation/TtscGenerationProof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscGenerationProof.js","sources":["../../../../src/core/transform/validation/TtscGenerationProof.ts"],"sourcesContent":[null],"names":["TtscGenerationProof","preparePluginBuildEnvironments","resultFilesystem","PluginBuildEnvironmentReadings","selectPluginSourceInputs","envelopeDerivation","pathIdentityKey","toProjectKey","disposeCachedTransform","evictGeneration"],"mappings":"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"}