infinity-harness 2.0.0

package/src/core/brief.ts

@@ -0,0 +1,242 @@
+/**
+ * infinity-harness — the brief.
+ *
+ * The brief answers one question: "what do I do right now?" It is injected at
+ * session start and after every phase change, so it has to be complete enough
+ * that an agent needs no other context, and short enough that it does not
+ * crowd out the work. Everything in it is derived from state on disk — the
+ * brief never invents a plan.
+ */
+
+import type { Brief, GateResult, HarnessConfig, Phase } from "./types.ts";
+import { PHASE_ROLE } from "./types.ts";
+import { loadConfig, getRetryConfig, isRetryExhausted } from "./config.ts";
+import {
+  loadFeatureList,
+  computeProgress,
+  nextActionableTask,
+  findFeature,
+  flattenTasks,
+} from "./featureList.ts";
+import { runChecks } from "./gates.ts";
+import { getPhaseOrder, nextPhase, isFinalPhase } from "./phases.ts";
+import * as P from "./paths.ts";
+import { readText } from "./fsx.ts";
+
+const PHASE_INTENT: Record<Phase, string> = {
+  init: "Set up the project skeleton and confirm the harness can see it.",
+  define: "Write down what is being built and how you will know it is done. Acceptance criteria per feature.",
+  plan: "Break each feature into ordered, dependency-aware tasks. No code yet.",
+  build: "Implement the current task. One task at a time, tests alongside.",
+  verify: "Prove the work behaves. Run the suite, look for what the tests do not cover.",
+  simplify: "Delete more than you add. Collapse duplication, drop dead paths.",
+  review: "Judge this as if someone else wrote it. Score it against the rubric.",
+  ship: "Tag, changelog, and leave the tree clean.",
+};
+
+export type BuildBriefOptions = {
+  /** Run the gate to include a live verdict. Costs a lint/test run. */
+  includeGate?: boolean;
+};
+
+export async function buildBrief(targetDir: string, options: BuildBriefOptions = {}): Promise<Brief> {
+  const { config, ok } = loadConfig(targetDir);
+  const { list } = loadFeatureList(targetDir);
+  const progress = computeProgress(list);
+  const phase = config.currentPhase;
+  const role = phase ? PHASE_ROLE[phase] : null;
+
+  const notes: string[] = [];
+  if (!ok) notes.push("harness/config.json is missing or unreadable — run init.");
+
+  const nextTask = nextActionableTask(list);
+  const feature = nextTask ? findFeature(list, nextTask.featureId) : null;
+
+  let gate: GateResult | null = null;
+  if (options.includeGate && phase) {
+    gate = await runChecks(targetDir, phase, { record: false });
+  }
+
+  const retry = getRetryConfig(config);
+  const exhausted = isRetryExhausted(config);
+  if (exhausted.exhausted) {
+    notes.push(
+      `Retry budget for ${exhausted.which} is exhausted. Stop and escalate to the human rather than retrying again.`,
+    );
+  }
+
+  const blockedTasks = flattenTasks(list).filter((t) => t.status === "blocked");
+  if (blockedTasks.length > 0) {
+    notes.push(`${blockedTasks.length} task(s) are blocked: ${blockedTasks.map((t) => t.compositeKey).join(", ")}`);
+  }
+
+  const complete = isFinalPhase(phase, config.phases?.enabled) && progress.tasksDone === progress.tasksTotal;
+
+  return {
+    phase,
+    role,
+    paused: Boolean(config.paused),
+    complete,
+    goal: (list.goals ?? [])[0]?.title ?? null,
+    feature: feature ? { id: feature.id, name: feature.name } : null,
+    task: nextTask
+      ? {
+          id: nextTask.id,
+          key: nextTask.compositeKey,
+          description: nextTask.description,
+          status: nextTask.status,
+        }
+      : null,
+    criteria: collectCriteria(feature, nextTask?.criteria),
+    validateCommand: "harness validate",
+    gate,
+    progress: {
+      tasksDone: progress.tasksDone,
+      tasksTotal: progress.tasksTotal,
+      featuresDone: progress.featuresDone,
+      featuresTotal: progress.featuresTotal,
+    },
+    retries: {
+      task: config.taskRetryCount ?? 0,
+      feature: config.featureRetryCount ?? 0,
+      phase: config.phaseRetryCount ?? 0,
+      max: retry.tasks.max,
+    },
+    notes,
+  };
+}
+
+function collectCriteria(
+  feature: { criteria?: string[] } | null,
+  taskCriteria: string[] | undefined,
+): string[] {
+  const out: string[] = [];
+  if (Array.isArray(taskCriteria)) out.push(...taskCriteria);
+  if (out.length === 0 && Array.isArray(feature?.criteria)) out.push(...feature.criteria);
+  return out;
+}
+
+// ── Rendering ───────────────────────────────────────────────────────────────
+
+const RULE = "─".repeat(64);
+
+/**
+ * Render the brief as the text injected into the agent's context.
+ * Deliberately plain: this is read by a model, not a terminal, so it carries
+ * no colour and no box drawing that would waste tokens.
+ */
+export function renderBrief(brief: Brief, config?: HarnessConfig): string {
+  const L: string[] = [];
+  const phase = (brief.phase ?? "not started").toUpperCase();
+
+  if (brief.paused) {
+    L.push("HARNESS PAUSED");
+    L.push("");
+    L.push("The pipeline is paused. Do not continue autonomously — tell the human and stop.");
+    return L.join("\n");
+  }
+
+  if (brief.complete) {
+    L.push("PIPELINE COMPLETE");
+    L.push("");
+    L.push(`All ${brief.progress.tasksTotal} task(s) across ${brief.progress.featuresTotal} feature(s) are done`);
+    L.push("and the final phase has passed. Report to the human; do not start new work.");
+    return L.join("\n");
+  }
+
+  L.push(RULE);
+  const head = [`NEXT STEP · ${phase}`];
+  if (brief.feature) head.push(brief.feature.id);
+  if (brief.task) head.push(brief.task.key);
+  L.push(head.join(" · "));
+  L.push(RULE);
+  L.push("");
+
+  if (brief.goal) {
+    L.push(`GOAL     ${brief.goal}`);
+  }
+  if (brief.role) {
+    L.push(`ROLE     ${brief.role} — ${PHASE_INTENT[brief.phase!]}`);
+  }
+  if (brief.feature) {
+    L.push(`FEATURE  ${brief.feature.id} · ${brief.feature.name}`);
+  }
+  if (brief.task) {
+    L.push(`TASK     ${brief.task.key} [${brief.task.status}]`);
+    L.push(`         ${brief.task.description}`);
+  } else {
+    L.push("TASK     (none actionable — every remaining task is blocked or the plan is empty)");
+  }
+
+  L.push("");
+  L.push(
+    `PROGRESS ${brief.progress.tasksDone}/${brief.progress.tasksTotal} tasks · ` +
+      `${brief.progress.featuresDone}/${brief.progress.featuresTotal} features · ` +
+      `retries ${brief.retries.task}/${brief.retries.max}`,
+  );
+
+  if (config) {
+    const order = getPhaseOrder(config.phases?.enabled);
+    const marked = order
+      .map((p) => (p === brief.phase ? `[${p.toUpperCase()}]` : p))
+      .join(" → ");
+    L.push(`PIPELINE ${marked}`);
+  }
+
+  if (brief.criteria.length) {
+    L.push("");
+    L.push("ACCEPTANCE CRITERIA");
+    for (const c of brief.criteria) L.push(`  - ${c}`);
+  }
+
+  if (brief.gate) {
+    L.push("");
+    L.push(`GATE     ${brief.gate.overall ? "PASS" : "FAIL"}`);
+    for (const c of brief.gate.checks) {
+      const mark = c.advisory ? "·" : c.pass ? "+" : "x";
+      L.push(`  ${mark} ${c.name}: ${c.detail}`);
+    }
+  }
+
+  if (brief.notes.length) {
+    L.push("");
+    L.push("ATTENTION");
+    for (const n of brief.notes) L.push(`  ! ${n}`);
+  }
+
+  L.push("");
+  L.push("THE LOOP");
+  L.push("  1. Do the work described above.");
+  L.push(`  2. Run: ${brief.validateCommand}`);
+  L.push("  3. FAIL → fix the listed checks and validate again.");
+  L.push("  4. PASS → the harness advances the phase and issues the next brief.");
+  L.push("");
+  L.push("Do not edit harness/config.json by hand and do not mark your own work complete.");
+  L.push("The gate is the only referee.");
+
+  return L.join("\n");
+}
+
+/** One-line status suitable for a status bar. */
+export function renderBriefLine(brief: Brief): string {
+  if (brief.paused) return "paused";
+  if (brief.complete) return "complete";
+  const bits = [brief.phase ?? "—"];
+  if (brief.task) bits.push(brief.task.key);
+  bits.push(`${brief.progress.tasksDone}/${brief.progress.tasksTotal}`);
+  return bits.join(" · ");
+}
+
+/** Phase doc + craft skill the brief points at, when present in the project. */
+export function referencedDocs(targetDir: string, phase: Phase | null): string[] {
+  if (!phase) return [];
+  const out: string[] = [];
+  const pd = P.phaseDocPath(targetDir, phase);
+  if (readText(pd) !== null) out.push(pd);
+  const role = PHASE_ROLE[phase];
+  const ad = P.agentDocPath(targetDir, role);
+  if (readText(ad) !== null) out.push(ad);
+  return out;
+}
+
+export { nextPhase };

package/src/core/config.ts

@@ -0,0 +1,265 @@
+/**
+ * infinity-harness — harness/config.json load, save, and mutation helpers.
+ *
+ * The config is the pipeline's control state: which phase, which feature/task,
+ * how many retries are burnt, and what the gate history looks like. It is
+ * read on nearly every call, so it is deliberately cheap to load and always
+ * deep-merged over defaults — an older config missing new keys still works.
+ */
+
+import type { HarnessConfig, GateHistoryEntry, Phase, Role } from "./types.ts";
+import { DEFAULT_ENABLED_PHASES } from "./types.ts";
+import { configPath } from "./paths.ts";
+import { readJson, writeJsonAtomic, backupOnce, fileExists } from "./fsx.ts";
+
+export const DEFAULT_MAX_RETRIES = 10;
+export const DEFAULT_FEATURE_RETRIES = 2;
+export const DEFAULT_PHASE_RETRIES = 2;
+export const COVERAGE_THRESHOLD_DEFAULT = 80;
+
+/** Cap on gateHistory length. Unbounded growth is a real problem on multi-day runs. */
+export const GATE_HISTORY_LIMIT = 500;
+
+export function defaultConfig(): HarnessConfig {
+  return {
+    version: "2.0",
+    stack: null,
+    mode: "copilot",
+    currentPhase: null,
+    currentRole: null,
+    currentFeature: null,
+    currentTask: null,
+    paused: false,
+    features: { remaining: 0, passing: 0, total: 0 },
+    gates: {
+      enabled: true,
+      checks: ["all"],
+      coverage: { enabled: false, threshold: COVERAGE_THRESHOLD_DEFAULT },
+      cleanState: { enabled: false, stalePatterns: [], startupCmd: null },
+      antiPlaceholder: { enabled: true, patterns: [] },
+    },
+    commands: { lint: null, test: null, coverage: null, build: null },
+    git: {
+      autoCommit: false,
+      autoTag: false,
+      branch: null,
+      clean: true,
+      hasUpstream: false,
+      lastCommitMessage: null,
+    },
+    phases: { enabled: [...DEFAULT_ENABLED_PHASES] },
+    roles: { strict: false },
+    loop: {
+      maxIterations: 2000,
+      maxWallClockMs: 24 * 60 * 60 * 1000,
+      noProgressLimit: 3,
+    },
+    retry: {
+      tasks: { enabled: true, maxRetries: null },
+      features: { enabled: false, maxRetries: DEFAULT_FEATURE_RETRIES },
+      phases: { enabled: false, maxRetries: DEFAULT_PHASE_RETRIES },
+    },
+    maxRetries: DEFAULT_MAX_RETRIES,
+    retryCount: 0,
+    taskRetryCount: 0,
+    featureRetryCount: 0,
+    phaseRetryCount: 0,
+    pipelineIteration: 0,
+    gateHistory: [],
+  };
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Deep-merge `partial` over `defaults`. Arrays are replaced, not merged. */
+function deepMerge<T>(defaults: T, partial: unknown): T {
+  if (!isPlainObject(partial)) return defaults;
+  if (!isPlainObject(defaults)) return partial as T;
+  const out: Record<string, unknown> = { ...(defaults as Record<string, unknown>) };
+  for (const [k, v] of Object.entries(partial)) {
+    const d = (defaults as Record<string, unknown>)[k];
+    out[k] = isPlainObject(v) && isPlainObject(d) ? deepMerge(d, v) : v;
+  }
+  return out as T;
+}
+
+export type LoadResult = {
+  ok: boolean;
+  config: HarnessConfig;
+  error: string | null;
+  /** True when no config file existed and defaults were synthesised. */
+  seeded: boolean;
+};
+
+/**
+ * Load config, merged over defaults.
+ *
+ * A missing file yields defaults with `ok:false` (the project is not
+ * initialised). A corrupt file yields defaults with an error — never a throw,
+ * because every lifecycle hook calls this and a crash there kills the session.
+ */
+export function loadConfig(targetDir: string): LoadResult {
+  const path = configPath(targetDir);
+  if (!fileExists(path)) {
+    return { ok: false, config: defaultConfig(), error: "no harness/config.json", seeded: true };
+  }
+  try {
+    const raw = readJson<Partial<HarnessConfig>>(path);
+    if (raw === null) {
+      return { ok: false, config: defaultConfig(), error: "harness/config.json is empty", seeded: true };
+    }
+    return { ok: true, config: deepMerge(defaultConfig(), raw), error: null, seeded: false };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, config: defaultConfig(), error: msg, seeded: false };
+  }
+}
+
+export function saveConfig(targetDir: string, config: HarnessConfig): { ok: boolean; error: string | null } {
+  const path = configPath(targetDir);
+  try {
+    trimGateHistory(config);
+    backupOnce(path);
+    writeJsonAtomic(path, config);
+    return { ok: true, error: null };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export function isHarnessProject(targetDir: string): boolean {
+  return fileExists(configPath(targetDir));
+}
+
+// ── Gate history ────────────────────────────────────────────────────────────
+
+export function trimGateHistory(config: HarnessConfig): void {
+  if (!Array.isArray(config.gateHistory)) {
+    config.gateHistory = [];
+    return;
+  }
+  if (config.gateHistory.length > GATE_HISTORY_LIMIT) {
+    config.gateHistory = config.gateHistory.slice(-GATE_HISTORY_LIMIT);
+  }
+}
+
+export function recordGate(
+  config: HarnessConfig,
+  phase: string,
+  result: "pass" | "fail",
+  scope?: { feature?: string; task?: string },
+): void {
+  if (!Array.isArray(config.gateHistory)) config.gateHistory = [];
+  const entry: GateHistoryEntry = {
+    phase,
+    result,
+    timestamp: new Date().toISOString(),
+    ...(scope?.feature ? { feature: scope.feature } : {}),
+    ...(scope?.task ? { task: scope.task } : {}),
+  };
+  config.gateHistory.push(entry);
+  trimGateHistory(config);
+}
+
+// ── Retry budgets ───────────────────────────────────────────────────────────
+
+export type EffectiveRetry = {
+  tasks: { enabled: boolean; max: number };
+  features: { enabled: boolean; max: number };
+  phases: { enabled: boolean; max: number };
+};
+
+/** Resolve retry budgets, seeding task retries from the legacy `maxRetries`. */
+export function getRetryConfig(config: HarnessConfig): EffectiveRetry {
+  const legacy = typeof config.maxRetries === "number" ? config.maxRetries : DEFAULT_MAX_RETRIES;
+  const r = config.retry ?? defaultConfig().retry;
+  return {
+    tasks: { enabled: r.tasks?.enabled ?? true, max: r.tasks?.maxRetries ?? legacy },
+    features: { enabled: r.features?.enabled ?? false, max: r.features?.maxRetries ?? DEFAULT_FEATURE_RETRIES },
+    phases: { enabled: r.phases?.enabled ?? false, max: r.phases?.maxRetries ?? DEFAULT_PHASE_RETRIES },
+  };
+}
+
+export function resetTaskRetry(config: HarnessConfig): void {
+  config.taskRetryCount = 0;
+}
+export function incrementTaskRetry(config: HarnessConfig): number {
+  config.taskRetryCount = (config.taskRetryCount ?? 0) + 1;
+  return config.taskRetryCount;
+}
+export function resetFeatureRetry(config: HarnessConfig): void {
+  config.featureRetryCount = 0;
+}
+export function incrementFeatureRetry(config: HarnessConfig): number {
+  config.featureRetryCount = (config.featureRetryCount ?? 0) + 1;
+  return config.featureRetryCount;
+}
+export function resetPhaseRetry(config: HarnessConfig): void {
+  config.phaseRetryCount = 0;
+  config.retryCount = 0;
+}
+export function incrementPhaseRetry(config: HarnessConfig): number {
+  config.phaseRetryCount = (config.phaseRetryCount ?? 0) + 1;
+  config.retryCount = (config.retryCount ?? 0) + 1;
+  return config.phaseRetryCount;
+}
+
+/** True when any *enabled* retry budget is exhausted — the signal to escalate. */
+export function isRetryExhausted(config: HarnessConfig): { exhausted: boolean; which: string | null } {
+  const r = getRetryConfig(config);
+  if (r.tasks.enabled && (config.taskRetryCount ?? 0) >= r.tasks.max) return { exhausted: true, which: "task" };
+  if (r.features.enabled && (config.featureRetryCount ?? 0) >= r.features.max) return { exhausted: true, which: "feature" };
+  if (r.phases.enabled && (config.phaseRetryCount ?? 0) >= r.phases.max) return { exhausted: true, which: "phase" };
+  return { exhausted: false, which: null };
+}
+
+// ── Dotted get/set (used by the `config` command surface) ────────────────────
+
+export function getKey(config: HarnessConfig, key: string): unknown {
+  let cur: unknown = config;
+  for (const part of key.split(".")) {
+    if (!isPlainObject(cur)) return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+export function setKey(config: HarnessConfig, key: string, value: unknown): void {
+  const parts = key.split(".");
+  let cur: Record<string, unknown> = config as unknown as Record<string, unknown>;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const p = parts[i]!;
+    if (!isPlainObject(cur[p])) cur[p] = {};
+    cur = cur[p] as Record<string, unknown>;
+  }
+  cur[parts[parts.length - 1]!] = value;
+}
+
+/** Required-field check. `currentPhase` is legitimately null before INIT. */
+export function validateConfig(config: HarnessConfig): string[] {
+  const required = ["version", "mode", "gates", "git", "phases", "maxRetries"];
+  const missing: string[] = [];
+  for (const f of required) {
+    const v = (config as Record<string, unknown>)[f];
+    if (v === undefined || v === null) missing.push(f);
+  }
+  if (!("currentPhase" in config)) missing.push("currentPhase");
+  return missing;
+}
+
+export function currentRoleFor(phase: Phase | null): Role | null {
+  if (!phase) return null;
+  const map: Record<Phase, Role> = {
+    init: "planner",
+    define: "planner",
+    plan: "planner",
+    build: "generator",
+    verify: "evaluator",
+    simplify: "simplifier",
+    review: "evaluator",
+    ship: "evaluator",
+  };
+  return map[phase] ?? null;
+}

package/src/core/exec.ts

@@ -0,0 +1,130 @@
+/**
+ * infinity-harness — bounded command execution.
+ *
+ * Every shell-out in the harness goes through here so that a hung lint or an
+ * infinite test loop cannot wedge a multi-day run. `run` never throws: a
+ * non-zero exit, a timeout, and a missing binary are all reported as data.
+ */
+
+import { spawn } from "node:child_process";
+
+export type RunResult = {
+  ok: boolean;
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  /** Command could not be started at all (ENOENT, EACCES, …). */
+  spawnError: string | null;
+  durationMs: number;
+};
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const LONG_TIMEOUT_MS = 300_000;
+
+/** Cap captured output so a runaway process cannot exhaust memory. */
+const MAX_CAPTURE_BYTES = 512 * 1024;
+
+export async function run(
+  command: string,
+  opts: { cwd: string; timeoutMs?: number; env?: NodeJS.ProcessEnv; shell?: boolean } = { cwd: process.cwd() },
+): Promise<RunResult> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const started = Date.now();
+
+  return new Promise<RunResult>((resolvePromise) => {
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+
+    const child = spawn(command, {
+      cwd: opts.cwd,
+      shell: opts.shell ?? true,
+      env: opts.env ?? process.env,
+      windowsHide: true,
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+    }, timeoutMs);
+
+    const settle = (code: number | null, spawnError: string | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise({
+        ok: !timedOut && spawnError === null && code === 0,
+        code,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        timedOut,
+        spawnError,
+        durationMs: Date.now() - started,
+      });
+    };
+
+    child.stdout?.on("data", (d: Buffer) => {
+      if (stdout.length < MAX_CAPTURE_BYTES) stdout += d.toString("utf-8");
+    });
+    child.stderr?.on("data", (d: Buffer) => {
+      if (stderr.length < MAX_CAPTURE_BYTES) stderr += d.toString("utf-8");
+    });
+    child.on("error", (e: Error) => settle(null, e.message));
+    child.on("close", (code) => settle(code, null));
+  });
+}
+
+// ── git helpers ─────────────────────────────────────────────────────────────
+
+export async function isGitRepo(cwd: string): Promise<boolean> {
+  const r = await run("git rev-parse --is-inside-work-tree", { cwd, timeoutMs: 10_000 });
+  return r.ok && r.stdout.trim() === "true";
+}
+
+export async function gitBranch(cwd: string): Promise<string | null> {
+  const r = await run("git rev-parse --abbrev-ref HEAD", { cwd, timeoutMs: 10_000 });
+  return r.ok ? r.stdout.trim() : null;
+}
+
+export async function gitIsClean(cwd: string): Promise<boolean> {
+  const r = await run("git status --porcelain", { cwd, timeoutMs: 15_000 });
+  // A failed git call must not be reported as "clean" — that would let a
+  // git-clean gate pass on a repo the harness cannot actually inspect.
+  if (!r.ok) return false;
+  return r.stdout.trim() === "";
+}
+
+/** True when the working tree has *any* uncommitted change. Inverse of clean. */
+export async function gitHasChanges(cwd: string): Promise<boolean> {
+  const r = await run("git status --porcelain", { cwd, timeoutMs: 15_000 });
+  if (!r.ok) return false;
+  return r.stdout.trim() !== "";
+}
+
+export async function gitHasUpstream(cwd: string): Promise<boolean> {
+  const r = await run("git rev-parse --abbrev-ref --symbolic-full-name @{u}", { cwd, timeoutMs: 10_000 });
+  return r.ok && r.stdout.trim() !== "";
+}
+
+export async function gitLastCommitMessage(cwd: string): Promise<string | null> {
+  const r = await run("git log -1 --pretty=%s", { cwd, timeoutMs: 10_000 });
+  return r.ok && r.stdout.trim() ? r.stdout.trim() : null;
+}
+
+export async function gitHasTag(cwd: string): Promise<boolean> {
+  const r = await run("git tag --points-at HEAD", { cwd, timeoutMs: 10_000 });
+  return r.ok && r.stdout.trim() !== "";
+}
+
+export async function gitBehindUpstream(cwd: string): Promise<number | null> {
+  const r = await run("git rev-list --count HEAD..@{u}", { cwd, timeoutMs: 15_000 });
+  if (!r.ok) return null;
+  const n = Number.parseInt(r.stdout.trim(), 10);
+  return Number.isNaN(n) ? null : n;
+}