ttsc 0.32.0 → 0.32.1

package/src/compiler/internal/ResidentCheckProcessHost.ts

@@ -0,0 +1,502 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type Interface, createInterface } from "node:readline";
+import { parentPort, workerData } from "node:worker_threads";
+
+import { E2ETrace } from "../../internal/E2ETrace";
+import type { ResidentCheckProcessOptions } from "./ResidentCheckProcessOptions";
+import type { ResidentCheckProcessProtocol } from "./ResidentCheckProcessProtocol";
+import type { ResidentCheckResult } from "./ResidentCheckResult";
+
+/**
+ * Worker-owned FIFO JSON-line transport for a `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.
+ * This loop owns the child independently of launcher callbacks. Retirement
+ * stops JSON-line assembly, drains raw output, 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. Writing and decoding visit line bytes; caller-defined serialization belongs to the client. 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, stops line assembly and drains raw output 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 ResidentCheckProcessHost {
+  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",
+      ResidentCheckProcessHost.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", ResidentCheckProcessHost.ignoreTransportError);
+      this.child.stderr?.off("data", onStderr);
+      for (const stream of [stdin, stdout, this.child.stderr]) {
+        stream?.off("error", onError);
+        stream?.off("error", ResidentCheckProcessHost.ignoreTransportError);
+        stream?.on("error", ResidentCheckProcessHost.ignoreTransportError);
+        stream?.destroy();
+      }
+      this.child.unref();
+    };
+  }
+
+  /**
+   * Write one caller-serialized JSON line 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.
+   *
+   * The client serializes before crossing the worker boundary. A closed input
+   * retires the host and rejects its other pending calls.
+   *
+   * @evidence contracts/common.md#principled-implementation The caller supplies one serialized line, 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 A closed pipe retires all pending requests rather than treating the host as healthy with one exceptional caller.
+   * @evidence contracts/common.md#meaningful-documentation Separate paragraphs document serialized input, 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 Writing visits serialized input bytes; 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 transport retains one resolver pair and its queued line per outstanding call until reply or retirement; live requests wait without an implicit timeout or population limit.
+   */
+  public request(line: string): 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);
+    }
+    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;
+    // A kill request can race with a natural exit. Actual zero-status close
+    // remains graceful even when the request reached an already exiting child.
+    if (this.forced && this.child.signalCode === "SIGKILL")
+      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);
+    }
+    // Retirement has already rejected every reply slot. Drain raw output rather
+    // than assembling unbounded JSON lines while shutdown timers are active.
+    this.reader.close();
+    this.child.stdout?.resume();
+    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 readable until actual close: destroying inherited pipes would
+    // conceal a descendant that still owns them and falsely authorize reuse.
+    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));
+}
+
+// Every retirement observation stays on this loop. Moving only timers to a
+// worker would still let a parent-side verdict overtake pending exit and pipe
+// events, and treating worker exit as child close would lose descendant safety.
+if (parentPort !== null) {
+  const port = parentPort;
+  const host = new ResidentCheckProcessHost(
+    workerData as ResidentCheckProcessOptions,
+  );
+  port.on("message", (command: ResidentCheckProcessProtocol.Command) => {
+    if (command.kind === "retire") host.dispose();
+    else
+      void host.request(command.line).then(
+        (result) =>
+          port.postMessage({
+            kind: "result",
+            id: command.id,
+            result,
+          } satisfies ResidentCheckProcessProtocol.Reply),
+        (error: Error) =>
+          port.postMessage({
+            kind: "error",
+            id: command.id,
+            error,
+          } satisfies ResidentCheckProcessProtocol.Reply),
+      );
+  });
+  port.once("close", () => host.dispose());
+  void host.waitForExit().then(
+    async () => {
+      let closeError: Error | undefined;
+      try {
+        await host.close();
+      } catch (error) {
+        closeError = asError(error);
+      }
+      port.postMessage({
+        kind: "terminal",
+        closeError,
+      } satisfies ResidentCheckProcessProtocol.Reply);
+      port.close();
+    },
+    (joinError: Error) => {
+      port.postMessage({
+        kind: "terminal",
+        joinError,
+        closeError: joinError,
+      } satisfies ResidentCheckProcessProtocol.Reply);
+      port.close();
+    },
+  );
+}

package/src/compiler/internal/ResidentCheckProcessProtocol.ts

@@ -0,0 +1,53 @@
+import type { ResidentCheckResult } from "./ResidentCheckResult";
+
+/**
+ * Messages between one resident client and its isolated process owner. Request
+ * identifiers pair concurrent callers; only the owner's terminal receipt
+ * establishes child-close authority. Errors use structured cloning.
+ *
+ * @evidence contracts/common.md#principled-implementation Discriminated messages separate request results from the actual-close verdict and strict shutdown status.
+ * @evidence contracts/common.md#clear-and-simple-design One private protocol connects the client and its one process owner without exposing worker transport to consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Worker departure is absent from the successful join receipt; it cannot substitute for child close.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains correlation, ownership and error transport.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation These data types define no native boundary; the client and host own worker and child creation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace describes data rather than choosing an execution algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Messages describe independent operations without caching results.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Types retain no resources; the client and host own queued requests and worker lifetime.
+ */
+export namespace ResidentCheckProcessProtocol {
+  /**
+   * Parent commands preserve request order before the terminal retire command.
+   * Request lines were serialized by the caller before admission.
+   *
+   * @evidence contracts/common.md#principled-implementation A discriminant separates serialized request admission from terminal retirement; numeric identifiers correlate independent callers.
+   * @evidence contracts/common.md#clear-and-simple-design Two command variants express the only supported parent operations without duplicating native shutdown state.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Commands carry actual caller data and retirement intent rather than fabricated native results.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains ordering and serialized-line admission.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The data declaration performs no filesystem, path or process operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms A command type selects no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A command type performs no reusable work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The declaration owns no live queue, worker or native handle.
+   */
+  export type Command =
+    | { kind: "request"; id: number; line: string }
+    | { kind: "retire" };
+
+  /**
+   * Owner replies separate request outcomes from native lifetime authority.
+   * Absent joinError certifies actual child close; closeError independently
+   * preserves strict shutdown failure for a joined child.
+   *
+   * @evidence contracts/common.md#principled-implementation Terminal joining and strict status are independent outcomes, allowing replacement of a joined failed host while refusing unknown ownership.
+   * @evidence contracts/common.md#clear-and-simple-design Request results use the request identifier, and one terminal receipt carries the host's two lifetime outcomes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The successful receipt requires actual child close; worker disappearance is not represented as success.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains absent join failure and independent strict status.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The data declaration performs no filesystem, path or process operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms A reply type selects no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A reply type performs no reusable work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The declaration owns no live reply queue, worker or native handle.
+   */
+  export type Reply =
+    | { kind: "result"; id: number; result: ResidentCheckResult }
+    | { kind: "error"; id: number; error: Error }
+    | { kind: "terminal"; joinError?: Error; closeError?: Error };
+}