wednesdayai 0.4.12-dev.716 → 0.4.12-dev.719

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

@@ -3,84 +3,30 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { isLearningDomainError } from "./errors.js";
-import { withCandidateDefaults } from "./extraction-candidate.js";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { createLearningSchemaSql } from "./learning-schema.js";
-import { withLessonDefaults } from "./lesson-record.js";
 import {
-  createDefaultLearningPgPool,
-  PostgresLessonStore,
-  type PgPoolLike,
-} from "./lesson-store-postgres.js";
+  assertScopeIsolation,
+  registerLessonStoreConformance,
+  TEST_SCHEMA,
+  type Backend,
+  type MakeStore,
+  type StoreScope,
+} from "./lesson-store-conformance.test-helpers.js";
+import { PostgresLessonStore } from "./lesson-store-postgres.js";
 import { createInMemoryPgPool, type InMemoryPgPool } from "./lesson-store-postgres.test-helpers.js";
 import { SqliteLessonStore } from "./lesson-store-sqlite.js";
 import { FileLearningStore } from "./store.js";
-import type { ExtractionCandidate, LearningLesson, LessonStore, SkillProposal } from "./types.js";
-
-type StoreScope = { workspaceId?: string; agentId?: string };
-type MakeStore = (scope: StoreScope) => Promise<LessonStore>;
-
-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 and the skip report.
-  label: string;
-  available: boolean;
-  make: MakeStore;
-  // Raw backing rows (or log bytes), for byte-identity assertions that bypass the store.
-  snapshot: () => Promise<string>;
-  skipReason?: string;
-};
-
-// 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 primary-mode-postgres.e2e.test.ts:21).
-// 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("-", "");
-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.
-const TEST_SCHEMA = `plugin_learning_core_test_${RUN_TOKEN}`;
-const PG_TABLE = `${TEST_SCHEMA}.learning_records`;
-
-const EXPECTED_CAPABILITY: Record<Backend["name"], "full" | "reduced"> = {
-  "fs-jsonl": "reduced",
-  sqlite: "full",
-  postgres: "full",
-};
+import type { LearningLesson } from "./types.js";
 
 // Shared backing resources: reset in beforeEach, torn down in afterEach. ONE per test, so a
 // make(scope) call returns a scoped view over storage the other scopes also see.
 let shared: { logDir: string; db: DatabaseSync; memPool: InMemoryPgPool };
 
-type ClosablePool = PgPoolLike & { end?: () => Promise<void> };
-let sharedPool: ClosablePool | undefined;
-
-async function cleanupPostgresRows(): Promise<void> {
-  if (!sharedPool) {
-    return;
-  }
-  // The table only exists once the postgres leg has run its DDL; probing avoids swallowing a
-  // real error in a bare catch.
-  const probe = await sharedPool.query("SELECT to_regclass($1) AS reg", [PG_TABLE]);
-  if (!probe.rows[0]?.reg) {
-    return;
-  }
-  await sharedPool.query(`DELETE FROM ${PG_TABLE} WHERE workspace_id LIKE $1`, [`${RUN_ID}%`]);
-}
-
 const BACKENDS: Backend[] = [
   {
     name: "fs-jsonl",
     label: "fs-jsonl",
-    available: true,
     make: async (scope) => new FileLearningStore({ logDir: shared.logDir, scope }),
     snapshot: async () => {
       const names = (await fs.readdir(shared.logDir, { recursive: true })).toSorted();
@@ -93,11 +39,13 @@ const BACKENDS: Backend[] = [
       }
       return parts.join("\n--\n");
     },
+    assertSearchIndex: async (store) => {
+      expect(store.describeBackend().capability).toBe("reduced");
+    },
   },
   {
     name: "sqlite",
     label: "sqlite",
-    available: true,
     make: async (scope) => new SqliteLessonStore({ db: shared.db, scope }),
     snapshot: async () =>
       JSON.stringify(
@@ -107,48 +55,32 @@ const BACKENDS: Backend[] = [
           )
           .all(),
       ),
-  },
-  {
-    name: "postgres",
-    label: "postgres (live server)",
-    available: Boolean(process.env.OPENCLAW_DB_URL),
-    skipReason: "OPENCLAW_DB_URL not set",
-    make: async (scope) => {
-      if (!sharedPool) {
-        throw new Error("postgres backend requested without OPENCLAW_DB_URL");
-      }
-      return new PostgresLessonStore({ pool: sharedPool, schema: TEST_SCHEMA, scope });
-    },
-    snapshot: async () => {
-      const result = await sharedPool!.query(
-        `SELECT * FROM ${PG_TABLE} WHERE workspace_id LIKE $1
-         ORDER BY workspace_id, agent_id, record_type, record_id`,
-        [`${RUN_ID}%`],
-      );
-      return JSON.stringify(result.rows);
+    assertSearchIndex: async () => {
+      const names = shared.db.prepare("SELECT name FROM sqlite_master").all() as Array<{
+        name: string;
+      }>;
+      expect(names.map((row) => row.name)).toContain("learning_lessons_fts");
     },
   },
   {
     // The postgres store's own logic — row mapping, transaction ordering, merge, chain walking —
     // is identical whichever server answers, so it is held to the same contract on every host
-    // rather than only where a database happens to be reachable. The live leg above stays the
-    // authority on real dialect behaviour; this leg never substitutes for it.
+    // rather than only where a database happens to be reachable. The live leg
+    // (lesson-store-conformance.pg.integration.test.ts, `pnpm test:pg`) stays the authority on
+    // real dialect behaviour; this leg never substitutes for it.
     name: "postgres",
     label: "postgres (in-memory double)",
-    available: true,
     make: async (scope) =>
       new PostgresLessonStore({ pool: shared.memPool, schema: TEST_SCHEMA, scope }),
     snapshot: async () => JSON.stringify(shared.memPool.rows()),
+    assertSearchIndex: async () => {
+      const sql = createLearningSchemaSql("postgres", { schema: TEST_SCHEMA }).join("\n");
+      expect(sql).toMatch(/search_tsv/i);
+      expect(sql).toMatch(/\bGIN\b/i);
+    },
   },
 ];
 
-beforeAll(() => {
-  const dsn = process.env.OPENCLAW_DB_URL;
-  if (dsn) {
-    sharedPool = createDefaultLearningPgPool(dsn);
-  }
-});
-
 beforeEach(async () => {
   shared = {
     logDir: await fs.mkdtemp(path.join(os.tmpdir(), "learning-conformance-")),
@@ -160,1428 +92,14 @@ beforeEach(async () => {
 afterEach(async () => {
   shared.db.close();
   await fs.rm(shared.logDir, { recursive: true, force: true });
-  await cleanupPostgresRows();
-});
-
-afterAll(async () => {
-  if (sharedPool) {
-    await sharedPool.query(`DROP SCHEMA IF EXISTS ${TEST_SCHEMA} CASCADE`);
-    await sharedPool.end?.();
-  }
 });
 
-// --- 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);
-}
-
-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");
-
-  if (backend.name === "sqlite") {
-    const names = shared.db.prepare("SELECT name FROM sqlite_master").all() as Array<{
-      name: string;
-    }>;
-    expect(names.map((row) => row.name)).toContain("learning_lessons_fts");
-  } else if (backend.name === "postgres") {
-    if (backend.label.includes("live") && sharedPool) {
-      const cols = await sharedPool.query(
-        `SELECT column_name FROM information_schema.columns
-         WHERE table_schema = $1 AND table_name = 'learning_records' AND column_name = 'search_tsv'`,
-        [TEST_SCHEMA],
-      );
-      expect(cols.rows.length).toBeGreaterThan(0);
-      const idx = await sharedPool.query(
-        `SELECT indexname FROM pg_indexes
-         WHERE schemaname = $1 AND tablename = 'learning_records' AND indexdef ILIKE '%gin%'`,
-        [TEST_SCHEMA],
-      );
-      expect(idx.rows.length).toBeGreaterThan(0);
-    } else {
-      const sql = createLearningSchemaSql("postgres", { schema: TEST_SCHEMA }).join("\n");
-      expect(sql).toMatch(/search_tsv/i);
-      expect(sql).toMatch(/\bGIN\b/i);
-    }
-  } else {
-    expect(store.describeBackend().capability).toBe("reduced");
-  }
-}
-
-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 ---
 
 for (const backend of BACKENDS) {
-  const d = backend.available ? describe : describe.skip;
-  d(
-    `LessonStore conformance — ${backend.label}${backend.available ? "" : ` (SKIPPED: ${backend.skipReason})`}`,
-    () => {
-      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);
-      });
-    },
-  );
+  registerLessonStoreConformance(backend);
 }
 
-// --- Skip reporting test (TS3) ---
-
-it("reports which backends were skipped (TS3)", () => {
-  const skipped = BACKENDS.filter((b) => !b.available).map((b) => `${b.label}: ${b.skipReason}`);
-  console.warn(
-    skipped.length
-      ? `conformance skipped — ${skipped.join(", ")}`
-      : `conformance: all ${BACKENDS.length} legs ran`,
-  );
-  expect(BACKENDS.filter((b) => b.available).length).toBeGreaterThanOrEqual(2);
-});
-
-// The in-memory double must never be mistaken for coverage of a real server. This asserts the
-// report above still names the live leg as skipped when no DSN is configured, so a green run on a
-// database-less host cannot read as "postgres verified".
-it("does not let the in-memory double mask an unrun live-postgres leg (TS3)", () => {
-  const live = BACKENDS.find((b) => b.label === "postgres (live server)");
-  expect(live).toBeDefined();
-  expect(live?.available).toBe(Boolean(process.env.OPENCLAW_DB_URL));
-
-  const double = BACKENDS.find((b) => b.label === "postgres (in-memory double)");
-  expect(double?.available).toBe(true);
-  expect(double?.name).toBe("postgres");
-});
-
 // --- Byte-identity test (TS1) ---
 
 it("fs-jsonl never rewrites an existing log on read (TS1 byte-identity)", async () => {