@ttsc/unplugin 0.30.4 → 0.31.0

package/src/core/transform/watch/TtscWatchInputState.ts

@@ -0,0 +1,86 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy";
+
+/**
+ * Exact generation state behind one derived watch input.
+ *
+ * @evidence contracts/common.md#principled-implementation The codec discriminant binds each observation to its own comparison payload; membership remains a project walk and cannot be substituted for one file's hash.
+ * @evidence contracts/common.md#clear-and-simple-design The discriminated union associates each codec with its required payload; it does not validate producer observations or prohibit additional structural fields.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Contract-defined codec values select real observation semantics; no fixture or host-specific expected digest is encoded.
+ * @evidence contracts/common.md#meaningful-documentation Spaced native member comments explain hash provenance, physical targets, plugin environment and membership policy; separated tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native targets and predicate observations are explicit payloads; plugin-tree state includes the build environment rather than assuming an OS name establishes equivalence.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchInputState only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchInputState only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchInputState only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export type TtscWatchInputState =
+  | {
+      /** A project-walk or dependency-only input read as ordinary host bytes. */
+      codec: "host";
+
+      /** Raw host-byte hash, or the shared missing/directory state marker. */
+      hash: string;
+    }
+  | {
+      /** A realized compiler-graph input, including its physical target. */
+      codec: "graph";
+
+      /** Compiler-normalized hash, directory-kind sentinel or missing marker. */
+      hash: string;
+
+      /** Observed physical target, or null when realpath could not be read. */
+      realpath: string | null;
+    }
+  | {
+      /** The exact compiler predicates observed for a resolver input. */
+      codec: "predicates";
+
+      /** The recorded predicates; omitted facts make no claim. */
+      observation: ITtscCompilerTransformation.IInputObservation;
+    }
+  | {
+      /**
+       * A Go source directory a plugin binary of the generation was built from
+       * (samchon/ttsc#1487). The input's path is the directory, observed as a
+       * whole subtree, and its state is the one the build keyed the binary on,
+       * the sources with the environment a build there is keyed on
+       * (`pluginSourceState` from `ttsc/plugin-source`, samchon/ttsc#1493),
+       * which only ttsc's rule proves (`pluginSourceStateHolds`): no one path's
+       * metadata stands for the files below it.
+       */
+      codec: "tree";
+
+      /** Shared plugin-source and build-environment state digest. */
+      digest: string;
+    }
+  | {
+      /**
+       * The project's root-file membership, which the adapter's project walk
+       * decides rather than the compiler (samchon/ttsc#1419). The input's path
+       * is the project root.
+       */
+      codec: "membership";
+
+      /**
+       * `projectMembershipDigest` of the walk: the policy and each directory
+       * whose subtree contains an admitted file, with its membership
+       * signature.
+       */
+      digest: string;
+
+      /**
+       * Every directory the walk enters, including those that hold no program
+       * input yet, since a file created in one is a new root file.
+       */
+      directories: readonly string[];
+
+      /** The rule the walk applied, which a re-walk must apply too. */
+      policy: ITtscProjectMembershipPolicy;
+    };

package/src/core/transform/watch/TtscWatchSelection.ts

@@ -0,0 +1,38 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * What a delivery's watch notifications need from the project selection that
+ * routed its file: reported config reads and failed discovery candidates,
+ * handed to the host beside every notification's own inputs
+ * (`selectionInputs`), the filesystem their evidence is read through, and the
+ * selected tsconfig, which spells the project for a notification that has no
+ * generation to spell it.
+ *
+ * @evidence contracts/common.md#principled-implementation The consulted configs preserve routing dependencies independently of the selected project, and the filesystem records which native view supplies their facts.
+ * @evidence contracts/common.md#clear-and-simple-design A readonly delivery context groups routing inputs and their observation capability without copying project-generation state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The full consulted sequence is represented instead of assuming the selected tsconfig alone explains project routing.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains each field's notification role; spaced member comments and separated tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The supplied filesystem owns native observation and the selected config retains adapter spelling, avoiding an implicit global filesystem or case-policy premise.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchSelection only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchSelection only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchSelection only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export interface TtscWatchSelection {
+  /**
+   * Ordered reported routing spellings, including failed discovery predicates;
+   * a listed candidate need not have had readable config contents.
+   */
+  readonly consulted: readonly string[];
+
+  /** The filesystem the delivery reads through. */
+  readonly filesystem: TtscTransformFilesystemOperations;
+
+  /** The selected project's tsconfig, as the adapter names it. */
+  readonly tsconfig: string;
+}

package/src/core/transform/watch/captureWatchInputBaseline.ts

@@ -0,0 +1,39 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import type { TtscWatchInputBaseline } from "./TtscWatchInputBaseline";
+import { captureWatchInputBaselines } from "./captureWatchInputBaselines";
+
+/**
+ * Capture a main-process baseline comparable with generation-owned evidence.
+ * Two equal broad observations are required; an observed mismatch or exception
+ * declines the capture. Equality does not establish an atomic snapshot or rule
+ * out a transient change between reads.
+ *
+ * @param options.tree Whether the path was recorded as a plugin source
+ *   directory, whose state the baseline then carries (samchon/ttsc#1487).
+ * @param options.accessibleEntries Whether compiler listing names are needed by
+ *   a recorded predicate. Unrequested listings are not enumerated.
+ * @param options.nativePredicates Native version-one codec kinds requested by
+ *   recorded inputs. Raw native listings are independent of compiler listings.
+ * @evidence contracts/common.md#principled-implementation Two independently captured codec facts must agree before a baseline is returned; equality detects observed changes but cannot establish absence of intervening unobserved changes.
+ * @evidence contracts/common.md#clear-and-simple-design The singleton delegates to the batch owner, which assembles codec facts and owns independent observations and failure handling.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unavailable reads retain their explicit codec markers and predicates; a mismatch or escaping exception declines capture without supplying expected state or retrying until a desired answer appears.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain capture rejection, equality limitations and optional subtree cost, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Stat, hash and identity use supplied native operations. Plugin-tree capture uses the shared native build-state owner, so an injected view must describe that same source tree.
+ * @evidence contracts/performance.md#efficient-algorithms Two fixed broad captures each read B bytes once for both codecs; native identity and metadata retain their path-resolution costs. Optional plugin-tree observation scans its selected population and bytes, and listings sort E UTF-8 names with encoding and prefix-comparison costs. Unrequested trees and listings are not scanned, and fresh identity contexts avoid reusing the first capture's metadata.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Independent current observations are the purpose of capture; the caller owns subsequent baseline reuse and its validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Hash buffers and identity contexts are call-local; this capture retains no cache, native handle or task.
+ */
+export function captureWatchInputBaseline(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+  options: {
+    tree?: boolean;
+    accessibleEntries?: boolean;
+    nativePredicates?: readonly (keyof NonNullable<
+      TtscWatchInputBaseline["nativePredicates"]
+    >)[];
+  } = {},
+): TtscWatchInputBaseline | undefined {
+  return captureWatchInputBaselines([file], filesystem, options).get(file);
+}

package/src/core/transform/watch/captureWatchInputBaselines.ts

@@ -0,0 +1,146 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { createHostPathIdentityContext } from "../filesystem/createHostPathIdentityContext";
+import { pathIdentityKey } from "../filesystem/pathIdentityKey";
+import { compilerAccessibleEntries } from "../inputs/compilerAccessibleEntries";
+import { compilerInputRealpathObservation } from "../inputs/compilerInputRealpathObservation";
+import { compilerInputTextHash } from "../inputs/compilerInputTextHash";
+import { compilerStatKind } from "../inputs/compilerStatKind";
+import { nativeInputPredicateState } from "../inputs/nativeInputPredicateState";
+import { pluginSourceState } from "../inputs/pluginSourceState";
+import { hashText } from "../utils/hashText";
+import { stableStringify } from "../utils/stableStringify";
+import { MISSING_INPUT_STATE } from "../validation/MISSING_INPUT_STATE";
+import type { TtscWatchInputBaseline } from "./TtscWatchInputBaseline";
+
+/**
+ * Capture a batch through two independently fresh native observation phases. A
+ * phase shares path/case observations only within this synchronous batch; the
+ * second phase has a new identity context and rereads every input. Nothing
+ * survives this call. Changed captures or escaping exceptions decline that
+ * input alone. Matching endpoints still cannot certify an atomic snapshot or
+ * exclude ABA.
+ *
+ * One current byte read supplies raw-host and compiler-text hashes in each
+ * phase. Failed reads retain native kind fallbacks; optional tree and listing
+ * observations keep their original owners and are captured in both phases.
+ * Requested native codecs share that phase's raw byte read and separately
+ * observe their own entry/listing/physical-target facts. Unsupported or failed
+ * native observations decline that path; equality still cannot exclude ABA.
+ *
+ * @evidence contracts/common.md#principled-implementation Each returned input has equal before/after facts from independent identity contexts and actual reads. Sharing directory resolution within a phase never supplies the second phase or a later batch; failed captures remain undefined independently of siblings.
+ * @evidence contracts/common.md#clear-and-simple-design Two phase maps surround one per-path fact collector, sharing the existing decoder, native predicates and optional tree/listing owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No lifetime or historical identity memo enters this API. Both phases run for every selected spelling and compare complete facts, including identity and realpath; equality does not invent atomicity or exclude unobserved changes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines phase ownership, shared byte provenance, rejection and the remaining temporal limitation.
+ * @evidence contracts/portability.md#os-neutral-implementation The coherent supplied filesystem provides native case, path, read, kind and listing capabilities. Each phase re-establishes aliases and case policy; no platform label supplies authority, and raw host bytes remain distinct from compiler-decoded text.
+ * @evidence contracts/performance.md#efficient-algorithms Two passes visit N unique spellings and read each path at most once per phase, sharing directory/case resolution within that phase. Native ancestor/path work, total bytes B, optional listing/tree populations and digest serialization remain costs; two maps retain O(N) baseline facts rather than historical generations.
+ * @evidence contracts/performance.md#reuse-equivalent-work Phase-local identity contexts reuse the same native namespace observation for related paths, and one actual byte observation supplies its two codecs. A new context and new reads are mandatory in the second phase and every later invocation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned baselines are caller-owned; both identity contexts and phase maps are synchronous call-local values with no timer, watcher or retained cache.
+ */
+export function captureWatchInputBaselines(
+  files: Iterable<string>,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+  options: {
+    tree?: boolean;
+    accessibleEntries?: boolean;
+    nativePredicates?: readonly (keyof NonNullable<
+      TtscWatchInputBaseline["nativePredicates"]
+    >)[];
+  } = {},
+): Map<string, TtscWatchInputBaseline | undefined> {
+  const selected = [...new Set(files)];
+  const observe = (): Map<string, TtscWatchInputBaseline | undefined> => {
+    const identities = createHostPathIdentityContext(filesystem);
+    return new Map(
+      selected.map((file) => {
+        try {
+          return [
+            file,
+            capture(file, filesystem, identities, options),
+          ] as const;
+        } catch {
+          return [file, undefined] as const;
+        }
+      }),
+    );
+  };
+  const before = observe();
+  const after = observe();
+  for (const file of selected) {
+    if (
+      before.get(file) === undefined ||
+      stableStringify(before.get(file)) !== stableStringify(after.get(file))
+    )
+      after.set(file, undefined);
+  }
+  return after;
+}
+
+/** Capture one path's codec facts from this phase's fresh namespace view. */
+function capture(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations,
+  identities: FilesystemPathIdentityContext,
+  options: {
+    tree?: boolean;
+    accessibleEntries?: boolean;
+    nativePredicates?: readonly (keyof NonNullable<
+      TtscWatchInputBaseline["nativePredicates"]
+    >)[];
+  },
+): TtscWatchInputBaseline {
+  const stat = compilerStatKind(file, filesystem);
+  let bytes: Buffer | undefined;
+  let readError: unknown;
+  try {
+    bytes = filesystem.readFile(file);
+  } catch (error) {
+    readError = error;
+    // Failed reads keep their explicit codec fallbacks.
+  }
+  const graphReadHash =
+    stat === "directory" || bytes === undefined
+      ? null
+      : compilerInputTextHash(bytes);
+  const directoryHash = hashText("ttsc:host-input:directory\0");
+  const hostHash =
+    bytes === undefined
+      ? compilerStatKind(file, filesystem) === "directory"
+        ? directoryHash
+        : MISSING_INPUT_STATE
+      : hashText(bytes);
+  const nativePredicates: NonNullable<
+    TtscWatchInputBaseline["nativePredicates"]
+  > = {};
+  for (const kind of new Set(options.nativePredicates ?? [])) {
+    const observed = nativeInputPredicateState(file, kind, filesystem, {
+      readFile() {
+        if (bytes === undefined) throw readError;
+        return bytes;
+      },
+    });
+    if (observed === undefined) {
+      throw new Error("Unable to observe a requested native input predicate.");
+    }
+    nativePredicates[kind] = observed;
+  }
+  return {
+    ...(Object.keys(nativePredicates).length === 0 ? {} : { nativePredicates }),
+    ...(options.accessibleEntries === true
+      ? { accessibleEntries: compilerAccessibleEntries(file, filesystem) }
+      : {}),
+    directoryExists: stat === "directory",
+    fileExists: stat === "file",
+    graphHash:
+      graphReadHash ??
+      (stat === "directory" ? directoryHash : MISSING_INPUT_STATE),
+    graphReadHash,
+    hostHash,
+    identity: pathIdentityKey(file, identities),
+    realpath: compilerInputRealpathObservation(file, filesystem),
+    stat,
+    ...(options.tree === true ? { tree: pluginSourceState(file) } : {}),
+  };
+}

package/src/core/transform/watch/captureWatchInputFileBaseline.ts

@@ -0,0 +1,49 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { createHostPathIdentityContext } from "../filesystem/createHostPathIdentityContext";
+import { pathIdentityKey } from "../filesystem/pathIdentityKey";
+import { stableStringify } from "../utils/stableStringify";
+import type { TtscWatchInputFileBaseline } from "./TtscWatchInputFileBaseline";
+
+/**
+ * Capture two equal file-predicate observations for implicit project discovery.
+ * A failed stat records a negative file predicate. A mismatch or escaping
+ * identity observation failure declines capture; equal samples do not establish
+ * an atomic filesystem snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation Fresh identity and regular-file predicates are captured twice and compared structurally, preserving discovery's stat.isFile semantics rather than compiler byte-read semantics.
+ * @evidence contracts/common.md#clear-and-simple-design A narrow local capture avoids broad graph and content facts that project discovery does not consume.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed stat remains a negative file predicate and an unstable identity declines capture; candidate names cannot manufacture successful availability.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies discovery, rejection and the sampling limitation, with a blank tag separator following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Supplied stat and identity operations determine native availability and case-sensitive identity, not an operating-system-wide casing rule.
+ * @evidence contracts/performance.md#efficient-algorithms Two narrow observations read metadata and native identity only, with path/component work and any case-policy directory observation owned by identity resolution; no file bytes or subtree content are scanned for this discovery predicate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each capture asks for independent current observations; the cache-key caller owns permission to reuse the resulting baseline.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Identity contexts and baseline objects remain call-local and no descriptor or task is acquired.
+ */
+export function captureWatchInputFileBaseline(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): TtscWatchInputFileBaseline | undefined {
+  const capture = (): TtscWatchInputFileBaseline => {
+    const identities = createHostPathIdentityContext(filesystem);
+    let fileExists = false;
+    try {
+      fileExists = filesystem.stat(file).isFile();
+    } catch {
+      // Project discovery rejects every candidate not proven to be a file.
+    }
+    return {
+      fileExists,
+      identity: pathIdentityKey(file, identities),
+    };
+  };
+  try {
+    const before = capture();
+    const after = capture();
+    return stableStringify(before) === stableStringify(after)
+      ? after
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/core/transform/watch/evidencedWatchInput.ts

@@ -0,0 +1,109 @@
+import path from "node:path";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import type { TtscEnvelopeDerivation } from "../envelope/TtscEnvelopeDerivation";
+import { derivationIdentity } from "../envelope/derivationIdentity";
+import { selectPluginSourceInputs } from "../envelope/selectPluginSourceInputs";
+import { toProjectKey } from "../project/toProjectKey";
+import { MISSING_INPUT_STATE } from "../validation/MISSING_INPUT_STATE";
+import type { TtscWatchInput } from "./TtscWatchInput";
+import type { TtscWatchInputState } from "./TtscWatchInputState";
+
+/**
+ * One input as a watch input, carrying identity from the generation's qualified
+ * native context and the state it recorded for the path: the compiler's
+ * predicate observation where it made one, the graph's hash and realpath for a
+ * realized input, the host bytes' hash for a walk or dependency-only input, or
+ * the state of a plugin source directory.
+ *
+ * State payloads are retained generation observations; identity queries share
+ * the generation context but a first spelling can still require native reads. A
+ * plugin source state takes precedence over other recorded codecs. An input
+ * with no recorded state returns `state` absent, leaving its caller to decide
+ * whether another observation is appropriate. No current byte read here
+ * manufactures evaluation-time state.
+ *
+ * @param spell The registration spelling callback. Predicate lookup uses the
+ *   native absolute lexical input; hash dictionaries use physical identity or
+ *   project keys without discarding the predicate's original spelling.
+ * @evidence contracts/common.md#principled-implementation Recorded plugin tree state takes precedence, then exact lexical predicates, external graph/host state and project host bytes. Own-entry hash guards preserve absent baselines; unknown state stays absent, with physical target/availability separate from registration spelling.
+ * @evidence contracts/common.md#clear-and-simple-design One derivation maps retained generation facts into the documented watch carrier while the caller supplies its spelling policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown codec state stays absent; the missing marker is a supported observation value rather than a guessed content hash.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes generation evidence and spelling ownership, followed by separated acknowledgment tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve and the generation's identity context preserve actual filesystem identity separately from caller-selected lexical spelling.
+ * @evidence contracts/performance.md#efficient-algorithms Each call allocates one carrier and performs lexical/identity queries plus a plugin-source lookup; a first plugin lookup may parse the full declared source record. Non-tree inputs also compute the project key before selecting the recorded codec. Cost includes key/path text, any cold native path/ancestor/case observations and one caller spelling callback, while recorded byte hashes are not reread. Shared context/plugin populations remain owner costs beyond this fixed carrier allocation.
+ * @evidence contracts/performance.md#reuse-equivalent-work Recorded hashes/predicates and plugin state come from one immutable generation. Identity and project-key queries share its context under a still-valid native view and fixed root; this operation creates a fresh carrier rather than memoizing it, and cannot certify those premises independently.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This mapping stores no new persistent cache or handle; retained generation facts belong to the generation owner.
+ */
+export function evidencedWatchInput(
+  cached: TtscCachedProjectTransform,
+  state: TtscEnvelopeDerivation,
+  input: string,
+  spell: (input: string) => string,
+): TtscWatchInput {
+  const external = cached.externalInputHashes ?? {};
+  const identity = derivationIdentity(state, input);
+  const spelling = path.resolve(input);
+  // A plugin's source directory is proven by the state its binary was built
+  // from, whatever else observed the path (samchon/ttsc#1487).
+  const digest = selectPluginSourceInputs(cached.result).get(spelling);
+  if (digest !== undefined) {
+    return {
+      file: spell(input),
+      evidence: {
+        identity,
+        missing: false,
+        state: { codec: "tree", digest },
+      },
+    };
+  }
+  const observation = cached.externalInputObservations?.[spelling];
+  const missing =
+    observation?.fileExists === false ||
+    state.graph?.inputProofs.get(spelling)?.hash === null ||
+    external[identity] === MISSING_INPUT_STATE;
+  const projectKey = toProjectKey(
+    cached.projectRoot,
+    input,
+    state.identityContext,
+  );
+  const externalHash = Object.prototype.hasOwnProperty.call(external, identity)
+    ? external[identity]
+    : undefined;
+  const projectHash = Object.prototype.hasOwnProperty.call(
+    cached.inputHashes,
+    projectKey,
+  )
+    ? cached.inputHashes[projectKey]
+    : undefined;
+  const graphRealpaths = cached.externalInputRealpaths ?? {};
+  const stateEvidence: TtscWatchInputState | undefined =
+    observation !== undefined
+      ? { codec: "predicates", observation }
+      : externalHash !== undefined &&
+          Object.prototype.hasOwnProperty.call(graphRealpaths, identity)
+        ? {
+            codec: "graph",
+            hash: externalHash,
+            realpath: graphRealpaths[identity] ?? null,
+          }
+        : externalHash !== undefined
+          ? { codec: "host", hash: externalHash }
+          : projectHash !== undefined
+            ? { codec: "host", hash: projectHash }
+            : undefined;
+  return {
+    file: spell(input),
+    evidence: {
+      identity,
+      missing,
+      ...(stateEvidence === undefined ? {} : { state: stateEvidence }),
+      unavailable:
+        observation?.fileExists === false
+          ? "not-file"
+          : missing
+            ? "missing"
+            : undefined,
+    },
+  };
+}

package/src/core/transform/watch/generationWatchInputs.ts

@@ -0,0 +1,94 @@
+import path from "node:path";
+
+import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
+import { envelopeDerivation } from "../envelope/envelopeDerivation";
+import { envelopeGraphIndexes } from "../envelope/envelopeGraphIndexes";
+import { selectHostInputs } from "../envelope/selectHostInputs";
+import { selectPluginSourceInputs } from "../envelope/selectPluginSourceInputs";
+import { isTransformScratchInput } from "../tsconfig/isTransformScratchInput";
+import type { TtscWatchInput } from "./TtscWatchInput";
+import { evidencedWatchInput } from "./evidencedWatchInput";
+
+/** One generation's inputs, derived once for every delivery of it. */
+const GENERATION_WATCH_INPUTS = new WeakMap<
+  TtscCachedProjectTransform,
+  readonly TtscWatchInput[]
+>();
+
+/**
+ * Every input of a generation, with the evidence it recorded: what the
+ * project's record holds and a watching session's bridge observes.
+ *
+ * The record uses a conservative generation-wide selection: every realized or
+ * resolver-input path of the graph (edge sources and targets, globals, the
+ * config chain, resolution inputs, and every candidate), every plugin-reported
+ * dependency, universal host input and plugin source directory. Graph sources
+ * are retained directly even when a per-file list excludes its own delivered
+ * spelling or admits a complete plugin declaration. This is not an exact union
+ * of all narrowed per-file watch lists. The disposed transform scratch tree is
+ * dropped, and so is the temporary tsconfig the compile ran under.
+ *
+ * Memoized per generation. Project-record delivery can separately add configs
+ * consulted while routing another module; this generation-wide input union
+ * retains one readonly snapshot. Consumers must not mutate its array or
+ * entries.
+ *
+ * Every path is the compiler's own spelling: the record is read by the adapter
+ * alone, and the host is handed only the record.
+ *
+ * @evidence contracts/common.md#principled-implementation The union covers compiler graph, reported dependencies, host inputs and plugin-source roots while excluding disposed scratch and temporary configuration paths.
+ * @evidence contracts/common.md#clear-and-simple-design A single append boundary centralizes lexical deduplication and evidence mapping; the memo returns one generation-wide readonly snapshot.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Scratch exclusion reflects disposed ownership, and dependency entries are validated before path use rather than supplemented with consumer-specific guesses.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains generation-wide derivation and memoization; callers must treat the returned array and its entries as immutable, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and generation identity preserve filesystem semantics; lexical spellings remain distinct registration keys even when their physical identities agree.
+ * @evidence contracts/performance.md#efficient-algorithms Cold selection can build graph and plugin-source indexes before scanning graph member spellings, every dependency occurrence and host/plugin lists. Each occurrence pays lexical path/scratch/key work; unique inputs additionally derive evidence with native identity/project-key queries and any cold observation costs. Temporary member arrays/indexes and output grow with producer/query populations and retained text; duplicates skip evidence conversion only after append checks. A completed generation snapshot needs only WeakMap entry selection.
+ * @evidence contracts/performance.md#reuse-equivalent-work The WeakMap shares the completed input union by cached-generation identity. Result/root/scratch/temporary options, recorded evidence and its native identity view must remain valid for that generation; callers must not mutate the shared array or entries. A new cached generation receives a distinct selection without granting freshness from this memo alone.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The owner retains one input array per cached generation, containing unique lexical keys, evidence carriers and references to recorded payloads; sizes follow selected populations and text without a byte cap. Weak keys do not keep generations alive, but a borrower can retain the array/evidence after generation release. Shared derivation indexes have their own state owner; no watcher handle is acquired here.
+ */
+export function generationWatchInputs(
+  cached: TtscCachedProjectTransform,
+): readonly TtscWatchInput[] {
+  const memo = GENERATION_WATCH_INPUTS.get(cached);
+  if (memo !== undefined) return memo;
+  const state = envelopeDerivation(cached);
+  const props = {
+    projectRoot: cached.projectRoot,
+    result: cached.result,
+    scratchDirectory: cached.scratchDirectory,
+    temporaryTsconfig: cached.temporaryTsconfig,
+  };
+  const temporary =
+    cached.temporaryTsconfig === undefined
+      ? undefined
+      : path.resolve(cached.temporaryTsconfig);
+  const seen = new Set<string>();
+  const inputs: TtscWatchInput[] = [];
+  const append = (input: string): void => {
+    const spelling = path.resolve(input);
+    if (
+      spelling === temporary ||
+      isTransformScratchInput(spelling, cached.scratchDirectory) ||
+      seen.has(spelling)
+    ) {
+      return;
+    }
+    seen.add(spelling);
+    inputs.push(evidencedWatchInput(cached, state, spelling, (input) => input));
+  };
+  if (cached.result.type !== "exception") {
+    for (const spelling of envelopeGraphIndexes(state, props).memberSpellings)
+      append(spelling);
+    for (const entries of Object.values(cached.result.dependencies ?? {})) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        if (typeof entry === "string" && entry.length !== 0)
+          append(path.resolve(cached.projectRoot, entry));
+      }
+    }
+    for (const input of selectHostInputs(props)) append(input);
+    for (const input of selectPluginSourceInputs(cached.result).keys())
+      append(input);
+  }
+  GENERATION_WATCH_INPUTS.set(cached, inputs);
+  return inputs;
+}

package/src/core/transform/watch/handWatchInputs.ts

@@ -0,0 +1,64 @@
+import type { TtscTransformHooks } from "./TtscTransformHooks";
+import type { TtscWatchInput } from "./TtscWatchInput";
+
+/**
+ * Hand one delivery's watch inputs to the host, each spelling once.
+ *
+ * The inputs reach here spelled as the host spells the project
+ * (`hostSpelling`), which folds the compiler's physical spelling of an input
+ * and the adapter's own spelling of the same file, the selected config among
+ * them, into one. A host given both would register the file twice, and one
+ * comparing its registrations lexically would watch it twice.
+ *
+ * One spelling can arrive more than once with different evidence, and the
+ * registration that carries the most is the one handed over: the project's
+ * root-file membership before anything else for the project root, and an
+ * evidenced input before a plain one. A graph lists the project root itself as
+ * a resolution input, so a failed generation's recovery list named it plainly
+ * before its membership, and keeping the first occurrence dropped the
+ * membership: nothing then observed a root file appearing, and an input deleted
+ * and recreated under a watching Next.js session was never heard again. The
+ * order the inputs were derived in decides nothing else; among equals the first
+ * stays, so the compiler's evidence, listed first, wins over the adapter's for
+ * one file.
+ *
+ * @param hooks The host's hooks; nothing is handed when it takes no inputs.
+ * @param inputs The inputs in the order they were derived.
+ * @param failed Whether they are a failed generation's, for a batching host.
+ * @evidence contracts/common.md#principled-implementation Exact registration spellings are deduplicated with membership preferred over ordinary evidence and evidence over a recovery-only path; equal-ranked entries retain the first observation.
+ * @evidence contracts/common.md#clear-and-simple-design One precedence pass feeds either the batch callback or individual callbacks, leaving evidence derivation and bundler policy with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Contract-defined precedence keeps the strongest available input meaning without inventing facts, and batch preference follows the supported callback contract.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains callback preference, deduplication and precedence, with separated tags following documentation guidance.
+ * @evidence contracts/performance.md#efficient-algorithms One pass performs N keyed selection operations with fixed rank checks, followed by a U-entry array copy, avoiding pairwise duplicate searches. Map hashing/comparison pays exact spelling text costs, and temporary storage retains U entries/keys. One batch or U individual callback effects add their host-owned work; no-hook delivery returns before selection/allocation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Callback delivery is an effect for each module; matching input values do not authorize suppressing another host notification.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The chosen map and batch are call-local; host callbacks own any retained watcher state after delivery.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Deduplicates inputs by their exact spelling and hands them to host callbacks; no path is parsed.
+ */
+export function handWatchInputs(
+  hooks: TtscTransformHooks | undefined,
+  inputs: readonly TtscWatchInput[],
+  failed?: boolean,
+): void {
+  const addWatchFile = hooks?.addWatchFile;
+  const addWatchFiles = hooks?.addWatchFiles;
+  if (addWatchFile === undefined && addWatchFiles === undefined) return;
+  const chosen = new Map<string, TtscWatchInput>();
+  for (const input of inputs) {
+    const kept = chosen.get(input.file);
+    if (kept === undefined || rank(input) > rank(kept)) {
+      chosen.set(input.file, input);
+    }
+  }
+  const distinct = [...chosen.values()];
+  if (addWatchFiles !== undefined) {
+    addWatchFiles(distinct, failed);
+    return;
+  }
+  for (const input of distinct) addWatchFile!(input.file, input.evidence);
+}
+
+/** How much a registration says about its path: membership, evidence, nothing. */
+function rank(input: TtscWatchInput): number {
+  if (input.evidence?.state?.codec === "membership") return 2;
+  return input.evidence === undefined ? 0 : 1;
+}