@cosmicdrift/kumiko-framework 0.45.1 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.45.1",
+  "version": "0.47.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.40.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.45.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"

package/src/db/__tests__/collect-table-metas.test.ts

@@ -2,9 +2,10 @@ import { describe, expect, test } from "bun:test";
 import { defineFeature } from "../../engine/define-feature";
 import { createEntity, createTextField } from "../../engine/factories";
 import { collectTableMetas } from "../collect-table-metas";
-import { integer, type SchemaTable, table, text, uuid } from "../dialect";
+import { integer, jsonb, type SchemaTable, table, text, uniqueIndex, uuid } from "../dialect";
 import { defineUnmanagedTable } from "../entity-table-meta";
-import { buildEntityTable } from "../table-builder";
+import { asEntityTableMeta } from "../query";
+import { buildBaseColumns, buildEntityTable } from "../table-builder";
 
 function exampleEntity() {
   return createEntity({
@@ -124,3 +125,60 @@ describe("collectTableMetas (#255)", () => {
     expect(() => collectTableMetas([feature])).toThrow(/no EntityTableMeta/);
   });
 });
+
+describe("collectTableMetas — r.entity backing table (#347)", () => {
+  const richWidgetTable = table(
+    "read_widgets",
+    {
+      ...buildBaseColumns(false, "uuid"),
+      name: text("name").notNull(),
+      tag: jsonb("tag").notNull(), // ride-along: no entity field declares this
+    },
+    (t) => [uniqueIndex("read_widgets_name_unique").on(t.name)],
+  ) as unknown as SchemaTable;
+
+  function widgetEntity() {
+    return createEntity({
+      table: "read_widgets",
+      fields: { name: createTextField({ required: true }) },
+    });
+  }
+
+  test("ride-along column + index from the backing table reach the generated meta", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("widget", widgetEntity(), { table: richWidgetTable });
+    });
+    const meta = collectTableMetas([feature]).find((m) => m.tableName === "read_widgets");
+    expect(meta?.columns.map((c) => c.name)).toContain("tag");
+    expect(meta?.indexes.map((i) => i.name)).toContain("read_widgets_name_unique");
+  });
+
+  test("generate draws from the backing table itself — one source (the #255 invariant)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("widget", widgetEntity(), { table: richWidgetTable });
+    });
+    const meta = collectTableMetas([feature]).find((m) => m.tableName === "read_widgets");
+    // Identical to the table the test-stack push + executor use → they cannot drift.
+    expect(meta).toEqual(asEntityTableMeta(richWidgetTable));
+  });
+
+  test("throws when the backing table is missing a field's column (superset violated)", () => {
+    const thin = createEntity({
+      table: "read_widgets",
+      fields: { name: createTextField({ required: true }) },
+    });
+    const rich = createEntity({
+      table: "read_widgets",
+      fields: {
+        name: createTextField({ required: true }),
+        extra: createTextField({ required: true }),
+      },
+    });
+    // Backing table built from the THIN entity lacks the `extra` column.
+    const backing = buildEntityTable("widget", thin) as unknown as SchemaTable;
+    const feature = defineFeature("test", (r) => {
+      r.entity("widget", rich, { table: backing });
+    });
+    expect(() => collectTableMetas([feature])).toThrow(/missing column "extra"/);
+  });
+});

package/src/db/collect-table-metas.ts

@@ -7,7 +7,11 @@
 // crashte (#255).
 
 import type { FeatureDefinition } from "../engine/types";
-import { buildEntityTableMeta, type EntityTableMeta } from "./entity-table-meta";
+import {
+  assertBackingTableSuperset,
+  buildEntityTableMeta,
+  type EntityTableMeta,
+} from "./entity-table-meta";
 import { enumerateFeatureTableSources } from "./feature-table-sources";
 import { asEntityTableMeta } from "./query";
 
@@ -35,7 +39,23 @@ export function collectTableMetas(
   // Verhalten (gleiche Reihenfolge, gleiche buildEntityTableMeta-Optionen).
   for (const feature of features) {
     for (const [name, ent] of Object.entries(feature.entities ?? {})) {
-      const meta = buildEntityTableMeta(name, ent, { relations: feature.relations[name] });
+      const fieldMeta = buildEntityTableMeta(name, ent, { relations: feature.relations[name] });
+      // Backing table wins: it's the physical DDL truth for ride-along columns/
+      // indexes the field-DSL can't express (secrets' envelope). Validated as a
+      // superset of the field-derived meta so a field/table disagreement throws.
+      const backing = feature.entityTables?.[name];
+      let meta = fieldMeta;
+      if (backing !== undefined) {
+        const tableMeta = asEntityTableMeta(backing);
+        if (!tableMeta) {
+          throw new Error(
+            `collectTableMetas: entity "${name}" (${feature.name}) declares a backing ` +
+              "table that carries no EntityTableMeta — build it via table() / buildEntityTable.",
+          );
+        }
+        assertBackingTableSuperset(name, fieldMeta, tableMeta);
+        meta = tableMeta;
+      }
       metas.push(meta);
       byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
     }

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

@@ -406,6 +406,47 @@ function sqlExpressionText(where: unknown): string | undefined {
   return undefined;
 }
 
+// Validates that a backing Drizzle table (declared via `r.entity(name, def,
+// { table })`) is a SUPERSET of the field-derived meta: every column the
+// entity fields produce must exist on the table with the same pgType +
+// notNull. Ride-along columns/indexes the table adds on top (envelope,
+// uniqueIndex, …) are exactly the point — they pass. A field with no matching
+// physical column, or a type/nullability mismatch, is real authoring drift
+// (the table and the entity disagree on a shared column) → throw. Catches the
+// inverse of the bug this whole mechanism fixes.
+export function assertBackingTableSuperset(
+  entityName: string,
+  fieldMeta: EntityTableMeta,
+  tableMeta: EntityTableMeta,
+): void {
+  const tableCols = columnsByNameMeta(tableMeta);
+  for (const fieldCol of fieldMeta.columns) {
+    const tableCol = tableCols.get(fieldCol.name);
+    if (!tableCol) {
+      throw new Error(
+        `r.entity("${entityName}", …, { table }): the backing table ` +
+          `"${tableMeta.tableName}" is missing column "${fieldCol.name}" that the ` +
+          "entity field declares. The table must be a superset of the entity's " +
+          "fields — add the column to the table or remove the field.",
+      );
+    }
+    if (tableCol.pgType !== fieldCol.pgType || tableCol.notNull !== fieldCol.notNull) {
+      throw new Error(
+        `r.entity("${entityName}", …, { table }): column "${fieldCol.name}" ` +
+          `disagrees between entity field (${fieldCol.pgType}, ` +
+          `notNull=${fieldCol.notNull}) and backing table "${tableMeta.tableName}" ` +
+          `(${tableCol.pgType}, notNull=${tableCol.notNull}). Align them.`,
+      );
+    }
+  }
+}
+
+function columnsByNameMeta(meta: EntityTableMeta): Map<string, ColumnMeta> {
+  const m = new Map<string, ColumnMeta>();
+  for (const c of meta.columns) m.set(c.name, c);
+  return m;
+}
+
 export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMeta {
   return {
     tableName: input.tableName,

package/src/db/schema-inspection.ts

@@ -1,5 +1,20 @@
 import type { DbConnection, DbTx } from "./connection";
 
+type UnsafeFn = (s: string, p?: readonly unknown[]) => Promise<readonly Record<string, unknown>[]>;
+
+// The raw postgres `.unsafe(sql, params)` escape hatch lives at different
+// depths depending on whether `db` is a DbConnection, a Drizzle session, or
+// the bare client. Resolve it once for the low-level inspection queries below.
+function resolveUnsafeClient(db: DbConnection | DbTx): UnsafeFn {
+  const dbAny = db as unknown as {
+    $client?: { unsafe?: UnsafeFn };
+    session?: { client?: { unsafe?: UnsafeFn } };
+    unsafe?: UnsafeFn;
+  };
+  const client = dbAny.$client ?? dbAny.session?.client ?? dbAny;
+  return (client as { unsafe: UnsafeFn }).unsafe;
+}
+
 // True when `<fullyQualifiedName>` refers to an existing relation in the
 // current database. Thin wrapper over `to_regclass`, which returns NULL
 // when the name doesn't resolve — the only postgres query that cheaply
@@ -17,18 +32,7 @@ export async function tableExists(
   db: DbConnection | DbTx,
   fullyQualifiedName: string,
 ): Promise<boolean> {
-  const dbAny = db as unknown as {
-    $client?: {
-      unsafe: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
-    };
-    session?: {
-      client?: {
-        unsafe: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
-      };
-    };
-    unsafe?: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
-  };
-  const client = dbAny.$client ?? dbAny.session?.client ?? dbAny;
+  const unsafe = resolveUnsafeClient(db);
   // quote_ident-Round-trip auf SQL-Seite: ohne Quotes folded postgres
   // unquoted identifier case-insensitiv (myWidget → mywidget), während die
   // generierte DDL den Namen via quoteIdent("myWidget") → "myWidget" case-
@@ -42,10 +46,29 @@ export async function tableExists(
           [fullyQualifiedName.slice(0, dotIdx), fullyQualifiedName.slice(dotIdx + 1)],
         ]
       : [`SELECT to_regclass(quote_ident($1)) IS NOT NULL AS exists`, [fullyQualifiedName]];
-  const rows = await (
-    client as {
-      unsafe: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
-    }
-  ).unsafe(sql, params);
-  return rows[0]?.exists ?? false;
+  const rows = await unsafe(sql, params);
+  return rows[0]?.["exists"] === true;
+}
+
+// Live column names of a `public` table, snake_case as stored. Empty set for a
+// non-existent table (callers gate on tableExists first). Used by the schema-
+// drift Layer-3 column-diff to catch a migrated-but-incomplete table (a
+// snapshot column the physical table is missing) at boot instead of as a
+// runtime-500 on the first write.
+export async function columnNamesOf(
+  db: DbConnection | DbTx,
+  tableName: string,
+): Promise<ReadonlySet<string>> {
+  const unsafe = resolveUnsafeClient(db);
+  const rows = await unsafe(
+    "SELECT column_name FROM information_schema.columns " +
+      "WHERE table_schema = 'public' AND table_name = $1",
+    [tableName],
+  );
+  const names = new Set<string>();
+  for (const row of rows) {
+    const name = row["column_name"];
+    if (typeof name === "string") names.add(name);
+  }
+  return names;
 }

package/src/engine/define-feature.ts

@@ -103,6 +103,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   // Tier-2 step kinds declared via r.requires.step("webhook.send"). Q9.
   const requiredSteps = new Set<string>();
   const entities: Record<string, EntityDefinition> = {};
+  const entityTables: Record<string, unknown> = {};
   const relations: Record<string, Record<string, RelationDefinition>> = {};
   const writeHandlers: Record<string, WriteHandlerDef> = {};
   const queryHandlers: Record<string, QueryHandlerDef> = {};
@@ -223,8 +224,13 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       toggleableDefault = options.default;
     },
 
-    entity(entityName: string, definition: EntityDefinition): EntityRef {
+    entity(
+      entityName: string,
+      definition: EntityDefinition,
+      options?: { readonly table?: unknown },
+    ): EntityRef {
       entities[entityName] = definition;
+      if (options?.table !== undefined) entityTables[entityName] = options.table;
       return { name: entityName, table: definition.table ?? toTableName(entityName) };
     },
 
@@ -923,6 +929,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     requiredSteps,
     ...(toggleableDefault !== undefined && { toggleableDefault }),
     entities,
+    entityTables,
     relations,
     writeHandlers,
     queryHandlers,

package/src/engine/registry.ts

@@ -1,5 +1,10 @@
+import { asEntityTableMeta } from "../bun-db/query";
 import { applyEntityEvent } from "../db/apply-entity-event";
-import { resolveTableName } from "../db/entity-table-meta";
+import {
+  assertBackingTableSuperset,
+  buildEntityTableMeta,
+  resolveTableName,
+} from "../db/entity-table-meta";
 import { buildEntityTable } from "../db/table-builder";
 import { buildMetricName, validateMetricName } from "../observability";
 import { type QnType, qualifyEntityName } from "./qualified-name";
@@ -67,9 +72,18 @@ function buildImplicitProjection(
   entityName: string,
   entity: EntityDefinition,
   qualify: typeof qualifyEntityName,
+  backingTable?: unknown,
 ): ProjectionDefinition {
   const name = qualify(featureName, "projection", `${entityName}${IMPLICIT_PROJECTION_SUFFIX}`);
-  const drizzleTable = buildEntityTable(entityName, entity);
+  // Backing table (r.entity(name, def, { table })) is the one physical table
+  // object shared by executor-writes, rebuild-replay, test-push and
+  // collectTableMetas — restoring the #255 invariant (test-push == generate).
+  // Validated as a superset of the field-derived columns so a field/table
+  // disagreement fails at boot, not as a silent thin-vs-rich row.
+  const drizzleTable =
+    backingTable !== undefined
+      ? resolveBackingTable(entityName, entity, backingTable)
+      : buildEntityTable(entityName, entity);
   // applyEntityEvent gibt ApplyResult zurück; SingleStreamApplyFn erwartet
   // Promise<void>. Im rebuild-Pfad ist die Row irrelevant — wir discarden.
   const handler = async (
@@ -99,6 +113,27 @@ function buildImplicitProjection(
   };
 }
 
+// Validates a r.entity backing table is a superset of the entity's field-
+// derived columns, then hands it back as the projection table. The cast is a
+// system-boundary reconstitution: the table is stored as `unknown` on
+// FeatureDefinition only to keep drizzle out of the plain-data shape, and
+// asEntityTableMeta confirms the kumiko-table shape at runtime.
+function resolveBackingTable(
+  entityName: string,
+  entity: EntityDefinition,
+  backingTable: unknown,
+): ProjectionDefinition["table"] {
+  const tableMeta = asEntityTableMeta(backingTable);
+  if (!tableMeta) {
+    throw new Error(
+      `r.entity("${entityName}", …, { table }): the backing table carries no ` +
+        "EntityTableMeta — build it via table() / buildEntityTable.",
+    );
+  }
+  assertBackingTableSuperset(entityName, buildEntityTableMeta(entityName, entity), tableMeta);
+  return backingTable as ProjectionDefinition["table"];
+}
+
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
@@ -886,7 +921,13 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // mit Entity-Name registriert.
   for (const feature of features) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-      const def = buildImplicitProjection(feature.name, entityName, entity, qualify);
+      const def = buildImplicitProjection(
+        feature.name,
+        entityName,
+        entity,
+        qualify,
+        feature.entityTables?.[entityName],
+      );
       if (projectionMap.has(def.name)) {
         throw new Error(
           `Implicit projection "${def.name}" kollidiert mit einer explizit registrierten r.projection. ` +

package/src/engine/types/feature.ts

@@ -202,6 +202,13 @@ export type FeatureDefinition = {
   // (test fixtures, partial boots — see registry.test.ts "slot robustness")
   // omit them and the registry guards against that. Type follows runtime.
   readonly entities?: Readonly<Record<string, EntityDefinition>>;
+  // Optional backing Drizzle table per entity, declared via the third arg of
+  // `r.entity(name, def, { table })`. Source of truth for the physical DDL
+  // when the table carries columns/indexes the field-DSL can't express
+  // (e.g. secrets' envelope jsonb without default). `collectTableMetas` and
+  // the registry's implicit-projection use this object instead of the
+  // field-derived table, so generate + test-push + executor share ONE table.
+  readonly entityTables?: Readonly<Record<string, unknown>>;
   readonly relations: Readonly<Record<string, EntityRelations>>;
   readonly writeHandlers: Readonly<Record<string, WriteHandlerDef>>;
   readonly queryHandlers: Readonly<Record<string, QueryHandlerDef>>;
@@ -359,7 +366,11 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // bug — and one nothing catches at boot, so don't.
   toggleable(options: { default: boolean }): void;
 
-  entity(name: string, definition: EntityDefinition): EntityRef;
+  entity(
+    name: string,
+    definition: EntityDefinition,
+    options?: { readonly table?: unknown },
+  ): EntityRef;
 
   writeHandler<TName extends string, TSchema extends ZodType>(
     def: WriteHandlerDefinition<TName, TSchema>,

package/src/migrations/__tests__/kumiko-drift.integration.test.ts

@@ -103,6 +103,48 @@ describe("kumiko-drift boot-gate", () => {
     expect(report.missingTables).toEqual(["kdrift_widget"]);
   });
 
+  test("snapshot column missing in DB → missingColumns (Layer 3, boot-fail not 500)", async () => {
+    // The #347 class: table was migrated from a thin snapshot, the snapshot is
+    // now richer (ride-along columns the generator started emitting). The table
+    // EXISTS (Layer 2 ok) but lacks columns the code will write → without
+    // Layer 3 this surfaces as a runtime-500 on the first write. Layer 3 makes
+    // it a boot-time SchemaDriftError with a regen-hint instead.
+    await asRawClient(testDb.db).unsafe(
+      `CREATE TABLE "kdrift_widget" ("id" uuid PRIMARY KEY, "key" text)`,
+    );
+    writeMigration("0001_init.sql", `SELECT 1;`); // recorded, table pre-exists thin
+    writeFileSync(
+      join(dir, ".snapshot.json"),
+      JSON.stringify({
+        version: 1,
+        tables: [
+          {
+            tableName: "kdrift_widget",
+            columns: [
+              { name: "id", pgType: "uuid", notNull: true },
+              { name: "key", pgType: "text", notNull: true },
+              { name: "envelope", pgType: "jsonb", notNull: true },
+              { name: "metadata", pgType: "jsonb", notNull: true },
+            ],
+            indexes: [],
+            source: "managed",
+          },
+        ],
+      }),
+    );
+    await runMigrationsFromDir(testDb.db, dir);
+
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(false);
+    expect(report.missingTables).toEqual([]);
+    expect(report.missingColumns).toEqual([
+      { table: "kdrift_widget", columns: ["envelope", "metadata"] },
+    ]);
+    await expect(assertKumikoSchemaCurrent(testDb.db, dir)).rejects.toBeInstanceOf(
+      SchemaDriftError,
+    );
+  });
+
   test("missing migrations dir → ok (no migrations to validate)", async () => {
     // Regression für review #155 finding 1: existing-App-Upgrade ohne
     // ./kumiko/migrations darf nicht roh ENOENT werfen (würde sonst plain

package/src/migrations/__tests__/kumiko-drift.report.test.ts

@@ -12,6 +12,7 @@ const empty: KumikoDriftReport = {
   pending: [],
   checksumMismatches: [],
   missingTables: [],
+  missingColumns: [],
 };
 
 describe("formatKumikoDriftReport", () => {
@@ -76,6 +77,18 @@ describe("formatKumikoDriftReport", () => {
     expect(out).not.toContain("Restore from backup");
   });
 
+  test("missing columns → lists table.columns + regen remediation", () => {
+    const report: KumikoDriftReport = {
+      ...empty,
+      ok: false,
+      missingColumns: [{ table: "read_tenant_secrets", columns: ["envelope", "metadata"] }],
+    };
+    const out = formatKumikoDriftReport(report);
+    expect(out).toContain("2 missing column(s)");
+    expect(out).toContain("read_tenant_secrets: envelope, metadata");
+    expect(out).toContain("'kumiko schema generate'");
+  });
+
   test("pending + mismatch combined → both remediation lines", () => {
     const report: KumikoDriftReport = {
       ...empty,

package/src/migrations/kumiko-drift.ts

@@ -6,20 +6,21 @@
 //   1. Migrations applied: every `kumiko/migrations/*.sql` has a row in
 //      `_kumiko_migrations`. Applied-but-edited (checksum mismatch) is drift.
 //   2. Tables exist: every table in `kumiko/migrations/.snapshot.json` exists.
+//   3. Columns exist: every column the snapshot declares for an existing table
+//      is present in the live schema. A migrated-but-incomplete table (snapshot
+//      richer than the DB — e.g. a ride-along column the generator once missed)
+//      would otherwise surface only as a runtime-500 on the first write.
 //
 // Contract (unchanged from the legacy gate): boot VALIDATES only, never
 // applies. Apply is the deploy-step `kumiko schema apply` (runMigrationsFromDir).
-//
-// Layer 3 (column-diff against the snapshot's ColumnMeta — catches manual
-// ALTERs / stale defs) is a documented follow-up; see
-// docs/plans/migration-system-consolidation.md.
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import type { DbConnection } from "../db/connection";
+import type { EntityTableMeta } from "../db/entity-table-meta";
 import { loadSnapshotJson } from "../db/migrate-generator";
 import { fetchAppliedMigrations, loadMigrationsFromDir } from "../db/migrate-runner";
-import { tableExists } from "../db/schema-inspection";
+import { columnNamesOf, tableExists } from "../db/schema-inspection";
 
 const SNAPSHOT_FILENAME = ".snapshot.json";
 
@@ -29,11 +30,17 @@ export type ChecksumMismatch = {
   readonly actual: string; // checksum of the file on disk now
 };
 
+export type MissingColumns = {
+  readonly table: string;
+  readonly columns: readonly string[];
+};
+
 export type KumikoDriftReport = {
   readonly ok: boolean;
   readonly pending: readonly string[];
   readonly checksumMismatches: readonly ChecksumMismatch[];
   readonly missingTables: readonly string[];
+  readonly missingColumns: readonly MissingColumns[];
 };
 
 export class SchemaDriftError extends Error {
@@ -56,7 +63,7 @@ export async function detectKumikoDrift(
   // würde loadMigrationsFromDir → readdirSync synchron ENOENT werfen
   // (plain Error, kein SchemaDriftError) und der Boot crasht roh.
   if (!existsSync(migrationsDir)) {
-    return { ok: true, pending: [], checksumMismatches: [], missingTables: [] };
+    return { ok: true, pending: [], checksumMismatches: [], missingTables: [], missingColumns: [] };
   }
   const local = loadMigrationsFromDir(migrationsDir);
   // Frische DB ohne je gelaufenes `kumiko schema apply` → tracking-table fehlt.
@@ -82,20 +89,38 @@ export async function detectKumikoDrift(
   // layer still gates.
   const snapshot = loadSnapshotJson(join(migrationsDir, SNAPSHOT_FILENAME));
   const missingTables: string[] = [];
+  const missingColumns: MissingColumns[] = [];
   if (snapshot) {
-    const checks = await Promise.all(
-      snapshot.tables.map((t) =>
-        tableExists(db, t.tableName).then((exists) => ({ name: t.tableName, exists })),
+    const existence = await Promise.all(
+      snapshot.tables.map((t) => tableExists(db, t.tableName).then((exists) => ({ t, exists }))),
+    );
+    const present: EntityTableMeta[] = [];
+    for (const { t, exists } of existence) {
+      if (exists) present.push(t);
+      else missingTables.push(t.tableName);
+    }
+    // Layer 3 — column-diff for tables that DO exist.
+    const columnChecks = await Promise.all(
+      present.map((t) =>
+        columnNamesOf(db, t.tableName).then((live) => ({
+          table: t.tableName,
+          columns: t.columns.map((c) => c.name).filter((n) => !live.has(n)),
+        })),
       ),
     );
-    for (const c of checks) if (!c.exists) missingTables.push(c.name);
+    for (const c of columnChecks) if (c.columns.length > 0) missingColumns.push(c);
   }
 
   return {
-    ok: pending.length === 0 && checksumMismatches.length === 0 && missingTables.length === 0,
+    ok:
+      pending.length === 0 &&
+      checksumMismatches.length === 0 &&
+      missingTables.length === 0 &&
+      missingColumns.length === 0,
     pending,
     checksumMismatches,
     missingTables,
+    missingColumns,
   };
 }
 
@@ -116,6 +141,13 @@ export function formatKumikoDriftReport(report: KumikoDriftReport): string {
     lines.push(`  ${report.missingTables.length} missing table(s):`);
     for (const t of report.missingTables) lines.push(`    - ${t}`);
   }
+  if (report.missingColumns.length > 0) {
+    const count = report.missingColumns.reduce((n, m) => n + m.columns.length, 0);
+    lines.push(`  ${count} missing column(s):`);
+    for (const m of report.missingColumns) {
+      lines.push(`    - ${m.table}: ${m.columns.join(", ")}`);
+    }
+  }
   // Per-Cause Remediation — `kumiko schema apply` löst NUR pending. Checksum-
   // mismatch ist eine Sackgasse für apply (MigrationChecksumMismatchError) und
   // baseline (ON CONFLICT DO NOTHING → landet in alreadyTracked). Missing
@@ -134,6 +166,13 @@ export function formatKumikoDriftReport(report: KumikoDriftReport): string {
     lines.push("Missing table(s) without pending migration(s) — table was dropped after apply.");
     lines.push("Restore from backup, or generate a new migration that re-creates the table.");
   }
+  if (report.missingColumns.length > 0) {
+    lines.push("Missing column(s) — the live table predates a richer snapshot (e.g. a");
+    lines.push("ride-along column the generator now emits). Run 'kumiko schema generate' to");
+    lines.push(
+      "produce an ALTER-TABLE migration for the new column(s), then 'kumiko schema apply'.",
+    );
+  }
   return lines.join("\n");
 }