fapony 0.3.4 → 0.3.6

package/src/mem/commands/read.ts

@@ -2,12 +2,14 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { parseSince } from "../../core/since.js";
 import { baselinePath, readEvidenceLintCmd } from "../../lint-baseline.js";
+import { CLI_FIND_EXCLUDE, engineFind } from "../engine.js";
 import { doneLines, fmtClose, fmtRow } from "../render.js";
 import { claimsOf, openRows, staleReport } from "../selectors.js";
 import type { CloseRow, WorkRow } from "../store.js";
 import { allRows, app, memCmd, planDir, root, rows } from "../store.js";
-import { planSweepCmd, shippedNotMoved } from "./plan.js";
+import { checkTickedLine, planSweepCmd, shippedNotMoved } from "./plan.js";
 import { THRESHOLD } from "./rotate.js";
 
 /** Files changed on this branch vs dev — empty set when dev is missing or diff fails. */
@@ -65,58 +67,186 @@ export const cmdStale = () => {
 };
 
 export const cmdFind = (a: string[]) => {
-  // mem find <word> — grep text/spec case-insensitively, newest first, capped at 20 rows
-  const q = a.join(" ").toLowerCase();
-  if (!q) {
-    console.error(`usage: ${memCmd} find <word>`);
+  // mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--open]
+  // Query logic lives in the shared engine (../engine.ts) — this wrapper owns
+  // only argv parsing + the single-line print. MCP memFind calls the same
+  // engine with no kind default (contract); CLI keeps its legacy default of
+  // hiding bookkeeping rows unless --kind names them (PLAN-unify-mem-engine).
+  const flagVal = (flag: string, i: number): string | undefined => {
+    const t = a[i];
+    const eq = `${flag}=`;
+    if (t.startsWith(eq)) return t.slice(eq.length);
+    return a[i + 1];
+  };
+  const consumed = (flag: string, i: number): number => {
+    if (a[i].startsWith(`${flag}=`)) return 1;
+    return 2;
+  };
+
+  let kind: string[] | undefined;
+  let files: string[] | undefined;
+  let sinceRaw: string | undefined;
+  let limit: number | undefined;
+  let open = false;
+  const positional: string[] = [];
+
+  for (let i = 0; i < a.length; ) {
+    const t = a[i];
+    if (t === "--kind" || t.startsWith("--kind=")) {
+      const v = flagVal("--kind", i);
+      if (!v || v.startsWith("--")) {
+        console.error(
+          `--kind needs a value — usage: ${memCmd} find "<text>" --kind bug,decision`,
+        );
+        process.exit(1);
+      }
+      kind = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      i += consumed("--kind", i);
+    } else if (t === "--files" || t.startsWith("--files=")) {
+      const v = flagVal("--files", i);
+      if (!v || v.startsWith("--")) {
+        console.error(
+          `--files needs a value — usage: ${memCmd} find --files path/to/file.ts[,more]`,
+        );
+        process.exit(1);
+      }
+      files = v
+        .split(",")
+        .map((s) => s.trim().replace(/^\.\//, ""))
+        .filter(Boolean);
+      i += consumed("--files", i);
+    } else if (t === "--since" || t.startsWith("--since=")) {
+      const v = flagVal("--since", i);
+      if (!v || v.startsWith("--")) {
+        console.error(`--since needs a value — use <N>d or YYYY-MM-DD`);
+        process.exit(1);
+      }
+      sinceRaw = v;
+      i += consumed("--since", i);
+    } else if (t === "--limit" || t.startsWith("--limit=")) {
+      const v = flagVal("--limit", i);
+      const n = Number(v);
+      if (!v || v.startsWith("--") || !Number.isInteger(n) || n < 0) {
+        console.error(
+          `--limit needs a non-negative integer — got "${v ?? ""}"`,
+        );
+        process.exit(1);
+      }
+      limit = n;
+      i += consumed("--limit", i);
+    } else if (t === "--open") {
+      open = true;
+      i += 1;
+    } else {
+      positional.push(t);
+      i += 1;
+    }
+  }
+
+  const q = positional.join(" ").trim();
+  if (
+    !q &&
+    !kind?.length &&
+    !files?.length &&
+    !sinceRaw &&
+    limit === undefined &&
+    !open
+  ) {
+    console.error(
+      `usage: ${memCmd} find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--open]`,
+    );
     process.exit(1);
   }
+
+  let sinceIso: string | undefined;
+  if (sinceRaw) {
+    try {
+      sinceIso = parseSince(sinceRaw).iso;
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+  }
+
   // allRows, not rows: find is recall — rotated history counts
-  const hits = allRows()
-    .filter(
-      (r): r is WorkRow =>
-        r.kind !== "close" &&
-        r.kind !== "synced" &&
-        r.kind !== "claim" &&
-        r.kind !== "release",
-    )
-    .filter(
-      (r) =>
-        r.text.toLowerCase().includes(q) ||
-        (r.spec ?? "").toLowerCase().includes(q),
-    )
-    .slice(-20);
-  for (const r of hits)
-    console.log(
-      `- [${r.id}] ${r.ts.slice(0, 10)} ${r.kind} ${r.text}${r.spec ? ` → ${r.spec}` : ""}`,
-    );
+  const { rows: newest } = engineFind(allRows(), {
+    text: q || undefined,
+    files,
+    kind,
+    excludeKind: kind?.length ? undefined : CLI_FIND_EXCLUDE,
+    sinceIso,
+    limit,
+    open: open || undefined,
+  });
+  // Legacy order: oldest first (engine returns newest first — same set, CLI print order unchanged)
+  const hits = [...newest].reverse();
+  for (const r of hits) {
+    if ("id" in r) {
+      console.log(
+        `- [${r.id}] ${r.ts.slice(0, 10)} ${r.kind} ${r.text ?? ""}${r.spec ? ` → ${r.spec}` : ""}`,
+      );
+    } else {
+      const label = "ref" in r && r.ref ? `${r.ref}(${r.kind})` : r.kind;
+      const body = ("text" in r && r.text) || ("spec" in r && r.spec) || "";
+      console.log(`- [${label}] ${r.ts.slice(0, 10)} ${r.kind} ${body}`);
+    }
+  }
   if (!hits.length) console.log("(no matches)");
 };
 
-/** Read a plan file and extract unchecked checkboxes from the TL;DR section. */
-const readPlanCheckboxes = (planPath: string): string[] => {
+/** Read a plan file and extract checked + unchecked items from the first ## section. */
+const readPlanSectionItems = (
+  planPath: string,
+): { checked: string[]; unchecked: string[] } => {
   try {
     const text = readFileSync(planPath, "utf8");
     // Skip frontmatter
     const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---/, "");
     // Find the first ## section (TL;DR)
     const start = body.search(/^##\s+/m);
-    if (start < 0) return [];
+    if (start < 0) return { checked: [], unchecked: [] };
     const rest = body.slice(start);
     const next = rest.slice(3).search(/^##\s+/m);
     const block = next < 0 ? rest : rest.slice(0, next + 3);
-    // Extract unchecked checkboxes
-    const items: string[] = [];
+    // Extract checkboxes — ticked and unticked
+    const checked: string[] = [];
+    const unchecked: string[] = [];
     for (const line of block.split("\n")) {
-      const m = /^\s*[-*]\s+\[\s\]\s+(.+)$/.exec(line);
-      if (m) items.push(m[1].trim());
+      let m = /^\s*[-*]\s+\[\s\]\s+(.+)$/.exec(line);
+      if (m) {
+        unchecked.push(m[1].trim());
+        continue;
+      }
+      m = /^\s*[-*]\s+\[[xX]\]\s+(.+)$/.exec(line);
+      if (m) checked.push(m[1].trim());
     }
-    return items;
+    return { checked, unchecked };
   } catch {
-    return [];
+    return { checked: [], unchecked: [] };
   }
 };
 
+// Chunk 9 (PLAN-seed-and-surface): one line under the next-chunk display
+// saying whether the last ticked chunk actually closed. Verified shas stay
+// silent; only the newest ticked chunk is ever mentioned — one line per
+// kickoff, never a list (else vela's 64/72 sha-less chunks become noise).
+const closureHint = (checked: string[]): string | null => {
+  const last = checked[checked.length - 1];
+  if (!last) return null;
+  const { missing, diverged, cited } = checkTickedLine(last, root);
+  const label = /chunk\s+([^\s—–-]+)/i.exec(last)?.[1] ?? "latest";
+  if (missing.length)
+    return `⚠ chunk ${label} is ticked but ${missing[0]} is not in git — nothing proves it closed`;
+  if (diverged.length)
+    return `⚠ chunk ${label} is ticked but ${diverged[0]} is not on HEAD (rebased away?)`;
+  if (!cited)
+    return `⚠ chunk ${label} is ticked but cites no commit — nothing to verify it closed`;
+  return null;
+};
+
 /** Check if a plan has `priority: high` in its frontmatter. */
 const hasHighPriority = (planPath: string): boolean => {
   try {
@@ -200,6 +330,7 @@ export const cmdKickoff = (a: string[]) => {
   // If no arg or arg didn't match an id/spec, check if it's a plan file
   let planFile: string | null = null;
   let planCheckboxes: string[] = [];
+  let planChecked: string[] = [];
 
   if (arg && !resolvedSpec && !target) {
     if (matches.length === 1) {
@@ -233,14 +364,18 @@ export const cmdKickoff = (a: string[]) => {
 
   // Read plan file if we found one (or if a .md arg matched a spec)
   if (planFile) {
-    planCheckboxes = readPlanCheckboxes(planFile);
+    const items = readPlanSectionItems(planFile);
+    planCheckboxes = items.unchecked;
+    planChecked = items.checked;
   } else if (arg && resolvedSpec && arg.endsWith(".md")) {
     // The spec resolved from the log might be a plan file — try to read it
     const dir = planDir;
     const byName = join(dir, basename(arg));
     if (existsSync(byName)) {
       planFile = byName;
-      planCheckboxes = readPlanCheckboxes(planFile);
+      const items = readPlanSectionItems(planFile);
+      planCheckboxes = items.unchecked;
+      planChecked = items.checked;
     }
   }
 
@@ -301,7 +436,7 @@ export const cmdKickoff = (a: string[]) => {
   const uniqueRecent = [...new Set(recentFiles)].slice(0, GROUP_CAP);
   if (uniqueRecent.length) {
     suggestions.push({
-      text: `แตะล่าสุด: ${uniqueRecent.join(", ")}`,
+      text: `Recently touched: ${uniqueRecent.join(", ")}`,
       run: `fapony review-seed --files ${uniqueRecent.join(",")}`,
     });
   }
@@ -310,7 +445,7 @@ export const cmdKickoff = (a: string[]) => {
   try {
     if (readEvidenceLintCmd(root) && !existsSync(baselinePath(root))) {
       suggestions.push({
-        text: "lint baseline ยังไม่ capture — แดงที่มีอยู่ก่อนจะถูกนับเป็นของคุณ",
+        text: "lint baseline not captured yet — pre-existing red will count as yours",
         run: "fapony lint-baseline --capture",
       });
     }
@@ -466,6 +601,12 @@ export const cmdKickoff = (a: string[]) => {
     if (!specRows.length && !specDecisions.length && !specCloses.length) {
       console.log("(no entries for this spec)");
     }
+    // The spec is also a plan file on disk — say whether the last ticked
+    // chunk actually closed (chunk 9). Silent when it verifies.
+    if (planFile) {
+      const hint = closureHint(planChecked);
+      if (hint) console.log(`\n${hint}`);
+    }
   } else if (target) {
     // id = a brief for that task
     const claims = claimsOf(all);
@@ -525,6 +666,10 @@ export const cmdKickoff = (a: string[]) => {
     } else {
       console.log(`\n(all chunks checked — ready to ship or archive)`);
     }
+    // Whether the last ticked chunk actually closed (chunk 9) — one line,
+    // silent when its sha verifies.
+    const hint = closureHint(planChecked);
+    if (hint) console.log(hint);
   } else if (arg) {
     console.error(`no id "${arg}" in the log`);
     process.exit(1);

package/src/mem/commands/write.ts

@@ -1,8 +1,9 @@
 // commands/write.ts — mutating commands: add, close, claim, release, synced, hook
 
+import { CapError, engineAdd, engineClose } from "../engine.js";
 import { claimsOf, openRows } from "../selectors.js";
 import type { WorkKind } from "../store.js";
-import { KINDS, memCmd, nextId, put, root, rows } from "../store.js";
+import { KINDS, memCmd, put, root, rows } from "../store.js";
 
 export const cmdAdd = async (a: string[]) => {
   // mem add <next|bug|decision|note|hold> "<text>" --files f1,f2 [path/to/SPEC.md]
@@ -65,33 +66,23 @@ export const cmdAdd = async (a: string[]) => {
     }
     text = filtered.join(" ");
   }
-  // read once — cap check + id collision
-  const all = rows();
-  // ponytail: a cap on open next/hold stops endless accumulation — forces triage of the old before opening new
-  const CAP = 15;
-  const CAP_HOLD = 10;
-  if (a[0] === "next" && !process.env.MEM_FORCE) {
-    const openNext = openRows(all).filter((r) => r.kind === "next").length;
-    if (openNext >= CAP) {
-      console.error(
-        `open next ${openNext}/${CAP} is full — close an old one first (or MEM_FORCE=1 if you really must)`,
-      );
-      process.exit(1);
-    }
-  }
-  if (a[0] === "hold" && !process.env.MEM_FORCE) {
-    const openHold = openRows(all).filter((r) => r.kind === "hold").length;
-    if (openHold >= CAP_HOLD) {
-      console.error(
-        `open hold ${openHold}/${CAP_HOLD} is full — close/release an old one first (or MEM_FORCE=1)`,
-      );
-      process.exit(1);
+  // Domain rules (caps, id) live in the shared engine — this wrapper owns
+  // only argv surface and the MEM_FORCE hint wording (PLAN-unify-mem-engine).
+  try {
+    const { id } = engineAdd({ kind: a[0], text, spec, files });
+    console.log(id);
+  } catch (e) {
+    if (e instanceof CapError) {
+      const hint =
+        e.cap === "next"
+          ? " (or MEM_FORCE=1 if you really must)"
+          : " (or MEM_FORCE=1)";
+      console.error(`${e.message}${hint}`);
+    } else {
+      console.error(e instanceof Error ? e.message : String(e));
     }
+    process.exit(1);
   }
-  // ponytail: prevent id collisions — logic centralized in nextId (store.ts)
-  const id = nextId(all);
-  put({ id, kind: a[0] as WorkKind, text, spec, files });
-  console.log(id);
 };
 
 export const cmdClose = async (a: string[]) => {
@@ -101,10 +92,6 @@ export const cmdClose = async (a: string[]) => {
     console.error(`id is required — usage: ${memCmd} close <id> "<text>"`);
     process.exit(1);
   }
-  if (!rows().some((r) => "id" in r && r.id === a[0])) {
-    console.error(`no id "${a[0]}" in the log`);
-    process.exit(1);
-  }
   const rest = a.slice(1);
   const useStdin = rest.includes("--stdin");
   let text: string;
@@ -113,7 +100,15 @@ export const cmdClose = async (a: string[]) => {
   } else {
     text = rest.join(" ");
   }
-  put({ kind: "close", ref: a[0], text });
+  // Tombstone rules (id must exist, text required) live in the shared engine —
+  // note this tightens CLI: an empty-text close now errors instead of writing
+  // a textless tombstone (intentional, PLAN-unify-mem-engine §4).
+  try {
+    engineClose({ id: a[0], text });
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
 };
 
 export const cmdClaim = (a: string[]) => {

package/src/mem/engine.ts

@@ -0,0 +1,249 @@
+// 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 { 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;
+}
+
+export interface EngineAddResult {
+  id: string;
+  kind: string;
+  text: string;
+  files: string[];
+  spec?: 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>");
+  }
+
+  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();
+  put({
+    id,
+    kind: a.kind as WorkKind,
+    text: a.text,
+    spec: a.spec,
+    files: a.files,
+  });
+  return { id, kind: a.kind, text: a.text, files: a.files, spec: a.spec, 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;
+}
+
+export interface EngineFindResult<T> {
+  rows: T[];
+  total: number;
+}
+
+export type FindableRow = {
+  kind: string;
+  text?: string;
+  spec?: string;
+  ref?: string;
+  files?: 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));
+  }
+
+  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 };
+}