@ttsc/unplugin 0.30.4 → 0.31.0

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

@@ -0,0 +1,45 @@
+/**
+ * Whether a project-walk snapshot is coherent for the inputs that matter.
+ *
+ * A capturing walk reads admitted regular files, including source artifacts
+ * that no compiled input consumed. Such a file can fail its own bracketed read
+ * while every declared input holds still. A validating walk may already limit
+ * those reads to declared keys. Attributable failure outside that population
+ * does not establish that the generation changed. A walk that could not
+ * enumerate a directory, or a file-level failure this snapshot could not
+ * attribute to a key, still taints everything: neither can be shown to leave
+ * the inputs alone.
+ *
+ * @evidence contracts/common.md#principled-implementation Global directory incompleteness taints all inputs, while attributable unstable files taint a declared generation only when their keys belong to its required population.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate separates enumeration coherence from file-level coherence without duplicating the filesystem walk.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown enumeration failures cannot be ignored as unrelated artifacts, and irrelevant file failures cannot invent a program inconsistency.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain global enumeration failure and attributable non-input instability as distinct states.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Reads completeness flags and key sets of an already collected snapshot; it reads no filesystem.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate borrows the snapshot and retains no storage or native resource.
+ * @evidence contracts/performance.md#efficient-algorithms Global flags precede one unstable-key scan with expected-constant Set entry lookup and early mismatch return; hashing or comparing a newly queried key retains its text cost. The predicate builds no secondary key collection.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The owning generation validator coordinates reused snapshots; this helper classifies one walk's authority.
+ */
+export function walkSnapshotComplete(
+  snapshot: {
+    /** Whether all selected directory and file observations were coherent. */
+    complete: boolean;
+
+    /** Whether enumeration and attribution establish every directory boundary. */
+    directoryComplete: boolean;
+
+    /** Project identity keys attributed to failed or unstable file observations. */
+    unstableFiles: ReadonlySet<string>;
+  },
+  declared: ReadonlySet<string> | undefined,
+): boolean {
+  if (declared === undefined) {
+    return snapshot.complete;
+  }
+  if (!snapshot.directoryComplete) {
+    return false;
+  }
+  for (const key of snapshot.unstableFiles) {
+    if (declared.has(key)) return false;
+  }
+  return true;
+}

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

@@ -0,0 +1,56 @@
+import path from "node:path";
+
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { hostInputRealpath } from "../inputs/hostInputRealpath";
+import { hostInputStateHash } from "../inputs/hostInputStateHash";
+import { inputMetadataSignature } from "../inputs/inputMetadataSignature";
+import type { TtscExternalDependencyWitness } from "./TtscExternalDependencyWitness";
+
+/**
+ * Read the state of plugin-reported dependency paths before a compile, keyed by
+ * resolved spelling.
+ *
+ * A compile learns its dependency-only paths only from the envelope it returns,
+ * so the paths read here are the ones an earlier compile of the same project
+ * reported. A path the compile reports for the first time has no witness, and
+ * its generation is compiled again with one (samchon/ttsc#1541).
+ *
+ * @param paths Dependency-only paths an earlier compile reported.
+ * @param filesystem The filesystem the compile reads.
+ * @evidence contracts/common.md#principled-implementation Content, physical target and metadata boundaries are captured before compile; signature equality records one comparison rather than certifying an atomic read or usable metadata.
+ * @evidence contracts/common.md#clear-and-simple-design One witness constructor groups the dependency observations required by postcompile admission, leaving retry policy to generation ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A newly reported path has no invented earlier witness; its owner must compile with a real pre-read observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain earlier-report inputs and the first-discovery recompile premise before argument tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Injected native operations observe content, link targets and timestamps while lexical resolved spellings keep alias metadata witnesses distinct.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Witness ownership transfers to the compile attempt and temporary map size follows reported dependency paths; this helper acquires no persistent handle.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   N supplied occurrences each receive metadata/content/realpath/metadata
+ *   observations and native resolved-key construction. Bytes read/hash dominate
+ *   large files, while component/link resolution and metadata/bigint signature
+ *   text remain real costs. Duplicate resolved keys still reread and overwrite;
+ *   U final keys retain hashes/targets/signatures, not the read buffers.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The attempt shares these precompile endpoints with postcompile admission,
+ *   which compares signatures, content and physical target and rejects absent
+ *   witnesses or changed comparisons. New paths need a later attempt with a
+ *   pre-read; matching endpoints are not a plugin-recorded read proof.
+ */
+export function witnessExternalDependencies(
+  paths: readonly string[],
+  filesystem: TtscTransformFilesystemOperations,
+): Map<string, TtscExternalDependencyWitness> {
+  const witnesses = new Map<string, TtscExternalDependencyWitness>();
+  for (const input of paths) {
+    const before = inputMetadataSignature(input, filesystem);
+    const hash = hostInputStateHash(input, filesystem);
+    const realpath = hostInputRealpath(input, filesystem);
+    const after = inputMetadataSignature(input, filesystem);
+    witnesses.set(path.resolve(input), {
+      hash,
+      realpath,
+      signature: after,
+      stable: before === after,
+    });
+  }
+  return witnesses;
+}

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

@@ -0,0 +1,74 @@
+import type { TtscWatchInput } from "./TtscWatchInput";
+
+/**
+ * What one delivery hands a host that observes the project through its record
+ * (`TtscTransformHooks.project`): the record file and the inputs a watching
+ * session's bridge observes to move it. A digest identifies snapshot bytes
+ * accepted by persistence, which can find identical bytes without rewriting. An
+ * existing record handed over without acceptance for that revision has no
+ * digest.
+ *
+ * @evidence contracts/common.md#principled-implementation The record path, optional accepted snapshot digest, failure flag and snapshot callback distinguish revision-specific byte acceptance from a record merely found after persistence refusal.
+ * @evidence contracts/common.md#clear-and-simple-design One delivery carrier groups the persisted record with its live-watch inputs while keeping reading behind a named callback signature.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An absent digest remains absent when persistence accepted no snapshot for this revision; identical existing bytes can be accepted without rewriting, and an arbitrary older record gains no guessed current proof.
+ * @evidence contracts/common.md#meaningful-documentation Native members explain digest ownership, recovery state and snapshot replacement; separated members and tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The actual native record spelling is carried separately from its content digest and input identities, with no OS-wide case assumption.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscProjectRegistration only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscProjectRegistration only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscProjectRegistration only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscProjectRegistration {
+  /**
+   * The digest of snapshot bytes this process wrote or found identical in
+   * {@link record} for the delivery's revision (`projectRecordDigest`), or
+   * `undefined` when persistence accepted no bytes for that revision. A host
+   * that keeps no snapshot of the record compares it with the record's bytes
+   * before it serves the module from a cache
+   * (`createRollupCachedModuleProof`).
+   */
+  digest?: string;
+
+  /** Whether the delivery failed and the inputs are the recovery inputs. */
+  failed: boolean;
+
+  /**
+   * This registration's retained snapshot of generation and routing inputs,
+   * with the evidence the record holds, for a bridge that observes them live.
+   * Additional config-selection inputs produce a new immutable snapshot, so
+   * later registrations can replace the bridge's observed input set.
+   */
+  inputs: TtscWatchProjectInputs;
+
+  /** Host-approved record path; digest identifies the accepted snapshot bytes. */
+  record: string;
+}
+
+/**
+ * Obtain the readonly watching snapshot retained for this registration.
+ *
+ * Later registrations may carry a new snapshot when the same generation gains
+ * another selection dependency. Consumers must not mutate the array or
+ * entries.
+ *
+ * @evidence contracts/common.md#principled-implementation The zero-argument result exposes a registration's stable snapshot while later registrations can represent an expanded dependency set.
+ * @evidence contracts/common.md#clear-and-simple-design A named function alias preserves the existing property signature and avoids changing callback assignability through method syntax.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Snapshot delivery carries recorded inputs instead of reconstructing evidence from an expected cache outcome.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe snapshot replacement and caller ownership; separated tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native spellings and identity facts stay in the input carrier; this callback performs no platform-dependent path rewrite.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchProjectInputs only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchProjectInputs only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchProjectInputs only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export type TtscWatchProjectInputs = () => readonly TtscWatchInput[];

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

@@ -0,0 +1,217 @@
+import type { TtscProjectRegistration } from "./TtscProjectRegistration";
+import type { TtscWatchInput } from "./TtscWatchInput";
+import type { TtscWatchInputEvidence } from "./TtscWatchInputEvidence";
+
+/**
+ * How a host learns what one delivery depends on. A host takes one of two
+ * shapes:
+ *
+ * - A host that keys each module on the inputs of that module alone, such as
+ *   `@ttsc/metro`'s fingerprint or a Vite dev server's module graph, takes them
+ *   through {@link addWatchFile} or {@link addWatchFiles}.
+ * - A build host, which watches files and snapshots them in a persistent cache,
+ *   takes the project's record through {@link project}: a generation compiles
+ *   the whole project, so a module's output is a function of the project's
+ *   state and of nothing finer, and the record is that state as one file.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional module callbacks and project registration represent the host's dependency models; explicit delivery lifecycle and actual cache withdrawal additionally distinguish a one-shot fresh-only answer from unsupported watching or unknown observation capability.
+ * @evidence contracts/common.md#clear-and-simple-design Named callback signatures preserve function-property variance and leave registration policy with the host rather than introducing a second host abstraction.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Hosts supply actual lifecycle and cache-withdrawal capabilities rather than guessed watch modes, no-op permission callbacks, bundler mutation or fabricated dependencies for an unknown input closure.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish module and project hosts, recovery batches, unwritable records and volatility; spaced member comments and separated tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Absolute native watch spellings and host-owned tool directories cross this explicit boundary; no OS name or fixed directory determines their capabilities.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscTransformHooks only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscTransformHooks only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscTransformHooks only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export interface TtscTransformHooks {
+  /**
+   * Invoked once per absolute watch-input path derived for the transformed file
+   * `F`: the plugin-reported `dependencies[F]` list unioned with the host-owned
+   * reference graph's contribution — the reachability closure of `graph.edges`
+   * from `F`, the `graph.globals` files, the `graph.configs` chain, importer
+   * `graph.candidates`, and universal `graph.resolutionInputs`, together with
+   * the universal host inputs and plugin source directories. For a file the
+   * envelope declared `dependenciesComplete` without also declaring it
+   * volatile, the reachability closure and `graph.globals` are dropped;
+   * `dependencies[F]`, importer `graph.candidates`, `graph.resolutionInputs`,
+   * the universal host inputs, the plugin source directories and the universal
+   * `graph.configs` chain remain. See `selectWatchInputs` for the exact
+   * derivation.
+   */
+  addWatchFile?: TtscAddWatchFile;
+
+  /**
+   * Batched form of {@link addWatchFile}. When supplied, the transform calls it
+   * once per delivered module and does not call `addWatchFile` for that module.
+   * `failed` marks a recovery batch: a failed compiler can omit inputs from its
+   * previous successful result, so replacing hosts should retain those
+   * spellings until the next successful delivery.
+   */
+  addWatchFiles?: TtscAddWatchFiles;
+
+  /**
+   * Whether the batch of {@link addWatchFile} or {@link addWatchFiles} also
+   * carries the project's root-file membership: one input for the project root,
+   * of kind `membership` (samchon/ttsc#1419), which a dev server's watcher
+   * observes by walking the project again when a membership snapshot is
+   * available. A host that already re-keys on the whole project walk, as
+   * `@ttsc/metro` does, leaves it out. A build host's record ({@link project})
+   * carries captured membership or an explicit null when it is unavailable.
+   */
+  membership?: boolean;
+
+  /**
+   * Whether the delivered id is already a bare filesystem path, as esbuild, Bun
+   * and a webpack-style loader context hand it (`args.path`, `resourcePath`),
+   * with any query or hash held apart by the host. A `?` or `#` in such a path
+   * belongs to a directory or file name, so the transform uses the id as it is.
+   * Left unset, the id is a bundler module id (Vite, Rollup, webpack, Rspack,
+   * Farm) whose query and hash suffix is stripped and whose host-wrapper
+   * queries (`?raw`, `?url`) are left to the host.
+   */
+  exactPath?: boolean;
+
+  /**
+   * Actual delivery lifecycle reported by the adapter. False identifies a
+   * one-shot execution; true identifies watching, and absence leaves it
+   * unknown. Fresh output with unavailable observations requires false plus a
+   * supported cache-withdrawal callback. When project.watching is supplied,
+   * both declarations must agree for that admission.
+   */
+  watching?: boolean;
+
+  /**
+   * A build host's registration: the transform writes the project's record
+   * below `toolDirectory` (`projectRecordFile`) to the generation's state and
+   * hands it over once per delivery, with the generation's inputs for a
+   * watching session's bridge (`registerProjectRecord`).
+   */
+  project?: {
+    /** Called once per delivery, failed deliveries included. */
+    register: TtscRegisterWatchProject;
+
+    /** The host's tool directory (`hostToolDirectory`), where the record lives. */
+    toolDirectory: string;
+
+    /**
+     * Where the record lives when `toolDirectory` cannot be written
+     * (`fallbackToolDirectory`, samchon/ttsc#1480), or `undefined` for a host
+     * that accepts no record outside its root, or none this user can write.
+     */
+    fallbackToolDirectory?: string;
+
+    /**
+     * Whether the host watches this session. A successful delivery that can be
+     * handed no record would be served from the host's watcher's silence after
+     * a type-only edit, so it fails instead
+     * (`TtscProjectRecordUnwritableError`); a host that cannot tell whether it
+     * watches, esbuild, leaves this unset.
+     */
+    watching?: boolean;
+  };
+
+  /**
+   * Invoked when the module's output depends on inputs no file-dependency
+   * snapshot of the module represents: the plugin declared the transformed file
+   * volatile (the envelope's `volatile` list), or the module was handed over
+   * without a complete host-observation closure, or without the project's
+   * record, which could not be written. Adapters should mark the module
+   * uncacheable where the bundler exposes that control (e.g. a webpack loader
+   * context's `cacheable(false)`), or answer the bundler's cache for it where
+   * the bundler asks instead (Rollup's `shouldTransformCachedModule`, through
+   * the module's `meta`).
+   */
+  markVolatile?: TtscMarkVolatile;
+}
+
+/**
+ * Receive one absolute watch spelling and its optional generation facts.
+ *
+ * @evidence contracts/common.md#principled-implementation The two parameters keep the host's lexical registration key separate from optional evidence used to validate that input.
+ * @evidence contracts/common.md#clear-and-simple-design A named function type retains the original callback-property signature and optional evidence without method bivariance.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts This supported callback boundary supplies dependencies without replacing host methods or inventing observations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes spelling and optional facts; the owning member documents derivation, with a blank tag separator following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The callback receives a native absolute spelling and generation-owned identity facts; it does not impose path case policy on the host.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscAddWatchFile only declares a shape; it has no computation at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscAddWatchFile only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscAddWatchFile only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export type TtscAddWatchFile = (
+  file: string,
+  evidence?: TtscWatchInputEvidence,
+) => void;
+
+/**
+ * Receive a readonly input batch; failed batches retain recovery dependencies.
+ *
+ * @evidence contracts/common.md#principled-implementation The batch and optional failure flag express replacement versus recovery delivery without erasing per-input evidence.
+ * @evidence contracts/common.md#clear-and-simple-design A single named function signature preserves the optional flag and original function-property assignability.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Recovery is an explicit host contract rather than successful evidence manufactured for a failed compile.
+ * @evidence contracts/common.md#meaningful-documentation Native prose and the owning member explain readonly batching and failed retention; separated tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native input spellings and filesystem identities remain in the documented input carrier without conversion to platform guesses.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscAddWatchFiles only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscAddWatchFiles only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscAddWatchFiles only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export type TtscAddWatchFiles = (
+  inputs: readonly TtscWatchInput[],
+  failed?: boolean,
+) => void;
+
+/**
+ * Hand a host the project record and its watching inputs for this delivery.
+ *
+ * @evidence contracts/common.md#principled-implementation The registration carrier supplies the record path, failure state and input snapshot callback needed by a project-based host.
+ * @evidence contracts/common.md#clear-and-simple-design A named callback signature preserves the nested property contract without adding a runtime wrapper or changing method variance.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Registration uses the supported host callback rather than patching its watcher or cache internals.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the delivery role and the registration type documents the payload, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The payload carries the record's actual native path; the host selects its writable location through the existing project boundary.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscRegisterWatchProject only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscRegisterWatchProject only declares a shape; it has no work to reuse
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscRegisterWatchProject only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export type TtscRegisterWatchProject = (
+  registration: TtscProjectRegistration,
+) => void;
+
+/**
+ * Mark the delivered module uncacheable when file dependencies cannot cover it.
+ *
+ * @evidence contracts/common.md#principled-implementation A no-argument notification expresses the current delivery's volatility without pretending that a synthetic file captures non-file dependencies.
+ * @evidence contracts/common.md#clear-and-simple-design The named callback retains the existing function-property signature and leaves each bundler's cache control with its adapter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported notification exposes uncertainty instead of forcing a cache hit through hidden host mutation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the uncacheable effect and the owning member explains its triggers; separated tags follow documentation guidance.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This no-argument cache-control notification carries no native filesystem or process representation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscMarkVolatile only declares a shape; it has no computation at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscMarkVolatile only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscMarkVolatile only declares a shape; it has no handle or retained
+ *   state at runtime.
+ */
+export type TtscMarkVolatile = () => void;

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

@@ -0,0 +1,28 @@
+import type { TtscWatchInputEvidence } from "./TtscWatchInputEvidence";
+
+/**
+ * One derived input and its optional generation proof.
+ *
+ * @evidence contracts/common.md#principled-implementation A lexical path identifies the watched spelling while optional evidence distinguishes recorded state from recovery-only registrations.
+ * @evidence contracts/common.md#clear-and-simple-design The pair separates the host's registration path from the generation facts used to validate it.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing evidence remains explicit rather than supplying a guessed successful state.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments explain absolute spelling and recovery absence, with member spacing and a blank tag separator following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lexical spelling remains separate from evidence identity; no OS-wide case assumption is encoded in the carrier.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchInput only declares a shape; it has no computation at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchInput only declares a shape; it has no work to reuse at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchInput only declares a shape; it has no handle or retained state
+ *   at runtime.
+ */
+export interface TtscWatchInput {
+  /**
+   * What the generation recorded for this input; absent on failed-generation
+   * recovery registrations.
+   */
+  evidence?: TtscWatchInputEvidence;
+
+  /** Absolute lexical spelling of the input. */
+  file: string;
+}

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

@@ -0,0 +1,73 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+
+import type { TtscWatchInputFileBaseline } from "./TtscWatchInputFileBaseline";
+
+/**
+ * Main-process observations for comparing one-path watch-input codecs.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate hashes and predicates represent the different compiler, host and plugin-tree observations without treating their codecs as interchangeable.
+ * @evidence contracts/common.md#clear-and-simple-design Extending the file baseline shares its identity predicate while named fields expose the broader comparison facts.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit null reads and failed realpath variants retain unavailable observations instead of expected hashes or guessed targets.
+ * @evidence contracts/common.md#meaningful-documentation Member comments distinguish read failure, stat classification and optional subtree capture, with spacing and a blank tag separator following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native stat kinds and realpath success are represented as observed facts; identity and lexical target are not conflated by a case-fold rule.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchInputBaseline only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchInputBaseline only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchInputBaseline only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscWatchInputBaseline extends TtscWatchInputFileBaseline {
+  /**
+   * Current version-one native codec facts, captured only for requested kinds.
+   * These observations do not certify a producer's identityStable flag or scope.
+   */
+  nativePredicates?: Partial<
+    Record<
+      NonNullable<
+        ITtscCompilerTransformation.IInputObservation["nativePredicates"]
+      >[number]["kind"],
+      { digest: string; realpath: string | null }
+    >
+  >;
+
+  /**
+   * Sorted compiler-accessible entry names, captured only when requested.
+   * Absence cannot establish a recorded listing predicate's agreement.
+   */
+  accessibleEntries?: NonNullable<
+    ITtscCompilerTransformation.IInputObservation["accessibleEntries"]
+  >;
+
+  /** Whether the compiler's stat classifies the path as a directory. */
+  directoryExists: boolean;
+
+  /** State hash under the `graph` evidence codec, or the missing-input marker. */
+  graphHash: string;
+
+  /**
+   * Hash of the compiler-style read an observation's `readFile` predicate
+   * records, or `null` when that read fails.
+   */
+  graphReadHash: string | null;
+
+  /** State hash under the `host` evidence codec, or the missing-input marker. */
+  hostHash: string;
+
+  /** The compiler's realpath observation of the path. */
+  realpath: { ok: false; path?: never } | { ok: true; path: string };
+
+  /** The compiler's stat classification of the path. */
+  stat: "directory" | "file" | "missing";
+
+  /**
+   * The path's state as a plugin source directory, its files and build
+   * environment (`pluginSourceState`, samchon/ttsc#1487, samchon/ttsc#1493),
+   * captured only for a path recorded as one, since the state reads every file
+   * below it; `null` when it cannot be read.
+   */
+  tree?: string | null;
+}

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

@@ -0,0 +1,46 @@
+import type { TtscWatchInputState } from "./TtscWatchInputState";
+
+/**
+ * What the generation already knows about one derived watch input, handed to
+ * the adapter so it does not rederive it per input per delivery.
+ *
+ * All facts are generation state: the identity is the memoized
+ * `pathIdentityKey` of the input. `missing` records unavailable file evidence,
+ * which can include an unreadable input rather than native absence;
+ * `unavailable` distinguishes an explicit failed file predicate from the
+ * broader missing-state marker. An adapter that computes them itself pays a
+ * `realpath`, a case-sensitivity directory listing, and an `existsSync` for
+ * every input of every delivered module, which is O(modules x inputs) for one
+ * build (samchon/ttsc#1246).
+ *
+ * @evidence contracts/common.md#principled-implementation Identity, availability and optional codec state preserve distinct generation observations; unavailable refines missing without claiming a current disk read.
+ * @evidence contracts/common.md#clear-and-simple-design The carrier keeps derived facts together so adapters consume one generation answer instead of reconstructing independent predicates.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown state stays optional; the supported missing/not-file distinction does not substitute fabricated content.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain generation ownership and repeated observation costs; spaced member comments and separated tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Filesystem identity is supplied by the generation's native identity owner rather than derived from path casing or an OS name here.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchInputEvidence only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchInputEvidence only declares a shape; it has no work to reuse at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchInputEvidence only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscWatchInputEvidence {
+  /** Memoized filesystem identity of the input. */
+  identity: string;
+
+  /** Whether the generation recorded this input as unavailable as a file. */
+  missing: boolean;
+
+  /** The generation state Metro can compare with its main-process baseline. */
+  state?: TtscWatchInputState;
+
+  /**
+   * Recorded unavailability category, not the only cause of invalidation.
+   * `missing` does not independently prove native absence.
+   */
+  unavailable?: "missing" | "not-file";
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Main-process file predicate used only by project discovery.
+ *
+ * @evidence contracts/common.md#principled-implementation The file predicate and identity express the two facts discovery needs; its member documentation distinguishes the broader compiler predicate used by the extending baseline.
+ * @evidence contracts/common.md#clear-and-simple-design This minimal base avoids reading content or constructing graph state for a discovery-only question.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Availability is observed and identity is carried explicitly, without accepting an expected candidate solely from its name.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain predicate provenance and identity mismatch, with separated members and tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation The native file predicate and filesystem identity remain independent facts; platform-specific case policy is not guessed by this type.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchInputFileBaseline only declares a shape; it has no computation
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchInputFileBaseline only declares a shape; it has no work to reuse
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchInputFileBaseline only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export interface TtscWatchInputFileBaseline {
+  /**
+   * Whether the path counts as a file under the predicate that captured it:
+   * discovery's regular-file check for a file baseline, or the compiler's stat
+   * kind, which counts anything but a directory, for a broad one.
+   */
+  fileExists: boolean;
+
+  /**
+   * Filesystem identity key of the path; evidence recorded for another identity
+   * never matches.
+   */
+  identity: string;
+}

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

@@ -0,0 +1,24 @@
+import type { TtscWatchInputBaseline } from "./TtscWatchInputBaseline";
+import type { TtscWatchInputFileBaseline } from "./TtscWatchInputFileBaseline";
+
+/**
+ * Baseline shape stored for either a discovery predicate or a full input.
+ *
+ * @evidence contracts/common.md#principled-implementation The union admits either the narrow discovery facts or the broader codec facts, matching the two capture operations.
+ * @evidence contracts/common.md#clear-and-simple-design Named baseline types retain their own member meanings instead of duplicating their representations in this alias.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The union preserves the supported narrow shape without inventing content evidence for discovery-only inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names the two purposes and the constituent types expose their documented facts; separated tags follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Both variants carry the observed native identity and predicate meanings rather than choosing a shape by operating-system name.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   TtscWatchInputKeyBaseline only declares a shape; it has no computation at
+ *   runtime.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   TtscWatchInputKeyBaseline only declares a shape; it has no work to reuse
+ *   at runtime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   TtscWatchInputKeyBaseline only declares a shape; it has no handle or
+ *   retained state at runtime.
+ */
+export type TtscWatchInputKeyBaseline =
+  | TtscWatchInputFileBaseline
+  | TtscWatchInputBaseline;