@lh8ppl/claude-memory-kit 0.1.0

package/src/weekly-curate.mjs

@@ -0,0 +1,454 @@
+// Weekly curate (Task 34, T-029).
+//
+// Companion to Task 33's daily-distill. Once a week (cron-scheduled
+// at Sun 09:00 per §1.4), rotate every today-{YYYY-MM-DD}.md older
+// than 7 days into archive.md, dedupe bullets across days, and
+// rebuild recent.md from the current week's files via dailyDistill.
+//
+// Public boundary:
+//   weeklyCurate({projectRoot, backend, now, cooldownMs?,
+//                 archiveMaxBytes?, recentMaxBytes?, skipRecentRebuild?})
+//     → {action: 'curated' | 'skipped' | 'error', archivedDays?,
+//        currentDays?, archivedPath?, recentPath?, bytesIn?, bytesOut?,
+//        duration_ms, errorCategory?, errors?}
+//
+// Composes on:
+//   - cooldown.mjs — shared 120s Haiku gate (same marker daily-distill /
+//     compress-session / auto-extract touch)
+//   - compressor.mjs — CompressorBackend interface; bin wrapper passes
+//     HaikuViaAnthropicApi
+//   - daily-distill.mjs — inline call to refresh recent.md from current
+//     week (cooldownMs=0 override per §8.7.2 composition)
+//   - canonicalize package — bullet-level dedup (Task 5 primitive that
+//     Task 10's mergeFacts itself uses; we reuse it at the scratchpad
+//     bullet level since today-*.md bullets have no per-bullet ids)
+//   - result-shapes.mjs — errorResult + ERROR_CATEGORIES
+//
+// Per design §8.7 + tasks.md 34.
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { canonicalize } from '@lh8ppl/cmk-canonicalize';
+import { nowIso } from './audit-log.mjs';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+import { HaikuTimeoutError } from './compressor.mjs';
+import {
+  DEFAULT_COOLDOWN_MS,
+  isCooldownActive,
+  touchCooldownMarker,
+} from './cooldown.mjs';
+import { dailyDistill } from './daily-distill.mjs';
+
+const DEFAULT_ARCHIVE_MAX_BYTES = 4096;
+const DEFAULT_RECENT_MAX_BYTES = 4096;
+const SESSIONS_REL = ['context', 'sessions'];
+const ARCHIVE_MD_REL = ['context', 'sessions', 'archive.md'];
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+const TODAY_RE = /^today-(\d{4}-\d{2}-\d{2})\.md$/;
+
+function buildCurateInstructions(archiveMaxBytes) {
+  return [
+    'You are a memory archivist for claude-memory-kit. The input below is a series of daily session summaries (one per day, oldest first) that are now older than 7 days. Consolidate them into a compact archive section.',
+    '',
+    'Output ONLY the consolidated Markdown. Do not write preamble. Do not acknowledge the task. Begin your response with the first heading.',
+    '',
+    'REQUIRED FORMAT:',
+    '',
+    'Group consolidated entries by ISO week start (Monday). Each week begins with:',
+    '',
+    '## Week of YYYY-MM-DD',
+    '',
+    'Under each week heading, emit bullets that summarize the work across the days in that week. Each bullet is a single line ≤120 chars. Bullets within a week appear in chronological order.',
+    '',
+    'HARD RULES:',
+    '  1. Preserve every citation ID matching /#[ULP]-[A-Z0-9]{6,8}/ verbatim. Never invent new IDs.',
+    `  2. Total output ≤ ${archiveMaxBytes} bytes.`,
+    '  3. Deduplicate aggressively: if the same fact appears across multiple days, emit it ONCE. The deterministic dedup pass after your output will collapse exact-after-canonical duplicates; YOUR job is to catch the looser semantic duplicates (paraphrases, restatements).',
+    '  4. No prose between bullets — only the bulleted list per week section.',
+    '  5. Your output goes directly into archive.md. Do not address the user, do not refer to yourself.',
+    '',
+    '=== BEGIN OLD DAILY SUMMARIES TO ARCHIVE ===',
+  ].join('\n');
+}
+
+function listAllTodayFiles(projectRoot) {
+  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
+  if (!existsSync(sessionsDir)) return [];
+  const matches = [];
+  for (const name of readdirSync(sessionsDir)) {
+    const m = TODAY_RE.exec(name);
+    if (!m) continue;
+    matches.push({ name, date: m[1], path: join(sessionsDir, name) });
+  }
+  matches.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+  return matches;
+}
+
+function splitByAge(files, now) {
+  const cutoffMs = new Date(now).getTime() - SEVEN_DAYS_MS;
+  const old = [];
+  const current = [];
+  for (const f of files) {
+    const fileMs = new Date(f.date + 'T00:00:00Z').getTime();
+    if (Number.isFinite(fileMs) && fileMs < cutoffMs) old.push(f);
+    else current.push(f);
+  }
+  return { old, current };
+}
+
+function readBuffer(files) {
+  return files
+    .map((f) => `## ${f.date}\n\n${readFileSync(f.path, 'utf8')}`)
+    .join('\n\n');
+}
+
+// Bullet-level dedup pass. Parses the Haiku output, finds bullets whose
+// canonicalize() output matches across days, collapses duplicates into
+// a single bullet with a `merged_from` HTML-comment line appended.
+//
+// The v0.1.0 contract for "merge high-similarity bullets via task 10"
+// (tasks.md 34.2): Task 10's mergeFacts API operates on per-fact files
+// under <tier>/memory/<id>.md — today-*.md bullets have no per-bullet
+// ids, so direct mergeFacts use is not the right tool. Instead the kit
+// reuses the canonicalize primitive (the same one Task 10 uses to
+// detect merge collisions) at the bullet text level. Looser semantic-
+// similarity dedup remains Haiku's responsibility per the prompt.
+//
+// Input: archive Markdown (sections of `## Week of ...` headers
+// followed by `- bullet` lines) + the list of source-date strings the
+// input came from.
+//
+// Output: same shape, with consecutive same-canonical bullets within a
+// week collapsed and a `<!-- merged_from: ['YYYY-MM-DD', ...] -->`
+// comment line appended after the consolidated bullet.
+//
+// SCOPE CONTRACT (skill-review I1, 2026-05-28): dedup only triggers
+// INSIDE a `## Week of ...` section. Bullets that appear BEFORE the
+// first such heading (e.g., Haiku ignores the prompt format and emits
+// bullets without a week wrapper) pass through verbatim with NO dedup.
+// This is intentional: without a section to scope-attribute the merge,
+// the merged_from comment would lose its provenance meaning. If a
+// future Haiku response shape needs implicit-section dedup, lift this
+// behavior here + add a corresponding test pinning the new shape.
+export function dedupBullets(archiveText, sourceDates) {
+  const lines = archiveText.split('\n');
+  const out = [];
+  const buffer = []; // pending bullets within current week
+  let inWeekSection = false;
+
+  function flushBuffer() {
+    if (buffer.length === 0) return;
+    // Group by canonical form. Preserve first-occurrence order.
+    const byCanonical = new Map();
+    const order = [];
+    for (const b of buffer) {
+      const key = canonicalize(b.text);
+      if (!key) {
+        // Empty after canonical — skip noise lines
+        continue;
+      }
+      if (!byCanonical.has(key)) {
+        byCanonical.set(key, { bullets: [], firstLine: b.line });
+        order.push(key);
+      }
+      byCanonical.get(key).bullets.push(b);
+    }
+    for (const key of order) {
+      const group = byCanonical.get(key);
+      const first = group.bullets[0];
+      out.push(first.line);
+      if (group.bullets.length > 1) {
+        // Collapsed multiple bullets into one. Record merged_from
+        // with the source dates the bullets came from. If the input
+        // bullet didn't carry a date attribution (rare — Haiku
+        // groups by week and our prompt tells it to dedup looser
+        // duplicates), fall back to "all source dates within this
+        // week section". v0.1.0 uses the simpler: every merged
+        // group attributes to the full set of sourceDates the
+        // weekly-curate call was given. This is conservative but
+        // correct — the audit trail says "these source days
+        // contributed to this consolidated bullet" without
+        // requiring per-bullet date tags Haiku may not emit.
+        const dates = sourceDates.slice().sort();
+        out.push(`<!-- merged_from: [${dates.map((d) => `'${d}'`).join(', ')}] -->`);
+      }
+    }
+    buffer.length = 0;
+  }
+
+  for (const line of lines) {
+    if (/^## Week of /.test(line)) {
+      flushBuffer();
+      out.push(line);
+      inWeekSection = true;
+      continue;
+    }
+    // S5 fix: any other `## ` heading (e.g., `## Decisions` if Haiku
+    // ignores the prompt format) ends the current week section. Without
+    // this reset, bullets under the non-week heading would still buffer
+    // into the prior week's dedup group — wrong attribution.
+    if (/^## /.test(line)) {
+      flushBuffer();
+      out.push(line);
+      inWeekSection = false;
+      continue;
+    }
+    if (inWeekSection && /^-\s/.test(line)) {
+      const text = line.replace(/^-\s+/, '');
+      buffer.push({ line, text });
+      continue;
+    }
+    if (inWeekSection && /^<!--/.test(line)) {
+      // Comment lines from Haiku — pass through, don't buffer
+      flushBuffer();
+      out.push(line);
+      continue;
+    }
+    // Section break or unrecognized line — flush + emit
+    flushBuffer();
+    out.push(line);
+  }
+  flushBuffer();
+  return out.join('\n');
+}
+
+function archiveMdPath(projectRoot) {
+  return join(projectRoot, ...ARCHIVE_MD_REL);
+}
+
+function curateLogPath(projectRoot, date) {
+  return join(projectRoot, ...SESSIONS_REL, `${date}.curate.log`);
+}
+
+function writeCurateLogEntry({ projectRoot, date, entry }) {
+  const path = curateLogPath(projectRoot, date);
+  mkdirSync(join(projectRoot, ...SESSIONS_REL), { recursive: true });
+  appendFileSync(path, JSON.stringify(entry) + '\n', 'utf8');
+  return path;
+}
+
+/**
+ * Run the weekly curate cycle.
+ *
+ * @returns {Promise<object>} action: 'curated' | 'skipped' | 'error'
+ */
+export async function weeklyCurate({
+  projectRoot,
+  backend,
+  now,
+  cooldownMs = DEFAULT_COOLDOWN_MS,
+  archiveMaxBytes = DEFAULT_ARCHIVE_MAX_BYTES,
+  recentMaxBytes = DEFAULT_RECENT_MAX_BYTES,
+  skipRecentRebuild = false,
+} = {}) {
+  const ts = now ?? nowIso();
+  const date = ts.slice(0, 10);
+  const t0 = Date.now();
+
+  if (!projectRoot) {
+    return errorResult({
+      category: ERROR_CATEGORIES.MISSING_PROJECT_ROOT,
+      errors: ['projectRoot is required'],
+      duration_ms: Date.now() - t0,
+    });
+  }
+  if (!backend || typeof backend.compress !== 'function') {
+    return errorResult({
+      category: ERROR_CATEGORIES.MISSING_BACKEND,
+      errors: ['backend (CompressorBackend) is required'],
+      duration_ms: Date.now() - t0,
+    });
+  }
+
+  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
+  if (!existsSync(sessionsDir)) {
+    return {
+      action: 'skipped',
+      reason: 'no-context-dir',
+      duration_ms: Date.now() - t0,
+    };
+  }
+
+  if (isCooldownActive({ projectRoot, now: ts, cooldownMs })) {
+    const duration_ms = Date.now() - t0;
+    writeCurateLogEntry({
+      projectRoot,
+      date,
+      entry: {
+        ts,
+        scope: 'weekly-curate',
+        input_bytes: 0,
+        output_bytes: 0,
+        // I2 fix: null model_id on the cooldown-skip path. Haiku was
+        // never called — recording the backend's modelId would
+        // mis-attribute the (non-existent) call in NDJSON analytics.
+        model_id: null,
+        cost_usd: 0,
+        duration_ms,
+        success: true,
+        skipped_reason: 'cooldown',
+      },
+    });
+    return { action: 'skipped', reason: 'cooldown', duration_ms };
+  }
+
+  const files = listAllTodayFiles(projectRoot);
+  const { old, current } = splitByAge(files, ts);
+
+  // No old files → nothing to archive; we still rebuild recent.md
+  // from current (idempotent no-op if it was just rebuilt by daily
+  // cron, since dailyDistill writes the same output deterministically).
+  if (old.length === 0) {
+    const duration_ms = Date.now() - t0;
+    writeCurateLogEntry({
+      projectRoot,
+      date,
+      entry: {
+        ts,
+        scope: 'weekly-curate',
+        input_bytes: 0,
+        output_bytes: 0,
+        model_id:
+          typeof backend.modelId === 'function' ? backend.modelId() : null,
+        cost_usd: 0,
+        duration_ms,
+        success: true,
+        skipped_reason: 'no-old-files',
+        current_days: current.length,
+      },
+    });
+    return {
+      action: 'skipped',
+      reason: 'no-old-files',
+      currentDays: current.length,
+      duration_ms,
+    };
+  }
+
+  const buffer = readBuffer(old);
+  const input_bytes = Buffer.byteLength(buffer, 'utf8');
+  const instructions = buildCurateInstructions(archiveMaxBytes);
+  const sourceDates = old.map((f) => f.date);
+
+  let result;
+  try {
+    result = await backend.compress({
+      input: buffer,
+      instructions,
+      preserveCitationIds: true,
+      maxOutputBytes: archiveMaxBytes,
+      timeoutMs: 50_000,
+    });
+    touchCooldownMarker({ projectRoot, now: ts });
+  } catch (err) {
+    touchCooldownMarker({ projectRoot, now: ts });
+    const errorCategory =
+      err instanceof HaikuTimeoutError
+        ? ERROR_CATEGORIES.HAIKU_TIMEOUT
+        : ERROR_CATEGORIES.COMPRESS_FAILED;
+    const duration_ms = Date.now() - t0;
+    writeCurateLogEntry({
+      projectRoot,
+      date,
+      entry: {
+        ts,
+        scope: 'weekly-curate',
+        input_bytes,
+        output_bytes: 0,
+        model_id:
+          typeof backend.modelId === 'function' ? backend.modelId() : null,
+        cost_usd: 0,
+        duration_ms,
+        success: false,
+        error_category: errorCategory,
+      },
+    });
+    return errorResult({
+      category: errorCategory,
+      errors: [err?.message ?? String(err)],
+      duration_ms,
+    });
+  }
+
+  const rawOutput = result?.outputText ?? '';
+  const dedupedOutput = dedupBullets(rawOutput, sourceDates);
+  const output_bytes = Buffer.byteLength(dedupedOutput, 'utf8');
+
+  // Append to archive.md (NOT overwrite — archive is append-only history).
+  const archivePath = archiveMdPath(projectRoot);
+  mkdirSync(join(projectRoot, ...SESSIONS_REL), { recursive: true });
+  const suffix = dedupedOutput.endsWith('\n') ? '' : '\n';
+  appendFileSync(archivePath, dedupedOutput + suffix + '\n', 'utf8');
+
+  // Delete OLD today-*.md files (audit retention via git history;
+  // committed tier per .gitignore.fragment).
+  // M3 fix: track per-file deletion errors in the NDJSON entry so ops
+  // can detect partial-deletion events (Windows file lock, race
+  // condition). Self-healing — next week's curate re-archives any
+  // surviving OLD file — but observability matters.
+  const deletionErrors = [];
+  for (const f of old) {
+    try {
+      unlinkSync(f.path);
+    } catch (err) {
+      deletionErrors.push({ path: f.path, error: err?.message ?? String(err) });
+    }
+  }
+
+  // Rebuild recent.md from current week via dailyDistill (cooldownMs=0
+  // override per §8.7.2 — both Haiku calls belong to a single curate
+  // cycle, not two independent invocations).
+  let recentPath;
+  let recentResult;
+  if (!skipRecentRebuild && current.length > 0) {
+    recentResult = await dailyDistill({
+      projectRoot,
+      backend,
+      now: ts,
+      cooldownMs: 0,
+      maxOutputBytes: recentMaxBytes,
+    });
+    if (recentResult?.outputPath) recentPath = recentResult.outputPath;
+  }
+
+  const duration_ms = Date.now() - t0;
+  writeCurateLogEntry({
+    projectRoot,
+    date,
+    entry: {
+      ts,
+      scope: 'weekly-curate',
+      input_bytes,
+      output_bytes,
+      model_id:
+        result?.modelId ??
+        (typeof backend.modelId === 'function' ? backend.modelId() : null),
+      cost_usd: result?.costUSD ?? 0,
+      duration_ms,
+      success: true,
+      archived_days: old.length,
+      current_days: current.length,
+      recent_rebuild_action: recentResult?.action ?? 'skipped',
+      ...(deletionErrors.length > 0 ? { deletion_errors: deletionErrors } : {}),
+    },
+  });
+
+  return {
+    action: 'curated',
+    archivedDays: old.length,
+    currentDays: current.length,
+    archivedPath: archivePath,
+    recentPath,
+    bytesIn: input_bytes,
+    bytesOut: output_bytes,
+    duration_ms,
+  };
+}

package/src/write-fact.mjs

@@ -0,0 +1,205 @@
+// Per-fact archive writer (Task 7, refactored in cleanup-layer-2-cross-module-drift).
+// Single public boundary: writeFact(opts) → result. See design §2.2 + §4.
+//
+// Uses shared modules: tier-paths (path resolution), frontmatter (js-yaml
+// serialize), audit-log (canonical NDJSON), result-shapes (errorCategory enum).
+// See CLAUDE.md "Shared modules" rule.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { generateId } from '@lh8ppl/cmk-canonicalize';
+import { VALID_TIERS, resolveTierRoot, resolveFactDir } from './tier-paths.mjs';
+import { parse, format } from './frontmatter.mjs';
+import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+
+const VALID_TYPES = new Set(['user', 'feedback', 'project', 'reference']);
+const VALID_WRITE_SOURCES = new Set([
+  'user-explicit',
+  'auto-extract',
+  'compressor',
+  'manual-edit',
+  'imported',
+]);
+const VALID_TRUST = new Set(['high', 'medium', 'low']);
+const SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]*$/i;
+
+// Layer-2 review: PR-1 rejected \n / \r / : in scalar frontmatter fields as
+// a minimum fix for the naive serializer (finding B2). PR-2's frontmatter.mjs
+// (js-yaml CORE_SCHEMA) quotes those chars properly. The B2 restriction is
+// LIFTED here — titles/sourceFile/sourceSha1 may contain newlines, colons,
+// and other YAML-special chars; they round-trip correctly via parse/format.
+// Round-trip tests in cli-write-fact.test.js (`B2 relaxation`) prove it.
+
+function validateOptions(opts) {
+  const errors = [];
+  if (!opts.tier || !VALID_TIERS.has(opts.tier)) {
+    errors.push("tier: must be 'U', 'P', or 'L'");
+  }
+  if (!opts.type || !VALID_TYPES.has(opts.type)) {
+    errors.push('type: must be one of user/feedback/project/reference');
+  }
+  if (
+    !opts.slug ||
+    typeof opts.slug !== 'string' ||
+    !SLUG_PATTERN.test(opts.slug)
+  ) {
+    errors.push(
+      'slug: must start with alphanumeric and contain only [A-Za-z0-9_-]',
+    );
+  }
+  if (!opts.title || typeof opts.title !== 'string' || !opts.title.trim()) {
+    errors.push('title: required, non-empty string');
+  }
+  if (opts.body == null || typeof opts.body !== 'string' || !opts.body.length) {
+    errors.push('body: required, non-empty string');
+  }
+  if (!opts.writeSource || !VALID_WRITE_SOURCES.has(opts.writeSource)) {
+    errors.push(
+      'writeSource: must be one of user-explicit/auto-extract/compressor/manual-edit/imported',
+    );
+  }
+  if (!opts.trust || !VALID_TRUST.has(opts.trust)) {
+    errors.push('trust: must be one of high/medium/low');
+  }
+  if (
+    !opts.sourceFile ||
+    typeof opts.sourceFile !== 'string' ||
+    !opts.sourceFile.length
+  ) {
+    errors.push('sourceFile: required, non-empty string');
+  }
+  if (
+    typeof opts.sourceLine !== 'number' ||
+    !Number.isInteger(opts.sourceLine) ||
+    opts.sourceLine < 1
+  ) {
+    errors.push('sourceLine: required, positive integer');
+  }
+  if (
+    !opts.sourceSha1 ||
+    typeof opts.sourceSha1 !== 'string' ||
+    !opts.sourceSha1.length
+  ) {
+    errors.push('sourceSha1: required, non-empty string');
+  }
+  return errors;
+}
+
+function buildFrontmatterObject(opts, computed) {
+  // Key order matters for visual diff stability — insertion order = on-disk order.
+  const fm = {
+    id: computed.id,
+    type: opts.type,
+    title: opts.title,
+    created_at: computed.createdAt,
+    write_source: opts.writeSource,
+    trust: opts.trust,
+    source_file: opts.sourceFile,
+    source_line: opts.sourceLine,
+    source_sha1: opts.sourceSha1,
+  };
+  if (opts.mergedFrom) fm.merged_from = opts.mergedFrom;
+  if (opts.supersededBy) fm.superseded_by = opts.supersededBy;
+  if (opts.tags) fm.tags = opts.tags;
+  if (opts.related) fm.related = opts.related;
+  if (opts.isPrivate === true) fm.private = true;
+  return fm;
+}
+
+// Per Layer-2 review M2: filter INDEX.md from the dedup scan. Pre-fix the
+// inline scanner here didn't exclude INDEX.md; harmless in practice (it
+// has no `id:` matching real ids) but inconsistent with reindex/forget.
+function findExistingFactById(factDir, id) {
+  if (!existsSync(factDir)) return null;
+  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'INDEX.md') continue;
+    const p = join(factDir, entry.name);
+    if (!statSync(p).isFile()) continue;
+    const { frontmatter } = parse(readFileSync(p, 'utf8'));
+    if (frontmatter?.id === id) return p;
+  }
+  return null;
+}
+
+function readExistingFactId(path) {
+  if (!existsSync(path)) return null;
+  const { frontmatter } = parse(readFileSync(path, 'utf8'));
+  return frontmatter?.id ?? null;
+}
+
+export function writeFact(opts = {}) {
+  const errors = validateOptions(opts);
+  if (errors.length > 0) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors,
+      id: null,
+      path: null,
+    });
+  }
+
+  const id = opts.id ?? generateId(opts.tier, opts.body);
+  const createdAt = opts.createdAt ?? nowIso();
+  const tierRoot = resolveTierRoot(opts);
+  const factDir = resolveFactDir(opts.tier, tierRoot);
+  const filename = `${opts.type}_${opts.slug}.md`;
+  const path = join(factDir, filename);
+
+  const existingIdAtPath = readExistingFactId(path);
+  if (existingIdAtPath !== null) {
+    if (existingIdAtPath === id) {
+      appendAuditEntry(tierRoot, {
+        ts: createdAt,
+        action: 'skipped',
+        tier: opts.tier,
+        id,
+        reasonCode: REASON_CODES.DUPLICATE,
+        paths: { before: path },
+      });
+      return { action: 'skipped', skipReason: 'duplicate', id, path };
+    }
+    return errorResult({
+      category: ERROR_CATEGORIES.COLLISION,
+      errors: [
+        `File exists at ${path} with different id ${existingIdAtPath}; refusing overwrite`,
+      ],
+      id,
+      path,
+    });
+  }
+
+  const elsewhere = findExistingFactById(factDir, id);
+  if (elsewhere) {
+    appendAuditEntry(tierRoot, {
+      ts: createdAt,
+      action: 'skipped',
+      tier: opts.tier,
+      id,
+      reasonCode: REASON_CODES.DUPLICATE_ELSEWHERE,
+      paths: { before: elsewhere, after: path },
+    });
+    return {
+      action: 'skipped',
+      skipReason: 'duplicate-elsewhere',
+      id,
+      path,
+      duplicateAt: elsewhere,
+    };
+  }
+
+  mkdirSync(factDir, { recursive: true });
+  const frontmatter = buildFrontmatterObject(opts, { id, createdAt });
+  writeFileSync(path, format({ frontmatter, body: `\n${opts.body}\n` }), 'utf8');
+
+  return { action: 'created', id, path };
+}