@lh8ppl/claude-memory-kit 0.1.0

package/src/reindex.mjs

@@ -0,0 +1,134 @@
+// Granular-archive pointer-index writer (Task 8, refactored in
+// cleanup-layer-2-cross-module-drift). Single public boundary:
+// reindex(opts) → result. See design §2.3.
+//
+// Uses shared modules: tier-paths (path resolution), frontmatter (js-yaml
+// parse). See CLAUDE.md "Shared modules" rule.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { VALID_TIERS, resolveTierRoot, resolveFactDir } from './tier-paths.mjs';
+import { parse } from './frontmatter.mjs';
+
+const INDEX_SIZE_WARN_BYTES = 25 * 1024;
+const HOOK_MAX_LEN = 80;
+
+const TIER_LABEL = {
+  P: 'project tier',
+  L: 'local tier',
+  U: 'user tier',
+};
+
+function extractHook(body) {
+  for (const raw of body.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith('#')) continue;
+    if (line.length > HOOK_MAX_LEN) {
+      return line.slice(0, HOOK_MAX_LEN).trimEnd() + '...';
+    }
+    return line;
+  }
+  return '';
+}
+
+function formatIndexLine({ id, type, title, filename, hook }) {
+  const head = `- (${id}) [${type}] [${title}](${filename})`;
+  return hook ? `${head} — ${hook}` : head;
+}
+
+function listFactFiles(factDir) {
+  if (!existsSync(factDir)) return [];
+  const out = [];
+  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'INDEX.md') continue;
+    out.push(entry.name);
+  }
+  return out.sort();
+}
+
+export function reindex(opts = {}) {
+  const { tier, projectRoot, userDir, warn } = opts;
+  if (!tier || !VALID_TIERS.has(tier)) {
+    throw new Error(
+      `reindex: invalid tier ${JSON.stringify(tier)}. Must be 'U', 'P', or 'L'.`,
+    );
+  }
+  const emit = warn ?? ((msg) => process.stderr.write(msg + '\n'));
+  const warnings = [];
+  function pushWarning(msg) {
+    warnings.push(msg);
+    emit(msg);
+  }
+
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const factDir = resolveFactDir(tier, tierRoot);
+  mkdirSync(factDir, { recursive: true });
+
+  const entries = [];
+  for (const filename of listFactFiles(factDir)) {
+    const path = join(factDir, filename);
+    let text;
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch (e) {
+      pushWarning(`reindex: failed to read ${filename}: ${e.message}`);
+      continue;
+    }
+    const { frontmatter, body, parseError } = parse(text);
+    if (!frontmatter) {
+      pushWarning(
+        `reindex: ${filename} skipped — ${parseError ?? 'no YAML frontmatter'}`,
+      );
+      continue;
+    }
+    if (!frontmatter.id || !frontmatter.type || !frontmatter.title) {
+      pushWarning(
+        `reindex: ${filename} skipped — missing required frontmatter field(s) (id/type/title)`,
+      );
+      continue;
+    }
+    if (frontmatter.deleted_at) continue;
+    entries.push({
+      id: frontmatter.id,
+      type: frontmatter.type,
+      title: frontmatter.title,
+      filename,
+      hook: extractHook(body),
+    });
+  }
+
+  entries.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const header = `# Granular memory index — ${TIER_LABEL[tier]}\n\n## Files\n`;
+  const bodyLines = entries.map(formatIndexLine).join('\n');
+  const content = entries.length
+    ? `${header}\n${bodyLines}\n`
+    : `${header}\n`;
+
+  const indexPath = join(factDir, 'INDEX.md');
+  writeFileSync(indexPath, content, 'utf8');
+
+  const bytes = Buffer.byteLength(content, 'utf8');
+  if (bytes > INDEX_SIZE_WARN_BYTES) {
+    pushWarning(
+      `reindex: ${indexPath} is ${(bytes / 1024).toFixed(1)} KB (>25 KB); consider consolidation`,
+    );
+  }
+
+  return {
+    tier,
+    indexPath,
+    factCount: entries.length,
+    bytes,
+    warnings,
+  };
+}

package/src/repair.mjs

@@ -0,0 +1,316 @@
+// `cmk repair` (Task 39, T-033, parts 39.1–39.3).
+//
+// Public boundary:
+//   async runRepair({projectRoot, scope: 'hooks'|'locks'|'index'|'all', staleLockMs?, reindexer?})
+//     → {action, scope, repairs: [...], errors, duration_ms}
+//
+// Three repair scopes:
+//   - 'hooks'  : deep-merge the kit's canonical hooks block from plugin/hooks/hooks.json
+//                into <projectRoot>/.claude/settings.json. Idempotent. Closes HC-2 failures.
+//   - 'locks'  : remove stale lock files (default >1h old; configurable via staleLockMs).
+//                Live locks (holderAlive: true) are preserved. Closes HC-9 failures.
+//   - 'index'  : invoke cmk reindex --full (Task 29's reindexFull boundary). Closes HC-5 failures.
+//   - 'all'    : run all three in order. Default scope when --all flag is set OR no scope provided
+//                (v0.1.0 defaults to NO-OP if no scope flag — user must opt in to repairs).
+//
+// Per design §14 + tasks.md 39 (39.1–39.3).
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  appendAuditEntry,
+  nowIso,
+  REASON_CODES,
+} from './audit-log.mjs';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+import { detectStaleLocks } from './lock-discipline.mjs';
+
+const DEFAULT_STALE_LOCK_MS = 60 * 60 * 1000; // 1 hour
+const SETTINGS_REL = ['.claude', 'settings.json'];
+
+// I1 fix (Task 39 skill-review 2026-05-28): the canonical hooks block
+// is embedded INLINE as a JS constant instead of being read from
+// plugin/hooks/hooks.json. Rationale: packages/cli/package.json `files`
+// lists ['bin/', 'src/', 'README.md'] — the plugin/ tree is OUTSIDE the
+// published @lh8ppl/claude-memory-kit tarball. Reading from plugin/ works
+// in-repo (where __dirname resolves up to the repo root) but breaks
+// post-`npm install -g` where plugin/ doesn't exist.
+//
+// Same Task-33-B1 class of bug: cron-emission paths were also broken
+// post-npm-install-g until they embedded absolute paths at registration
+// time. The embed-the-canonical-constant pattern is the durable fix.
+//
+// Source of truth: keep this in sync with plugin/hooks/hooks.json. A
+// future validator (scripts/validate-hooks-block-sync.mjs) would catch
+// drift automatically; v0.1.x candidate.
+const KIT_HOOKS_BLOCK = Object.freeze({
+  Setup: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-version-check"', timeout: 30 }] }],
+  SessionStart: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-inject-context"', timeout: 30 }] }],
+  UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-capture-prompt"', timeout: 10 }] }],
+  PostToolUse: [{ matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-observe-edit"', async: true, timeout: 120 }] }],
+  Stop: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-capture-turn"', timeout: 30 }] }],
+  SessionEnd: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-compress-session"', timeout: 60 }] }],
+});
+
+/**
+ * Repair `<projectRoot>/.claude/settings.json` by merging in the kit's
+ * canonical hooks block. Preserves any other top-level keys + non-kit
+ * hook entries (e.g., the user's own PreToolUse hooks under different
+ * matchers).
+ */
+function repairHooks({ projectRoot, ts }) {
+  // I1 fix: use the inlined KIT_HOOKS_BLOCK constant; no file read,
+  // no npm-install-g brittleness.
+  const kitHooks = KIT_HOOKS_BLOCK;
+
+  const settingsPath = join(projectRoot, ...SETTINGS_REL);
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch (err) {
+      return {
+        kind: 'hooks',
+        changed: false,
+        error: `${settingsPath} parse error: ${err?.message ?? err}`,
+      };
+    }
+  }
+
+  const before = JSON.stringify(settings);
+  if (!settings.hooks || typeof settings.hooks !== 'object') {
+    settings.hooks = {};
+  }
+
+  // Merge each event array: replace the kit's hook entries (matched by
+  // command substring) with the canonical version; keep any user-added
+  // entries that don't reference the kit.
+  const KIT_COMMAND_TOKENS = [
+    'cmk-version-check',
+    'cmk-inject-context',
+    'cmk-capture-prompt',
+    'cmk-observe-edit',
+    'cmk-capture-turn',
+    'cmk-compress-session',
+  ];
+  const isKitEntry = (entry) => {
+    if (!entry || typeof entry !== 'object') return false;
+    // Entry shape varies: {command} or {hooks: [{command}]}.
+    const collectCommands = (e) => {
+      const cmds = [];
+      if (typeof e.command === 'string') cmds.push(e.command);
+      if (Array.isArray(e.hooks)) {
+        for (const h of e.hooks) if (typeof h.command === 'string') cmds.push(h.command);
+      }
+      return cmds;
+    };
+    const cmds = collectCommands(entry);
+    return cmds.some((c) => KIT_COMMAND_TOKENS.some((t) => c.includes(t)));
+  };
+
+  for (const [eventName, kitEntries] of Object.entries(kitHooks)) {
+    const existing = Array.isArray(settings.hooks[eventName])
+      ? settings.hooks[eventName]
+      : [];
+    const userEntries = existing.filter((e) => !isKitEntry(e));
+    settings.hooks[eventName] = [...userEntries, ...kitEntries];
+  }
+
+  const after = JSON.stringify(settings);
+  const changed = before !== after;
+
+  if (changed) {
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  }
+
+  // I3 fix (Task 39 skill-review 2026-05-28): emit a Door-4 audit
+  // entry per outcome. cmk repair mutates user-visible state; without
+  // this, a "cmk repair broke my settings.json" report two weeks from
+  // now has no audit trail.
+  try {
+    appendAuditEntry(join(projectRoot, 'context'), {
+      ts,
+      action: 'repair',
+      tier: 'P',
+      id: 'P-RPHKAPLD', // synthetic stable id for hooks-repair events (base32 alphabet)
+      reasonCode: changed ? REASON_CODES.REPAIR_HOOKS_APPLIED : REASON_CODES.REPAIR_HOOKS_NOOP,
+      extra: { settingsPath, events: Object.keys(kitHooks) },
+    });
+  } catch {
+    // best-effort — never block repair on audit-log failure
+  }
+
+  return {
+    kind: 'hooks',
+    changed,
+    settingsPath,
+    events: Object.keys(kitHooks),
+  };
+}
+
+/**
+ * Repair stale locks under <projectRoot>/context/.locks/ +
+ * <userDir>/.locks/. Removes locks older than staleLockMs whose holder
+ * process is no longer alive. Live locks are preserved.
+ */
+function repairLocks({ projectRoot, userDir, staleLockMs, now, ts }) {
+  const stale = detectStaleLocks(projectRoot, { userDir }).filter((r) => r.stale);
+  const removed = [];
+  const preserved = [];
+  // M1 fix (skill-review 2026-05-28): nowMs is anchored once and used
+  // for BOTH cutoff comparison AND preserved-entry ageMs reporting. Old
+  // code used injected `now` for cutoff but Date.now() for ageMs, which
+  // produced confusing test fixtures if anyone asserted on age values.
+  const nowMs = now ? new Date(now).getTime() : Date.now();
+  const cutoffMs = nowMs - staleLockMs;
+  for (const lock of stale) {
+    let mtimeMs;
+    try {
+      mtimeMs = statSync(lock.path).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (mtimeMs > cutoffMs) {
+      // Stale but recent (within the staleLockMs window) — keep for now
+      preserved.push({ path: lock.path, ageMs: nowMs - mtimeMs, reason: 'within-cutoff' });
+      continue;
+    }
+    try {
+      unlinkSync(lock.path);
+      removed.push({ path: lock.path, reason: lock.reason });
+    } catch (err) {
+      preserved.push({
+        path: lock.path,
+        ageMs: nowMs - mtimeMs,
+        reason: `unlink-failed: ${err?.message ?? err}`,
+      });
+    }
+  }
+  // I3 fix (skill-review 2026-05-28): emit a Door-4 audit entry per
+  // removed lock so the audit trail records every file deletion the
+  // repair pipeline performed. Without this, a "cmk repair deleted my
+  // lock" post-mortem has nothing to read.
+  for (const r of removed) {
+    try {
+      appendAuditEntry(join(projectRoot, 'context'), {
+        ts,
+        action: 'repair',
+        tier: 'P',
+        id: 'P-RPLKRMVD', // synthetic stable id for repair-lock-removed events (base32 alphabet)
+        reasonCode: REASON_CODES.REPAIR_LOCK_REMOVED,
+        extra: { path: r.path, reason: r.reason },
+      });
+    } catch {
+      // best-effort
+    }
+  }
+  return {
+    kind: 'locks',
+    changed: removed.length > 0,
+    removed,
+    preserved,
+  };
+}
+
+/**
+ * Repair the SQLite + FTS5 index by invoking the reindex full pipeline
+ * (Task 29's reindexFull). Lazy-loaded so test imports don't pull in
+ * the better-sqlite3 binary unnecessarily.
+ *
+ * @param {object} opts
+ * @param {Function} [opts.reindexer]  test-injected reindex function; defaults to import('./index-rebuild.mjs').reindexFull
+ */
+async function repairIndex({ projectRoot, userDir, reindexer }) {
+  let reindexFn = reindexer;
+  if (!reindexFn) {
+    const mod = await import('./index-rebuild.mjs');
+    reindexFn = mod.reindexFull;
+  }
+  if (typeof reindexFn !== 'function') {
+    return {
+      kind: 'index',
+      changed: false,
+      error: 'reindexFull is not a function',
+    };
+  }
+  try {
+    const r = await reindexFn({ projectRoot, userDir });
+    return {
+      kind: 'index',
+      changed: true,
+      result: r,
+    };
+  } catch (err) {
+    return {
+      kind: 'index',
+      changed: false,
+      error: `reindex failed: ${err?.message ?? err}`,
+    };
+  }
+}
+
+/**
+ * Public boundary: run the repair pipeline.
+ *
+ * @returns {Promise<object>}
+ */
+export async function runRepair({
+  projectRoot,
+  userDir,
+  scope = 'all',
+  staleLockMs = DEFAULT_STALE_LOCK_MS,
+  reindexer,
+  now,
+} = {}) {
+  const ts = now ?? nowIso();
+  const t0 = Date.now();
+  if (!projectRoot) {
+    return errorResult({
+      category: ERROR_CATEGORIES.MISSING_PROJECT_ROOT,
+      errors: ['projectRoot is required'],
+      duration_ms: Date.now() - t0,
+    });
+  }
+  if (!['hooks', 'locks', 'index', 'all'].includes(scope)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`invalid scope: ${scope}; expected 'hooks' | 'locks' | 'index' | 'all'`],
+      duration_ms: Date.now() - t0,
+    });
+  }
+
+  const scopes = scope === 'all' ? ['hooks', 'locks', 'index'] : [scope];
+  const repairs = [];
+  let errors = 0;
+  for (const s of scopes) {
+    if (s === 'hooks') {
+      const r = repairHooks({ projectRoot, ts });
+      if (r.error) errors += 1;
+      repairs.push(r);
+    } else if (s === 'locks') {
+      const r = repairLocks({ projectRoot, userDir, staleLockMs, now: ts, ts });
+      if (r.error) errors += 1;
+      repairs.push(r);
+    } else if (s === 'index') {
+      // eslint-disable-next-line no-await-in-loop
+      const r = await repairIndex({ projectRoot, userDir, reindexer });
+      if (r.error) errors += 1;
+      repairs.push(r);
+    }
+  }
+  return {
+    action: 'completed',
+    scope,
+    repairs,
+    errors,
+    duration_ms: Date.now() - t0,
+  };
+}

package/src/result-shapes.mjs

@@ -0,0 +1,155 @@
+// Canonical result-shape conventions for cmk public boundaries.
+//
+// Per the Layer-2 review's I3 finding, `errorCategory` was tagged inconsistently
+// across the four modules: writeFact set it; forget never did; mergeFacts set it
+// only for input validation. A consumer doing `if (r.errorCategory === 'schema')`
+// branched correctly for some failures and missed others. This module pins down
+// the enum + provides helpers so error returns are uniform.
+//
+// Public surface:
+//   ERROR_CATEGORIES — frozen enum of errorCategory values
+//   ACTION_TYPES     — frozen enum of action values
+//   errorResult({category, errors, ...rest}) → canonical error result object
+//   notFoundResult({errors, ...rest}) → canonical not-found result object
+//
+// The canonical result shape for write-side boundaries is:
+//   { action: enum, id?, path?, errorCategory?, errors?, ...extras }
+// Where action is the discriminator. errorCategory + errors only appear when
+// action === 'error'. See CLAUDE.md "Shared modules" + design §1.3.
+
+export const ERROR_CATEGORIES = Object.freeze({
+  // Input shape wrong — a validation rule was violated. Caller passed bad
+  // arguments. Most validateOptions failures use this.
+  SCHEMA: 'schema',
+
+  // Runtime constraint violated. The arguments looked valid but the operation
+  // can't proceed without corrupting existing state. Examples:
+  //   - mergeFacts: merged body would dedup against an unrelated existing fact
+  //   - writeFact: same path exists with a different id (would overwrite)
+  COLLISION: 'collision',
+
+  // Lookup failed at runtime. Used by callers that distinguish "I couldn't
+  // find what you asked for" from "your input was wrong" — typically pairs
+  // with action: 'not-found' for the cleanest UX, but errorCategory: 'not-found'
+  // is available for write-side boundaries that need to report missing
+  // referenced ids without a discriminator change.
+  NOT_FOUND: 'not-found',
+
+  // Another writer holds a lock; retry later. Used by the auto-extract
+  // subagent (Task 23) when a prior invocation still holds the
+  // context/.locks/auto-extract.lock file.
+  CONCURRENT_RUN: 'concurrent_run',
+
+  // A scratchpad write would push the file past its configured cap even
+  // after consolidation (Task 12, design §2.1). Caller chose not to
+  // forcibly truncate; the write is rejected so no silent data loss.
+  CAP_EXCEEDED: 'cap_exceeded',
+
+  // --- Auto-extract / hook entrypoint validation (Task 23) -----------
+  // These pair with handlers that ALWAYS exit 0 (a crashed hook is
+  // worse than a missing capture). The category surfaces in
+  // sessions/{date}.extract.log so analytics can track failure modes.
+
+  // The caller did not pass `projectRoot`. Programmer error in the
+  // bin wrapper; ships as a guard against misuse.
+  MISSING_PROJECT_ROOT: 'missing_project_root',
+
+  // No CompressorBackend implementation was passed. Same shape as
+  // above — guards a programmer error.
+  MISSING_BACKEND: 'missing_backend',
+
+  // The expected turn buffer file (Task 21 wrote it under
+  // transcripts/.extract-*.tmp) doesn't exist by the time auto-extract
+  // gets scheduled. Could be a race with Task 21's writeFileSync, or
+  // a manual cleanup of stale temp files.
+  MISSING_TURN: 'missing_turn',
+
+  // The CompressorBackend's compress() rejected. For
+  // HaikuViaAnthropicApi this means the `claude --print` subprocess
+  // exited non-zero or the spawn itself failed. HAIKU_TIMEOUT
+  // (below) is the disambiguated case for "took too long" vs.
+  // "exited unhealthy"; analytics treat them differently.
+  HAIKU_FAILED: 'haiku_failed',
+
+  // CompressorBackend.compress() exceeded the caller-supplied
+  // timeoutMs (design §8.5). The subprocess was killed by the
+  // SIGTERM → grace → SIGKILL escalation in terminateSubprocess.
+  // Auto-extract passes timeoutMs=25_000 (under 30s Stop hook
+  // ceiling); compress-session passes 50_000 (under 60s SessionEnd
+  // ceiling). The inner timeout exists so the catch + finally +
+  // log-write all run BEFORE the outer hook ceiling kills the
+  // parent — without it, a hung Haiku call would leak the
+  // auto-extract.lock file and skip the NDJSON log entry.
+  // Distinct from HAIKU_FAILED so analytics can separate "the API
+  // is slow today" from "the API rejected our call".
+  HAIKU_TIMEOUT: 'haiku_timeout',
+
+  // SessionEnd compression (Task 22) — the CompressorBackend's
+  // compress() rejected when called with the §8.4 compression
+  // prompt against sessions/now.md. Disambiguates from
+  // HAIKU_FAILED in extract.log so analytics can separate
+  // extraction failures from compression failures (same root cause
+  // — the `claude` subprocess — but the call sites have different
+  // recovery semantics: extract is best-effort, compression
+  // leaves now.md intact for the next attempt).
+  COMPRESS_FAILED: 'compress_failed',
+
+  // Poison_Guard rejection (Task 24, design §6.7) — the pre-write
+  // regex filter matched a secret/injection pattern. memoryWrite()
+  // returns this category and the matched pattern_id surfaces in
+  // .locks/poison-guard.log (NDJSON, redacted) so audits can track
+  // frequency without exposing the cleartext that triggered the
+  // rejection. Pairs with POISON_GUARD_CATEGORIES from
+  // poison-guard.mjs for routing analytics.
+  POISON_GUARD: 'poison_guard',
+
+  // `cmk search` requested --mode=semantic or --mode=hybrid but the
+  // Layer 5b memsearch+Milvus install isn't present (Task 30, design
+  // §9.3). Pairs with `process.exitCode = 2` in subcommands.mjs per
+  // tasks.md 30.2's explicit "exit 2 when not installed" contract.
+  // NO silent fallback to keyword — the user asked for semantic,
+  // and the surface should fail-loud so they know what's missing.
+  SEMANTIC_UNAVAILABLE: 'semantic_unavailable',
+});
+
+export const ACTION_TYPES = Object.freeze({
+  CREATED: 'created',
+  SKIPPED: 'skipped',
+  TOMBSTONED: 'tombstoned',
+  MERGED: 'merged',
+  ERROR: 'error',
+  CANCELLED: 'cancelled',
+  NOT_FOUND: 'not-found',
+});
+
+const VALID_CATEGORIES = new Set(Object.values(ERROR_CATEGORIES));
+
+export function errorResult({ category, errors, ...rest }) {
+  if (!VALID_CATEGORIES.has(category)) {
+    throw new Error(
+      `errorResult: invalid category ${JSON.stringify(category)}. Must be one of: ${[
+        ...VALID_CATEGORIES,
+      ].join(', ')}`,
+    );
+  }
+  if (!Array.isArray(errors) || errors.length === 0) {
+    throw new Error('errorResult: errors must be a non-empty array');
+  }
+  return {
+    action: 'error',
+    errorCategory: category,
+    errors,
+    ...rest,
+  };
+}
+
+export function notFoundResult({ errors, ...rest }) {
+  if (!Array.isArray(errors) || errors.length === 0) {
+    throw new Error('notFoundResult: errors must be a non-empty array');
+  }
+  return {
+    action: 'not-found',
+    errors,
+    ...rest,
+  };
+}