@remnic/core 9.3.624 → 9.3.626

package/src/wearables/config.ts

@@ -0,0 +1,332 @@
+/**
+ * Wearables config parsing — strict, loud, and default-safe.
+ *
+ * Mirrors the `procedural` block conventions in config.ts: shape
+ * violations and unparseable values throw with actionable messages
+ * (CLAUDE.md rule 51); boolean-ish strings coerce via the shared
+ * helpers (rule 36); every numeric knob is bounds-checked; the
+ * memory-creation default is the least-privileged mode (rule 48).
+ */
+
+import { coerceBool, coerceNumber } from "../connectors/coerce.js";
+import type { ImportanceLevel } from "../types.js";
+import { compileCorrectionRules } from "./corrections.js";
+import { compileRedactionPatterns } from "./redaction.js";
+import type {
+  WearableCleanupSettings,
+  WearableCorrectionRule,
+  WearableMemoryMode,
+  WearableSourceSettings,
+  WearablesConfig,
+} from "./types.js";
+
+export const KNOWN_WEARABLE_SOURCE_IDS = ["limitless", "bee", "omi"] as const;
+
+const MEMORY_MODES: WearableMemoryMode[] = ["off", "review", "auto"];
+const IMPORTANCE_LEVELS: ImportanceLevel[] = [
+  "trivial",
+  "low",
+  "normal",
+  "high",
+  "critical",
+];
+const NATIVE_IMPORT_MODES = ["off", "review"] as const;
+
+const DEFAULT_MIN_CONFIDENCE = 0.6;
+const DEFAULT_MIN_IMPORTANCE: ImportanceLevel = "low";
+const DEFAULT_MAX_MEMORIES_PER_DAY = 20;
+const MAX_MEMORIES_PER_DAY_CEILING = 500;
+
+export function defaultWearableCleanupSettings(): WearableCleanupSettings {
+  return {
+    mergeSameSpeaker: true,
+    stripFillers: true,
+    collapseRepeats: true,
+    dropLowQuality: true,
+  };
+}
+
+export function defaultWearableSourceSettings(): WearableSourceSettings {
+  return {
+    enabled: false,
+    memoryMode: "review",
+    minConfidence: DEFAULT_MIN_CONFIDENCE,
+    minImportance: DEFAULT_MIN_IMPORTANCE,
+    maxMemoriesPerDay: DEFAULT_MAX_MEMORIES_PER_DAY,
+    importNativeMemories: "off",
+    cleanup: defaultWearableCleanupSettings(),
+  };
+}
+
+export function defaultWearablesConfig(): WearablesConfig {
+  return {
+    enabled: false,
+    redactionEnabled: true,
+    redactionPatterns: [],
+    offTheRecordEnabled: false,
+    digestEnabled: false,
+    corrections: [],
+    sources: {},
+  };
+}
+
+function requireObject(
+  value: unknown,
+  keyPath: string,
+): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `${keyPath} must be an object (got ${JSON.stringify(value)})`,
+    );
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseBool(
+  value: unknown,
+  keyPath: string,
+  fallback: boolean,
+): boolean {
+  if (value === undefined) return fallback;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `${keyPath} must be a boolean or one of "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off" (got ${JSON.stringify(value)})`,
+    );
+  }
+  return coerced;
+}
+
+function parseEnum<T extends string>(
+  value: unknown,
+  keyPath: string,
+  allowed: readonly T[],
+  fallback: T,
+): T {
+  if (value === undefined) return fallback;
+  if (typeof value === "string" && (allowed as readonly string[]).includes(value)) {
+    return value as T;
+  }
+  throw new Error(
+    `${keyPath} must be one of ${allowed.map((entry) => `"${entry}"`).join(", ")} (got ${JSON.stringify(value)})`,
+  );
+}
+
+function parseOptionalString(
+  value: unknown,
+  keyPath: string,
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${keyPath} must be a non-empty string when set`);
+  }
+  return value.trim();
+}
+
+function parseCorrectionRules(
+  value: unknown,
+  keyPath: string,
+): WearableCorrectionRule[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${keyPath} must be an array of correction rules`);
+  }
+  const rules = value.map((entry, index) => {
+    const raw = requireObject(entry, `${keyPath}[${index}]`);
+    const rule: WearableCorrectionRule = {
+      match: typeof raw.match === "string" ? raw.match : "",
+      replace: typeof raw.replace === "string" ? raw.replace : "",
+    };
+    if (raw.regex !== undefined) {
+      rule.regex = parseBool(raw.regex, `${keyPath}[${index}].regex`, false);
+    }
+    if (raw.caseInsensitive !== undefined) {
+      rule.caseInsensitive = parseBool(
+        raw.caseInsensitive,
+        `${keyPath}[${index}].caseInsensitive`,
+        true,
+      );
+    }
+    if (raw.sources !== undefined) {
+      if (
+        !Array.isArray(raw.sources) ||
+        raw.sources.some((source) => typeof source !== "string")
+      ) {
+        throw new Error(`${keyPath}[${index}].sources must be an array of strings`);
+      }
+      rule.sources = raw.sources as string[];
+    }
+    return rule;
+  });
+  // Compile now so bad rules fail at config load, not mid-sync.
+  compileCorrectionRules(rules, keyPath);
+  return rules;
+}
+
+function parseSourceSettings(
+  value: unknown,
+  keyPath: string,
+): WearableSourceSettings {
+  const raw = requireObject(value, keyPath);
+  const defaults = defaultWearableSourceSettings();
+
+  const minConfidenceRaw = coerceNumber(raw.minConfidence);
+  // Out-of-range values reject loudly instead of clamping — silently
+  // turning minConfidence 7 into 1 would change the memory gate in a
+  // way the operator never asked for (Codex P2 on PR #1458, round 3).
+  if (
+    raw.minConfidence !== undefined &&
+    (minConfidenceRaw === undefined || minConfidenceRaw < 0 || minConfidenceRaw > 1)
+  ) {
+    throw new Error(
+      `${keyPath}.minConfidence must be a number between 0 and 1 (got ${JSON.stringify(raw.minConfidence)})`,
+    );
+  }
+  const minConfidence = minConfidenceRaw ?? defaults.minConfidence;
+
+  const maxPerDayRaw = coerceNumber(raw.maxMemoriesPerDay);
+  // Reject non-integers instead of flooring them: 0.5 would floor to 0,
+  // and 0 is the documented "disable the cap" value — a fractional typo
+  // must not silently remove the cap (Codex P2 on PR #1458).
+  if (
+    raw.maxMemoriesPerDay !== undefined &&
+    (maxPerDayRaw === undefined ||
+      !Number.isInteger(maxPerDayRaw) ||
+      maxPerDayRaw < 0 ||
+      maxPerDayRaw > MAX_MEMORIES_PER_DAY_CEILING)
+  ) {
+    throw new Error(
+      `${keyPath}.maxMemoriesPerDay must be an integer between 0 and ${MAX_MEMORIES_PER_DAY_CEILING} (0 disables the cap); got ${JSON.stringify(raw.maxMemoriesPerDay)}`,
+    );
+  }
+  // 0 is the documented "disable the cap" value — honored here AND in
+  // the schema minimum (CLAUDE.md rule 45).
+  const maxMemoriesPerDay = maxPerDayRaw ?? defaults.maxMemoriesPerDay;
+
+  const rawCleanup =
+    raw.cleanup === undefined ? {} : requireObject(raw.cleanup, `${keyPath}.cleanup`);
+  const cleanup: WearableCleanupSettings = {
+    mergeSameSpeaker: parseBool(
+      rawCleanup.mergeSameSpeaker,
+      `${keyPath}.cleanup.mergeSameSpeaker`,
+      defaults.cleanup.mergeSameSpeaker,
+    ),
+    stripFillers: parseBool(
+      rawCleanup.stripFillers,
+      `${keyPath}.cleanup.stripFillers`,
+      defaults.cleanup.stripFillers,
+    ),
+    collapseRepeats: parseBool(
+      rawCleanup.collapseRepeats,
+      `${keyPath}.cleanup.collapseRepeats`,
+      defaults.cleanup.collapseRepeats,
+    ),
+    dropLowQuality: parseBool(
+      rawCleanup.dropLowQuality,
+      `${keyPath}.cleanup.dropLowQuality`,
+      defaults.cleanup.dropLowQuality,
+    ),
+  };
+
+  return {
+    enabled: parseBool(raw.enabled, `${keyPath}.enabled`, false),
+    apiKey: parseOptionalString(raw.apiKey, `${keyPath}.apiKey`),
+    baseUrl: parseOptionalString(raw.baseUrl, `${keyPath}.baseUrl`),
+    appId: parseOptionalString(raw.appId, `${keyPath}.appId`),
+    userId: parseOptionalString(raw.userId, `${keyPath}.userId`),
+    memoryMode: parseEnum(
+      raw.memoryMode,
+      `${keyPath}.memoryMode`,
+      MEMORY_MODES,
+      defaults.memoryMode,
+    ),
+    minConfidence,
+    minImportance: parseEnum(
+      raw.minImportance,
+      `${keyPath}.minImportance`,
+      IMPORTANCE_LEVELS,
+      defaults.minImportance,
+    ),
+    maxMemoriesPerDay,
+    importNativeMemories: parseEnum(
+      raw.importNativeMemories,
+      `${keyPath}.importNativeMemories`,
+      NATIVE_IMPORT_MODES,
+      defaults.importNativeMemories,
+    ),
+    cleanup,
+  };
+}
+
+/**
+ * Parse the `wearables` config block. `undefined` yields the disabled
+ * default config; any present-but-malformed value throws.
+ */
+export function parseWearablesConfig(value: unknown): WearablesConfig {
+  if (value === undefined) return defaultWearablesConfig();
+  const raw = requireObject(value, "wearables");
+  const defaults = defaultWearablesConfig();
+
+  const timezone = parseOptionalString(raw.timezone, "wearables.timezone");
+  if (timezone !== undefined) {
+    try {
+      new Intl.DateTimeFormat("en-US", { timeZone: timezone });
+    } catch {
+      throw new Error(
+        `wearables.timezone must be a valid IANA timezone identifier (got ${JSON.stringify(timezone)})`,
+      );
+    }
+  }
+
+  let redactionPatterns: string[] = defaults.redactionPatterns;
+  if (raw.redactionPatterns !== undefined) {
+    if (
+      !Array.isArray(raw.redactionPatterns) ||
+      raw.redactionPatterns.some((pattern) => typeof pattern !== "string")
+    ) {
+      throw new Error("wearables.redactionPatterns must be an array of strings");
+    }
+    redactionPatterns = raw.redactionPatterns as string[];
+    // Compile now so invalid regexes fail at config load.
+    compileRedactionPatterns(redactionPatterns);
+  }
+
+  const sources: Record<string, WearableSourceSettings> = {};
+  if (raw.sources !== undefined) {
+    const rawSources = requireObject(raw.sources, "wearables.sources");
+    for (const [sourceId, sourceValue] of Object.entries(rawSources)) {
+      if (!/^[a-z][a-z0-9-]{0,63}$/.test(sourceId)) {
+        throw new Error(
+          `wearables.sources keys must be lowercase source ids (letters, digits, dashes); got ${JSON.stringify(sourceId)}`,
+        );
+      }
+      sources[sourceId] = parseSourceSettings(
+        sourceValue,
+        `wearables.sources.${sourceId}`,
+      );
+    }
+  }
+
+  return {
+    enabled: parseBool(raw.enabled, "wearables.enabled", defaults.enabled),
+    ...(timezone !== undefined ? { timezone } : {}),
+    redactionEnabled: parseBool(
+      raw.redactionEnabled,
+      "wearables.redactionEnabled",
+      defaults.redactionEnabled,
+    ),
+    redactionPatterns,
+    offTheRecordEnabled: parseBool(
+      raw.offTheRecordEnabled,
+      "wearables.offTheRecordEnabled",
+      defaults.offTheRecordEnabled,
+    ),
+    digestEnabled: parseBool(
+      raw.digestEnabled,
+      "wearables.digestEnabled",
+      defaults.digestEnabled,
+    ),
+    corrections: parseCorrectionRules(raw.corrections, "wearables.corrections"),
+    sources,
+  };
+}

package/src/wearables/corrections.test.ts

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { test } from "node:test";
+
+import {
+  applyCorrections,
+  compileCorrectionRule,
+  compileCorrectionRules,
+  loadCorrectionsFile,
+  saveCorrectionsFile,
+} from "./corrections.js";
+
+function compiled(rules: Parameters<typeof compileCorrectionRules>[0]) {
+  return compileCorrectionRules(rules, "test");
+}
+
+test("literal rules match on word boundaries, case-insensitive by default", () => {
+  const rules = compiled([{ match: "remnick", replace: "Remnic" }]);
+  assert.equal(
+    applyCorrections("Remnick and REMNICK but not remnickson", rules, "limitless").text,
+    "Remnic and Remnic but not remnickson",
+  );
+});
+
+test("literal rules escape regex metacharacters", () => {
+  const rules = compiled([{ match: "node.js (v22)", replace: "Node 22" }]);
+  const result = applyCorrections("we run node.js (v22) here", rules, "limitless");
+  assert.equal(result.text, "we run Node 22 here");
+  assert.equal(result.applied, 1);
+  // The dot must not act as a wildcard.
+  assert.equal(
+    applyCorrections("nodeXjs (v22)", rules, "limitless").applied,
+    0,
+  );
+});
+
+test("dollar signs in replacements stay literal", () => {
+  const rules = compiled([{ match: "five bucks", replace: "$5 ($$ saved)" }]);
+  assert.equal(
+    applyCorrections("that cost five bucks", rules, "limitless").text,
+    "that cost $5 ($$ saved)",
+  );
+});
+
+test("regex rules work and case sensitivity is honored", () => {
+  const rules = compiled([
+    { match: "colou?r", replace: "color", regex: true, caseInsensitive: false },
+  ]);
+  const result = applyCorrections("colour Colour", rules, "limitless");
+  assert.equal(result.text, "color Colour");
+});
+
+test("rules scoped to sources skip other sources", () => {
+  const rules = compiled([
+    { match: "panda", replace: "Pendant", sources: ["limitless"] },
+  ]);
+  assert.equal(applyCorrections("my panda", rules, "limitless").applied, 1);
+  assert.equal(applyCorrections("my panda", rules, "bee").applied, 0);
+});
+
+test("invalid rules are rejected loudly at compile time", () => {
+  assert.throws(() => compileCorrectionRule({ match: "", replace: "x" }, "r"), /non-empty/);
+  assert.throws(
+    () => compileCorrectionRule({ match: "(", replace: "x", regex: true }, "r"),
+    /not a valid regular expression/,
+  );
+  assert.throws(
+    () => compileCorrectionRule({ match: "a*", replace: "x", regex: true }, "r"),
+    /matches the empty string/,
+  );
+});
+
+test("corrections file round-trips, validates, and tolerates absence", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-corrections-"));
+  try {
+    assert.deepEqual(await loadCorrectionsFile(dir), []);
+    const rules = [
+      { match: "remnick", replace: "Remnic" },
+      { match: "acme corp", replace: "ACME Corp", sources: ["bee"] },
+    ];
+    await saveCorrectionsFile(dir, rules);
+    assert.deepEqual(await loadCorrectionsFile(dir), rules);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a corrupt corrections file throws instead of silently dropping rules", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-corrections-"));
+  try {
+    const { promises: fsPromises } = await import("node:fs");
+    const filePath = path.join(dir, "state", "wearables", "corrections.json");
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, "{not json", "utf-8");
+    await assert.rejects(loadCorrectionsFile(dir), /not valid JSON/);
+    await fsPromises.writeFile(filePath, JSON.stringify({ rules: "nope" }), "utf-8");
+    await assert.rejects(loadCorrectionsFile(dir), /unexpected shape/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("saving an invalid rule set is rejected before touching the file", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "remnic-corrections-"));
+  try {
+    await saveCorrectionsFile(dir, [{ match: "good", replace: "fine" }]);
+    await assert.rejects(
+      saveCorrectionsFile(dir, [{ match: "(", replace: "x", regex: true }]),
+      /not a valid regular expression/,
+    );
+    // The previously-saved rules are still intact.
+    assert.equal((await loadCorrectionsFile(dir)).length, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/wearables/corrections.ts

@@ -0,0 +1,211 @@
+/**
+ * Wearable transcript corrections — user-specific replacement rules.
+ *
+ * ASR engines consistently mishear the same proper nouns for the same
+ * person ("remnick" for "Remnic", a colleague's name, product jargon).
+ * Rules come from two places, merged at sync time:
+ *
+ *  1. `wearables.corrections` in plugin config (declarative, versioned
+ *     with the operator's config).
+ *  2. A CLI-managed rules file at `state/wearables/corrections.json`
+ *     (added interactively via `remnic wearables corrections add`).
+ *
+ * Literal rules are regex-escaped before compilation and replacements
+ * are applied via a function (never a replacement string) so `$` in
+ * either side can't corrupt output.
+ */
+
+import { promises as fsPromises } from "node:fs";
+import * as path from "node:path";
+
+import type { WearableCorrectionRule } from "./types.js";
+
+export interface CompiledCorrectionRule {
+  rule: WearableCorrectionRule;
+  pattern: RegExp;
+}
+
+export interface CorrectionApplication {
+  text: string;
+  applied: number;
+}
+
+/** Hard cap on rule pattern length (bounds hostile/pathological regexes). */
+const MAX_PATTERN_LENGTH = 256;
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Validate and compile a correction rule. Throws a descriptive error on
+ * invalid input (empty match, regex that doesn't compile, regex that
+ * matches the empty string) — callers surface this at config parse or
+ * CLI time rather than skipping the rule silently.
+ */
+export function compileCorrectionRule(
+  rule: WearableCorrectionRule,
+  label: string,
+): CompiledCorrectionRule {
+  if (typeof rule.match !== "string" || rule.match.length === 0) {
+    throw new Error(`${label}: match must be a non-empty string`);
+  }
+  if (rule.match.length > MAX_PATTERN_LENGTH) {
+    throw new Error(
+      `${label}: match exceeds ${MAX_PATTERN_LENGTH} characters — correction patterns must stay short`,
+    );
+  }
+  if (typeof rule.replace !== "string") {
+    throw new Error(`${label}: replace must be a string`);
+  }
+  const flags = rule.caseInsensitive === false ? "g" : "gi";
+  let pattern: RegExp;
+  if (rule.regex === true) {
+    try {
+      // Operator-supplied regexes are the documented feature here
+      // (rules live in the operator's own config / state file, never in
+      // request input); the length cap above bounds pathological
+      // patterns. CodeQL js/regex-injection is dismissed by design for
+      // this site.
+      pattern = new RegExp(rule.match, flags);
+    } catch (err) {
+      throw new Error(
+        `${label}: match is not a valid regular expression: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  } else {
+    // Literal rules match on word boundaries when both edges of the
+    // match are word characters, so "remnick" doesn't fire inside
+    // "remnickson" unless the user opts into regex mode.
+    const escaped = escapeRegExp(rule.match);
+    const leading = /^[\p{L}\p{N}_]/u.test(rule.match) ? "\\b" : "";
+    const trailing = /[\p{L}\p{N}_]$/u.test(rule.match) ? "\\b" : "";
+    pattern = new RegExp(`${leading}${escaped}${trailing}`, flags);
+  }
+  if (pattern.test("")) {
+    throw new Error(
+      `${label}: pattern matches the empty string and would corrupt every transcript`,
+    );
+  }
+  pattern.lastIndex = 0;
+  return { rule, pattern };
+}
+
+/** Compile a rule list, labeling errors with their index. */
+export function compileCorrectionRules(
+  rules: WearableCorrectionRule[],
+  labelPrefix: string,
+): CompiledCorrectionRule[] {
+  return rules.map((rule, index) =>
+    compileCorrectionRule(rule, `${labelPrefix}[${index}]`),
+  );
+}
+
+/** Apply every applicable rule to a piece of transcript text. */
+export function applyCorrections(
+  text: string,
+  rules: CompiledCorrectionRule[],
+  sourceId: string,
+): CorrectionApplication {
+  let applied = 0;
+  let result = text;
+  for (const { rule, pattern } of rules) {
+    if (
+      Array.isArray(rule.sources) &&
+      rule.sources.length > 0 &&
+      !rule.sources.includes(sourceId)
+    ) {
+      continue;
+    }
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, () => {
+      applied += 1;
+      // Replacement via function: `$` in rule.replace stays literal.
+      return rule.replace;
+    });
+  }
+  return { text: result, applied };
+}
+
+// ---------------------------------------------------------------------------
+// CLI-managed rules file
+// ---------------------------------------------------------------------------
+
+interface CorrectionsFileShape {
+  version: 1;
+  rules: WearableCorrectionRule[];
+}
+
+export function correctionsFilePath(memoryDir: string): string {
+  return path.join(memoryDir, "state", "wearables", "corrections.json");
+}
+
+/**
+ * Load CLI-managed correction rules. A missing file means no rules; a
+ * malformed file throws (operators should know their corrections are
+ * not being applied rather than silently losing them).
+ */
+export async function loadCorrectionsFile(
+  memoryDir: string,
+): Promise<WearableCorrectionRule[]> {
+  const filePath = correctionsFilePath(memoryDir);
+  let raw: string;
+  try {
+    raw = await fsPromises.readFile(filePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `wearables corrections file is not valid JSON (state/wearables/corrections.json): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    Array.isArray(parsed) ||
+    !Array.isArray((parsed as CorrectionsFileShape).rules)
+  ) {
+    throw new Error(
+      'wearables corrections file has an unexpected shape (state/wearables/corrections.json); expected {"version":1,"rules":[...]}',
+    );
+  }
+  const rules = (parsed as CorrectionsFileShape).rules;
+  // Validate every persisted rule up front so a hand-edited bad rule
+  // fails at load with its index, not mid-sync.
+  compileCorrectionRules(rules, "state corrections");
+  return rules;
+}
+
+/** Persist CLI-managed rules atomically (temp file + rename). */
+export async function saveCorrectionsFile(
+  memoryDir: string,
+  rules: WearableCorrectionRule[],
+): Promise<void> {
+  compileCorrectionRules(rules, "state corrections");
+  const filePath = correctionsFilePath(memoryDir);
+  await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+  const payload: CorrectionsFileShape = { version: 1, rules };
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now().toString(36)}`;
+  await fsPromises.writeFile(
+    tmpPath,
+    `${JSON.stringify(payload, null, 2)}\n`,
+    "utf-8",
+  );
+  try {
+    await fsPromises.rename(tmpPath, filePath);
+  } catch (err) {
+    // Clean up the temp file on rename failure; the original (if any)
+    // is untouched.
+    await fsPromises.unlink(tmpPath).catch(() => undefined);
+    throw err;
+  }
+}