@avee1234/memport 0.1.0

package/src/adapters/claude-code.js

@@ -0,0 +1,317 @@
+// Claude Code memory adapter — the first *real* store adapter (#14).
+//
+// A Claude Code memory store is a **directory**, not a single file: one
+// `<slug>.md` per fact, each with YAML-ish frontmatter (`name`, `description`,
+// `metadata.type`) plus a Markdown body, alongside a derived `MEMORY.md` index.
+// Because the store's unit is one file = one fact, the mapping is **one file ↔
+// one record** and `type ↔ kind` is a 4↔4 bijection, so the translation is
+// reversible for every field the CC format can hold.
+//
+// Export reads each memory file into a neutral record (skipping the derived
+// `MEMORY.md`); import writes records back as files and regenerates `MEMORY.md`.
+// Fields the CC format cannot store (`created`, `salience`, `source`,
+// `embedding`) are reported in `map`'s `unsupported` list rather than silently
+// dropped. Frontmatter is read by a small hand-written parser for the known CC
+// subset — not a general YAML engine — so the adapter stays zero-dependency.
+
+import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ExportError } from '../export.js';
+import { ImportError } from '../import.js';
+
+// The one CC-storable file (an index, not a memory) — never a record.
+const INDEX_FILE = 'MEMORY.md';
+
+// Fixed bijection between Claude Code `metadata.type` and memport `kind`.
+const TYPE_TO_KIND = { user: 'fact', feedback: 'preference', project: 'event', reference: 'entity' };
+const KIND_TO_TYPE = { fact: 'user', preference: 'feedback', event: 'project', entity: 'reference' };
+
+// Fields the neutral format carries but the CC file format has no slot for.
+// Reported (never silently dropped) via `map`, in this fixed order.
+const UNSUPPORTED_FIELDS = ['created', 'salience', 'source', 'embedding'];
+
+// --- frontmatter (hand-written, zero-dep) ------------------------------------
+
+// Parse the leading `---`…`---` block plus the Markdown body. Handles the known
+// CC subset: flat `key: value` lines and the one nested block `metadata:` /
+// `  type: <value>`. Only the *first* `---…---` at the top is consumed, so a
+// `---` horizontal rule inside the body is left as body text.
+function parseFrontmatter(text, file) {
+  const lines = text.split('\n');
+  if (lines[0].trim() !== '---') {
+    throw new ExportError('invalid_memory_file', `missing frontmatter opening --- in ${file}`, { file });
+  }
+  let close = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      close = i;
+      break;
+    }
+  }
+  if (close === -1) {
+    throw new ExportError('invalid_memory_file', `missing frontmatter closing --- in ${file}`, { file });
+  }
+
+  const fm = {};
+  let inMetadata = false;
+  for (const line of lines.slice(1, close)) {
+    if (line.trim() === '') continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue; // ignore lines outside the known subset
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim();
+    const indented = /^\s/.test(line);
+    if (indented) {
+      if (inMetadata) fm.metadata[key] = value;
+      continue;
+    }
+    if (key === 'metadata') {
+      fm.metadata = {};
+      inMetadata = true;
+      continue;
+    }
+    inMetadata = false;
+    fm[key] = value;
+  }
+
+  const body = lines.slice(close + 1).join('\n').trim();
+  return { fm, body };
+}
+
+// Parse one memory file into a partial record (links resolved in a second pass).
+function parseMemoryFile(file) {
+  const { fm, body } = parseFrontmatter(readFileSync(file, 'utf8'), file);
+
+  if (!fm.name) {
+    throw new ExportError('invalid_memory_file', `missing frontmatter 'name' in ${file}`, { file });
+  }
+  const type = fm.metadata && fm.metadata.type;
+  if (!type) {
+    throw new ExportError('invalid_memory_file', `missing frontmatter 'metadata.type' in ${file}`, { file });
+  }
+  const kind = TYPE_TO_KIND[type];
+  if (!kind) {
+    throw new ExportError(
+      'invalid_memory_file',
+      `unknown metadata.type '${type}' in ${file} (known: ${Object.keys(TYPE_TO_KIND).join(', ')})`,
+      { file },
+    );
+  }
+  if (body.length === 0) {
+    throw new ExportError('invalid_memory_file', `empty body in ${file}`, { file });
+  }
+
+  const stat = statSync(file);
+  const created = new Date(stat.birthtimeMs || stat.mtimeMs).toISOString();
+
+  const record = { id: fm.name, content: body, kind, created, source: 'claude-code' };
+  if (fm.description) record.description = fm.description;
+  return record;
+}
+
+// The `[[slug]]` wiki-links found in a body, in order of first appearance,
+// deduped.
+function wikiLinks(body) {
+  const found = [];
+  const seen = new Set();
+  const re = /\[\[([^\]]+)\]\]/g;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const slug = m[1].trim();
+    if (!seen.has(slug)) {
+      seen.add(slug);
+      found.push(slug);
+    }
+  }
+  return found;
+}
+
+// Lift each record's resolved wiki-links into `links[]`: a `[[slug]]` counts
+// only when `slug` names *another* exported record. Unresolved links stay body
+// text, so the exported set never carries a `dangling_link`.
+function resolveLinks(records) {
+  const ids = new Set(records.map((r) => r.id));
+  for (const r of records) {
+    const links = wikiLinks(r.content).filter((slug) => slug !== r.id && ids.has(slug));
+    if (links.length > 0) r.links = links;
+  }
+  return records;
+}
+
+// Read every memory file in `dir` into resolved records, name-sorted for
+// determinism. Throws ExportError on a malformed file or a missing directory.
+function readMemoryDir(dir) {
+  let stat;
+  try {
+    stat = statSync(dir);
+  } catch {
+    throw new ExportError('source_not_found', `source not found: ${dir}`, { file: dir });
+  }
+  if (!stat.isDirectory()) {
+    throw new ExportError(
+      'source_not_a_directory',
+      `source is not a directory: ${dir} (a Claude Code memory store is a directory of .md files)`,
+      { file: dir },
+    );
+  }
+
+  const files = readdirSync(dir)
+    .filter((name) => name.endsWith('.md') && name !== INDEX_FILE)
+    .sort((a, b) => a.localeCompare(b))
+    .map((name) => join(dir, name));
+
+  return resolveLinks(files.map(parseMemoryFile));
+}
+
+// --- serialization (record → CC file) ----------------------------------------
+
+// The frontmatter `description` / index hook for a record: its preserved
+// `description` field, else the first non-empty line of `content` truncated.
+function deriveHook(record) {
+  if (typeof record.description === 'string' && record.description.trim()) {
+    return record.description.trim();
+  }
+  const firstLine = (record.content || '').split('\n').find((l) => l.trim()) || '';
+  const trimmed = firstLine.trim();
+  return trimmed.length > 100 ? `${trimmed.slice(0, 100).trimEnd()}…` : trimmed;
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// The body to write: `content`, plus a trailing `Related: [[a]] [[b]]` line for
+// any `links[]` id not already present as an inline `[[id]]` (idempotent for
+// CC-origin sets, whose links are already inline).
+function bodyWithLinks(record) {
+  const content = record.content;
+  const links = Array.isArray(record.links) ? record.links : [];
+  const missing = links.filter((id) => !new RegExp(`\\[\\[${escapeRegExp(id)}\\]\\]`).test(content));
+  if (missing.length === 0) return content;
+  return `${content}\n\nRelated: ${missing.map((id) => `[[${id}]]`).join(' ')}`;
+}
+
+// Serialize one record as a `<id>.md` file body (2-space frontmatter, one
+// trailing newline). `created`/`salience`/`source`/`embedding` have no slot.
+function serializeMemoryFile(record) {
+  const type = KIND_TO_TYPE[record.kind];
+  return (
+    `---\n` +
+    `name: ${record.id}\n` +
+    `description: ${deriveHook(record)}\n` +
+    `metadata:\n` +
+    `  type: ${type}\n` +
+    `---\n\n` +
+    `${bodyWithLinks(record)}\n`
+  );
+}
+
+// The title-cased slug used as an index link label (`user-role` → `User Role`).
+function titleCase(id) {
+  return id
+    .split('-')
+    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}
+
+// Regenerate `MEMORY.md`: a header plus one `- [Title](id.md) — hook` line per
+// record, in the given record order.
+function renderIndex(records) {
+  const lines = ['# Memory index', ''];
+  for (const r of records) {
+    lines.push(`- [${titleCase(r.id)}](${r.id}.md) — ${deriveHook(r)}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export const claudeCodeAdapter = {
+  name: 'claude-code',
+
+  /**
+   * @param {string} source - a Claude Code memory directory of `<slug>.md` files
+   * @returns {{ records: Array<object> }} one record per memory file (MEMORY.md excluded)
+   * @throws {ExportError} on a missing/non-directory source or a malformed file
+   */
+  read(source) {
+    return { records: readMemoryDir(source) };
+  },
+
+  // --- import side ----------------------------------------------------------
+
+  /**
+   * Split each record into what a CC file can hold vs. what it cannot. Every
+   * record is `supported` (written with its storable fields); `unsupported`
+   * names the CC-unstorable fields (`created`/`salience`/`source`/`embedding`)
+   * present on each record so import can report, not silently drop, them.
+   * @param {Array<object>} set
+   * @returns {{ supported: Array<object>, unsupported: Array<{id: string, fields: string[]}> }}
+   */
+  map(set) {
+    const unsupported = [];
+    for (const record of set) {
+      const fields = UNSUPPORTED_FIELDS.filter((f) => f in record);
+      if (fields.length > 0) unsupported.push({ id: record.id, fields });
+    }
+    return { supported: set, unsupported };
+  },
+
+  /**
+   * Read the existing records at an import target directory so `import.js` can
+   * merge by id. A missing directory is normal (a fresh write) → `[]`; a
+   * malformed existing file surfaces as an ImportError.
+   * @param {string} target - a Claude Code memory directory
+   * @returns {Array<object>} existing records ([] if the directory is absent)
+   */
+  readExisting(target) {
+    try {
+      statSync(target);
+    } catch {
+      return []; // absent target — a fresh write, not an error
+    }
+    try {
+      return readMemoryDir(target);
+    } catch (e) {
+      if (e instanceof ExportError) {
+        throw new ImportError(e.code, e.message, { file: e.file });
+      }
+      throw e;
+    }
+  },
+
+  /**
+   * Write the final record list as `<id>.md` files plus a regenerated
+   * `MEMORY.md`. Existing `*.md` files whose id is not in the incoming list are
+   * pruned so the directory reflects the set (this happens on `replace`, whose
+   * list is the incoming set alone; `merge`'s list includes the existing
+   * records, so nothing is pruned).
+   * @param {string} target - a Claude Code memory directory
+   * @param {Array<object>} records - the final record list from `import.js`
+   * @throws {ImportError} if the directory cannot be created or written
+   */
+  write(target, records) {
+    try {
+      mkdirSync(target, { recursive: true });
+    } catch (e) {
+      throw new ImportError('write_failed', `cannot create target directory ${target}: ${e.message}`, {
+        file: target,
+      });
+    }
+
+    try {
+      const keep = new Set(records.map((r) => `${r.id}.md`));
+      for (const name of readdirSync(target)) {
+        if (name.endsWith('.md') && name !== INDEX_FILE && !keep.has(name)) {
+          unlinkSync(join(target, name));
+        }
+      }
+      for (const record of records) {
+        writeFileSync(join(target, `${record.id}.md`), serializeMemoryFile(record));
+      }
+      writeFileSync(join(target, INDEX_FILE), renderIndex(records));
+    } catch (e) {
+      throw new ImportError('write_failed', `cannot write target ${target}: ${e.message}`, {
+        file: target,
+      });
+    }
+  },
+};

package/src/adapters/folder.js

@@ -0,0 +1,170 @@
+// Folder adapter — the always-works case for both export (#2) and import (#3).
+//
+// Export side: reads a single `.json` file or every `.json` file in a directory
+// and yields the raw record objects it finds, in a stable order (files
+// name-sorted, record order within a file preserved). It is an *identity-ish*
+// export: the folder is expected to already hold memport-shaped records, so
+// records pass through unchanged — no field fabrication, no stripping. Anything
+// malformed is a loud ExportError; whether the records are actually valid is
+// decided downstream by validateMemorySet in the pipeline.
+//
+// Import side: the folder store is a single bare-array `.memport` file. It is
+// full-fidelity, so `map` is a pure pass-through (`unsupported` always `[]`),
+// `readExisting` returns the current records (or `[]` if the file is absent —
+// writing to a fresh target is normal), and `write` emits the same 2-space,
+// trailing-newline JSON as export, so the round-trip is byte-stable.
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ExportError } from '../export.js';
+import { ImportError } from '../import.js';
+
+// Resolve `source` to the list of `.json` files to read, name-sorted for
+// determinism. A directory contributes its top-level `*.json` entries (no
+// recursion); a single file is used as-is.
+function listFiles(source) {
+  let stat;
+  try {
+    stat = statSync(source);
+  } catch {
+    throw new ExportError('source_not_found', `source not found: ${source}`, {
+      file: source,
+    });
+  }
+
+  if (stat.isDirectory()) {
+    return readdirSync(source)
+      .filter((name) => name.endsWith('.json'))
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => join(source, name));
+  }
+
+  return [source];
+}
+
+export const folderAdapter = {
+  name: 'folder',
+  /**
+   * @param {string} source - a directory of `.json` files or a single `.json` file
+   * @returns {{ records: Array<object> }} raw records in stable order
+   */
+  read(source) {
+    const files = listFiles(source);
+    const records = [];
+
+    for (const file of files) {
+      let parsed;
+      try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+      } catch (e) {
+        throw new ExportError('invalid_json', `invalid JSON in ${file}: ${e.message}`, {
+          file,
+        });
+      }
+
+      if (Array.isArray(parsed)) {
+        records.push(...parsed);
+      } else if (parsed !== null && typeof parsed === 'object') {
+        records.push(parsed);
+      } else {
+        // A JSON scalar (number, string, boolean, null) is neither a record nor
+        // a batch of records.
+        throw new ExportError(
+          'invalid_json',
+          `${file} must contain a record object or an array of records`,
+          { file },
+        );
+      }
+    }
+
+    return { records };
+  },
+
+  // --- import side ----------------------------------------------------------
+
+  /**
+   * Map a set to what the folder target can hold. The folder store is
+   * full-fidelity, so this is a pure pass-through: everything is supported,
+   * nothing is dropped. Lossy real adapters (#5/#6) populate `unsupported`.
+   * @param {Array<object>} set
+   * @returns {{ supported: Array<object>, unsupported: Array<{id: string, fields: string[]}> }}
+   */
+  map(set) {
+    return { supported: set, unsupported: [] };
+  },
+
+  /**
+   * Read the *existing* records at an import target. Unlike `read` (export's
+   * strict source read), a missing target is normal — writing to a fresh file
+   * is the common case — so it yields `[]` rather than throwing.
+   * @param {string} target - a single `.json` / `.memport` file
+   * @returns {Array<object>} existing records ([] if the target does not exist)
+   * @throws {ImportError} if the target is a directory or holds non-array JSON
+   */
+  readExisting(target) {
+    let stat;
+    try {
+      stat = statSync(target);
+    } catch {
+      return []; // absent target — a fresh write, not an error
+    }
+
+    if (stat.isDirectory()) {
+      throw new ImportError(
+        'target_is_directory',
+        `target is a directory: ${target} (folder import writes a single file)`,
+        { file: target },
+      );
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(target, 'utf8'));
+    } catch (e) {
+      throw new ImportError('invalid_json', `invalid JSON in target ${target}: ${e.message}`, {
+        file: target,
+      });
+    }
+
+    if (!Array.isArray(parsed)) {
+      throw new ImportError(
+        'invalid_json',
+        `target ${target} must contain a memory set (a JSON array of records)`,
+        { file: target },
+      );
+    }
+
+    return parsed;
+  },
+
+  /**
+   * Write the final record list to the target file as a bare JSON array with
+   * 2-space indent + a trailing newline — byte-identical to export's output.
+   * @param {string} target - a single `.json` / `.memport` file path
+   * @param {Array<object>} records
+   * @throws {ImportError} if the target is a directory or cannot be written
+   */
+  write(target, records) {
+    let stat;
+    try {
+      stat = statSync(target);
+    } catch {
+      stat = undefined;
+    }
+    if (stat && stat.isDirectory()) {
+      throw new ImportError(
+        'target_is_directory',
+        `target is a directory: ${target} (folder import writes a single file)`,
+        { file: target },
+      );
+    }
+
+    try {
+      writeFileSync(target, `${JSON.stringify(records, null, 2)}\n`);
+    } catch (e) {
+      throw new ImportError('write_failed', `cannot write target ${target}: ${e.message}`, {
+        file: target,
+      });
+    }
+  },
+};

package/src/adapters/index.js

@@ -0,0 +1,55 @@
+// Export-adapter registry (#2).
+//
+// The seam that lets Mem0 (#5) / Claude Code (#6) slot in by adding one file and
+// one entry here — the pipeline and CLI stay adapter-agnostic. v1 ships only the
+// folder adapter.
+
+import { ExportError } from '../export.js';
+import { ImportError } from '../import.js';
+import { folderAdapter } from './folder.js';
+import { claudeCodeAdapter } from './claude-code.js';
+
+export const EXPORT_ADAPTERS = {
+  folder: folderAdapter,
+  'claude-code': claudeCodeAdapter,
+};
+
+// A separate registry for import: export adapters are read-only by contract,
+// while import needs read+write. The same `folderAdapter` object satisfies both
+// (it gained `map`/`readExisting`/`write`), but keeping the registries distinct
+// keeps the read-only vs read-write contracts explicit and lets a future store
+// support one direction only.
+export const IMPORT_ADAPTERS = {
+  folder: folderAdapter,
+  'claude-code': claudeCodeAdapter,
+};
+
+/**
+ * Look up an export adapter by name.
+ * @param {string} name
+ * @returns {{ name: string, read: Function }}
+ * @throws {ExportError} with code `unknown_adapter` if the name is unregistered
+ */
+export function getAdapter(name) {
+  const adapter = EXPORT_ADAPTERS[name];
+  if (!adapter) {
+    const known = Object.keys(EXPORT_ADAPTERS).join(', ');
+    throw new ExportError('unknown_adapter', `unknown adapter: ${name} (known: ${known})`);
+  }
+  return adapter;
+}
+
+/**
+ * Look up an import adapter by name.
+ * @param {string} name
+ * @returns {{ name: string, map: Function, readExisting: Function, write: Function }}
+ * @throws {ImportError} with code `unknown_adapter` if the name is unregistered
+ */
+export function getImportAdapter(name) {
+  const adapter = IMPORT_ADAPTERS[name];
+  if (!adapter) {
+    const known = Object.keys(IMPORT_ADAPTERS).join(', ');
+    throw new ImportError('unknown_adapter', `unknown adapter: ${name} (known: ${known})`);
+  }
+  return adapter;
+}

package/src/conformance.js

@@ -0,0 +1,140 @@
+// memport conformance — score how much memory survives a round-trip (#4).
+//
+// The headline metric: given two memport sets — the memory *before* a
+// round-trip or migration and the memory *after* — score how much survived and
+// name exactly what was lost or degraded. Pure and read-only: no adapters, no
+// stores, no writes. Inputs are already memport sets (e.g. two `exportMemory`
+// outputs), so the pipeline is just:
+//   1. validate *both* sets with `validateMemorySet` — matching depends on
+//      reliable, unique ids, so garbage is rejected before scoring,
+//   2. resolve the identity strategy (`opts.identity`, default `'id'`) and
+//      index `after` by id,
+//   3. walk `before` in order: an id absent from `after` is `lost`; an id
+//      present is `preserved` (every field identical) or `degraded` (≥1 field
+//      dropped/changed/added, itemized),
+//   4. return `{ score, total, preserved, lost, degraded }` where
+//      `score = preserved / total` (rounded to 4 decimals; `total === 0 → 1`).
+
+import { validateMemorySet } from './validate.js';
+
+// The supported identity matchers (the seam). v1 lists only exact-`id` match;
+// content-hash / fuzzy are roadmap follow-ups that slot in here.
+export const CONFORMANCE_IDENTITIES = ['id'];
+
+/**
+ * Error thrown by the conformance scorer. Mirrors `ExportError` / `ImportError`
+ * so the CLI renders all three uniformly: `.code` names the failure for
+ * exit-code mapping, `.errors` carries the #1 structured errors on an invalid
+ * input, `.side` names which set (`'before'` | `'after'`) was invalid, and
+ * `.file` names the offending file (set by the CLI for messaging).
+ */
+export class ConformanceError extends Error {
+  constructor(code, message, { errors, side, file } = {}) {
+    super(message);
+    this.name = 'ConformanceError';
+    this.code = code;
+    if (errors !== undefined) this.errors = errors;
+    if (side !== undefined) this.side = side;
+    if (file !== undefined) this.file = file;
+  }
+}
+
+// Small recursive structural equality for JSON values. Records are JSON, so
+// structural equality is well-defined and zero-dep. Primitives compared strict;
+// arrays elementwise by length+index (so `embedding` / `links` order matters);
+// plain objects by same key set + recursive values.
+function deepEqual(x, y) {
+  if (x === y) return true;
+
+  if (Array.isArray(x) || Array.isArray(y)) {
+    if (!Array.isArray(x) || !Array.isArray(y)) return false;
+    if (x.length !== y.length) return false;
+    return x.every((el, i) => deepEqual(el, y[i]));
+  }
+
+  if (typeof x === 'object' && x !== null && typeof y === 'object' && y !== null) {
+    const kx = Object.keys(x);
+    const ky = Object.keys(y);
+    if (kx.length !== ky.length) return false;
+    return kx.every((k) => Object.prototype.hasOwnProperty.call(y, k) && deepEqual(x[k], y[k]));
+  }
+
+  return false;
+}
+
+// The sorted list of field names that differ between two matched records, over
+// the union of their keys minus `ignore`. A key present on only one side is
+// always a difference (a dropped or added field). Sorted with `localeCompare`
+// for a deterministic order.
+function diffFields(a, b, ignore) {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  const fields = [];
+  for (const k of keys) {
+    if (ignore.has(k)) continue;
+    if (!deepEqual(a[k], b[k])) fields.push(k);
+  }
+  return fields.sort((x, y) => x.localeCompare(y));
+}
+
+function round4(n) {
+  return Math.round(n * 1e4) / 1e4;
+}
+
+/**
+ * Score how much of `before` survived into `after`.
+ * @param {Array<object>} before - the reference set (what we ask to survive)
+ * @param {Array<object>} after - the set to check it against
+ * @param {{ identity?: string, ignoreFields?: string[] }} [opts]
+ * @returns {{ score: number, total: number, preserved: number, lost: Array<{id: string, kind: string, content: string}>, degraded: Array<{id: string, fields: string[]}> }}
+ * @throws {ConformanceError} on an invalid input set (`invalid_set`, carrying
+ *   `.side` + the #1 `.errors`) or an unknown identity (`unknown_identity`).
+ */
+export function scoreConformance(before, after, opts = {}) {
+  // Validate both sets first — reliable, unique ids are what matching depends
+  // on, so comparing garbage is meaningless. Report the first invalid side.
+  for (const [side, set] of [['before', before], ['after', after]]) {
+    const { valid, errors } = validateMemorySet(set);
+    if (!valid) {
+      throw new ConformanceError('invalid_set', `${side} is an invalid memory set`, {
+        side,
+        errors,
+      });
+    }
+  }
+
+  const identity = opts.identity ?? 'id';
+  if (!CONFORMANCE_IDENTITIES.includes(identity)) {
+    throw new ConformanceError(
+      'unknown_identity',
+      `unknown identity: ${identity} (known: ${CONFORMANCE_IDENTITIES.join(', ')})`,
+    );
+  }
+
+  const ignore = new Set(opts.ignoreFields ?? []);
+
+  // ids are unique post-validation, so no record is silently clobbered.
+  const afterById = new Map(after.map((r) => [r.id, r]));
+
+  const lost = [];
+  const degraded = [];
+  let preserved = 0;
+
+  for (const rec of before) {
+    const other = afterById.get(rec.id);
+    if (other === undefined) {
+      lost.push({ id: rec.id, kind: rec.kind, content: rec.content });
+      continue;
+    }
+    const fields = diffFields(rec, other, ignore);
+    if (fields.length === 0) {
+      preserved++;
+    } else {
+      degraded.push({ id: rec.id, fields });
+    }
+  }
+
+  const total = before.length;
+  const score = total === 0 ? 1 : round4(preserved / total);
+
+  return { score, total, preserved, lost, degraded };
+}