wednesdayai 0.4.12-dev.715 → 0.4.12-dev.717

package/extensions/learning-core/src/lesson-store-conformance.test-helpers.ts

@@ -0,0 +1,1406 @@
+import crypto from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { isLearningDomainError } from "./errors.js";
+import { withCandidateDefaults } from "./extraction-candidate.js";
+import { withLessonDefaults } from "./lesson-record.js";
+import type { ExtractionCandidate, LearningLesson, LessonStore, SkillProposal } from "./types.js";
+
+// The LessonStore conformance contract, written once and registered per backend leg:
+// lesson-store-conformance.test.ts runs the fs-jsonl, sqlite and in-memory-double legs in the
+// default lanes; lesson-store-conformance.pg.integration.test.ts runs the live-server leg
+// (`pnpm test:pg`).
+
+export type StoreScope = { workspaceId?: string; agentId?: string };
+export type MakeStore = (scope: StoreScope) => Promise<LessonStore>;
+
+export type Backend = {
+  // The backend identity describeBackend() must report. Two entries may share it: the postgres
+  // store is run against both a live server and the in-memory double.
+  name: "fs-jsonl" | "sqlite" | "postgres";
+  // How this leg is named in the suite title.
+  label: string;
+  make: MakeStore;
+  // Raw backing rows (or log bytes), for byte-identity assertions that bypass the store.
+  snapshot: () => Promise<string>;
+  // This backend's evidence that searchLessons is index-backed (fs-jsonl: reduced capability).
+  assertSearchIndex: (store: LessonStore) => Promise<void>;
+};
+
+// Every workspaceId this suite writes carries the run id, so two concurrent runs against one
+// shared OPENCLAW_DB_URL can neither read nor delete each other's rows
+// (mirrors TEST_SESSION_ID in primary-mode-postgres.pg.integration.test.ts).
+// A pid is unique only among LIVE processes on ONE host: two CI shards, two machines against one
+// shared server, or a later run after pid reuse all collide -- and this suite DELETEs by prefix
+// and DROPs its schema, so a collision is destructive, not merely flaky.
+const RUN_TOKEN = crypto.randomUUID().replaceAll("-", "");
+export const RUN_ID = `test_${RUN_TOKEN}`;
+function ws(name: string): string {
+  return `${RUN_ID}_${name}`;
+}
+
+// `schema` is REQUIRED on PostgresLessonStore; a run-unique name keeps concurrent runs apart.
+export const TEST_SCHEMA = `plugin_learning_core_test_${RUN_TOKEN}`;
+export const PG_TABLE = `${TEST_SCHEMA}.learning_records`;
+
+const EXPECTED_CAPABILITY: Record<Backend["name"], "full" | "reduced"> = {
+  "fs-jsonl": "reduced",
+  sqlite: "full",
+  postgres: "full",
+};
+
+// --- Assertion helpers: written ONCE against LessonStore, run for every backend ---
+
+async function assertRoundTripsLesson(make: MakeStore) {
+  const scope = { agentId: "a1", workspaceId: ws("roundtrip") };
+  const store = await make(scope);
+
+  const lesson: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-roundtrip",
+      scope,
+      kind: "procedure",
+      text: "Do X when Y happens.",
+      confidence: 0.9,
+      occurrences: 1,
+      distinctSessionIds: ["session-1"],
+      evidence: [
+        {
+          sessionId: "session-1",
+          observedAt: "2026-05-24T10:00:00.000Z",
+          summary: "Observed in production.",
+        },
+      ],
+      createdAt: "2026-05-24T10:00:00.000Z",
+      updatedAt: "2026-05-24T10:00:00.000Z",
+    },
+    "2026-05-24T10:00:00.000Z",
+  );
+
+  await store.upsertLesson(lesson);
+  const retrieved = await store.getLesson("lesson-roundtrip");
+
+  expect(retrieved, "round-trip must preserve every lifecycle field").toEqual(lesson);
+}
+
+// The legacy read-through seeds with this: a row another writer already holds (with its distill
+// flags or its invalid_at) must never be overwritten by a stale legacy copy.
+async function assertInsertLessonIfAbsentNeverOverwrites(make: MakeStore) {
+  const scope = { agentId: "a1", workspaceId: ws("insert-if-absent") };
+  const store = await make(scope);
+  const at = "2026-05-24T10:00:00.000Z";
+  const lesson: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-seed",
+      scope,
+      kind: "procedure",
+      text: "Seed me.",
+      confidence: 0.9,
+      occurrences: 1,
+      distinctSessionIds: ["session-1"],
+      evidence: [],
+      createdAt: at,
+      updatedAt: at,
+    },
+    at,
+  );
+  await store.insertLessonIfAbsent(lesson);
+  expect(await store.getLesson("lesson-seed")).toEqual(lesson);
+  const live = { ...lesson, proposed: true, invalidAt: "2026-05-25T00:00:00.000Z" };
+  await store.upsertLesson(live);
+  await store.insertLessonIfAbsent(lesson);
+  expect(await store.getLesson("lesson-seed")).toEqual(live);
+}
+
+async function assertUpsertIsIdempotent(make: MakeStore) {
+  const scope = { agentId: "a2", workspaceId: ws("idempotent") };
+  const store = await make(scope);
+
+  const lesson: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-idempotent",
+      scope,
+      kind: "failure",
+      text: "Handle error code E_NOENT.",
+      confidence: 0.8,
+      occurrences: 1,
+      distinctSessionIds: ["session-2"],
+      evidence: [
+        {
+          sessionId: "session-2",
+          observedAt: "2026-05-24T11:00:00.000Z",
+          summary: "Error trace logged.",
+        },
+      ],
+      createdAt: "2026-05-24T11:00:00.000Z",
+      updatedAt: "2026-05-24T11:00:00.000Z",
+    },
+    "2026-05-24T11:00:00.000Z",
+  );
+
+  await store.upsertLesson(lesson);
+  await store.upsertLesson(lesson);
+
+  const all = await store.listLessons();
+  expect(all, "a second upsert of the same id must not duplicate the row").toHaveLength(1);
+  expect(all[0]).toEqual(lesson);
+}
+
+export async function assertScopeIsolation(make: MakeStore) {
+  const scopeA = { agentId: "a1", workspaceId: ws("w1") };
+  const scopeB = { agentId: "a2", workspaceId: ws("w2") };
+  const storeW1A1 = await make(scopeA);
+  const storeW2A2 = await make(scopeB);
+
+  const lessonW1A1: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-scope-1",
+      scope: scopeA,
+      kind: "procedure",
+      text: "Scoped lesson 1.",
+      confidence: 0.7,
+      occurrences: 1,
+      distinctSessionIds: ["sess-1"],
+      evidence: [
+        {
+          sessionId: "sess-1",
+          observedAt: "2026-05-24T12:00:00.000Z",
+          summary: "In w1/a1.",
+        },
+      ],
+      createdAt: "2026-05-24T12:00:00.000Z",
+      updatedAt: "2026-05-24T12:00:00.000Z",
+    },
+    "2026-05-24T12:00:00.000Z",
+  );
+
+  await storeW1A1.upsertLesson(lessonW1A1);
+
+  const visibleToW2A2 = await storeW2A2.listLessons();
+  const found = visibleToW2A2.find((l) => l.id === lessonW1A1.id);
+  // The message names the offending scope so the mutation self-check can match on it instead of
+  // on whatever object vitest happens to dump.
+  expect(
+    found,
+    `scope isolation violated: w2 (${scopeB.workspaceId}/${scopeB.agentId}) can read ${lessonW1A1.id}, written under ${scopeA.workspaceId}/${scopeA.agentId}`,
+  ).toBeUndefined();
+}
+
+// assertScopeIsolation varies workspace AND agent together, so a store that filters on only ONE of
+// the two columns still passes it. This holds each dimension constant in turn, so dropping either
+// predicate is caught. (Found by mutating PostgresLessonStore.scopeFilter to skip agent_id: the
+// combined-scope assertion above stayed green.)
+async function assertScopeIsolationPerDimension(make: MakeStore) {
+  const workspaceId = ws("dim");
+
+  function lessonAt(id: string, scope: StoreScope): LearningLesson {
+    return withLessonDefaults(
+      {
+        id,
+        scope,
+        kind: "procedure",
+        text: `Lesson ${id}.`,
+        confidence: 0.7,
+        occurrences: 1,
+        distinctSessionIds: ["sess-dim"],
+        evidence: [
+          { sessionId: "sess-dim", observedAt: "2026-05-24T12:00:00.000Z", summary: "dim." },
+        ],
+        createdAt: "2026-05-24T12:00:00.000Z",
+        updatedAt: "2026-05-24T12:00:00.000Z",
+      },
+      "2026-05-24T12:00:00.000Z",
+    );
+  }
+
+  // Same workspace, different agent — only the agent_id predicate can separate these.
+  const agentA = { workspaceId, agentId: "dim-a1" };
+  const agentB = { workspaceId, agentId: "dim-a2" };
+  await (await make(agentA)).upsertLesson(lessonAt("lesson-dim-agent", agentA));
+  const seenByOtherAgent = (await (await make(agentB)).listLessons()).find(
+    (l) => l.id === "lesson-dim-agent",
+  );
+  expect(
+    seenByOtherAgent,
+    `agent isolation violated: agent ${agentB.agentId} can read a lesson written by ${agentA.agentId} in the SAME workspace ${workspaceId}`,
+  ).toBeUndefined();
+
+  // Same agent, different workspace — only the workspace_id predicate can separate these.
+  const wsA = { workspaceId: ws("dim-w1"), agentId: "dim-shared" };
+  const wsB = { workspaceId: ws("dim-w2"), agentId: "dim-shared" };
+  await (await make(wsA)).upsertLesson(lessonAt("lesson-dim-workspace", wsA));
+  const seenByOtherWorkspace = (await (await make(wsB)).listLessons()).find(
+    (l) => l.id === "lesson-dim-workspace",
+  );
+  expect(
+    seenByOtherWorkspace,
+    `workspace isolation violated: workspace ${wsB.workspaceId} can read a lesson written in ${wsA.workspaceId} by the SAME agent ${wsA.agentId}`,
+  ).toBeUndefined();
+}
+
+async function assertEmptyScopeReadsAcrossScopes(make: MakeStore) {
+  const scopeA = { agentId: "a1", workspaceId: ws("cross") };
+  const storeW1A1 = await make(scopeA);
+  const storeEmptyScope = await make({});
+
+  const lessonW1A1: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-cross-scope",
+      scope: scopeA,
+      kind: "procedure",
+      text: "Lesson visible across scopes.",
+      confidence: 0.75,
+      occurrences: 1,
+      distinctSessionIds: ["sess-2"],
+      evidence: [
+        {
+          sessionId: "sess-2",
+          observedAt: "2026-05-24T13:00:00.000Z",
+          summary: "Cross-scope test.",
+        },
+      ],
+      createdAt: "2026-05-24T13:00:00.000Z",
+      updatedAt: "2026-05-24T13:00:00.000Z",
+    },
+    "2026-05-24T13:00:00.000Z",
+  );
+
+  await storeW1A1.upsertLesson(lessonW1A1);
+
+  const allLessons = await storeEmptyScope.listLessons();
+  expect(
+    allLessons.find((l) => l.id === lessonW1A1.id),
+    "an empty scope must read across every scope",
+  ).toBeDefined();
+}
+
+async function assertSupersedeRetainsPredecessor(make: MakeStore) {
+  const scope = { agentId: "a3", workspaceId: ws("supersede") };
+  const store = await make(scope);
+
+  const predecessor: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-v1",
+      scope,
+      kind: "procedure",
+      text: "Old approach.",
+      confidence: 0.6,
+      occurrences: 1,
+      distinctSessionIds: ["sess-3"],
+      evidence: [
+        {
+          sessionId: "sess-3",
+          observedAt: "2026-05-24T14:00:00.000Z",
+          summary: "Original approach.",
+        },
+      ],
+      createdAt: "2026-05-24T14:00:00.000Z",
+      updatedAt: "2026-05-24T14:00:00.000Z",
+    },
+    "2026-05-24T14:00:00.000Z",
+  );
+
+  await store.upsertLesson(predecessor);
+
+  const successor: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-v2",
+      scope,
+      kind: "procedure",
+      text: "New improved approach.",
+      confidence: 0.9,
+      occurrences: 1,
+      distinctSessionIds: ["sess-3"],
+      evidence: [
+        {
+          sessionId: "sess-3",
+          observedAt: "2026-05-24T14:15:00.000Z",
+          summary: "Improved version.",
+        },
+      ],
+      createdAt: "2026-05-24T14:15:00.000Z",
+      updatedAt: "2026-05-24T14:15:00.000Z",
+    },
+    "2026-05-24T14:15:00.000Z",
+  );
+
+  const result = await store.supersedeLesson({
+    predecessorId: "lesson-v1",
+    successor,
+    now: "2026-05-24T14:15:00.000Z",
+  });
+
+  expect(result.supersedesId).toBe("lesson-v1");
+
+  const pred = await store.getLesson("lesson-v1");
+  expect(pred, "supersede must retain the predecessor").toBeDefined();
+  expect(pred?.invalidAt, "the predecessor must carry invalid_at").toBe("2026-05-24T14:15:00.000Z");
+
+  const succ = await store.getLesson("lesson-v2");
+  expect(succ?.supersedesId, "the successor must link back to the predecessor").toBe("lesson-v1");
+}
+
+// A successor sharing the predecessor's id would overwrite the same primary key with a row whose
+// supersedesId points at itself, and every later getLessonChain would throw "cycle detected" -- an
+// unrecoverable break in the provenance guarantee. The tool derives the successor id by hashing the
+// text, so identical text reaches this path from a real operator action, not just a bad caller.
+// The ordering contract. Backends store records in different physical layouts (append-only log
+// position, SQLite rowid, a Postgres heap row), and an UPDATE perturbs each layout differently:
+// `INSERT OR REPLACE` mints a new rowid, the log's dedup keeps the newest globalSeq, while a real
+// `ON CONFLICT DO UPDATE` leaves the row where it was. Ordering therefore has to be stated on the
+// data (createdAt, id tiebreak), not inherited from storage. gateway-methods.ts hands list output
+// straight to the operator with no sort, so a divergence here is directly user-visible.
+//
+// The update must target the EARLIER record, after the later one exists. Updating the most recent
+// record leaves it last under every layout, so the assertion would pass on all three backends while
+// the divergence was fully present.
+async function assertUpdateDoesNotReorder(make: MakeStore) {
+  const scope = { agentId: "a4order", workspaceId: ws("order") };
+  const store = await make(scope);
+  const early = "2026-05-24T09:00:00.000Z";
+  const late = "2026-05-24T17:00:00.000Z";
+
+  function at(
+    id: string,
+    createdAt: string,
+    text: string,
+    evidence: LearningLesson["evidence"] = [],
+  ): LearningLesson {
+    return withLessonDefaults(
+      {
+        id,
+        scope,
+        kind: "procedure",
+        text,
+        confidence: 0.7,
+        occurrences: 1,
+        distinctSessionIds: ["sess-order"],
+        evidence,
+        createdAt,
+        updatedAt: createdAt,
+      },
+      createdAt,
+    );
+  }
+
+  await store.upsertLesson(at("lesson-early", early, "first"));
+  await store.upsertLesson(at("lesson-late", late, "second"));
+  expect((await store.listLessons()).map((l) => l.id)).toEqual(["lesson-early", "lesson-late"]);
+
+  // The merge must genuinely MUTATE the record. mergeLessons ignores candidate.text and derives
+  // every change from candidate.evidence, so a candidate with no new evidence is a no-op: the
+  // fs-jsonl store emits no delta, appends nothing, and the list cannot reorder — the assertion
+  // below would then pass on every backend with the sort removed. Supplying unseen evidence is what
+  // makes this leg able to fail.
+  await store.mergeLesson(
+    at("lesson-early", early, "first", [
+      { sessionId: "sess-order-2", observedAt: late, summary: "a later observation" },
+    ]),
+  );
+
+  expect(
+    (await store.listLessons()).map((l) => l.id),
+    "updating the EARLIER lesson must not move it in the list",
+  ).toEqual(["lesson-early", "lesson-late"]);
+}
+
+async function assertSupersedeRejectsSelfReference(make: MakeStore) {
+  const scope = { agentId: "a3self", workspaceId: ws("supersede-self") };
+  const store = await make(scope);
+  const now = "2026-05-24T14:15:00.000Z";
+
+  await store.upsertLesson(
+    withLessonDefaults(
+      {
+        id: "lesson-self",
+        scope,
+        kind: "correction",
+        text: "original",
+        confidence: 0.9,
+        occurrences: 1,
+        distinctSessionIds: ["sess-self"],
+        evidence: [],
+        createdAt: now,
+        updatedAt: now,
+      },
+      now,
+    ),
+  );
+
+  await expect(
+    store.supersedeLesson({
+      predecessorId: "lesson-self",
+      successor: withLessonDefaults(
+        {
+          id: "lesson-self",
+          scope,
+          kind: "correction",
+          text: "original",
+          confidence: 0.9,
+          occurrences: 1,
+          distinctSessionIds: ["sess-self"],
+          evidence: [],
+          createdAt: now,
+          updatedAt: now,
+        },
+        now,
+      ),
+      now,
+    }),
+    "a successor sharing the predecessor id must be refused, not written",
+  ).rejects.toThrow(/must differ from the predecessor/);
+
+  // The refusal must leave the predecessor untouched -- a partial write is the corruption itself.
+  const pred = await store.getLesson("lesson-self");
+  expect(
+    pred?.invalidAt,
+    "the refused supersede must not have closed the predecessor",
+  ).toBeUndefined();
+  expect(
+    pred?.supersedesId,
+    "the refused supersede must not have self-linked the record",
+  ).toBeUndefined();
+  await expect(
+    store.getLessonChain("lesson-self"),
+    "the chain must still be readable after the refusal",
+  ).resolves.toBeDefined();
+}
+
+async function assertActiveListExcludesInvalidated(make: MakeStore) {
+  const scope = { agentId: "a4", workspaceId: ws("active") };
+  const store = await make(scope);
+
+  const lesson: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-active",
+      scope,
+      kind: "preference",
+      text: "Active lesson.",
+      confidence: 0.8,
+      occurrences: 1,
+      distinctSessionIds: ["sess-4"],
+      evidence: [
+        {
+          sessionId: "sess-4",
+          observedAt: "2026-05-24T15:00:00.000Z",
+          summary: "Active.",
+        },
+      ],
+      createdAt: "2026-05-24T15:00:00.000Z",
+      updatedAt: "2026-05-24T15:00:00.000Z",
+    },
+    "2026-05-24T15:00:00.000Z",
+  );
+
+  await store.upsertLesson(lesson);
+
+  const invalidLesson: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-invalid",
+      scope,
+      kind: "preference",
+      text: "Invalidated lesson.",
+      confidence: 0.5,
+      occurrences: 1,
+      distinctSessionIds: ["sess-4"],
+      evidence: [
+        {
+          sessionId: "sess-4",
+          observedAt: "2026-05-24T15:30:00.000Z",
+          summary: "Invalid.",
+        },
+      ],
+      createdAt: "2026-05-24T15:30:00.000Z",
+      updatedAt: "2026-05-24T15:30:00.000Z",
+      invalidAt: "2026-05-24T16:00:00.000Z",
+    },
+    "2026-05-24T15:30:00.000Z",
+  );
+
+  await store.upsertLesson(invalidLesson);
+
+  expect(await store.getLesson("lesson-active")).toBeDefined();
+  expect(
+    await store.getLesson("lesson-invalid"),
+    "getLesson must still return an invalidated record",
+  ).toBeDefined();
+
+  // BOTH ends of the window, not just invalidAt: a record whose validFrom has not arrived is not
+  // active either, and only asserting the expiry end would leave that half uncovered per backend.
+  const notYetValid: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-not-yet-valid",
+      scope,
+      kind: "preference",
+      text: "Not yet effective.",
+      confidence: 0.5,
+      occurrences: 1,
+      distinctSessionIds: ["sess-4"],
+      evidence: [],
+      createdAt: "2026-05-24T15:30:00.000Z",
+      updatedAt: "2026-05-24T15:30:00.000Z",
+      validFrom: "2099-01-01T00:00:00.000Z",
+    },
+    "2026-05-24T15:30:00.000Z",
+  );
+
+  await store.upsertLesson(notYetValid);
+
+  const now = "2026-05-24T17:00:00.000Z";
+  const active = await store.listActiveLessons(now);
+  expect(active.find((l) => l.id === "lesson-active")).toBeDefined();
+  expect(
+    active.find((l) => l.id === "lesson-invalid"),
+    "listActiveLessons must exclude an invalidated record",
+  ).toBeUndefined();
+  expect(
+    active.find((l) => l.id === "lesson-not-yet-valid"),
+    "listActiveLessons must exclude a record whose validFrom has not arrived",
+  ).toBeUndefined();
+  expect(
+    await store.getLesson("lesson-not-yet-valid"),
+    "getLesson must still return a not-yet-valid record",
+  ).toBeDefined();
+}
+
+async function assertChainWalksNewestFirstAndRejectsCycle(make: MakeStore) {
+  const scope = { agentId: "a5", workspaceId: ws("chain") };
+  const store = await make(scope);
+
+  const v1: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-v1-chain",
+      scope,
+      kind: "procedure",
+      text: "Version 1.",
+      confidence: 0.5,
+      occurrences: 1,
+      distinctSessionIds: ["sess-5"],
+      evidence: [
+        {
+          sessionId: "sess-5",
+          observedAt: "2026-05-24T17:00:00.000Z",
+          summary: "V1.",
+        },
+      ],
+      createdAt: "2026-05-24T17:00:00.000Z",
+      updatedAt: "2026-05-24T17:00:00.000Z",
+    },
+    "2026-05-24T17:00:00.000Z",
+  );
+
+  await store.upsertLesson(v1);
+
+  await store.supersedeLesson({
+    predecessorId: "lesson-v1-chain",
+    successor: withLessonDefaults(
+      {
+        id: "lesson-v2-chain",
+        scope,
+        kind: "procedure",
+        text: "Version 2.",
+        confidence: 0.7,
+        occurrences: 1,
+        distinctSessionIds: ["sess-5"],
+        evidence: [
+          {
+            sessionId: "sess-5",
+            observedAt: "2026-05-24T17:30:00.000Z",
+            summary: "V2.",
+          },
+        ],
+        createdAt: "2026-05-24T17:30:00.000Z",
+        updatedAt: "2026-05-24T17:30:00.000Z",
+      },
+      "2026-05-24T17:30:00.000Z",
+    ),
+    now: "2026-05-24T17:30:00.000Z",
+  });
+
+  await store.supersedeLesson({
+    predecessorId: "lesson-v2-chain",
+    successor: withLessonDefaults(
+      {
+        id: "lesson-v3-chain",
+        scope,
+        kind: "procedure",
+        text: "Version 3.",
+        confidence: 0.95,
+        occurrences: 1,
+        distinctSessionIds: ["sess-5"],
+        evidence: [
+          {
+            sessionId: "sess-5",
+            observedAt: "2026-05-24T18:00:00.000Z",
+            summary: "V3.",
+          },
+        ],
+        createdAt: "2026-05-24T18:00:00.000Z",
+        updatedAt: "2026-05-24T18:00:00.000Z",
+      },
+      "2026-05-24T18:00:00.000Z",
+    ),
+    now: "2026-05-24T18:00:00.000Z",
+  });
+
+  const chain = await store.getLessonChain("lesson-v3-chain");
+  expect(
+    chain.map((lesson) => lesson.id),
+    "getLessonChain must walk newest-first",
+  ).toEqual(["lesson-v3-chain", "lesson-v2-chain", "lesson-v1-chain"]);
+
+  // A corrupt pair of mutual back-links must be rejected, not walked forever. supersedeLesson
+  // cannot produce this, so the cycle is written through upsertLesson.
+  const cycleA: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-cycle-a",
+      scope,
+      supersedesId: "lesson-cycle-b",
+      kind: "procedure",
+      text: "Cycle A.",
+      confidence: 0.5,
+      occurrences: 1,
+      distinctSessionIds: ["sess-5"],
+      evidence: [
+        {
+          sessionId: "sess-5",
+          observedAt: "2026-05-24T18:30:00.000Z",
+          summary: "Cycle A.",
+        },
+      ],
+      createdAt: "2026-05-24T18:30:00.000Z",
+      updatedAt: "2026-05-24T18:30:00.000Z",
+    },
+    "2026-05-24T18:30:00.000Z",
+  );
+  const cycleB: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-cycle-b",
+      scope,
+      supersedesId: "lesson-cycle-a",
+      kind: "procedure",
+      text: "Cycle B.",
+      confidence: 0.5,
+      occurrences: 1,
+      distinctSessionIds: ["sess-5"],
+      evidence: [
+        {
+          sessionId: "sess-5",
+          observedAt: "2026-05-24T18:31:00.000Z",
+          summary: "Cycle B.",
+        },
+      ],
+      createdAt: "2026-05-24T18:31:00.000Z",
+      updatedAt: "2026-05-24T18:31:00.000Z",
+    },
+    "2026-05-24T18:31:00.000Z",
+  );
+
+  await store.upsertLesson(cycleA);
+  await store.upsertLesson(cycleB);
+
+  await expect(store.getLessonChain("lesson-cycle-a")).rejects.toThrow(/cycle/i);
+}
+
+async function assertMergeAccumulatesOccurrencesAndEvidence(make: MakeStore) {
+  const scope = { agentId: "a7", workspaceId: ws("merge") };
+  const store = await make(scope);
+
+  const lesson1: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-merge",
+      scope,
+      kind: "failure",
+      text: "Handle timeouts.",
+      confidence: 0.7,
+      occurrences: 1,
+      distinctSessionIds: ["sess-7a"],
+      evidence: [
+        {
+          evidenceId: "ev-1",
+          sessionId: "sess-7a",
+          observedAt: "2026-05-24T19:00:00.000Z",
+          summary: "First occurrence.",
+        },
+      ],
+      createdAt: "2026-05-24T19:00:00.000Z",
+      updatedAt: "2026-05-24T19:00:00.000Z",
+    },
+    "2026-05-24T19:00:00.000Z",
+  );
+
+  const merged1 = await store.mergeLesson(lesson1);
+  expect(merged1.occurrences).toBe(1);
+  expect(merged1.evidence).toHaveLength(1);
+
+  const lesson2: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-merge",
+      scope,
+      kind: "failure",
+      text: "Handle timeouts.",
+      confidence: 0.85,
+      occurrences: 1,
+      distinctSessionIds: ["sess-7b"],
+      evidence: [
+        {
+          evidenceId: "ev-2",
+          sessionId: "sess-7b",
+          observedAt: "2026-05-24T19:30:00.000Z",
+          summary: "Second occurrence.",
+        },
+      ],
+      createdAt: "2026-05-24T19:00:00.000Z",
+      updatedAt: "2026-05-24T19:30:00.000Z",
+    },
+    "2026-05-24T19:00:00.000Z",
+  );
+
+  const merged2 = await store.mergeLesson(lesson2);
+  expect(merged2.occurrences, "merge must accumulate occurrences").toBe(2);
+  expect(merged2.evidence, "merge must accumulate evidence").toHaveLength(2);
+  expect(merged2.distinctSessionIds).toEqual(["sess-7a", "sess-7b"]);
+  expect(merged2.confidence).toBe(0.85);
+}
+
+async function assertProposalAndAuditRoundTrip(make: MakeStore) {
+  const store = await make({ agentId: "a8", workspaceId: ws("proposal") });
+
+  const proposal: SkillProposal = {
+    id: "proposal-1",
+    lessonIds: ["lesson-1"],
+    status: "pending",
+    skillName: "test-skill",
+    title: "Test proposal",
+    body: "# Test",
+    scannerFindings: [],
+    createdAt: "2026-05-24T20:00:00.000Z",
+    updatedAt: "2026-05-24T20:00:00.000Z",
+  };
+
+  await store.insertProposalIfAbsent(proposal);
+  const retrieved = await store.getProposal("proposal-1");
+  expect(retrieved).toEqual(proposal);
+
+  const decided = await store.recordProposalDecision({
+    proposalId: "proposal-1",
+    status: "applied",
+    actor: "test-user",
+    now: "2026-05-24T20:15:00.000Z",
+  });
+
+  expect(decided.status).toBe("applied");
+  expect(decided.decidedBy).toBeDefined();
+  expect(decided.decidedAt).toBe("2026-05-24T20:15:00.000Z");
+
+  const audit = await store.listAudit();
+  expect(audit.length, "the decision must append an audit event").toBeGreaterThan(0);
+}
+
+async function assertFindProposalWithScope(make: MakeStore) {
+  const scope = { agentId: "a9", workspaceId: ws("proposal-scope") };
+  const store = await make(scope);
+
+  const proposal: SkillProposal = {
+    id: "proposal-scoped",
+    lessonIds: ["lesson-1"],
+    status: "pending",
+    skillName: "test-skill",
+    title: "Test proposal",
+    body: "# Test",
+    scannerFindings: [],
+    createdAt: "2026-05-24T20:00:00.000Z",
+    updatedAt: "2026-05-24T20:00:00.000Z",
+  };
+  await store.insertProposalIfAbsent(proposal);
+
+  // Look it up through a store built with an EMPTY scope. That is exactly how the gateway calls it
+  // (index.ts wires `createLessonStore({ ..., scope: {} })`), and it is the leg that fails today.
+  const crossScope = await make({});
+  const found = await crossScope.findProposalWithScope("proposal-scoped");
+  expect(
+    found,
+    "a proposal written under one scope must be findable from an empty scope",
+  ).toBeDefined();
+  expect(found?.proposal.id).toBe("proposal-scoped");
+  // The proposal's OWN scope must come back -- NOT the caller's. If this returns the empty scope,
+  // decide() resolves no workspace and apply dies with "workspace unresolvable; cannot apply".
+  expect(found?.scope.workspaceId).toBe(scope.workspaceId);
+  expect(found?.scope.agentId).toBe(scope.agentId);
+
+  // A proposal written WITHOUT a scope must read back as an empty scope on EVERY backend. The SQL
+  // stores persist an absent scope field as "" (writeRecord: `this.scope.workspaceId ?? ""`), never
+  // NULL, so a column read that only guards against NULL hands back {workspaceId: "", agentId: ""}
+  // and diverges from fs-jsonl, which returns the raw log scope `{}`.
+  const unscopedStore = await make({});
+  await unscopedStore.insertProposalIfAbsent({
+    ...proposal,
+    id: "proposal-unscoped",
+    lessonIds: ["lesson-2"],
+    skillName: "test-skill-unscoped",
+  });
+  const unscoped = await crossScope.findProposalWithScope("proposal-unscoped");
+  expect(unscoped?.proposal.id).toBe("proposal-unscoped");
+  expect(unscoped?.scope).toEqual({});
+
+  expect(await crossScope.findProposalWithScope("no-such-proposal")).toBeUndefined();
+}
+
+async function assertSupersedeRejectsOccupiedSuccessorId(make: MakeStore) {
+  // The tool derives the successor id from the replacement TEXT, so text that duplicates another
+  // lesson's text mints THAT lesson's id. Writing it would overwrite an unrelated record with the
+  // predecessor's carried fields and still report success -- silent cross-lesson data loss.
+  const scope = { agentId: "a1", workspaceId: ws("occupied-successor") };
+  const store = await make(scope);
+  const at = "2026-05-24T12:00:00.000Z";
+  const make_ = (id: string): LearningLesson =>
+    withLessonDefaults(
+      {
+        id,
+        scope,
+        kind: "procedure",
+        text: `text for ${id}`,
+        confidence: 0.5,
+        occurrences: 1,
+        distinctSessionIds: [],
+        evidence: [],
+        createdAt: at,
+        updatedAt: at,
+      },
+      at,
+    );
+  const predecessor = make_("lesson-occupied-pred");
+  const bystander = make_("lesson-occupied-bystander");
+  await store.upsertLesson(predecessor);
+  await store.upsertLesson(bystander);
+
+  await expect(
+    store.supersedeLesson({
+      predecessorId: predecessor.id,
+      successor: make_(bystander.id),
+      now: "2026-05-24T13:00:00.000Z",
+    }),
+    "a successor id that already belongs to another lesson must be refused",
+  ).rejects.toThrow(/already belongs to another lesson/);
+
+  // And nothing may have been written on the way to that refusal.
+  expect(await store.getLesson(bystander.id)).toEqual(bystander);
+  expect((await store.getLesson(predecessor.id))?.invalidAt).toBeUndefined();
+}
+
+async function assertIdempotentResupersede(make: MakeStore) {
+  const scope = { agentId: "a1", workspaceId: ws("resupersede") };
+  const store = await make(scope);
+  const pred: LearningLesson = withLessonDefaults(
+    {
+      id: "lesson-pred",
+      scope,
+      kind: "correction",
+      text: "first",
+      confidence: 0.9,
+      occurrences: 1,
+      distinctSessionIds: ["s1"],
+      evidence: [],
+      createdAt: "2026-08-01T00:00:00.000Z",
+      updatedAt: "2026-08-01T00:00:00.000Z",
+    },
+    "2026-08-01T00:00:00.000Z",
+  );
+  await store.upsertLesson(pred);
+  const makeSucc = (id: string, text: string, at: string): LearningLesson =>
+    withLessonDefaults(
+      {
+        id,
+        scope,
+        kind: "correction",
+        text,
+        confidence: 0.9,
+        occurrences: 1,
+        distinctSessionIds: ["s1"],
+        evidence: [],
+        createdAt: at,
+        updatedAt: at,
+      },
+      at,
+    );
+  const first = await store.supersedeLesson({
+    predecessorId: pred.id,
+    successor: makeSucc("lesson-succ-1", "second", "2026-08-02T00:00:00.000Z"),
+    now: "2026-08-02T00:00:00.000Z",
+  });
+  const second = await store.supersedeLesson({
+    predecessorId: pred.id,
+    successor: makeSucc("lesson-succ-2", "third", "2026-08-03T00:00:00.000Z"),
+    now: "2026-08-03T00:00:00.000Z",
+  });
+  expect(second.id).toBe(first.id);
+  const all = await store.listLessons();
+  expect(all.filter((lesson) => lesson.supersedesId === pred.id)).toHaveLength(1);
+}
+
+async function assertCandidateRoundTrip(make: MakeStore) {
+  const store = await make({ workspaceId: ws("cand"), agentId: "a1" });
+  const candidate = withCandidateDefaults(
+    {
+      sessionId: "sess-1",
+      workspaceId: ws("cand"),
+      agentId: "a1",
+      excerpt: "redacted",
+      tags: ["correction"],
+    },
+    "2026-08-15T00:00:00.000Z",
+  );
+  await store.upsertCandidate(candidate);
+  await store.upsertCandidate({ ...candidate, excerpt: "redacted-2" });
+  const got = await store.getCandidate("sess-1");
+  expect(got?.excerpt).toBe("redacted-2");
+  expect(got?.status).toBe("pending");
+  const pending = await store.listPendingCandidates({ tags: ["correction"] });
+  expect(pending.map((entry) => entry.sessionId)).toEqual(["sess-1"]);
+  await store.markCandidateProcessed("sess-1", {
+    status: "processed",
+    promotedLessonId: "lesson-x",
+  });
+  expect((await store.listPendingCandidates()).map((entry) => entry.sessionId)).not.toContain(
+    "sess-1",
+  );
+  expect((await store.getCandidate("sess-1"))?.promotedLessonId).toBe("lesson-x");
+  expect(await store.listLessons()).toHaveLength(0);
+}
+
+async function assertGetCandidatesBySessionIdsRoundTrip(make: MakeStore) {
+  const scope = { agentId: "a1", workspaceId: ws("batch-candidates") };
+  const store = await make(scope);
+  const candidate = {
+    sessionId: "sess-a",
+    excerpt: "redacted",
+    tags: ["correction"],
+    status: "pending",
+    endedAt: "2026-05-24T20:00:00.000Z",
+  } as ExtractionCandidate;
+  await store.upsertCandidate(candidate);
+  await store.upsertCandidate({ ...candidate, sessionId: "sess-b" });
+
+  const found = await store.getCandidatesBySessionIds(["sess-a", "sess-b", "sess-missing"]);
+  expect(
+    found.map((entry) => entry.sessionId).sort(),
+    "found ids only — missing ids are absent, not an error",
+  ).toEqual(["sess-a", "sess-b"]);
+  expect(await store.getCandidatesBySessionIds([])).toEqual([]);
+
+  const otherAgent = await make({ agentId: "a2", workspaceId: ws("batch-candidates") });
+  expect(
+    await otherAgent.getCandidatesBySessionIds(["sess-a"]),
+    "agent isolation holds for the batch read in the same workspace",
+  ).toEqual([]);
+  const otherWorkspace = await make({ agentId: "a1", workspaceId: ws("batch-other") });
+  expect(
+    await otherWorkspace.getCandidatesBySessionIds(["sess-a"]),
+    "workspace isolation holds for the batch read with the same agent",
+  ).toEqual([]);
+}
+
+async function assertSearchLessons(make: MakeStore, backend: Backend) {
+  const store = await make({ workspaceId: ws("srch"), agentId: "a1" });
+  await store.upsertLesson(
+    withLessonDefaults(
+      {
+        id: "lesson-hit",
+        scope: { workspaceId: ws("srch"), agentId: "a1" },
+        kind: "procedure",
+        text: "Always use pnpm-lock.yaml",
+        confidence: 0.9,
+        occurrences: 1,
+        distinctSessionIds: ["s"],
+        evidence: [],
+        createdAt: "2026-08-15T00:00:00.000Z",
+        updatedAt: "2026-08-15T00:00:00.000Z",
+      },
+      "2026-08-15T00:00:00.000Z",
+    ),
+  );
+  await store.upsertLesson(
+    withLessonDefaults(
+      {
+        id: "lesson-miss",
+        scope: { workspaceId: ws("srch"), agentId: "a1" },
+        kind: "procedure",
+        text: "Prefer HTTPS",
+        confidence: 0.9,
+        occurrences: 1,
+        distinctSessionIds: ["s"],
+        evidence: [],
+        createdAt: "2026-08-15T00:00:00.000Z",
+        updatedAt: "2026-08-15T00:00:00.000Z",
+      },
+      "2026-08-15T00:00:00.000Z",
+    ),
+  );
+  await store.upsertCandidate(
+    withCandidateDefaults(
+      {
+        sessionId: "sess-search",
+        workspaceId: ws("srch"),
+        agentId: "a1",
+        excerpt: "Always use pnpm-lock.yaml",
+        tags: ["untagged"],
+      },
+      "2026-08-15T00:00:00.000Z",
+    ),
+  );
+  const hits = await store.searchLessons(
+    "pnpm-lock",
+    { workspaceId: ws("srch"), agentId: "a1" },
+    5,
+  );
+  expect(hits[0]?.lesson.id).toBe("lesson-hit");
+  expect(hits[0]?.score).toBeGreaterThan(0);
+  expect(hits.map((h) => h.lesson.id)).not.toContain("lesson-miss");
+  expect(hits.map((h) => h.lesson.id)).not.toContain("sess-search");
+
+  await backend.assertSearchIndex(store);
+}
+
+async function assertFindProposalRejectsCrossScopeAmbiguity(make: MakeStore) {
+  // A proposal id is hash(lessonId + skillName) and a lesson id is hash(text) -- neither carries
+  // the scope. Two workspaces that learn the same text and propose the same skill therefore mint
+  // the SAME id, which the (workspace, agent, type, id) key permits. The cross-scope lookup then
+  // has no correct answer, so it must refuse rather than hand the gateway an arbitrary scope and
+  // apply one owner's decision to the other's proposal.
+  const shared: SkillProposal = {
+    id: "proposal-collides",
+    lessonIds: ["lesson-same-text"],
+    status: "pending",
+    skillName: "same-skill",
+    title: "Collides",
+    body: "# Collides",
+    scannerFindings: [],
+    createdAt: "2026-05-24T20:00:00.000Z",
+    updatedAt: "2026-05-24T20:00:00.000Z",
+  };
+  const left = await make({ agentId: "a1", workspaceId: ws("ambiguous-left") });
+  const right = await make({ agentId: "a2", workspaceId: ws("ambiguous-right") });
+  // upsertProposal, not insertProposalIfAbsent: the duplicate guard is scope-filtered, and the
+  // in-memory Postgres double does not honour that filter, so it would refuse the second write and
+  // never build the two-scope state this asserts on. The collision is what is under test here, not
+  // how it is created.
+  await left.upsertProposal(shared);
+  await right.upsertProposal(shared);
+
+  const crossScope = await make({});
+  await expect(
+    crossScope.findProposalWithScope("proposal-collides"),
+    "an id present in two scopes must be refused, not resolved to an arbitrary one",
+  ).rejects.toThrow(/exists in 2 scopes/);
+}
+
+async function assertListProposalsWithScopeKeepsCrossScopeSameId(make: MakeStore) {
+  const shared: SkillProposal = {
+    id: "proposal-collides-list",
+    lessonIds: ["lesson-same-text"],
+    status: "pending",
+    skillName: "same-skill",
+    title: "Collides",
+    body: "# Collides",
+    scannerFindings: [],
+    createdAt: "2026-05-24T20:00:00.000Z",
+    updatedAt: "2026-05-24T20:00:00.000Z",
+  };
+  const left = await make({ agentId: "a1", workspaceId: ws("list-left") });
+  const right = await make({ agentId: "a2", workspaceId: ws("list-right") });
+  // upsertProposal, not insertProposalIfAbsent — same reason as the ambiguity assert above
+  // (:1138-1141): the duplicate guard is scope-filtered and the in-memory postgres double does
+  // not honour that filter, so it would refuse the second write.
+  await left.upsertProposal(shared);
+  await right.upsertProposal(shared);
+
+  const crossScope = await make({});
+  const matches = (await crossScope.listProposalsWithScope()).filter(
+    (entry) => entry.proposal.id === shared.id,
+  );
+  expect(
+    matches,
+    "both scopes' rows must be listed — fs-jsonl used to collapse them by recordId (finding 17)",
+  ).toHaveLength(2);
+  expect(matches.map((entry) => entry.scope)).toEqual(
+    expect.arrayContaining([
+      { agentId: "a1", workspaceId: ws("list-left") },
+      { agentId: "a2", workspaceId: ws("list-right") },
+    ]),
+  );
+}
+
+async function assertAlreadyDecidedDecisionRejectsWithCode(make: MakeStore) {
+  const store = await make({ agentId: "a1", workspaceId: ws("decided-code") });
+  const proposal: SkillProposal = {
+    id: "proposal-decided-code",
+    lessonIds: ["lesson-x"],
+    status: "pending",
+    skillName: "decided-code",
+    title: "Decided",
+    body: "# Decided",
+    scannerFindings: [],
+    createdAt: "2026-05-24T20:00:00.000Z",
+    updatedAt: "2026-05-24T20:00:00.000Z",
+  };
+  await store.upsertProposal(proposal);
+  await store.recordProposalDecision({
+    proposalId: proposal.id,
+    status: "applied",
+    actor: "owner",
+    now: "2026-05-24T21:00:00.000Z",
+  });
+  await expect(
+    store.recordProposalDecision({
+      proposalId: proposal.id,
+      status: "rejected",
+      actor: "owner",
+      now: "2026-05-24T22:00:00.000Z",
+    }),
+    "an already-decided refusal must carry a LEARNING_* code on every backend leg",
+  ).rejects.toMatchObject({ code: expect.stringMatching(/^LEARNING_/) });
+}
+
+async function assertInvalidateLesson(make: MakeStore) {
+  const scope = { agentId: "a1", workspaceId: ws("invalidate") };
+  const store = await make(scope);
+  const now = "2026-05-24T17:00:00.000Z";
+  const lesson = withLessonDefaults(
+    {
+      id: "lesson-invalidate",
+      scope,
+      kind: "procedure" as const,
+      text: "Use pnpm for installs.",
+      confidence: 0.8,
+      occurrences: 1,
+      distinctSessionIds: ["sess-1"],
+      evidence: [],
+      createdAt: now,
+      updatedAt: now,
+    },
+    now,
+  );
+  await store.upsertLesson(lesson);
+  const later = "2026-05-24T18:00:00.000Z";
+  const invalidated = await store.invalidateLesson({
+    id: "lesson-invalidate",
+    now: later,
+    reason: "contradicted",
+    sessionId: "sess-9",
+  });
+  expect(invalidated).toMatchObject({
+    id: "lesson-invalidate",
+    text: "Use pnpm for installs.",
+    invalidAt: later,
+    invalidatedBySessionId: "sess-9",
+    invalidationReason: "contradicted",
+  });
+  // The field round-trips through the store, no successor is minted, and it is inactive.
+  expect(await store.getLesson("lesson-invalidate")).toMatchObject({
+    invalidAt: later,
+    invalidatedBySessionId: "sess-9",
+  });
+  expect(await store.listLessons()).toHaveLength(1);
+  expect(await store.listActiveLessons(later)).toEqual([]);
+  // Idempotent: a second invalidation keeps the first invalidAt.
+  const again = await store.invalidateLesson({
+    id: "lesson-invalidate",
+    now: "2026-05-25T00:00:00.000Z",
+  });
+  expect(again.invalidAt).toBe(later);
+  await expect(store.invalidateLesson({ id: "lesson-missing", now: later })).rejects.toThrow(
+    /Lesson not found/,
+  );
+}
+
+// VAL-PROD-022: invalidateLesson leaves a lesson retired with no successor. The public
+// (non-exact) supersede must refuse it and write nothing: no restamped invalidAt, no active
+// successor for a retired lesson.
+async function assertSupersedeRefusesInvalidatedWithoutSuccessor(
+  make: MakeStore,
+  backend: Backend,
+) {
+  const scope = { agentId: "a1", workspaceId: ws("supersede-invalidated") };
+  const store = await make(scope);
+  const created = "2026-08-01T00:00:00.000Z";
+  const invalidatedAt = "2026-08-02T00:00:00.000Z";
+  await store.upsertLesson(
+    withLessonDefaults(
+      {
+        id: "lesson-retired",
+        scope,
+        kind: "correction",
+        text: "retired text",
+        confidence: 0.9,
+        occurrences: 1,
+        distinctSessionIds: ["s1"],
+        evidence: [],
+        createdAt: created,
+        updatedAt: created,
+      },
+      created,
+    ),
+  );
+  await store.invalidateLesson({
+    id: "lesson-retired",
+    now: invalidatedAt,
+    reason: "contradicted",
+    sessionId: "sess-inv",
+  });
+  const before = await backend.snapshot();
+  const later = "2026-08-03T00:00:00.000Z";
+  const error = await store
+    .supersedeLesson({
+      predecessorId: "lesson-retired",
+      successor: withLessonDefaults(
+        {
+          id: "lesson-resurrected",
+          scope,
+          kind: "correction",
+          text: "resurrected text",
+          confidence: 0.9,
+          occurrences: 1,
+          distinctSessionIds: ["s1"],
+          evidence: [],
+          createdAt: later,
+          updatedAt: later,
+        },
+        later,
+      ),
+      now: later,
+    })
+    .then(
+      () => undefined,
+      (err: unknown) => err,
+    );
+  expect(error).toBeInstanceOf(Error);
+  expect(isLearningDomainError(error)).toBe(true);
+  expect((error as Error).message).toMatch(/invalidated and has no successor/);
+  expect(await backend.snapshot()).toBe(before);
+  expect(await store.getLesson("lesson-retired")).toMatchObject({
+    invalidAt: invalidatedAt,
+    invalidatedBySessionId: "sess-inv",
+    invalidationReason: "contradicted",
+  });
+  expect(await store.getLesson("lesson-resurrected")).toBeUndefined();
+  const all = await store.listLessons();
+  expect(all.filter((lesson) => lesson.supersedesId === "lesson-retired")).toEqual([]);
+  expect(
+    (await store.listActiveLessons(later)).filter((l) => l.supersedesId === "lesson-retired"),
+  ).toEqual([]);
+}
+
+async function assertDescribeBackend(make: MakeStore, expected: Backend["name"]) {
+  const store = await make({ agentId: "a9", workspaceId: ws("describe") });
+  const desc = store.describeBackend();
+
+  expect(desc.backend, `${expected} store must report its own backend name`).toBe(expected);
+  expect(desc.capability, `${expected} store must report its documented capability`).toBe(
+    EXPECTED_CAPABILITY[expected],
+  );
+}
+
+// --- Backend tests: registered once per leg by each conformance test file ---
+
+export function registerLessonStoreConformance(backend: Backend): void {
+  describe(`LessonStore conformance — ${backend.label}`, () => {
+    it("round-trips a lesson with every lifecycle field", async () => {
+      await assertRoundTripsLesson(backend.make);
+    });
+
+    it("upsert is idempotent by id within a scope", async () => {
+      await assertUpsertIsIdempotent(backend.make);
+    });
+
+    it("scopes reads — a lesson in w1/a1 is invisible to w2/a2", async () => {
+      await assertScopeIsolation(backend.make);
+    });
+
+    it("isolates on workspace and on agent independently", async () => {
+      await assertScopeIsolationPerDimension(backend.make);
+    });
+
+    it("an empty scope reads across all scopes", async () => {
+      await assertEmptyScopeReadsAcrossScopes(backend.make);
+    });
+
+    it("supersedeLesson retains the predecessor with invalid_at and links the successor", async () => {
+      await assertSupersedeRetainsPredecessor(backend.make);
+    });
+
+    it("updating an earlier lesson does not reorder the list", async () => {
+      await assertUpdateDoesNotReorder(backend.make);
+    });
+
+    it("supersedeLesson refuses a successor whose id equals the predecessor id", async () => {
+      await assertSupersedeRejectsSelfReference(backend.make);
+    });
+
+    it("invalidateLesson ends a lesson without a successor and records invalidatedBySessionId", async () => {
+      await assertInvalidateLesson(backend.make);
+    });
+
+    it("listActiveLessons excludes invalidated records; getLesson still returns them", async () => {
+      await assertActiveListExcludesInvalidated(backend.make);
+    });
+
+    it("getLessonChain walks the chain newest-first and rejects a cycle", async () => {
+      await assertChainWalksNewestFirstAndRejectsCycle(backend.make);
+    });
+
+    it("insertLessonIfAbsent never overwrites an existing row", async () => {
+      await assertInsertLessonIfAbsentNeverOverwrites(backend.make);
+    });
+
+    it("mergeLesson accumulates occurrences and evidence", async () => {
+      await assertMergeAccumulatesOccurrencesAndEvidence(backend.make);
+    });
+
+    it("proposal + audit round-trip", async () => {
+      await assertProposalAndAuditRoundTrip(backend.make);
+    });
+
+    it("findProposalWithScope returns a proposal's own scope even when queried from an empty scope", async () => {
+      await assertFindProposalWithScope(backend.make);
+    });
+
+    it("supersedeLesson REFUSES a successor id that already belongs to another lesson", async () => {
+      await assertSupersedeRejectsOccupiedSuccessorId(backend.make);
+    });
+
+    it("supersedeLesson refuses an invalidated lesson with no successor and writes nothing (VAL-PROD-022)", async () => {
+      await assertSupersedeRefusesInvalidatedWithoutSuccessor(backend.make, backend);
+    });
+
+    it("re-superseding an invalidated lesson returns the existing successor", async () => {
+      await assertIdempotentResupersede(backend.make);
+    });
+
+    it("findProposalWithScope REFUSES an id that exists in two scopes", async () => {
+      await assertFindProposalRejectsCrossScopeAmbiguity(backend.make);
+    });
+
+    it("listProposalsWithScope keeps both scopes' rows for a cross-scope same-id proposal", async () => {
+      await assertListProposalsWithScopeKeepsCrossScopeSameId(backend.make);
+    });
+
+    it("recordProposalDecision on an already-decided proposal rejects with a LEARNING_* code", async () => {
+      await assertAlreadyDecidedDecisionRejectsWithCode(backend.make);
+    });
+
+    it("describeBackend reports the expected backend and capability", async () => {
+      await assertDescribeBackend(backend.make, backend.name);
+    });
+
+    it("round-trips a candidate and keeps it out of listLessons", async () => {
+      await assertCandidateRoundTrip(backend.make);
+    });
+
+    it("batches candidate lookups by session id set", async () => {
+      await assertGetCandidatesBySessionIdsRoundTrip(backend.make);
+    });
+
+    it("searchLessons ranks the distinctive token and skips candidates (TS12)", async () => {
+      await assertSearchLessons(backend.make, backend);
+    });
+  });
+}