@rafinery/cli 0.13.0 → 0.14.0

package/lib/distiller/schema-ladder.mjs

@@ -1,186 +0,0 @@
-// The schema ladder (0.11.0 — schema-aware reconciliation, owner's 4-case
-// doctrine, 2026-07-25). Distillation is where knowledge from two lineages
-// meets, so it is ALSO where brain schema versions meet — the reconciler
-// resolves the version lattice BEFORE any claim-level judging, and the merged
-// result always lands on the newest schema the RUNNER understands:
-//
-//   1. target < source            → REWRITE-TARGET: the whole target brain
-//      lifts to the newer schema (the incoming side already speaks it).
-//   2. target > source            → UPGRADE-SOURCE: incoming old-schema
-//      candidates lift into the target's newer schema before judging.
-//   3. target == source < latest  → REWRITE-MERGED: both sides lift; the
-//      merged target is a full rewrite onto the latest schema.
-//   4. target == source == latest → DIFF: the happy flow, exactly today.
-//   ∅. either side > latest       → ABORT LOUDLY: a newer CLI authored this;
-//      this runner cannot judge a schema it does not know — update the
-//      runner, NEVER downgrade knowledge.
-//
-// Every non-abort mode converges in ONE pass: toVersion is always the
-// runner's latest (which case 1/2's higher side already equals or precedes —
-// the runner can never know less than what it authored). Transforms are
-// REGISTERED per step (v(N-1)→vN) in LADDER below; a missing step throws —
-// the ladder never guesses a schema (no assumed values). v1 is the baseline
-// and the only schema in existence today, so the registry ships empty: this
-// module is the SEAM, proven by tests, that makes a future v2 a one-entry
-// change instead of a migration crisis.
-
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-
-// Per-step, PER-OKF-TYPE transforms (owner 2026-07-26: each file class has its
-// own shape in the contract's type registry, so each ladder step declares each
-// class EXPLICITLY):
-//
-//   LADDER[2] = {
-//     describe: "what v2 changes",
-//     rule: (content) => content2,     // a real shape change for rules
-//     playbook: "unchanged",           // EXPLICIT identity — visible, auditable
-//     improvement: (content) => …,
-//   }
-//
-// Only the three DURABLE knowledge classes ladder (rule · playbook ·
-// improvement — the classes distillation judges and the brain keeps). Derived/
-// generated files (coverage, checklist, ledger, reconciliation reports,
-// manifest) are NEVER migrated — their producers regenerate them at the new
-// schema. A step missing a class entry is a LOUD error, not implicit identity:
-// "unchanged" must be declared, never assumed. Every applied step (identity
-// included) re-stamps the note's own `schemaVersion:` line.
-export const LADDER = {};
-
-export const LADDER_CLASSES = ["rule", "playbook", "improvement"];
-
-// Class resolution chain (owner 2026-07-26): DIRECTORY first — inside rafa's
-// transport the path is governed identity (the CAS row key, the registry
-// glob, the hydrate target; it cannot drift without becoming a different
-// row) — then the PORTABLE filename suffix (`.rule.md` · `.playbook.md` ·
-// `.improvement.md`), which travels WITH a file that leaves the canonical
-// tree (foreign OKF bundles, out-of-context shares) while staying outside
-// the corruptible content. When BOTH are present they must AGREE — a
-// contradiction throws loudly, never a guess. Returns null for non-laddered
-// paths (intent records, reports, …) — those pass through untouched.
-const SUFFIX_CLASS = {
-  ".rule.md": "rule",
-  ".playbook.md": "playbook",
-  ".improvement.md": "improvement",
-};
-export function classOf(path) {
-  const p = String(path).replace(/\\/g, "/");
-  const byDir = p.includes("brain/rules/")
-    ? "rule"
-    : p.includes("brain/playbooks/")
-      ? "playbook"
-      : p.includes("improve/improvements/")
-        ? "improvement"
-        : null;
-  const bySuffix =
-    Object.entries(SUFFIX_CLASS).find(([s]) => p.endsWith(s))?.[1] ?? null;
-  if (byDir && bySuffix && byDir !== bySuffix)
-    throw new Error(
-      `schema ladder: directory class "${byDir}" contradicts filename class "${bySuffix}" (${p}) — ` +
-        "fix the file's home or its name; the ladder never guesses",
-    );
-  return byDir ?? bySuffix;
-}
-
-// A note's OWN declared schema (first-fence `schemaVersion:`). Default 1 — the
-// founding schema, same convention as stampedVersions defaulting to the first
-// release (a pre-stamp file predates versioning, it isn't unversioned).
-export function noteSchemaVersion(content) {
-  if (typeof content !== "string" || !content.startsWith("---")) return 1;
-  const end = content.indexOf("\n---", 3);
-  const fm = end === -1 ? content : content.slice(0, end);
-  const m = fm.match(/^schemaVersion:\s*(\d+)\s*$/m);
-  return m ? Number(m[1]) : 1;
-}
-
-const NOTE_DIRS = ["brain/rules", "brain/playbooks", "improve/improvements"];
-
-export function walkBrainNotes(rafaDir) {
-  const out = [];
-  const walk = (dir) => {
-    if (!existsSync(dir)) return;
-    for (const e of readdirSync(dir)) {
-      const p = join(dir, e);
-      if (statSync(p).isDirectory()) walk(p);
-      else if (e.endsWith(".md") && !e.startsWith("_") && !e.endsWith(".theirs.md"))
-        out.push(p);
-    }
-  };
-  for (const d of NOTE_DIRS) walk(join(rafaDir, d));
-  return out;
-}
-
-// The TARGET brain's schema: manifest.json first (the compiled truth), else
-// the max over its notes' own declarations, else the founding schema.
-export function brainSchemaVersion(rafaDir) {
-  try {
-    const m = JSON.parse(readFileSync(join(rafaDir, "manifest.json"), "utf8"));
-    if (Number.isInteger(m.schemaVersion)) return m.schemaVersion;
-  } catch {
-    /* no manifest — fall through to the notes */
-  }
-  const versions = walkBrainNotes(rafaDir).map((f) =>
-    noteSchemaVersion(readFileSync(f, "utf8")),
-  );
-  return versions.length ? Math.max(...versions) : 1;
-}
-
-// The SOURCE side's schema: the max over the incoming candidates' own
-// declarations (a working set may be mixed if it straddled an upgrade).
-export function sourceSchemaVersion(contents) {
-  const versions = (contents ?? []).map(noteSchemaVersion);
-  return versions.length ? Math.max(...versions) : 1;
-}
-
-// The lattice. Returns {mode, toVersion, rewriteTarget, upgradeSource, reason}.
-export function resolveSchemaPlan({ target, source, latest }) {
-  if (target > latest || source > latest)
-    return {
-      mode: "abort-newer-than-runner",
-      toVersion: null,
-      rewriteTarget: false,
-      upgradeSource: false,
-      reason:
-        `brain schema v${Math.max(target, source)} is NEWER than this runner's v${latest} — ` +
-        "a newer CLI authored it. Update @rafinery/cli and re-run; knowledge is never downgraded.",
-    };
-  const base = { toVersion: latest, rewriteTarget: target < latest, upgradeSource: source < latest };
-  if (target < source)
-    return { mode: "rewrite-target", ...base, reason: `target v${target} < source v${source} — full target rewrite onto v${latest}` };
-  if (source < target)
-    return { mode: "upgrade-source", ...base, reason: `source v${source} < target v${target} — incoming candidates lift into v${latest}` };
-  if (target < latest)
-    return { mode: "rewrite-merged", ...base, reason: `both sides v${target} < runner v${latest} — merged result rewrites onto v${latest}` };
-  return { mode: "diff", ...base, reason: `both sides already v${latest} — plain diff reconcile` };
-}
-
-const stampVersion = (content, v) =>
-  content.replace(/^schemaVersion:\s*\d+\s*$/m, `schemaVersion: ${v}`);
-
-// Lift ONE note of ONE class from its own declared version to `to`, one
-// registered step at a time. A missing step OR a missing class entry within a
-// step is a loud error, never a guess; the explicit "unchanged" is the only
-// legal identity, and even it re-stamps the note's schemaVersion line.
-export function applyLadder(content, to, cls) {
-  if (!LADDER_CLASSES.includes(cls))
-    throw new Error(
-      `schema ladder: "${cls}" is not a laddered class (${LADDER_CLASSES.join("|")}) — ` +
-        "derived/generated files regenerate at the new schema, they never migrate",
-    );
-  let from = noteSchemaVersion(content);
-  let out = content;
-  while (from < to) {
-    const step = LADDER[from + 1];
-    const t = step?.[cls];
-    if (t === undefined)
-      throw new Error(
-        `schema ladder: no registered ${cls} transform v${from}→v${from + 1} — every step ` +
-          'declares every class (a function, or the EXPLICIT "unchanged"); ' +
-          "update @rafinery/cli to a release that ships it (the ladder never guesses a schema)",
-      );
-    out = t === "unchanged" ? out : t(out);
-    out = stampVersion(out, from + 1);
-    from += 1;
-  }
-  return out;
-}