ttsc 0.30.4 → 0.31.1

package/src/TtscService.ts

@@ -1,58 +1,69 @@
 import path from "node:path";
 
-import type { ResidentTransformProcess } from "./compiler/internal/residentTransformProcess";
+import type { TtscServiceRequestOptions } from "./TtscServiceRequestOptions";
+import type { ResidentTransformProcess } from "./compiler/internal/ResidentTransformProcess";
 import { startResidentTransform } from "./compiler/internal/startResidentTransform";
+import { CompilerContextSnapshot } from "./internal/CompilerContextSnapshot";
+import { resolvePhysicalPath } from "./internal/pathIdentity/resolvePhysicalPath";
 import type { ITtscCompilerContext } from "./structures/ITtscCompilerContext";
 
-/** Per-call controls for a resident transform or update request. */
-export interface TtscServiceRequestOptions {
-  /** Abort this call before it receives a reply. */
-  signal?: AbortSignal;
-}
-
 /**
  * Resident, incremental transform service for the `ttsc` TypeScript-Go
  * pipeline.
  *
  * Where {@link TtscCompiler.transform} spawns a fresh process and recompiles the
- * whole project on every call, `TtscService` keeps one long-lived host warm: it
- * compiles the project once and then answers per-file transform requests from
- * that warm program. A single service instance transforms many files (a watch
- * server, an editor session, a codegen tool) while paying the project compile
- * once instead of once per file. Sharing one host across separate worker
- * processes (a Metro worker pool) is tracked in samchon/ttsc#255.
+ * whole project on every call, `TtscService` shares one long-lived host across
+ * per-file transform and update requests. The serve producer owns initial
+ * compilation, transformed-text reuse and later generations; custom executable
+ * hosts must honor that protocol rather than the wrapper proving their cache
+ * behavior. One service instance can address many files. One host serves one
+ * process; sharing it across separate worker processes (a Metro worker pool) is
+ * not provided.
  *
  * The shape mirrors a legacy TypeScript `LanguageService`: construct it against
  * a project context, ask it to transform individual files, and dispose it when
  * done. Construction is synchronous (it launches the host); the host compiles
- * in the background, so the first {@link transformFile} resolves once that
- * compile lands.
+ * in the background; the first {@link transformFile} waits for its host reply
+ * and can reject on startup or protocol failure.
  *
- * Resident mode runs through the linked-plugin shared host, so the project must
+ * Resident mode runs through a selected shared host, so the project must
  * declare at least one transform-stage plugin; the constructor throws
  * otherwise. It does not run check-stage plugins (unlike
- * {@link TtscCompiler.transform}); only the program's own type-checking gates an
- * {@link updateFile}.
+ * {@link TtscCompiler.transform}); program loading and transform-stage plugin
+ * success gate an {@link updateFile} in the utility producer. A selected
+ * executable plugin host must implement the resident serve protocol; the
+ * generated linked-plugin utility host supplies that protocol itself.
+ *
+ * @evidence contracts/common.md#principled-implementation One resident host owns committed transform state and validated transform/update replies; fixed context selectors and captured JSON configuration preserve construction authority while later requests address the selected project's logical spelling. The utility producer retains printed text after closing each loaded Program.
+ * @evidence contracts/common.md#clear-and-simple-design The class exposes transform, update and disposal around one resident client; private path adaptation handles the physical-versus-program spelling distinction without duplicating client protocol state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The resident protocol is an actual required host capability, not an assumed executable property; failed compile/protocol replies remain failures rather than fabricated absent files or successful updates.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain resident lifetime, transform/check-stage scope, custom serve requirement and captured configuration; method comments distinguish absence, rejected builds and disposal consequences.
+ * @evidence contracts/portability.md#os-neutral-implementation Native physical resolution and path-relative containment map aliases back to retained Program spelling, including Windows 8.3 roots; native host spawning and environment authority stay with the resident client owner.
+ * @evidence contracts/performance.md#efficient-algorithms Construction delegates configuration/plugin discovery and native startup; requests delegate host processing, serialization and reply parsing. Best-effort path adaptation traverses native ancestors/text and can perform Windows case-query work; returned text and submitted content add data costs without a wrapper compile.
+ * @evidence contracts/performance.md#reuse-equivalent-work The same service shares one selected serve producer; current transformed output and ordered generation replacement are producer responsibilities, not a custom-host cache guarantee authenticated by this wrapper.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One resident client retains its child and pending requests without a queue or active-duration cap. Disposal or terminal failure rejects pending work, closes pipes and attempts signals; void disposal neither awaits child close nor guarantees OS termination or host memory release.
  */
 export class TtscService {
   private readonly resident: ResidentTransformProcess;
   private readonly projectRoot: string;
+  private readonly physicalProjectRoot: string;
 
   /**
    * Create a service bound to the given project context and launch its resident
    * host. The context is the same shape {@link TtscCompiler} accepts; it is not
    * replaceable per call.
+   *
+   * Plugin JSON conversion, including custom `toJSON`, is captured once before
+   * launching the host. Unsupported cyclic or BigInt payloads fail here.
    */
   public constructor(context: ITtscCompilerContext = {}) {
-    const started = startResidentTransform({
-      ...context,
-      env: context.env ? { ...context.env } : undefined,
-      plugins: Array.isArray(context.plugins)
-        ? [...context.plugins]
-        : context.plugins,
-    });
+    const started = startResidentTransform(
+      CompilerContextSnapshot.clone(context),
+    );
     this.resident = started.process;
+    // The Program keeps this spelling, including a Windows 8.3 component.
     this.projectRoot = started.projectRoot;
+    this.physicalProjectRoot = resolvePhysicalPath(started.projectRoot);
   }
 
   /**
@@ -62,6 +73,15 @@ export class TtscService {
    *
    * Rejects when the resident host failed to compile the project; the rejection
    * carries the host's diagnostics so callers can surface a real build error.
+   *
+   * @evidence contracts/common.md#principled-implementation Only a validated found=false reply means absence; found replies supply transformed text, while compilation or protocol errors reject instead of collapsing into undefined.
+   * @evidence contracts/common.md#clear-and-simple-design One resident request uses private path adaptation and returns the reply's text without a second file lookup or compilation policy.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The client validates the real protocol shape; this method neither fabricates text nor hides host failure as an excluded source.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain project-relative filenames, absent-program-file meaning and diagnostic rejection, with prose separated from tags.
+   * @evidence contracts/portability.md#os-neutral-implementation Best-effort native physical resolution maps contained aliases to the retained logical root spelling; fallback paths are not a continuing identity certificate. fileName is structured request data rather than shell text.
+   * @evidence contracts/performance.md#efficient-algorithms One path adaptation and resident request delegate ancestor/case observations, request serialization, host lookup and reply parsing; path and response text contribute cost. The wrapper itself launches no new compile.
+   * @evidence contracts/performance.md#reuse-equivalent-work Resident program output is shared until an update changes its generation; file lookup uses that current program rather than an independent stale response cache.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources One pending request and returned text belong to this call; the client owns cancellation/terminal settlement with no implicit per-call deadline. Queued cancellation can retire sibling calls; disposal attempts signals without a child-close join.
    */
   public async transformFile(
     fileName: string,
@@ -85,8 +105,21 @@ export class TtscService {
    * Apply new in-memory content for one file and re-transform the project, so a
    * subsequent {@link transformFile} reflects the edit without restarting the
    * host. Returns whether the re-transform succeeded; `false` means the edit
-   * did not compile and the previous transform is still in effect. A relative
+   * failed the host's rebuild and the previous transform is still in effect. In
+   * the utility producer this includes load/type-check or transform-plugin
+   * failure; custom hosts must honor the same update protocol. A relative
    * `fileName` is resolved against the project root.
+   *
+   * @evidence contracts/common.md#principled-implementation A validated updated boolean reports the producer's edit result; the utility host rolls failed rebuilds back to its prior overlay and transformed text. Custom host compliance is a protocol requirement, not compilation independently observed by this wrapper.
+   * @evidence contracts/common.md#clear-and-simple-design The method sends one content/path update through the resident client and leaves generation replacement and reply validation to their owners.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The host's real updated reply determines the result; protocol failure rejects instead of being converted into false or an invented successful edit.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes rejected builds, false update results and subsequent transform visibility, with separated acknowledgments.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path adaptation supplies the resident Program spelling while content travels as structured text, without shell interpretation or platform-specific separators in protocol logic.
+   * @evidence contracts/performance.md#efficient-algorithms One content update delegates the producer's re-transform strategy; this wrapper adds best-effort ancestor/case/path adaptation, content serialization and reply parsing. Returned boolean selection has fixed shape, but native/path/content/host work is not constant.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Updating resident source changes program state and cannot be shared solely because request text matches a previous effectful call.
+   *
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The pending request retains serialized content and callbacks until client settlement; accepted generations belong to the producer. Disposal or terminal failure clears pending work and attempts signals without proving child termination; queued cancellation also retires sibling requests.
    */
   public async updateFile(
     fileName: string,
@@ -100,18 +133,41 @@ export class TtscService {
     );
     // The resident client validated the reply carries a boolean `updated`, so a
     // malformed or wrong-shape reply rejected instead of collapsing to `false`.
-    // `false` here means only that the edit did not compile.
+    // `false` reports a failed host rebuild, not a separately observed cause.
     return reply.updated === true;
   }
 
-  /** Terminate the resident host and reject any in-flight requests. */
+  /**
+   * Reject in-flight requests, close client pipes and attempt host termination.
+   * Returns without waiting for child close; OS signaling can fail.
+   *
+   * @evidence contracts/common.md#principled-implementation Delegating to the client retires request ownership and rejects pending work, then attempts supported pipe destruction and child signals without certifying process closure.
+   * @evidence contracts/common.md#clear-and-simple-design Disposal has one resident owner; this wrapper keeps no second shutdown state or listener registry.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported client termination path is used without replacing child methods or pretending outstanding transforms completed.
+   * @evidence contracts/common.md#meaningful-documentation Native wording distinguishes pending-request rejection and termination attempts from an awaited child-close receipt.
+   * @evidence contracts/portability.md#os-neutral-implementation Child termination is delegated to the Node resident client instead of an OS-specific shell kill command.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms One delegate retires the client; that owner scans outstanding request slots and removes listeners before native pipe/signal attempts. Fixed wrapper steps do not make shutdown independent of pending population.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Disposal is an ownership-ending effect, not a computation whose output authorizes shared execution.
+   *
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The client rejects requests and closes pipes, with one unreferenced grace timer attempting forced termination. Repeated disposal respects terminal state; failed signaling may leave the child alive, and this method supplies no process-tree or close join.
+   */
   public dispose(): void {
     this.resident.dispose();
   }
 
   private absolutePath(fileName: string): string {
-    return path.isAbsolute(fileName)
-      ? fileName
-      : path.resolve(this.projectRoot, fileName);
+    const physical = resolvePhysicalPath(
+      path.resolve(this.projectRoot, fileName),
+    );
+    const relative = path.relative(this.physicalProjectRoot, physical);
+    // Compare both sides physically, then address an in-project file exactly as
+    // the resident Program names it. Its source lookup compares names, not
+    // filesystem identities, and on Windows it may retain an 8.3 root.
+    return relative === ".." ||
+      relative.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(relative)
+      ? physical
+      : path.join(this.projectRoot, relative);
   }
 }

package/src/TtscServiceRequestOptions.ts

@@ -0,0 +1,21 @@
+/**
+ * Cancellation for a resident transform or update request.
+ *
+ * An abort before enqueueing affects only this call. Once enqueued, an abort
+ * retires the shared resident host and rejects its outstanding calls because
+ * the FIFO reply protocol carries no request identifiers. Work already sent has
+ * no rollback guarantee.
+ *
+ * @evidence contracts/common.md#principled-implementation The optional standard AbortSignal expresses caller cancellation; pre-enqueue cancellation is local, while queued cancellation retires the identifier-free FIFO so later replies cannot settle the wrong call.
+ * @evidence contracts/common.md#clear-and-simple-design One per-call control leaves process ownership and request contents with their existing owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cancellation uses the standard signal protocol without replacing resident methods or introducing a fixture-specific control.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain cancellation before and after enqueueing, the shared-host effect and absence of transactional rollback, with prose separated from tags.
+ * @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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export interface TtscServiceRequestOptions {
+  /** Abort this call; an enqueued call also retires the shared resident host. */
+  signal?: AbortSignal;
+}

package/src/compiler/internal/CapturedProcessOutput.ts

@@ -0,0 +1,69 @@
+/**
+ * A child process's standard output and error, captured through files instead
+ * of pipes.
+ *
+ * Produced by {@link captureProcessOutput}. Pass `stdoutFd` and `stderrFd` as
+ * the child's stdio, read the streams back after it exits, and always call
+ * `dispose` to attempt descriptor closure and private-directory removal.
+ * Cleanup errors are suppressed, so calling it does not certify native
+ * release.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate descriptors and paths represent inherited child writes and retry-by-name reads, while read and dispose expose the two permitted lifecycle operations.
+ * @evidence contracts/common.md#clear-and-simple-design The interface groups both streams under one disposal operation, while exposed native descriptors remain the caller responsibility; encoding is chosen at read time.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Stream names and encoding choices are declared capture semantics, not consumer-specific substitutions or mutations of a child-process API.
+ * @evidence contracts/common.md#meaningful-documentation The type documents producer, handoff and mandatory disposal; each member has a separated native explanation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Paths and descriptor numbers carry Node's native filesystem representation; retry callers receive physical file paths rather than a shell command or assumed slash spelling.
+ * @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 CapturedProcessOutput {
+  /**
+   * Attempt each descriptor close once and backing-file removal. Repeated calls
+   * have no effect; removal failure does not replace the process outcome.
+   *
+   * @evidence contracts/common.md#principled-implementation Disposal terminates ownership once, so a later call cannot close a descriptor number that the OS has already reassigned.
+   * @evidence contracts/common.md#clear-and-simple-design One operation consumes the cleanup attempt for both streams and their directory; callers use it in finally without separate ordering, while suppressed failures can leave native resources.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Best-effort cleanup preserves the real process outcome instead of manufacturing a successful acquisition or hiding a read failure.
+   * @evidence contracts/common.md#meaningful-documentation The comment states idempotence and removal's best-effort effect, following the documentation skill's guidance on ownership and failure.
+   * @evidence contracts/portability.md#os-neutral-implementation Descriptor closure and removal use native Node APIs; inherited Windows handles can defer removal without changing descriptor ownership.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources dispose declares a signature only; the implementation owns acquisition and release of resources.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms dispose declares a signature only; the implementation owns the processing strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work dispose declares a signature only; the implementation owns any shared work.
+   */
+  dispose(): void;
+
+  /**
+   * Read one stream after the child exits, decoded unless `"buffer"` is asked
+   * for. Undefined encoding means UTF-8. Filesystem read errors propagate.
+   *
+   * @evidence contracts/common.md#principled-implementation The literal stream choice selects its owned file; buffer returns raw bytes, while a requested BufferEncoding determines decoding.
+   * @evidence contracts/common.md#clear-and-simple-design Read is separate from disposal so callers can obtain both streams before ending their shared ownership.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Read errors remain errors rather than being replaced by expected or empty output.
+   * @evidence contracts/common.md#meaningful-documentation Timing, default encoding and I/O failure are documented in a separate native paragraph following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation The stream is read from a native file path with Node's byte and encoding APIs, independent of platform newline conventions.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources read declares a signature only; the implementation owns acquisition and release of resources.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms read declares a signature only; the implementation owns the processing strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work read declares a signature only; the implementation owns any shared work.
+   */
+  read(
+    stream: "stdout" | "stderr",
+    encoding: BufferEncoding | "buffer" | undefined,
+  ): string | Buffer;
+
+  /** Open descriptor of the standard-error file, to hand to the child. */
+  stderrFd: number;
+
+  /**
+   * Path of the standard-error file inside the per-call private directory. A
+   * descriptor-exhaustion retry reopens it by name (see
+   * {@link spawnSyncResilient}).
+   */
+  stderrPath: string;
+
+  /** Open descriptor of the standard-output file, to hand to the child. */
+  stdoutFd: number;
+
+  /** Path of the standard-output file inside the per-call private directory. */
+  stdoutPath: string;
+}

package/src/compiler/internal/CompilerArgumentsInspection.ts

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+
+import { readCompilerOptionOccurrence } from "../../flags/readCompilerOptionOccurrence";
+
+/**
+ * Inspect compiler argument frames without replacing the emitting producer.
+ * Response identity and content are observed; native occurrence widths keep
+ * dash and @ operands with their options. Unknown or incomplete inspection
+ * requests fail before a reporting flag can become a missing scalar value.
+ *
+ * @evidence contracts/common.md#principled-implementation Shared native occurrence widths preserve option operands and response-frame boundaries; bracketed physical metadata and hashes establish observations without inventing compiler ownership.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace owns argument inspection and its file observation representation; callers retain executable selection, native validation and emission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing native response tokenization and metadata are retained, with generated occurrence consumption rather than independent option arity guesses or foreign method replacement.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains refusal, observation limits and producer ownership; members document transferred response observations and physical file signatures.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The grouping owns no independent native representation; its inspection and observation members describe their filesystem boundaries.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The grouping has no independent computation; the selected members own scans and hashing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No namespace cache or shared task is retained.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Invocation-local inspection and synchronous file operations have member owners.
+ */
+export namespace CompilerArgumentsInspection {
+  /**
+   * Expand observed response frames while preserving native operand positions.
+   * Throws when read-only reporting cannot safely extend the original frame.
+   * The producer still receives the caller's original argv and owns
+   * diagnostics. Response text is read separately between two hashed
+   * observations; equality does not establish an atomic snapshot or detect a
+   * change restored in between.
+   *
+   * @evidence contracts/common.md#principled-implementation A stack preserves each response frame and occurrence widths skip scalar operands; bare booleans receive an explicit value only in the inspection projection so parent tokens cannot bind across frames.
+   * @evidence contracts/common.md#clear-and-simple-design One cursor per frame and one active physical-path set distinguish ordered reuse from cycles, returning projected argv and the observations needed by the emission owner.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts This is conservative inspection admission, not a second native option validator; unknown or unsafe frames throw without rewriting the actual producer request.
+   * @evidence contracts/common.md#meaningful-documentation The comment describes projected argv, refusal and retained native diagnostic ownership.
+   * @evidence contracts/portability.md#os-neutral-implementation Native real paths and bigint file metadata identify response files; UTF-8 and BOM-selected UTF-16 decoding preserve the existing native filesystem text boundary.
+   * @evidence contracts/performance.md#efficient-algorithms Cursors advance through expanded occurrences; each response expansion performs two hashed file observations and a separate decoded read, plus native path resolution and tokenization. Cost follows all reread bytes, expanded argument text and path/metadata work; repeated frames and expansion depth have no fixed cap.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Response files are reread for each invocation because bytes and identity may change; no earlier request establishes continued validity.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Synchronous reads retain no handles; active paths leave the set as frames close, and projected arguments and observations transfer to the caller. Stack, decoded buffers and output follow the uncapped expanded invocation; failures leave only call-local state for collection.
+   */
+  export function inspect(args: readonly string[], cwd: string) {
+    const observations = new Map<string, string>();
+    const projected: string[] = [];
+    const active = new Set<string>();
+    const frames: {
+      args: readonly string[];
+      index: number;
+      physical?: string;
+    }[] = [{ args, index: 0 }];
+    while (frames.length !== 0) {
+      const frame = frames[frames.length - 1]!;
+      if (frame.index === frame.args.length) {
+        if (frame.physical !== undefined) active.delete(frame.physical);
+        frames.pop();
+        continue;
+      }
+      const index = frame.index;
+      const token = frame.args[index]!;
+      if (token.startsWith("@")) {
+        frame.index++;
+        const file = path.resolve(cwd, token.slice(1));
+        const before = observeInputFile(file);
+        const physical = (JSON.parse(before) as [string])[0];
+        if (active.has(physical))
+          throw new Error(`Cyclic compiler response file: ${file}`);
+        const text = responseText(fs.readFileSync(file));
+        if (observeInputFile(file) !== before)
+          throw new Error(
+            `Compiler response file changed during reading: ${file}`,
+          );
+        const previous = observations.get(file);
+        if (previous !== undefined && previous !== before)
+          throw new Error(
+            `Compiler response file changed between reads: ${file}`,
+          );
+        observations.set(file, before);
+        active.add(physical);
+        frames.push({ args: responseTokens(text), index: 0, physical });
+        continue;
+      }
+      const occurrence = readCompilerOptionOccurrence(frame.args, index);
+      if (token.startsWith("-")) {
+        const option = occurrence.option;
+        if (
+          option === undefined ||
+          token.includes("=") ||
+          (option.kind !== "boolean" &&
+            option.kind !== "list" &&
+            occurrence.width === 1) ||
+          (option.kind === "boolean" && occurrence.booleanValue === undefined)
+        )
+          throw new Error(
+            `Unsupported or incomplete compiler inspection option: ${token}`,
+          );
+      }
+      projected.push(...frame.args.slice(index, index + occurrence.width));
+      if (occurrence.option?.kind === "boolean" && occurrence.width === 1)
+        projected.push(occurrence.booleanValue === true ? "true" : "false");
+      frame.index += occurrence.width;
+    }
+    return { args: projected, observations };
+  }
+
+  /**
+   * Bracket a regular file read with physical identity and bigint metadata.
+   * Executable cross-command observations omit ctime; source observations keep
+   * it. A change restored between observations can remain invisible.
+   *
+   * @evidence contracts/common.md#principled-implementation Real paths, object metadata and SHA256 bytes describe the actual observed file; before/after equality rejects an unstable read, with executable ctime omitted only from the returned cross-command signature.
+   * @evidence contracts/common.md#clear-and-simple-design One serialized signature is shared by source, executable and response observation consumers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No path spelling, same-stem output or version label substitutes for observed physical identity and bytes; the documented gap is not claimed atomic.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains metadata bracketing, executable ctime and the observation gap.
+   * @evidence contracts/portability.md#os-neutral-implementation Native realpath and bigint stat values represent physical objects without assuming platform case policy or inode precision in JavaScript numbers.
+   * @evidence contracts/performance.md#efficient-algorithms One file read and SHA256 hash scan the file bytes; two native realpath resolutions and two bigint stats also contribute filesystem cost. Signature construction, comparisons and JSON serialization follow path and metadata text, with a transient file-sized buffer and returned signature.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A current observation cannot reuse earlier bytes without validating the same current identity and contents; no history is cached here.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous readFile and stat operations retain no open handle; the signature transfers to its caller.
+   */
+  export function observeInputFile(
+    source: string,
+    kind: "source" | "executable" = "source",
+  ): string {
+    const physical = fs.realpathSync.native(source);
+    const before = fs.statSync(source, { bigint: true });
+    if (!before.isFile())
+      throw new Error("Observed compiler input is not a regular file.");
+    const hash = createHash("sha256")
+      .update(fs.readFileSync(source))
+      .digest("hex");
+    const after = fs.statSync(source, { bigint: true });
+    const fullSignature = (stat: fs.BigIntStats) =>
+      [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+    if (
+      fullSignature(before) !== fullSignature(after) ||
+      fs.realpathSync.native(source) !== physical
+    )
+      throw new Error("Compiler input changed during observation.");
+    const signature =
+      kind === "source"
+        ? fullSignature(after)
+        : [after.dev, after.ino, after.size, after.mtimeNs].join(":");
+    return JSON.stringify([physical, signature, hash]);
+  }
+}
+
+/** Native filesystem decoding strips UTF-8/UTF-16 BOMs before tokenization. */
+function responseText(bytes: Buffer): string {
+  if (bytes.length >= 2) {
+    const littleEndian = bytes[0] === 0xff && bytes[1] === 0xfe;
+    const bigEndian = bytes[0] === 0xfe && bytes[1] === 0xff;
+    if (littleEndian || bigEndian) {
+      if (bytes.length % 2 !== 0)
+        throw new Error("Incomplete UTF-16 compiler response text.");
+      return new TextDecoder(littleEndian ? "utf-16le" : "utf-16be", {
+        ignoreBOM: true,
+      }).decode(bytes.subarray(2));
+    }
+  }
+  const start =
+    bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf ? 3 : 0;
+  return bytes.subarray(start).toString("utf8");
+}
+
+/** Native response grammar: ASCII control/space separators and whole quotes. */
+function responseTokens(text: string): string[] {
+  const args: string[] = [];
+  let position = 0;
+  while (position < text.length) {
+    while (position < text.length && text.charCodeAt(position) <= 32)
+      position++;
+    if (position === text.length) break;
+    if (text[position] === '"') {
+      const end = text.indexOf('"', position + 1);
+      if (end === -1) throw new Error("Unterminated compiler response quote.");
+      args.push(text.slice(position + 1, end));
+      position = end + 1;
+    } else {
+      const start = position;
+      while (position < text.length && text.charCodeAt(position) > 32)
+        position++;
+      args.push(text.slice(start, position));
+    }
+  }
+  return args;
+}