@specific.dev/spectest 0.128.0 → 0.129.0

package/src/terminal.ts

@@ -20,7 +20,7 @@
 //
 // PTY-on-the-host trick: the daemon runs under systemd with no controlling
 // TTY, so `docker exec -it` (the docker CLI rejects -it when its own stdin
-// isn't a TTY) needs a PTY wrapper. `script -qfc 'CMD' /dev/null` allocates
+// isn't a TTY) needs a PTY wrapper. `script -qfec 'CMD' /dev/null` allocates
 // a PTY for CMD; we set the slave's size with `stty rows R cols C` inside
 // the wrapped command so the container app sees the cols/rows the caller
 // asked for. `script(1)` ships in util-linux which is essential on Debian,
@@ -30,7 +30,7 @@ import { Terminal as XtermHeadless } from "@xterm/headless";
 
 import { recordTerminalStep, reserveEvent, truncateUtf8 } from "./recorder.js";
 import type { EventReservation } from "./recorder.js";
-import type { TerminalStepAction } from "./recorder.js";
+import type { TerminalStepAction, TerminalWaitMatcher, TerminalWaitOutcome } from "./recorder.js";
 import { wrap } from "./inspect.js";
 // One default deadline for "wait until the app shows it", whichever surface
 // the author is watching — see the constant for why it is what it is.
@@ -64,6 +64,28 @@ export interface TerminalOpts {
   timeoutMs?: number;
 }
 
+/** A visible terminal failure that should stop a wait immediately. */
+export interface TerminalFailureCondition {
+  description: string;
+  matcher: string | RegExp;
+}
+
+export interface TerminalWaitOptions {
+  timeoutMs?: number;
+  intervalMs?: number;
+  /** Cancel this observation without closing the terminal. */
+  signal?: AbortSignal;
+  /** Describe a custom predicate's condition separately from the step title. */
+  condition?: string;
+  /** Checked against the rendered screen before the success matcher. */
+  failOn?: readonly TerminalFailureCondition[];
+}
+
+export interface TerminalCloseOptions {
+  /** Total deadline including graceful exit, kill and pipe drain. Default 10 s. */
+  timeoutMs?: number;
+}
+
 /** Result of the one-shot `ctx.terminal(...)` convenience. */
 export interface TerminalResult {
   /** Full decoded PTY output (raw bytes, ANSI escapes included). Capped. */
@@ -90,7 +112,8 @@ export interface Terminal {
   /**
    * Resolves when the underlying process ends — by `close()`, by the
    * inner command exiting, or by timeout — to a `TerminalResult` with
-   * the full captured `output` and `exitCode`. Never rejects.
+   * the full captured `output` and `exitCode`. Rejects if output cannot
+   * be drained after exit.
    *
    * The result is provenance-tagged against the `exit` step, so an
    * `expect((await term.exited).output).toContain(...)` /
@@ -133,23 +156,26 @@ export interface Terminal {
    * `description` is a short human label that shows up in the event
    * log so timelines don't fill with anonymous waits.
    *
-   * Defaults: 5 s total timeout, 100 ms between polls. Throws on
-   * timeout.
+   * Defaults: 10 s total timeout, 100 ms between polls. Throws on timeout,
+   * a failure condition, predicate error, cancellation, or process exit before
+   * a match. On exit the final drained screen is checked first. Async custom
+   * predicates are supported; cancellation stops polling but cannot forcibly
+   * cancel work started by the predicate itself.
    */
   waitFor(
     description: string,
     matcher: string,
-    opts?: { timeoutMs?: number; intervalMs?: number },
+    opts?: TerminalWaitOptions,
   ): Promise<Wrapped<string>>;
   waitFor(
     description: string,
     matcher: RegExp,
-    opts?: { timeoutMs?: number; intervalMs?: number },
+    opts?: TerminalWaitOptions,
   ): Promise<Wrapped<RegExpMatchArray>>;
   waitFor<T = unknown>(
     description: string,
     matcher: (screen: string, output: string) => T,
-    opts?: { timeoutMs?: number; intervalMs?: number },
+    opts?: TerminalWaitOptions,
   ): Promise<Wrapped<NonNullable<Awaited<T>>>>;
 
   /**
@@ -157,9 +183,9 @@ export interface Terminal {
    * SIGKILLs after a grace period. Idempotent. Resolves to a
    * `TerminalResult` (tagged against the `close` step) so you can assert
    * on the transcript of a session that doesn't self-terminate. Optional
-   * — terminals are not auto-closed when a test ends.
+   * — terminals are not auto-closed when a test ends. Rejects on cleanup timeout.
    */
-  close(): Promise<Wrapped<TerminalResult>>;
+  close(opts?: TerminalCloseOptions): Promise<Wrapped<TerminalResult>>;
 }
 
 /**
@@ -270,9 +296,10 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
   // 80x24, but the daemon has none, so it's whatever util-linux picks
   // as the fallback).
   const inner = `stty rows ${rows} cols ${cols} 2>/dev/null; exec ${shellQuote(["docker", ...dockerArgs])}`;
-  // `script -q -f -c CMD /dev/null` runs CMD in a PTY (no preamble, flushed
+  // `script -q -f -e -c CMD /dev/null` runs CMD in a PTY (no preamble, flushed
   // after each write, output discarded — we capture via stdout pipe).
-  const spawnArgs = ["script", "-qfc", inner, "/dev/null"];
+  // -e preserves the child command status; without it script reports 0 on failure.
+  const spawnArgs = ["script", "-qfec", inner, "/dev/null"];
 
   const start = Date.now();
   const proc = Bun.spawn(spawnArgs, {
@@ -295,15 +322,23 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
   let exitCode: number | undefined;
   let closed = false;
   let resolveExit!: (code: number) => void;
-  const rawExited = new Promise<number>((res) => {
+  let rejectExit!: (error: unknown) => void;
+  let exitSettled = false;
+  const exitWaiters = new Set<() => void>();
+  const cancelWaits = new Set<() => void>();
+  const rawExited = new Promise<number>((res, reject) => {
     resolveExit = res;
+    rejectExit = reject;
   });
+  // Lifecycle errors are observed by waitFor/exited/close, possibly much later.
+  void rawExited.catch(() => {});
   // Cast time at the moment the process actually exited. Captured by
   // the IIFE below so the `exit` step we record points the player at
   // the very end of the visible session.
   let exitCastTimeSec: number | undefined;
 
-  const decoder = new TextDecoder("utf-8", { fatal: false });
+  let outputEnded = false;
+  const readers = new Set<ReadableStreamDefaultReader<Uint8Array>>();
   // Subscribers waiting for the next frame to arrive. Used by send /
   // sendLine / press so the recorded `castTimeSec` lands on the echo's
   // frame instead of microseconds before it.
@@ -320,12 +355,14 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
   // millisecond as the following `sendLine`'s echo showed that echo
   // — the replay ran one step ahead of the step list.
   let lastFrameT = 0;
+  let lastRenderedFrameT = 0;
   const ingest = (chunk: string): void => {
+    if (outputEnded) return;
     let t = (Date.now() - start) / 1000;
     if (t <= lastFrameT) t = lastFrameT + 0.001;
     lastFrameT = t;
     sink.pushFrame(t, chunk);
-    emu.write(chunk);
+    emu.write(chunk, () => { lastRenderedFrameT = t; });
     if (output.length < OUTPUT_CAP_BYTES) {
       const room = OUTPUT_CAP_BYTES - output.length;
       output += chunk.length > room ? chunk.slice(0, room) : chunk;
@@ -348,10 +385,13 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
       const finish = (): void => {
         if (done) return;
         done = true;
+        clearTimeout(timeout);
+        const index = frameWaiters.indexOf(finish);
+        if (index >= 0) frameWaiters.splice(index, 1);
         resolve();
       };
+      const timeout = setTimeout(finish, timeoutMs);
       frameWaiters.push(finish);
-      setTimeout(finish, timeoutMs);
     });
   };
 
@@ -360,19 +400,31 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
   ): Promise<void> => {
     if (!stream) return;
     const reader = stream.getReader();
+    const decoder = new TextDecoder("utf-8", { fatal: false });
+    readers.add(reader);
     try {
       while (true) {
         const { done, value } = await reader.read();
-        if (done) return;
+        if (done) {
+          const tail = decoder.decode();
+          if (tail) ingest(tail);
+          return;
+        }
         if (!value || value.byteLength === 0) continue;
         const chunk = decoder.decode(value, { stream: true });
         if (chunk.length === 0) continue;
         ingest(chunk);
       }
     } finally {
+      readers.delete(reader);
       reader.releaseLock();
     }
   };
+  const stopOutput = () => {
+    outputEnded = true;
+    for (const reader of readers) void reader.cancel().catch(() => {});
+  };
+  const flushScreen = () => new Promise<void>((resolve) => emu.write("", resolve));
 
   // Drain stdout + stderr concurrently. `script` writes everything to
   // stdout under `-t`, but we drain stderr anyway in case script(1)
@@ -380,6 +432,7 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
   const stdout = proc.stdout as ReadableStream<Uint8Array> | null | undefined;
   const stderr = proc.stderr as ReadableStream<Uint8Array> | null | undefined;
   const drained = Promise.all([drainStream(stdout), drainStream(stderr)]);
+  void drained.catch(() => {});
 
   // Race the optional session-level timeout. For interactive terminals
   // we usually have no timeout; the wrapper for one-shot supplies one.
@@ -396,28 +449,28 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
     }, opts.timeoutMs);
   }
 
-  // When the process exits, drain whatever's left and resolve `exited`.
-  // We don't await `drained` here — it's already running and will
-  // settle on its own; the explicit `await drained` happens in close().
-  (async () => {
-    const code = await proc.exited;
-    exited = true;
-    exitCode = code;
-    if (timer) clearTimeout(timer);
-    // Let `drained` finish so the final asciicast frames land before we
-    // mark the sink closed. drainStream is bounded by the OS pipe being
-    // closed when proc exits, so this won't hang.
+  // A child may inherit a pipe after the PTY wrapper exits. Bound the drain,
+  // and flush xterm's asynchronous writes before exposing the final screen.
+  void (async () => {
     try {
-      await drained;
-    } catch {
-      /* ignore */
+      const code = await proc.exited;
+      exited = true;
+      exitCode = code;
+      if (timer) clearTimeout(timer);
+      await within(drained.then(flushScreen), 5_000, "Terminal output did not finish draining within 5000ms");
+      exitCastTimeSec = lastRenderedFrameT + 0.0005;
+      sink.markClosed();
+      resolveExit(code);
+    } catch (error) {
+      stopOutput();
+      sink.markClosed();
+      rejectExit(error);
+    } finally {
+      exitSettled = true;
+      if (timer) clearTimeout(timer);
+      for (const wake of exitWaiters) wake();
+      exitWaiters.clear();
     }
-    // Record cast time AFTER drain, so the `exit` step we record below
-    // points the player at the very last frame (the program's final
-    // output before EOF). Same between-frames stamp as `recordOpEvent`.
-    exitCastTimeSec = lastFrameT + 0.0005;
-    sink.markClosed();
-    resolveExit(code);
   })();
 
   // Helper to write raw bytes to the PTY. We treat stdin as binary
@@ -425,8 +478,9 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
   // a FileSink-like depending on the version — use the FileSink-style
   // `write(string)` which both shapes accept).
   const stdinWriter = proc.stdin as { write(s: string): unknown; flush?(): unknown } | undefined;
-  const writeStdin = async (data: string): Promise<void> => {
-    if (exited || closed || !stdinWriter) return;
+  const writeStdin = async (data: string, closing = false): Promise<void> => {
+    if (exited || (closed && !closing) || !stdinWriter)
+      throw new Error(`Terminal ${JSON.stringify(service)} is ${exited ? "exited" : "closed"}`);
     stdinWriter.write(data);
     try {
       const r = stdinWriter.flush?.();
@@ -505,9 +559,15 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
   let exitedAccessor: Promise<Wrapped<TerminalResult>> | undefined;
   const getExited = (): Promise<Wrapped<TerminalResult>> => {
     if (exitedAccessor) return exitedAccessor;
-    const resv = reserveEvent();
     exitedAccessor = (async () => {
-      const code = await rawExited;
+      let code: number;
+      try { code = await rawExited; }
+      catch (error) {
+        recordOpEvent("exit", { exitCode }, Date.now(), errorMessage(error));
+        throw error;
+      }
+      // Reserve on actual completion, not when .exited is read for a race.
+      const resv = reserveEvent();
       const result = buildResult(code);
       // No recorder (eval/setup): there's no event to nest under, but we
       // still wrap (with an undefined seq) so the accessor's wrapped type is
@@ -533,6 +593,8 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
     return exitedAccessor;
   };
 
+  let closePromise: Promise<Wrapped<TerminalResult>> | undefined;
+
   const handle: InternalTerminal = {
     cols,
     rows,
@@ -615,102 +677,190 @@ export async function openTerminal(args: OpenTerminalArgs): Promise<InternalTerm
     async waitFor(
       description: string,
       matcher: string | RegExp | ((screen: string, output: string) => unknown),
-      waitOpts?: { timeoutMs?: number; intervalMs?: number },
+      waitOpts?: TerminalWaitOptions,
     ) {
-      const timeoutMs = waitOpts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
-      const intervalMs = waitOpts?.intervalMs ?? 100;
+      const timeoutMs = durationOption(waitOpts?.timeoutMs, DEFAULT_ACTION_TIMEOUT_MS, "timeoutMs");
+      const intervalMs = durationOption(waitOpts?.intervalMs, 100, "intervalMs");
       const t = Date.now();
       const resv = reserveEvent();
-      const deadline = t + timeoutMs;
+      const castStartTimeSec = Math.max((t - start) / 1000, lastFrameT + 0.0005);
+      const condition: TerminalWaitMatcher = typeof matcher === "function"
+        ? { kind: "custom", ...(waitOpts?.condition ? { description: waitOpts.condition } : {}) }
+        : describeMatcher(matcher);
+      const failureMatchers = waitOpts?.failOn?.map(({ description, matcher }) => ({
+        description, matcher: describeMatcher(matcher),
+      }));
       let attempts = 0;
-      const check = (): unknown => {
-        attempts++;
-        const scr = renderScreen();
-        if (typeof matcher === "string") {
-          return scr.includes(matcher) ? matcher : null;
-        }
-        if (matcher instanceof RegExp) {
-          const m = scr.match(matcher);
-          return m ?? null;
-        }
-        return matcher(scr, output);
+      let observed: { castTimeSec: number; screenPreview: string; screenTruncated: boolean } | undefined;
+      let outcome: TerminalWaitOutcome = "predicate_error";
+      const control = new AbortController();
+      const cancel = () => {
+        outcome = "cancelled";
+        control.abort(waitOpts?.signal?.reason ?? new Error(`waitFor ${JSON.stringify(description)} cancelled: terminal closed`));
       };
-      while (true) {
-        const v = check();
-        if (v) {
-          const seq = recordOpEvent("waitFor", { description, attempts, matched: true }, t, undefined, resv);
-          // Tag the matched value so an `expect(...)` on it links its
-          // assertion back to this waitFor step (sourceSeq) instead of
-          // rendering as an orphan sidebar row. Mirrors how http/db/exec
-          // results carry their op's seq. `as never` lets this single
-          // body satisfy the three overload return types.
-          return wrap(v, seq) as never;
-        }
-        if (Date.now() >= deadline) {
-          const err = `waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`;
-          recordOpEvent(
-            "waitFor",
-            { description, attempts, matched: false },
-            t,
-            err,
-            resv,
-          );
-          throw new Error(err);
+      const timeout = setTimeout(() => {
+        outcome = "timed_out";
+        control.abort(new Error(`waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`));
+      }, timeoutMs);
+      cancelWaits.add(cancel);
+      waitOpts?.signal?.addEventListener("abort", cancel, { once: true });
+      if (waitOpts?.signal?.aborted || closed) cancel();
+      const waitFields = () => ({
+        description, attempts, matched: outcome === "matched", outcome,
+        matcher: condition, failureMatchers, timeoutMs, intervalMs,
+        ...(outcome === "process_exited" ? { exitCode } : {}),
+        castStartTimeSec,
+        castEndTimeSec: castStartTimeSec + (Date.now() - t) / 1000,
+      });
+      const pause = () => new Promise<void>((resolve, reject) => {
+        const cleanup = () => {
+          clearTimeout(poll);
+          exitWaiters.delete(wake);
+          control.signal.removeEventListener("abort", abort);
+        };
+        const wake = () => { cleanup(); resolve(); };
+        const abort = () => { cleanup(); reject(control.signal.reason); };
+        const poll = setTimeout(wake, intervalMs);
+        exitWaiters.add(wake);
+        control.signal.addEventListener("abort", abort, { once: true });
+        if (control.signal.aborted) abort();
+        else if (exitSettled) wake();
+      });
+      try {
+        while (true) {
+          control.signal.throwIfAborted();
+          if (exited || exitSettled) {
+            try { await withSignal(rawExited, control.signal); }
+            catch (error) {
+              if (!control.signal.aborted) outcome = "process_exited";
+              throw error;
+            }
+          }
+          control.signal.throwIfAborted();
+          const checkedFinalScreen = exitSettled;
+          const screen = renderScreen();
+          const preview = truncateUtf8(screen);
+          observed = { castTimeSec: lastRenderedFrameT + 0.0005,
+            screenPreview: preview.value, screenTruncated: preview.truncated };
+          attempts++;
+          for (const failure of waitOpts?.failOn ?? []) {
+            if (matchScreen(screen, failure.matcher)) {
+              outcome = "failure_matched";
+              throw new Error(`waitFor ${JSON.stringify(description)} failed: ${failure.description}`);
+            }
+          }
+          const observedOutput = output;
+          const value = typeof matcher === "function"
+            ? await withSignal(Promise.resolve().then(() => {
+              control.signal.throwIfAborted();
+              return matcher(screen, observedOutput);
+            }), control.signal)
+            : matchScreen(screen, matcher);
+          control.signal.throwIfAborted();
+          if (value) {
+            outcome = "matched";
+            const seq = recordOpEvent("waitFor", { ...waitFields(), ...observed }, t, undefined, resv);
+            return wrap(value, seq) as never;
+          }
+          if (exitSettled && !checkedFinalScreen) continue;
+          if (exitSettled) {
+            outcome = "process_exited";
+            throw new Error(`waitFor ${JSON.stringify(description)} failed: terminal exited with code ${exitCode} before the condition matched`);
+          }
+          await pause();
         }
-        await new Promise((r) => setTimeout(r, intervalMs));
+      } catch (error) {
+        recordOpEvent("waitFor", { ...waitFields(),
+          ...((outcome === "predicate_error" || outcome === "failure_matched") ? observed : {}),
+        }, t, errorMessage(error), resv);
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+        cancelWaits.delete(cancel);
+        waitOpts?.signal?.removeEventListener("abort", cancel);
       }
     },
-    async close() {
-      // Use `rawExited` rather than `term.exited` everywhere we need a
-      // raw number internally — the public getter resolves to a wrapped
-      // result (and records an `exit` step on first read) which we don't
-      // want as a side-effect of internal teardown logic.
-      if (closed)
-        return buildResult(
-          exitCode ?? (await rawExited),
-        ) as unknown as Wrapped<TerminalResult>;
-      closed = true;
+    close(closeOpts?: TerminalCloseOptions) {
+      if (closePromise) return closePromise;
+      const timeoutMs = durationOption(closeOpts?.timeoutMs, 10_000, "timeoutMs");
       const t = Date.now();
       const resv = reserveEvent();
-      // Polite first: send EOF (Ctrl-D). For a login shell this exits
-      // cleanly. For a long-running command it's a no-op and we fall
-      // through to SIGKILL.
-      try {
-        await writeStdin("\x04");
-      } catch {
-        /* ignore */
-      }
-      // Closing stdin signals EOF to the script wrapper too.
-      try {
-        (proc.stdin as { end?: () => void } | undefined)?.end?.();
-      } catch {
-        /* ignore */
-      }
-      // Grace period before forcibly killing.
-      const grace = 1_500;
-      const raced = await Promise.race([
-        rawExited,
-        new Promise<"timeout">((r) => setTimeout(() => r("timeout"), grace)),
-      ]);
-      if (raced === "timeout") {
+      closed = true;
+      for (const cancel of cancelWaits) cancel();
+      closePromise = (async () => {
         try {
-          proc.kill();
-        } catch {
-          /* ignore */
+          if (!exited) {
+            // Send EOF even though new user operations are now closed.
+            try { await writeStdin("\x04", true); } catch { /* already exited */ }
+            try { (proc.stdin as { end?: () => void } | undefined)?.end?.(); } catch { /* already closed */ }
+          }
+          const grace = Math.min(1_500, timeoutMs / 2);
+          let graceTimer: ReturnType<typeof setTimeout> | undefined;
+          const finished = await Promise.race([
+            rawExited.then(() => true),
+            new Promise<false>((resolve) => { graceTimer = setTimeout(() => resolve(false), grace); }),
+          ]).finally(() => clearTimeout(graceTimer));
+          if (!finished && !exited) {
+            try { proc.kill("SIGKILL"); } catch { /* process already gone */ }
+          }
+          const code = await within(rawExited, Math.max(0, timeoutMs - (Date.now() - t)),
+            `Terminal close timed out after ${timeoutMs}ms`);
+          const result = buildResult(code);
+          const seq = recordOpEvent("close", { exitCode: code }, t, undefined, resv);
+          return wrap(result, seq) as unknown as Wrapped<TerminalResult>;
+        } catch (error) {
+          if (!exited) { try { proc.kill("SIGKILL"); } catch { /* best effort */ } }
+          stopOutput();
+          if (timer) clearTimeout(timer);
+          recordOpEvent("close", { exitCode }, t, errorMessage(error), resv);
+          throw error;
         }
-      }
-      const code = await rawExited;
-      const result = buildResult(code);
-      const seq = recordOpEvent("close", { exitCode: code }, t, undefined, resv);
-      // Tag the result against the close step so assertions on the
-      // transcript of a non-self-terminating session nest under it.
-      return wrap(result, seq) as unknown as Wrapped<TerminalResult>;
+      })();
+      return closePromise;
     },
   };
 
   return handle;
 }
 
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function durationOption(value: number | undefined, fallback: number, name: string): number {
+  const duration = value ?? fallback;
+  if (!Number.isFinite(duration) || duration < 0) throw new Error(`${name} must be a finite non-negative number`);
+  return duration;
+}
+
+function describeMatcher(matcher: string | RegExp): TerminalWaitMatcher {
+  return typeof matcher === "string" ? { kind: "text", value: matcher }
+    : { kind: "regex", value: matcher.source, flags: matcher.flags };
+}
+
+function matchScreen(screen: string, matcher: string | RegExp) {
+  return typeof matcher === "string" ? (screen.includes(matcher) ? matcher : null)
+    : screen.match(new RegExp(matcher.source, matcher.flags));
+}
+
+function withSignal<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    if (signal.aborted) {
+      signal.removeEventListener("abort", abort);
+      abort();
+    }
+  });
+}
+
+function within<T>(work: Promise<T>, ms: number, message: string): Promise<T> {
+  const control = new AbortController();
+  const timer = setTimeout(() => control.abort(new Error(message)), ms);
+  return withSignal(work, control.signal).finally(() => clearTimeout(timer));
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Key name → byte sequence
 // ────────────────────────────────────────────────────────────────────────