@ttsc/unplugin 0.30.4 → 0.31.1

package/src/core/transform/generation/captureTransformSourceHashes.ts

@@ -0,0 +1,50 @@
+import path from "node:path";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { resultFilesystem } from "../cache/resultFilesystem";
+import { envelopeDerivation } from "../envelope/envelopeDerivation";
+import { pathIdentityKey } from "../filesystem/pathIdentityKey";
+import { hostInputStateHash } from "../inputs/hostInputStateHash";
+
+/**
+ * Capture native host-state hashes for source paths named by transform outputs,
+ * including sources outside the project walk. Reads hash raw bytes; a failed
+ * read of an observed directory retains the host-state directory marker, while
+ * other unreadable output paths remain absent.
+ *
+ * The current source identity is then overwritten with the caller's selected
+ * hash even when no output names it. Capture supplies its post-compile project
+ * walk's disk hash when available and otherwise the delivered-text hash; that
+ * fallback does not establish that the compiler observed those bytes. If the
+ * output pass already read this source, the final assignment does not undo it.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful output keys identify source paths relative to the project; native host-state hashes become identity-keyed baselines and the caller's selected disk-or-delivery hash overrides the current identity without granting generation completeness.
+ * @evidence contracts/common.md#clear-and-simple-design This helper constructs only the source baseline map; resultFilesystem supplies native reads and envelopeDerivation supplies the generation's shared identity context.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Non-directory failed reads supply no fabricated output-source hash, and transformed output text is never hashed as source. The explicitly supplied current-source fallback is distinguished from native disk evidence; the capture owner separately decides completeness and reuse.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish raw host state, directory markers and failed reads from the current source's caller-selected fallback and explain the output-pass read that an override cannot avoid.
+ * @evidence contracts/portability.md#os-neutral-implementation Output paths are resolved with Node native semantics and compared through the envelope identity context; no case folding or OS-specific file reader is introduced.
+ * @evidence contracts/performance.md#efficient-algorithms Object.keys allocates the full output-key array, then one pass resolves native spellings, reads and hashes each exposed source's bytes and inserts successful host states. Failed reads may stat; identity resolution may observe uncached ancestors and case capabilities. Distinct output spellings may repeat a physical read before sharing one key. Map storage grows with distinct identities and key text; the final current assignment adds no read beyond that pass.
+ * @evidence contracts/performance.md#reuse-equivalent-work The caller's selected current hash and the immutable envelope's identity transaction are reused; the output pass does not memoize content reads by physical identity. The fresh map belongs to this capture rather than reusing historical content across changes.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Generation capture owns the returned baseline map's lifetime; this helper acquires no retained handle or observer.
+ */
+export function captureTransformSourceHashes(
+  /** Generation supplying native reads, output names and shared identity. */
+  cached: TtscCachedProjectTransform,
+  /** Requested native source spelling, included even without an output key. */
+  currentFile: string,
+  /** Caller-selected post-compile walk hash or delivered-text fallback. */
+  currentSourceHash: string,
+): Record<string, string> {
+  const filesystem = resultFilesystem(cached.result);
+  const identities = envelopeDerivation(cached).identityContext;
+  const hashes: Record<string, string> = {};
+  if (cached.result.type === "success") {
+    for (const output of Object.keys(cached.result.typescript)) {
+      const file = path.resolve(cached.projectRoot, output);
+      const hash = hostInputStateHash(file, filesystem);
+      if (hash !== null) hashes[pathIdentityKey(file, identities)] = hash;
+    }
+  }
+  hashes[pathIdentityKey(currentFile, identities)] = currentSourceHash;
+  return hashes;
+}

package/src/core/transform/generation/carryTransformAttemptInputs.ts

@@ -0,0 +1,44 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+
+/**
+ * Carry the rejected capture's learned names and compiler rule into its retry.
+ *
+ * Exact dependency spellings form an insertion-ordered union, not a physical
+ * identity index. The next capture observes those names again before compiling;
+ * retaining a name supplies no retained byte, metadata or notification proof.
+ * An absent captured case answer leaves the previous answer unchanged.
+ *
+ * @evidence contracts/common.md#principled-implementation A fresh Set preserves prior insertion order and adds newly reported external names once under string equality. Nullish case precedence preserves explicit false and a previous unknown answer.
+ * @evidence contracts/common.md#clear-and-simple-design This input transition returns next-attempt facts without mutating the supplied Set or capture; the retry caller owns capture admission, observation and disposal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Learned names are not native identity or fresh proof, and no omitted diagnostic witness is invented as a dependency. Reported external inputs remain distinct from bounded failure samples.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains lexical union order, optional case carry and the requirement for the next capture to obtain new observations.
+ * @evidence contracts/portability.md#os-neutral-implementation Carries the compiler comparison boolean unchanged and keeps reported native spellings distinct; it neither folds paths by OS name nor canonicalizes them without the filesystem owner.
+ * @evidence contracts/performance.md#efficient-algorithms One Set copy plus one reported-input scan preserves nonmutation and insertion order. Time follows prior and reported name counts with string hashing costs; temporary Set space follows their unique union. This copy replaces the retry owner's in-place update and is not claimed to accelerate it.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Carries names and a comparison rule, not observations or reusable compilation proof; the next capture must witness its own environment.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transfers a newly allocated Set to the retry owner without storing history or acquiring handles. The caller owns cumulative name retention and capture-resource release.
+ */
+export function carryTransformAttemptInputs(
+  witnessed: ReadonlySet<string>,
+  useCaseSensitiveFileNames: boolean | undefined,
+  captured: Pick<
+    TtscCachedProjectTransform,
+    "externalDependencyInputs" | "membershipPolicy"
+  >,
+): {
+  /** Caller-owned lexical union to observe before the next compilation. */
+  witnessed: Set<string>;
+
+  /** Latest supplied compiler rule, preserving unknown when none is available. */
+  useCaseSensitiveFileNames: boolean | undefined;
+} {
+  const nextWitnessed = new Set(witnessed);
+  for (const dependency of captured.externalDependencyInputs ?? []) {
+    nextWitnessed.add(dependency);
+  }
+  return {
+    witnessed: nextWitnessed,
+    useCaseSensitiveFileNames:
+      captured.membershipPolicy.useCaseSensitiveFileNames ??
+      useCaseSensitiveFileNames,
+  };
+}

package/src/core/transform/generation/createGenerationProofFailures.ts

@@ -0,0 +1,18 @@
+import type { TtscGenerationProofFailures } from "./TtscGenerationProofFailures";
+
+/**
+ * Create a fresh proof-witness collection for one transform attempt. Its
+ * recorder bounds retained entries and their deduplication identities.
+ *
+ * @evidence contracts/common.md#principled-implementation Empty entries, zero omitted occurrences and an empty seen set establish the recorder's initial aggregate invariants.
+ * @evidence contracts/common.md#clear-and-simple-design This constructor supplies only fresh aggregate storage; the recorder owns limits and identity composition.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An attempt receives independent storage rather than sharing mutable witnesses from an earlier compile or manufacturing an initial verdict.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies per-attempt ownership and the recorder's bounding responsibility before separated acknowledgments.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Fresh storage transfers to the attempt owner and its terminal diagnostic sequence; recordGenerationProofFailure bounds entry and identity counts at eight, while retained witness text follows supplied lengths. This constructor owns no handle or separate historical collection.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Allocates an empty collection.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Creates a new collection per attempt by definition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Allocates an empty collection and reads no filesystem or path.
+ */
+export function createGenerationProofFailures(): TtscGenerationProofFailures {
+  return { entries: [], omitted: 0, seen: new Set() };
+}

package/src/core/transform/generation/createUnstableGenerationError.ts

@@ -0,0 +1,81 @@
+import path from "node:path";
+
+import { disposeCachedTransform } from "../cache/disposeCachedTransform";
+import { TtscUnstableGenerationError } from "../errors/TtscUnstableGenerationError";
+import type { TtscFailedGenerationValidation } from "./TtscFailedGenerationValidation";
+import type { TtscGenerationProofFailures } from "./TtscGenerationProofFailures";
+
+/** Render one input without leaking source content or control characters. */
+function formatGenerationFailurePath(
+  projectRoot: string,
+  input: string,
+): string {
+  const absolute = path.resolve(input);
+  const relative = path.relative(projectRoot, absolute);
+  const display =
+    relative === ""
+      ? "."
+      : relative !== ".." &&
+          !relative.startsWith(`..${path.sep}`) &&
+          !path.isAbsolute(relative)
+        ? relative
+        : absolute;
+  return JSON.stringify(display.split(path.sep).join("/"));
+}
+
+/**
+ * Build the terminal error shared by waiters of an unstable generation, with
+ * bounded per-attempt witnesses and a retained retry comparison baseline. Live
+ * generation fields detach and their cleanup is attempted before the error
+ * retains that data; failed native cleanup is not certified released. Producer
+ * details and native paths are JSON-escaped for safe diagnostics.
+ *
+ * @evidence contracts/common.md#principled-implementation Each attempted proof contributes its classified witnesses and omitted count, while absent retained entries remain an explicit incomplete proof; the validation baseline identifies the environment that can authorize retry.
+ * @evidence contracts/common.md#clear-and-simple-design Error rendering stays here, path attribution uses one private formatter and live generation disposal delegates to the shared lifecycle owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unstable proof is reported rather than converted into reusable output; dropped witnesses remain visible and diagnostic control characters cannot create fictitious lines.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes shared terminal error data from released live resources and explains bounded witnesses and escaped producer input.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative-path classification uses Node path semantics; slash rendering is only diagnostic presentation and does not change filesystem identity or project ownership.
+ * @evidence contracts/performance.md#efficient-algorithms Rendering visits each attempt and retained witness once, with native path processing and escaping driven by diagnostic text lengths; delegated disposal also closes the final attempt's retained watchers without rescanning source contents.
+ * @evidence contracts/performance.md#reuse-equivalent-work transformProject creates one terminal verdict for its failed attempt sequence, and cache waiters share that error instead of separately rerendering or recompiling the same unchanged environment.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The shared disposer detaches watcher/probe ownership and attempts each cleanup before the error retains comparison data. Failed native close/removal can leave underlying resources; the error does not acquire their handles or claim cleanup succeeded. Retained comparison/witness text has cache-owner lifetime and no byte bound from the witness-count cap.
+ */
+export function createUnstableGenerationError(
+  projectRoot: string,
+  attempts: readonly TtscGenerationProofFailures[],
+  validation: TtscFailedGenerationValidation,
+): TtscUnstableGenerationError {
+  const lines = [
+    `ttsc: could not capture a reusable transform generation after ${attempts.length} attempts.`,
+    `  project: ${JSON.stringify(projectRoot)}`,
+  ];
+  attempts.forEach((failures, index) => {
+    lines.push(`  attempt ${index + 1}:`);
+    if (failures.entries.length === 0) {
+      lines.push("    - project/generation-proof-incomplete");
+    }
+    for (const failure of failures.entries) {
+      const input =
+        failure.path === undefined
+          ? ""
+          : `: ${formatGenerationFailurePath(projectRoot, failure.path)}`;
+      const detail =
+        failure.detail === undefined
+          ? ""
+          : ` (producer: ${JSON.stringify(failure.detail)})`;
+      lines.push(`    - ${failure.domain}/${failure.kind}${input}${detail}`);
+    }
+    if (failures.omitted !== 0) {
+      lines.push(
+        `    - ... ${failures.omitted} additional witness(es) omitted`,
+      );
+    }
+  });
+  lines.push(
+    "  Stop writes to the listed inputs before compilation, or fix the producer that omitted or contradicted the listed proof.",
+  );
+  // The failed snapshot remains useful as immutable retry evidence, but it can
+  // never serve a module. Release every live resource before its terminal
+  // verdict is retained in the cache.
+  disposeCachedTransform(validation.cached);
+  return new TtscUnstableGenerationError(lines.join("\n"), validation);
+}

package/src/core/transform/generation/failedGenerationEnvironmentChanged.ts

@@ -0,0 +1,171 @@
+import { PluginBuildEnvironmentReadings } from "ttsc/plugin-source";
+
+import { refreshProcessClockReference } from "../clock/refreshProcessClockReference";
+import { envelopeDerivation } from "../envelope/envelopeDerivation";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { pathIdentityKey } from "../filesystem/pathIdentityKey";
+import { hostInputStateHash } from "../inputs/hostInputStateHash";
+import { inputMetadataEvidence } from "../inputs/inputMetadataEvidence";
+import { pluginSourceHolds } from "../inputs/pluginSourceHolds";
+import { pluginSourceState } from "../inputs/pluginSourceState";
+import { usesPreparedPluginBuildEnvironments } from "../inputs/preparePluginBuildEnvironments";
+import { collectProjectInputSnapshot } from "../project/collectProjectInputSnapshot";
+import { hashText } from "../utils/hashText";
+import { MISSING_INPUT_STATE } from "../validation/MISSING_INPUT_STATE";
+import { sameHashes } from "../validation/sameHashes";
+import { sameProjectDirectories } from "../validation/sameProjectDirectories";
+import { walkSnapshotComplete } from "../validation/walkSnapshotComplete";
+import { TERMINAL_ENVIRONMENT_VERDICTS } from "./TERMINAL_ENVIRONMENT_VERDICTS";
+import type { TtscFailedGenerationValidation } from "./TtscFailedGenerationValidation";
+import { failedGenerationInputState } from "./failedGenerationInputState";
+import { projectWalkFailureFingerprint } from "./projectWalkFailureFingerprint";
+
+/**
+ * Whether current observations refute a terminal proof failure's recorded
+ * environment.
+ *
+ * This is deliberately a confirmation test. Escaping probe exceptions retain
+ * the old verdict; represented unavailable fingerprints can differ from prior
+ * observations and trigger retry without proving a physical content change.
+ * Cache lifecycle reset remains the unconditional recovery boundary.
+ *
+ * The delivered module's own text is checked on every delivery. The rest of the
+ * environment, the project walk and every recorded input outside it, is
+ * confirmed once per event-loop turn and shared by that turn's deliveries, and
+ * it is proven by metadata first, as live validation does: a file or input
+ * whose separable signature still matches carries its recorded state and is not
+ * read again (samchon/ttsc#1398). Separable means against a clock reference the
+ * confirmation mints itself before it reads, as a delivery does, so a write a
+ * clock rollback put into a recorded stamp's tick is read. The generation's own
+ * probe directory was released with it, so the reference is minted in the probe
+ * directory this process keeps (`refreshProcessClockReference`).
+ *
+ * The shared verdict remains until its scheduled setImmediate eviction runs.
+ * Writes after confirmation can therefore be missed by that window's later
+ * deliveries, apart from their independent delivered-text/disk check. Host
+ * delivery timing is not guaranteed here; lifecycle reset bypasses retained
+ * terminal state.
+ *
+ * @evidence contracts/common.md#principled-implementation Delivered-source divergence is checked against its disk baseline before sharing an environment verdict. Current project/failure or exact/tree state can refute the terminal baseline; represented unavailable observations may differ, while escaping exceptions return false. Neither false nor unavailable markers certify a reusable success.
+ * @evidence contracts/common.md#clear-and-simple-design The exported boundary handles per-delivery text and turn-shared coordination, while its private environment comparator owns walk and out-of-walk revalidation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A text-only upstream rewrite does not replace the compiler's disk baseline. Explicit failure fingerprints stay retry-comparison data rather than fabricated readable content; an escaping probe exception is not invented evidence of change.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain confirmation rather than successful-generation proof, current-turn sharing, clock separation and next-turn freshness limitations, with props and tags visibly separated.
+ * @evidence contracts/portability.md#os-neutral-implementation Filesystem identity and metadata separation use the supplied host operations and process clock reference; plugin tree state uses the same native build environment composition that keyed its binary.
+ * @evidence contracts/performance.md#efficient-algorithms Each delivery hashes supplied text and queries native identity, conditionally reading source bytes before any memo hit. A cold environment check refreshes clock proof, walks the project, compares file/directory/failure populations and validates all reached recorded inputs; metadata-separable matches avoid ordinary full fingerprints, while trees retain source/build scans. Costs include text/bytes, native access and delegated sorting/encoding, not just input count.
+ * @evidence contracts/performance.md#reuse-equivalent-work One verdict per validation object is shared until its setImmediate eviction callback runs. Stable validation contents and the same coherent host view are caller premises; delivered-text/disk checks remain outside sharing. This window can miss later same-window environment changes and does not establish success authority.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The WeakMap stores one boolean per reached validation object; each scheduled eviction callback temporarily keeps that object reachable until execution. There is no object-count cap or eviction deadline here. Baseline bytes belong to terminal/cache lifetime, while the shared process-clock owner controls probe acquisition and cleanup; this comparator does not acquire a generation watcher.
+ */
+export function failedGenerationEnvironmentChanged(
+  validation: TtscFailedGenerationValidation,
+  props: {
+    /** Native source path requested by this delivery. */
+    currentFile: string;
+
+    /** Host-supplied text checked separately from the turn-shared environment. */
+    currentSource: string;
+
+    /** Same host filesystem boundary that observed the cached generation. */
+    filesystem: TtscTransformFilesystemOperations;
+  },
+): boolean {
+  try {
+    const identities = envelopeDerivation(validation.cached).identityContext;
+    const currentSourceHash = hashText(props.currentSource);
+    const expectedSourceHash =
+      validation.cached.sourceHashes?.[
+        pathIdentityKey(props.currentFile, identities)
+      ];
+    // A delivered text that differs from the file changes nothing while the
+    // disk still holds the bytes the compile read (samchon/ttsc#1394).
+    if (
+      expectedSourceHash !== undefined &&
+      expectedSourceHash !== currentSourceHash &&
+      hostInputStateHash(props.currentFile, props.filesystem) !==
+        expectedSourceHash
+    ) {
+      return true;
+    }
+    const shared = TERMINAL_ENVIRONMENT_VERDICTS.get(validation);
+    if (shared !== undefined) return shared;
+    const verdict = environmentChanged(validation, props.filesystem);
+    TERMINAL_ENVIRONMENT_VERDICTS.set(validation, verdict);
+    setImmediate(() => TERMINAL_ENVIRONMENT_VERDICTS.delete(validation));
+    return verdict;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Confirm the project walk and every recorded input outside it. A plugin tree
+ * always validates its full source/build state before ordinary-path metadata
+ * reuse is considered, because parent metadata cannot prove descendant state.
+ */
+function environmentChanged(
+  validation: TtscFailedGenerationValidation,
+  filesystem: TtscTransformFilesystemOperations,
+): boolean {
+  refreshProcessClockReference(validation.cached.projectRoot, filesystem);
+  const identities = envelopeDerivation(validation.cached).identityContext;
+  const current = collectProjectInputSnapshot(
+    validation.cached.projectRoot,
+    identities,
+    filesystem,
+    {
+      hashes: validation.projectInputHashes,
+      signatures: validation.cached.inputSignatures ?? {},
+    },
+    { policy: validation.cached.membershipPolicy },
+  );
+  if (
+    validation.projectWalkComplete !==
+      walkSnapshotComplete(current, validation.declaredInputs) ||
+    validation.projectWalkFailures !==
+      projectWalkFailureFingerprint(
+        current,
+        validation.declaredInputs,
+        validation.cached.projectRoot,
+        identities,
+      ) ||
+    !sameHashes(
+      validation.projectInputHashes,
+      current.hashes,
+      validation.declaredInputs,
+    ) ||
+    !sameProjectDirectories(
+      validation.cached.projectDirectories ?? [],
+      current.projectDirectories,
+    )
+  ) {
+    return true;
+  }
+  for (const [input, recorded] of validation.inputStates) {
+    if (recorded.tree) {
+      // A plugin source that could not be read then moved once it can be.
+      // The async delivery owner prepares native authority before confirmation.
+      const prepared = usesPreparedPluginBuildEnvironments(
+        validation.cached.result,
+      )
+        ? { environment: PluginBuildEnvironmentReadings.cached(input) }
+        : undefined;
+      if (
+        recorded.state === MISSING_INPUT_STATE
+          ? pluginSourceState(input, prepared) !== null
+          : !pluginSourceHolds(input, recorded.state, filesystem, prepared)
+      )
+        return true;
+      continue;
+    }
+    const evidence = inputMetadataEvidence(input, filesystem);
+    if (
+      recorded.signature !== undefined &&
+      evidence?.separable === true &&
+      evidence.signature === recorded.signature
+    ) {
+      continue;
+    }
+    if (failedGenerationInputState(input, filesystem) !== recorded.state)
+      return true;
+  }
+  return false;
+}

package/src/core/transform/generation/failedGenerationInputState.ts

@@ -0,0 +1,56 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { hostInputRealpath } from "../inputs/hostInputRealpath";
+import { hostInputStateHash } from "../inputs/hostInputStateHash";
+import { inputMetadataSignature } from "../inputs/inputMetadataSignature";
+import { hashText } from "../utils/hashText";
+import { MISSING_INPUT_STATE } from "../validation/MISSING_INPUT_STATE";
+
+/**
+ * Digest one exact out-of-walk path's metadata, content state, physical target
+ * and directory listing. Failed directory observation is distinct from a path
+ * that is not a directory; this is a retry-change fingerprint, not a success
+ * proof of an unreadable input.
+ *
+ * @evidence contracts/common.md#principled-implementation Metadata, host state, realpath and sorted entry-kind observations jointly represent exact-path changes; missing/unavailable states remain explicit in the serialized digest.
+ * @evidence contracts/common.md#clear-and-simple-design Existing input helpers own metadata/content/identity reads; this operation composes them with directory membership into one compact terminal comparison value.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Observation failures cannot equal an invented valid directory state, and a retained failure fingerprint does not certify unreadable compiler input.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies fingerprint components, failed-directory distinctions and the difference between retry comparison and reusable-generation proof.
+ * @evidence contracts/portability.md#os-neutral-implementation All native observations use the injected filesystem boundary and host helpers; directory entry classifications come from actual Dirent capabilities rather than suffix or OS-name guesses.
+ * @evidence contracts/performance.md#efficient-algorithms Following kind, metadata, content and realpath observations each retain native path/access costs; helpers can reread metadata and resolve ancestors rather than making a fixed observation count a time bound. A directory's N entries are materialized, their name/kind text sorted and joined before hashing, with comparison/encoding costs driven by text bytes and O(N) listing/frame storage. Content hashing additionally reads available bytes; sorting removes enumeration-order effects, not observation failures.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This fresh observation fingerprint establishes a current comparison value; terminal environment validation owns metadata-first reuse and turn-shared verdicts.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only a digest transfers to the caller; this operation owns no historical input-state cache, native handle or watcher lifecycle.
+ */
+export function failedGenerationInputState(
+  input: string,
+  filesystem: TtscTransformFilesystemOperations,
+): string {
+  let directory = "not-directory";
+  try {
+    if (filesystem.stat(input).isDirectory()) {
+      directory = hashText(
+        filesystem
+          .readdir(input)
+          .map((entry) =>
+            [
+              entry.name,
+              entry.isDirectory(),
+              entry.isFile(),
+              entry.isSymbolicLink(),
+            ].join(":"),
+          )
+          .sort()
+          .join("\0"),
+      );
+    }
+  } catch {
+    directory = "unavailable";
+  }
+  return hashText(
+    JSON.stringify([
+      inputMetadataSignature(input, filesystem) ?? "missing",
+      hostInputStateHash(input, filesystem) ?? MISSING_INPUT_STATE,
+      hostInputRealpath(input, filesystem),
+      directory,
+    ]),
+  );
+}

package/src/core/transform/generation/mergeGenerationProofFailures.ts

@@ -0,0 +1,38 @@
+import type { TtscGenerationProofFailures } from "./TtscGenerationProofFailures";
+import { recordGenerationProofFailure } from "./recordGenerationProofFailure";
+
+/**
+ * Fold source witnesses into a target through the shared bounded recorder.
+ * Source omissions remain counted because their lost identities cannot be
+ * deduplicated against the target's retained evidence.
+ *
+ * Capture supplies distinct source and target collections, leaving the source
+ * unchanged. Retained witnesses are shared references, so producers must treat
+ * their classifications as fixed after recording.
+ *
+ * @evidence contracts/common.md#principled-implementation Retained source entries use the target recorder's identity policy, while saturated addition preserves already omitted occurrence counts that cannot be recovered from source entries.
+ * @evidence contracts/common.md#clear-and-simple-design This operation coordinates aggregation without duplicating recorder limits or witness identity encoding.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing witnesses remain omitted rather than being silently converted into proof success or guessed unique identities.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain shared recorder ownership and the reason lost source identities cannot be deduplicated.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Merge visits the source's recorder-bounded retained entries once. Each
+ *   delegated insertion encodes the complete witness tuple and queries its
+ *   identity, so work and temporary encoded keys retain witness-text cost even
+ *   with at most eight entries. Omission addition is constant work; discarded
+ *   evidence is not reconstructed.
+ * @evidence contracts/performance.md#reuse-equivalent-work The shared recorder reuses retained target identities to suppress duplicates across evidence families; mutable aggregate merges are not memoized.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The target remains subject to the recorder's eight-entry/seen-key bound; merge retains no source history beyond copied witnesses and its saturated omission count.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Combines in-memory witness collections; it parses no path.
+ */
+export function mergeGenerationProofFailures(
+  target: TtscGenerationProofFailures,
+  source: TtscGenerationProofFailures,
+): void {
+  for (const failure of source.entries) {
+    recordGenerationProofFailure(target, failure);
+  }
+  target.omitted = Math.min(
+    Number.MAX_SAFE_INTEGER,
+    target.omitted + source.omitted,
+  );
+}

package/src/core/transform/generation/onlyLearnedCompileFacts.ts

@@ -0,0 +1,42 @@
+import type { TtscGenerationProofFailures } from "./TtscGenerationProofFailures";
+
+/** Failures that say an attempt learned a fact of its compile too late to use. */
+const LEARNED_FACTS = new Set([
+  // A plugin-reported dependency path first named by this compile's envelope,
+  // which had no witness read before it (samchon/ttsc#1541).
+  "dependency-unwitnessed",
+  // The compiler's case policy, first reported by this compile's envelope,
+  // which the walk before it did not match under (samchon/ttsc#1545).
+  "case-policy-learned",
+]);
+
+/**
+ * Whether the retained, lossless failure aggregate names only facts learned
+ * after the attempt's pre-compile observation.
+ *
+ * The retry owner carries learned dependencies and compiler case policy into
+ * the next attempt, without spending its movement budget for this
+ * classification. This predicate classifies recorded failures, not independent
+ * disk stability; producers must record other failed proofs. An omitted witness
+ * could be anything, so it prevents that exemption. The retry owner separately
+ * enforces the absolute attempt cap and handles refuted adoptions.
+ *
+ * @param failures The attempt's recorded proof failures.
+ * @evidence contracts/common.md#principled-implementation A nonempty aggregate with omitted=0 and only dependency-unwitnessed or case-policy-learned qualifies for the retry owner's learned-fact exemption. This is classification of supplied witnesses, not a separate proof of project stability; omitted or other recorded failures prevent the exemption.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate centralizes which proof classes consume the retry movement budget, leaving actual attempts and the absolute cap to transformProject.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The recognized kinds express real compile facts learned after pre-witnessing, and no omitted or mixed failure is excused by a fixture-specific retry exception.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the missing-knowledge distinction, retry consequence and conservative dropped-witness rule, with params and acknowledgment separation.
+ * @evidence contracts/performance.md#efficient-algorithms Zero omissions and nonempty entries guard an every scan that stops at the first other kind. The recorder bounds normal retained count, while the supplied kind text still contributes to Set hashing/comparison. No per-call index or copied entry list is allocated.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The fixed two-kind lookup table is algorithm data, not shared completed or in-flight computation. This predicate recomputes classification of the supplied aggregate; transformProject owns retries and learned observations.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows the aggregate and reads a fixed private two-kind table. It acquires no retained per-attempt state, handle or running task and controls no aggregate lifecycle.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Classifies failure kinds by a fixed set of strings; it reads no filesystem or path.
+ */
+export function onlyLearnedCompileFacts(
+  failures: TtscGenerationProofFailures,
+): boolean {
+  return (
+    failures.omitted === 0 &&
+    failures.entries.length !== 0 &&
+    failures.entries.every((failure) => LEARNED_FACTS.has(failure.kind))
+  );
+}

package/src/core/transform/generation/projectWalkFailureFingerprint.ts

@@ -0,0 +1,82 @@
+import path from "node:path";
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+
+import type { TtscProjectWalkFailure } from "../project/TtscProjectWalkFailure";
+import { toProjectKey } from "../project/toProjectKey";
+import { hashText } from "../utils/hashText";
+import { walkSnapshotComplete } from "../validation/walkSnapshotComplete";
+
+/**
+ * Hash the walk's declared-input-relevant failure shape for terminal retry
+ * comparison. File failures outside the declared keys are ignored; directory
+ * failures and unidentifiable paths remain relevant to walk completeness.
+ * Sorted failure/unstable lists make observation order irrelevant.
+ *
+ * This records producer classifications and resolved diagnostic spellings,
+ * rather than reopening paths to obtain error messages. Identity filtering
+ * shares the caller's observation transaction and may perform its native
+ * probes. A digest difference confirms a changed failure shape, not that a new
+ * generation can succeed.
+ *
+ * @evidence contracts/common.md#principled-implementation Declared keys filter only file failures with resolvable identity; completeness, directory completeness and sorted kind/path observations preserve the failure shape under hashText's digest comparison premise.
+ * @evidence contracts/common.md#clear-and-simple-design This helper produces a compact comparison fingerprint while walkSnapshotComplete owns completeness semantics and toProjectKey owns filesystem identity mapping.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unidentifiable failed paths remain included rather than being dropped to manufacture a complete walk, and directory failures are not excused by declared-file selection.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain declared filtering, conservative identity failure, order-insensitive fingerprinting and its confirmation-only role before separated acknowledgments.
+ * @evidence contracts/portability.md#os-neutral-implementation Node resolves diagnostic native paths while toProjectKey uses the supplied filesystem identity context; no protocol slash or OS-name case assumption replaces path identity.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Copies all unstable keys and scans all failures before sorting selected
+ *   collections, preserving the borrowed snapshot's order. Set lookups retain
+ *   key-text cost; declared file failures delegate native identity resolution
+ *   and containment to the supplied transaction. Completeness may scan unstable
+ *   keys again. Selected path resolution, string comparisons, JSON encoding
+ *   and UTF-8 hashing scale with diagnostic/key text; temporary arrays and
+ *   encoded text grow with the supplied and selected populations. Sorting is
+ *   needed because failure observation order is not retry identity.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   File filtering reuses path and directory-capability observations through
+ *   the caller's identity transaction. The completed fingerprint is not cached
+ *   here; terminal validation stores the baseline and compares a new snapshot.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Temporary filtered/sorted arrays transfer only a digest string; no retained cache, handle or generation lifecycle is owned here.
+ */
+export function projectWalkFailureFingerprint(
+  snapshot: {
+    /** Whether selected directory and file observations were coherent. */
+    complete: boolean;
+
+    /** Whether relevant directory enumeration completed. */
+    directoryComplete: boolean;
+
+    /** Relative or full project identity keys with unstable observations. */
+    unstableFiles: ReadonlySet<string>;
+
+    /** Native failed-path observations and their producer classifications. */
+    walkFailures: readonly TtscProjectWalkFailure[];
+  },
+  declared: ReadonlySet<string> | undefined,
+  projectRoot: string,
+  identities: FilesystemPathIdentityContext,
+): string {
+  const relevantUnstableFiles =
+    declared === undefined
+      ? [...snapshot.unstableFiles]
+      : [...snapshot.unstableFiles].filter((key) => declared.has(key));
+  const relevantFailures = snapshot.walkFailures.filter((failure) => {
+    if (!failure.kind.startsWith("file-")) return true;
+    if (declared === undefined) return true;
+    try {
+      return declared.has(toProjectKey(projectRoot, failure.path, identities));
+    } catch {
+      return true;
+    }
+  });
+  return hashText(
+    JSON.stringify({
+      complete: walkSnapshotComplete(snapshot, declared),
+      directoryComplete: snapshot.directoryComplete,
+      failures: relevantFailures
+        .map((failure) => `${failure.kind}\0${path.resolve(failure.path)}`)
+        .sort(),
+      unstableFiles: relevantUnstableFiles.sort(),
+    }),
+  );
+}