ttsc 0.30.4 → 0.31.1

package/src/internal/SpawnSyncOutputFiles.ts

@@ -0,0 +1,29 @@
+/**
+ * The files a synchronous child's standard output and error are captured into.
+ *
+ * {@link spawnSyncResilient} needs them to retry a spawn that failed with
+ * `EBADF` in the supported descriptor-limit failure class. The retry runs
+ * through a fresh broker that opens these same files itself; numeric descriptor
+ * height and retry success are not established by this path pair. The caller
+ * reads the output from one place whichever path produced it.
+ *
+ * The two destinations may name the same file to combine diagnostics. The
+ * caller owns the capture files and their cleanup. These are native file paths,
+ * not open descriptors or shell redirection expressions.
+ *
+ * @evidence contracts/common.md#principled-implementation Named stdout/stderr destinations carry actual output across ordinary and broker launches; equal paths deliberately combine the streams. The pair denotes caller-owned capture destinations rather than ownership of live descriptors.
+ * @evidence contracts/common.md#clear-and-simple-design A two-path container supplies only the output destinations needed by the broker while spawn options and capture-file lifecycle remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The broker writes the actual child streams into caller-selected files; the type provides no synthetic output or special-case expected command result.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain retry use, common read destinations, caller cleanup and path-versus-descriptor meaning; member and acknowledgment spacing follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native output paths are passed to supported filesystem operations rather than encoded as shell redirection; the launch owner decides whether the POSIX descriptor broker is applicable.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface SpawnSyncOutputFiles {
+  /** File receiving the child's standard error. */
+  stderr: string;
+
+  /** File receiving the child's standard output. */
+  stdout: string;
+}

package/src/internal/cacheEntryExists.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+
+/**
+ * Whether a cache entry exists, including a dangling symlink or junction.
+ *
+ * @evidence contracts/common.md#principled-implementation lstat observes the terminal entry without following a dangling link; only missing entry or missing ancestor means false, while other filesystem errors propagate.
+ * @evidence contracts/common.md#clear-and-simple-design One native observation and one missing-error branch expose existence without duplicating physical identity or cleanup policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Permission and I/O failures are not converted into assumed absence; no foreign filesystem method is replaced.
+ * @evidence contracts/common.md#meaningful-documentation Native wording explicitly includes dangling aliases, the nonobvious distinction needed by cleanup callers, and tags occupy their own block.
+ * @evidence contracts/portability.md#os-neutral-implementation Node lstat carries native terminal-link semantics and normalized missing errno rather than inferring existence from path spelling or OS names.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources cacheEntryExists acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms One lstat checks the terminal entry without following its link target; native path conversion, ancestor lookup and filesystem observation costs depend on the supplied path and filesystem rather than the fixed local errno comparisons. No directory enumeration or content read is requested here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate owns no cross-request coordination; cleanup consumers request a current mutable entry observation rather than reuse historical existence as deletion authority.
+ */
+export function cacheEntryExists(location: string): boolean {
+  try {
+    fs.lstatSync(location);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return false;
+    throw error;
+  }
+}

package/src/internal/createCanonicalTempDirectory.ts

@@ -2,33 +2,44 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-export interface CanonicalTempDirectoryOperations {
-  lstat(location: string): { isDirectory(): boolean };
-  mkdtemp(prefix: string): string;
-  realpath(location: string): string;
-}
-
-const FILESYSTEM_OPERATIONS: CanonicalTempDirectoryOperations = {
-  lstat: fs.lstatSync,
-  mkdtemp: fs.mkdtempSync,
-  realpath: fs.realpathSync.native,
-};
+import type { CanonicalTempDirectoryOperations } from "./CanonicalTempDirectoryOperations";
 
 /**
- * Create a unique temporary directory under a frozen physical parent.
+ * Create a unique temporary directory under an observed physical parent.
+ *
+ * Resolving the parent before creation removes the caller's TEMP/TMPDIR alias
+ * from the returned path. The postflight accepts a directory only when its
+ * physical path is a direct child of that parent. Prefixes must name one native
+ * basename and cannot be the navigation components `.` or `..`.
+ *
+ * A failed postflight leaves the allocated entry untouched because its safe
+ * ownership was not established. These observations hold no directory handle
+ * and are not atomic with later use: they do not prevent another actor from
+ * changing the physical namespace after validation. The caller owns cleanup of
+ * an accepted directory and must preserve that boundary during its use.
  *
- * The parent is resolved before creation so retargeting the caller's
- * TEMP/TMPDIR alias cannot redirect later writes or recursive cleanup. The
- * postflight accepts only a real directory that resolves to a direct child of
- * that same parent; a rejected child is deliberately left untouched because no
- * safe ownership identity was established.
+ * @evidence contracts/common.md#principled-implementation Native realpath, unique allocation and link-preserving stat establish the observed physical parent and accepted direct child; reserved navigation prefixes are rejected before allocation rather than creating an entry outside that parent.
+ * @evidence contracts/common.md#clear-and-simple-design One creator owns preflight, allocation and postflight through three filesystem primitives; callers receive an accepted physical path and own subsequent use and cleanup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed observations propagate without substituting a guessed path or recursively deleting an entry whose ownership is unproven; injected primitives belong to this boundary rather than replacing foreign globals.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain prefix restrictions, alias removal, postflight rejection, possible unclaimed allocation and the lack of atomic or held-directory protection under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation node:path assembles and validates native names, os.tmpdir supplies the default parent, and native realpath expands aliases; no fixed temporary root, manual separator replacement or OS-wide case folding determines containment.
+ * @evidence contracts/performance.md#efficient-algorithms Prefix checks and native path assembly scan path text; a fixed number of realpath/stat observations and one unique allocation delegate alias resolution and filesystem lookup work. No explicit directory enumeration occurs here, but the fixed call count does not bound native lookup, alias depth or allocation costs. Temporary path strings grow with the observed native spellings.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call requires a unique allocation and current parent/child observations; reusing an earlier directory or postflight would violate that ownership boundary.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources An accepted directory transfers to its caller for cleanup, and this function retains no registry or open handle. A rejected or unobservable postflight can leave an allocation because no safe cleanup target is established; that failure is propagated rather than claiming all allocations were reclaimed.
  */
 export function createCanonicalTempDirectory(
   prefix: string,
   parent: string = os.tmpdir(),
   operations: CanonicalTempDirectoryOperations = FILESYSTEM_OPERATIONS,
 ): string {
-  if (prefix.length === 0 || path.basename(prefix) !== prefix) {
+  if (
+    prefix.length === 0 ||
+    prefix === "." ||
+    prefix === ".." ||
+    path.basename(prefix) !== prefix
+  ) {
     throw new TypeError("ttsc: temporary directory prefix must be a basename");
   }
   const physicalParent = operations.realpath(path.resolve(parent));
@@ -51,3 +62,9 @@ export function createCanonicalTempDirectory(
   }
   return physicalDirectory;
 }
+
+const FILESYSTEM_OPERATIONS: CanonicalTempDirectoryOperations = {
+  lstat: fs.lstatSync,
+  mkdtemp: fs.mkdtempSync,
+  realpath: fs.realpathSync.native,
+};

package/src/internal/isContendedCandidateRename.ts

@@ -0,0 +1,35 @@
+/**
+ * Whether a lock-candidate rename refusal is classified as contention by the
+ * publication policy used by both build-lock protocols.
+ *
+ * The candidate was just created in the destination's directory, so that
+ * directory accepted that allocation. Windows access refusals can occur when
+ * another process holds or is deleting the destination. A holder that releases
+ * between the failed rename and a later look at the destination leaves nothing
+ * to see, so asking whether the destination exists would take the lost race for
+ * a permission failure. The policy therefore classifies the error code without
+ * that lookup; allocation does not prove that later source/destination-specific
+ * permissions permit renaming, nor does the code identify a peer. The input
+ * must be a native error object or errno record; nullish thrown values are not
+ * a supported record for this classifier.
+ *
+ * @param error What the rename threw.
+ * @returns Whether the refusal is eligible for the caller's contention path.
+ * @evidence contracts/common.md#principled-implementation The protocol's accepted codes include access refusals under the just-created candidate premise. A later destination lookup cannot identify a disappeared race, and the code itself does not prove that another process caused the refusal.
+ * @evidence contracts/common.md#clear-and-simple-design One classifier serves the two lock protocols while each caller owns candidate creation, polling and its retry deadline.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The access-error allowance is tied to the real lock-publication premise, not a blanket suppression of unrelated permissions or expected fixture outcomes.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the candidate ownership premise and disappearing-destination race, making this narrow classifier's permitted use visible.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared protocol classifies EEXIST/ENOTEMPTY and Windows-style access refusal codes through native errno representation. Successful candidate allocation is a sampled premise, not an OS-wide permission guarantee or proof of a peer cause.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isContendedCandidateRename acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms One native error-code read and at most four exact comparisons classify the supplied record without filesystem lookup or text traversal; supported native errno records provide that property, while arbitrary accessor behavior is not a bounded native observation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate coordinates no completed or in-flight work across requests; it classifies the current supplied refusal and leaves polling and admission state with the protocols.
+ */
+export function isContendedCandidateRename(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  return (
+    code === "EEXIST" ||
+    code === "ENOTEMPTY" ||
+    code === "EACCES" ||
+    code === "EPERM"
+  );
+}

package/src/internal/isSpawnSyncFdExhaustion.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether a spawn error reports EBADF, including message-only native errors.
+ *
+ * The caller decides whether its platform and stdio mode permit a descriptor
+ * retry; EBADF alone does not prove that every failure was descriptor height.
+ *
+ * @evidence contracts/common.md#principled-implementation The code or message reports the native EBADF class; this predicate does not pretend to diagnose the descriptor's exact failure mechanism.
+ * @evidence contracts/common.md#clear-and-simple-design Error classification is separate from the caller's platform gate and broker selection, so one predicate serves both launch owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Message matching supports native errors without a code property; it does not replace foreign errors or convert command failure into success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state both the accepted error representations and the limitation of EBADF as a cause diagnosis, with a separate tag block.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isSpawnSyncFdExhaustion acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms A matching code short-circuits; otherwise includes scans the supplied message for a fixed marker. Message length drives worst-case text work and has no quota here, despite a fixed number of source expressions.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work isSpawnSyncFdExhaustion computes one result per call, so there is no repeated work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation isSpawnSyncFdExhaustion computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export function isSpawnSyncFdExhaustion(error: Error | undefined): boolean {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  return code === "EBADF" || error?.message.includes("EBADF") === true;
+}

package/src/internal/javascriptRuntimeCapabilities.ts

@@ -0,0 +1,166 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { captureProcessOutput } from "../compiler/internal/captureProcessOutput";
+import { SidecarEnvironment } from "../compiler/internal/sharedHost/SidecarEnvironment";
+import { E2ETrace } from "./E2ETrace";
+import type { IJavaScriptRuntimeCapabilities } from "./IJavaScriptRuntimeCapabilities";
+import { OwnedSynchronousProcess } from "./OwnedSynchronousProcess";
+import { isSpawnSyncFdExhaustion } from "./isSpawnSyncFdExhaustion";
+import { runtimeExecutableIdentity } from "./runtimeExecutableIdentity";
+import { spawnSyncWithLowDescriptors } from "./spawnSyncWithLowDescriptors";
+
+/**
+ * Probe an interpreter instead of inferring its identity from the host.
+ *
+ * Successful absolute candidates can be reused only while their actual bytes,
+ * lexical link and physical target agree. Preloaded, relative and wrapper
+ * candidates are probed anew because those inputs can select mutable behavior.
+ * Cache-ineligible candidates do not acquire executable proofs used only by
+ * cache lookup and publication.
+ *
+ * @evidence contracts/common.md#principled-implementation A child reports its own feature availability and executable; byte-aware before/after identity and same-executable proof authorize reuse only for a stable absolute runtime without NODE_OPTIONS preload authority.
+ * @evidence contracts/common.md#clear-and-simple-design One probe owner coordinates identity, spawning and parsing; the shared fingerprint helper owns file-content proof and the low-descriptor helper owns the POSIX launch distinction.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Feature availability comes from the actual interpreter rather than its name; descriptor fallback handles a supported kernel constraint and failures produce unsupported capabilities, not fabricated success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain measured capabilities, reuse restrictions and freshness, with comments separating platform launch and cache permission from tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared environment merge and lookup apply native name identity to caller precedence and NODE_OPTIONS preload authority, including Windows aliases; Node spawn receives an executable and argv without shell syntax, and only POSIX descriptor exhaustion uses the isolated broker.
+ * @evidence contracts/performance.md#efficient-algorithms Environment merge/name handling first decides cache eligibility. Eligible hits read B executable bytes; eligible misses acquire before/after content proofs around the actual probe. Ineligible calls retain the fresh child without reading executable bytes solely for the forbidden cache. Probe spawning/parsing, a possible descriptor-exhaustion retry and capture-file reads add text/environment/native lookup costs and transient output storage; this adapter sets no explicit byte quota.
+ * @evidence contracts/performance.md#reuse-equivalent-work Stable absolute candidates that report their own executable share measured capability results, including false feature flags; changed executable bytes, link/target identity, preload options or wrapper identity require another probe, while failed probes without executable identity are not reused.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous probe owns child completion and fallback captures; finally attempts capture close/removal, whose helper suppresses cleanup failures, so native/file release is unconfirmed on failure. Capability entries retain absolute spellings and path/identity text with no eviction quota; failed identity validation can remove an entry. Returned capability copies transfer to callers.
+ */
+export function javascriptRuntimeCapabilities(
+  runtime: string,
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+): IJavaScriptRuntimeCapabilities {
+  const effectiveEnv = SidecarEnvironment.merge(process.env, env);
+  const cacheKey = runtimeCapabilityCacheKey(runtime, effectiveEnv);
+  const beforeIdentity =
+    cacheKey === undefined ? undefined : runtimeExecutableIdentity(runtime);
+  if (cacheKey !== undefined && beforeIdentity !== undefined) {
+    const cached = runtimeCapabilityCache.get(cacheKey);
+    if (cached?.identity === beforeIdentity) return { ...cached.capabilities };
+    runtimeCapabilityCache.delete(cacheKey);
+  }
+  const args = [
+    "-e",
+    `const Module = require("node:module"); process.stdout.write(JSON.stringify({ bun: typeof globalThis.Bun === "object", executable: process.execPath, registerHooks: typeof Module.registerHooks === "function" }));`,
+  ];
+  const options = {
+    cwd,
+    encoding: "utf8" as const,
+    env: effectiveEnv,
+    timeout: 30_000,
+    windowsHide: true,
+  };
+  let result = E2ETrace.synchronous(
+    runtime,
+    args,
+    options,
+    "runtime-capability-probe",
+    () =>
+      OwnedSynchronousProcess.launch<string>(runtime, args, options) ??
+      childProcess.spawnSync(runtime, args, options),
+  );
+  if (process.platform !== "win32" && isSpawnSyncFdExhaustion(result.error)) {
+    const capture = captureProcessOutput();
+    try {
+      const retried = spawnSyncWithLowDescriptors(runtime, args, options, {
+        stderr: capture.stderrPath,
+        stdout: capture.stdoutPath,
+      });
+      const stdout = capture.read("stdout", "utf8") as string;
+      const stderr = capture.read("stderr", "utf8") as string;
+      result = {
+        ...retried,
+        output: [null, stdout, stderr],
+        stderr,
+        stdout,
+      };
+    } finally {
+      capture.dispose();
+    }
+  }
+  let capabilities: IJavaScriptRuntimeCapabilities = {
+    bun: false,
+    registerHooks: false,
+  };
+  if (result.status === 0) {
+    try {
+      const parsed = JSON.parse(
+        result.stdout,
+      ) as Partial<IJavaScriptRuntimeCapabilities>;
+      capabilities = {
+        bun: parsed.bun === true,
+        ...(typeof parsed.executable === "string" &&
+        path.isAbsolute(parsed.executable)
+          ? { executable: path.resolve(parsed.executable) }
+          : {}),
+        registerHooks: parsed.registerHooks === true,
+      };
+    } catch {
+      // An incompatible executable is not a Node runtime candidate.
+    }
+  }
+  // Cache successful absolute candidates only when the child reports that same
+  // executable and both its lexical link and physical target retain the same
+  // filesystem and actual content identity. Relative/bare commands and wrappers can resolve
+  // differently by cwd/PATH/environment, failed probes without an executable
+  // identity can become valid later, and NODE_OPTIONS can load mutable user
+  // code, so none of those states are memoized. A successful probe can report
+  // false for either feature and still be reused under the executable proof.
+  // This removes a process spawn from the common path without
+  // authorizing a replaced or redirected runtime in a long-lived host.
+  const afterIdentity =
+    cacheKey === undefined ? undefined : runtimeExecutableIdentity(runtime);
+  if (
+    cacheKey !== undefined &&
+    capabilities.executable !== undefined &&
+    beforeIdentity !== undefined &&
+    beforeIdentity === afterIdentity &&
+    sameRuntimeExecutable(runtime, capabilities.executable)
+  ) {
+    runtimeCapabilityCache.set(cacheKey, {
+      capabilities: { ...capabilities },
+      identity: afterIdentity,
+    });
+  }
+  return capabilities;
+}
+
+type RuntimeCapabilityCacheEntry = {
+  capabilities: IJavaScriptRuntimeCapabilities;
+  identity: string;
+};
+
+const runtimeCapabilityCache = new Map<string, RuntimeCapabilityCacheEntry>();
+
+/** True when a probe ran the candidate itself rather than a mutable wrapper. */
+function sameRuntimeExecutable(candidate: string, executable: string): boolean {
+  try {
+    const candidateStats = fs.statSync(candidate, { bigint: true });
+    const executableStats = fs.statSync(executable, { bigint: true });
+    return (
+      (candidateStats.ino !== 0n &&
+        candidateStats.dev === executableStats.dev &&
+        candidateStats.ino === executableStats.ino) ||
+      fs.realpathSync.native(candidate) === fs.realpathSync.native(executable)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Stable cache key only for an absolute runtime with no preload authority. */
+function runtimeCapabilityCacheKey(
+  runtime: string,
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  if (
+    !path.isAbsolute(runtime) ||
+    SidecarEnvironment.read(env, "NODE_OPTIONS")?.trim()
+  )
+    return undefined;
+  return path.resolve(runtime);
+}

package/src/internal/nativeBinary.ts

@@ -0,0 +1,11 @@
+/**
+ * Public entry of `ttsc/binary`.
+ *
+ * The rules that find ttsc's platform binary (an absolute `TTSC_BINARY`, the
+ * per-platform package, then the repository's own dev layout) are ttsc's alone.
+ * A tool host that runs one of that binary's helper commands, as
+ * `@ttsc/unplugin` runs its native watch helpers, imports them from here, so
+ * the helper always comes from the binary ttsc itself uses and no consumer
+ * carries a copy of the rules.
+ */
+export { resolveBinary } from "../compiler/internal/resolveBinary";

package/src/internal/parseWindowsDirectoryCaseSensitivity.ts

@@ -0,0 +1,50 @@
+/**
+ * Interpret fsutil's case-sensitivity query without assuming a display
+ * language.
+ *
+ * English messages identify the state in the final field of the complete
+ * native message. The echoed directory path supplies no status evidence. For
+ * every other locale, the volume-root query supplies the raw localized suffix
+ * for the ordinary disabled state. A target with that suffix is insensitive;
+ * a different successful message is the enabled state.
+ *
+ * Inputs must be successful fsutil query responses. The opaque comparison
+ * assumes the volume-root response represents the ordinary disabled state;
+ * unrecognized or truncated framing returns no answer.
+ *
+ * @evidence contracts/common.md#principled-implementation Capturing the final status field of the complete native English message separates status authority from echoed path data. Other locales compare the successful response suffix with a known disabled volume-root response, under the query framing and root-state premises.
+ * @evidence contracts/common.md#clear-and-simple-design One complete-message recognition precedes one raw-byte fallback, avoiding a separate locale dictionary or unreliable console-code-page conversion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The native English message grammar supplies status framing without path-word exceptions or a locale dictionary. Absent baseline framing remains undefined, while the successful-query premise is explicit rather than applied to arbitrary output.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe locale handling, successful-query inputs and the disabled-root assumption, with the acknowledgment block separated.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows-specific query interpretation remains isolated; comparing native output bytes avoids assuming UTF-8 decoding preserves localized fsutil suffixes, while volume-root framing remains a stated boundary assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Decoded text, encoded root bytes and views of the supplied buffers are invocation-local; returning a boolean or undefined retains none of them and acquires no native handle or historical cache.
+ * @evidence contracts/performance.md#efficient-algorithms UTF-8 decoding and trailing-whitespace trimming precede one anchored native-message scan. The fallback encodes the root, searches the volume buffer for those bytes and compares one suffix view. Work and temporary storage depend on response/root lengths and byte-search implementation; inputs have no size cap here, and no locale dictionary or recursive lookup is built.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This byte interpreter owns no native-query producer or mutable directory observations to coordinate. The caller supplies current query bytes and any reusable disabled-root baseline; the parser adds no authority cache.
+ */
+export function parseWindowsDirectoryCaseSensitivity(
+  directoryOutput: Buffer,
+  volumeOutput: Buffer | undefined,
+  volumeRoot: string,
+): boolean | undefined {
+  const text = directoryOutput.toString("utf8");
+  const english =
+    /^Case sensitive attribute on directory [^\r\n]+ is (enabled|disabled)\.$/iu.exec(
+      text.trimEnd(),
+    );
+  if (english !== null) return english[1]!.toLowerCase() === "enabled";
+  if (volumeOutput === undefined) return undefined;
+
+  const encodedRoot = Buffer.from(volumeRoot, "utf8");
+  const rootOffset = volumeOutput.lastIndexOf(encodedRoot);
+  if (rootOffset === -1) return undefined;
+  const disabledSuffix = volumeOutput.subarray(rootOffset + encodedRoot.length);
+  if (
+    disabledSuffix.length === 0 ||
+    directoryOutput.length < disabledSuffix.length
+  ) {
+    return undefined;
+  }
+  return !directoryOutput
+    .subarray(directoryOutput.length - disabledSuffix.length)
+    .equals(disabledSuffix);
+}

package/src/internal/pathIdentity/FilesystemPathIdentity.ts

@@ -0,0 +1,44 @@
+/**
+ * One path answered by the filesystem, in two forms that answer different
+ * questions.
+ *
+ * `path` is the spelling to hand back to the filesystem or to a user: the
+ * observed physical prefix (reparse points and Windows 8.3 names expanded when
+ * resolved) followed by an unresolved suffix canonicalized according to the
+ * resolved ancestor's measured ASCII case policy. In strict resolution the
+ * suffix represents missing path structure; best-effort resolution can also
+ * retain unreadable existing entries. If no prefix resolves, the path remains
+ * lexically normalized. `key` is the spelling to compare under those
+ * observations; unresolved names are locations, not proof that an entry exists.
+ * Unknown case policy and unproved Unicode equivalence retain distinct keys, so
+ * key inequality cannot prove physical distinction.
+ *
+ * Produced by {@link FilesystemPathIdentityContext.resolve}.
+ *
+ * @evidence contracts/common.md#principled-implementation The pair separates comparison spelling from the path usable by native consumers. Resolved prefixes use native physical observations, and unresolved ASCII suffixes fold only under observed insensitivity; best-effort mode does not certify that every existing entry resolved. Unknown and Unicode variants may retain different keys without proof of distinct physical entries.
+ * @evidence contracts/common.md#clear-and-simple-design Two named fields expose the distinction without storing a second independently computed identity policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The representation records native resolution outcomes instead of fixture spellings or global case-folding assertions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain comparison versus returned spelling, missing-suffix canonicalization and member use; documented properties are separated and carry no acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Existing native aliases and Windows volume-root spelling are represented separately from missing-suffix case policy; unknown directory policy preserves exact spellings and cannot authorize treating case variants as equivalent.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type FilesystemPathIdentity = {
+  /**
+   * Comparison key under this transaction's filesystem observations. Windows
+   * volume roots use native root grammar. Unresolved ASCII letters fold only
+   * under measured insensitivity; unknown and non-ASCII variants can retain
+   * distinct keys even when a later native observation would establish an
+   * alias.
+   */
+  key: string;
+
+  /**
+   * Observed physical prefix followed by the unresolved suffix, or lexical
+   * spelling if no prefix resolved. Use it to open, watch, or print the
+   * location; best-effort output is not proof that every existing segment was
+   * resolved.
+   */
+  path: string;
+};