fapony 0.7.0 → 0.7.1

package/src/mem/engine.ts

@@ -1,329 +0,0 @@
-// src/mem/engine.ts — the single validation+write engine for mem add/close.
-//
-// Both entry points call it: CLI (commands/write.ts cmdAdd/cmdClose) and MCP
-// (adapters/mcp/tools/mem.ts memAdd/memClose). Every domain rule lives here
-// exactly once — kind check, files[] required, hold-requires-spec, open
-// next/hold caps. Wrappers own only their surface: argv parsing +
-// console.error/exit (CLI), worktree-shape checks + JSON results (MCP).
-//
-// Precondition: the store is initialized (initStore) before calling — cli.ts
-// does it at dispatch, the MCP wrapper does it per call with its worktree.
-// (PLAN-unify-mem-engine chunk 1)
-
-import { KEY_RE } from "../core/mem-log.js";
-import { checkKeyDomain, keyMatchesQuery } from "./key-registry.js";
-import { openRows } from "./selectors.js";
-import { KINDS, nextId, put, rows, type WorkKind } from "./store.js";
-
-export const CAP_NEXT = 15;
-export const CAP_HOLD = 10;
-
-/**
- * Thrown when an open next/hold cap is full. Carries which cap so the CLI
- * wrapper can append its MEM_FORCE hint while MCP passes the bare message
- * (the two surfaces keep their exact legacy strings — PLAN §4).
- */
-export class CapError extends Error {
-  readonly cap: "next" | "hold";
-  constructor(cap: "next" | "hold", message: string) {
-    super(message);
-    this.name = "CapError";
-    this.cap = cap;
-  }
-}
-
-export interface EngineAddArgs {
-  kind: string;
-  text: string;
-  files: string[];
-  spec?: string;
-  /** Problem identity — optional, but validated against KEY_RE whenever present. */
-  key?: string;
-  /**
-   * Registry domains for this repo (`.fapony/keys.json` via loadKeyRegistry).
-   * null/undefined = no registry on disk = free-form keys, never reject.
-   * Wrappers resolve it; the engine stays pure (no fs).
-   */
-  knownDomains?: string[] | null;
-}
-
-export interface EngineAddResult {
-  id: string;
-  kind: string;
-  text: string;
-  files: string[];
-  spec?: string;
-  key?: string;
-  ts: string;
-}
-
-export function engineAdd(a: EngineAddArgs): EngineAddResult {
-  if (!KINDS.includes(a.kind as WorkKind)) {
-    throw new Error(`kind must be one of ${KINDS.join("|")} — got "${a.kind}"`);
-  }
-  if (a.files.length === 0) {
-    throw new Error("files must contain at least one path");
-  }
-  if (!a.text.trim()) {
-    throw new Error("text is required and must not be empty");
-  }
-  // Without a spec a hold can never be resolved by rotate — reject at write.
-  if (a.kind === "hold" && !a.spec) {
-    throw new Error("hold requires a spec — pass spec: <path/to/SPEC.md>");
-  }
-  // One validator for both surfaces (CLI argv reaches here too) — reject loudly
-  // with a usable example, never silently drop the key (SPEC-mem-keys §Validation).
-  if (a.key !== undefined && !KEY_RE.test(a.key)) {
-    throw new Error(
-      `key must match [a-z0-9-]{3,40}(:[a-z0-9-]{1,40})? — e.g. "fix-stop-dedupe" or "auth:login", got "${a.key}"`,
-    );
-  }
-  // Registry gate (PLAN-mem-core chunk 4): the domain half must be declared.
-  const domainError =
-    a.key !== undefined ? checkKeyDomain(a.key, a.knownDomains) : null;
-  if (domainError) throw new Error(domainError);
-
-  const all = rows();
-  if (a.kind === "next" && !process.env.MEM_FORCE) {
-    const openNext = openRows(all).filter((r) => r.kind === "next").length;
-    if (openNext >= CAP_NEXT) {
-      throw new CapError(
-        "next",
-        `open next ${openNext}/${CAP_NEXT} is full — close an old one first`,
-      );
-    }
-  }
-  if (a.kind === "hold" && !process.env.MEM_FORCE) {
-    const openHold = openRows(all).filter((r) => r.kind === "hold").length;
-    if (openHold >= CAP_HOLD) {
-      throw new CapError(
-        "hold",
-        `open hold ${openHold}/${CAP_HOLD} is full — close/release an old one first`,
-      );
-    }
-  }
-
-  const id = nextId(all);
-  const ts = new Date().toISOString();
-  // Every row written from here on is v:2 — key optional, but the version
-  // stamps the schema so a reader can tell new rows from v:1 legacy ones.
-  // JSON.stringify drops the undefined key, so keyless rows carry only v.
-  put({
-    id,
-    kind: a.kind as WorkKind,
-    text: a.text,
-    spec: a.spec,
-    files: a.files,
-    key: a.key,
-    v: 2,
-  });
-  return {
-    id,
-    kind: a.kind,
-    text: a.text,
-    files: a.files,
-    spec: a.spec,
-    key: a.key,
-    ts,
-  };
-}
-
-export interface EngineCloseArgs {
-  id: string;
-  text: string;
-}
-
-export interface EngineCloseResult {
-  ref: string;
-  text: string;
-  ts: string;
-}
-
-export function engineClose(a: EngineCloseArgs): EngineCloseResult {
-  if (!a.id.trim()) {
-    throw new Error("id is required");
-  }
-  if (!a.text.trim()) {
-    throw new Error("text is required and must not be empty");
-  }
-
-  const all = rows();
-  if (!all.some((r) => "id" in r && r.id === a.id)) {
-    throw new Error(`no id "${a.id}" in the log`);
-  }
-
-  const ts = new Date().toISOString();
-  put({ kind: "close", ref: a.id, text: a.text });
-
-  return { ref: a.id, text: a.text, ts };
-}
-
-// --- find ---
-//
-// The single query engine for mem find. Both entry points call it with rows
-// they already read — CLI (commands/read.ts cmdFind, via allRows() which
-// includes rotated archives) and MCP (adapters/mcp/tools/mem.ts memFind, via
-// readMemLog whose loose log*.jsonl regex includes log.YYYY-MM-DD.jsonl too).
-// Archive scope is therefore identical on both sides with no parameter for it
-// (PLAN-unify-mem-engine chunk 2 §4.1: the "MCP reads live only" premise was
-// wrong — both see archives, base rate 0 archive files vs 211 live rows).
-//
-// The engine is pure: it takes rows + typed params, never touches argv
-// strings or the store. Wrappers own their surface — CLI parses
-// --kind/--files/--since/--limit/--open at the argv layer, MCP validates its JSON
-// shape — and each passes its own kind default (PLAN §5 escape):
-// MCP passes no exclude (contract: "every kind, no default filter", locked by
-// test), CLI passes the bookkeeping exclude to keep its legacy output.
-
-export const FIND_DEFAULT_LIMIT = 20;
-
-/** Bookkeeping rows the CLI hides unless explicitly asked via --kind. */
-export const CLI_FIND_EXCLUDE = ["close", "synced", "claim", "release"];
-
-export interface EngineFindArgs {
-  /** Substring over text/spec/ref, case-insensitive. Omit = no text filter. */
-  text?: string;
-  /** Repo-relative paths — stored files[] first, text/spec/ref fallback. */
-  files?: string[];
-  /** Include filter — when non-empty, wins over excludeKind. */
-  kind?: string[];
-  /** Exclude filter — applied only when kind is empty. */
-  excludeKind?: string[];
-  /** ISO timestamp — only rows at or after this time (inclusive). */
-  sinceIso?: string;
-  /** Max rows returned (total still counts all matches). Default 20. */
-  limit?: number;
-  /**
-   * true = unresolved work only: drops bookkeeping kinds
-   * (close/claim/release/synced) plus work rows a close row points at.
-   * Mirrors selectors.openRows but stays generic (no store types) so MCP rows
-   * qualify. Default false — recall shows closed rows too.
-   */
-  open?: boolean;
-  /**
-   * Problem-identity match — a bare domain doubles as a prefix (`auth`
-   * catches every `auth:*`; `auth:login` is exact). Rows whose effective key
-   * differs fall out (v:1 rows included; they stay reachable via
-   * files/text). A close row matches through the key of the work row its
-   * ref points at (derived at read time, never stored). A pure miss also
-   * returns knownKeys.
-   */
-  key?: string;
-}
-
-export interface EngineFindResult<T> {
-  rows: T[];
-  total: number;
-  /** Present only on a pure key miss — every distinct key in `all`, sorted. */
-  knownKeys?: string[];
-}
-
-export type FindableRow = {
-  kind: string;
-  text?: string;
-  spec?: string;
-  ref?: string;
-  files?: string[];
-  key?: string;
-  ts: string;
-};
-
-export function engineFind<T extends FindableRow>(
-  all: T[],
-  a: EngineFindArgs,
-): EngineFindResult<T> {
-  let out = [...all];
-
-  if (a.open === true) {
-    const dead = new Set(
-      all
-        .filter((r) => r.kind === "close" && typeof r.ref === "string")
-        .map((r) => r.ref as string),
-    );
-    const BOOKKEEPING = new Set(["close", "claim", "release", "synced"]);
-    out = out.filter(
-      (r) =>
-        !BOOKKEEPING.has(r.kind) &&
-        !("id" in r && typeof r.id === "string" && dead.has(r.id)),
-    );
-  }
-
-  if (a.sinceIso) {
-    const since = a.sinceIso;
-    out = out.filter((r) => !(r.ts < since));
-  }
-
-  if (a.kind && a.kind.length > 0) {
-    const keep = new Set(a.kind);
-    out = out.filter((r) => keep.has(r.kind));
-  } else if (a.excludeKind && a.excludeKind.length > 0) {
-    const drop = new Set(a.excludeKind);
-    out = out.filter((r) => !drop.has(r.kind));
-  }
-
-  // Domain-prefix key match, before text/files — a wrong key must never fall
-  // through to substring luck. Close rows derive their key from the ref'd
-  // work row (read-time derive: match only; the row itself stays keyless).
-  // knownKeys fires only on a pure key miss — answer a wrong guess with the
-  // real list.
-  let knownKeys: string[] | undefined;
-  if (a.key) {
-    const want = a.key;
-    const idKey = new Map<string, string>();
-    for (const r of all) {
-      if ("id" in r && typeof r.id === "string" && r.key) {
-        idKey.set(r.id, r.key);
-      }
-    }
-    const eff = (r: T): string | undefined =>
-      r.key ??
-      (r.kind === "close" && typeof r.ref === "string"
-        ? idKey.get(r.ref)
-        : undefined);
-    out = out.filter((r) => keyMatchesQuery(eff(r), want));
-    if (!all.some((r) => keyMatchesQuery(eff(r), want))) {
-      const distinct = new Set<string>();
-      for (const r of all) {
-        if (r.key) distinct.add(r.key);
-      }
-      knownKeys = [...distinct].sort();
-    }
-  }
-
-  if (a.text?.trim()) {
-    const needle = a.text.toLowerCase();
-    out = out.filter((r) =>
-      `${r.text ?? ""}\n${r.spec ?? ""}\n${r.ref ?? ""}`
-        .toLowerCase()
-        .includes(needle),
-    );
-  }
-
-  if (a.files && a.files.length > 0) {
-    // Rows written by `mem add --files` carry files[] — match that first.
-    // Older rows (and any row whose author skipped --files) have none, so the
-    // text/spec/ref substring stays as the fallback: low recall by nature,
-    // a limit of the data rather than of the query.
-    const paths = a.files.map((f) => f.toLowerCase());
-    out = out.filter((r) => {
-      const stored = (r.files ?? []).map((f) => f.toLowerCase());
-      if (stored.some((f) => paths.some((p) => f === p || f.endsWith(`/${p}`))))
-        return true;
-      const hay =
-        `${r.text ?? ""}\n${r.spec ?? ""}\n${r.ref ?? ""}`.toLowerCase();
-      return paths.some((p) => hay.includes(p));
-    });
-  }
-
-  // Newest first — the canonical order. The CLI wrapper reprints oldest-first
-  // to keep its legacy output byte-identical (same set, legacy order).
-  out.sort((x, y) => y.ts.localeCompare(x.ts));
-
-  const total = out.length;
-  const limit = Math.max(0, a.limit ?? FIND_DEFAULT_LIMIT);
-  return {
-    rows: out.slice(0, limit),
-    total,
-    ...(knownKeys ? { knownKeys } : {}),
-  };
-}

package/src/mem/index.ts

@@ -1,201 +0,0 @@
-// src/mem/index.ts — CLI dispatch for `fapony mem <sub>`
-//
-// Moved from templates/mem/mem.ts (2026-09-19) as part of PLAN-agent-one-call chunk 1.
-// Now an export function called by fapony.ts, not a standalone script.
-
-import { existsSync } from "node:fs";
-import { basename, join } from "node:path";
-import { levenshtein } from "../commands.js";
-import { cmdPlanCheck, cmdPlanSweep } from "./commands/plan.js";
-import { cmdDone, cmdFind, cmdKickoff, cmdStale } from "./commands/read.js";
-import { cmdRotate } from "./commands/rotate.js";
-import { cmdWhere } from "./commands/where.js";
-import {
-  cmdAdd,
-  cmdClaim,
-  cmdClose,
-  cmdHook,
-  cmdRelease,
-  cmdSynced,
-} from "./commands/write.js";
-import { doneDir, planDir } from "./store.js";
-
-const MEM_HELP = `usage: fapony mem [--mem-dir <path>] <sub> [args]
-
-subcommands:
-  where                       show the resolved mem dir and which step won
-  kickoff [<plan.md>] [--pick <n>]   open a session + a next-up list
-  add <kind> "<text>" --files f1,f2 [--key k] [spec.md]
-  close <id> "<msg>"          close a bug
-  find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--key k]
-                          substring-search every row (archives included)
-  done | stale              views
-  claim <id> | release <id> | synced   bookkeeping
-  plan-sweep [<plan.md> [--apply]]     move shipped plans + fix links
-  plan-check <plan.md>        validate a plan's frontmatter/sections
-  rotate                      archive the live log when it grows
-  hook                        Stop-hook payload reader (installed, not run by hand)
-
---mem-dir <path> wins over config and the walk-up (global to every sub)
-example: fapony mem add note "decided X because Y" --files src/a.ts`;
-
-const HELP: Record<string, string> = {
-  where: `usage: fapony mem where [--from <dir>]
-show the .fapony/.memory dir the resolver picks and which step won — writes nothing
-  --from <dir>    resolve as if cwd were here
-example: fapony mem where`,
-  kickoff: `usage: fapony mem kickoff [<plan.md>] [--pick <n>]
-open a session and print a "next up" list (priority plans, unchecked chunks, open bugs)
-  <plan.md>   plan whose first unchecked chunk is offered as a context line
-  --pick <n>  run suggestion [n] non-interactively; refuses context/template items
-example: fapony mem kickoff .fapony/plan/PLAN-x.md`,
-  add: `usage: fapony mem add <next|bug|decision|note|hold> "<text>" --files f1,f2 [--key k] [spec.md]
-append one row to the mem log
-  --files f1,f2   repo-relative paths this row is about (required)
-  --key k         problem identity, bare or domain:sub (e.g. auth:login) — the domain must be in .fapony/keys.json when that file exists (optional)
-  --stdin         read <text> from stdin (avoids shell metachar)
-example: fapony mem add decision "chose X because Y" --files src/a.ts,src/b.ts --key unify-mem-engine`,
-  close: `usage: fapony mem close <id> "<what was done | commit>"
-tombstone a bug so it stops showing as open work
-  --stdin         read the message from stdin
-example: fapony mem close mt14 "fixed in a2c6beb"`,
-  find: `usage: fapony mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--key k]
-substring search over every row's text/spec/ref (rotated archives included) — bookkeeping kinds (close/synced/claim/release) hidden unless --kind names them
-  --kind a,b    include only these kinds (overrides the bookkeeping default)
-  --files f1,f2 rows about these paths (stored files[] first, text/spec/ref fallback)
-  --key k       problem-identity match — a bare domain catches every domain:* (auth matches auth:login); a miss prints the known keys
-  --since 7d    only rows at or after this time (<N>d or YYYY-MM-DD)
-  --limit n     max rows returned (default 20, newest first)
-example: fapony mem find "usage-web" --kind bug,decision --limit 5`,
-  done: `usage: fapony mem done
-closed rows with their tombstone message
-example: fapony mem done`,
-  stale: `usage: fapony mem stale
-decisions that never made it into their spec
-example: fapony mem stale`,
-  claim: `usage: fapony mem claim <id>
-claim an open next|bug before working it
-example: fapony mem claim mt14`,
-  release: `usage: fapony mem release <id> [--stdin]
-give back a claimed row without closing it
-example: fapony mem release mt14`,
-  synced: `usage: fapony mem synced [<spec.md>]
-mark a spec as carried into the log
-example: fapony mem synced .fapony/spec/SPEC-x.md`,
-  "plan-sweep": `usage: fapony mem plan-sweep [<plan.md>] [--apply]
-find shipped plans (or move one) and fix the links that point at it
-  --apply   perform the git mv + link fixes (default = dry run)
-example: fapony mem plan-sweep .fapony/plan/PLAN-x.md --apply`,
-  "plan-check": `usage: fapony mem plan-check <plan.md>
-validate a plan's frontmatter and required sections
-example: fapony mem plan-check .fapony/plan/PLAN-x.md`,
-  rotate: `usage: fapony mem rotate
-archive the live log to log.YYYY-MM-DD.jsonl once it crosses the threshold
-example: fapony mem rotate`,
-  hook: `usage: fapony mem hook
-reads the Stop-hook payload on stdin — installed by fapony, not run by hand
-example: (installed hook only)`,
-};
-
-// Subcommand names for top-level did-you-mean (src/commands.ts) — derived
-// from HELP keys so the list cannot drift from the dispatch below.
-export const MEM_SUBCOMMANDS: string[] = Object.keys(HELP);
-
-// Chunk 7 (PLAN-seed-and-surface, bug muc85pml): `fapony mem now` used to fall
-// through to kickoff and print an overview ("N entries") instead of an error —
-// a typo that looks like success. Three rules, in order:
-//   1. a known subcommand → dispatch (unchanged)
-//   2. looks like a plan path (.md suffix, a slash, or a file with that name
-//      in planDir/doneDir) → kickoff — this is `fapony mem PLAN-x.md`, which
-//      must keep working without the `kickoff` word
-//   3. anything else → error, exit 1 (a typo is never a kickoff)
-//
-// `exists` is injectable so tests hit this directly without a store on disk —
-// production passes nothing and reads planDir/doneDir live.
-export function classifyMemArg(
-  arg: string,
-  exists?: (name: string) => boolean,
-): "subcommand" | "plan" | "unknown" {
-  // hasOwn, not `in` or indexing — prototype props ("toString") are not
-  // subcommands.
-  if (Object.hasOwn(HELP, arg)) return "subcommand";
-  if (arg.endsWith(".md") || arg.includes("/")) return "plan";
-  const has =
-    exists ??
-    ((name: string): boolean => {
-      const base = basename(name);
-      const candidates = [name, base, `${name}.md`, `${base}.md`];
-      return candidates.some(
-        (c) => existsSync(join(planDir, c)) || existsSync(join(doneDir, c)),
-      );
-    });
-  if (has(arg)) return "plan";
-  return "unknown";
-}
-
-export async function cmdMem(a: string[], memDir?: string): Promise<void> {
-  const [cmd, ...rest] = a;
-
-  // SPEC §2: every subcommand answers --help with signature + flags + one runnable
-  // example, because the reader is an agent that gets one call to get it right.
-  if (cmd === "-h" || cmd === "--help") {
-    console.log(MEM_HELP);
-    return;
-  }
-  if (rest.includes("-h") || rest.includes("--help")) {
-    console.log(HELP[cmd] ?? MEM_HELP);
-    return;
-  }
-
-  if (cmd === "add") {
-    await cmdAdd(rest);
-  } else if (cmd === "close") {
-    await cmdClose(rest);
-  } else if (cmd === "claim") {
-    cmdClaim(rest);
-  } else if (cmd === "release") {
-    await cmdRelease(rest);
-  } else if (cmd === "synced") {
-    cmdSynced(rest);
-  } else if (cmd === "hook") {
-    await cmdHook();
-  } else if (cmd === "done") {
-    cmdDone();
-  } else if (cmd === "stale") {
-    cmdStale();
-  } else if (cmd === "find") {
-    cmdFind(rest);
-  } else if (cmd === "kickoff") {
-    cmdKickoff(rest);
-  } else if (cmd === "where") {
-    cmdWhere(rest, memDir);
-  } else if (cmd === "plan-sweep") {
-    cmdPlanSweep(rest);
-  } else if (cmd === "plan-check") {
-    cmdPlanCheck(rest);
-  } else if (cmd === "rotate") {
-    cmdRotate(rest);
-  } else if (cmd === undefined) {
-    // bare `fapony mem` → kickoff (ranked session overview)
-    cmdKickoff(rest);
-  } else if (classifyMemArg(cmd) === "plan") {
-    // `fapony mem PLAN-x.md` — the plan arg rides along (the old else-branch
-    // dropped it and printed the no-arg overview instead).
-    cmdKickoff([cmd, ...rest]);
-  } else {
-    console.error(`fapony mem: unknown subcommand "${cmd}"`);
-    const scored = MEM_SUBCOMMANDS.map((s) => ({
-      s,
-      d: levenshtein(cmd, s),
-    }))
-      .filter((x) => x.d <= 2)
-      .sort((x, y) => x.d - y.d || (x.s < y.s ? -1 : 1))
-      .slice(0, 3)
-      .map((x) => `"fapony mem ${x.s}"`);
-    if (scored.length > 0) {
-      console.error(`did you mean ${scored.join(" or ")}?`);
-    }
-    console.error(`subcommands: ${MEM_SUBCOMMANDS.join(" ")}`);
-    process.exit(1);
-  }
-}

package/src/mem/key-registry.ts

@@ -1,116 +0,0 @@
-// src/mem/key-registry.ts — domain key registry (`domain:sub`).
-//
-// PLAN-mem-core chunk 4: keys an agent invents never converge (3%), so a repo
-// that wants convergence declares its domains in `.fapony/keys.json`, beside
-// `conventions.json` — fixed path, no config field (rule: never add a field
-// derivable from structure). No file = keys stay free-form (never reject);
-// a file = the domain half must be listed, the sub half stays free.
-//
-// Shape: {"domains": ["auth", "hook"]} (a bare ["auth"] array reads the same).
-
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { FAPONY_DIR, KEYS_FILE, KEYS_FILENAME } from "../core/config.js";
-import { KEY_SEGMENT_RE } from "../core/mem-log.js";
-import { resolveMemDir } from "../memory.js";
-
-/** Split `domain:sub` — null domain = a bare legacy key, always allowed. */
-export function splitKey(key: string): { domain: string; sub: string } | null {
-  const i = key.indexOf(":");
-  if (i < 0) return null;
-  return { domain: key.slice(0, i), sub: key.slice(i + 1) };
-}
-
-/**
- * A bare domain query doubles as a prefix: `auth` matches the exact key
- * `auth` and every `auth:*`. A query carrying a colon is an exact match —
- * `auth:login` never pulls in `auth:logout`.
- */
-export function keyMatchesQuery(
-  rowKey: string | undefined,
-  query: string,
-): boolean {
-  if (!rowKey) return false;
-  if (query.includes(":")) return rowKey === query;
-  return rowKey === query || rowKey.startsWith(`${query}:`);
-}
-
-export function resolveKeysPath(worktree: string): string | null {
-  // Same anchor as conventions.json: the .fapony/ dir holding the mem log,
-  // so the registry and the log cannot drift apart.
-  const memDir = resolveMemDir(worktree);
-  const base = memDir ? join(memDir, "..") : join(worktree, FAPONY_DIR);
-  const app = join(base, KEYS_FILENAME);
-  if (existsSync(app)) return app;
-  const root = join(worktree, KEYS_FILE);
-  return existsSync(root) ? root : null;
-}
-
-export interface KeyRegistry {
-  path: string | null;
-  /** Sorted, deduped, segment-valid — the list reject messages print. */
-  domains: string[];
-  warnings: string[];
-}
-
-/** Missing file = empty + no error (same contract as conventions.json). */
-export function loadKeyRegistry(worktree: string): KeyRegistry {
-  const path = resolveKeysPath(worktree);
-  if (!path) return { path: null, domains: [], warnings: [] };
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf-8");
-  } catch {
-    return { path, domains: [], warnings: [`keys.json unreadable: ${path}`] };
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (e) {
-    return {
-      path,
-      domains: [],
-      warnings: [
-        `keys.json is not valid JSON — ${
-          e instanceof Error ? e.message.split("\n")[0] : "parse error"
-        }`,
-      ],
-    };
-  }
-  const rows: unknown[] = Array.isArray(parsed)
-    ? parsed
-    : Array.isArray((parsed as { domains?: unknown }).domains)
-      ? (parsed as { domains: unknown[] }).domains
-      : [];
-  const seen = new Set<string>();
-  let dropped = 0;
-  for (const r of rows) {
-    if (typeof r === "string" && KEY_SEGMENT_RE.test(r)) seen.add(r);
-    else dropped++;
-  }
-  const warnings =
-    dropped > 0
-      ? [
-          `keys.json: ${dropped} entr${dropped === 1 ? "y" : "ies"} dropped (not [a-z0-9-]{3,40})`,
-        ]
-      : [];
-  return { path, domains: [...seen].sort(), warnings };
-}
-
-/**
- * null domains = no registry on disk = free-form keys (never reject).
- * A registry gates only the domain half; bare keys stay backward compatible.
- */
-export function checkKeyDomain(
-  key: string,
-  domains: string[] | null | undefined,
-): string | null {
-  if (domains == null) return null;
-  const split = splitKey(key);
-  if (!split) return null;
-  if (domains.includes(split.domain)) return null;
-  return (
-    `unknown key domain "${split.domain}" — known domains: ` +
-    (domains.length ? domains.join(", ") : "(none yet)")
-  );
-}