fix(miner): add tenant_id column to governor-ledger and plan-store

#4939 added a nullable tenant_id TEXT column to the miner's local ledger
schemas as hosted-readiness groundwork, but governor-ledger.js's
governor_events table and plan-store.js's miner_plans table were left
out — both passed an empty migrations array to applySchemaMigrations.

Add an addTenantIdColumn migration to each, guarded by a PRAGMA
table_info column-presence check (idempotent against an already-migrated
file), mirroring event-ledger.js and run-state.js. A fresh store now
stamps user_version 2; a pre-existing file upgrades in place with every
row preserved and tenant_id NULL. No consumer reads or writes the column
yet, so self-host behavior is byte-identical.

Closes #6597

Author: nghetienhiep

packages/loopover-miner/lib/governor-ledger.js

@@ -90,6 +90,19 @@ function rowToDecision(row) {
   };
 }
 
+// v1 -> v2 (#4939): additive tenant-scoping column, a prerequisite for any hosted, multi-tenant use of this
+// same store's logic. NULL for every row today -- self-host behavior is byte-identical, since nothing reads or
+// writes it yet (no consumer exists until a future hosted deployment populates it). Same defensive
+// column-presence guard as this file's sibling stores' own additive migrations (e.g. event-ledger.js's
+// tenant_id addition).
+function addTenantIdColumn(db) {
+  const hasTenantIdColumn = db
+    .prepare("PRAGMA table_info(governor_events)")
+    .all()
+    .some((column) => column.name === "tenant_id");
+  if (!hasTenantIdColumn) db.exec("ALTER TABLE governor_events ADD COLUMN tenant_id TEXT");
+}
+
 /**
  * Opens the append-only governor ledger, creating the table on first use. Rows are returned in ascending `id`
  * order (insertion order). (#2328)
@@ -113,8 +126,8 @@ export function initGovernorLedger(dbPath = resolveGovernorLedgerDbPath()) {
     )
   `);
   db.exec("CREATE INDEX IF NOT EXISTS idx_governor_events_repo ON governor_events (repo_full_name, id)");
-  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations (none yet).
-  applySchemaMigrations(db, []);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations.
+  applySchemaMigrations(db, [addTenantIdColumn]);
   // Opt-in retention (#4834): prune aged/excess rows when an operator has enabled it; a no-op by default.
   pruneLedgerByRetention(db, GOVERNOR_LEDGER_RETENTION_SPEC, resolveLedgerRetentionPolicy(), Date.now());
 

packages/loopover-miner/lib/plan-store.js

@@ -143,6 +143,19 @@ function rowToRecord(row) {
   return { planId: row.plan_id, plan, status: row.status, updatedAt: row.updated_at };
 }
 
+// v1 -> v2 (#4939): additive tenant-scoping column, a prerequisite for any hosted, multi-tenant use of this
+// same store's logic. NULL for every row today -- self-host behavior is byte-identical, since nothing reads or
+// writes it yet (no consumer exists until a future hosted deployment populates it). Same defensive
+// column-presence guard as the package's sibling stores' own additive migrations (e.g. event-ledger.js's
+// tenant_id addition).
+function addTenantIdColumn(db) {
+  const hasTenantIdColumn = db
+    .prepare("PRAGMA table_info(miner_plans)")
+    .all()
+    .some((column) => column.name === "tenant_id");
+  if (!hasTenantIdColumn) db.exec("ALTER TABLE miner_plans ADD COLUMN tenant_id TEXT");
+}
+
 /**
  * Opens the local plan store, creating the table on first use. `savePlan` is a single atomic INSERT…ON CONFLICT
  * upsert keyed by `plan_id`; the plan JSON is validated on save AND re-validated on load, so a corrupted row is
@@ -165,8 +178,8 @@ export function openPlanStore(dbPath = resolvePlanStoreDbPath()) {
       updated_at TEXT NOT NULL
     )
   `);
-  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations (none yet).
-  applySchemaMigrations(db, []);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations.
+  applySchemaMigrations(db, [addTenantIdColumn]);
 
   const saveStatement = db.prepare(`
     INSERT INTO miner_plans (plan_id, plan_json, status, updated_at)

test/unit/miner-governor-ledger.test.ts

@@ -15,6 +15,7 @@ import {
   readGovernorEvents,
   resolveGovernorLedgerDbPath,
 } from "../../packages/loopover-miner/lib/governor-ledger.js";
+import { readSchemaVersion } from "../../packages/loopover-miner/lib/schema-version.js";
 
 const roots: string[] = [];
 const ledgers: Array<{ close(): void }> = [];
@@ -194,6 +195,82 @@ describe("loopover-miner governor ledger (#2328)", () => {
     });
   });
 
+  describe("schema migrations", () => {
+    it("stamps user_version 2 on a fresh store (baseline 1 plus the tenant_id migration)", () => {
+      const ledger = tempLedger();
+      const readonly = new DatabaseSync(ledger.dbPath, { readOnly: true });
+      expect(readSchemaVersion(readonly)).toBe(2);
+      const columns = readonly.prepare("PRAGMA table_info(governor_events)").all() as Array<{ name: string }>;
+      expect(columns.map((column) => column.name)).toContain("tenant_id");
+      readonly.close();
+    });
+
+    it("v1 -> v2 (#4939): upgrades a pre-existing file in place, adding tenant_id NULL and preserving every row", () => {
+      const root = mkdtempSync(join(tmpdir(), "loopover-miner-governor-legacy-v1-"));
+      roots.push(root);
+      const dbPath = join(root, "legacy-v1.sqlite3");
+      const legacy = new DatabaseSync(dbPath);
+      legacy.exec(`
+        CREATE TABLE governor_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts TEXT NOT NULL,
+          event_type TEXT NOT NULL,
+          repo_full_name TEXT,
+          action_class TEXT NOT NULL,
+          decision TEXT NOT NULL,
+          reason TEXT NOT NULL,
+          payload_json TEXT NOT NULL
+        )
+      `);
+      legacy.exec("PRAGMA user_version = 1");
+      legacy.exec(
+        "INSERT INTO governor_events (ts, event_type, repo_full_name, action_class, decision, reason, payload_json) VALUES ('2026-01-01T00:00:00.000Z', 'allowed', 'acme/widgets', 'analyze', 'allow', 'within budget', '{}')",
+      );
+      legacy.close();
+
+      const ledger = initGovernorLedger(dbPath);
+      ledgers.push(ledger);
+      // The pre-existing row survives the upgrade and reads back unchanged.
+      expect(ledger.readGovernorEvents().map((event) => event.reason)).toEqual(["within budget"]);
+      const readonly = new DatabaseSync(dbPath, { readOnly: true });
+      expect(readSchemaVersion(readonly)).toBe(2);
+      const columns = readonly.prepare("PRAGMA table_info(governor_events)").all() as Array<{ name: string }>;
+      expect(columns.map((column) => column.name)).toContain("tenant_id");
+      const row = readonly
+        .prepare("SELECT tenant_id FROM governor_events WHERE repo_full_name = 'acme/widgets'")
+        .get() as { tenant_id: string | null };
+      expect(row.tenant_id).toBeNull();
+      readonly.close();
+    });
+
+    it("REGRESSION: a v1 file that (unusually) already carries tenant_id is not re-altered into a duplicate-column error", () => {
+      const root = mkdtempSync(join(tmpdir(), "loopover-miner-governor-legacy-partial-v2-"));
+      roots.push(root);
+      const dbPath = join(root, "legacy-partial-v2.sqlite3");
+      const legacy = new DatabaseSync(dbPath);
+      legacy.exec(`
+        CREATE TABLE governor_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts TEXT NOT NULL,
+          event_type TEXT NOT NULL,
+          repo_full_name TEXT,
+          action_class TEXT NOT NULL,
+          decision TEXT NOT NULL,
+          reason TEXT NOT NULL,
+          payload_json TEXT NOT NULL,
+          tenant_id TEXT
+        )
+      `);
+      legacy.exec("PRAGMA user_version = 1");
+      legacy.close();
+
+      expect(() => {
+        const ledger = initGovernorLedger(dbPath);
+        ledgers.push(ledger);
+      }).not.toThrow();
+    });
+  });
+
   it("uses the default singleton ledger helpers and closes cleanly", () => {
     const root = mkdtempSync(join(tmpdir(), "loopover-miner-governor-default-"));
     roots.push(root);

test/unit/miner-plan-store.test.ts

@@ -10,6 +10,7 @@ import {
   resolvePlanStoreDbPath,
 } from "../../packages/loopover-miner/lib/plan-store.js";
 import type { PlanDag } from "../../packages/loopover-miner/lib/plan-store.js";
+import { readSchemaVersion } from "../../packages/loopover-miner/lib/schema-version.js";
 
 const roots: string[] = [];
 const stores: Array<{ close(): void }> = [];
@@ -172,4 +173,72 @@ describe("loopover-miner plan store (#2318)", () => {
     expect(() => store.loadPlan("p1")).toThrow("corrupted_plan_row");
     expect(() => store.listPlans()).toThrow("corrupted_plan_row");
   });
+
+  describe("schema migrations", () => {
+    it("stamps user_version 2 on a fresh store (baseline 1 plus the tenant_id migration)", () => {
+      const store = tempStore();
+      const readonly = new DatabaseSync(store.dbPath, { readOnly: true });
+      expect(readSchemaVersion(readonly)).toBe(2);
+      const columns = readonly.prepare("PRAGMA table_info(miner_plans)").all() as Array<{ name: string }>;
+      expect(columns.map((column) => column.name)).toContain("tenant_id");
+      readonly.close();
+    });
+
+    it("v1 -> v2 (#4939): upgrades a pre-existing file in place, adding tenant_id NULL and preserving every row", () => {
+      const root = mkdtempSync(join(tmpdir(), "loopover-miner-plan-store-legacy-v1-"));
+      roots.push(root);
+      const dbPath = join(root, "legacy-v1.sqlite3");
+      const legacy = new DatabaseSync(dbPath);
+      legacy.exec(`
+        CREATE TABLE miner_plans (
+          plan_id TEXT PRIMARY KEY,
+          plan_json TEXT NOT NULL,
+          status TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed')),
+          updated_at TEXT NOT NULL
+        )
+      `);
+      legacy.exec("PRAGMA user_version = 1");
+      legacy
+        .prepare("INSERT INTO miner_plans VALUES (?, ?, ?, ?)")
+        .run("p1", JSON.stringify(PLAN), "running", "2026-01-01T00:00:00.000Z");
+      legacy.close();
+
+      const store = openPlanStore(dbPath);
+      stores.push(store);
+      // The pre-existing row survives the upgrade and reads back unchanged.
+      expect(store.loadPlan("p1")?.status).toBe("running");
+      const readonly = new DatabaseSync(dbPath, { readOnly: true });
+      expect(readSchemaVersion(readonly)).toBe(2);
+      const columns = readonly.prepare("PRAGMA table_info(miner_plans)").all() as Array<{ name: string }>;
+      expect(columns.map((column) => column.name)).toContain("tenant_id");
+      const row = readonly.prepare("SELECT tenant_id FROM miner_plans WHERE plan_id = 'p1'").get() as {
+        tenant_id: string | null;
+      };
+      expect(row.tenant_id).toBeNull();
+      readonly.close();
+    });
+
+    it("REGRESSION: a v1 file that (unusually) already carries tenant_id is not re-altered into a duplicate-column error", () => {
+      const root = mkdtempSync(join(tmpdir(), "loopover-miner-plan-store-legacy-partial-v2-"));
+      roots.push(root);
+      const dbPath = join(root, "legacy-partial-v2.sqlite3");
+      const legacy = new DatabaseSync(dbPath);
+      legacy.exec(`
+        CREATE TABLE miner_plans (
+          plan_id TEXT PRIMARY KEY,
+          plan_json TEXT NOT NULL,
+          status TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed')),
+          updated_at TEXT NOT NULL,
+          tenant_id TEXT
+        )
+      `);
+      legacy.exec("PRAGMA user_version = 1");
+      legacy.close();
+
+      expect(() => {
+        const store = openPlanStore(dbPath);
+        stores.push(store);
+      }).not.toThrow();
+    });
+  });
 });