@cosmicdrift/kumiko-framework 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/__tests__/schema-cli-status.integration.test.ts

@@ -65,7 +65,8 @@ describe("runSchemaCli status", () => {
     writeMigration("0001_init.sql", `SELECT 1;`);
     const { out, lines } = captureOut();
     const code = await runSchemaCli(["status"], appDir, out);
-    expect(code).toBe(0);
+    // Exit 1 = pending-drift erkannt (1 Migration lokal, 0 applied); status gated CI non-zero.
+    expect(code).toBe(1);
     const joined = lines.join("\n");
     expect(joined).toContain("0 applied");
     expect(joined).toContain("1 pending");

package/src/bun-db/__tests__/extract-table-info.test.ts

@@ -0,0 +1,72 @@
+// extractTableInfo discriminator-shadow regression.
+//
+// EntityTableMeta carries a `source: "managed" | "unmanaged"` discriminator.
+// table() (dialect) spreads the column handles as enumerable props over the
+// meta object, so an entity field literally named `source` overwrote the
+// discriminator → extractTableInfo failed the meta check, fell into the (dead)
+// drizzle branch, and typed timestamptz columns via getSQLType() as
+// "timestamp with time zone". prepareValue only serializes Temporal.Instant for
+// "timestamptz" → a raw Temporal reached postgres-js → "Cannot use valueOf" on
+// every create of such an entity (e.g. pattern-storage's pattern-file).
+
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "../../db/table-builder";
+import { extractTableInfo, resolveConflictColumns } from "../query";
+
+describe("extractTableInfo — EntityTableMeta discriminator is shadow-proof", () => {
+  test("an entity field named `source` does not shadow the discriminator", () => {
+    const table = buildEntityTable("patternFile", {
+      fields: {
+        path: { type: "text", required: true },
+        source: { type: "text", required: true },
+      },
+    });
+    const info = extractTableInfo(table);
+    // The framework-canonical pgType the bun-db serializer matches on — NOT the
+    // drizzle getSQLType() spelling "timestamp with time zone".
+    expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
+    // The user-defined `source` column is still present + correctly typed.
+    expect(info.pgTypeOf("source")).toBe("text");
+  });
+
+  test.each([
+    "columns",
+    "tableName",
+    "indexes",
+  ])("an entity field named `%s` (another meta key) also does not shadow it", (fieldName) => {
+    const table = buildEntityTable("thing", {
+      fields: { [fieldName]: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
+  });
+
+  test("control entity without a colliding field is unaffected", () => {
+    const table = buildEntityTable("note", {
+      fields: { title: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
+  });
+});
+
+describe("resolveConflictColumns — shadow-proof PK inference", () => {
+  test("an entity field named `columns` does not shadow the inferred primary key", () => {
+    const table = buildEntityTable("thing", {
+      fields: { columns: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    // No explicit conflictKeys → infer the real PK (`id`) from the symbol-based
+    // meta. Reading `table.columns` directly would yield the `columns` field
+    // handle (the bug this guards), not the PK list.
+    expect(resolveConflictColumns(table, info, undefined)).toEqual(["id"]);
+  });
+
+  test("explicit conflictKeys are mapped through columnOf (control)", () => {
+    const table = buildEntityTable("thing", {
+      fields: { slug: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    expect(resolveConflictColumns(table, info, ["slug"])).toEqual(["slug"]);
+  });
+});

package/src/bun-db/query.ts

@@ -37,32 +37,34 @@ function snakeToCamel(key: string): string {
 import type { BunDbRunner } from "./connection";
 
 // Drizzle-pgTable-Inspection via raw Symbol-access (kein drizzle-orm import).
-// drizzle stores the table name unter `Symbol.for("kumiko:schema:Name")` und die
-// column-map unter `Symbol.for("kumiko:schema:Columns")`.
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-
-function getTableName(table: unknown): string | null {
-  if (typeof table !== "object" || table === null) return null;
-  const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
-  return typeof name === "string" ? name : null;
-}
-
-function extractDrizzleColumns(table: unknown): Map<string, { name: string; sqlType?: string }> {
-  const out = new Map<string, { name: string; sqlType?: string }>();
-  if (typeof table !== "object" || table === null) return out;
-  const cols = (table as Record<symbol, unknown>)[KUMIKO_COLUMNS_SYMBOL];
-  if (typeof cols !== "object" || cols === null) return out;
-  for (const [key, val] of Object.entries(cols as Record<string, unknown>)) {
-    if (typeof val !== "object" || val === null) continue;
-    const colObj = val as { name?: unknown; getSQLType?: () => string };
-    const colName = colObj.name;
-    if (typeof colName !== "string") continue;
-    // Drizzle's getSQLType uses `this` — call as method on colObj.
-    const sqlType = typeof colObj.getSQLType === "function" ? colObj.getSQLType() : undefined;
-    out.set(key, { name: colName, ...(sqlType !== undefined && { sqlType }) });
-  }
-  return out;
+// table() (dialect) stores the canonical, shadow-proof EntityTableMeta under
+// `Symbol.for("kumiko:schema:Meta")`. The column handles on the table object are
+// enumerable props, so an entity field named `source`/`columns`/`tableName`/…
+// would overwrite the matching meta key — reading the meta from the symbol is
+// the only collision-safe path.
+const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
+
+function isEntityTableMeta(v: unknown): v is EntityTableMeta {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    typeof (v as EntityTableMeta).tableName === "string" &&
+    Array.isArray((v as EntityTableMeta).columns) &&
+    Array.isArray((v as EntityTableMeta).indexes) &&
+    ((v as EntityTableMeta).source === "managed" || (v as EntityTableMeta).source === "unmanaged")
+  );
+}
+
+// Resolve any framework table input to its canonical EntityTableMeta:
+//  - table()/buildEntityTable outputs carry it under KUMIKO_META_SYMBOL, immune
+//    to a column-handle shadowing a meta key.
+//  - buildEntityTableMeta / defineUnmanagedTable return a plain meta with no
+//    handle-spread, so its structural shape is itself unshadowable.
+function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
+  if (table === null || typeof table !== "object") return undefined;
+  const fromSymbol = (table as Record<symbol, unknown>)[KUMIKO_META_SYMBOL];
+  if (isEntityTableMeta(fromSymbol)) return fromSymbol;
+  return isEntityTableMeta(table) ? table : undefined;
 }
 
 // `db` Input akzeptiert drei Shapes:
@@ -218,69 +220,30 @@ export type TableInfo = {
 };
 
 export function extractTableInfo(table: TableLike): TableInfo {
-  // EntityTableMeta discriminator: hat source-property "managed" | "unmanaged"
-  if (
-    table !== null &&
-    typeof table === "object" &&
-    "source" in table &&
-    (table.source === "managed" || table.source === "unmanaged")
-  ) {
-    const meta = table as EntityTableMeta;
-    const colByField = new Map<string, string>();
-    const fieldByCol = new Map<string, string>();
-    const typeByCol = new Map<string, string>();
-    const bigintModeByCol = new Map<string, "number" | "bigint">();
-    for (const c of meta.columns) {
-      typeByCol.set(c.name, c.pgType);
-      if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
-      // EntityTableMeta column names are snake_case. Map snake → snake AND
-      // derive a camelCase JS field-name so result rows can be renamed back
-      // to the API shape (`aggregate_id` → `aggregateId`).
-      colByField.set(c.name, c.name);
-      const camel = snakeToCamel(c.name);
-      if (camel !== c.name) colByField.set(camel, c.name);
-      fieldByCol.set(c.name, camel === c.name ? c.name : camel);
-    }
-    return {
-      name: meta.tableName,
-      columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
-      pgTypeOf: (col) => typeByCol.get(col),
-      bigintJsModeOf: (col) => bigintModeByCol.get(col),
-      fieldOf: (col) => fieldByCol.get(col) ?? snakeToCamel(col),
-      hasColumn: (fieldOrColumn) => colByField.has(fieldOrColumn) || fieldByCol.has(fieldOrColumn),
-    };
-  }
-  // drizzle pgTable: tableName via Symbol.for("kumiko:schema:Name"), columns via
-  // enumerable properties (jeder col-object hat .name + .getSQLType()).
-  // Wir lesen Beide via raw Symbol/Property-access — kein drizzle-orm import.
-  const name = getTableName(table);
-  if (!name) {
+  const meta = asEntityTableMeta(table);
+  if (!meta) {
     throw new Error(
-      "bun-db.extractTableInfo: table-Argument ist weder EntityTableMeta noch drizzle pgTable",
+      "bun-db.extractTableInfo: table is not a kumiko EntityTableMeta — " +
+        "build it via buildEntityTable / buildEntityTableMeta / table().",
     );
   }
-  const cols = extractDrizzleColumns(table);
   const colByField = new Map<string, string>();
   const fieldByCol = new Map<string, string>();
   const typeByCol = new Map<string, string>();
   const bigintModeByCol = new Map<string, "number" | "bigint">();
-  if (
-    table !== null &&
-    typeof table === "object" &&
-    "columns" in table &&
-    Array.isArray((table as EntityTableMeta).columns)
-  ) {
-    for (const c of (table as EntityTableMeta).columns) {
-      if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
-    }
-  }
-  for (const [field, { name: colName, sqlType }] of cols) {
-    colByField.set(field, colName);
-    fieldByCol.set(colName, field);
-    if (sqlType) typeByCol.set(colName, sqlType);
+  for (const c of meta.columns) {
+    typeByCol.set(c.name, c.pgType);
+    if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
+    // EntityTableMeta column names are snake_case. Map snake → snake AND
+    // derive a camelCase JS field-name so result rows can be renamed back
+    // to the API shape (`aggregate_id` → `aggregateId`).
+    colByField.set(c.name, c.name);
+    const camel = snakeToCamel(c.name);
+    if (camel !== c.name) colByField.set(camel, c.name);
+    fieldByCol.set(c.name, camel === c.name ? c.name : camel);
   }
   return {
-    name,
+    name: meta.tableName,
     columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
     pgTypeOf: (col) => typeByCol.get(col),
     bigintJsModeOf: (col) => bigintModeByCol.get(col),
@@ -394,7 +357,7 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
     ) {
       // Bun.SQL / some drivers return int4 as bigint or numeric string.
       // Drizzle coerced to number for numberField columns — match that.
-      const n = typeof value === "bigint" ? Number(value) : Number(value);
+      const n = Number(value);
       if (!Number.isNaN(n)) coerced = n;
     }
     const fieldName = info.fieldOf(key);
@@ -731,17 +694,9 @@ function insertEntries(info: TableInfo, values: Record<string, unknown>): Insert
     });
 }
 
-function isEntityTableMeta(table: unknown): table is EntityTableMeta {
-  return (
-    typeof table === "object" &&
-    table !== null &&
-    "source" in table &&
-    (table.source === "managed" || table.source === "unmanaged") &&
-    "columns" in table
-  );
-}
-
-function resolveConflictColumns(
+// Exported for the shadow-proof regression test — `table.columns` would be the
+// drizzle handle (not the PK list) when an entity has a field named `columns`.
+export function resolveConflictColumns(
   table: TableLike,
   info: TableInfo,
   conflictKeys: readonly string[] | undefined,
@@ -749,8 +704,11 @@ function resolveConflictColumns(
   if (conflictKeys !== undefined && conflictKeys.length > 0) {
     return conflictKeys.map((field) => info.columnOf(field));
   }
-  if (isEntityTableMeta(table)) {
-    const pks = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  // Read the shadow-proof meta — `table.columns` directly would be the handle
+  // object when an entity has a field named `columns`.
+  const meta = asEntityTableMeta(table);
+  if (meta) {
+    const pks = meta.columns.filter((c) => c.primaryKey).map((c) => c.name);
     if (pks.length > 0) return pks;
   }
   if (info.hasColumn("id")) return [info.columnOf("id")];

package/src/db/__tests__/source-shadow-create.integration.test.ts

@@ -0,0 +1,54 @@
+// End-to-end regression for the EntityTableMeta discriminator shadow.
+//
+// An entity field literally named `source` overwrote the `source:
+// "managed"|"unmanaged"` discriminator on the table-meta. extractTableInfo
+// then failed its meta check, fell into the dead drizzle branch, and typed the
+// timestamptz base-columns as "timestamp with time zone" (getSQLType spelling).
+// prepareValue only serializes Temporal.Instant for "timestamptz", so a raw
+// Temporal reached postgres-js → "Cannot use valueOf" on every create.
+//
+// extract-table-info.test.ts pins the proximate cause (pgTypeOf stays
+// "timestamptz"). This proves the actual create-path no longer crashes — the
+// integration proof the unit test cannot give.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertOne, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createTextField } from "../../engine";
+import { setupTestStack, type TestStack, unsafeCreateEntityTable } from "../../stack";
+
+const sourceEntity = createEntity({
+  table: "ssc_source",
+  fields: {
+    // `source` collides with the EntityTableMeta discriminator key.
+    source: createTextField({ required: true }),
+  },
+});
+const sourceTable = buildEntityTable("source-row", sourceEntity);
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await unsafeCreateEntityTable(stack.db, sourceEntity, "source-row");
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("entity with a `source` field — create-path is shadow-proof", () => {
+  test("insertOne serializes the timestamptz inserted_at — no Temporal valueOf crash", async () => {
+    // Passing a real Temporal.Instant exercises the timestamptz serializer
+    // path that the shadow used to bypass. Pre-fix this threw "Cannot use
+    // valueOf"; post-fix the row persists and round-trips as a Temporal.Instant.
+    await insertOne(stack.db, sourceTable, {
+      source: "import",
+      tenantId: "00000000-0000-4000-8000-000000000001",
+      insertedAt: Temporal.Instant.from("2026-01-15T12:00:00Z"),
+    });
+
+    const rows = await selectMany(stack.db, sourceTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["source"]).toBe("import");
+    expect(rows[0]?.["insertedAt"]).toBeInstanceOf(Temporal.Instant);
+  });
+});

package/src/db/__tests__/sql-inventory.test.ts

@@ -1,5 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { formatReport, isRawSqlAllowed, joinPath, scanRepo } from "../sql-inventory";
+import {
+  formatReport,
+  isRawSqlAllowed,
+  joinPath,
+  scanRepo,
+  toBaselineJson,
+} from "../sql-inventory";
 
 const cleanups: string[] = [];
 
@@ -53,4 +59,23 @@ describe("sql-inventory", () => {
     expect(report.summary.byBucket.disallowed).toBeGreaterThanOrEqual(1);
     expect(formatReport(report)).toContain("sql inventory");
   });
+
+  test("toBaselineJson normalizes machine-specific root + scannedAt, keeps the rest", async () => {
+    const root = await tempRepo({
+      "packages/framework/src/handlers/bad.ts": `export async function y(db: unknown) {
+  return asRawClient(db).unsafe("DELETE FROM read_users");
+}`,
+    });
+
+    const report = await scanRepo(root);
+    expect(report.root).toBe(root);
+    expect(report.scannedAt).not.toBe("");
+
+    const parsed = JSON.parse(toBaselineJson(report));
+    expect(parsed.root).toBe(".");
+    expect(parsed.scannedAt).toBe("");
+    expect(parsed.root).not.toContain(root);
+    expect(parsed.summary.disallowed).toBe(report.summary.disallowed);
+    expect(parsed.hits).toHaveLength(report.hits.length);
+  });
 });

package/src/db/__tests__/table-builder-indexes.test.ts

@@ -147,6 +147,21 @@ describe("validateBoot — entity.indexes", () => {
     expect(() => validateBoot([feature])).toThrow(/redundant/);
   });
 
+  test("single-column UNIQUE auf tenantId ist erlaubt (1:1-Constraint)", () => {
+    // Der `&& !def.unique`-Branch in entity-handler.ts: ein UNIQUE-Index auf
+    // tenantId allein ist kein redundanter Read-Index, sondern ein
+    // 1:1-Constraint (genau ein Row pro Tenant). Nur die NON-unique-Variante
+    // oben ist redundant — beide Hälften der Bedingung sind damit gepinnt,
+    // sonst fliegt der Branch beim nächsten Revert/Refactor stumm raus.
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", {
+        fields: { title: createTextField({}) },
+        indexes: [{ unique: true, columns: ["tenantId"] }],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
   test("composite mit tenantId ist OK (z.B. für unique über 3 Cols)", () => {
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { testTenantId } from "../../stack";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+// Tenant-isolation: a caller-supplied `where.tenantId` must NEVER override the
+// enforced tenant scope. These tests drive the real query-builder against a
+// recording fake runner and assert on the emitted SQL + bound values — no
+// Postgres needed because the bug lives entirely in the WHERE-object merge.
+
+const entity = createEntity({
+  table: "merge_items",
+  fields: { name: createTextField({ required: true }) },
+});
+const table = buildEntityTable("mergeItem", entity);
+
+const own = testTenantId(1);
+const foreign = testTenantId(2);
+
+type Captured = { sql: string; values: readonly unknown[] };
+
+function recordingDb(captured: Captured[]) {
+  return {
+    unsafe: async (sql: string, values: readonly unknown[]) => {
+      captured.push({ sql, values });
+      return [] as unknown[];
+    },
+  };
+}
+
+describe("tenant-db WHERE merge — caller cannot override tenant scope", () => {
+  test("selectMany ignores a foreign where.tenantId and keeps the IN-scope filter", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.selectMany(table, { tenantId: foreign });
+
+    expect(captured).toHaveLength(1);
+    // The enforced scope is an IN over [own, SYSTEM_TENANT_ID]; the foreign id
+    // must not appear as a sole-equality predicate (the pre-fix bug).
+    expect(captured[0]?.sql).toMatch(/tenant_id" IN /i);
+    expect(captured[0]?.values).toContain(own);
+    expect(captured[0]?.values).not.toContain(foreign);
+  });
+
+  test("updateMany forces own tenantId even when where.tenantId is foreign", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.updateMany(table, { name: "x" }, { tenantId: foreign });
+
+    const update = captured.find((c) => /UPDATE/i.test(c.sql));
+    expect(update).toBeDefined();
+    expect(update?.values).toContain(own);
+    expect(update?.values).not.toContain(foreign);
+  });
+
+  test("deleteMany forces own tenantId even when where.tenantId is foreign", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.deleteMany(table, { tenantId: foreign });
+
+    const del = captured.find((c) => /DELETE/i.test(c.sql));
+    expect(del).toBeDefined();
+    expect(del?.values).toContain(own);
+    expect(del?.values).not.toContain(foreign);
+  });
+
+  test("a non-tenantId where predicate is still applied alongside the scope", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.selectMany(table, { name: "needle" });
+
+    expect(captured[0]?.sql).toMatch(/tenant_id" IN /i);
+    expect(captured[0]?.values).toContain("needle");
+    expect(captured[0]?.values).toContain(own);
+  });
+});

package/src/db/dialect.ts

@@ -40,6 +40,11 @@ export type ColumnHandle = {
 
 const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
 const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
+// Shadow-proof handle on the EntityTableMeta. The column handles below are
+// spread as enumerable props, so an entity field named `source`/`columns`/
+// `tableName`/… would overwrite the matching meta key. extractTableInfo reads
+// the canonical meta from this symbol instead of the (shadowable) props.
+const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 
 // SchemaTable — opaque shape with both EntityTableMeta + Symbol-based
 // introspection. Returned by `table(...)`.
@@ -469,6 +474,7 @@ export function table<TCols extends ColumnMap>(
   const out = Object.assign({}, base, handles, {
     [KUMIKO_NAME_SYMBOL]: tableName,
     [KUMIKO_COLUMNS_SYMBOL]: handles,
+    [KUMIKO_META_SYMBOL]: base,
   }) as SchemaTable;
   return out;
 }

package/src/db/entity-table-meta.ts

@@ -253,7 +253,7 @@ function fieldToColumnMeta(
   }
 }
 
-function resolveTableName(
+export function resolveTableName(
   entityName: string,
   entity: EntityDefinition,
   featureName: string | undefined,

package/src/db/queries/event-store.ts

@@ -81,6 +81,22 @@ export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string):
   return rows[0]?.v ?? 0;
 }
 
+/** tenant_id the aggregate's events were written under — no membership/tenant
+ *  filter. A r.systemScope() aggregate (e.g. user) lives in whichever tenant
+ *  its creating executor used, which need not be a tenant the subject holds a
+ *  membership in. Returns null for unknown streams. */
+export async function selectAggregateStreamTenant(
+  db: AnyDb,
+  aggregateId: string,
+  aggregateType: string,
+): Promise<string | null> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
+    [aggregateId, aggregateType],
+  )) as ReadonlyArray<{ t: string | null }>;
+  return rows[0]?.t ?? null;
+}
+
 export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   const rows = (await asRawClient(db).unsafe(
     `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,
@@ -91,14 +107,9 @@ export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   return BigInt(raw);
 }
 
-/** Head event id for lag metrics — same aggregate as selectEventsHighWaterMark. */
+/** Head event id for lag metrics — alias for selectEventsHighWaterMark. */
 export async function selectEventsHeadId(db: AnyDb): Promise<bigint> {
-  const rows = (await asRawClient(db).unsafe(
-    `SELECT COALESCE(MAX(id), 0)::bigint AS head FROM kumiko_events`,
-  )) as ReadonlyArray<{ head?: bigint | string | null }>;
-  const raw = rows[0]?.head;
-  if (typeof raw === "bigint") return raw;
-  return BigInt(raw ?? 0);
+  return selectEventsHighWaterMark(db);
 }
 
 export async function selectNextEventIdAfter(db: AnyDb, afterId: bigint): Promise<bigint | null> {

package/src/db/sql-inventory.ts

@@ -176,6 +176,15 @@ export async function scanRepo(repoRoot: string): Promise<SqlInventoryReport> {
   };
 }
 
+// Serialize for the checked-in baseline. `root` (absolute scan path) and
+// `scannedAt` (run timestamp) are machine-/run-specific noise that churned the
+// baseline on every regen; --compare-baseline reads only summary.disallowed.
+// Pin them to stable placeholders so the committed file is reproducible.
+export function toBaselineJson(report: SqlInventoryReport): string {
+  const stable: SqlInventoryReport = { ...report, root: ".", scannedAt: "" };
+  return `${JSON.stringify(stable, null, 2)}\n`;
+}
+
 export function formatReport(report: SqlInventoryReport): string {
   const lines: string[] = [
     "--- sql inventory ---",

package/src/db/tenant-db.ts

@@ -133,15 +133,18 @@ export function createTenantDb(
 
   // Reads see own-tenant rows + reference data (tenantId === SYSTEM_TENANT_ID).
   // Writes never touch reference rows — those are system-mode only.
+  // The tenant filter is spread LAST so a caller-supplied `where.tenantId`
+  // cannot override the enforced scope — overriding it would be a
+  // tenant-isolation bypass.
   function readWhere(table: Table, where?: WhereObject): WhereObject | undefined {
     if (!hasTenantColumn(table) || mode === "system") return where;
     const tenantFilter: WhereObject = { tenantId: [tenantId, SYSTEM_TENANT_ID] };
-    return where ? { ...tenantFilter, ...where } : tenantFilter;
+    return where ? { ...where, ...tenantFilter } : tenantFilter;
   }
 
   function writeWhere(table: Table, where: WhereObject): WhereObject {
     if (!hasTenantColumn(table) || mode === "system") return where;
-    return { tenantId, ...where };
+    return { ...where, tenantId };
   }
 
   function insertValues(table: Table, data: Record<string, unknown>): Record<string, unknown> {