@ttsc/unplugin 0.30.3 → 0.31.0

package/src/core/transform/inputs/compilerInputRealpathObservation.ts

@@ -0,0 +1,40 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import { resolveFilesystemPath } from "ttsc/path-identity";
+
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * Replay the compiler's realpath observation. An empty resolver result is
+ * unsuccessful; a thrown native resolution uses the compiler's cleaned lexical
+ * fallback instead of becoming a missing-input proof.
+ *
+ * @evidence contracts/common.md#principled-implementation Empty results and thrown resolution remain distinct because the compiler records an empty result as failed but cleans the input spelling on native resolution failure.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter maps resolver output into the envelope's realpath observation; identity comparison remains with its consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The lexical fallback reproduces the compiler filesystem contract rather than fabricating successful physical resolution for a known input.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes empty, successful and fallback results; a blank comment line separates acknowledgments under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay uses the supplied resolver and explicit path dialect through resolveFilesystemPath; the cleaned fallback does not claim native alias or case equivalence.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed protocol adapter maps one supplied realpath result or exception into an observation. Native resolution and lexical path cleanup retain their component/link and text-length costs in the respective owners; one call is not a constant native-work guarantee.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work It replays the compiler's observation against the filesystem now by design, so nothing is shared.
+ */
+export function compilerInputRealpathObservation(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations,
+): NonNullable<ITtscCompilerTransformation.IInputObservation["realpath"]> {
+  try {
+    const realpath = filesystem.realpath(file);
+    return realpath.length === 0
+      ? { ok: false }
+      : {
+          ok: true,
+          path: resolveFilesystemPath(realpath, filesystem.platform),
+        };
+  } catch {
+    // TypeScript-Go's OS and io filesystems return the cleaned input spelling
+    // when native realpath resolution fails; they do not expose the failure.
+    return {
+      ok: true,
+      path: resolveFilesystemPath(file, filesystem.platform),
+    };
+  }
+}

package/src/core/transform/inputs/compilerInputTextHash.ts

@@ -0,0 +1,37 @@
+import { hashText } from "../utils/hashText";
+
+/**
+ * Hash one observed byte buffer under the compiler's BOM decoding rules. UTF-16
+ * omits an incomplete trailing unit and big-endian decoding copies its slice
+ * before swapping; raw host hashing can still consume the original bytes.
+ *
+ * @evidence contracts/common.md#principled-implementation Compiler text decoding removes UTF BOMs and preserves the existing incomplete UTF-16 unit rule before hashing.
+ * @evidence contracts/common.md#clear-and-simple-design One byte-to-text hash owner lets a current observation share its actual read across compiler and host codecs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supplied observed bytes determine the hash; no expected digest or stale filesystem reading substitutes for them.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains decoding and the original buffer's continued raw-byte availability.
+ * @evidence contracts/portability.md#os-neutral-implementation Encoding comes from observed BOM bytes, independently of platform defaults; big-endian decoding copies before swapping and leaves raw input unchanged.
+ * @evidence contracts/performance.md#efficient-algorithms Decoding and hashing scan B bytes; UTF-8 slices share storage, while UTF-16 decoding allocates proportional text and big-endian input requires a copy.
+ * @evidence contracts/performance.md#reuse-equivalent-work The caller can derive both codecs from one current read; this pure decoder retains no cross-observation cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the digest escapes; temporary decoded text and copied bytes remain call-local.
+ */
+export function compilerInputTextHash(bytes: Buffer): string {
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+    const even = bytes.subarray(2, 2 + Math.floor((bytes.length - 2) / 2) * 2);
+    return hashText(Buffer.from(even.toString("utf16le"), "utf8"));
+  }
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+    const even = Buffer.from(
+      bytes.subarray(2, 2 + Math.floor((bytes.length - 2) / 2) * 2),
+    );
+    even.swap16();
+    return hashText(Buffer.from(even.toString("utf16le"), "utf8"));
+  }
+  return hashText(
+    bytes.length >= 3 &&
+      bytes[0] === 0xef &&
+      bytes[1] === 0xbb &&
+      bytes[2] === 0xbf
+      ? bytes.subarray(3)
+      : bytes,
+  );
+}

package/src/core/transform/inputs/compilerStatKind.ts

@@ -0,0 +1,26 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * Classify a following stat as the compiler does: directories retain their
+ * kind, every other successful stat is a file, and a failed stat is missing.
+ * This classification does not establish readable content.
+ *
+ * @evidence contracts/common.md#principled-implementation The three results preserve the compiler's directory-versus-other stat semantics and failure result; isFile is intentionally not a separate prerequisite.
+ * @evidence contracts/common.md#clear-and-simple-design One following stat owns classification without mixing byte reads or lexical existence checks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification derives from observed metadata rather than extensions, recorded expectations or a patched stat implementation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains non-directory success and the readability boundary, with a separated acknowledgment block following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral kind observation uses the supplied filesystem's following stat and native directory predicate; special non-directory nodes follow compiler semantics rather than host-specific guesses.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The fixed scalar adapter classifies one supplied following stat and chooses no population-processing strategy. Native component/link resolution cost remains with that filesystem operation; one call does not certify constant native work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work It classifies the filesystem now by design, so nothing is shared.
+ */
+export function compilerStatKind(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations,
+): "directory" | "file" | "missing" {
+  try {
+    return filesystem.stat(file).isDirectory() ? "directory" : "file";
+  } catch {
+    return "missing";
+  }
+}

package/src/core/transform/inputs/graphInputObservationFailures.ts

@@ -0,0 +1,94 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { compilerAccessibleEntries } from "./compilerAccessibleEntries";
+import { compilerInputRealpathObservation } from "./compilerInputRealpathObservation";
+import { compilerStatKind } from "./compilerStatKind";
+import { graphInputReadHash } from "./graphInputReadHash";
+import { nativeInputPredicateMatches } from "./nativeInputPredicateMatches";
+import { sameHostInputRealpath } from "./sameHostInputRealpath";
+
+/**
+ * Replay the predicates recorded for one compiler-input spelling and collect
+ * every mismatch. Only recorded predicates are observed; one following stat is
+ * shared by kind, existence and read checks. Directory listings preserve sorted
+ * compiler entry names, while realpaths compare through filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Each present predicate compares its recorded result with compiler-compatible replay, preserving read failure, native kind, listing order and realpath identity as separate observations.
+ * @evidence contracts/common.md#clear-and-simple-design The collector owns mismatch names and delegates stat, text normalization and physical equivalence to their single-purpose observers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unrecorded predicates are not invented, and read or resolution failure is compared against recorded failure instead of replaced by a convenient cache match.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states full collection, absent-predicate behavior and shared observations, with separated acknowledgment tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay uses the supplied filesystem and identity context; accessible-entry joining selects that view's path dialect and realpath equality follows actual case capabilities.
+ * @evidence contracts/performance.md#efficient-algorithms One kind stat serves existence, kind and read checks; native listing/link/identity operations retain their path costs. Selected listings encode name bytes, sort E names by compared UTF-8 prefixes and serialize current/recorded names for equality; text decoding/hashing scans B read bytes. Temporary storage follows listing names/encodings/serialized text, read buffers and supplied identity observations; the returned failure list has the six compiler predicate names plus one name per supplied native predicate. Absent listing/read predicates perform neither operation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This collects one current replay; the generation owner decides whether an earlier replay remains valid across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Entry arrays and failure names are observation-local, with no persistent cache, descriptor or running task owned by the collector.
+ */
+export function graphInputObservationFailures(
+  file: string,
+  observation: ITtscCompilerTransformation.IInputObservation,
+  filesystem: TtscTransformFilesystemOperations,
+  identities: FilesystemPathIdentityContext,
+): string[] {
+  const failures: string[] = [];
+  for (const predicate of observation.nativePredicates ?? []) {
+    if (!nativeInputPredicateMatches(file, predicate, filesystem, identities)) {
+      failures.push(`native-${predicate.kind}-changed`);
+    }
+  }
+  if (observation.accessibleEntries !== undefined) {
+    const current = compilerAccessibleEntries(file, filesystem);
+    if (
+      JSON.stringify(current) !== JSON.stringify(observation.accessibleEntries)
+    ) {
+      failures.push("accessible-entries-changed");
+    }
+  }
+  const kind =
+    observation.fileExists !== undefined ||
+    observation.directoryExists !== undefined ||
+    observation.stat !== undefined ||
+    observation.readFile !== undefined
+      ? compilerStatKind(file, filesystem)
+      : undefined;
+  if (
+    observation.fileExists !== undefined &&
+    (kind === "file") !== observation.fileExists
+  ) {
+    failures.push("file-exists-changed");
+  }
+  if (
+    observation.directoryExists !== undefined &&
+    (kind === "directory") !== observation.directoryExists
+  ) {
+    failures.push("directory-exists-changed");
+  }
+  if (observation.stat !== undefined && kind !== observation.stat) {
+    failures.push("stat-changed");
+  }
+  if (observation.readFile !== undefined) {
+    const currentHash = graphInputReadHash(file, filesystem, kind);
+    if (
+      (observation.readFile.ok && currentHash !== observation.readFile.hash) ||
+      (!observation.readFile.ok && currentHash !== null)
+    ) {
+      failures.push("read-file-changed");
+    }
+  }
+  if (observation.realpath !== undefined) {
+    const currentRealpath = compilerInputRealpathObservation(file, filesystem);
+    if (
+      observation.realpath.ok !== currentRealpath.ok ||
+      (observation.realpath.ok &&
+        currentRealpath.ok &&
+        !sameHostInputRealpath(
+          observation.realpath.path,
+          currentRealpath.path,
+          identities,
+        ))
+    ) {
+      failures.push("realpath-changed");
+    }
+  }
+  return failures;
+}

package/src/core/transform/inputs/graphInputReadHash.ts

@@ -0,0 +1,33 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { compilerInputTextHash } from "./compilerInputTextHash";
+import { compilerStatKind } from "./compilerStatKind";
+
+/**
+ * Hash a successful compiler-style text read, or return null for a directory or
+ * failed read. UTF BOMs are removed; UTF-16 BOM input is decoded to UTF-8, with
+ * an incomplete trailing code unit omitted. The supplied kind must come from
+ * the same filesystem observation when a caller already has one.
+ *
+ * @evidence contracts/common.md#principled-implementation BOM handling reproduces compiler text normalization before SHA-256; directory classification rejects byte reads while stat-missing paths still attempt the compiler read predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One read adapter owns text decoding and optional kind reuse without substituting directory sentinel hashes for read results.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts BOM constants are encoding discriminants, not expected hashes; failed reads remain null instead of manufactured content.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes failure, BOM normalization, incomplete units and observed-kind provenance, with separated tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral reads use the supplied filesystem and encoding bytes; big-endian UTF-16 is copied before swapping so a shared Buffer is not mutated.
+ * @evidence contracts/performance.md#efficient-algorithms Native kind and byte observations pay their path/component resolution costs. Decoding and hashing scan B input bytes, with O(B) decoding space for UTF-16; UTF-8 and BOM stripping use shared slices, and an existing kind avoids a second stat. Directory kind avoids the byte read entirely.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This performs a fresh read within one observation; consumers own cross-request hash reuse and its metadata proof.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Buffers and hash state are call-local; no persistent descriptor, task or retained cache is acquired here.
+ */
+export function graphInputReadHash(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+  observedKind?: "directory" | "file" | "missing",
+): string | null {
+  const kind = observedKind ?? compilerStatKind(file, filesystem);
+  try {
+    if (kind === "directory") return null;
+    return compilerInputTextHash(filesystem.readFile(file));
+  } catch {
+    return null;
+  }
+}

package/src/core/transform/inputs/graphInputStateHash.ts

@@ -0,0 +1,29 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { hashText } from "../utils/hashText";
+import { compilerStatKind } from "./compilerStatKind";
+import { graphInputReadHash } from "./graphInputReadHash";
+
+/**
+ * Fingerprint compiler-normalized text, or the directory-kind sentinel when
+ * text cannot be read from a directory. Other failed reads return null. A
+ * directory hash records kind rather than a recursive listing of its contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The compiler read hash is preferred, and only an observed directory receives the shared directory marker; other unreadable kinds preserve null.
+ * @evidence contracts/common.md#clear-and-simple-design This combines the separate kind and text observers while keeping byte normalization with graphInputReadHash.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The sentinel is the declared directory state encoding, not a fabricated file hash or an assertion that directory membership stayed unchanged.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes content, directory kind and failed reads, using a separated acknowledgment block under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral stat and read observations share the supplied filesystem; directory status comes from native capability rather than separators or extensions.
+ * @evidence contracts/performance.md#efficient-algorithms One stat is passed into the text reader rather than repeated. Native observations retain their path/component resolution costs, decoded text hashing scans B bytes, and directory fallback hashes only the fixed kind marker without enumeration or a source read.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The operation returns a fresh state fingerprint; saved fingerprint equivalence is governed by generation proof owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned digest escapes; temporary buffers and hash state are owned by the read operation and no historical state is kept here.
+ */
+export function graphInputStateHash(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): string | null {
+  const kind = compilerStatKind(file, filesystem);
+  const readHash = graphInputReadHash(file, filesystem, kind);
+  if (readHash !== null) return readHash;
+  return kind === "directory" ? hashText("ttsc:host-input:directory\0") : null;
+}

package/src/core/transform/inputs/hostInputRealpath.ts

@@ -0,0 +1,31 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * Read the physical spelling selected by a host-input path. Resolution failure
+ * returns null; successful resolver spelling is returned unchanged so callers
+ * can apply their filesystem identity policy separately.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful physical resolution and failure remain distinct through string and null without applying the compiler's lexical fallback.
+ * @evidence contracts/common.md#clear-and-simple-design A single resolver call exposes target observation while normalization and identity comparison remain caller responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed native resolution is not replaced with guessed lexical identity or a known-input target.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states failure and unchanged-spelling semantics, using separated prose and tags under documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral target observation delegates to the supplied realpath capability, retaining native aliases and spelling without platform-wide case folding.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns before the function does; no handle is retained.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One supplied resolution processes the path's components and native link
+ *   targets; a single call does not imply constant work or bounded target text.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This observes one current target. Identity contexts and enclosing generation
+ *   validators own any sharing and its observation lifetime.
+ */
+export function hostInputRealpath(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): string | null {
+  try {
+    return filesystem.realpath(file);
+  } catch {
+    return null;
+  }
+}

package/src/core/transform/inputs/hostInputStateHash.ts

@@ -0,0 +1,34 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { hashText } from "../utils/hashText";
+
+/**
+ * Hash host-input raw bytes. If reading fails, an observed directory receives
+ * the shared directory marker and any other state returns null. Unlike graph
+ * reads, successful host bytes retain their BOM and original encoding.
+ *
+ * @evidence contracts/common.md#principled-implementation Byte hashing preserves the host-input contract independently of compiler text normalization, with following stat used only to classify a failed read.
+ * @evidence contracts/common.md#clear-and-simple-design The read-first path and directory fallback produce one optional fingerprint without mixing graph decoding into host state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual bytes determine successful hashes; the directory marker is a contract-defined kind value and unreadable files do not gain guessed contents.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes raw bytes, graph normalization and null fallback, with a blank tag separator following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral content comes from the supplied read capability with no line-ending or byte-order rewrite; following stat determines native directory fallback.
+ * @evidence contracts/performance.md#efficient-algorithms Successful reads require one O(B) byte hash and no stat; only failed reads request metadata, retaining a call-local Buffer proportional to file size.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each invocation observes current bytes; generation owners establish when a saved host hash can replace this read.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No cache, open descriptor or asynchronous task is retained by this synchronous fingerprint helper.
+ */
+export function hostInputStateHash(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): string | null {
+  try {
+    return hashText(filesystem.readFile(file));
+  } catch {
+    try {
+      return filesystem.stat(file).isDirectory()
+        ? hashText("ttsc:host-input:directory\0")
+        : null;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/core/transform/inputs/inputMetadataEvidence.ts

@@ -0,0 +1,94 @@
+import { stampSeparable } from "../clock/stampSeparable";
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import type { TtscInputMetadataEvidence } from "./TtscInputMetadataEvidence";
+
+/**
+ * Observe lexical-link and target metadata together with clock separability. An
+ * unavailable link target retains a missing-target signature and cannot
+ * authorize notification-only or metadata-only reuse. Unavailable lexical
+ * metadata returns undefined rather than representing a proven missing input.
+ *
+ * The caller must refresh the filesystem's device clock references before the
+ * content read whose reuse is being proven; this observer does not mint them.
+ *
+ * @evidence contracts/common.md#principled-implementation Link and target identity, size and stamps capture different mutation paths; a missing target stays distinct, and both observed stamps must pass the same-device strict clock-separability predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One metadata record carries signature, notification authority and separability as independent facts; clock acquisition and later content-reuse decisions remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Symlinks and multiply linked files cannot acquire blanket watcher authority, and broken-link state is not rewritten into a lexical-parent missing-path proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state unavailable-target behavior, unavailable metadata and clock-reference ordering; separated tags and distinct member comments follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral evidence reads actual bigint device, inode, link count and nanosecond stamps through the supplied following/nonfollowing capabilities rather than assuming OS-wide clock precision or watcher coverage.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One lstat suffices for ordinary inputs; only symbolic links need a target
+ *   stat. Fixed-field signatures and device lookups avoid file-byte reads while
+ *   native path resolution and bigint formatting retain component/digit costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This captures the evidence consumed by reuse coordinators; it neither stores completed content work nor decides equivalence across deliveries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The result holds primitive evidence only; device clock references belong to their filesystem owner and this function acquires no retained handle or task.
+ */
+export function inputMetadataEvidence(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): TtscInputMetadataEvidence | undefined {
+  try {
+    const link = filesystem.lstat(file);
+    let target = link;
+    if (link.isSymbolicLink()) {
+      try {
+        target = filesystem.statBigInt(file);
+      } catch {
+        // Keep a broken link in the existing-input manifest. Its own metadata
+        // stays stable while the target is missing, and the first successful
+        // stat after the target appears changes this signature. Treating it as
+        // a plain missing path would watch/list only the link's parent, which
+        // cannot observe a target created in another directory. It carries no
+        // readable bytes, so it never needs to be separable.
+        return {
+          signature: [
+            link.dev,
+            link.ino,
+            link.mode,
+            link.size,
+            link.mtimeNs,
+            link.ctimeNs,
+            "missing-target",
+          ].join(":"),
+          notificationAuthoritative: false,
+          separable: false,
+        };
+      }
+    }
+    return {
+      signature: [
+        link.dev,
+        link.ino,
+        link.nlink,
+        link.mode,
+        link.size,
+        link.mtimeNs,
+        link.ctimeNs,
+        target.dev,
+        target.ino,
+        target.nlink,
+        target.mode,
+        target.size,
+        target.mtimeNs,
+        target.ctimeNs,
+      ].join(":"),
+
+      // A write through a hardlink outside the watched tree changes this inode
+      // without notifying either the original directory or a watcher opened on
+      // the original path. Keep such files on metadata validation. Symlinks are
+      // likewise governed by the target path, outside the lexical observer.
+      notificationAuthoritative:
+        !link.isSymbolicLink() &&
+        !(link.isFile() && (link.nlink > 1n || target.nlink > 1n)),
+
+      // Both halves must be separable: a write remints the target's stamp, a
+      // link retarget the link's own, and either one hiding inside its recorded
+      // tick would evade the skipped content and realpath comparisons.
+      separable:
+        stampSeparable(filesystem, link) && stampSeparable(filesystem, target),
+    };
+  } catch {
+    return undefined;
+  }
+}

package/src/core/transform/inputs/inputMetadataSignature.ts

@@ -0,0 +1,28 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { inputMetadataEvidence } from "./inputMetadataEvidence";
+
+/**
+ * Extract the current lexical-path and target metadata signature, or undefined
+ * when metadata cannot be observed. Matching signatures alone do not authorize
+ * content reuse: the caller must also establish clock separability and
+ * coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional extraction preserves unavailable evidence instead of inventing a missing-path signature, while metadata semantics stay with inputMetadataEvidence.
+ * @evidence contracts/common.md#clear-and-simple-design This adapter exposes just the signature to callers that own their separate reuse conditions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Signature equality is not promoted into unconditional byte equality or silent-watcher proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose corrects the signature-only reuse implication and states unavailable metadata, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral metadata comes from the supplied following and nonfollowing capabilities; this wrapper adds no path or case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; it returns a string.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Delegated evidence performs one nonfollowing metadata read and at most one
+ *   target read, plus fixed-field bigint formatting and clock-device lookups.
+ *   Native path resolution and output digit lengths contribute real cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A signature is recomputed per proof; whether it may stand for content is decided by its callers against a fresh clock reference.
+ */
+export function inputMetadataSignature(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): string | undefined {
+  return inputMetadataEvidence(file, filesystem)?.signature;
+}

package/src/core/transform/inputs/matchesGraphInputObservation.ts

@@ -0,0 +1,31 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { graphInputObservationFailures } from "./graphInputObservationFailures";
+
+/**
+ * Report whether replay found no changed recorded compiler predicates.
+ * Unrecorded predicates impose no condition. The failure collector performs the
+ * complete observation even though this adapter returns only a boolean.
+ *
+ * @evidence contracts/common.md#principled-implementation An empty failure list means each explicitly recorded predicate matched its replay; absent predicates do not create extra obligations.
+ * @evidence contracts/common.md#clear-and-simple-design The boolean adapter uses the same failure collector as diagnostic callers instead of a competing predicate replay implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Acceptance is derived from actual replay failures, not a quiet watcher or a cached boolean independent of current observations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states absent-predicate and complete-replay semantics, using separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay receives the same filesystem operations and identity context as the observation owner; the adapter adds no native spelling assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms It returns whether graphInputObservationFailures found nothing, which replays only the recorded predicates.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A replay answers for the filesystem now; callers decide whether an earlier replay may be shared.
+ */
+export function matchesGraphInputObservation(
+  file: string,
+  observation: ITtscCompilerTransformation.IInputObservation,
+  filesystem: TtscTransformFilesystemOperations,
+  identities: FilesystemPathIdentityContext,
+): boolean {
+  return (
+    graphInputObservationFailures(file, observation, filesystem, identities)
+      .length === 0
+  );
+}

package/src/core/transform/inputs/missingPathProbe.ts

@@ -0,0 +1,66 @@
+import path from "node:path";
+
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * Choose an ancestor candidate for a path already observed as missing. The
+ * nearest existing directory supplies a child name to check. An existing
+ * nondirectory ancestor is returned as a blocker; metadata must also prove that
+ * blocker unchanged. The caller must obtain native existence evidence for the
+ * returned child; a directory listing alone cannot exclude every native alias.
+ *
+ * Root exhaustion returns a candidate even when root stat failed, so this
+ * selection alone never proves absence. Path parsing follows an explicit
+ * filesystem.platform override, or the running Node host when none is
+ * supplied.
+ *
+ * @evidence contracts/common.md#principled-implementation Ancestor traversal stops at a directory, a nondirectory blocker or root; the returned candidate and optional blocker let consumers obtain the separate observations required for an absence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One upward walk selects the observation boundary without acquiring watchers or asserting that selection itself certifies a missing path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed ancestor stats continue to parents; root termination is a traversal boundary rather than invented successful accessibility or an unconditional absence result.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain blocker evidence, caller native-proof responsibility, root failure and explicit versus default path dialect; member comments and tags remain visibly separated following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral traversal selects Node's Windows or POSIX path implementation from the observing filesystem's override, falling back to the host platform, and applies that same dialect to resolution, parent traversal and child-name extraction without inferring case policy.
+ * @evidence contracts/performance.md#efficient-algorithms At most D ancestor stats are performed for D path components; parent string operations can cost O(D times path length), and no subtree walk or content read is performed.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This selects one current probe boundary; observers own reuse of candidate observations and blocker metadata across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The walk retains only its current path and returned candidate; native watchers and saved absence proofs belong to consumers.
+ */
+export function missingPathProbe(
+  file: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): {
+  /** Existing nondirectory ancestor whose metadata must remain unchanged. */
+  blocker?: string;
+
+  /**
+   * Directory containing the candidate; exhaustion does not prove
+   * accessibility.
+   */
+  directory: string;
+
+  /** Original child spelling whose native absence the caller must establish. */
+  name: string;
+} {
+  const pathApi =
+    (filesystem.platform ?? process.platform) === "win32"
+      ? path.win32
+      : path.posix;
+  let child = pathApi.resolve(file);
+  for (;;) {
+    const directory = pathApi.dirname(child);
+    try {
+      const stats = filesystem.stat(directory);
+      if (stats.isDirectory()) {
+        return { directory, name: pathApi.basename(child) };
+      }
+      return {
+        blocker: directory,
+        directory: pathApi.dirname(directory),
+        name: pathApi.basename(directory),
+      };
+    } catch {}
+    if (directory === child) {
+      return { directory, name: pathApi.basename(child) };
+    }
+    child = directory;
+  }
+}