Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
29.0 KB
Raw Blame
/**
 * Tests for `src/core/brain/lessons-promotion.ts` (t_1e952e43).
 *
 * Drives the operator-approved lesson promotion kernel:
 *   - the exact qualification conjunction (preference-derived, confirmed,
 *     high confidence, preferred tier, enabled scope, fresh approval) with
 *     every non-member carrying exactly one named blocked reason;
 *   - the deterministic, timestamp-free block body render;
 *   - the approvals ledger in the derived store (round-trip, upsert,
 *     named refusals, never under `Brain/`);
 *   - the three new log event kinds appending through the shared chain;
 *   - the writer-routing assertion: the kernel writes rules files only
 *     through the shared rules-block writer, never through `node:fs`.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  LESSONS_APPROVALS_FILE,
  LESSON_PROMOTION_BLOCKED,
  LESSONS_PROMOTION_SCOPES_CONFIG_KEY,
  LessonRenderError,
  LessonsPromotionScopesMalformedError,
  lessonPromotionCandidates,
  lessonsApprovalsPath,
  markLessonPromoted,
  readLessonApprovals,
  recordLessonApproval,
  renderLessonsBlockBody,
  renderLessonsBlockWithDrops,
  resolvePromotionScopesStrict,
  lessonIdsInBlockBody,
  type LessonApprovalRow,
  type LessonPromotionCandidate,
} from "../../../src/core/brain/lessons-promotion.ts";
import { LESSON_TIER, type LessonEntry } from "../../../src/core/brain/lessons.ts";
import { computeContentHash } from "../../../src/core/brain/content-hash.ts";
import { appendLogEvent } from "../../../src/core/brain/log.ts";
import { listLogDates, readLogDay } from "../../../src/core/brain/log-jsonl.ts";
import { resolveLessonsPromotionScopes } from "../../../src/core/brain/policy/blocks/lessons.ts";
import {
  DEFAULT_BEGIN_MARKER,
  DEFAULT_END_MARKER,
} from "../../../src/core/install/managed-block.ts";
import { RULES_BLOCK_ID, RULES_BLOCK_MARKERS } from "../../../src/core/install/rules-block.ts";
import {
  missingWritebackGateClauses,
  WRITEBACK_CONTRACT_REQUIREMENTS,
} from "../../../src/core/brain/writeback-contract.ts";
import type { BrainPreference } from "../../../src/core/brain/types.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";

// ----- Fixtures -------------------------------------------------------------

const NOW = new Date("2026-05-20T12:00:00Z");

function buildPref(id: string, overrides: Partial<BrainPreference> = {}): BrainPreference {
  return {
    kind: "brain-preference",
    id,
    created_at: "2026-01-01T00:00:00Z",
    confirmed_at: "2026-01-02T00:00:00Z",
    unconfirmed_until: "2026-01-08T00:00:00Z",
    tags: [],
    topic: id.replace(/^pref-/, ""),
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    principle: `principle for ${id}`,
    scope: "backend",
    evidenced_by: [],
    applied_count: 3,
    violated_count: 0,
    last_evidence_at: "2026-05-01T00:00:00Z",
    confidence: "high",
    confidence_value: 0.9,
    pinned: false,
    ...overrides,
  };
}

function buildLesson(id: string, overrides: Partial<LessonEntry> = {}): LessonEntry {
  return {
    id,
    kind: "preference",
    title: `principle for ${id}`,
    scope: "backend",
    tier: LESSON_TIER.preferred,
    signedScore: 1.5,
    positiveMass: 1.5,
    negativeMass: 0,
    corroboration: 2,
    stance: null,
    lastOutcomeAt: "2026-05-01T00:00:00Z",
    ...overrides,
  };
}

function buildRow(prefId: string, overrides: Partial<LessonApprovalRow> = {}): LessonApprovalRow {
  return {
    prefId,
    decision: "approved",
    decidedAt: "2026-05-10T00:00:00Z",
    decidedBy: "yes-flag",
    approvedContentHash: computeContentHash(`principle for ${prefId}`, "backend"),
    targets: ["AGENTS.md"],
    blockId: RULES_BLOCK_ID.lessons,
    lastPromotedAt: null,
    ...overrides,
  };
}

function promoteCase(prefId: string): {
  pref: BrainPreference;
  lesson: LessonEntry;
  row: LessonApprovalRow;
} {
  return {
    pref: buildPref(prefId),
    lesson: buildLesson(prefId),
    row: buildRow(prefId),
  };
}

// ----- Qualification --------------------------------------------------------

describe("lessonPromotionCandidates", () => {
  test("the exact conjunction promotes, with the pinned candidate shape", () => {
    const { pref, lesson, row } = promoteCase("pref-fresh");
    const result = lessonPromotionCandidates([pref], [lesson], [row], {
      enabledScopes: ["backend"],
    });
    expect(result.promotable.length).toBe(1);
    const candidate: LessonPromotionCandidate = result.promotable[0]!;
    expect(candidate.prefId).toBe("pref-fresh");
    expect(candidate.principle).toBe("principle for pref-fresh");
    expect(candidate.scope).toBe("backend");
    expect(candidate.tier).toBe(LESSON_TIER.preferred);
    expect(candidate.confidence).toBe("high");
    expect(candidate.contentHash).toBe(computeContentHash("principle for pref-fresh", "backend"));
    expect(result.blocked).toEqual([]);
  });

  test("an unconfirmed or quarantined preference is blocked unconfirmed", () => {
    const { pref, lesson, row } = promoteCase("pref-un");
    for (const status of [
      BRAIN_PREFERENCE_STATUS.unconfirmed,
      BRAIN_PREFERENCE_STATUS.quarantine,
    ]) {
      const result = lessonPromotionCandidates([{ ...pref, status }], [lesson], [row], {
        enabledScopes: ["backend"],
      });
      expect(result.promotable).toEqual([]);
      expect(result.blocked).toEqual([
        { prefId: "pref-un", reason: LESSON_PROMOTION_BLOCKED.unconfirmed },
      ]);
    }
  });

  test("a preference without a scope, or outside the enabled scopes, is blocked scope_not_enabled", () => {
    const { pref, lesson, row } = promoteCase("pref-scope");
    for (const scope of [undefined, "frontend"]) {
      const result = lessonPromotionCandidates(
        [scope === undefined ? { ...pref, scope: undefined } : { ...pref, scope }],
        [scope === undefined ? { ...lesson, scope: null } : lesson],
        [row],
        { enabledScopes: ["backend"] },
      );
      expect(result.promotable).toEqual([]);
      expect(result.blocked).toEqual([
        { prefId: "pref-scope", reason: LESSON_PROMOTION_BLOCKED.scopeNotEnabled },
      ]);
    }
  });

  test("a medium- or low-confidence preference is blocked low_confidence", () => {
    const { pref, lesson, row } = promoteCase("pref-conf");
    for (const confidence of ["medium", "low"] as const) {
      const result = lessonPromotionCandidates([{ ...pref, confidence }], [lesson], [row], {
        enabledScopes: ["backend"],
      });
      expect(result.promotable).toEqual([]);
      expect(result.blocked).toEqual([
        { prefId: "pref-conf", reason: LESSON_PROMOTION_BLOCKED.lowConfidence },
      ]);
    }
  });

  test("a non-preferred tier, or a preference with no lesson yet, is blocked tier_not_preferred", () => {
    const { pref, lesson, row } = promoteCase("pref-tier");
    for (const tier of [LESSON_TIER.tentative, LESSON_TIER.contested, LESSON_TIER.avoid]) {
      const result = lessonPromotionCandidates([pref], [{ ...lesson, tier }], [row], {
        enabledScopes: ["backend"],
      });
      expect(result.promotable).toEqual([]);
      expect(result.blocked).toEqual([
        { prefId: "pref-tier", reason: LESSON_PROMOTION_BLOCKED.tierNotPreferred },
      ]);
    }
    // No lesson entry at all: the preference has not earned the tier.
    const noLesson = lessonPromotionCandidates([pref], [], [row], { enabledScopes: ["backend"] });
    expect(noLesson.promotable).toEqual([]);
    expect(noLesson.blocked).toEqual([
      { prefId: "pref-tier", reason: LESSON_PROMOTION_BLOCKED.tierNotPreferred },
    ]);
  });

  test("a preference with no approval row is blocked not_approved", () => {
    const { pref, lesson } = promoteCase("pref-norow");
    const result = lessonPromotionCandidates([pref], [lesson], [], {
      enabledScopes: ["backend"],
    });
    expect(result.promotable).toEqual([]);
    expect(result.blocked).toEqual([
      { prefId: "pref-norow", reason: LESSON_PROMOTION_BLOCKED.notApproved },
    ]);
  });

  test("a stale approval (content-hash mismatch) drops the lesson and reports stale_approval", () => {
    const { pref, lesson, row } = promoteCase("pref-stale");
    const drifted = lessonPromotionCandidates(
      [{ ...pref, principle: "principle for pref-stale, amended" }],
      [{ ...lesson, title: "principle for pref-stale, amended" }],
      [row],
      { enabledScopes: ["backend"] },
    );
    expect(drifted.promotable).toEqual([]);
    expect(drifted.blocked).toEqual([
      { prefId: "pref-stale", reason: LESSON_PROMOTION_BLOCKED.staleApproval },
    ]);
  });

  test("a denied row blocks by name, dominates the report, and suppresses a stale approval", () => {
    const { pref, lesson, row } = promoteCase("pref-denied");
    const denied = lessonPromotionCandidates([pref], [lesson], [{ ...row, decision: "denied" }], {
      enabledScopes: ["backend"],
    });
    expect(denied.promotable).toEqual([]);
    expect(denied.blocked).toEqual([
      { prefId: "pref-denied", reason: LESSON_PROMOTION_BLOCKED.denied },
    ]);
    // The operator's will dominates the report even beside other gates.
    const deniedAndUnconfirmed = lessonPromotionCandidates(
      [{ ...pref, status: BRAIN_PREFERENCE_STATUS.unconfirmed }],
      [lesson],
      [{ ...row, decision: "denied" }],
      { enabledScopes: ["backend"] },
    );
    expect(deniedAndUnconfirmed.blocked).toEqual([
      { prefId: "pref-denied", reason: LESSON_PROMOTION_BLOCKED.denied },
    ]);
  });

  test("every input preference is classified exactly once, with a closed-set reason", () => {
    const fresh = promoteCase("pref-a");
    const staleRow = buildRow("pref-b", {
      approvedContentHash: "stale-hash-value-that-matches-nothing",
    });
    const prefs = [fresh.pref, buildPref("pref-b"), buildPref("pref-c")];
    const lessons = [
      fresh.lesson,
      buildLesson("pref-b", { tier: LESSON_TIER.tentative }),
      buildLesson("pref-c"),
    ];
    const approvals = [fresh.row, staleRow];
    const result = lessonPromotionCandidates(prefs, lessons, approvals, {
      enabledScopes: ["backend"],
    });
    expect(result.promotable.map((c) => c.prefId)).toEqual(["pref-a"]);
    expect(result.blocked.map((b) => b.prefId).toSorted()).toEqual(["pref-b", "pref-c"]);
    const members = new Set(Object.values(LESSON_PROMOTION_BLOCKED));
    for (const blocked of result.blocked) {
      expect(members.has(blocked.reason)).toBe(true);
    }
    expect(result.blocked.find((b) => b.prefId === "pref-b")?.reason).toBe(
      LESSON_PROMOTION_BLOCKED.tierNotPreferred,
    );
    expect(result.blocked.find((b) => b.prefId === "pref-c")?.reason).toBe(
      LESSON_PROMOTION_BLOCKED.notApproved,
    );
  });

  test("dead-end lessons never promote: only preference entries match", () => {
    const deadEnd: LessonEntry = buildLesson("de-2026-05-01-fail", {
      kind: "dead-end",
      tier: LESSON_TIER.avoid,
      scope: null,
    });
    const result = lessonPromotionCandidates([], [deadEnd], [], { enabledScopes: ["backend"] });
    expect(result.promotable).toEqual([]);
    expect(result.blocked).toEqual([]);
  });
});

// ----- Render ---------------------------------------------------------------

describe("renderLessonsBlockBody", () => {
  test("identical inputs produce identical bytes", () => {
    const a = promoteCase("pref-x");
    const b = promoteCase("pref-y");
    const input = [a, b].map((c) => ({
      prefId: c.pref.id,
      principle: c.pref.principle,
      scope: c.pref.scope ?? "",
      tier: c.lesson.tier,
      confidence: c.pref.confidence,
      contentHash: c.row.approvedContentHash,
    }));
    expect(renderLessonsBlockBody(input)).toBe(renderLessonsBlockBody(input));
  });

  test("orders by tier, then scope, then id, with no timestamps", () => {
    const candidates: LessonPromotionCandidate[] = [
      {
        prefId: "pref-zeta",
        principle: "zeta rule",
        scope: "backend",
        tier: LESSON_TIER.preferred,
        confidence: "high",
        contentHash: "hash-zeta-000000000000000000000000000000000000000000000000",
      },
      {
        prefId: "pref-alpha",
        principle: "alpha rule",
        scope: "testing",
        tier: LESSON_TIER.preferred,
        confidence: "high",
        contentHash: "hash-alpha-00000000000000000000000000000000000000000000000",
      },
      {
        prefId: "pref-beta",
        principle: "beta rule",
        scope: "backend",
        tier: LESSON_TIER.preferred,
        confidence: "high",
        contentHash: "hash-beta-0000000000000000000000000000000000000000000000000",
      },
    ];
    const body = renderLessonsBlockBody(candidates);
    const lines = body.split("\n").filter((line) => line.startsWith("- `pref-"));
    expect(lines.map((line) => line.match(/`([^`]+)`/)?.[1])).toEqual([
      "pref-beta", // scope backend before testing, id order within scope
      "pref-zeta",
      "pref-alpha",
    ]);
    // No timestamp can appear in a deterministic body.
    expect(body).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
  });

  test("the limit caps the render in order; non-positive or fractional limits refuse by name", () => {
    const candidates: LessonPromotionCandidate[] = ["a", "b", "c"].map((suffix) => ({
      prefId: `pref-${suffix}`,
      principle: `rule ${suffix}`,
      scope: "backend",
      tier: LESSON_TIER.preferred,
      confidence: "high",
      contentHash: `hash-${suffix}`,
    }));
    const capped = renderLessonsBlockBody(candidates, { limit: 2 });
    expect(capped.split("\n").filter((line) => line.startsWith("- `pref-")).length).toBe(2);
    expect(capped).toContain("pref-a");
    expect(capped).toContain("pref-b");
    expect(capped).not.toContain("pref-c");
    for (const limit of [0, -1, 1.5]) {
      expect(() => renderLessonsBlockBody(candidates, { limit })).toThrow(RangeError);
    }
  });

  test("the drops render names the lessons the limit cut, in render order", () => {
    const candidates: LessonPromotionCandidate[] = ["a", "b", "c"].map((suffix) => ({
      prefId: `pref-${suffix}`,
      principle: `rule ${suffix}`,
      scope: "backend",
      tier: LESSON_TIER.preferred,
      confidence: "high",
      contentHash: `hash-${suffix}`,
    }));
    const rendered = renderLessonsBlockWithDrops(candidates, { limit: 2 });
    // The body is exactly what the plain render produces.
    expect(rendered.body).toBe(renderLessonsBlockBody(candidates, { limit: 2 }));
    // The cut is named, not silent: the lesson past the cap is reported.
    expect(rendered.droppedIds).toEqual(["pref-c"]);
    // Under the cap everything renders and nothing is dropped.
    expect(renderLessonsBlockWithDrops(candidates).droppedIds).toEqual([]);
    expect(renderLessonsBlockWithDrops(candidates, { limit: 3 }).droppedIds).toEqual([]);
  });

  test("an empty promotable set is a named refusal: removal is the writer's job", () => {
    expect(() => renderLessonsBlockBody([])).toThrow(/remove/i);
  });

  test("multi-line principles collapse to one line", () => {
    const body = renderLessonsBlockBody([
      {
        prefId: "pref-multi",
        principle: "first line\nsecond line",
        scope: "backend",
        tier: LESSON_TIER.preferred,
        confidence: "high",
        contentHash: "hash-multi",
      },
    ]);
    expect(body.split("\n").filter((line) => line.startsWith("- `pref-")).length).toBe(1);
    expect(body).toContain("first line second line");
  });

  test("the lessons body satisfies no usage-block clause and carries no usage marker", () => {
    const body = renderLessonsBlockBody([
      {
        prefId: "pref-ind",
        principle: "an approved rule",
        scope: "backend",
        tier: LESSON_TIER.preferred,
        confidence: "high",
        contentHash: "hash-ind",
      },
    ]);
    // The blocks are independent: the lessons body satisfies none of the
    // usage block's gate clauses, and carries none of its marker spellings.
    expect(missingWritebackGateClauses(body).length).toBe(WRITEBACK_CONTRACT_REQUIREMENTS.length);
    expect(body).not.toContain(DEFAULT_BEGIN_MARKER);
    expect(body).not.toContain(DEFAULT_END_MARKER);
    expect(RULES_BLOCK_MARKERS.lessons.begin).not.toBe(RULES_BLOCK_MARKERS.usage.begin);
  });

  test("a scope carrying a line break refuses the render by name (marker forgery attempt)", () => {
    // A multi-line scope (a YAML block scalar in agent-authored
    // frontmatter) could carry a whole-line lessons end marker and brick
    // every later lessons-block operation. The render refuses the lesson
    // instead of emitting it.
    const forged: LessonPromotionCandidate = {
      prefId: "pref-forge",
      principle: "an approved rule",
      scope: `backend\n${RULES_BLOCK_MARKERS.lessons.end}`,
      tier: LESSON_TIER.preferred,
      confidence: "high",
      contentHash: "hash-forge",
    };
    let thrown: unknown = null;
    try {
      renderLessonsBlockBody([forged]);
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(LessonRenderError);
    const err = thrown as InstanceType<typeof LessonRenderError>;
    expect(err.prefId).toBe("pref-forge");
    expect(err.field).toBe("scope");
    expect(err.message).toContain("pref-forge");
    expect(err.message).not.toMatch(/\n/);
  });

  test("a scope carrying a marker string on one line refuses the render too", () => {
    const shaped: LessonPromotionCandidate = {
      prefId: "pref-shape",
      principle: "an approved rule",
      scope: RULES_BLOCK_MARKERS.lessons.end,
      tier: LESSON_TIER.preferred,
      confidence: "high",
      contentHash: "hash-shape",
    };
    expect(() => renderLessonsBlockBody([shaped])).toThrow(LessonRenderError);
    // Every spelling is checked, not just the lessons pair.
    const usageShaped: LessonPromotionCandidate = {
      ...shaped,
      prefId: "pref-usage-shape",
      scope: DEFAULT_BEGIN_MARKER,
    };
    expect(() => renderLessonsBlockBody([usageShaped])).toThrow(LessonRenderError);
  });

  test("a pref id carrying whitespace or a backtick refuses the render by name", () => {
    const base: LessonPromotionCandidate = {
      prefId: "pref-ok",
      principle: "an approved rule",
      scope: "backend",
      tier: LESSON_TIER.preferred,
      confidence: "high",
      contentHash: "hash-ok",
    };
    for (const prefId of ["pref-two words", "pref-new\nline", "pref-`backtick`"]) {
      let thrown: unknown = null;
      try {
        renderLessonsBlockBody([{ ...base, prefId }]);
      } catch (err) {
        thrown = err;
      }
      expect(thrown).toBeInstanceOf(LessonRenderError);
      const err = thrown as InstanceType<typeof LessonRenderError>;
      expect(err.field).toBe("prefId");
    }
  });

  test("a single-line scope with inner spaces still renders", () => {
    const body = renderLessonsBlockBody([
      {
        prefId: "pref-space",
        principle: "an approved rule",
        scope: "code review",
        tier: LESSON_TIER.preferred,
        confidence: "high",
        contentHash: "hash-space",
      },
    ]);
    expect(body).toContain("(scope: code review)");
  });
});

// ----- Approvals ledger -----------------------------------------------------

let tmp: string;
let vault: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-lessons-promotion-"));
  vault = join(tmp, "vault");
  mkdirSync(vault, { recursive: true });
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

describe("lesson approvals ledger", () => {
  test("the ledger lives in the derived store, never under Brain/", () => {
    const path = lessonsApprovalsPath(vault);
    expect(path).toContain(join(".open-second-brain", LESSONS_APPROVALS_FILE));
    expect(path).not.toContain("Brain");
    expect(LESSONS_APPROVALS_FILE).toBe("lessons-approvals.json");
  });

  test("record then read round-trips the row atomically", () => {
    const { row } = promoteCase("pref-ledger");
    recordLessonApproval(vault, row);
    expect(readLessonApprovals(vault)).toEqual([row]);
    const dir = join(vault, ".open-second-brain");
    expect(existsSync(join(dir, LESSONS_APPROVALS_FILE))).toBe(true);
    // Atomic write discipline: no temp leftovers beside the ledger.
    const leftovers = readdirSync(dir).filter((name) => name.startsWith(LESSONS_APPROVALS_FILE));
    expect(leftovers).toEqual([LESSONS_APPROVALS_FILE]);
  });

  test("a second decision for the same id replaces the row (state table, not history)", () => {
    const { row } = promoteCase("pref-twice");
    recordLessonApproval(vault, row);
    recordLessonApproval(vault, buildRow("pref-other"));
    recordLessonApproval(vault, { ...row, decision: "denied", decidedBy: "interactive-yes" });
    const rows = readLessonApprovals(vault);
    expect(rows.length).toBe(2);
    const twice = rows.find((r) => r.prefId === "pref-twice");
    expect(twice?.decision).toBe("denied");
    expect(twice?.decidedBy).toBe("interactive-yes");
  });

  test("reads are sorted by pref id, so identical states are byte-identical files", () => {
    recordLessonApproval(vault, buildRow("pref-z"));
    recordLessonApproval(vault, buildRow("pref-a"));
    const rows = readLessonApprovals(vault);
    expect(rows.map((r) => r.prefId)).toEqual(["pref-a", "pref-z"]);
    const bytes = readFileSync(lessonsApprovalsPath(vault), "utf8");
    expect(bytes.indexOf("pref-a")).toBeGreaterThan(-1);
    expect(bytes.indexOf("pref-a")).toBeLessThan(bytes.indexOf("pref-z"));
  });

  test("a missing ledger reads as empty", () => {
    expect(readLessonApprovals(vault)).toEqual([]);
  });

  test("corrupt JSON, an unknown schema version and a damaged row refuse by name", () => {
    const { row } = promoteCase("pref-corrupt");
    recordLessonApproval(vault, row);
    const path = lessonsApprovalsPath(vault);
    const original = readFileSync(path, "utf8");
    const patterns: ReadonlyArray<RegExp> = [/corrupted/, /schema_version/, /decision/];
    const mutations: ReadonlyArray<string> = [
      original.replaceAll("{", "{broken"),
      original.replace('"schema_version": 1', '"schema_version": 99'),
      original.replace('"decision": "approved"', '"decision": "maybe"'),
    ];
    for (let i = 0; i < mutations.length; i++) {
      writeFileSync(path, mutations[i]!);
      let message = "";
      try {
        readLessonApprovals(vault);
      } catch (err) {
        message = (err as Error).message;
      }
      expect(`${i}: matched: ${patterns[i]!.test(message)}`).toBe(`${i}: matched: true`);
      expect(message).toContain(path);
    }
    // The ledger survives untouched for the operator to repair by hand.
    writeFileSync(path, original);
    expect(readLessonApprovals(vault).length).toBe(1);
  });

  test("markLessonPromoted stamps the row, and a missing row refuses by name", () => {
    const { row } = promoteCase("pref-promoted");
    recordLessonApproval(vault, row);
    markLessonPromoted(vault, "pref-promoted", NOW);
    const rows = readLessonApprovals(vault);
    expect(rows[0]?.lastPromotedAt).toBe("2026-05-20T12:00:00Z");
    expect(() => markLessonPromoted(vault, "pref-absent", NOW)).toThrow(/pref-absent/);
  });
});

// ----- Config resolution ----------------------------------------------------

describe("resolveLessonsPromotionScopes", () => {
  const ENV_KEY = "OPEN_SECOND_BRAIN_LESSONS_PROMOTION_SCOPES";
  let savedEnv: string | undefined;

  beforeEach(() => {
    savedEnv = process.env[ENV_KEY];
    delete process.env[ENV_KEY];
  });

  afterEach(() => {
    if (savedEnv === undefined) delete process.env[ENV_KEY];
    else process.env[ENV_KEY] = savedEnv;
  });

  test("the pinned config key is exported from the kernel", () => {
    expect(LESSONS_PROMOTION_SCOPES_CONFIG_KEY).toBe("lessons.promotion.scopes");
  });

  test("absent-or-empty resolves to a named count of zero (promotion disabled)", () => {
    const resolution = resolveLessonsPromotionScopes();
    expect(resolution.scopes).toEqual([]);
    expect(resolution.count).toBe(0);
    expect(resolution.origin).toBe("absent");
  });

  test("the env twin wins and parses a comma-separated list", () => {
    process.env[ENV_KEY] = "backend, testing ,, frontend";
    const resolution = resolveLessonsPromotionScopes();
    expect(resolution.scopes).toEqual(["backend", "testing", "frontend"]);
    expect(resolution.count).toBe(3);
    expect(resolution.origin).toBe("env");
  });

  test("a bracket-shaped value is malformed and resolves disabled", () => {
    process.env[ENV_KEY] = "[backend, testing]";
    const resolution = resolveLessonsPromotionScopes();
    expect(resolution.count).toBe(0);
    expect(resolution.origin).toBe("absent");
  });

  test("a present-but-malformed scopes value is a named refusal at the kernel boundary", () => {
    // The policy block's resolver keeps its documented fallback; the
    // kernel wrapper - which every promotion caller reads - refuses a
    // value that is PRESENT but malformed, so an operator can tell
    // "configured wrong" from "never configured".
    process.env[ENV_KEY] = "[backend, testing]";
    let thrown: unknown = null;
    try {
      resolvePromotionScopesStrict();
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(LessonsPromotionScopesMalformedError);
    const err = thrown as InstanceType<typeof LessonsPromotionScopesMalformedError>;
    expect(err.source).toBe("env");
    expect(err.message).toContain(ENV_KEY);
    expect(err.message).toContain("malformed");
    expect(err.message).toContain("promotion stays disabled");
    expect(err.message).not.toMatch(/\n/);
    // The config layer refuses by name the same way.
    delete process.env[ENV_KEY];
    let configThrown: unknown = null;
    try {
      resolvePromotionScopesStrict(join(tmp, "missing-config.yaml"));
    } catch (configError) {
      configThrown = configError;
    }
    // No config file exists here, so the config arm stays silent and the
    // resolution is the plain disabled one - the refusal above is the
    // malformed case, not a missing-file case.
    expect(configThrown).toBeNull();
  });
});

// ----- Log event kinds ------------------------------------------------------

describe("lessons log event kinds", () => {
  test("the three kinds append through the shared chain and read back", () => {
    const kinds = [
      BRAIN_LOG_EVENT_KIND.lessonsApproved,
      BRAIN_LOG_EVENT_KIND.lessonsDenied,
      BRAIN_LOG_EVENT_KIND.lessonsPromoted,
    ];
    for (const kind of kinds) {
      appendLogEvent(
        vault,
        {
          eventType: kind,
          timestamp: "2026-05-20T12:00:00Z",
          agent: "test-agent",
          body: { pref: "[[pref-x]]" },
        },
        { deviceId: "" },
      );
    }
    const dates = listLogDates(vault);
    expect(dates.length).toBe(1);
    const day = readLogDay(vault, dates[0]!);
    expect(day.entries.map((e) => e.eventType)).toEqual(kinds);
  });

  test("the kind spellings are pinned", () => {
    expect(BRAIN_LOG_EVENT_KIND.lessonsApproved).toBe("lessons-approved");
    expect(BRAIN_LOG_EVENT_KIND.lessonsDenied).toBe("lessons-denied");
    expect(BRAIN_LOG_EVENT_KIND.lessonsPromoted).toBe("lessons-promoted");
  });
});

// ----- Writer routing -------------------------------------------------------

describe("writer routing", () => {
  test("the kernel never imports node:fs write functions; rules writes ride the K1 writer", () => {
    const source = readFileSync(
      join(import.meta.dir, "..", "..", "..", "src", "core", "brain", "lessons-promotion.ts"),
      "utf8",
    );
    expect(source).toMatch(/from "node:fs"/);
    // Read-only fs names only; every write-shaped name is absent.
    for (const banned of [
      "writeFileSync",
      "appendFileSync",
      "writeSync",
      "openSync",
      "renameSync",
      "unlinkSync",
      "rmSync",
      "insertManagedBlock",
    ]) {
      expect(`${banned}: ${new RegExp(`\\b${banned}\\b`).test(source)}`).toBe(`${banned}: false`);
    }
    expect(source).toContain("atomicWriteFileSync");
  });
});

// ----- Block body ids (t_1e952e43 C3: the doctor and the verb read back
// which lessons a managed block carries; the parser lives beside the
// render so the format coupling stays in one module) ------------------------

describe("lessonIdsInBlockBody", () => {
  test("extracts the pref ids a rendered body carries, in render order", () => {
    const prefs = [buildPref("pref-b"), buildPref("pref-a")];
    const lessons = [buildLesson("pref-b"), buildLesson("pref-a")];
    const rows = [buildRow("pref-b"), buildRow("pref-a")];
    const { promotable } = lessonPromotionCandidates(prefs, lessons, rows, {
      enabledScopes: ["backend"],
    });
    const body = renderLessonsBlockBody(promotable, { limit: 20 });
    // Same scope and tier, so the render order is the id order.
    expect(lessonIdsInBlockBody(body)).toEqual(["pref-a", "pref-b"]);
  });

  test("a body with no lesson lines yields no ids", () => {
    expect(lessonIdsInBlockBody("# house rules\n")).toEqual([]);
    expect(lessonIdsInBlockBody("- not a lesson line\n- `unterminated\n")).toEqual([]);
  });
});