ttsc 0.30.3 → 0.31.0

package/src/compiler/internal/ResidentTransformProcess.ts

@@ -0,0 +1,299 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type Interface, createInterface } from "node:readline";
+
+import { E2ETrace } from "../../internal/E2ETrace";
+import type { ResidentReplyKind } from "./ResidentReplyKind";
+import type { ResidentTransformProcessOptions } from "./ResidentTransformProcessOptions";
+import type { ResidentTransformRequestOptions } from "./ResidentTransformRequestOptions";
+import { ResidentTransformRequests } from "./ResidentTransformRequests";
+
+/**
+ * Async client for the long-lived `utility-host serve` process.
+ *
+ * The serve host answers newline-delimited requests within one process; its
+ * producer owns project loading, transformed text and update semantics. This
+ * class speaks that protocol: each {@link request} writes one JSON line and the
+ * host replies with one line, matched FIFO. A transform request
+ * (`{"file":...}`) is answered with `{"typescript":...,"found":...}`, and an
+ * update request (`{"update":...,"content":...}`) with `{"updated":...}`.
+ *
+ * One resident process answers every request from one service instead of
+ * spawning a fresh `transform` subprocess per call. Client construction does
+ * not await startup compilation or certify a custom host's caching behavior.
+ *
+ * The caller owns disposal. Live requests have no deadline; queue population
+ * and reply-line size depend on the caller and host, without a fixed cap.
+ *
+ * @evidence contracts/common.md#principled-implementation FIFO ownership follows the host's ordered request loop; malformed framing retires all slots, while a valid object with an invalid operation shape consumes and rejects only its own slot.
+ * @evidence contracts/common.md#clear-and-simple-design The client owns one child, line reader, queue and terminal state; reply validation and settlement are private transport responsibilities distinct from the service's project policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing files and rejected edits remain legitimate negative replies; corrupt lines reject instead of becoming synthetic empty results or being rescued through foreign method replacement.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish operations, startup reuse, caller ownership and uncapped live requests, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Node receives the executable, separate argv, native cwd and environment directly; supported pipe APIs carry protocol text without platform-specific shell quoting.
+ * @evidence contracts/performance.md#efficient-algorithms A cursor advances through the FIFO with amortized constant queue settlement; consumed prefixes compact only when at least half the array has been consumed, and retirement drains outstanding calls once. Request serialization and reply parsing cost observed data/text volume, with caller serialization callbacks adding arbitrary work. Stderr conversion and concatenation scan each chunk plus the retained tail before truncation; native startup and host processing remain delegated.
+ * @evidence contracts/performance.md#reuse-equivalent-work One startup-selected host is shared across requests; the client does not memoize responses across edits. Transformed-text state and ordered update behavior belong to the serve producer, not a custom-host cache guarantee established by this client.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Consumed slots release callbacks, settlement removes abort listeners, and retirement clears outstanding state and closes pipes. Stderr has a fixed tail cap, but pending calls and line bytes are uncapped and OS signaling may fail to terminate the child.
+ */
+export class ResidentTransformProcess {
+  private readonly child: ChildProcess;
+  private readonly reader: Interface;
+  private readonly requests = new ResidentTransformRequests();
+  private stderr = "";
+
+  public constructor(options: ResidentTransformProcessOptions) {
+    // Default stdio is "pipe" for stdin/stdout/stderr, which is exactly what the
+    // line protocol needs; spelling it out as a string[] would not narrow to
+    // StdioOptions, so it is left implicit.
+    const nativeArgs = [...options.args];
+    const trace = E2ETrace.begin(
+      options.binary,
+      nativeArgs,
+      options,
+      "resident-transform",
+    );
+    this.child = spawn(options.binary, nativeArgs, {
+      cwd: options.cwd,
+      env: options.env,
+      windowsHide: true,
+    });
+    E2ETrace.asynchronous(trace, this.child);
+    const stdout = this.child.stdout;
+    const stdin = this.child.stdin;
+    if (stdout === null || stdin === null) {
+      this.child.kill();
+      throw new Error("ttsc: resident transform host has no stdio pipes");
+    }
+    this.reader = createInterface({ input: stdout });
+    this.reader.on("line", (line) => this.onLine(line));
+    // Drive completion off stdout's end, not the process "exit" event: every
+    // buffered "line" is delivered before "close", so a reply that arrived just
+    // before the host exited still resolves its request instead of racing the
+    // exit-time rejection.
+    this.reader.on("close", () => this.onReaderClose());
+    this.child.stderr?.on("data", (chunk: Buffer | string) => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      // Keep only the tail: stderr is consulted for the crash message, and a
+      // long resident session can write diagnostics on every failed update.
+      this.stderr = (this.stderr + text).slice(-STDERR_TAIL_LIMIT);
+    });
+    this.child.on("error", (error) => this.fail(error));
+    // A dead host's pipes emit "error" (EPIPE on POSIX, often ECONNRESET on
+    // Windows). Without these listeners Node turns a pipe error into an uncaught
+    // exception that crashes the whole consumer process; route them through
+    // fail() (stderr is non-critical) so a pipe death fails in-flight requests
+    // instead, and also closes the window where stdin.destroyed has not flipped.
+    stdin.on("error", (error) => this.fail(error));
+    stdout.on("error", (error) => this.fail(error));
+    this.child.stderr?.on("error", () => {});
+  }
+
+  /**
+   * Send one request to the host and resolve with its validated JSON reply. The
+   * host answers in FIFO order; `kind` tells the client which reply shape the
+   * payload asks for, so the reply is validated as a well-formed `kind` reply
+   * before it resolves. Rejects when the reply is not a valid `kind` reply,
+   * when the host has already failed or exited, or if writing the request
+   * fails.
+   *
+   * An abort before enqueueing affects only this call. Once enqueued, aborting
+   * retires the whole FIFO because the reply stream has no request identifiers.
+   * Serialization failure leaves the healthy host available for another call.
+   * Payload serialization can invoke caller-defined conversion; exceptional
+   * thrown values can also execute or fail conversion while being normalized.
+   *
+   * @evidence contracts/common.md#principled-implementation Each queued request carries its expected operation and resolves only from its own validated FIFO reply; cancellation after enqueueing retires the stream to prevent shifted reply ownership.
+   * @evidence contracts/common.md#clear-and-simple-design Local serialization and pre-abort checks precede shared queue ownership; one settlement helper handles replies, cancellation and write failure with listener cleanup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Cancellation does not remove a positional reply and continue under a false framing assumption; invalid replies cannot masquerade as missing files or rejected edits.
+   * @evidence contracts/common.md#meaningful-documentation The separate lifecycle paragraph explains which failures affect one caller and which retire the shared host, applying the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Requests are JSON data written through the existing native pipe; filenames remain producer-owned values rather than command strings or assumed POSIX paths.
+   * @evidence contracts/performance.md#efficient-algorithms Serialization visits supplied properties and encoded data, with caller-defined conversion costs not bounded by final JSON size. FIFO insertion and ordered settlement have amortized constant queue work; reply text parsing precedes fixed field checks, and host execution is delegated.
+   * @evidence contracts/performance.md#reuse-equivalent-work File requests share the existing producer's committed transformation; effectful updates keep distinct ordered slots, and the client caches no response across producer state transitions.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Each pending call owns resolver callbacks and at most one abort listener; settlement removes the listener and queue reference, while cancellation retires every outstanding call. Live uncancelled work has no implicit timeout or queue cap.
+   */
+  public request(
+    payload: Record<string, unknown>,
+    kind: ResidentReplyKind,
+    options: ResidentTransformRequestOptions = {},
+  ): Promise<Record<string, unknown>> {
+    if (this.requests.failure !== undefined) {
+      return Promise.reject(this.requests.failure);
+    }
+    if (options.signal?.aborted) {
+      return Promise.reject(cancelledError(options.signal));
+    }
+    const stdin = this.child.stdin;
+    if (stdin === null || stdin.destroyed) {
+      const error = new Error("ttsc: resident transform 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<Record<string, unknown>>((resolve, reject) => {
+      const pending = this.requests.add(
+        kind,
+        resolve,
+        reject,
+        options.signal,
+        (request) => this.cancel(request, options.signal!),
+      );
+      if (options.signal?.aborted) {
+        pending.abort!();
+        return;
+      }
+      try {
+        stdin.write(line, (error) => {
+          if (error === null || error === undefined || pending.settled) {
+            return;
+          }
+          this.requests.settle(pending, error);
+          this.fail(
+            new Error(
+              `ttsc: resident transform host could not write a request: ${error.message}`,
+            ),
+          );
+        });
+      } catch (error) {
+        if (pending.settled) return;
+        const reason = asError(error);
+        this.requests.settle(pending, reason);
+        this.fail(
+          new Error(
+            `ttsc: resident transform host could not write a request: ${reason.message}`,
+          ),
+        );
+      }
+    });
+  }
+
+  /**
+   * Retire the client, reject in-flight requests and attempt child termination.
+   * Safe to call more than once; this void operation does not await child close
+   * or prove OS signaling succeeded.
+   *
+   * @evidence contracts/common.md#principled-implementation Failure becomes terminal before all queued callers are rejected, so buffered lines cannot settle new callers after disposal.
+   * @evidence contracts/common.md#clear-and-simple-design Disposal reuses the transport retirement path and preserves the child's real exit error when it has already died.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Cleanup uses supported child and stream APIs and rejects outstanding calls rather than synthesizing successful results. Destroy/signal attempts are not a child-close receipt or a guaranteed process-tree shutdown.
+   * @evidence contracts/common.md#meaningful-documentation The native comment states caller-visible rejection and idempotence, following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Node destroys its own pipes and performs child signaling with its supported platform behavior; no process-tree shell command or signal assumption is imposed on callers.
+   * @evidence contracts/performance.md#efficient-algorithms The queue is detached once and each outstanding request is settled once, making shutdown linear in pending population.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Disposal ends the shared producer rather than computing or validating a reusable result.
+   *
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Retirement removes all abort listeners, queue references and pipes; a single unreferenced grace timer attempts forced termination and is cleared on exit. OS failure to signal can still leave a running child.
+   */
+  public dispose(): void {
+    if (this.requests.failure !== undefined) return;
+    // If the host already died, reject with its real exit error (stderr + exit
+    // code) rather than a bland "disposed" message.
+    this.fail(
+      this.child.exitCode !== null || this.child.signalCode !== null
+        ? this.exitError()
+        : new Error("ttsc: resident transform host disposed"),
+    );
+  }
+
+  private onLine(line: string): void {
+    if (this.requests.accept(line)) this.terminate();
+  }
+
+  private onReaderClose(): void {
+    if (this.requests.failure === undefined) this.fail(this.exitError());
+  }
+
+  private fail(error: Error): void {
+    if (!this.requests.retire(error)) return;
+    this.terminate();
+  }
+
+  private cancel(pending: PendingRequest, signal: AbortSignal): void {
+    if (pending.settled) return;
+    this.requests.settle(pending, cancelledError(signal));
+    this.fail(
+      new Error(
+        `ttsc: resident transform host retired after another request was cancelled${abortDetail(
+          signal,
+        )}${stderrSuffix(this.stderr)}`,
+      ),
+    );
+  }
+
+  private terminate(): void {
+    this.reader.close();
+    this.child.stdout?.destroy();
+    this.child.stderr?.destroy();
+    const stdin = this.child.stdin;
+    if (stdin !== null && !stdin.destroyed) stdin.destroy();
+    if (this.child.exitCode !== null || this.child.signalCode !== null) return;
+    try {
+      this.child.kill();
+    } catch {
+      // A failed cooperative signal does not cancel the forced attempt.
+    }
+    const force = setTimeout(() => {
+      if (this.child.exitCode !== null || this.child.signalCode !== null) {
+        return;
+      }
+      try {
+        this.child.kill("SIGKILL");
+      } catch {
+        // The host exited between the liveness check and the forced signal.
+      }
+    }, TERMINATION_GRACE_MS);
+    force.unref();
+    this.child.once("exit", () => clearTimeout(force));
+  }
+
+  private exitError(): Error {
+    const detail = this.stderr.trim();
+    if (detail.length !== 0) {
+      return new Error(detail);
+    }
+    // Read the child's own exit fields (set synchronously by Node) so the
+    // message is accurate even before this instance's "exit" handler would run.
+    const code = this.child.exitCode;
+    const signalCode = this.child.signalCode;
+    const signal = signalCode === null ? "" : `, signal ${signalCode}`;
+    return new Error(
+      `ttsc: resident transform host exited (code ${code ?? "null"}${signal})`,
+    );
+  }
+}
+
+/** Cap on retained stderr so a long-lived host cannot grow it without bound. */
+const STDERR_TAIL_LIMIT = 64 * 1024;
+
+/** Allow a cooperative host a short shutdown window before forcing it down. */
+const TERMINATION_GRACE_MS = 1_000;
+
+type PendingRequest = ReturnType<ResidentTransformRequests["add"]>;
+
+function cancelledError(signal: AbortSignal): Error {
+  const error = new Error(
+    `ttsc: resident transform request cancelled${abortDetail(signal)}`,
+  );
+  error.name = "AbortError";
+  return error;
+}
+
+function abortDetail(signal: AbortSignal): string {
+  const reason = signal.reason;
+  if (reason === undefined) return "";
+  try {
+    return `: ${reason instanceof Error ? reason.message : String(reason)}`;
+  } catch {
+    return "";
+  }
+}
+
+function stderrSuffix(stderr: string): string {
+  const detail = stderr.trim();
+  return detail.length === 0 ? "" : `: ${detail}`;
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/compiler/internal/ResidentTransformProcessOptions.ts

@@ -0,0 +1,30 @@
+/**
+ * How to start the resident transform host behind {@link TtscService}.
+ *
+ * The host is spawned once and then answers transform requests over its line
+ * protocol. This record fixes startup executable, argv and spawn authority;
+ * later operation data belongs to the request lane. It does not freeze files or
+ * certify how a custom host responds to configuration changes.
+ *
+ * @evidence contracts/common.md#principled-implementation A fixed executable and argv identify the resident producer; optional cwd and environment retain Node's explicitly documented spawn defaults.
+ * @evidence contracts/common.md#clear-and-simple-design This startup record contains only spawn inputs, keeping later operation and cancellation data outside the fixed project configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native invocation is caller-supplied data rather than a recognized consumer name or a patched child-process implementation.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraph explains fixed configuration, and separated member comments state paths and default meanings following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native executable and cwd representations stay distinct from argv strings; optional environment delegates to Node's supported native spawn behavior.
+ * @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 ResidentTransformProcessOptions {
+  /** Full argv of the host, including its serve subcommand. */
+  args: readonly string[];
+
+  /** Absolute path of the native transform host executable. */
+  binary: string;
+
+  /** Working directory of the host; defaults to the current directory. */
+  cwd?: string;
+
+  /** Environment of the host; defaults to this process's environment. */
+  env?: NodeJS.ProcessEnv;
+}

package/src/compiler/internal/ResidentTransformReply.ts

@@ -0,0 +1,79 @@
+import type { ResidentReplyKind } from "./ResidentReplyKind";
+
+/**
+ * Decode resident reply objects and validate their operation-specific fields.
+ *
+ * Parsing distinguishes malformed JSON or a non-object value from an object
+ * with the wrong reply shape. The transport owns how either failure settles its
+ * FIFO; these operations do not read pipes or manage a resident child.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate object decoding and operation admission preserve the distinction the transport uses for framing failure versus one invalid reply.
+ * @evidence contracts/common.md#clear-and-simple-design One internal namespace owns the two reply-data operations used by the resident transport without acquiring its queue or process state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The decoder and predicate retain ordinary JSON and field checks; no synthetic reply, foreign mutation or alternate host is introduced.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs identify the failure distinction and leave FIFO settlement and child lifetime with the transport.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This namespace groups JSON data operations and defines no native file, path or process boundary.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace container performs no computation; its members own decoding and field checks.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace stores no completed or in-flight results and coordinates no shared request work.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace holds no mutable state, handles or running tasks.
+ */
+export namespace ResidentTransformReply {
+  /**
+   * Parse one JSON object, returning `undefined` for malformed JSON, arrays,
+   * primitives and `null`. An empty object remains an object for the separate
+   * operation-shape check; corrupt data never becomes a synthetic empty reply.
+   *
+   * @evidence contracts/common.md#principled-implementation JSON.parse owns JSON syntax and values; the nonnull object and nonarray checks admit only decoded object records.
+   * @evidence contracts/common.md#clear-and-simple-design One parse attempt followed by object admission leaves reply fields and transport settlement to their owning operations.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Parse failure remains undefined rather than being repaired or replaced with a successful negative reply.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph distinguishes malformed data from the empty object passed to shape validation.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation JSON text and decoded values are data; this operation accesses no filesystem or process.
+   * @evidence contracts/performance.md#efficient-algorithms The native JSON decoder scans the supplied text and allocates its decoded value; object admission uses fixed checks without a second traversal. Input text and decoded population determine time and temporary space.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call decodes its supplied reply; this operation coordinates no completed or in-flight work across requests.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned record transfers to the caller; this operation retains no historical values, handles or tasks and sets no input-size bound.
+   */
+  export function parse(line: string): Record<string, unknown> | undefined {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return undefined;
+    }
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed)
+    ) {
+      return parsed as Record<string, unknown>;
+    }
+    return undefined;
+  }
+
+  /**
+   * Admit a decoded object for the operation the caller requested.
+   *
+   * Transform replies need boolean `found`; a found file also needs string
+   * `typescript`, including empty text. A missing file leaves text irrelevant.
+   * Update replies need boolean `updated`. Extra fields are allowed.
+   *
+   * @evidence contracts/common.md#principled-implementation The requested operation selects its required boolean field, and only a found transform requires text, preserving legitimate negative replies.
+   * @evidence contracts/common.md#clear-and-simple-design Fixed field checks consume the parsed record and operation discriminant without copying payloads or consulting transport state.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing and rejected outcomes remain valid booleans; wrong field types are rejected rather than coerced or inferred from unrelated fields.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph explains empty text, negative replies and permitted extra fields without claiming FIFO or lifecycle coverage.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The operation inspects decoded fields without interpreting filenames or accessing native resources.
+   * @evidence contracts/performance.md#efficient-algorithms Admission performs a fixed number of property reads and type checks on ordinary JSON-decoded records, independent of text or extra-field count. Supplying a different accessor-bearing record can add caller-defined property-read work.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate coordinates no cross-request computation or cached admission result.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Field checks retain no reply, callback, handle or running task after return.
+   */
+  export function isValid(
+    reply: Record<string, unknown>,
+    kind: ResidentReplyKind,
+  ): boolean {
+    if (kind === "transform") {
+      if (typeof reply.found !== "boolean") {
+        return false;
+      }
+      return reply.found ? typeof reply.typescript === "string" : true;
+    }
+    return typeof reply.updated === "boolean";
+  }
+}

package/src/compiler/internal/ResidentTransformRequestOptions.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-request lifecycle controls for a resident transform host.
+ *
+ * @evidence contracts/common.md#principled-implementation An optional AbortSignal represents caller cancellation, with omission leaving the live operation pending until reply or host retirement.
+ * @evidence contracts/common.md#clear-and-simple-design Cancellation belongs to one request rather than the fixed startup record; the transport owns the shared FIFO consequence after enqueueing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The signal uses the supported cancellation interface and introduces no inferred deadline or fixture-dependent abort policy.
+ * @evidence contracts/common.md#meaningful-documentation The native member comment states the otherwise nonobvious in-flight retirement consequence, 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 ResidentTransformRequestOptions {
+  /** Abort this request. An in-flight abort retires the FIFO host. */
+  signal?: AbortSignal;
+}

package/src/compiler/internal/ResidentTransformRequests.ts

@@ -0,0 +1,198 @@
+import type { ResidentReplyKind } from "./ResidentReplyKind";
+import { ResidentTransformReply } from "./ResidentTransformReply";
+
+/**
+ * FIFO promise slots and terminal rejection for one resident reply stream. The
+ * transport owns framing, writing, error construction and child shutdown; this
+ * state owner releases settled callbacks and abort listeners.
+ *
+ * @evidence contracts/common.md#principled-implementation Each admitted slot settles once, head advancement preserves FIFO reply ownership, and retirement becomes terminal before all remaining slots are rejected.
+ * @evidence contracts/common.md#clear-and-simple-design One state owner holds slots, cursor and terminal error; native transport actions remain with ResidentTransformProcess.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual promise callbacks and AbortSignals are retained without constructing a peer, replacing streams or inventing host replies.
+ * @evidence contracts/common.md#meaningful-documentation Native prose bounds this state operation separately from framing, cancellation error policy and native shutdown.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This owner uses JavaScript arrays, callbacks and standard AbortSignal listeners without filesystem or native process operations.
+ * @evidence contracts/performance.md#efficient-algorithms Cursor settlement is amortized constant queue work; consumed prefixes compact only after at least half is consumed, while retirement drains the retained slot array linearly. Callback work remains supplied and is not bounded here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Slots represent distinct live requests, not equivalent computations or a reusable reply cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Settlement releases its queue reference and abort listener; retirement detaches the queue and rejects live slots. Live pending population has no cap or deadline, and native child lifetime remains outside this owner.
+ */
+export class ResidentTransformRequests {
+  /** First terminal error, preserved for later request rejection. */
+  public failure: Error | undefined;
+
+  private readonly pending: (PendingRequest | undefined)[] = [];
+  private pendingHead = 0;
+
+  /**
+   * Current FIFO slot, or no queued reply owner. This read does not consume it.
+   *
+   * @evidence contracts/common.md#principled-implementation The current cursor identifies the single slot that may own the next reply without advancing or inventing an owner.
+   * @evidence contracts/common.md#clear-and-simple-design A read-only cursor lookup separates reply ownership from settlement.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only an admitted array slot is returned; no synthetic request or reply is constructed.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes observing the slot from consuming it.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation In-memory array indexing has no native platform boundary.
+   * @evidence contracts/performance.md#efficient-algorithms One cursor-indexed array read does not scan the pending population.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This is a state lookup, not reusable computation coordination.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned slot remains owned by the queue and caller; this read creates no historical state or handle.
+   */
+  public current(): PendingRequest | undefined {
+    return this.pending[this.pendingHead];
+  }
+
+  /**
+   * Admit one already framed line to its FIFO owner. Malformed or unsolicited
+   * replies retire the stream; an invalid operation shape rejects only its own
+   * slot. Return whether native transport teardown is now required.
+   *
+   * @evidence contracts/common.md#principled-implementation Terminal tails and blank lines are ignored, malformed JSON retires all live slots to prevent shifted ownership, and valid JSON with the wrong operation shape consumes only the current slot.
+   * @evidence contracts/common.md#clear-and-simple-design Existing reply parsing and admission feed the same settlement and retirement owner without taking over native line framing.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual framed text and slot kind drive outcomes; no peer, compiler reply or native-close receipt is invented.
+   * @evidence contracts/common.md#meaningful-documentation Native prose separates stream corruption from operation-shape failure and transport teardown.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation String and JSON admission performs no native stream or process operation.
+   * @evidence contracts/performance.md#efficient-algorithms Trimming and JSON parsing cost line bytes; error echo is capped at 200 code units, settlement is amortized queue work and terminal retirement visits outstanding slots.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each line belongs to one request; no reply result is memoized or reused.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Settlement and retirement release slots/listeners; supplied framed lines have no length bound here, while retained error echoes are capped. Native pipes and child release remain with the transport.
+   */
+  public accept(line: string): boolean {
+    if (this.failure !== undefined) return false;
+    const trimmed = line.trim();
+    if (trimmed.length === 0) return false;
+    const request = this.current();
+    if (request === undefined) {
+      return this.retire(
+        new Error("ttsc: resident transform host sent an unsolicited reply"),
+      );
+    }
+    const reply = ResidentTransformReply.parse(trimmed);
+    if (reply === undefined) {
+      const error = new Error(
+        `ttsc: resident transform host sent a malformed reply: ${echoLine(trimmed)}`,
+      );
+      this.settle(request, error);
+      return this.retire(error);
+    }
+    if (!ResidentTransformReply.isValid(reply, request.kind)) {
+      this.settle(
+        request,
+        new Error(
+          `ttsc: resident transform host sent an invalid ${request.kind} reply: ${echoLine(trimmed)}`,
+        ),
+      );
+      return false;
+    }
+    this.settle(request, reply);
+    return false;
+  }
+
+  /**
+   * Register one slot and its optional abort listener before enqueueing it. The
+   * transport performs its original post-enqueue aborted check and write.
+   *
+   * @evidence contracts/common.md#principled-implementation Resolver identity and expected reply kind stay with one slot; the standard signal listener invokes the owning transport's cancellation operation.
+   * @evidence contracts/common.md#clear-and-simple-design Admission creates the slot, installs its listener and appends it in that order, while write and cancellation policy remain with the transport.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The supplied callback is the production cancellation owner, with no fake stream, peer or host output.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies listener order and the remaining post-enqueue/write responsibility.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Array admission and standard AbortSignal registration perform no native platform operation.
+   * @evidence contracts/performance.md#efficient-algorithms Admission appends one slot and registers at most one listener; callback execution costs belong to the supplied cancellation operation.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every slot represents a distinct request and no computation reuse is selected.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Each live slot retains resolver callbacks and at most one abort listener until settlement or retirement; pending population is uncapped.
+   */
+  public add(
+    kind: ResidentReplyKind,
+    resolve: (reply: Record<string, unknown>) => void,
+    reject: (reason: Error) => void,
+    signal: AbortSignal | undefined,
+    onAbort: (pending: PendingRequest) => void,
+  ): PendingRequest {
+    const pending: PendingRequest = {
+      kind,
+      reject,
+      resolve,
+      settled: false,
+      signal,
+    };
+    if (signal !== undefined) {
+      pending.abort = () => onAbort(pending);
+      signal.addEventListener("abort", pending.abort, { once: true });
+    }
+    this.pending.push(pending);
+    return pending;
+  }
+
+  /**
+   * Settle a slot once, releasing its listener and any matching FIFO head.
+   * Detached slots from retirement still settle but cannot shift a newer head.
+   *
+   * @evidence contracts/common.md#principled-implementation The settled guard prevents duplicate callbacks; head identity controls cursor advancement and Error results reject while object replies resolve.
+   * @evidence contracts/common.md#clear-and-simple-design One settlement operation handles normal replies, write errors, cancellation and detached retirement slots.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Settlement uses the actual supplied result and slot identity without inferring host status or replacing promise callbacks.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes head release, detached slots and exactly-once settlement.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Standard signal listener removal and in-memory promise callbacks need no native platform branch.
+   * @evidence contracts/performance.md#efficient-algorithms Head movement is constant until half-consumed compaction copies the remaining array, giving amortized constant queue work; supplied callback work is additional.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Exactly-once slot settlement is request ownership, not reusable computation selection.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources A settled head clears its array reference, and settlement removes its abort listener before callbacks. A non-head slot can remain referenced until head progression or retirement, with no history retained after detachment.
+   */
+  public settle(
+    pending: PendingRequest,
+    result: Error | Record<string, unknown>,
+  ): 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 (pending.signal !== undefined && pending.abort !== undefined) {
+      pending.signal.removeEventListener("abort", pending.abort);
+    }
+    if (result instanceof Error) pending.reject(result);
+    else pending.resolve(result);
+  }
+
+  /**
+   * Preserve the first failure and reject all remaining slots before the
+   * transport tears down its reader and child. Return whether this call
+   * retired.
+   *
+   * @evidence contracts/common.md#principled-implementation Terminal error assignment precedes queue detachment and rejection, so reentrant callers observe failure and later retirement cannot replace the original error.
+   * @evidence contracts/common.md#clear-and-simple-design State retirement returns a transition indicator; the actual transport alone owns reader, pipe and child termination.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No child exit or stream-close outcome is fabricated from terminal queue state.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies ordering, first-error identity and the caller's remaining native teardown.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Queue detachment and callback settlement are in-memory operations, independent of native signaling.
+   * @evidence contracts/performance.md#efficient-algorithms One array detachment and one visit per retained slot drain the queue; rejection callback work remains additional.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The terminal guard makes a state transition idempotent rather than reusing a computation result.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Detached slots settle and remove listeners; only the terminal Error remains with this owner. Child handles and termination timers remain with the actual transport.
+   */
+  public retire(error: Error): boolean {
+    if (this.failure !== undefined) return false;
+    this.failure = error;
+    const pending = this.pending.splice(0);
+    this.pendingHead = 0;
+    for (const request of pending) {
+      if (request !== undefined) this.settle(request, error);
+    }
+    return true;
+  }
+}
+
+/** Actual resolver callbacks and optional abort listener for one FIFO slot. */
+interface PendingRequest {
+  abort?: () => void;
+  kind: ResidentReplyKind;
+  reject: (reason: Error) => void;
+  resolve: (reply: Record<string, unknown>) => void;
+  settled: boolean;
+  signal?: AbortSignal;
+}
+
+/** Cap on how much of an offending line an error message echoes back. */
+const REPLY_ECHO_LIMIT = 200;
+
+/** Truncate an offending reply line so error messages stay bounded. */
+function echoLine(line: string): string {
+  return line.length > REPLY_ECHO_LIMIT
+    ? `${line.slice(0, REPLY_ECHO_LIMIT)}…`
+    : line;
+}