ttsc 0.30.4 → 0.31.1

package/src/compiler/internal/ResidentCheckProcess.ts

@@ -0,0 +1,445 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type Interface, createInterface } from "node:readline";
+
+import { E2ETrace } from "../../internal/E2ETrace";
+import type { ResidentCheckProcessOptions } from "./ResidentCheckProcessOptions";
+import type { ResidentCheckRequest } from "./ResidentCheckRequest";
+import type { ResidentCheckResult } from "./ResidentCheckResult";
+
+/**
+ * FIFO JSON-line client for a check-stage `check-serve` sidecar.
+ *
+ * A watch session serializes cycles, but the client still queues replies so a
+ * caller cannot accidentally pair a late response with the next request. Any
+ * framing failure retires the process; the launcher can fall back to an
+ * ordinary one-shot command after joining the original child. An unjoined child
+ * cannot authorize that replacement.
+ *
+ * The caller owns disposal. Requests have no deadline, and outstanding request
+ * count and reply-line size are not capped; a slow live check remains pending.
+ * Retirement ends stdin and waits for actual close. A one-second grace period
+ * starts after stdin finishes, followed by forced termination and a one-second
+ * join deadline. Pending stdin writes have a one-second flush deadline once the
+ * retiring call stack yields. An unjoined deadline releases this client's
+ * pipes, request listeners, timers and event-loop process reference while
+ * keeping joining failed; the client object still holds its ChildProcess. It
+ * neither kills unrelated descendants nor certifies their termination. A forced
+ * or unjoined process is not a graceful shutdown. These delays are event-loop
+ * timer policies, not hard elapsed-time bounds; synchronous blocking or
+ * callback starvation can postpone their delivery.
+ *
+ * @evidence contracts/common.md#principled-implementation One positional reply consumes one queued cycle; invalid framing or shape retires the stream so a delayed reply cannot answer a different cycle.
+ * @evidence contracts/common.md#clear-and-simple-design One client owns its child, line reader, FIFO and failure state; private parsing and settlement keep transport policy separate from the watch coordinator's fallback.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Protocol validation uses the declared reply fields, and transport failure is rejection rather than a fabricated successful check or a consumer-specific recovery.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain FIFO ownership, retirement, caller disposal and the absence of request bounds, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node spawns the supplied native executable with an argv array and pipe streams, without shell quoting; cwd and environment retain caller-provided native semantics.
+ * @evidence contracts/performance.md#efficient-algorithms A head cursor consumes replies with amortized constant queue work and failure drains outstanding requests once. Encoding/decoding visit data and text bytes; caller-defined serialization can add arbitrary work. Stderr decoding and concatenation scan the new chunk plus retained tail before truncation. Native spawn, check execution and shutdown completion remain delegated and event-loop scheduled.
+ * @evidence contracts/performance.md#reuse-equivalent-work One startup-selected child is shared across FIFO cycles, but its native session can update or reconstruct Program generations. Changed/external paths travel with each request and the watch owner replaces the process on configuration/plugin identity changes; the client does not reuse a response or certify every custom host's internal Program cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Each settled slot releases its request; retirement clears the queue and drains replies until actual close or the failed join deadline. That deadline releases owned transport handles and callbacks without claiming the physical child or unrelated descendants joined; live request count and line bytes have no fixed cap.
+ */
+export class ResidentCheckProcess {
+  private readonly child: ChildProcess;
+  private readonly pending: (PendingRequest | undefined)[] = [];
+  private pendingHead = 0;
+  private readonly reader: Interface;
+  private failure: Error | undefined;
+  private stderr = "";
+  private readonly exited: Promise<void>;
+  private closing = false;
+  private didClose = false;
+  private forced = false;
+  private flushDeadline: NodeJS.Timeout | undefined;
+  private terminationTimer: NodeJS.Timeout | undefined;
+  private terminationDeadline: NodeJS.Timeout | undefined;
+  private releaseTransport: (() => void) | undefined;
+
+  public constructor(options: ResidentCheckProcessOptions) {
+    const nativeArgs = [...options.args];
+    const trace = E2ETrace.begin(
+      options.binary,
+      nativeArgs,
+      options,
+      "resident-check",
+    );
+    this.child = spawn(options.binary, nativeArgs, {
+      cwd: options.cwd,
+      env: options.env,
+      windowsHide: true,
+    });
+    E2ETrace.asynchronous(trace, this.child);
+    let onChildClose: (() => void) | undefined;
+    this.exited = new Promise<void>((resolve, reject) => {
+      onChildClose = () => {
+        this.didClose = true;
+        clearTimeout(this.flushDeadline);
+        clearTimeout(this.terminationTimer);
+        clearTimeout(this.terminationDeadline);
+        this.releaseTransport = undefined;
+        this.reader?.close();
+        resolve();
+      };
+      this.child.once("close", onChildClose);
+      this.rejectExit = reject;
+    });
+    // Legacy dispose initiates retirement without returning a promise. Keep its
+    // rejected join observable to awaiters without an unhandled rejection.
+    void this.exited.catch(() => {});
+    const stdin = this.child.stdin;
+    const stdout = this.child.stdout;
+    if (stdin === null || stdout === null) {
+      this.child.kill();
+      throw new Error("ttsc: resident check host has no stdio pipes");
+    }
+    this.reader = createInterface({ input: stdout });
+    const onLine = (line: string) => this.onLine(line);
+    const onReaderClose = () => {
+      if (this.failure === undefined) this.fail(this.exitError());
+    };
+    const onStderr = (chunk: Buffer | string) => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      this.stderr = (this.stderr + text).slice(-STDERR_TAIL_LIMIT);
+    };
+    const onError = (error: Error) => this.fail(error);
+    this.reader.on("line", onLine);
+    this.reader.on("close", onReaderClose);
+    this.child.stderr?.on("data", onStderr);
+    this.child.on("error", onError);
+    stdin.on("error", onError);
+    stdout.on("error", onError);
+    this.child.stderr?.on("error", ResidentCheckProcess.ignoreTransportError);
+    this.releaseTransport = () => {
+      clearTimeout(this.flushDeadline);
+      clearTimeout(this.terminationTimer);
+      clearTimeout(this.terminationDeadline);
+      this.reader.off("line", onLine);
+      this.reader.off("close", onReaderClose);
+      this.reader.close();
+      if (onChildClose !== undefined) this.child.off("close", onChildClose);
+      this.child.off("error", onError);
+      this.child.on("error", ResidentCheckProcess.ignoreTransportError);
+      this.child.stderr?.off("data", onStderr);
+      for (const stream of [stdin, stdout, this.child.stderr]) {
+        stream?.off("error", onError);
+        stream?.off("error", ResidentCheckProcess.ignoreTransportError);
+        stream?.on("error", ResidentCheckProcess.ignoreTransportError);
+        stream?.destroy();
+      }
+      this.child.unref();
+    };
+  }
+
+  /**
+   * Send one watch cycle and wait for its reply.
+   *
+   * Replies are paired with requests in FIFO order. A request made after the
+   * process failed, or whose line cannot be written, rejects with the failure
+   * that retired the process, so the caller can fall back to a one-shot check
+   * for that cycle.
+   *
+   * Serialization precedes enqueueing and normally rejects only this call;
+   * exceptional thrown-value conversion can itself fail during normalization. A
+   * closed input retires the host and rejects its other pending calls.
+   *
+   * @evidence contracts/common.md#principled-implementation Serialization precedes enqueueing, and each successfully enqueued call keeps its own FIFO slot until a validated reply or shared retirement settles it.
+   * @evidence contracts/common.md#clear-and-simple-design Pre-write validation remains local; write failures use the same settlement and retirement operations as pipe and protocol failure.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed serialization cannot consume a reply slot, and a closed pipe is not treated as a healthy host with one exceptional caller.
+   * @evidence contracts/common.md#meaningful-documentation Separate paragraphs document reply ordering, rejection scope and closed-input effects, applying the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation JSON lines pass native change paths as data over Node's stdin stream, without constructing a shell command or converting native separators.
+   * @evidence contracts/performance.md#efficient-algorithms Encoding visits supplied properties and output bytes, with caller-defined conversion not bounded by final JSON size; enqueueing and settlement have amortized constant queue work plus reply parsing. Native check work is delegated rather than bounded by transport cost.
+   * @evidence contracts/performance.md#reuse-equivalent-work Each cycle is sent to the existing fixed-configuration Program owner; changes are effectful transitions and are not coalesced merely because request values match.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The client retains one resolver pair per outstanding call until reply or retirement; serialization allocates one request line, and live requests wait without an implicit timeout or population limit.
+   */
+  public request(payload: ResidentCheckRequest): Promise<ResidentCheckResult> {
+    if (this.failure !== undefined) return Promise.reject(this.failure);
+    const stdin = this.child.stdin;
+    if (stdin === null || stdin.destroyed) {
+      const error = new Error("ttsc: resident check host stdin is closed");
+      this.fail(error);
+      return Promise.reject(error);
+    }
+    let line: string;
+    try {
+      line = `${JSON.stringify(payload)}\n`;
+    } catch (error) {
+      return Promise.reject(asError(error));
+    }
+    return new Promise<ResidentCheckResult>((resolve, reject) => {
+      const pending: PendingRequest = { reject, resolve, settled: false };
+      this.pending.push(pending);
+      try {
+        stdin.write(line, (error) => {
+          if (error === null || error === undefined || pending.settled) return;
+          this.settle(pending, error);
+          this.fail(error);
+        });
+      } catch (error) {
+        const reason = asError(error);
+        this.settle(pending, reason);
+        this.fail(reason);
+      }
+    });
+  }
+
+  /**
+   * Retire the sidecar: reject pending requests and close its request stream.
+   * Idempotent; a process that already failed is left as is.
+   *
+   * @evidence contracts/common.md#principled-implementation Setting failure before rejecting the detached FIFO makes disposal terminal; subsequent replies and requests cannot revive the child.
+   * @evidence contracts/common.md#clear-and-simple-design Disposal enters the same retirement path as transport failure instead of maintaining a second cleanup sequence.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Cleanup ends the actual owned streams and attempts child termination; it does not disguise a pending request as a successful result.
+   * @evidence contracts/common.md#meaningful-documentation The native comment states terminal rejection and repeated-call behavior, following the documentation skill's ownership guidance.
+   * @evidence contracts/portability.md#os-neutral-implementation Owned stream EOF and forced signaling use Node's supported APIs without shell or POSIX process-tree commands.
+   * @evidence contracts/performance.md#efficient-algorithms Retirement visits each outstanding request once and releases the queue in linear time rather than repeatedly shifting all remaining entries.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Disposal ends the owner and produces no computation that another request may reuse.
+   *
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Disposal clears pending callbacks and requests stdin EOF while preserving output until actual close or a failed join timer. Failed join destroys/unrefs owned transport and removes request listeners without proving child/descendant termination; timer delivery depends on the event loop, and the client object can still retain its ChildProcess.
+   */
+  public dispose(): void {
+    this.fail(new Error("ttsc: resident check host disposed"));
+  }
+
+  /**
+   * End the request stream and await the owned child's actual close event. A
+   * forced, signalled or nonzero exit rejects; repeated calls share
+   * retirement.
+   *
+   * @evidence contracts/common.md#principled-implementation EOF is sent on the owned input and success requires the child's actual close with status zero, never merely a successful kill request.
+   * @evidence contracts/common.md#clear-and-simple-design Retirement and join are shared with dispose; this awaitable boundary adds exit validation for callers that must release process ownership.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Forced and unknown termination remain failures rather than fabricated graceful completion.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states the child-close authority, success condition and repeated-call behavior.
+   * @evidence contracts/portability.md#os-neutral-implementation Native stdin EOF and child close events work through Node's process API; forced signalling is a failure rather than a portable graceful-stop assumption.
+   * @evidence contracts/performance.md#efficient-algorithms Closing performs one retirement traversal and constant-time exit validation; no polling population grows over the lifetime.
+   * @evidence contracts/performance.md#reuse-equivalent-work Repeated closes reuse the single actual-exit promise but never reuse an earlier process's exit as proof for another child.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Actual close clears termination timers. A failed event-loop-scheduled join deadline destroys/unrefs transport and removes request listeners while retaining terminal failure; unref releases event-loop liveness, not the client object's ChildProcess reference or proof of physical child/descendant termination.
+   */
+  public async close(): Promise<void> {
+    this.dispose();
+    await this.exited;
+    if (this.forced)
+      throw new Error("ttsc: resident check host required forced termination");
+    if (this.child.exitCode !== 0 || this.child.signalCode !== null)
+      throw this.exitError();
+  }
+
+  /**
+   * Await actual retirement before a transport-failure fallback starts. A known
+   * failed child may be replaced; an unjoined child may not.
+   *
+   * @evidence contracts/common.md#principled-implementation A replacement can start only after the original child's close event releases its native ownership.
+   * @evidence contracts/common.md#clear-and-simple-design The transport owner exposes joining separately from graceful status validation for the supported recovery policy.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An elapsed deadline rejects instead of treating a still-live process as retired.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes recovery's known failed exit from shutdown's graceful success requirement.
+   * @evidence contracts/portability.md#os-neutral-implementation The actual close event, rather than a signal result or native PID spelling, establishes retirement on each platform.
+   * @evidence contracts/performance.md#efficient-algorithms This accessor returns the existing promise without adding a child listener or polling filesystem/process state; subscriber work belongs to the caller.
+   * @evidence contracts/performance.md#reuse-equivalent-work Every waiter shares this child's terminal event; a replacement always owns a new promise.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Waiters share actual close or, after retirement begins, its event-loop-scheduled failed join deadline. Waiting alone starts no termination timer; a live unretired child can remain pending without a deadline, and an unjoined owner remains failure.
+   */
+  public waitForExit(): Promise<void> {
+    return this.exited;
+  }
+
+  private rejectExit: ((error: Error) => void) | undefined;
+
+  private onLine(line: string): void {
+    if (this.failure !== undefined || line.trim().length === 0) return;
+    const pending = this.pending[this.pendingHead];
+    if (pending === undefined) {
+      this.fail(
+        new Error("ttsc: resident check host sent an unsolicited reply"),
+      );
+      return;
+    }
+    const result = parseResidentCheckResult(line);
+    if (result === undefined) {
+      const error = new Error(
+        `ttsc: resident check host sent a malformed reply: ${echoLine(line)}`,
+      );
+      this.settle(pending, error);
+      this.fail(error);
+      return;
+    }
+    this.settle(pending, result);
+  }
+
+  private settle(
+    pending: PendingRequest,
+    result: Error | ResidentCheckResult,
+  ): void {
+    if (pending.settled) return;
+    pending.settled = true;
+    if (this.pending[this.pendingHead] === pending) {
+      this.pending[this.pendingHead++] = undefined;
+      if (this.pendingHead * 2 >= this.pending.length) {
+        this.pending.splice(0, this.pendingHead);
+        this.pendingHead = 0;
+      }
+    }
+    if (result instanceof Error) pending.reject(result);
+    else pending.resolve(result);
+  }
+
+  private fail(error: Error): void {
+    if (this.failure !== undefined) return;
+    this.failure = error;
+    const pending = this.pending.splice(0);
+    this.pendingHead = 0;
+    for (const request of pending) {
+      if (request !== undefined) this.settle(request, error);
+    }
+    this.terminate();
+  }
+
+  private terminate(): void {
+    if (this.closing) return;
+    this.closing = true;
+    const stdin = this.child.stdin;
+    if (stdin !== null && !stdin.destroyed) {
+      try {
+        // EOF cannot reach the child until the owned writable pipe finishes.
+        // A blocked parent event loop must not spend the child's shutdown grace
+        // before that delivery can happen.
+        stdin.end(() => this.startTerminationGrace());
+        // Start delivery's own deadline after the caller gives Node control.
+        // This bounds an unread full pipe without charging synchronous caller
+        // work against either delivery or the child's later EOF grace.
+        queueMicrotask(() => {
+          if (this.didClose || this.terminationTimer !== undefined) return;
+          this.flushDeadline = setTimeout(
+            () => this.forceTerminationAndJoin(),
+            TERMINATION_GRACE_MS,
+          );
+        });
+        return;
+      } catch {
+        stdin.destroy();
+      }
+    }
+    this.startTerminationGrace();
+  }
+
+  private startTerminationGrace(): void {
+    clearTimeout(this.flushDeadline);
+    // Keep output pipes readable until close: destroying them would discard the
+    // last reply and confuse a requested EOF with transport truncation.
+    if (
+      this.didClose ||
+      this.terminationTimer !== undefined ||
+      this.terminationDeadline !== undefined
+    )
+      return;
+    this.terminationTimer = setTimeout(
+      () => this.forceTerminationAndJoin(),
+      TERMINATION_GRACE_MS,
+    );
+  }
+
+  private forceTerminationAndJoin(): void {
+    if (this.didClose || this.terminationDeadline !== undefined) return;
+    if (this.child.exitCode === null && this.child.signalCode === null) {
+      this.forced = true;
+      try {
+        this.child.kill("SIGKILL");
+      } catch {
+        // The deadline still requires actual close, even if kill fails.
+      }
+    }
+    this.terminationDeadline = setTimeout(() => {
+      this.rejectExit?.(
+        new Error("ttsc: resident check host did not close after termination"),
+      );
+      // Reject first: destroying inherited pipes can cause Node's close event,
+      // but releasing our handles cannot prove a graceful physical join.
+      this.releaseTransport?.();
+      this.releaseTransport = undefined;
+    }, TERMINATION_GRACE_MS);
+  }
+
+  private static ignoreTransportError(): void {}
+
+  private exitError(): Error {
+    const detail = this.stderr.trim();
+    if (detail.length !== 0) return new Error(detail);
+    const signal =
+      this.child.signalCode === null ? "" : `, signal ${this.child.signalCode}`;
+    return new Error(
+      `ttsc: resident check host exited (code ${
+        this.child.exitCode ?? "null"
+      }${signal})`,
+    );
+  }
+}
+
+const STDERR_TAIL_LIMIT = 64 * 1024;
+
+const REPLY_ECHO_LIMIT = 200;
+
+const TERMINATION_GRACE_MS = 1_000;
+
+type PendingRequest = {
+  reject(reason: Error): void;
+  resolve(result: ResidentCheckResult): void;
+  settled: boolean;
+};
+function parseResidentCheckResult(
+  line: string,
+): ResidentCheckResult | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (
+    !isRecord(value) ||
+    typeof value.status !== "number" ||
+    !Number.isInteger(value.status)
+  ) {
+    return undefined;
+  }
+  if (typeof value.stdout !== "string" || typeof value.stderr !== "string") {
+    return undefined;
+  }
+  const telemetry = value.telemetry;
+  if (
+    !isRecord(telemetry) ||
+    typeof telemetry.pid !== "number" ||
+    !Number.isSafeInteger(telemetry.pid) ||
+    typeof telemetry.programLoads !== "number" ||
+    !Number.isSafeInteger(telemetry.programLoads) ||
+    typeof telemetry.programUpdates !== "number" ||
+    !Number.isSafeInteger(telemetry.programUpdates) ||
+    typeof telemetry.reused !== "boolean"
+  ) {
+    return undefined;
+  }
+  return {
+    diagnostics: [],
+    status: value.status,
+    stderr: value.stderr,
+    stdout: value.stdout,
+    telemetry: {
+      pid: telemetry.pid,
+      programLoads: telemetry.programLoads,
+      programUpdates: telemetry.programUpdates,
+      reused: telemetry.reused,
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function echoLine(line: string): string {
+  const trimmed = line.trim();
+  return JSON.stringify(
+    trimmed.length <= REPLY_ECHO_LIMIT
+      ? trimmed
+      : `${trimmed.slice(0, REPLY_ECHO_LIMIT)}…`,
+  );
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/compiler/internal/ResidentCheckProcessOptions.ts

@@ -0,0 +1,32 @@
+/**
+ * How to start a resident `check-serve` sidecar for a watch session.
+ *
+ * Everything that fixes the check (compiler options, project, plugins,
+ * threading) travels in `args` once, at spawn time. Only filesystem changes
+ * travel later, as {@link ResidentCheckRequest} lines.
+ *
+ * @evidence contracts/common.md#principled-implementation Executable, argv, cwd and complete environment represent the fixed native invocation independently from per-cycle change requests.
+ * @evidence contracts/common.md#clear-and-simple-design Required fields establish one complete check-sidecar startup context without implicit environment merge policy inside the client.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Configuration uses explicit invocation data rather than recognizing a plugin name or supplying fixture-specific compiler arguments.
+ * @evidence contracts/common.md#meaningful-documentation The type explains fixed startup state, and separated member comments document native executable, argument and environment authority following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The executable and cwd are native paths, argv remains separate strings, and environment names retain the supplying boundary's native identity policy.
+ * @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 ResidentCheckProcessOptions {
+  /** Full argv of the sidecar, including its `check-serve` subcommand. */
+  args: readonly string[];
+
+  /** Absolute path of the native check host executable. */
+  binary: string;
+
+  /** Working directory the sidecar resolves project-relative paths from. */
+  cwd: string;
+
+  /**
+   * Complete environment of the sidecar. It is passed verbatim rather than
+   * merged, so the caller decides which inherited ttsc variables survive.
+   */
+  env: NodeJS.ProcessEnv;
+}

package/src/compiler/internal/ResidentCheckRequest.ts

@@ -0,0 +1,39 @@
+/**
+ * One watch cycle sent to a resident `check-serve` sidecar: the filesystem
+ * transitions since the previous cycle, and nothing else.
+ *
+ * The sidecar keeps its Program warm across cycles. Each field tells it how
+ * much of that Program the change can have affected; an empty request re-runs
+ * the check on the unchanged Program.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate source changes, external rule inputs and full invalidation express different Program state transitions; omitted lists denote no changes in that category.
+ * @evidence contracts/common.md#clear-and-simple-design One optional change record carries only cycle transitions, while compiler and plugin selection remain fixed startup inputs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The request reports real input categories rather than forcing a test-specific reload or hiding a topology change as unchanged state.
+ * @evidence contracts/common.md#meaningful-documentation Native member paragraphs explain the invalidation consequence of each category and optional-state meaning, with member spacing following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Change lists carry native file paths for the sidecar's project resolution; the type does not impose URL spelling, slash normalization or a universal filesystem case policy.
+ * @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 ResidentCheckRequest {
+  /**
+   * Source files whose contents changed. A file the Program already holds as a
+   * source updates incrementally; any other path (a config edit, a new or
+   * removed file) makes the sidecar reload the Program instead.
+   */
+  changed?: readonly string[];
+
+  /**
+   * Changed files that are declared inputs of a project rule (for example a
+   * document an `@ttsc/evidence` graph reads). They invalidate that rule's
+   * state without reloading the TypeScript Program, unless the same path is
+   * also a source file.
+   */
+  external?: readonly string[];
+
+  /**
+   * Drop the warm Program before this cycle. Sent for a change the launcher
+   * cannot localize, so the request that carries it rebuilds from scratch.
+   */
+  invalidate?: boolean;
+}

package/src/compiler/internal/ResidentCheckResult.ts

@@ -0,0 +1,24 @@
+import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import type { ResidentCheckTelemetry } from "./ResidentCheckTelemetry";
+
+/**
+ * Textual check output and Program activity for one
+ * {@link ResidentCheckRequest}.
+ *
+ * The transport supplies status, stdout and stderr with an empty diagnostics
+ * list. The watch coordinator reconstructs structured diagnostics from that
+ * text using the same normalization as the one-shot check.
+ *
+ * @evidence contracts/common.md#principled-implementation Intersecting the ordinary build result with required telemetry preserves status and textual diagnostics while expressing how that particular resident cycle used its Program.
+ * @evidence contracts/common.md#clear-and-simple-design The type adds only resident provenance to the existing result representation rather than duplicating the build result fields.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Telemetry describes the producer's actual cycle; the type supplies no synthetic successful status or measurement-only branch.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraph distinguishes the result from its residency metadata, and the member comment identifies telemetry purpose following the documentation skill.
+ * @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.
+ * @evidence contracts/portability.md#os-neutral-implementation The inherited build-result fields retain their native diagnostic/output/input path conventions; resident telemetry adds numeric producer identity and activity without converting those paths or imposing a platform-specific PID spelling.
+ */
+export type ResidentCheckResult = TtscBuildResult & {
+  /** How the sidecar served this cycle. */
+  telemetry: ResidentCheckTelemetry;
+};

package/src/compiler/internal/ResidentCheckTelemetry.ts

@@ -0,0 +1,36 @@
+/**
+ * How a resident check sidecar served one cycle.
+ *
+ * Ordinary diagnostics can report the producer's process identity and Program
+ * activity without enabling a separate measurement mode.
+ *
+ * Load and update counts classify the producer's accepted state transitions,
+ * rather than counting every compiler Program object. An incremental update can
+ * create a new generation object while reusing the prior Program's data. Failed
+ * load attempts are not counted as successful loads.
+ *
+ * @evidence contracts/common.md#principled-implementation Process identity, cumulative successful cold loads/full reconstructions and data-reusing updates distinguish producer lifetime from the current cycle's reuse flag; the counters do not assert total compiler object creation.
+ * @evidence contracts/common.md#clear-and-simple-design Four scalar observations report residency without exposing the sidecar's mutable Program or adding lifecycle controls to a result record.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Observations are supplied by the real resident producer rather than inferred from plugin names, timing or a benchmark-specific execution path.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies ordinary diagnostic use, and separated member comments explain lifetime and count meanings following the documentation skill.
+ * @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 ResidentCheckTelemetry {
+  /** Process id of the sidecar; stable across cycles while it stays resident. */
+  pid: number;
+
+  /** Successful cold loads and full update reconstructions since startup. */
+  programLoads: number;
+
+  /** Data-reusing source updates since startup, counted per changed source. */
+  programUpdates: number;
+
+  /**
+   * This cycle retained warm Program data without full reconstruction. It does
+   * not certify reuse of the same compiler generation object.
+   */
+  reused: boolean;
+}

package/src/compiler/internal/ResidentReplyKind.ts

@@ -0,0 +1,18 @@
+/**
+ * The operation a request expects a reply for. The host answers a transform
+ * request (`{"file":...}`) with `{"typescript":...,"found":...}` and an update
+ * request (`{"update":...,"content":...}`) with `{"updated":...}`. The client
+ * knows which it sent, so it validates the reply's shape against the operation
+ * before handing it back — a well-formed JSON object of the wrong operation
+ * shape is a protocol error, not a valid negative result.
+ *
+ * @evidence contracts/common.md#principled-implementation The two literal operations identify their distinct reply schemas, allowing a negative domain answer to remain distinguishable from an invalid operation-shaped reply.
+ * @evidence contracts/common.md#clear-and-simple-design A closed discriminant union carries the operation needed for validation without storing a second mutable request object.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Operation discriminants are protocol-defined values, not hardcoded consumer identities or expected results.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraph gives both wire forms and explains why shape validation matters, following the documentation skill.
+ * @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 type ResidentReplyKind = "transform" | "update";