@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/db/index.d.ts

@@ -1,3 +1,4 @@
+export { isTimestamptzType } from "./aggregate-sql.ts";
 export { applyEntityEvent } from "./apply-entity-event.ts";
 export { assertExistsIn } from "./assert-exists-in.ts";
 export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.ts";
@@ -10,6 +11,7 @@ export type { CursorQueryOptions, CursorResult, DecodedKeysetCursor } from "./cu
 export { decodeCursor, decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.ts";
 export type { SchemaTable, SelectQuery, TableColumns } from "./dialect.ts";
 export { bigint, bigserial, boolean, extractTableName, index, instant, instantToDriver, integer, jsonb, moneyAmount, numeric, primaryKey, serial, sql, table, text, timestamp, uniqueIndex, uuid, } from "./dialect.ts";
+export { instantToTimestamptzParam } from "./driver-value-preparation.ts";
 export type { EagerLoadEntityResolver, EagerLoadViewer, EagerloadedRow } from "./eagerload.ts";
 export { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "./eagerload.ts";
 export { collectEncryptedFieldNames, configuredEntityFieldEncryption, configureEntityFieldEncryption, decryptEntityFieldValues, encryptEntityFieldValues, } from "./entity-field-encryption.ts";
@@ -19,6 +21,7 @@ export { defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-met
 export type { EntityLifecycleVerb, EventStoreExecutor, EventStoreExecutorOptions, LockGuardOption, WritePurpose, } from "./event-store-executor.ts";
 export { createEventStoreExecutor, entityEventName, WritePurposes, } from "./event-store-executor.ts";
 export { enumerateFeatureTableSources, type FeatureTableSource, } from "./feature-table-sources.ts";
+export { answerListAggregate, labelListAggregateGroups } from "./list-aggregate-labels.ts";
 export { flattenLocatedTimestamp, type LocatedTimestampRead, rehydrateLocatedTimestamp, } from "./located-timestamp.ts";
 export { assertUniqueTableNames, assertValidMigrationName, diffSnapshots, type GenerateMigrationInput, type GenerateMigrationOutput, generateMigration, loadSnapshotJson, renderMigrationSql, type SchemaDiff, type Snapshot, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.ts";
 export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, type Migration, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.ts";
@@ -28,8 +31,8 @@ export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.ts";
 export { readDatabaseNow } from "./queries/database-now.ts";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.ts";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.ts";
-export type { DeleteManyBatchedOptions, DeleteManyBatchedResult, IncrementCounterOptions, InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, TableInfo, UpsertOnConflictOptions, WhereObject, WhereOperator, WhereValue, } from "./query.ts";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, instantToTimestamptzParam, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.ts";
+export type { DeleteManyBatchedOptions, DeleteManyBatchedResult, IncrementCounterOptions, InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, UpsertOnConflictOptions, WhereObject, WhereOperator, WhereValue, } from "./query.ts";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.ts";
 export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from "./rebuild-marker.ts";
 export { seedReferenceData } from "./reference-data.ts";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.ts";
@@ -38,5 +41,6 @@ export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFramework
 export { tableExists } from "./schema-inspection.ts";
 export { withoutStatementTimeout } from "./statement-timeout.ts";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityRow, type EntityTable, type ExecutorManagedRunner, type ExecutorManagedWriteCapability, physicalColumnName, toSnakeCase, toTableName, type Writable, type WritableSchemaTable, type WritableTable, } from "./table-builder.ts";
+export { extractTableInfo, type TableInfo } from "./table-info.ts";
 export type { CreateTenantDbOptions, ExecutorManagedTenantDb, OutsideTransactionContext, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.ts";
 export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.ts";

package/dist/db/index.js

@@ -1,3 +1,4 @@
+export { isTimestamptzType } from "./aggregate-sql.js";
 export { applyEntityEvent } from "./apply-entity-event.js";
 export { assertExistsIn } from "./assert-exists-in.js";
 export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.js";
@@ -7,12 +8,14 @@ export { seedConfigValues } from "./config-seed.js";
 export { createDbConnection, DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "./connection.js";
 export { decodeCursor, decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
 export { bigint, bigserial, boolean, extractTableName, index, instant, instantToDriver, integer, jsonb, moneyAmount, numeric, primaryKey, serial, sql, table, text, timestamp, uniqueIndex, uuid, } from "./dialect.js";
+export { instantToTimestamptzParam } from "./driver-value-preparation.js";
 export { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "./eagerload.js";
 export { collectEncryptedFieldNames, configuredEntityFieldEncryption, configureEntityFieldEncryption, decryptEntityFieldValues, encryptEntityFieldValues, } from "./entity-field-encryption.js";
 export { entityTableFromRegistry } from "./entity-table-from-registry.js";
 export { defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-meta.js";
 export { createEventStoreExecutor, entityEventName, WritePurposes, } from "./event-store-executor.js";
 export { enumerateFeatureTableSources, } from "./feature-table-sources.js";
+export { answerListAggregate, labelListAggregateGroups } from "./list-aggregate-labels.js";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp, } from "./located-timestamp.js";
 export { assertUniqueTableNames, assertValidMigrationName, diffSnapshots, generateMigration, loadSnapshotJson, renderMigrationSql, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.js";
 export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
@@ -22,7 +25,7 @@ export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 export { readDatabaseNow } from "./queries/database-now.js";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, instantToTimestamptzParam, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
 export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from "./rebuild-marker.js";
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
@@ -31,4 +34,5 @@ export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTable
 export { tableExists } from "./schema-inspection.js";
 export { withoutStatementTimeout } from "./statement-timeout.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
+export { extractTableInfo } from "./table-info.js";
 export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/list-aggregate-labels.d.ts

@@ -0,0 +1,14 @@
+import type { ListAggregateResult } from "@cosmicdrift/kumiko-types/list-aggregate-types";
+import type { EntityDefinition } from "../engine/types/index.ts";
+import type { EagerLoadEntityResolver, EagerLoadViewer } from "./eagerload.ts";
+import type { EventStoreExecutor } from "./event-store-executor.ts";
+import type { TenantDb } from "./tenant-db.ts";
+type LabelDeps = {
+    readonly entity: EntityDefinition;
+    readonly resolveEntity: EagerLoadEntityResolver;
+    readonly viewer: EagerLoadViewer;
+};
+export declare function labelListAggregateGroups(result: ListAggregateResult, groupByField: string | undefined, deps: LabelDeps, db: TenantDb): Promise<ListAggregateResult>;
+type AggregateRequest = Parameters<EventStoreExecutor["aggregate"]>[0];
+export declare function answerListAggregate(executor: Pick<EventStoreExecutor, "aggregate">, request: AggregateRequest, user: Parameters<EventStoreExecutor["aggregate"]>[1], db: TenantDb, runtimeOptions: Parameters<EventStoreExecutor["aggregate"]>[3], labelDeps: LabelDeps): Promise<ListAggregateResult>;
+export {};

package/dist/db/list-aggregate-labels.js

@@ -0,0 +1,26 @@
+import { enrichWithReferences } from "./eagerload.js";
+function labelOf(ref, labelField) {
+    if (typeof ref !== "object" || ref === null || Array.isArray(ref))
+        return null;
+    const value = Reflect.get(ref, labelField);
+    return typeof value === "string" ? value : null;
+}
+// Labels come from the same eager-load path as list rows, so they carry its
+// ownership and field-read gating instead of a second label query.
+export async function labelListAggregateGroups(result, groupByField, deps, db) {
+    if (groupByField === undefined || result.groups.length === 0)
+        return result;
+    const def = deps.entity.fields[groupByField];
+    if (def?.type !== "reference" || def.multiple === true)
+        return result;
+    const enriched = await enrichWithReferences(result.groups.map((g) => ({ [groupByField]: g.key })), deps.entity, deps.resolveEntity, db, deps.viewer);
+    const groups = result.groups.map((group, i) => {
+        const ref = Reflect.get(enriched[i]?.["_refs"] ?? {}, groupByField);
+        return { ...group, label: labelOf(ref, def.labelField ?? "id") };
+    });
+    return { ...result, groups };
+}
+export async function answerListAggregate(executor, request, user, db, runtimeOptions, labelDeps) {
+    const result = await executor.aggregate(request, user, db, runtimeOptions);
+    return labelListAggregateGroups(result, request.aggregate.groupBy, labelDeps, db);
+}

package/dist/db/located-timestamp.d.ts

@@ -1,13 +1,13 @@
 import type { EntityDefinition } from "../engine/types/index.ts";
 /**
- * API → DB: locatedTimestamp-Felder zu zwei flachen Spalten flatten.
+ * API → DB: flatten locatedTimestamp fields into two flat columns.
  *
- * - `{ at, tz }` (UI-Form) → `{ <name>Utc, <name>Tz }` (utc via Temporal berechnet)
- * - `{ utc, tz }` (Server-Form) → utc gewinnt direkt
- * - `{ at, tz, utc }` → utc gewinnt; at wird ignoriert (Konsistenz-Check ist
- *   Caller-Verantwortung)
+ * - `{ at, tz }` (UI form) → `{ <name>Utc, <name>Tz }` (`utc` calculated via Temporal)
+ * - `{ utc, tz }` (server form) → `utc` takes precedence
+ * - `{ at, tz, utc }` → `utc` takes precedence; `at` is ignored (the caller is
+ *   responsible for the consistency check)
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export declare function flattenLocatedTimestamp(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
 /** Shape of a single rehydrated locatedTimestamp field. `at` is the wall clock in `tz`
@@ -18,12 +18,12 @@ export type LocatedTimestampRead = {
     readonly utc: string;
 };
 /**
- * DB → API: zwei flache Spalten zu combined { at, tz, utc } rehydraten.
+ * DB → API: rehydrate two flat columns into combined { at, tz, utc }.
  *
- * `at` ist immer Wall-Clock in der gespeicherten `tz` (Pickup-Ort-lokal).
- * Wer User-Sicht braucht, leitet aus `utc` selbst ab — der Server kennt
- * keine User-TZ.
+ * `at` is always the wall-clock time in the stored `tz` (local to the pickup
+ * location). To obtain a user-specific view, derive it from `utc` yourself —
+ * the server does not know the user's time zone.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export declare function rehydrateLocatedTimestamp(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/located-timestamp.js

@@ -1,23 +1,22 @@
-// Auto-Convert für locatedTimestamp-Felder im DB-Layer.
+// Automatically converts locatedTimestamp fields in the DB layer.
 //
-// Vertrag (siehe auch db/money.ts — gleicher Compound-Type-Pattern):
-//   API-Form:    { at, tz } | { utc, tz }
-//   DB-Form:     <name>Utc TIMESTAMPTZ + <name>Tz TEXT
-//   Read-Form:   { at, tz, utc }
+// Contract (see also db/money.ts — the same compound-type pattern):
+//   API form:   { at, tz } | { utc, tz }
+//   DB form:    <name>Utc TIMESTAMPTZ + <name>Tz TEXT
+//   Read form:  { at, tz, utc }
 //
-// `at`-Default-Sicht beim Read: Pickup-Ort-lokal (utc projiziert in
-// gespeicherter tz). Server kennt User-TZ nicht — User-spezifische
-// Anzeige passiert client-seitig aus utc.
+// Default `at` view on read: local to the pickup location (`utc` projected into
+// the stored `tz`). The server does not know the user's time zone, so
+// user-specific display is derived from `utc` on the client.
 // Static import, not the ambient global: Bun doesn't expose Temporal on
 // globalThis, so this crashed with "Temporal is not defined" outside boot
-// paths that install it (#1480).
+// paths that install it.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-// Sprint F: <name>Utc-Spalte ist jetzt instant() (siehe dialect.ts) —
-// Drizzle gibt direkt Temporal.Instant zurück. Vor Sprint F kam ein PG-
-// Wire-Format-String "2026-04-15 09:00:00+00" rein der via String-Massage
-// zu ISO-8601 gemacht werden musste. Heute übernimmt der customType die
-// Konversion DB↔Instant — diese Funktion ist nur noch defensive Glue für
-// Legacy-Code-Pfade die noch Strings durchreichen (z.B. raw SQL).
+// The <name>Utc column uses instant() (see dialect.ts), so Drizzle returns Temporal.Instant.
+// Previously, a PostgreSQL wire-format string "2026-04-15 09:00:00+00" had to be
+// converted to ISO 8601 through string manipulation. The customType now handles
+// DB↔Instant conversion, so this function is only defensive glue for legacy code
+// paths that still pass strings (for example, raw SQL).
 function toInstant(value) {
     if (value instanceof Temporal.Instant)
         return value;
@@ -27,14 +26,14 @@ function toInstant(value) {
     return Temporal.Instant.from(iso);
 }
 /**
- * API → DB: locatedTimestamp-Felder zu zwei flachen Spalten flatten.
+ * API → DB: flatten locatedTimestamp fields into two flat columns.
  *
- * - `{ at, tz }` (UI-Form) → `{ <name>Utc, <name>Tz }` (utc via Temporal berechnet)
- * - `{ utc, tz }` (Server-Form) → utc gewinnt direkt
- * - `{ at, tz, utc }` → utc gewinnt; at wird ignoriert (Konsistenz-Check ist
- *   Caller-Verantwortung)
+ * - `{ at, tz }` (UI form) → `{ <name>Utc, <name>Tz }` (`utc` calculated via Temporal)
+ * - `{ utc, tz }` (server form) → `utc` takes precedence
+ * - `{ at, tz, utc }` → `utc` takes precedence; `at` is ignored (the caller is
+ *   responsible for the consistency check)
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export function flattenLocatedTimestamp(payload, entity) {
     const T = Temporal;
@@ -53,10 +52,10 @@ export function flattenLocatedTimestamp(payload, entity) {
         if (pair.tz === undefined)
             continue;
         const tz = pair.tz;
-        // Sprint F: <name>Utc-Spalte ist instant() — Drizzle erwartet
-        // Temporal.Instant. Konvertierung pair.utc-string → Instant geht via
-        // toInstant() (kennt String + Instant); pair.at + tz → Instant via
-        // Temporal-Math.
+        // The <name>Utc column uses instant(); Drizzle expects
+        // Temporal.Instant. Conversion from pair.utc string → Instant goes through
+        // toInstant() (which handles strings and Instant values); pair.at + tz →
+        // Instant uses Temporal math.
         const instant = pair.utc !== undefined
             ? toInstant(pair.utc)
             : pair.at !== undefined
@@ -70,13 +69,13 @@ export function flattenLocatedTimestamp(payload, entity) {
     return result;
 }
 /**
- * DB → API: zwei flache Spalten zu combined { at, tz, utc } rehydraten.
+ * DB → API: rehydrate two flat columns into combined { at, tz, utc }.
  *
- * `at` ist immer Wall-Clock in der gespeicherten `tz` (Pickup-Ort-lokal).
- * Wer User-Sicht braucht, leitet aus `utc` selbst ab — der Server kennt
- * keine User-TZ.
+ * `at` is always the wall-clock time in the stored `tz` (local to the pickup
+ * location). To obtain a user-specific view, derive it from `utc` yourself —
+ * the server does not know the user's time zone.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate.
  */
 export function rehydrateLocatedTimestamp(row, entity) {
     const result = { ...row };

package/dist/db/migrate-generator.d.ts

@@ -3,7 +3,7 @@ import { type RetiredFrameworkTable } from "./retired-framework-tables.ts";
 declare const SNAPSHOT_VERSION: 1;
 export type Snapshot = {
     readonly version: typeof SNAPSHOT_VERSION;
-    readonly generatedAt: string;
+    readonly generatedAt?: string;
     readonly tables: readonly EntityTableMeta[];
 };
 export type ColumnChange = {

package/dist/db/migrate-generator.js

@@ -1,31 +1,36 @@
-// Build-time Generator: EntityTableMeta[] → reviewbares SQL-Migration-File.
-// Ersatz für `drizzle-kit generate`.
+// Build-time generator: EntityTableMeta[] → reviewable SQL migration file.
+// Replacement for `drizzle-kit generate`.
 //
-// **NO-MAGIC-ON-DATA Kernprinzip** (siehe drizzle-replacement.md):
-//   - Generator emittiert SQL-Files für PR-Review/Edit
-//   - Generator wird NIE zur App-Runtime aufgerufen
-//   - Output ist Start-Form; App-Author darf das SQL hand-editieren
-//     (BRIN-Index, partial-Index, performance-tuning) bevor committed
-//   - Append-only: bestehende Migration-Files werden NIE überschrieben.
-//     Neue Schema-Diffs landen in einem NEUEN File mit incrementierter
-//     Sequence-Number.
+// **NO-MAGIC-ON-DATA core principle** (see drizzle-replacement.md):
+//   - The generator emits SQL files for PR review/editing.
+//   - The generator is NEVER called at app runtime.
+//   - The output is a starting point; app authors may hand-edit the SQL
+//     (BRIN index, partial index, performance tuning) before committing.
+//   - Append-only: existing migration files are NEVER overwritten.
+//     New schema diffs go into a NEW file with an incremented sequence number.
 //
-// **DESTRUCTIVE-ops** (DROP TABLE/COLUMN, INDEX-removal) werden als
-// AUSKOMMENTIERTE statements emittiert — Reviewer muss explizit
-// uncommenten + ggf. Data-Backup-Schritt vorlauf einfügen. Default:
-// niemals automatisch droppen.
+// **DESTRUCTIVE operations** (DROP TABLE/COLUMN, index removal) are emitted
+// as commented-out statements — reviewers must explicitly uncomment them
+// and may need to add a data-backup step beforehand. Default:
+// never drop automatically.
 import { readFileSync, writeFileSync } from "node:fs";
 import { errorCodeOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { compareByCodepoint } from "../utils/index.js";
 import { renderIndex, renderTableDdl } from "./render-ddl.js";
 import { findRetiredTableDrops } from "./retired-framework-tables.js";
 const SNAPSHOT_VERSION = 1;
+function isSnapshot(value) {
+    return (isPlainObject(value) &&
+        value["version"] === SNAPSHOT_VERSION &&
+        (value["generatedAt"] === undefined || typeof value["generatedAt"] === "string") &&
+        Array.isArray(value["tables"]));
+}
 export function snapshotFromMetas(metas) {
     // Stable ordering by tableName so the snapshot.json diff in PRs is
     // meaningful (table-add isn't a noisy re-sort of everything). Codepoint, not
     // localeCompare: the snapshot is serialized to byte-exact JSON and the table
     // order carries into the generated migration SQL — locale-dependent ordering
-    // would drift between macOS-dev and Linux-CI (#367).
+    // would drift between macOS-dev and Linux-CI.
     const sorted = [...metas].sort((a, b) => compareByCodepoint(a.tableName, b.tableName));
     return {
         version: SNAPSHOT_VERSION,
@@ -41,6 +46,9 @@ export function loadSnapshotJson(path) {
         if (version !== SNAPSHOT_VERSION) {
             throw new Error(`Snapshot at ${path} has version ${String(version)}, expected ${SNAPSHOT_VERSION}`);
         }
+        if (!isSnapshot(parsed)) {
+            throw new Error(`Snapshot at ${path} is malformed: expected a tables list`);
+        }
         return parsed;
     }
     catch (err) {
@@ -53,7 +61,7 @@ export function writeSnapshotJson(path, snapshot) {
     writeFileSync(path, `${JSON.stringify(snapshot, null, 2)}\n`);
 }
 function indexMetaKey(idx) {
-    // Index-Identität via Name (PG-Constraint: unique innerhalb der DB)
+    // Index identity is based on its name (PostgreSQL constraint: unique within the database).
     return idx.name;
 }
 function indexColumnsEqual(a, b) {
@@ -71,100 +79,85 @@ function indexesByName(meta) {
         m.set(indexMetaKey(i), i);
     return m;
 }
-function diffOneTable(prev, next) {
-    const prevCols = columnsByName(prev);
-    const nextCols = columnsByName(next);
-    const newColumns = [];
-    const droppedColumns = [];
-    const changedColumns = [];
-    for (const [name, nextCol] of nextCols) {
-        const prevCol = prevCols.get(name);
-        if (!prevCol) {
-            newColumns.push(nextCol);
-            continue;
-        }
-        const change = { name };
-        if (prevCol.notNull !== nextCol.notNull) {
-            Object.assign(change, {
-                nullabilityChanged: { from: prevCol.notNull, to: nextCol.notNull },
-            });
-        }
-        if (prevCol.defaultSql !== nextCol.defaultSql) {
-            Object.assign(change, {
-                defaultChanged: { from: prevCol.defaultSql, to: nextCol.defaultSql },
-            });
-        }
-        if (prevCol.pgType !== nextCol.pgType) {
-            Object.assign(change, {
-                typeChanged: { from: prevCol.pgType, to: nextCol.pgType },
-            });
-        }
-        if (change.nullabilityChanged || change.defaultChanged || change.typeChanged) {
-            changedColumns.push(change);
-        }
-    }
-    for (const name of prevCols.keys()) {
-        if (!nextCols.has(name))
-            droppedColumns.push(name);
-    }
-    const prevIdx = indexesByName(prev);
-    const nextIdx = indexesByName(next);
-    const newIndexes = [];
-    const droppedIndexes = [];
-    const changedIndexes = [];
-    for (const [name, idx] of nextIdx) {
-        const prevI = prevIdx.get(name);
-        if (!prevI) {
-            newIndexes.push(idx);
+function strictEqual(a, b) {
+    return a === b;
+}
+function fromToWhenDifferent(from, to, isEqual = strictEqual) {
+    return isEqual(from, to) ? undefined : { from, to };
+}
+// added and changed follow next's order, dropped follows prev's order; the
+// rendered migration depends on both.
+function diffByName(prev, next, compare) {
+    const added = [];
+    const changed = [];
+    for (const [name, nextItem] of next) {
+        const prevItem = prev.get(name);
+        if (prevItem === undefined) {
+            added.push(nextItem);
             continue;
         }
-        const columnsChanged = indexColumnsEqual(prevI.columns, idx.columns)
-            ? undefined
-            : { from: prevI.columns, to: idx.columns };
-        const uniqueChanged = (prevI.unique ?? false) === (idx.unique ?? false)
-            ? undefined
-            : { from: prevI.unique ?? false, to: idx.unique ?? false };
-        // Whitespace-only re-rendering of the predicate must not drop and rebuild a large index.
-        const whereSqlChanged = whereSqlEqual(prevI.whereSql, idx.whereSql)
-            ? undefined
-            : { from: prevI.whereSql, to: idx.whereSql };
-        const needsManualWhereChanged = (prevI.needsManualWhere ?? false) === (idx.needsManualWhere ?? false)
-            ? undefined
-            : { from: prevI.needsManualWhere ?? false, to: idx.needsManualWhere ?? false };
-        if (columnsChanged || uniqueChanged || whereSqlChanged || needsManualWhereChanged) {
-            // Single literal typed as IndexChange so a misspelled key fails to compile instead of silently dropping the change.
-            const change = {
-                name,
-                ...(columnsChanged && { columnsChanged }),
-                ...(uniqueChanged && { uniqueChanged }),
-                ...(whereSqlChanged && { whereSqlChanged }),
-                ...(needsManualWhereChanged && { needsManualWhereChanged }),
-            };
-            changedIndexes.push(change);
-        }
+        const change = compare(name, prevItem, nextItem);
+        if (change !== undefined)
+            changed.push(change);
     }
-    for (const name of prevIdx.keys()) {
-        if (!nextIdx.has(name))
-            droppedIndexes.push(name);
+    const dropped = [...prev.keys()].filter((name) => !next.has(name));
+    return { added, dropped, changed };
+}
+function compareColumns(name, prevCol, nextCol) {
+    const nullabilityChanged = fromToWhenDifferent(prevCol.notNull, nextCol.notNull);
+    const defaultChanged = fromToWhenDifferent(prevCol.defaultSql, nextCol.defaultSql);
+    const typeChanged = fromToWhenDifferent(prevCol.pgType, nextCol.pgType);
+    if (!nullabilityChanged && !defaultChanged && !typeChanged)
+        return undefined;
+    return {
+        name,
+        ...(nullabilityChanged && { nullabilityChanged }),
+        ...(defaultChanged && { defaultChanged }),
+        ...(typeChanged && { typeChanged }),
+    };
+}
+function compareIndexes(name, prevIndex, nextIndex) {
+    const columnsChanged = fromToWhenDifferent(prevIndex.columns, nextIndex.columns, indexColumnsEqual);
+    const uniqueChanged = fromToWhenDifferent(prevIndex.unique ?? false, nextIndex.unique ?? false);
+    // Whitespace-only re-rendering of the predicate must not drop and rebuild a large index.
+    const whereSqlChanged = fromToWhenDifferent(prevIndex.whereSql, nextIndex.whereSql, whereSqlEqual);
+    const needsManualWhereChanged = fromToWhenDifferent(prevIndex.needsManualWhere ?? false, nextIndex.needsManualWhere ?? false);
+    if (!columnsChanged && !uniqueChanged && !whereSqlChanged && !needsManualWhereChanged) {
+        return undefined;
     }
-    const isEmpty = newColumns.length === 0 &&
-        droppedColumns.length === 0 &&
-        changedColumns.length === 0 &&
-        newIndexes.length === 0 &&
-        droppedIndexes.length === 0 &&
-        changedIndexes.length === 0;
-    if (isEmpty)
-        return null;
+    // Single literal typed as IndexChange so a misspelled key fails to compile instead of silently dropping the change.
     return {
+        name,
+        ...(columnsChanged && { columnsChanged }),
+        ...(uniqueChanged && { uniqueChanged }),
+        ...(whereSqlChanged && { whereSqlChanged }),
+        ...(needsManualWhereChanged && { needsManualWhereChanged }),
+    };
+}
+function hasNoTableChanges(diff) {
+    return [
+        diff.newColumns,
+        diff.droppedColumns,
+        diff.changedColumns,
+        diff.newIndexes,
+        diff.droppedIndexes,
+        diff.changedIndexes,
+    ].every((list) => list.length === 0);
+}
+function diffOneTable(prev, next) {
+    const columns = diffByName(columnsByName(prev), columnsByName(next), compareColumns);
+    const indexes = diffByName(indexesByName(prev), indexesByName(next), compareIndexes);
+    const diff = {
         tableName: prev.tableName,
-        newColumns,
-        droppedColumns,
-        changedColumns,
-        newIndexes,
-        droppedIndexes,
-        changedIndexes,
+        newColumns: columns.added,
+        droppedColumns: columns.dropped,
+        changedColumns: columns.changed,
+        newIndexes: indexes.added,
+        droppedIndexes: indexes.dropped,
+        changedIndexes: indexes.changed,
         nextMeta: next,
     };
+    return hasNoTableChanges(diff) ? null : diff;
 }
 export function diffSnapshots(prev, next) {
     const prevByName = new Map();
@@ -273,8 +266,7 @@ function renderColumnChange(tableName, change) {
         // timestamptz → date: PG's implicit ::date cast (what a bare ALTER ...
         // TYPE without USING falls back to) reads the session TimeZone, so the
         // same row migrates to a different calendar day depending on who/where
-        // runs it — exactly the non-determinism kumiko-framework#1924 fixes.
-        // Anchor explicitly at UTC instead of trusting the session.
+        // runs it. Anchor explicitly at UTC instead of trusting the session.
         if ((from === "timestamptz" || from === "timestamptz(3)") && to === "date") {
             out.push(`-- ${from} → date: explicit UTC anchor — a bare cast would use the session TimeZone (non-deterministic).`);
             out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE date USING (${col} AT TIME ZONE 'UTC')::date;`);
@@ -383,7 +375,7 @@ export function renderMigrationSql(diff, options) {
                 // needsManualWhere renders CREATE as a commented WARN (renderIndex),
                 // since the generator can't express the new WHERE — the DROP has to
                 // stay commented too, or the live index gets dropped with no
-                // executable replacement (kumiko-framework#2492 review).
+                // executable replacement.
                 lines.push(nextIdxMeta.needsManualWhere === true
                     ? `-- (review) DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`
                     : `DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`);