@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/db/executor-managed-tables.js

@@ -2,11 +2,20 @@ import { AccessDeniedError, InternalError } from "../errors/index.js";
 import { asEntityTableMeta, tableNameOf } from "./table-introspection.js";
 const executorManagedTables = new WeakSet();
 const executorManagedWriteRunners = new WeakSet();
-export function markExecutorManagedTable(table) {
+const entitySourceByTable = new WeakMap();
+// Projection tables (r.projection) have no entity source; only entity tables can take a created event.
+export function markExecutorManagedTable(table, entitySource) {
     executorManagedTables.add(table);
     const meta = asEntityTableMeta(table);
     if (meta !== undefined)
         executorManagedTables.add(meta);
+    if (entitySource !== undefined)
+        entitySourceByTable.set(table, entitySource);
+}
+export function executorManagedEntitySourceOf(table) {
+    if (typeof table !== "object" || table === null)
+        return undefined;
+    return entitySourceByTable.get(table);
 }
 export function isExecutorManagedTable(table) {
     if (typeof table !== "object" || table === null)
@@ -20,7 +29,7 @@ export function registerExecutorManagedWriteRunner(runner) {
     executorManagedWriteRunners.add(runner);
 }
 // WeakSet.has never reads a property off runner, so a fail-closed guard Proxy stays untouched.
-// postgres.js clients are callable (tagged templates), so a runner can be a function.
+// Bun.SQL clients are callable (tagged templates), so a runner can be a function.
 export function hasExecutorManagedWriteCapability(runner) {
     if (typeof runner !== "object" && typeof runner !== "function")
         return false;
@@ -34,7 +43,7 @@ export function executorManagedWriteDenied(runner, table, operation) {
     const tableName = tableNameOf(table);
     return new AccessDeniedError({
         message: `${operation}(${tableName}): "${tableName}" is fed by events (r.entity / r.projection). ` +
-            "Write it through the entity executor (r.crud, ctx.write, createEventStoreExecutor) or inside a " +
+            "Write it through the entity executor (r.crud, ctx.dispatch.write, createEventStoreExecutor) or inside a " +
             "projection apply; a direct write drifts from the event stream and a rebuild drops or resurrects the row.",
     });
 }

package/dist/db/index.d.ts

@@ -3,44 +3,45 @@ 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";
 export { collectTableMetas } from "./collect-table-metas.ts";
-export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.ts";
 export { seedConfigValues } from "./config-seed.ts";
-export type { CreateDbConnectionOptions, DbConnection, DbConnectionHandle, DbConnectionOptions, DbRow, DbRunner, DbTx, } from "./connection.ts";
+export type { DbConnection, DbRow, DbRunner, DbTx, } from "./connection.ts";
 export { createDbConnection, DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "./connection.ts";
-export type { CursorQueryOptions, CursorResult, DecodedKeysetCursor } from "./cursor.ts";
 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 type { SchemaTable } from "./dialect.ts";
+export { boolean, extractTableName, index, instant, integer, jsonb, 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";
+export { collectEncryptedFieldNames, configuredEntityFieldEncryption, configureEntityFieldEncryption, decryptEntityFieldValues, } from "./entity-field-encryption.ts";
 export { entityTableFromRegistry } from "./entity-table-from-registry.ts";
-export type { BuildEntityTableMetaOptions, ColumnMeta, CompositePrimaryKeyMeta, EntityTableMeta, IndexMeta, PgType, UnmanagedTableInput, } from "./entity-table-meta.ts";
+export type { ColumnMeta, EntityTableMeta, } from "./entity-table-meta.ts";
 export { defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-meta.ts";
-export type { EntityLifecycleVerb, EventStoreExecutor, EventStoreExecutorOptions, LockGuardOption, WritePurpose, } from "./event-store-executor.ts";
+export type { EventStoreExecutor, 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";
-export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.ts";
-export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, type PgErrorInfo, } from "./pg-error.ts";
+export { enumerateFeatureTableSources } from "./feature-table-sources.ts";
+export { type KnownTables, knownTablesOf } from "./known-table-names.ts";
+export { answerListAggregate } from "./list-aggregate-labels.ts";
+export { generateMigration, loadSnapshotJson, writeSnapshotJson, } from "./migrate-generator.ts";
+export { runMigrationsFromDir } from "./migrate-runner.ts";
+export { type MoneyRead, rehydrateMoney } from "./money.ts";
+export { extractPgError, isUndefinedTable, isUniqueViolation, } from "./pg-error.ts";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.ts";
 export { readDatabaseNow } from "./queries/database-now.ts";
+export { listEventTenantIds } from "./queries/event-tenants.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, 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 { executeRawQuery } from "./queries/raw-sql.ts";
+export { withSessionAdvisoryLock } from "./queries/session-advisory-lock.ts";
+export type { JsonTextMatch, SelectOptions, WhereObject, } from "./query.ts";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, requireEntityTableMeta, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.ts";
 export { seedReferenceData } from "./reference-data.ts";
-export { renderTableDdl, renderTablesDdl } from "./render-ddl.ts";
-export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, type ReplayMismatch, replayMigrationsDir, } from "./replay-migration-sql.ts";
-export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.ts";
+export { renderTablesDdl } from "./render-ddl.ts";
+export { ROW_LEVEL_SECURITY_MODES, type RowLevelSecurityMode } from "./render-rls-ddl.ts";
+export { assertRowLevelSecurityBootState, assertRowLevelSecurityTableState, } from "./row-level-security-boot-check.ts";
+export { rowLevelSecurityModeOf } from "./row-level-security-connection.ts";
+export type { RowLevelSecurityScope } from "./row-level-security-scope.ts";
+export { assertNoActiveRowLevelSecurityScope } from "./row-level-security-scope.ts";
 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 { scopeTenantDbToTenant } from "./scope-tenant-db-to-tenant.ts";
+export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, type ExecutorManagedRunner, physicalColumnName, 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";
+export type { ExecutorManagedTenantDb, TenantDb, UncheckedSystemDb, } from "./tenant-db.ts";
+export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, } from "./tenant-db.ts";
+export { runInOwnTransaction } from "./tenant-db-scoped-rebind.ts";

package/dist/db/index.js

@@ -3,36 +3,38 @@ 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";
 export { collectTableMetas } from "./collect-table-metas.js";
-export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 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 { boolean, extractTableName, index, instant, integer, jsonb, 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 { collectEncryptedFieldNames, configuredEntityFieldEncryption, configureEntityFieldEncryption, decryptEntityFieldValues, } 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";
-export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
-export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, } from "./pg-error.js";
+export { enumerateFeatureTableSources } from "./feature-table-sources.js";
+export { knownTablesOf } from "./known-table-names.js";
+export { answerListAggregate } from "./list-aggregate-labels.js";
+export { generateMigration, loadSnapshotJson, writeSnapshotJson, } from "./migrate-generator.js";
+export { runMigrationsFromDir } from "./migrate-runner.js";
+export { rehydrateMoney } from "./money.js";
+export { extractPgError, isUndefinedTable, isUniqueViolation, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 export { readDatabaseNow } from "./queries/database-now.js";
+export { listEventTenantIds } from "./queries/event-tenants.js";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
-export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.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 { executeRawQuery } from "./queries/raw-sql.js";
+export { withSessionAdvisoryLock } from "./queries/session-advisory-lock.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, requireEntityTableMeta, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
 export { seedReferenceData } from "./reference-data.js";
-export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
-export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migration-sql.js";
-export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
+export { renderTablesDdl } from "./render-ddl.js";
+export { ROW_LEVEL_SECURITY_MODES } from "./render-rls-ddl.js";
+export { assertRowLevelSecurityBootState, assertRowLevelSecurityTableState, } from "./row-level-security-boot-check.js";
+export { rowLevelSecurityModeOf } from "./row-level-security-connection.js";
+export { assertNoActiveRowLevelSecurityScope } from "./row-level-security-scope.js";
 export { tableExists } from "./schema-inspection.js";
-export { withoutStatementTimeout } from "./statement-timeout.js";
-export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
+export { scopeTenantDbToTenant } from "./scope-tenant-db-to-tenant.js";
+export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, } 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";
+export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, } from "./tenant-db.js";
+export { runInOwnTransaction } from "./tenant-db-scoped-rebind.js";

package/dist/db/known-table-names.d.ts

@@ -0,0 +1,6 @@
+import type { FeatureDefinition } from "../engine/types/index.ts";
+export declare function isLiveFrameworkTable(tableName: string): boolean;
+export type KnownTables = {
+    readonly has: (tableName: string) => boolean;
+};
+export declare function knownTablesOf(features: readonly FeatureDefinition[]): KnownTables;

package/dist/db/known-table-names.js

@@ -0,0 +1,21 @@
+import { collectTableMetas } from "./collect-table-metas.js";
+import { isRetiredFrameworkTable } from "./retired-framework-tables.js";
+// The prefix only picks which boot-check message a table gets; both groups still throw, and a second
+// framework table list would be one more source to maintain.
+// Event store and pipeline state (kumiko_events, kumiko_projections, ...) are created by framework
+// boot, not by `schema generate`, so no feature declares them.
+const FRAMEWORK_TABLE_PREFIX = "kumiko_";
+export function isLiveFrameworkTable(tableName) {
+    return tableName.startsWith(FRAMEWORK_TABLE_PREFIX) && !isRetiredFrameworkTable(tableName);
+}
+// Same source as `kumiko schema generate`: a tenant table that is not listed here has no owner left.
+export function knownTablesOf(features) {
+    // Lazy: a healthy boot finds no unprotected table and never asks, so it skips collecting metas.
+    let names;
+    return {
+        has: (tableName) => {
+            names ??= new Set(collectTableMetas(features).map((meta) => meta.tableName));
+            return names.has(tableName) || isLiveFrameworkTable(tableName);
+        },
+    };
+}

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

@@ -1,5 +1,5 @@
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 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";

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

@@ -1,4 +1,4 @@
-import type { EntityDefinition } from "../engine/types/index.ts";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 /**
  * API → DB: flatten locatedTimestamp fields into two flat columns.
  *

package/dist/db/located-timestamp.js

@@ -1,8 +1,3 @@
-// Automatically converts locatedTimestamp fields in the DB layer.
-//
-// 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 }
 //
 // Default `at` view on read: local to the pickup location (`utc` projected into

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

@@ -1,10 +1,14 @@
 import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta.ts";
+import { type PrimaryKeyChange } from "./migrate-primary-key.ts";
+import { type RowLevelSecurityChange } from "./migrate-rls-diff.ts";
+import { type RowLevelSecurityMode, type TableRowLevelSecurity } from "./render-rls-ddl.ts";
 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 tables: readonly EntityTableMeta[];
+    readonly rowLevelSecurity?: Readonly<Record<string, TableRowLevelSecurity>>;
 };
 export type ColumnChange = {
     readonly name: string;
@@ -48,6 +52,7 @@ export type TableDiff = {
     readonly newIndexes: readonly IndexMeta[];
     readonly droppedIndexes: readonly string[];
     readonly changedIndexes: readonly IndexChange[];
+    readonly primaryKeyChanged?: PrimaryKeyChange;
     readonly nextMeta: EntityTableMeta;
 };
 export type SchemaDiff = {
@@ -55,15 +60,24 @@ export type SchemaDiff = {
     readonly droppedTables: readonly string[];
     readonly changedTables: readonly TableDiff[];
 };
-export declare function snapshotFromMetas(metas: readonly EntityTableMeta[]): Snapshot;
+export declare function snapshotFromMetas(metas: readonly EntityTableMeta[], options?: {
+    readonly rowLevelSecurity?: RowLevelSecurityMode;
+}): Snapshot;
 export declare function loadSnapshotJson(path: string): Snapshot | null;
 export declare function writeSnapshotJson(path: string, snapshot: Snapshot): void;
 export declare function diffSnapshots(prev: Snapshot | null, next: Snapshot): SchemaDiff;
 export declare function managedChangeRequiresRecreate(td: TableDiff): boolean;
+export declare function isRecreatedManagedTable(td: TableDiff): boolean;
+export declare function hasNoSchemaChanges(input: {
+    readonly diff: SchemaDiff;
+    readonly retiredDrops: readonly RetiredFrameworkTable[];
+    readonly rowLevelSecurityChanges: readonly RowLevelSecurityChange[];
+}): boolean;
 export declare function renderMigrationSql(diff: SchemaDiff, options: {
     readonly name: string;
     readonly sequenceNumber: number;
     readonly retiredDrops?: readonly RetiredFrameworkTable[];
+    readonly rowLevelSecurityChanges?: readonly RowLevelSecurityChange[];
 }): string;
 export type GenerateMigrationInput = {
     readonly metas: readonly EntityTableMeta[];
@@ -73,6 +87,7 @@ export type GenerateMigrationInput = {
     /** Raw SQL of all earlier migrations, in order — lets the generator decide
      *  whether a retired framework table still needs its executable drop. */
     readonly priorMigrationsSql?: readonly string[];
+    readonly rowLevelSecurity?: RowLevelSecurityMode;
 };
 export type GenerateMigrationOutput = {
     readonly filename: string;
@@ -80,6 +95,7 @@ export type GenerateMigrationOutput = {
     readonly snapshot: Snapshot;
     readonly diff: SchemaDiff;
     readonly retiredDrops: readonly RetiredFrameworkTable[];
+    readonly rowLevelSecurityChanges: readonly RowLevelSecurityChange[];
 };
 export declare const MIGRATION_NAME_RE: RegExp;
 export declare function assertValidMigrationName(name: string): void;

package/dist/db/migrate-generator.js

@@ -15,17 +15,23 @@
 // 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 { compareByCodepoint } from "../utils/compare.js";
+import { diffPrimaryKey, renderPrimaryKeyChange, } from "./migrate-primary-key.js";
+import { diffRowLevelSecurity, renderRowLevelSecurityChanges, } from "./migrate-rls-diff.js";
 import { renderIndex, renderTableDdl } from "./render-ddl.js";
+import { isTableRowLevelSecurityRecord, rowLevelSecurityByTable, } from "./render-rls-ddl.js";
 import { findRetiredTableDrops } from "./retired-framework-tables.js";
+import { quoteIdent } from "./sql-identifier.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"]));
+        Array.isArray(value["tables"]) &&
+        (value["rowLevelSecurity"] === undefined ||
+            isTableRowLevelSecurityRecord(value["rowLevelSecurity"])));
 }
-export function snapshotFromMetas(metas) {
+export function snapshotFromMetas(metas, options = {}) {
     // 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
@@ -36,6 +42,9 @@ export function snapshotFromMetas(metas) {
         version: SNAPSHOT_VERSION,
         generatedAt: new Date().toISOString(),
         tables: sorted,
+        ...(options.rowLevelSecurity === "on" && {
+            rowLevelSecurity: rowLevelSecurityByTable(sorted),
+        }),
     };
 }
 export function loadSnapshotJson(path) {
@@ -135,18 +144,20 @@ function compareIndexes(name, prevIndex, nextIndex) {
     };
 }
 function hasNoTableChanges(diff) {
-    return [
-        diff.newColumns,
-        diff.droppedColumns,
-        diff.changedColumns,
-        diff.newIndexes,
-        diff.droppedIndexes,
-        diff.changedIndexes,
-    ].every((list) => list.length === 0);
+    return (diff.primaryKeyChanged === undefined &&
+        [
+            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 primaryKeyChanged = diffPrimaryKey(prev, next);
     const diff = {
         tableName: prev.tableName,
         newColumns: columns.added,
@@ -155,6 +166,7 @@ function diffOneTable(prev, next) {
         newIndexes: indexes.added,
         droppedIndexes: indexes.dropped,
         changedIndexes: indexes.changed,
+        ...(primaryKeyChanged && { primaryKeyChanged }),
         nextMeta: next,
     };
     return hasNoTableChanges(diff) ? null : diff;
@@ -225,15 +237,26 @@ function describeRecreateReasons(td) {
     if (typeChanged.length > 0) {
         reasons.push(`column type change: ${typeChanged.join(", ")}`);
     }
+    if (td.primaryKeyChanged) {
+        const { from, to } = td.primaryKeyChanged;
+        reasons.push(`primary-key change: ${from.columns.join(", ")} → ${to.columns.join(", ")}`);
+    }
     return reasons;
 }
 export function managedChangeRequiresRecreate(td) {
     return describeRecreateReasons(td).length > 0;
 }
-// --- SQL-Render ---------------------------------------------------------
-function quoteIdent(name) {
-    return `"${name.replace(/"/g, '""')}"`;
+export function isRecreatedManagedTable(td) {
+    return td.nextMeta.source === "managed" && managedChangeRequiresRecreate(td);
+}
+export function hasNoSchemaChanges(input) {
+    return (input.diff.newTables.length === 0 &&
+        input.diff.changedTables.length === 0 &&
+        input.diff.droppedTables.length === 0 &&
+        input.retiredDrops.length === 0 &&
+        input.rowLevelSecurityChanges.length === 0);
 }
+// --- SQL-Render ---------------------------------------------------------
 function renderColumnInline(col) {
     const parts = [quoteIdent(col.name), col.pgType];
     if (col.defaultSql !== undefined)
@@ -347,7 +370,7 @@ export function renderMigrationSql(diff, options) {
         lines.push("-- === Changed tables ===");
         for (const td of diff.changedTables) {
             lines.push(`-- ${td.tableName}`);
-            if (td.nextMeta.source === "managed" && managedChangeRequiresRecreate(td)) {
+            if (isRecreatedManagedTable(td)) {
                 lines.push("-- managed projection — recreated + rebuilt from events (see .rebuild.json)");
                 lines.push(`-- WARN: destructive change (${describeRecreateReasons(td).join("; ")}) forces DROP+CREATE + full event replay.`);
                 lines.push("-- Consider an Expand/Contract split across two releases to avoid the rebuild — see docs/guides/expand-contract-managed-projections.md.");
@@ -363,6 +386,7 @@ export function renderMigrationSql(diff, options) {
                 for (const stmt of renderColumnChange(td.tableName, ch))
                     lines.push(stmt);
             }
+            lines.push(...renderPrimaryKeyChange(td.tableName, td.primaryKeyChanged));
             for (const idx of td.newIndexes) {
                 lines.push(renderIndex(td.tableName, idx));
             }
@@ -390,6 +414,7 @@ export function renderMigrationSql(diff, options) {
             lines.push("");
         }
     }
+    lines.push(...renderRowLevelSecurityChanges(options.rowLevelSecurityChanges));
     if (diff.droppedTables.length > 0) {
         lines.push("-- === Dropped tables ===");
         for (const name of diff.droppedTables) {
@@ -405,10 +430,11 @@ export function renderMigrationSql(diff, options) {
         }
         lines.push("");
     }
-    if (diff.newTables.length === 0 &&
-        diff.changedTables.length === 0 &&
-        diff.droppedTables.length === 0 &&
-        retiredDrops.length === 0) {
+    if (hasNoSchemaChanges({
+        diff,
+        retiredDrops,
+        rowLevelSecurityChanges: options.rowLevelSecurityChanges ?? [],
+    })) {
         lines.push("-- No schema changes detected.");
     }
     return lines.join("\n");
@@ -436,13 +462,16 @@ export function assertUniqueTableNames(metas) {
 export function generateMigration(input) {
     assertValidMigrationName(input.name);
     assertUniqueTableNames(input.metas);
-    const nextSnapshot = snapshotFromMetas(input.metas);
+    const nextSnapshot = snapshotFromMetas(input.metas, { rowLevelSecurity: input.rowLevelSecurity });
     const diff = diffSnapshots(input.prevSnapshot, nextSnapshot);
+    const recreatedTables = new Set(diff.changedTables.filter(isRecreatedManagedTable).map((td) => td.tableName));
+    const rowLevelSecurityChanges = diffRowLevelSecurity(input.prevSnapshot, nextSnapshot, recreatedTables);
     const retiredDrops = findRetiredTableDrops(input.priorMigrationsSql ?? [], nextSnapshot);
     const sqlContent = renderMigrationSql(diff, {
         name: input.name,
         sequenceNumber: input.sequenceNumber,
         retiredDrops,
+        rowLevelSecurityChanges,
     });
     const seq = input.sequenceNumber.toString().padStart(4, "0");
     return {
@@ -451,5 +480,6 @@ export function generateMigration(input) {
         snapshot: nextSnapshot,
         diff,
         retiredDrops,
+        rowLevelSecurityChanges,
     };
 }

package/dist/db/migrate-primary-key.d.ts

@@ -0,0 +1,12 @@
+import type { EntityTableMeta } from "./entity-table-meta.ts";
+export type PrimaryKey = {
+    readonly columns: readonly string[];
+    readonly constraintName: string;
+};
+export type PrimaryKeyChange = {
+    readonly from: PrimaryKey;
+    readonly to: PrimaryKey;
+};
+export declare function primaryKeyOf(meta: EntityTableMeta): PrimaryKey;
+export declare function diffPrimaryKey(prev: EntityTableMeta, next: EntityTableMeta): PrimaryKeyChange | undefined;
+export declare function renderPrimaryKeyChange(tableName: string, change: PrimaryKeyChange | undefined): readonly string[];

package/dist/db/migrate-primary-key.js

@@ -0,0 +1,45 @@
+import { quoteIdent } from "./sql-identifier.js";
+// Postgres names an implicit PK `<table>_pkey` and, past 63 bytes, shortens the table part, never the suffix.
+const MAX_IDENTIFIER_LENGTH = 63;
+const IMPLICIT_PRIMARY_KEY_SUFFIX = "_pkey";
+// Older snapshots may omit `primaryKey: false` and `compositePrimaryKey`, so only a truthy flag counts.
+export function primaryKeyOf(meta) {
+    if (meta.compositePrimaryKey !== undefined) {
+        return {
+            columns: meta.compositePrimaryKey.columns,
+            constraintName: meta.compositePrimaryKey.name,
+        };
+    }
+    return {
+        columns: meta.columns.filter((col) => col.primaryKey === true).map((col) => col.name),
+        constraintName: `${meta.tableName.slice(0, MAX_IDENTIFIER_LENGTH - IMPLICIT_PRIMARY_KEY_SUFFIX.length)}${IMPLICIT_PRIMARY_KEY_SUFFIX}`,
+    };
+}
+function primaryKeysEqual(a, b) {
+    return (a.constraintName === b.constraintName &&
+        a.columns.length === b.columns.length &&
+        a.columns.every((col, i) => col === b.columns[i]));
+}
+export function diffPrimaryKey(prev, next) {
+    const from = primaryKeyOf(prev);
+    const to = primaryKeyOf(next);
+    return primaryKeysEqual(from, to) ? undefined : { from, to };
+}
+// Executable, not commented: the change loses no data, and it fails loudly when existing rows are not unique on the new key.
+export function renderPrimaryKeyChange(tableName, change) {
+    if (change === undefined)
+        return [];
+    const table = quoteIdent(tableName);
+    const { from, to } = change;
+    const lines = [
+        `-- WARN: primary-key change (${from.columns.join(", ")} → ${to.columns.join(", ")}). Existing rows must be unique on the new key.`,
+    ];
+    if (from.columns.length > 0) {
+        lines.push(`ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS ${quoteIdent(from.constraintName)};`);
+    }
+    if (to.columns.length > 0) {
+        const columns = to.columns.map(quoteIdent).join(", ");
+        lines.push(`ALTER TABLE ${table} ADD CONSTRAINT ${quoteIdent(to.constraintName)} PRIMARY KEY (${columns});`);
+    }
+    return lines;
+}

package/dist/db/migrate-rls-diff.d.ts

@@ -0,0 +1,20 @@
+import { type TableRowLevelSecurity } from "./render-rls-ddl.ts";
+export type RowLevelSecurityChange = {
+    readonly kind: "enable";
+    readonly tableName: string;
+    readonly next: TableRowLevelSecurity;
+    readonly previous?: TableRowLevelSecurity;
+} | {
+    readonly kind: "disable";
+    readonly tableName: string;
+    readonly previous: TableRowLevelSecurity;
+};
+type RowLevelSecuritySnapshotView = {
+    readonly tables: readonly {
+        readonly tableName: string;
+    }[];
+    readonly rowLevelSecurity?: Readonly<Record<string, TableRowLevelSecurity>>;
+};
+export declare function diffRowLevelSecurity(previous: RowLevelSecuritySnapshotView | null, next: RowLevelSecuritySnapshotView, recreatedTables: ReadonlySet<string>): RowLevelSecurityChange[];
+export declare function renderRowLevelSecurityChanges(changes?: readonly RowLevelSecurityChange[]): string[];
+export {};

package/dist/db/migrate-rls-diff.js

@@ -0,0 +1,61 @@
+// Row level security part of the migration generator: diffs the per-table policy
+// specs between two snapshots and renders the resulting DDL section.
+import { isSameTableRowLevelSecurity, renderDisableRowLevelSecurity, renderEnableRowLevelSecurity, } from "./render-rls-ddl.js";
+import { quoteIdent } from "./sql-identifier.js";
+function specOf(view, tableName) {
+    const byTable = view?.rowLevelSecurity;
+    if (byTable === undefined || !Object.hasOwn(byTable, tableName))
+        return undefined;
+    return byTable[tableName];
+}
+function changeForTable(tableName, previous, next, recreatedTables) {
+    const nextSpec = specOf(next, tableName);
+    const previousSpec = specOf(previous, tableName);
+    const recreated = recreatedTables.has(tableName);
+    if (nextSpec !== undefined) {
+        const unchanged = previousSpec !== undefined &&
+            !recreated &&
+            isSameTableRowLevelSecurity(previousSpec, nextSpec);
+        if (unchanged)
+            return undefined;
+        return {
+            kind: "enable",
+            tableName,
+            next: nextSpec,
+            ...(previousSpec !== undefined && !recreated && { previous: previousSpec }),
+        };
+    }
+    const existedBefore = previous?.tables.some((table) => table.tableName === tableName) === true;
+    if (previousSpec !== undefined && existedBefore && !recreated) {
+        return { kind: "disable", tableName, previous: previousSpec };
+    }
+    return undefined;
+}
+export function diffRowLevelSecurity(previous, next, recreatedTables) {
+    const changes = [];
+    for (const { tableName } of next.tables) {
+        const change = changeForTable(tableName, previous, next, recreatedTables);
+        if (change !== undefined)
+            changes.push(change);
+    }
+    return changes;
+}
+function renderChange(change) {
+    const tableSql = quoteIdent(change.tableName);
+    if (change.kind === "enable") {
+        return renderEnableRowLevelSecurity(tableSql, change.next, change.previous);
+    }
+    return [
+        "-- WARN: row level security switched off, tenant isolation falls back to the application layer",
+        ...renderDisableRowLevelSecurity(tableSql, change.previous),
+    ];
+}
+export function renderRowLevelSecurityChanges(changes = []) {
+    if (changes.length === 0)
+        return [];
+    return [
+        "-- === Row level security ===",
+        ...changes.flatMap((change) => [`-- ${change.tableName}`, ...renderChange(change)]),
+        "",
+    ];
+}