@codewithjuber/forgekit 0.8.0

package/src/ledger_bridge.js

@@ -0,0 +1,279 @@
+// forge ledger bridge — the P1 migration seam between the legacy stores (lessons/*.md,
+// recall facts) and the PCM ledger. The ledger shadows every write as the new
+// canonical, and `forge ledger import` back-fills pre-ledger history. P2 (shipped —
+// see ledger_read.js) flipped READS to a merged view (legacy ∪ ledger); the legacy
+// files remain the canonical LOCAL state until full retirement.
+// Spec: docs/plans/substrate-v2/01-pcm-protocol.md §7.
+//
+// Every entry point here is BEST-EFFORT by design: the legacy store is still
+// canonical for local state, so a bridge failure returns {ok:false} and must never
+// break a hook or CLI write that already succeeded.
+import { mintClaim, outcomeRecord } from "./ledger.js";
+import {
+  appendEvidence,
+  loadClaims,
+  putClaim,
+  readEvidence,
+  reindex,
+  repoLedger,
+  tombstone,
+} from "./ledger_store.js";
+import { load as loadLessons } from "./lessons_store.js";
+// listStored, NOT list: the bridge reconciles the FILE store against the ledger. The
+// merged `list` (P2 read flip) includes ledger-only teammate facts, which have no file
+// and would read here as "deleted from the store".
+import { listStored as listFacts, readFact } from "./recall.js";
+import { epochDay, gitAuthor } from "./util.js";
+
+/** One best-effort policy for the whole bridge (never throws into a caller). */
+const bestEffort = (fn) => {
+  try {
+    return fn();
+  } catch (err) {
+    if (process.env.FORGE_DEBUG === "1")
+      process.stderr.write(`forge ledger bridge: ${err?.message ?? err}\n`);
+    return { ok: false, reason: String(err?.message ?? err) };
+  }
+};
+
+/** A lesson's claim: body = the CONTENT (trigger + texts) only. Counts/status are
+ *  evidence-derived and the legacy file id rides in PROVENANCE (excluded from the
+ *  content address) — so teammates who learn the same lesson mint the same id even
+ *  if their legacy filenames differ, and confirm/contradict never re-mints.
+ *  @returns {{ok:boolean, reason?:string, claim?:any}} */
+export function lessonClaim(lesson, t = 0) {
+  return mintClaim({
+    kind: "lesson",
+    body: {
+      correctedBehavior: lesson.correctedBehavior ?? "",
+      trigger: {
+        action: lesson.trigger?.action ?? "",
+        files: lesson.trigger?.files ?? [],
+        keywords: lesson.trigger?.keywords ?? [],
+        symbols: lesson.trigger?.symbols ?? [],
+      },
+      whatWentWrong: lesson.whatWentWrong ?? "",
+    },
+    scope: { level: lesson.scope ?? "repo" },
+    provenance: { agent: "cortex", author: gitAuthor(), task: lesson.id ?? "" },
+    t,
+  });
+}
+
+/** A recall fact's claim. Name/text are trimmed so the shadow-write path and the
+ *  file-parse import path mint the SAME id for the same fact.
+ *  @returns {{ok:boolean, reason?:string, claim?:any}} */
+export function factClaim(name, text, t = 0) {
+  return mintClaim({
+    kind: "fact",
+    body: { name: String(name).trim(), text: String(text).trim() },
+    scope: { level: "repo" },
+    provenance: { agent: "recall", author: gitAuthor() },
+    t,
+  });
+}
+
+/**
+ * Shadow-write one lesson event into the repo ledger.
+ * @param {string} root repo root
+ * @param {object} lesson the (already saved) lesson object
+ * @param {{result?:"confirm"|"contradict", oracle?:string, ref?:string, t?:number}} ev
+ *   evidence for this event; omit result for mint-only (a freshly created lesson has
+ *   zero evidence — creation is not confirmation). `ref` is required whenever a
+ *   result is given (outcomeRecord enforces it).
+ */
+export function recordLessonEvent(root, lesson, ev = {}) {
+  return bestEffort(() => {
+    const dir = repoLedger(root);
+    const minted = lessonClaim(lesson, ev.t ?? 0);
+    if (!minted.ok) return { ok: false, reason: minted.reason };
+    const put = putClaim(dir, minted.claim);
+    if (!put.ok) return put;
+    if (ev.result) {
+      const o = outcomeRecord({
+        oracle: ev.oracle ?? "cortex.episode",
+        result: ev.result,
+        ref: ev.ref,
+        author: gitAuthor(),
+        t: ev.t ?? 0,
+      });
+      if (!o.ok) return { ok: false, reason: "reason" in o ? o.reason : "invalid outcome" };
+      const a = appendEvidence(dir, minted.claim.id, o.outcome);
+      if (!a.ok) return a;
+    }
+    return { ok: true, id: minted.claim.id };
+  });
+}
+
+/**
+ * A lesson's body was rewritten (distillation) — content addressing means a NEW claim
+ * id, so carry the history across: mint the new claim, copy the old claim's evidence
+ * to it, and tombstone the old claim as superseded. Without this, evidence splits
+ * between an orphaned template claim and the distilled one.
+ */
+export function supersedeLessonClaim(root, before, after, t = epochDay()) {
+  return bestEffort(() => {
+    const dir = repoLedger(root);
+    const oldC = lessonClaim(before, t);
+    const newC = lessonClaim(after, t);
+    if (!newC.ok) return { ok: false, reason: newC.reason };
+    const put = putClaim(dir, newC.claim);
+    if (!put.ok) return put;
+    if (oldC.ok && oldC.claim.id !== newC.claim.id) {
+      for (const o of readEvidence(dir, oldC.claim.id)) appendEvidence(dir, newC.claim.id, o);
+      tombstone(dir, oldC.claim.id, {
+        author: gitAuthor(),
+        reason: `superseded-by:${newC.claim.id}`,
+        t,
+      });
+    }
+    return { ok: true, id: newC.claim.id };
+  });
+}
+
+/**
+ * Shadow one fact into a ledger, superseding any live fact claim with the same name
+ * but different content — so `forge remember api-base <new>` retires the old value
+ * instead of leaving a stale phantom the P2 read-flip would resurrect.
+ * @returns {{ok:boolean, reason?:string, id?:string, existed?:boolean}}
+ */
+export function shadowFact(ledgerDir, name, text, t = epochDay()) {
+  return bestEffort(() => {
+    const minted = factClaim(name, text, t);
+    if (!minted.ok) return { ok: false, reason: minted.reason };
+    const put = putClaim(ledgerDir, minted.claim);
+    if (!put.ok) return put;
+    for (const c of loadClaims(ledgerDir)) {
+      if (
+        c.kind === "fact" &&
+        !c.tombstone &&
+        c.id !== minted.claim.id &&
+        c.body?.name === minted.claim.body.name
+      )
+        tombstone(ledgerDir, c.id, {
+          author: gitAuthor(),
+          reason: `superseded-by:${minted.claim.id}`,
+          t,
+        });
+    }
+    reindex(ledgerDir, t);
+    return { ...put, id: minted.claim.id };
+  });
+}
+
+/**
+ * Re-align a ledger's fact claims with the store they shadow: any live fact claim
+ * whose (name, text) no longer exists as a stored fact is tombstoned. Called after
+ * `forge recall consolidate` (which rm's duplicate files) so deleted memories don't
+ * survive as live claims.
+ */
+export function reconcileFacts(store, ledgerDir, t = epochDay()) {
+  return bestEffort(() => {
+    const current = new Set();
+    for (const slug of listFacts(store)) {
+      const f = readFact(store, slug);
+      if (f) {
+        const minted = factClaim(f.name, f.text, t);
+        if (minted.ok) current.add(minted.claim.id);
+      }
+    }
+    let removed = 0;
+    for (const c of loadClaims(ledgerDir)) {
+      // Only reconcile claims THIS author minted: a locally-authored claim with no
+      // backing file means the file was deleted (consolidate rm'd a duplicate). A
+      // teammate's claim (arrived via `forge ledger merge`) never had a local file —
+      // with the P2 read flip it IS the readable fact, and tombstoning it here would
+      // silently delete team knowledge on every consolidate.
+      const mine = (c.provenance?.author ?? "") === gitAuthor();
+      if (c.kind === "fact" && !c.tombstone && mine && !current.has(c.id)) {
+        tombstone(ledgerDir, c.id, { author: gitAuthor(), reason: "removed-from-store", t });
+        removed++;
+      }
+    }
+    if (removed) reindex(ledgerDir, t);
+    return { ok: true, removed };
+  });
+}
+
+/**
+ * Import every fact in a recall/brain store into a ledger (idempotent; supersedes
+ * stale same-name claims via shadowFact).
+ * @returns {{facts:number, refused:string[]}}
+ */
+export function importFacts(store, ledgerDir, nowDay = 0) {
+  const refused = [];
+  let facts = 0;
+  for (const slug of listFacts(store)) {
+    const f = readFact(store, slug);
+    if (!f) {
+      refused.push(`fact ${slug}: unreadable`);
+      continue;
+    }
+    const r = shadowFact(ledgerDir, f.name, f.text, nowDay);
+    if (r.ok && !r.existed) facts++;
+    else if (!r.ok) refused.push(`fact ${slug}: ${r.reason}`);
+  }
+  return { facts, refused };
+}
+
+/**
+ * One-shot back-fill of PRE-LEDGER history. A lesson whose claim already exists in
+ * the ledger is skipped entirely — its live shadow-writes are already tracking it,
+ * and re-synthesizing evidence from the (still-moving) legacy counters would double-
+ * count and break idempotence. Only never-seen claims get their aggregate counts
+ * expanded into conservative `legacy.import` outcomes.
+ * @param {string} root repo root (lessons + repo ledger)
+ * @param {{recallStore?:string, recallLedger?:string, nowDay?:number}} opts
+ * @returns {{lessons:number, facts:number, outcomes:number, refused:string[]}}
+ */
+export function importLegacy(root, { recallStore, recallLedger, nowDay = 0 } = {}) {
+  const dir = repoLedger(root);
+  const refused = [];
+  let lessons = 0;
+  let outcomes = 0;
+
+  for (const lesson of loadLessons(root)) {
+    const minted = lessonClaim(lesson, lesson.createdDay ?? 0);
+    if (!minted.ok) {
+      refused.push(`lesson ${lesson.id}: ${minted.reason}`);
+      continue;
+    }
+    const put = putClaim(dir, minted.claim);
+    if (!put.ok) {
+      refused.push(`lesson ${lesson.id}: ${put.reason}`);
+      continue;
+    }
+    if (put.existed) continue; // already tracked live — never re-synthesize
+    lessons++;
+    // Aggregate counts become individual, decay-dated outcomes: confirms carry the
+    // last-confirmed day (what freshness keyed on), contradictions the created day
+    // (the legacy store kept no per-contradiction date — documented approximation).
+    /** @type {{result:"confirm"|"contradict", t:number, n:number}[]} */
+    const synth = [];
+    for (let i = 0; i < (lesson.evidenceCount ?? 0); i++)
+      synth.push({ result: "confirm", t: lesson.lastConfirmedDay ?? 0, n: i });
+    for (let i = 0; i < (lesson.contradictionCount ?? 0); i++)
+      synth.push({ result: "contradict", t: lesson.createdDay ?? 0, n: i });
+    for (const s of synth) {
+      const o = outcomeRecord({
+        oracle: "legacy.import",
+        result: s.result,
+        ref: `legacy:${lesson.id}#${s.result}${s.n}`,
+        t: s.t,
+      });
+      if (!o.ok) continue;
+      const a = appendEvidence(dir, minted.claim.id, o.outcome);
+      if (a.ok && !a.deduped) outcomes++;
+    }
+  }
+
+  let facts = 0;
+  if (recallStore) {
+    const r = importFacts(recallStore, recallLedger ?? dir, nowDay);
+    facts = r.facts;
+    refused.push(...r.refused);
+  }
+
+  reindex(dir, nowDay);
+  return { lessons, facts, outcomes, refused };
+}

package/src/ledger_read.js

@@ -0,0 +1,152 @@
+// forge ledger read — the P2 read-path flip (docs/plans/substrate-v2/01-pcm-protocol.md §7).
+// Since P1 the PCM ledger has been the convergent WRITE store while the legacy stores
+// (lessons/*.md, recall/brain facts) served every read. This module turns reads into a
+// MERGED VIEW (legacy ∪ ledger) so knowledge that arrives via `forge ledger merge`
+// actually reaches injection and retrieval. The legacy file is still the canonical
+// LOCAL state — the ledger only ADDS what teammates know — so the merge dedupes by the
+// legacy id with the legacy record winning. Retiring the legacy formats entirely is the
+// next step (ROADMAP.md).
+//
+// Everything here is READ-ONLY and best-effort by design: hooks call these on every
+// session start / pre-edit, so a missing or corrupt ledger degrades to legacy-only —
+// never an error, never a write.
+import { DEFAULT_HALF_LIFE_DAYS, val, validOutcome } from "./ledger.js";
+import { loadClaims, repoLedger } from "./ledger_store.js";
+import { load } from "./lessons_store.js";
+import { slug } from "./util.js";
+
+/**
+ * Map a ledger `lesson` claim onto the legacy lesson shape (lessons.js), so every
+ * existing consumer — matchScore, selectForInjection, confidenceOf, summary — can rank
+ * a teammate's claim without knowing the ledger exists. Inverse-ish of
+ * ledger_bridge.lessonClaim: body carries trigger/whatWentWrong/correctedBehavior, and
+ * the legacy lesson id rides in provenance.task (it is excluded from the content
+ * address so teammates converge on one claim id).
+ *
+ * The legacy lifecycle (candidate/active/quarantined/retired) is local mutable state
+ * the ledger deliberately does not store, so status is DERIVED from evidence:
+ *
+ * | claim state                          | derived status | rationale |
+ * |--------------------------------------|----------------|-----------|
+ * | tombstoned                           | "retired"      | a retraction is the ledger's retirement |
+ * | val(claim, nowDay) ≥ 0.6             | "active"       | one fresh confirm (bridge oracle w=0.5 → val 0.6) clears it — mirrors confirm()'s promote-on-recurrence |
+ * | val < 0.45 and ≥ 1 contradiction     | "quarantined"  | net-negative outcome evidence — mirrors contradict()'s demotion |
+ * | otherwise                            | "candidate"    | a fresh claim sits at the 0.5 prior, exactly newLesson() |
+ *
+ * Count/date fields are rebuilt from the evidence log: evidenceCount = valid confirm
+ * outcomes, contradictionCount = valid contradict outcomes, lastConfirmedDay = latest
+ * confirm t (else the mint day), createdDay = the mint day (provenance.t).
+ * @param {any} claim a materialized lesson claim (ledger_store.loadClaims view)
+ * @param {number} [nowDay] epoch day used for the val() decay clock
+ * @returns {object} a legacy-shaped lesson
+ */
+export function claimToLesson(claim, nowDay = 0) {
+  const body = claim.body ?? {};
+  const evidence = (claim.evidence ?? []).filter(validOutcome);
+  const confirms = evidence.filter((e) => e.result === "confirm");
+  const contradictions = evidence.length - confirms.length;
+  const createdDay = claim.provenance?.t ?? 0;
+  const v = val(claim, nowDay);
+  const status = claim.tombstone
+    ? "retired"
+    : v >= 0.6
+      ? "active"
+      : v < 0.45 && contradictions >= 1
+        ? "quarantined"
+        : "candidate";
+  return {
+    id: String(claim.provenance?.task || "") || `lsn_${claim.id.slice(0, 8)}`,
+    trigger: {
+      files: body.trigger?.files ?? [],
+      symbols: body.trigger?.symbols ?? [],
+      keywords: body.trigger?.keywords ?? [],
+      action: body.trigger?.action || undefined,
+    },
+    scope: claim.scope?.level ?? "repo",
+    whatWentWrong: body.whatWentWrong ?? "",
+    correctedBehavior: body.correctedBehavior ?? "",
+    evidenceCount: confirms.length,
+    contradictionCount: contradictions,
+    quarantineReconfirms: 0,
+    status,
+    createdDay,
+    lastConfirmedDay: confirms.length ? Math.max(...confirms.map((e) => e.t ?? 0)) : createdDay,
+    halfLifeDays: DEFAULT_HALF_LIFE_DAYS,
+    // The claim id is the audit pointer back to the ledger (`forge ledger blame <id>`).
+    provenance: { episodes: [], signals: [], claim: claim.id },
+  };
+}
+
+/** Every lesson claim of the repo ledger, mapped to legacy shape. [] when there is no
+ *  ledger or it is unreadable (best-effort — hooks call this on every event). */
+export function ledgerLessons(root, nowDay = 0) {
+  try {
+    return loadClaims(repoLedger(root))
+      .filter((c) => c.kind === "lesson")
+      .map((c) => claimToLesson(c, nowDay));
+  } catch {
+    return [];
+  }
+}
+
+// Within the ledger, two claims can map to one legacy id (a distillation supersedes its
+// template claim; both carry the same provenance.task). Prefer the live one, then the
+// most recently confirmed; ties keep the first in claim-id order (loadClaims is sorted),
+// so the pick is deterministic across replicas.
+const preferred = (a, b) => {
+  if ((a.status === "retired") !== (b.status === "retired")) return a.status === "retired" ? b : a;
+  return b.lastConfirmedDay > a.lastConfirmedDay ? b : a;
+};
+
+/**
+ * The merged lesson read: legacy `load(root)` ∪ ledger lessons, deduped by the LEGACY
+ * id with the legacy file winning — the legacy store is still the canonical local
+ * state (recordMistake/confirm/contradict edit it), so a local lesson's own shadow
+ * claim (same provenance.task) is invisible here, while a teammate's claim (different
+ * task, no local file) surfaces. Order is deterministic: legacy lessons in file order,
+ * then ledger-only lessons sorted by lesson id.
+ * @param {string} root
+ * @param {number} [nowDay]
+ * @returns {object[]}
+ */
+export function mergedLessons(root, nowDay = 0) {
+  const legacy = load(root);
+  const local = new Set(legacy.map((l) => l.id));
+  const byId = new Map();
+  for (const l of ledgerLessons(root, nowDay)) {
+    if (local.has(l.id)) continue; // legacy wins — the local file is canonical
+    const prev = byId.get(l.id);
+    byId.set(l.id, prev ? preferred(prev, l) : l);
+  }
+  return [...legacy, ...[...byId.values()].sort((a, b) => (a.id < b.id ? -1 : 1))];
+}
+
+/** Live (non-tombstoned) `fact` claims of one ledger as {slug, name, text} — the fact
+ *  counterpart of ledgerLessons. Best-effort: [] when the ledger is missing/corrupt. */
+export function ledgerFacts(dir) {
+  try {
+    return loadClaims(dir)
+      .filter((c) => c.kind === "fact" && !c.tombstone)
+      .map((c) => ({
+        slug: slug(c.body?.name ?? "") || "fact",
+        name: String(c.body?.name ?? ""),
+        text: String(c.body?.text ?? ""),
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Merged fact slugs for a file store + its ledger: the file store's slugs win on
+ * collision (a stored file is the canonical local value; shadowFact tombstones stale
+ * same-name claims, so a surviving collision means the file is newer). Sorted, unique.
+ * @param {string[]} fileSlugs slugs of the file-backed facts (already the store's truth)
+ * @param {string} dir the ledger directory that shadows this store
+ * @returns {string[]}
+ */
+export function mergeFactSlugs(fileSlugs, dir) {
+  const seen = new Set(fileSlugs);
+  for (const f of ledgerFacts(dir)) seen.add(f.slug);
+  return [...seen].sort();
+}