@ttsc/unplugin 0.30.3 → 0.31.0

package/src/core/transform/validation/matchesUniversalHostInputProbes.ts

@@ -0,0 +1,73 @@
+import path from "node:path";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { resultFilesystem } from "../cache/resultFilesystem";
+import type { TtscHostInputValidation } from "./TtscHostInputValidation";
+
+/**
+ * Prove the universal inputs that were absent are still absent, through one
+ * native stat of the requested candidate. Groups retain the first missing
+ * component beneath the nearest directory; unqualified inputs retain their full
+ * exact paths.
+ *
+ * Unlike the entries half, this one rejects on an inability to prove: a
+ * permission or I/O failure certifies nothing about absence. That is the right
+ * answer for both narrow and complete proof: a recorded unavailable-content
+ * marker alone cannot distinguish absence from a newly present unreadable file.
+ * Complete validation still compares its recorded byte and membership
+ * populations after this independent native absence predicate holds.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact native ENOENT or ENOTDIR observations prove candidate absence, including native Unicode and short-name aliases. A vanished ancestor leaves descendants unreachable; replacement by a file rejects the grouped directory proof.
+ * @evidence contracts/common.md#clear-and-simple-design Missing-name validation has its own native absence boundary shared by narrow and complete proof; byte hashes and project membership remain separate predicates.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Listing inequality is not native name inequality; permission and transient failures are not fabricated absence. Only ENOENT and ENOTDIR qualify missing-path observations.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain inability-to-prove rejection, unreadable-content ambiguity and both caller routes before tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The injected native stat resolves original candidate spelling, and its platform selects the same win32 or posix joining grammar as capture's ancestor probe. Case flags and JavaScript Unicode folding do not replace native alias resolution.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The pass borrows generation-owned groups and retains only each current native probe result; no directory listing, historical state or handle is acquired.
+ * @evidence contracts/performance.md#efficient-algorithms Each group checks its directory once, then each candidate requires one native stat. Work follows candidate count and native path resolution, without enumerating unrelated directory entries; exact probes are necessary because listing names cannot establish all native aliases.
+ * @evidence contracts/performance.md#reuse-equivalent-work Capture shares nearest-ancestor selection and raw candidate groups across consumers; each current absence proof must observe native candidates again unless the owning notification validator establishes unchanged inputs.
+ */
+export function matchesUniversalHostInputProbes(
+  cached: TtscCachedProjectTransform,
+  validation: TtscHostInputValidation,
+): boolean {
+  const filesystem = resultFilesystem(cached.result);
+  const paths =
+    (filesystem.platform ?? process.platform) === "win32"
+      ? path.win32
+      : path.posix;
+  for (const input of validation.directMissing ?? []) {
+    try {
+      filesystem.stat(input);
+      return false;
+    } catch (error) {
+      if (!isMissingPathError(error)) return false;
+    }
+  }
+  for (const [directory, names] of validation.missing) {
+    try {
+      if (!filesystem.stat(directory).isDirectory()) return false;
+    } catch (error) {
+      // Only a provably absent/non-directory ancestor keeps every descendant
+      // unreachable. Permission and transient I/O failures cannot prove that
+      // a candidate is still missing, while replacing the proving directory
+      // with an exact file can itself redirect module resolution.
+      if (!isMissingPathError(error)) return false;
+      continue;
+    }
+    for (const name of names) {
+      try {
+        filesystem.stat(paths.join(directory, name));
+        return false;
+      } catch (error) {
+        if (!isMissingPathError(error)) return false;
+      }
+    }
+  }
+  return true;
+}
+
+/** True only for errors that prove a path cannot currently be traversed. */
+function isMissingPathError(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}

package/src/core/transform/validation/matchesUniversalHostInputTrees.ts

@@ -0,0 +1,76 @@
+import {
+  PluginBuildEnvironmentReadings,
+  processPluginBuildEnvironment,
+} from "ttsc/plugin-source";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { resultFilesystem } from "../cache/resultFilesystem";
+import { pluginSourceHolds } from "../inputs/pluginSourceHolds";
+import { usesPreparedPluginBuildEnvironments } from "../inputs/preparePluginBuildEnvironments";
+import type { TtscHostInputValidation } from "./TtscHostInputValidation";
+import { trackerProvesInputUnchanged } from "./trackerProvesInputUnchanged";
+
+/**
+ * Whether every plugin source directory of a generation still holds the state
+ * its binary was built from, its files and the environment a build there runs
+ * in (samchon/ttsc#1487, samchon/ttsc#1493).
+ *
+ * A directory whose tracker heard nothing below it has unchanged files, and is
+ * skipped while the environment it was last proven under is still this
+ * process's prepared reading (`PluginBuildEnvironmentReadings.cached`), which
+ * holds only while the Go tool, its environment file, and the C toolchain it
+ * names hold: the tracker watches the sources, not the toolchain outside them
+ * (samchon/ttsc#1516). Any other is proven by ttsc's rule
+ * (`pluginSourceHolds`), since no one path's metadata stands for the files
+ * below it. The proof lists the directory as the plugin build lists it, which a
+ * delivery pays only after an event below the directory, a changed environment,
+ * or where no tracker watches it or its watch cannot vouch for it, and reads
+ * the files' bytes again when population, metadata or fresh clock qualification
+ * does not permit digest reuse (`pluginSourceFilesDigest`). A missing or stale
+ * prepared environment reading returns false here. The async delivery owner
+ * prepares that authority before this synchronous proof; that prepared route
+ * never starts a cold Go or SDK probe on the host thread. Standalone
+ * synchronous results retain their original native observation and mismatch
+ * refresh; the async preparation owner marks its result identity.
+ *
+ * @param cached The generation being validated.
+ * @param validation Its universal-input manifest.
+ * @evidence contracts/common.md#principled-implementation Source state is qualified together with the Go build environment; tracker silence proves source files only, so changed environment requires the owning plugin-source proof.
+ * @evidence contracts/common.md#clear-and-simple-design One validator delegates binary-state semantics to ttsc and records the environment each successful tree proof saw.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A quiet source watcher cannot certify an external toolchain, and unreadable sources cannot become empty successful state.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish source notification, environment authority and metadata-qualified digest reuse before param tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Supported plugin-source APIs and capability-qualified native trackers own source/toolchain observation without OS-wide watcher assumptions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One environment witness per current manifest tree is replaced in place; no delivery history is retained.
+ * @evidence contracts/performance.md#efficient-algorithms Each tree first pays the shared environment reader's variable-key construction and native dependency qualification. Qualified silent sources avoid enumeration; other trees enumerate and sort the selected file population, inspect metadata and hash source bytes whenever population, metadata or clock evidence cannot qualify reuse. The synchronous owner can also refresh native environment authority after a mismatch.
+ * @evidence contracts/performance.md#reuse-equivalent-work Generation environment witnesses and the owning digest cache share prior proof only while source and toolchain identities remain valid.
+ */
+export function matchesUniversalHostInputTrees(
+  cached: TtscCachedProjectTransform,
+  validation: TtscHostInputValidation,
+): boolean {
+  for (const [directory, digest] of validation.trees) {
+    // Read before any proof, so the environment recorded below is one the
+    // proof saw or older, never a newer one it did not prove.
+    const prepared = usesPreparedPluginBuildEnvironments(cached.result);
+    const environment = prepared
+      ? PluginBuildEnvironmentReadings.cached(directory)
+      : processPluginBuildEnvironment(directory);
+    if (environment === undefined) return false;
+    if (
+      trackerProvesInputUnchanged(cached.hostInputMutationTracker, directory) &&
+      validation.treeEnvironments?.get(directory) === environment
+    )
+      continue;
+    if (
+      !pluginSourceHolds(
+        directory,
+        digest,
+        resultFilesystem(cached.result),
+        prepared ? { environment } : undefined,
+      )
+    )
+      return false;
+    (validation.treeEnvironments ??= new Map()).set(directory, environment);
+  }
+  return true;
+}

package/src/core/transform/validation/matchesUniversalHostInputs.ts

@@ -0,0 +1,53 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscHostInputValidation } from "./TtscHostInputValidation";
+import { matchesUniversalHostInputEntries } from "./matchesUniversalHostInputEntries";
+import { matchesUniversalHostInputProbes } from "./matchesUniversalHostInputProbes";
+import { matchesUniversalHostInputTrees } from "./matchesUniversalHostInputTrees";
+import { nativeInputPredicatesHold } from "./nativeInputPredicatesHold";
+import { trackerProvesInputUnchanged } from "./trackerProvesInputUnchanged";
+
+/**
+ * Validate universal descriptor/config inputs. Versioned native config
+ * predicates are replayed before notification shortcuts; other proven inputs
+ * retain reuse. Existing paths use the generation's native metadata manifest;
+ * missing probes are grouped by the nearest existing directory and checked
+ * through native candidate stats so alternate spellings cannot hide an existing
+ * input.
+ *
+ * While the tracker proves every input the manifest covers unchanged, source
+ * content is not read; plugin build environments still require their own
+ * identity check. Otherwise each input is proven on its own: an entry or a
+ * plugin source its tracker proves is skipped, and the rest are read. One input
+ * a watch cannot prove, a plugin source outside the project on macOS, whose
+ * stream no probe proves delivered (samchon/ttsc#1453), used to send every
+ * universal input back to the disk on every delivery.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact healthy notifications qualify covered source spellings, while tree environment checks remain mandatory because external build authority is independent of native source events.
+ * @evidence contracts/common.md#clear-and-simple-design One coordinator combines existing-entry, missing-name and tree authority without duplicating their native observations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Source watcher silence cannot replace toolchain/environment identity; failed or unproved scopes fall back to their owning validators.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs separate source-content reuse, mandatory environment checks and per-input fallback rather than claiming notifications eliminate every observation.
+ * @evidence contracts/portability.md#os-neutral-implementation Filesystem-aware validators use actual tracker delivery capability and exact lexical coverage rather than platform-wide assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The coordinator borrows generation manifests and trackers without retaining a result or acquiring a handle.
+ * @evidence contracts/performance.md#efficient-algorithms Every admission first replays all generation-owned typed config predicates; this mandatory cost includes native queries, file bytes or directory membership independently of watcher/epoch qualification.  The coverage scan stops at the first unproved input. Each coverage query checks overlapping unproven scopes and sampled events with native path comparisons; fallback adds unresolved bytes, native candidate probes and plugin tree enumeration. Mandatory environment qualification pays its owning dependency and environment-key costs on either route.
+ * @evidence contracts/performance.md#reuse-equivalent-work Typed config predicate replay is not cached by this coordinator and remains mandatory even when the following existing shortcut shares other proof.  Shared manifests and qualified silent sources avoid repeated content reads only while the owning tree validator also proves unchanged build environment.
+ */
+export function matchesUniversalHostInputs(
+  cached: TtscCachedProjectTransform,
+  validation: TtscHostInputValidation,
+): boolean {
+  if (!nativeInputPredicatesHold(cached)) return false;
+  let notificationsProveAll = true;
+  for (const input of validation.covered) {
+    if (!trackerProvesInputUnchanged(cached.hostInputMutationTracker, input)) {
+      notificationsProveAll = false;
+      break;
+    }
+  }
+  if (notificationsProveAll)
+    return matchesUniversalHostInputTrees(cached, validation);
+  return (
+    matchesUniversalHostInputEntries(cached, validation) &&
+    matchesUniversalHostInputProbes(cached, validation) &&
+    matchesUniversalHostInputTrees(cached, validation)
+  );
+}

package/src/core/transform/validation/nativeInputPredicatesHold.ts

@@ -0,0 +1,48 @@
+import path from "node:path";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { resultFilesystem } from "../cache/resultFilesystem";
+import { envelopeDerivation } from "../envelope/envelopeDerivation";
+import { nativeInputPredicateMatches } from "../inputs/nativeInputPredicateMatches";
+
+/**
+ * Validate every generation-owned native config predicate before cache reuse.
+ * This check also applies when notification/epoch shortcuts admit other inputs.
+ * A generation with no native predicates requires no native replay context;
+ * existing non-native proof owners still perform their own validation.
+ *
+ * @evidence contracts/common.md#principled-implementation Every recorded native predicate must match through the generation's original filesystem view. An empty native predicate population contributes no native constraint, without admitting other proof domains or converting an exception into reuse.
+ * @evidence contracts/common.md#clear-and-simple-design One gate is shared by source, complete-snapshot and universal-input admission; the typed replay owns encodings and native errors.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Metadata and notification shortcuts cannot omit typed config predicates or repair an unstable producer witness.
+ * @evidence contracts/common.md#meaningful-documentation The comment identifies generation ownership and the admission shortcuts that must retain this gate.
+ * @evidence contracts/portability.md#os-neutral-implementation Relative names are resolved against the recorded project with the filesystem view's path dialect; native identity and encoding belong to the replay operation.
+ * @evidence contracts/performance.md#efficient-algorithms The initial observation scan detects whether native replay is required without resolving a root or performing filesystem queries. Nonempty populations add a second linear traversal plus native replay and path-byte costs, stopping at the first refusal; empty and legacy-only populations require no replay context.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This admission gate stores no separate cache and checks the recorded generation supplied by its caller.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Per-call enumeration owns no handle or watcher; the cached envelope owns retained predicates.
+ */
+export function nativeInputPredicatesHold(
+  cached: TtscCachedProjectTransform,
+): boolean {
+  if (cached.result.type === "exception") return false;
+  const observations = cached.result.graph?.inputObservations ?? {};
+  if (
+    !Object.values(observations).some(
+      (observation) => (observation.nativePredicates?.length ?? 0) !== 0,
+    )
+  )
+    return true;
+  const filesystem = resultFilesystem(cached.result);
+  const identities = envelopeDerivation(cached).identityContext;
+  for (const [name, observation] of Object.entries(observations)) {
+    if ((observation.nativePredicates?.length ?? 0) === 0) continue;
+    const file = (
+      (filesystem.platform ?? process.platform) === "win32"
+        ? path.win32
+        : path.posix
+    ).resolve(cached.projectRoot, name);
+    for (const predicate of observation.nativePredicates ?? [])
+      if (!nativeInputPredicateMatches(file, predicate, filesystem, identities))
+        return false;
+  }
+  return true;
+}

package/src/core/transform/validation/notificationsProveProgramUnchanged.ts

@@ -0,0 +1,92 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { resultFilesystem } from "../cache/resultFilesystem";
+import { TRANSFORM_CLOCK_REFERENCE_DIRECTORIES } from "../clock/TRANSFORM_CLOCK_REFERENCE_DIRECTORIES";
+import { refreshFilesystemClockReference } from "../clock/refreshFilesystemClockReference";
+import { isProjectWalkPath } from "../project/isProjectWalkPath";
+import { notificationsProveMembership } from "../tracker/notificationsProveMembership";
+import { matchesUniversalHostInputs } from "./matchesUniversalHostInputs";
+
+/**
+ * Whether the generation's live notifications prove its program could not have
+ * changed since capture (samchon/ttsc#1398).
+ *
+ * A module outside the program stays outside it until the program changes: a
+ * config admits it, or an input starts importing it. Either one is an event the
+ * generation's watchers report, a membership change, a content change of a
+ * program input, or a changed universal input. While none has been reported and
+ * every watcher can vouch for content, the out-of-program answer holds, and the
+ * delivery skips the project walk it used to pay every time.
+ *
+ * @evidence contracts/common.md#principled-implementation Proven membership and healthy complete content notifications exclude program-input changes; universal validation separately qualifies configuration and plugin-source authority.
+ * @evidence contracts/common.md#clear-and-simple-design One admission predicate composes membership, relevant tracker changes and universal proof for out-of-program deliveries.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed or omitted notification streams cannot prove unchanged state; unrelated project events are excluded only by compiler membership policy.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain out-of-program stability and relevant change categories before tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Actual watcher content authority, compiler membership policy and same-device clock references qualify native observations without OS-name-derived case rules.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Trackers and clock references belong to the generation owner; this predicate retains no history or resource.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Scans the three trackers' recorded changes until a relevant event. Each
+ *   project event pays lexical policy checks and native lstat along its path;
+ *   costs follow event count, path components and policy matching. Admission
+ *   then refreshes the native clock probe and validates universal coverage,
+ *   unresolved content/candidates and plugin environment/tree authority. A
+ *   quiet stream does not make that delegated work constant or eliminate it.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Qualified current notification and universal authority permit sibling
+ *   out-of-program deliveries to reuse the generation without another project
+ *   walk. The predicate is recomputed against live flags and recorded events;
+ *   it caches no boolean permission across a tracker or universal change.
+ */
+export function notificationsProveProgramUnchanged(
+  /**
+   * Generation supplying live tracker state, compiler policy and universal
+   * proof.
+   */
+  cached: TtscCachedProjectTransform,
+): boolean {
+  if (!notificationsProveMembership(cached)) return false;
+  for (const tracker of [
+    cached.projectMutationTracker,
+    cached.hostInputMutationTracker,
+    cached.candidateMutationTracker,
+  ]) {
+    if (tracker === undefined) continue;
+    if (
+      tracker.contentAuthoritative !== true ||
+      tracker.membershipChanged ||
+      tracker.changesOmitted
+    ) {
+      return false;
+    }
+    for (const changed of tracker.changes) {
+      // The project observer also hears paths the walk never enters, such as
+      // a package directory named like a source; only what the walk covers
+      // can be a program input. Every other tracker's paths are inputs.
+      if (
+        tracker !== cached.projectMutationTracker ||
+        isProjectWalkPath(
+          cached.projectRoot,
+          changed,
+          undefined,
+          resultFilesystem(cached.result),
+          cached.membershipPolicy,
+        )
+      ) {
+        return false;
+      }
+    }
+  }
+  if (
+    cached.projectMutationTracker === undefined ||
+    cached.hostInputValidation === undefined
+  ) {
+    return false;
+  }
+  // The universal inputs no tracker vouches for are proven by metadata, which
+  // stands for content only against a reference minted since any rollback, as
+  // every other delivery proof mints before it reads.
+  refreshFilesystemClockReference(
+    TRANSFORM_CLOCK_REFERENCE_DIRECTORIES.get(cached),
+    resultFilesystem(cached.result),
+  );
+  return matchesUniversalHostInputs(cached, cached.hostInputValidation);
+}

package/src/core/transform/validation/notifiesAbsence.ts

@@ -0,0 +1,44 @@
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { trackerProvesInputUnchanged } from "./trackerProvesInputUnchanged";
+
+/**
+ * Report whether the generation's live candidate watcher still proves this
+ * exact spelling unchanged. Candidates include recorded fileExists:false
+ * predicates, which can describe directories as well as absent paths; the
+ * caller selects the recorded predicate or missing scalar it wants to reuse.
+ *
+ * Losing the watcher is not evidence of anything, so a failed tracker sends the
+ * input back to being probed by hand, exactly as a failed tracker already sends
+ * the whole generation back to complete-snapshot validation.
+ *
+ * @evidence contracts/common.md#principled-implementation The candidate tracker's exact coverage and healthy authoritative notification predicate qualify absence reuse.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter selects the absence tracker without duplicating watcher-health policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing or failed candidate observer cannot prove continued absence.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain exact spelling and why proof loss returns to direct probing.
+ * @evidence contracts/portability.md#os-neutral-implementation Authority comes from observed native delivery capability and the tracker's component-aware overlap semantics.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Candidate tracker selection is fixed work, but the proof checks exact
+ *   native coverage and scans unproven scopes/events until an overlap. Costs
+ *   follow their populations and delegated native identity/path comparisons;
+ *   it does not read candidate bytes or enumerate a project here.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Qualified current candidate notifications permit the caller's recorded
+ *   unavailable-file state to be reused without a direct probe. Missing
+ *   coverage, uncertainty or an
+ *   overlapping event withdraws that permission; the verdict is not cached
+ *   across tracker changes merely because the supplied path is unchanged.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Borrows the generation's candidate tracker and its identity/proof storage;
+ *   those owners control retained maps and handles, without new state here.
+ */
+export function notifiesAbsence(
+  /** Generation owning the separately scoped candidate observer. */
+  cached: TtscCachedProjectTransform,
+  /**
+   * Exact native candidate spelling; physical aliases alone do not grant
+   * coverage.
+   */
+  input: string,
+): boolean {
+  return trackerProvesInputUnchanged(cached.candidateMutationTracker, input);
+}

package/src/core/transform/validation/restrictNotificationCoverageToProvenInputs.ts

@@ -0,0 +1,65 @@
+import path from "node:path";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { derivationIdentity } from "../envelope/derivationIdentity";
+import { envelopeDerivation } from "../envelope/envelopeDerivation";
+import type { TtscProjectMutationTracker } from "../tracker/TtscProjectMutationTracker";
+import { MISSING_INPUT_STATE } from "./MISSING_INPUT_STATE";
+import type { TtscHostInputValidation } from "./TtscHostInputValidation";
+
+/**
+ * Remove missing or unreadable input claims from mutable tracker coverage. This
+ * is a postcapture filter, not independent admission of every remaining
+ * spelling; generation stability and tracker health must also hold.
+ *
+ * The observers must open before the post-compile snapshots so they can witness
+ * an A-B-A race. Their exact coverage can only be narrowed after those reads.
+ * Unreadable nondirectory and absent inputs can record the same `missing`
+ * state; neither may inherit a content shortcut because its metadata can stay
+ * fixed while bytes become readable. Missing resolver candidates inside the
+ * project retain their separate component-aware candidate tracker, while every
+ * other such input continues through the recorded predicate or directory-list
+ * proof.
+ *
+ * A plugin source directory has no entry, and is kept all the same: capture
+ * records it among the manifest's trees only once its state was proven
+ * (`pluginSourceHolds`, samchon/ttsc#1487), and the tracker watches it as a
+ * whole subtree. Qualified silence can serve its source files, but the build
+ * environment still needs separate proof. Dropping it left every delivery
+ * unable to take the manifest's notification shortcut, re-reading every
+ * universal input and proving every plugin source's state again.
+ *
+ * @evidence contracts/common.md#principled-implementation This filter removes explicit missing/unreadable host or external states, while admitted trees and kind/content-qualified entries keep their separate authority. Missing host validation alone does not clear the set or prove other spellings; full admission remains with capture and validators.
+ * @evidence contracts/common.md#clear-and-simple-design One postcapture operation reconciles watcher coverage with the admitted manifest rather than duplicating snapshot rules during observer acquisition.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Opening a watch cannot certify bytes capture could not read or invent content authority from metadata.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain observer timing, unreadable states and the legitimate source-tree distinction.
+ * @evidence contracts/portability.md#os-neutral-implementation Lexical coverage and physical derivation identity remain separate so aliases and actual case policy cannot be conflated.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The existing coverage Set shrinks, without retaining old certification or acquiring watches; this does not itself release tracker registrations, generation identity memos or native resources owned elsewhere.
+ * @evidence contracts/performance.md#efficient-algorithms N covered spellings are copied before filtering, with O(N) temporary references plus path text and map/set lookup work. First derivation identities can perform native realpath/ancestor/case queries; generation memos share those observations. No content bytes or source tree are read here.
+ * @evidence contracts/performance.md#reuse-equivalent-work Only capture-proven coverage remains eligible for shared notification validation; other spellings retain direct proof.
+ */
+export function restrictNotificationCoverageToProvenInputs(
+  tracker: TtscProjectMutationTracker | undefined,
+  cached: TtscCachedProjectTransform,
+  hostValidation: TtscHostInputValidation | undefined,
+): void {
+  if (!(tracker?.covered instanceof Set)) return;
+  const covered = tracker.covered as Set<string>;
+  const state = envelopeDerivation(cached);
+  for (const input of [...covered]) {
+    const absolute = path.resolve(input);
+    if (hostValidation?.trees.has(absolute) === true) continue;
+    const hostEntry = hostValidation?.entries.get(absolute);
+    if (
+      (hostValidation?.covered.has(absolute) === true &&
+        (hostEntry === undefined ||
+          (hostEntry.readable === false && hostEntry.strict !== true))) ||
+      cached.externalInputHashes?.[derivationIdentity(state, absolute)] ===
+        MISSING_INPUT_STATE ||
+      cached.externalInputObservations?.[absolute]?.readFile?.ok === false ||
+      cached.externalInputObservations?.[absolute]?.fileExists === false
+    ) {
+      covered.delete(input);
+    }
+  }
+}

package/src/core/transform/validation/sameHashes.ts

@@ -0,0 +1,42 @@
+/**
+ * Compare two project-walk snapshots.
+ *
+ * `keys` narrows the comparison to the generation's declared inputs. The walk
+ * hashes admitted regular files under the project root, but only a file the
+ * compile actually consumed can change an output, and a project root is a
+ * working directory: a framework's generated types, a log, a coverage report,
+ * or a test artifact appears and changes there while a compile runs. Comparing
+ * those would declare the generation incoherent and cost a whole-project
+ * recompile for every remaining module (samchon/ttsc#1246). Files entering or
+ * leaving the project remain covered by the directory-membership snapshot,
+ * which is the one thing a content comparison cannot see. An envelope that
+ * declares no input set (a graph-free legacy host) passes `undefined` and keeps
+ * the whole-walk comparison.
+ *
+ * @evidence contracts/common.md#principled-implementation Declared keys select relevant recorded content; legacy absence of that population requires exact key count and value equality for the full snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design One comparison exposes narrowed and legacy-wide semantics without owning project enumeration or membership discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Irrelevant build artifacts cannot taint a declared generation, and narrowing never substitutes for the separate membership proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain declared-input scope, unrelated artifacts and the separate membership obligation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares recorded and current hash maps by key; it reads no filesystem and parses no path.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Key arrays are local to the comparison and no retained cache or native resource is acquired.
+ * @evidence contracts/performance.md#efficient-algorithms Declared comparison scans only its key set with early mismatch return; legacy comparison materializes both key arrays before checking left values. Property lookup and hash/signature equality include key and value text costs, while temporary key arrays grow with the full compared records. No file read or membership enumeration is repeated here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The generation validator decides whether this snapshot comparison may be shared; this helper computes one requested equality verdict.
+ */
+export function sameHashes(
+  left: Record<string, string>,
+  right: Record<string, string>,
+  keys?: ReadonlySet<string>,
+): boolean {
+  if (keys !== undefined) {
+    for (const key of keys) {
+      if (left[key] !== right[key]) return false;
+    }
+    return true;
+  }
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) {
+    return false;
+  }
+  return leftKeys.every((key) => right[key] === left[key]);
+}

package/src/core/transform/validation/sameProjectDirectories.ts

@@ -0,0 +1,47 @@
+import type { TtscProjectDirectorySnapshot } from "../project/TtscProjectDirectorySnapshot";
+
+/**
+ * Compare directory signatures relevant to either generation snapshot.
+ *
+ * Directories irrelevant on both sides cannot change program membership.
+ * Gaining or losing relevance remains visible from the side where it matters.
+ *
+ * @evidence contracts/common.md#principled-implementation The union of relevant directory paths compares membership signatures on both sides, preserving entry and exit from the program's relevant population.
+ * @evidence contracts/common.md#clear-and-simple-design One equality helper compares already deterministic snapshots without rediscovering compiler membership policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Relevance is supplied by the actual walk policy; unrelated output churn is not used to invalidate a generation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains both-sided relevance and why ignored-on-both directories cannot affect this proof.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares directory signatures by recorded path string; the strings were produced by the same walk, and no filesystem is read.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Temporary maps and path sets are local and no history or native handle is retained.
+ * @evidence contracts/performance.md#efficient-algorithms Both complete directory populations are scanned to select relevant entries. Two relevant maps and a union set give expected-constant entry lookup per relevant path; key hashing and signature equality retain their text costs. Temporary filtered arrays, map-entry pairs and union key collections grow with the selected relevant directories rather than retaining historical snapshots.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Snapshot admission owns sharing of the resulting proof; this helper computes one value comparison.
+ */
+export function sameProjectDirectories(
+  left: readonly TtscProjectDirectorySnapshot[],
+  right: readonly TtscProjectDirectorySnapshot[],
+): boolean {
+  // Compare only the directories that can hold program inputs, on either side.
+  // A directory irrelevant on both is not part of the program's membership at
+  // all, so its appearance, disappearance or churn says nothing: that is a
+  // bundler's output tree. One that gained or lost relevance is present in the
+  // comparison from the side where it counts, and so is caught.
+  const select = (
+    snapshots: readonly TtscProjectDirectorySnapshot[],
+  ): Map<string, TtscProjectDirectorySnapshot> =>
+    new Map(
+      snapshots
+        .filter((directory) => directory.relevant)
+        .map((directory) => [directory.path, directory]),
+    );
+  const leftRelevant = select(left);
+  const rightRelevant = select(right);
+  const paths = new Set([...leftRelevant.keys(), ...rightRelevant.keys()]);
+  for (const location of paths) {
+    if (
+      leftRelevant.get(location)?.signature !==
+      rightRelevant.get(location)?.signature
+    ) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/core/transform/validation/trackerProvesInputUnchanged.ts

@@ -0,0 +1,56 @@
+import path from "node:path";
+
+import { pathIsWithin } from "../filesystem/pathIsWithin";
+import type { TtscProjectMutationTracker } from "../tracker/TtscProjectMutationTracker";
+
+/**
+ * Whether a healthy notification scope proves one exact input unchanged: the
+ * tracker is live, its silence is proven, the input is one it watches by name,
+ * the watch below which the input lives was proven to deliver, and no event
+ * touched the input.
+ *
+ * @evidence contracts/common.md#principled-implementation Verified healthy content authority, exact covered spelling and no overlapping unproven scope or event establish this input's notification witness.
+ * @evidence contracts/common.md#clear-and-simple-design One shared predicate supplies universal and derived-input validators with the same notification authority rule.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Quiet but failed, incomplete or undeliverable scopes are rejected rather than promoted to proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose enumerates health, coverage and overlap premises rather than treating silence as universal authority.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lexical resolution and supplied overlap semantics qualify paths; fallback containment is component-aware rather than substring matching.
+ * @evidence contracts/performance.md#efficient-algorithms Health and exact covered-key checks precede sequential scans of unproven scopes and sampled changes, stopping at the first overlap. Cost follows those populations and each native identity or lexical path comparison; no project enumeration or source byte read occurs here.
+ * @evidence contracts/performance.md#reuse-equivalent-work This predicate qualifies reuse of a generation's recorded content from its current tracker witness. Exact coverage, verified delivery, complete healthy content authority and absence of overlapping uncertainty or events are all required; the boolean itself is recomputed rather than cached across tracker changes.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function trackerProvesInputUnchanged(
+  tracker: TtscProjectMutationTracker | undefined,
+  input: string,
+): boolean {
+  if (
+    tracker === undefined ||
+    tracker.failed ||
+    tracker.unverified === true ||
+    tracker.changesOmitted
+  ) {
+    return false;
+  }
+  if (tracker.contentAuthoritative !== true) return false;
+  const absolute = path.resolve(input);
+  if (tracker.covered?.has(absolute) !== true) return false;
+  // The watch below which the input lives could not prove it delivered, so
+  // its silence says nothing about this input (samchon/ttsc#1453).
+  for (const directory of tracker.unproven ?? []) {
+    if (
+      tracker.overlaps?.(absolute, directory) ??
+      (pathIsWithin(absolute, directory) || pathIsWithin(directory, absolute))
+    ) {
+      return false;
+    }
+  }
+  for (const changed of tracker.changes) {
+    if (
+      tracker.overlaps?.(absolute, changed) ??
+      (pathIsWithin(absolute, changed) || pathIsWithin(changed, absolute))
+    ) {
+      return false;
+    }
+  }
+  return true;
+}