@lorekit/cli 1.59.1 → 1.61.0

package/src/shared/candidates-pure.mjs

@@ -0,0 +1,110 @@
+// Pure core for `lorekit invariants candidates` — ranks near-duplicate
+// clusters (the same Jaccard heuristic `dedupe` uses) as merge candidates for
+// a hand-written compile-pipeline invariant declaration.
+//
+// This module is deliberately read-only in a stronger sense than "no writes":
+// it never CLASSIFIES anything. It surfaces what a lesson already states about
+// itself (a parsed meta comment, a seen_count, a resolved recurrence class)
+// and ranks it — it does not decide whether a trigger-context is mechanically
+// detectable, and it does not validate `status` against a fixed vocabulary
+// (none is defined anywhere in this codebase yet). That judgment is the human
+// step the compile pipeline's "never auto-compile, never auto-gate" rule
+// protects; a scan that started making those calls would be the thing the
+// rule exists to prevent.
+//
+// Operates on already-enriched cluster members — `{ scope, key, seenCount,
+// value }` — leaving the store I/O and the seen_count/meta correlation to the
+// command (`../commands/invariants.mjs`). Zero-dep, total: malformed input
+// degrades to the empty/default case rather than throwing.
+
+const META_COMMENT_RE = /<!--\s*meta:([\s\S]*?)-->/;
+const META_FIELD_RE = /([\w-]+)=("(?:[^"\\]|\\.)*"|\S+)/g;
+
+/**
+ * Extract the `<!-- meta: seen_count=1 status=active expires=<iso>
+ * trigger-context="<signal>" -->` convention documented in the lorekit-setup
+ * skill's `self-improvement-loops.md`. Nothing in the CLI parses this
+ * convention today; this is read-only extraction for a human's judgment, not
+ * a schema the scan enforces. Absent or malformed input yields `{}`, never a
+ * throw — a lesson written before (or without) the convention is not an
+ * error, just a candidate with no meta fields.
+ */
+export function parseMetaComment(value) {
+  if (typeof value !== 'string') return {};
+  const m = META_COMMENT_RE.exec(value);
+  if (!m) return {};
+  const out = {};
+  META_FIELD_RE.lastIndex = 0;
+  let mm;
+  while ((mm = META_FIELD_RE.exec(m[1]))) {
+    const [, k, rawV] = mm;
+    out[k] =
+      rawV.startsWith('"') && rawV.endsWith('"') ? rawV.slice(1, -1).replace(/\\"/g, '"') : rawV;
+  }
+  return out;
+}
+
+function totalSeen(members) {
+  return (members || []).reduce((n, m) => n + (Number.isFinite(m.seenCount) ? m.seenCount : 0), 0);
+}
+
+function distinctScopeCount(members) {
+  return new Set((members || []).map((m) => m.scope)).size;
+}
+
+/**
+ * A cluster is a candidate when its recurrence signal is real: either the
+ * summed `seenCount` across members crosses `minSeenCount` (default 3 — the
+ * kickoff's "seen_count >= 3" criterion, applied to the SUM across the
+ * cluster's members rather than any single one, since the whole pitch of a
+ * candidate is "these N sightings are really one entry"), or a member's own
+ * meta comment already declares a non-"active" status.
+ */
+export function isCandidate(members, { minSeenCount = 3 } = {}) {
+  if (totalSeen(members) >= minSeenCount) return true;
+  return (members || []).some((m) => {
+    const status = parseMetaComment(m.value).status;
+    return typeof status === 'string' && status.length > 0 && status !== 'active';
+  });
+}
+
+/** Recurrence × distinct scopes — the ranking signal the kickoff names. */
+export function scoreCandidate(members) {
+  return totalSeen(members) * distinctScopeCount(members);
+}
+
+/**
+ * Filter a set of dedupe-style clusters down to candidates and rank them,
+ * highest score first (ties broken by member count, then the first member's
+ * `scope::key` for determinism). Each input cluster is
+ * `{ members: [{scope,key,seenCount,value}], size, minSimilarity?,
+ * maxSimilarity? }`. Never mutates the input.
+ *
+ * `resolveClass`, when supplied, is called with the cluster's raw members to
+ * attach a resolved recurrence class (the `dedupe` join, reused here) — a
+ * candidate already resolving to a known class is a stronger case ("this
+ * should join an existing invariant") than one that doesn't ("this might be a
+ * new class"). Optional so the pure ranking logic stays testable without it.
+ */
+export function rankCandidates(clusters, { minSeenCount = 3, resolveClass } = {}) {
+  return (clusters || [])
+    .filter((cl) => isCandidate(cl.members, { minSeenCount }))
+    .map((cl) => {
+      const members = (cl.members || []).map((m) => ({ ...m, meta: parseMetaComment(m.value) }));
+      return {
+        members,
+        size: cl.size ?? members.length,
+        minSimilarity: cl.minSimilarity,
+        maxSimilarity: cl.maxSimilarity,
+        recurrenceClass: typeof resolveClass === 'function' ? resolveClass(cl.members) : null,
+        score: scoreCandidate(cl.members),
+      };
+    })
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      if (b.size !== a.size) return b.size - a.size;
+      const aKey = `${a.members[0]?.scope}::${a.members[0]?.key}`;
+      const bKey = `${b.members[0]?.scope}::${b.members[0]?.key}`;
+      return aKey < bKey ? -1 : aKey > bKey ? 1 : 0;
+    });
+}

package/src/shared/completions.mjs

@@ -71,6 +71,8 @@ const FLAG = {
   'retention-days': { desc: 'Only purge archived older than n days', arg: 'n' },
   files: { desc: 'Changed files to check', arg: 'path' },
   strict: { desc: 'Exit non-zero on any unmet obligation' },
+  'strict-all': { desc: 'Exit non-zero on ANY unmet obligation, advisory included' },
+  'min-seen-count': { desc: 'Minimum summed seen_count for a candidate', arg: 'n' },
   'policy-id': { desc: 'Run/preview a saved policy', arg: 'id' },
   'min-age-days': { desc: 'Match lessons at least n days old', arg: 'n' },
   'unseen-days': { desc: 'Match lessons unseen for at least n days', arg: 'n' },
@@ -121,7 +123,9 @@ const COMMANDS = [
     flags: ['dir', 'scope', 'threshold', 'cluster-by-key', 'json', 'endpoint', 'token', 'store'] },
   { name: 'obligations', summary: 'Check changed files against the surface-partner map',
     positional: 'path',
-    flags: ['files', 'strict', 'json'] },
+    flags: ['files', 'strict', 'strict-all', 'json'] },
+  { name: 'invariants', summary: "Compile pipeline's candidate scan (`invariants candidates`)",
+    flags: ['dir', 'scope', 'min-seen-count', 'json', 'endpoint', 'token', 'store'] },
   { name: 'link', summary: 'Print a shareable dashboard deep-link URL', aliases: ['url'],
     positional: 'address',
     flags: ['dir', 'scope', 'key', 'q', 'owner', 'tags', 'range', 'from', 'to', 'archived', 'base', 'json'] },

package/src/shared/deeplink-pure.mjs

@@ -46,6 +46,9 @@ export const LORE_PARAM_DEFAULTS = {
   // "unfiltered".
   filters: null,
   tags: [], // string[] — legacy label filter (AND across labels); [] means "no filter". Still READ by the app, superseded by `filters`
+  // RetentionConditions | null — the retention-preview trio (min age / unseen-for
+  // / seen-at-most). `null` means no narrowing; absent from the URL when unset.
+  retention: null,
   // 'active' | 'archived' | 'expiring' | null — the Explorer's Status control.
   // `null`, NOT 'active', is the default for `filters`' reason: the app has to
   // tell "absent" from an explicit choice, because an absent `status` falls back
@@ -59,9 +62,21 @@ export const LORE_PARAM_DEFAULTS = {
 
 // A stable, readable param order (also makes URLs deterministic for tests).
 // Mirrors the `useUrlState` call order in `LoreExplorer.tsx` (+ the `lesson`
-// param last), so `filters` and `tags` sit between `owner` and `status`. `scope`
-// precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
-const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'filters', 'tags', 'status', 'archived', 'lesson'];
+// param last), so `filters` and `tags` sit between `owner` and `status`, and
+// `retention` sits between `tags` and `status`. `scope` precedes `lesson` so a
+// lesson link reads `?scope=…&lesson=…`.
+const PARAM_ORDER = [
+  'scope',
+  'q',
+  'range',
+  'owner',
+  'filters',
+  'tags',
+  'retention',
+  'status',
+  'archived',
+  'lesson',
+];
 
 // Strip trailing slashes from a base URL, falling back to the default when the
 // input is empty/absent. Pure.

package/src/shared/obligations-map.mjs

@@ -31,7 +31,32 @@
 //                                // when a name-derived module's real partner
 //                                // could live under either of two sibling
 //                                // directories)
-//     lessonKey: string,        // canonical memory key to cite
+//     state: 'advisory'|'gating'|'retired',
+//                                // advisory: reported, gates nothing.
+//                                // gating: fails --strict. An entry may only
+//                                // be `gating` if it has a `guard` — an
+//                                // independent source that already asserts
+//                                // the partnership. Without one, the entry
+//                                // asserts only its own author's belief, and
+//                                // `perf-index` / `error-code-doc` say as
+//                                // much in their notes. Enforced in
+//                                // obligations.test.mjs.
+//                                // retired: not checked; kept for provenance.
+//     cluster: string,          // the recurrence class this entry
+//                                // instantiates (`./recurrence-clusters.mjs`).
+//                                // Supplies the lesson key to cite, and
+//                                // groups entries that share a root cause.
+//     lessonKey?: string,       // an entry-specific memory key, overriding
+//                                // its cluster's canonical one. Rare.
+//     owner: string,            // who reviews this entry when it misfires.
+//                                // An entry with no owner is cruft with a CI
+//                                // job attached.
+//     added: string,            // ISO date
+//     reviewBy: string,         // ISO date. Memories expire; without this the
+//                                // map is the one place in the system under
+//                                // no decay pressure, and it accumulates the
+//                                // way the lesson variants it replaced did.
+//                                // Guard-less entries get a shorter horizon.
 //     guard?: string,           // the existing CI spec/script that enforces
 //                                // this partnership, if any
 //     note?: string,            // why this entry exists / its limitations
@@ -56,19 +81,6 @@
 
 import { mirrorPairs } from './mirror-pairs.mjs';
 
-// The flagship recurrence class: a partner copies a CLAIM (a mirrored
-// module's behavior, a generated artifact's content, a documented mechanism)
-// and goes stale when the source changes. Cited by every entry below whose
-// obligation is "this partner copies what you just changed."
-const COPIES_A_CLAIM_LESSON =
-  'implement-suggestion-lessons::a-mechanism-clause-you-correct-in-the-pr-body-must-be-corrected-in-every-doc-that-copies-it';
-
-// The registered-everywhere / sibling-set recurrence class: adding or moving
-// something that a SET of surfaces enumerates (a doc listing every command,
-// a generated mirror listing every file) re-flags every surface that lists
-// the set and now has a hole.
-const SIBLING_SET_LESSON = 'aw-lessons::docs-drift-grep-must-search-names-not-invocation';
-
 const EDGE_MIRROR_GUARD = 'packages/mcp-core/src/edge/edge-parity.spec.ts';
 
 // One `{ match, obliges }` row PER KNOWN PAIR, in both directions — see the
@@ -76,17 +88,25 @@ const EDGE_MIRROR_GUARD = 'packages/mcp-core/src/edge/edge-parity.spec.ts';
 const EDGE_MIRROR_ENTRIES = mirrorPairs.flatMap(({ core, edge }) => [
   {
     id: 'edge-mirror',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: edge,
     obliges: [core],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: EDGE_MIRROR_GUARD,
     note: 'An edge (Deno) module mirrored self-contained from mcp-core — edit one, mirror the other. Partner looked up from the shared mirror-pairs inventory, never reconstructed from an assumed-symmetric path.',
   },
   {
     id: 'edge-mirror-core',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: core,
     obliges: [edge],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: EDGE_MIRROR_GUARD,
     note: 'The reverse direction of edge-mirror — a mcp-core source file changed, its known edge mirror (from the same mirror-pairs inventory) is the partner.',
   },
@@ -96,6 +116,10 @@ export const SURFACE_PARTNER_MAP = [
   ...EDGE_MIRROR_ENTRIES,
   {
     id: 'tool-catalog',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: 'packages/schemas/src/shared/tool-catalog.ts',
     obliges: [
       'supabase/functions/mcp/tool-dispatch.generated.ts',
@@ -103,52 +127,84 @@ export const SURFACE_PARTNER_MAP = [
       'packages/web/public/llms.txt',
       'run:pnpm nx generate:llms schemas',
     ],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: 'packages/mcp-core/src/mcp-guards/tool-catalog-parity.spec.ts, scripts/codegen/gen-surfaces.mjs --check',
     note: 'The catalog is the single origin of the operation surface — every generated projection of it must be regenerated in the same commit.',
   },
   {
     id: 'llms-generated',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: ['packages/schemas/src/llms/template.md', 'packages/schemas/src/shared/tool-catalog.ts'],
     obliges: ['packages/web/public/llms.txt', 'run:pnpm nx generate:llms schemas'],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: 'packages/schemas/src/llms/render.spec.ts',
     note: 'llms.txt is GENERATED — never hand-edited; the committed file must be what the generator produces from these two sources.',
   },
   {
     id: 'docs-section',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: 're:^packages/web/src/content/docs/[^/]+\\.mdx$',
     obliges: ['packages/web/src/lib/docs/sections.ts'],
-    lessonKey: SIBLING_SET_LESSON,
+    cluster: 'sibling-set',
     guard: 'packages/web/src/lib/docs/sections.spec.ts',
     note: 'A new/removed docs page needs its DOCS_SECTIONS entry, or the site index and the page itself drift apart.',
   },
   {
     id: 'plugin-skill',
+    state: 'gating',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2027-02-26',
     match: 'packages/cli/skill/**',
     obliges: ['run:node scripts/codegen/sync-plugin-skill.mjs', 'plugins/lorekit-claude/skills/**'],
-    lessonKey: SIBLING_SET_LESSON,
+    cluster: 'sibling-set',
     guard: 'scripts/codegen/sync-plugin-skill.mjs --check',
     note: 'The Claude plugin vendors a copy of every skill/* source — regenerate the mirror, never hand-edit it.',
   },
+  {
+    id: 'cli-flag-doc',
+    state: 'advisory',
+    owner: '@mthines',
+    added: '2026-08-31',
+    reviewBy: '2026-11-30',
+    match: 'packages/cli/bin/lorekit.mjs',
+    obliges: ['docs/cli.md', 'packages/cli/README.md', 'CLAUDE.md'],
+    cluster: 'copies-a-claim',
+    guard: null,
+    note: 'The flag table and per-command help in bin/lorekit.mjs is the origin of every flag claim; docs/cli.md, the package README (prose AND its flag table) and CLAUDE.md each restate it. Found by running this command against its own changed-set while changing the meaning of --strict: nothing fired, because the map covered every generated surface and no hand-written one. A path proxy, not a content predicate — bin/lorekit.mjs changes for reasons unrelated to flags — so advisory by construction, like error-code-doc.',
+  },
   {
     id: 'perf-index',
+    state: 'advisory',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2026-11-26',
     match: 're:^supabase/migrations/.*index.*\\.sql$',
     obliges: ['supabase/tests/migrations.test.sql'],
-    lessonKey: SIBLING_SET_LESSON,
+    cluster: 'sibling-set',
     guard: null,
     note: 'Convention only — a real gap. A new index migration has no automated nudge to add its coverage to the migrations test.',
   },
   {
     id: 'error-code-doc',
+    state: 'advisory',
+    owner: '@mthines',
+    added: '2026-08-26',
+    reviewBy: '2026-11-26',
     match: ['supabase/functions/mcp/mcp-handler.ts', 'packages/mcp-core/src/auth/account-wide-tools.ts'],
     obliges: [
       'docs/mcp-tools.md',
       'packages/schemas/src/llms/template.md',
       'packages/web/public/llms.txt',
     ],
-    lessonKey: COPIES_A_CLAIM_LESSON,
+    cluster: 'copies-a-claim',
     guard: null,
-    note: 'A documented path-proxy, not a content predicate — obligations sees file paths, not diffs, so it cannot tell an error-const edit from an unrelated one in the same file and may over-flag. Advisory only (never gates unless --strict, and even then it is one signal among several).',
+    note: 'A documented path-proxy, not a content predicate — obligations sees file paths, not diffs, so it cannot tell an error-const edit from an unrelated one in the same file and may over-flag. State is `advisory` for that reason: it is reported on every hit and gates nothing, not even under --strict (only --strict-all).',
   },
 ];

package/src/shared/obligations-pure.mjs

@@ -45,6 +45,8 @@
 // `stemOf` (below) is the simpler, general-purpose primitive — a plain
 // basename-without-extension — exported for standalone use and unit testing.
 
+import { clusterForEntry, lessonKeyForEntry } from './recurrence-clusters.mjs';
+
 export const RUN_PREFIX = 'run:';
 export const REGEX_PREFIX = 're:';
 
@@ -217,10 +219,15 @@ export function checkObligations({ changedFiles = [], map = [] } = {}) {
 
       let bucket = byId.get(entry.id);
       if (!bucket) {
+        const cluster = clusterForEntry(entry);
         bucket = {
           id: entry.id,
-          lessonKey: entry.lessonKey ?? null,
+          state: entry.state ?? 'advisory',
+          cluster: cluster ? { id: cluster.id, name: cluster.name, why: cluster.why } : null,
+          lessonKey: lessonKeyForEntry(entry),
           guard: entry.guard ?? null,
+          owner: entry.owner ?? null,
+          reviewBy: entry.reviewBy ?? null,
           note: entry.note ?? null,
           obliges: new Map(),
         };
@@ -232,15 +239,25 @@ export function checkObligations({ changedFiles = [], map = [] } = {}) {
     }
   }
 
-  const matched = [...byId.values()].map((b) => ({
-    id: b.id,
-    lessonKey: b.lessonKey,
-    guard: b.guard,
-    note: b.note,
-    obliges: [...b.obliges.values()],
-  }));
+  const matched = [...byId.values()]
+    .filter((b) => b.state !== 'retired')
+    .map((b) => ({
+      id: b.id,
+      state: b.state,
+      cluster: b.cluster,
+      lessonKey: b.lessonKey,
+      guard: b.guard,
+      owner: b.owner,
+      reviewBy: b.reviewBy,
+      note: b.note,
+      obliges: [...b.obliges.values()],
+    }));
+
+  const countUnmet = (entries) =>
+    entries.reduce((n, e) => n + e.obliges.filter((o) => o.met === false).length, 0);
 
-  const unmet = matched.reduce((n, e) => n + e.obliges.filter((o) => o.met === false).length, 0);
+  const unmet = countUnmet(matched);
+  const unmetGating = countUnmet(matched.filter((e) => e.state === 'gating'));
 
-  return { files, matched, unmet, ok: unmet === 0 };
+  return { files, matched, unmet, unmetGating, ok: unmet === 0, okGating: unmetGating === 0 };
 }

package/src/shared/recurrence-clusters.mjs

@@ -0,0 +1,161 @@
+// Recurrence clusters — the named classes of repeated failure that the
+// Surface-Partner Map's entries instantiate.
+//
+// This module formalizes something the map already did informally. Before it,
+// `obligations-map.mjs` held two bare string constants —
+// `COPIES_A_CLAIM_LESSON` and `SIBLING_SET_LESSON` — whose own comments called
+// them "the flagship recurrence class" and "the registered-everywhere /
+// sibling-set recurrence class". Eight entries, two classes: the clustering had
+// been done by hand and encoded as a variable name.
+//
+// Naming it makes three things possible that a bare constant does not:
+//
+//   1. A cluster can carry WHY it recurs and WHAT ITS SHAPE IS, not just which
+//      lesson key to cite. That text is what a human hitting the check needs.
+//   2. `checkObligations` can report the cluster alongside the entry, so two
+//      unmet obligations from the same root cause read as one problem.
+//   3. It is the join point for the compile pipeline: a cluster is what a
+//      candidates scan over the memory store produces (N near-duplicate
+//      memories that are really one class), and an invariant entry is what a
+//      human writes from a cluster. The `sourceKeys` field records that origin
+//      in the only direction currently available — from the entry back to the
+//      memories.
+//
+// Pure and zero-dep by design, like `obligations-pure.mjs`: no filesystem, no
+// cwd, no network. The registry is data.
+//
+// Cluster schema:
+//   {
+//     id: string,          // stable slug, referenced by map entries' `cluster`
+//     name: string,        // one line, the shape of the recurrence
+//     lessonKey: string,   // canonical memory key an entry in this class cites
+//     why: string,         // why this class recurs — shown on a hit
+//     sourceKeys?: string[] // other memory keys this class subsumes, if known
+//   }
+
+/**
+ * The named recurrence classes. Adding one is a deliberate act: a cluster
+ * asserts that several distinct memories are really one class, which is the
+ * claim a groom-merge would act on. Two entries sharing a `lessonKey` but not
+ * a cluster is a smell — they are the same class and should say so.
+ */
+export const RECURRENCE_CLUSTERS = [
+  {
+    id: 'copies-a-claim',
+    name: 'A partner copies a claim and goes stale when the source changes',
+    lessonKey:
+      'implement-suggestion-lessons::a-mechanism-clause-you-correct-in-the-pr-body-must-be-corrected-in-every-doc-that-copies-it',
+    why: 'Some surface — a mirrored module, a generated artifact, a doc paragraph — restates a claim it does not own. Changing the origin does not change the copy, and nothing in the edit itself points at the copy.',
+  },
+  {
+    id: 'sibling-set',
+    name: 'A set-enumerating surface gains a hole when a member is added or moved',
+    lessonKey: 'aw-lessons::docs-drift-grep-must-search-names-not-invocation',
+    why: 'Several surfaces enumerate a set (every command, every docs page, every mirrored file). Adding or moving a member leaves each enumeration silently incomplete, and a grep for the invocation rather than the name misses them.',
+  },
+];
+
+const BY_ID = new Map(RECURRENCE_CLUSTERS.map((cl) => [cl.id, cl]));
+const BY_LESSON_KEY = new Map(RECURRENCE_CLUSTERS.map((cl) => [cl.lessonKey, cl]));
+
+/** The cluster with this id, or null. Total: an unknown id is not an error. */
+export function clusterById(id) {
+  if (typeof id !== 'string' || !id) return null;
+  return BY_ID.get(id) ?? null;
+}
+
+/**
+ * The cluster that owns this lesson key, or null. Lets an entry that still
+ * carries a bare `lessonKey` (rather than a `cluster` id) resolve to its class,
+ * so the two forms coexist during the migration.
+ */
+export function clusterForLessonKey(lessonKey) {
+  if (typeof lessonKey !== 'string' || !lessonKey) return null;
+  return BY_LESSON_KEY.get(lessonKey) ?? null;
+}
+
+/**
+ * Resolve an entry's cluster from either form — an explicit `cluster` id wins,
+ * a bare `lessonKey` falls back to reverse lookup. Returns null when the entry
+ * belongs to no known class, which is legal but worth reporting: an entry with
+ * no cluster is a one-off, and a one-off is weak evidence for a check.
+ */
+export function clusterForEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  return clusterById(entry.cluster) ?? clusterForLessonKey(entry.lessonKey);
+}
+
+/**
+ * The lesson key an entry should cite: its own explicit `lessonKey` if it has
+ * one, otherwise its cluster's canonical key.
+ */
+export function lessonKeyForEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  if (typeof entry.lessonKey === 'string' && entry.lessonKey) return entry.lessonKey;
+  return clusterForEntry(entry)?.lessonKey ?? null;
+}
+
+/** Every map entry belonging to a cluster, by id. Order preserved. */
+export function clusterMembers(clusterId, map = []) {
+  if (!Array.isArray(map)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const entry of map) {
+    if (clusterForEntry(entry)?.id !== clusterId) continue;
+    if (!entry.id || seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    out.push(entry.id);
+  }
+  return out;
+}
+
+/**
+ * The join to `dedupe`: does a group of memory keys (a dedupe cluster's
+ * members) already belong to a NAMED recurrence class? A member's `key`
+ * resolves to a class when it equals that class's canonical `lessonKey` or
+ * appears in its `sourceKeys` — the other sightings the class is known to
+ * subsume.
+ *
+ * This is a stronger signal than lexical similarity alone: a dedupe cluster
+ * that resolves here isn't just "these look alike", it's "this is (at least
+ * partly) another sighting of a class we already named and can cite."
+ *
+ * `pure: true` only when EVERY member resolves to the SAME single class — the
+ * strongest case, where merging under the class's canonical key loses no
+ * stragglers. A mixed match (some members resolve, some don't, or they split
+ * across classes) still reports the majority class via `matched`, so a
+ * partial hit isn't silently discarded — ties break by registry order.
+ *
+ * Total: no members, or no member resolving to any class, returns the null
+ * shape rather than throwing or returning undefined fields.
+ */
+export function resolveRecurrenceClass(members = [], clusters = RECURRENCE_CLUSTERS) {
+  const list = Array.isArray(members) ? members : [];
+  const counts = new Map();
+  const matched = [];
+  for (const m of list) {
+    const key = m?.key;
+    if (typeof key !== 'string' || !key) continue;
+    for (const cl of clusters) {
+      const sourceKeys = Array.isArray(cl.sourceKeys) ? cl.sourceKeys : [];
+      if (key !== cl.lessonKey && !sourceKeys.includes(key)) continue;
+      matched.push(key);
+      counts.set(cl.id, (counts.get(cl.id) ?? 0) + 1);
+      break;
+    }
+  }
+  if (matched.length === 0) return { classId: null, className: null, matched: [], pure: false };
+
+  let bestId = null;
+  let bestCount = -1;
+  for (const cl of clusters) {
+    const n = counts.get(cl.id) ?? 0;
+    if (n > bestCount) {
+      bestCount = n;
+      bestId = cl.id;
+    }
+  }
+  const best = clusters.find((cl) => cl.id === bestId) ?? null;
+  const pure = matched.length === list.length && counts.size === 1;
+  return { classId: best?.id ?? null, className: best?.name ?? null, matched, pure };
+}