@minnowdb/core 0.5.0 → 0.6.0

package/dist/engine/schema.d.ts

@@ -1,6 +1,6 @@
 import { type ColumnDefault, type SqlDomain, type TableColumnRecord, type TableRecord } from "../storage/types.js";
 import { type Catalog, type CatalogColumn, type CatalogTable } from "./catalog.js";
-import { type QueryValue } from "./query.js";
+import { type Expression, type QueryValue } from "./query.js";
 /**
  * Typed schema DSL and catalog migration planning. Column builders carry compile-time value and
  * nullability types; `planMigration` diffs a schema against the live catalog into metadata-only
@@ -9,6 +9,14 @@ import { type QueryValue } from "./query.js";
  * catalog-only, and older segments read the new column as NULL.
  */
 export type SchemaColumnType = "boolean" | "number" | "string" | "datetime";
+/** Compiles and validates one immutable, row-local generated-column expression. */
+export declare function compileGeneratedColumnExpression(tableName: string, columnName: string, sql: string, columns: ReadonlyArray<{
+    readonly name: string;
+    readonly generatedValue?: {
+        readonly kind: "stored";
+        readonly sql: string;
+    };
+}>): Expression;
 /** What a FOREIGN KEY does to child rows when the parent row is deleted (E141-04). */
 export type ReferentialAction = "restrict" | "cascade" | "set null";
 /** A declared relation. `onDelete` defaults to "restrict", matching SQL's own default. */
@@ -47,22 +55,29 @@ export declare function foreignKeyName(tableName: string, columnName: string): s
 export type HasDefault<TValue> = TValue & {
     readonly __minnowHasDefault?: true;
 };
-export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boolean, TUnique extends boolean = false, THasDefault extends boolean = false, TInput extends SchemaValue = TValue> {
+export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boolean, TUnique extends boolean = false, THasDefault extends boolean = false, TInput extends SchemaValue = TValue, TDomain extends SqlDomain["kind"] | undefined = undefined, TGenerated extends boolean = false> {
     readonly kind: "column";
     readonly type: SchemaColumnType;
     readonly isNullable: TNullable;
     readonly isUnique: TUnique;
     readonly hasDefault: THasDefault;
+    readonly isGenerated: TGenerated;
     /** Type-only metadata consumed by adapters; optional so it emits no runtime payload. */
     readonly "~types"?: {
         readonly select: TValue;
         readonly input: TInput;
+        readonly domain: TDomain;
+        readonly generated: TGenerated;
     };
     /** True for exact SQL integer columns; ordinary number columns use Float64 semantics. */
     readonly integer: boolean;
     /** Logical SQL semantics layered over the stable string storage encoding. */
     readonly sqlDomain?: SqlDomain;
     readonly defaultSpec?: ColumnDefault;
+    readonly generatedSpec?: {
+        readonly kind: "stored";
+        readonly sql: string;
+    };
     /** Present on `column.enum()` builders: the closed set of values writes must draw from. */
     readonly enumValues?: readonly string[];
     /** What rows written before this column existed read as; see `.backfill()`. */
@@ -70,11 +85,11 @@ export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boo
     readonly renamedFromName?: string;
     readonly reference?: ColumnReferenceSpec;
     /** Marks the column nullable; inserts may omit it and reads may return null. */
-    nullable(): ColumnBuilder<TValue, true, TUnique, THasDefault, TInput>;
+    nullable(): ColumnBuilder<TValue, true, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /** Marks the table's unique key; exactly one non-nullable column may carry it. */
-    unique(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput>): ColumnBuilder<TValue, TNullable, true, THasDefault, TInput>;
+    unique(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput, TDomain, TGenerated>): ColumnBuilder<TValue, TNullable, true, THasDefault, TInput, TDomain, TGenerated>;
     /** Declares this column as the rename target of an existing catalog column. */
-    renamedFrom(name: string): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
+    renamedFrom(name: string): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /**
      * What rows written before this column existed read as, instead of NULL. Giving one is what
      * makes adding a non-nullable column possible: no stored byte is rewritten, and reads
@@ -84,7 +99,7 @@ export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boo
      * catalog — so it can derive a value (a timestamp, a version stamp) without readers ever
      * disagreeing. It cannot derive from other columns; that would need a value per row.
      */
-    backfill(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput>, value: TInput | (() => TInput)): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
+    backfill(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput, TDomain, TGenerated>, value: TInput | (() => TInput)): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /**
      * Declares a FOREIGN KEY onto another table's unique key. `migrate()` creates it as a real
      * constraint, so a write naming a parent row that does not exist is rejected — the same
@@ -92,31 +107,33 @@ export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boo
      *
      * `onDelete` defaults to `"restrict"`. `"set null"` requires a nullable column.
      */
-    references(this: ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>, table: string, column: string, options?: {
+    references(this: ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>, table: string, column: string, options?: {
         onDelete?: Exclude<ReferentialAction, "set null">;
         enforced?: true;
     } | {
         enforced: false;
         onDelete?: never;
-    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
-    references(this: ColumnBuilder<TValue, true, TUnique, THasDefault, TInput>, table: string, column: string, options: {
+    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
+    references(this: ColumnBuilder<TValue, true, TUnique, THasDefault, TInput, TDomain, TGenerated>, table: string, column: string, options: {
         onDelete: "set null";
         enforced?: true;
-    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
+    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /** Declares a literal SQL default. Omission or SQL `DEFAULT` invokes it; NULL does not. */
-    default(value: TInput): ColumnBuilder<TValue, TNullable, TUnique, true, TInput>;
+    default(value: TInput): ColumnBuilder<TValue, TNullable, TUnique, true, TInput, TDomain, TGenerated>;
     /**
      * Declares a variable-free SQL default expression, such as `CURRENT_TIMESTAMP`,
      * `gen_random_uuid()`, or `nextval('orders_id_seq')`. The engine parses and type-checks it
      * before migration and evaluates it once per omitted row.
      */
-    defaultSql(sql: string): ColumnBuilder<TValue, TNullable, TUnique, true, TInput>;
+    defaultSql(sql: string): ColumnBuilder<TValue, TNullable, TUnique, true, TInput, TDomain, TGenerated>;
+    /** Declares a stored expression over sibling columns. Callers never insert or update it. */
+    generatedSql(sql: string): ColumnBuilder<TValue, TNullable, TUnique, false, TInput, TDomain, true>;
     /**
      * Generates monotonically increasing integers for omitted or SQL `DEFAULT` slots from a persistent
      * per-table counter that is atomic across tabs. Explicit values are allowed and bump the
      * counter past their maximum. Number unique-key columns only.
      */
-    autoIncrement: TValue extends number ? (this: ColumnBuilder<TValue, false, true, THasDefault, TInput>) => ColumnBuilder<TValue, TNullable, TUnique, true, TInput> : never;
+    autoIncrement: TValue extends number ? (this: ColumnBuilder<TValue, false, true, THasDefault, TInput, TDomain, TGenerated>) => ColumnBuilder<TValue, TNullable, TUnique, true, TInput, TDomain, TGenerated> : never;
 }
 type SchemaValue = boolean | number | string | Date;
 /**
@@ -130,9 +147,14 @@ interface AnyColumn {
     readonly isNullable: boolean;
     readonly isUnique: boolean;
     readonly hasDefault: boolean;
+    readonly isGenerated: boolean;
     readonly integer: boolean;
     readonly sqlDomain?: SqlDomain;
     readonly defaultSpec?: ColumnDefault;
+    readonly generatedSpec?: {
+        readonly kind: "stored";
+        readonly sql: string;
+    };
     readonly enumValues?: readonly string[];
     readonly backfillValue?: SchemaValue | (() => SchemaValue);
     readonly renamedFromName?: string;
@@ -144,30 +166,30 @@ interface AnyColumn {
  */
 export declare function columnWithDefaultSpec(base: Pick<AnyColumn, "type" | "isNullable" | "isUnique" | "renamedFromName" | "reference" | "enumValues"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain">>, spec: ColumnDefault): AnyColumn;
 /** Rebuilds a fluent column from structured-clone-safe metadata. */
-export declare function columnFromState(state: Pick<AnyColumn, "type" | "isNullable" | "isUnique"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain" | "renamedFromName" | "reference" | "defaultSpec" | "enumValues" | "backfillValue">>): AnyColumn;
+export declare function columnFromState(state: Pick<AnyColumn, "type" | "isNullable" | "isUnique"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain" | "renamedFromName" | "reference" | "defaultSpec" | "generatedSpec" | "enumValues" | "backfillValue">>): AnyColumn;
 export declare const column: {
-    boolean: () => ColumnBuilder<boolean, false, false, false, boolean>;
-    number: () => ColumnBuilder<number, false, false, false, number>;
+    boolean: () => ColumnBuilder<boolean, false, false, false, boolean, undefined, false>;
+    number: () => ColumnBuilder<number, false, false, false, number, undefined, false>;
     /** Exact safe-integer semantics, matching SQL INTEGER/SMALLINT/BIGINT. */
-    integer: () => ColumnBuilder<number, false, false, false, number>;
-    string: () => ColumnBuilder<string, false, false, false, string>;
-    datetime: () => ColumnBuilder<Date, false, false, false, Date>;
+    integer: () => ColumnBuilder<number, false, false, false, number, undefined, false>;
+    string: () => ColumnBuilder<string, false, false, false, string, undefined, false>;
+    datetime: () => ColumnBuilder<Date, false, false, false, Date, undefined, false>;
     /** Exact decimal SQL NUMERIC. Selects return strings; writes accept strings or numbers. */
     numeric: (options?: {
         precision?: number;
         scale?: number;
-    }) => ColumnBuilder<string, false, false, false, string | number>;
-    json: () => ColumnBuilder<string, false, false, false, string>;
-    jsonb: () => ColumnBuilder<string, false, false, false, string>;
-    uuid: () => ColumnBuilder<string, false, false, false, string>;
+    }) => ColumnBuilder<string, false, false, false, string | number, "numeric", false>;
+    json: () => ColumnBuilder<string, false, false, false, string, "json", false>;
+    jsonb: () => ColumnBuilder<string, false, false, false, string, "jsonb", false>;
+    uuid: () => ColumnBuilder<string, false, false, false, string, "uuid", false>;
     /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
-    date: () => ColumnBuilder<string, false, false, false, string>;
-    time: () => ColumnBuilder<string, false, false, false, string>;
-    interval: () => ColumnBuilder<string, false, false, false, string>;
+    date: () => ColumnBuilder<string, false, false, false, string, "date", false>;
+    time: () => ColumnBuilder<string, false, false, false, string, "time", false>;
+    interval: () => ColumnBuilder<string, false, false, false, string, "interval", false>;
     /** JSON array text at the JavaScript boundary, with the SQL element type retained in metadata. */
-    array: (element: string) => ColumnBuilder<string, false, false, false, string>;
+    array: (element: string) => ColumnBuilder<string, false, false, false, string, "array", false>;
     /** A named SQL enum domain, distinct from the lightweight `column.enum()` restriction. */
-    sqlEnum: <const TValues extends readonly [string, ...string[]]>(name: string, values: TValues) => ColumnBuilder<TValues[number], false>;
+    sqlEnum: <const TValues extends readonly [string, ...string[]]>(name: string, values: TValues) => ColumnBuilder<TValues[number], false, false, false, TValues[number], "enum">;
     /**
      * A string column restricted to a closed set of values, typed as their literal union:
      *
@@ -310,11 +332,15 @@ type NullableKeys<TTable extends AnyTable> = {
 type DefaultKeys<TTable extends AnyTable> = {
     [K in keyof TTable["columns"]]: TTable["columns"][K]["hasDefault"] extends true ? K : never;
 }[keyof TTable["columns"]];
-type OptionalInsertKeys<TTable extends AnyTable> = NullableKeys<TTable> | DefaultKeys<TTable>;
+type GeneratedKeys<TTable extends AnyTable> = {
+    [K in keyof TTable["columns"]]: TTable["columns"][K]["isGenerated"] extends true ? K : never;
+}[keyof TTable["columns"]];
+type OptionalInsertKeys<TTable extends AnyTable> = Exclude<NullableKeys<TTable> | DefaultKeys<TTable>, GeneratedKeys<TTable>>;
+type RequiredInsertKeys<TTable extends AnyTable> = Exclude<keyof TTable["columns"], OptionalInsertKeys<TTable> | GeneratedKeys<TTable>>;
 /** Insert rows require every non-nullable column and may omit nullable or default-bearing ones. */
-export type InferInsertRow<TTable extends AnyTable> = Omit<{
-    [K in keyof TTable["columns"]]: ColumnInputValue<TTable["columns"][K]>;
-}, OptionalInsertKeys<TTable>> & {
+export type InferInsertRow<TTable extends AnyTable> = {
+    [K in RequiredInsertKeys<TTable>]: ColumnInputValue<TTable["columns"][K]>;
+} & {
     [K in OptionalInsertKeys<TTable>]?: ColumnInputValue<TTable["columns"][K]>;
 };
 /** Scalar `.unique()` keys plus columns named by a table-level primary key. */
@@ -327,7 +353,7 @@ export type PrimaryKeyKeys<TTable extends AnyTable> = {
  * stays assignable under `exactOptionalPropertyTypes`.
  */
 export type InferUpdateChanges<TTable extends AnyTable> = {
-    [K in keyof TTable["columns"] as K extends PrimaryKeyKeys<TTable> ? never : K]?: ColumnInputValue<TTable["columns"][K]> | undefined;
+    [K in keyof TTable["columns"] as K extends PrimaryKeyKeys<TTable> | GeneratedKeys<TTable> ? never : K]?: ColumnInputValue<TTable["columns"][K]> | undefined;
 };
 export type MigrationStep = {
     kind: "create-table";
@@ -376,6 +402,14 @@ export type MigrationStep = {
     tableName: string;
     columnName: string;
     defaultValue: ColumnDefault | null;
+} | {
+    kind: "alter-generated";
+    tableName: string;
+    columnName: string;
+    generatedValue: {
+        readonly kind: "stored";
+        readonly sql: string;
+    } | null;
 }
 /** Informational relationships are catalog-only and may change without scanning stored rows. */
  | {

package/dist/engine/schema.js

@@ -1,7 +1,52 @@
 import { copyDate, dateMilliseconds } from "../date-value.js";
 import { validateColumnDefault, validateEnumValues, validateSqlDomain, } from "../storage/types.js";
-import { compileCheckExpression, expressionColumns, validateDefaultExpression, } from "./query.js";
+import { childExpressions, compileCheckExpression, expressionColumns, hasAggregate, validateDefaultExpression, } from "./query.js";
 import { externalSqlDomainValue, normalizeSqlDomainValue } from "./sql-domains.js";
+const volatileGeneratedFunctions = new Set([
+    "CURRENT_DATE",
+    "CURRENT_TIMESTAMP",
+    "LOCALTIME",
+    "RANDOM",
+    "GEN_RANDOM_UUID",
+    "NEXTVAL",
+    "CURRVAL",
+]);
+/** Compiles and validates one immutable, row-local generated-column expression. */
+export function compileGeneratedColumnExpression(tableName, columnName, sql, columns) {
+    if (sql.length === 0 || sql.trim() !== sql) {
+        throw new TypeError(`Generated SQL must be a trimmed non-empty expression: ${tableName}.${columnName}`);
+    }
+    const expression = compileCheckExpression(sql, `generated ${tableName}.${columnName}`);
+    if (hasAggregate(expression)) {
+        throw new TypeError(`Generated column ${tableName}.${columnName} must be an immutable expression over sibling columns`);
+    }
+    const inspect = (node) => {
+        if (node.kind === "subquery" || node.kind === "exists") {
+            throw new TypeError(`Generated column ${tableName}.${columnName} must be an immutable expression over sibling columns`);
+        }
+        if (node.kind === "call" && volatileGeneratedFunctions.has(node.name)) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} cannot call volatile function ${node.name}`);
+        }
+        childExpressions(node).forEach(inspect);
+    };
+    inspect(expression);
+    for (const reference of expressionColumns(expression)) {
+        const pieces = reference.split(".");
+        const referencedName = pieces.at(-1) ?? reference;
+        const qualifier = pieces.length > 1 ? pieces.slice(0, -1).join(".") : undefined;
+        if (qualifier !== undefined && qualifier !== tableName) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} references another table: ${reference}`);
+        }
+        const referenced = columns.find(({ name }) => name === referencedName);
+        if (referenced === undefined) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} names an unknown column: ${referencedName}`);
+        }
+        if (referencedName === columnName || referenced.generatedValue !== undefined) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} cannot reference a generated column: ${referencedName}`);
+        }
+    }
+    return expression;
+}
 /**
  * The constraint name `migrate()` gives a declared relation. It matches the name the SQL parser
  * derives for an unnamed inline REFERENCES, so a table built either way has the same catalog.
@@ -45,9 +90,11 @@ function createColumn(type, state = {}) {
         isNullable: (state.isNullable ?? false),
         isUnique: (state.isUnique ?? false),
         hasDefault: (state.defaultSpec !== undefined),
+        isGenerated: (state.generatedSpec !== undefined),
         integer: state.integer ?? false,
         ...(state.sqlDomain === undefined ? {} : { sqlDomain: state.sqlDomain }),
         ...(state.defaultSpec === undefined ? {} : { defaultSpec: state.defaultSpec }),
+        ...(state.generatedSpec === undefined ? {} : { generatedSpec: state.generatedSpec }),
         ...(state.renamedFromName === undefined ? {} : { renamedFromName: state.renamedFromName }),
         ...(state.reference === undefined ? {} : { reference: state.reference }),
         ...(state.enumValues === undefined ? {} : { enumValues: state.enumValues }),
@@ -65,9 +112,15 @@ function createColumn(type, state = {}) {
         }),
         renamedFrom: (name) => {
             validateSchemaName(name, "Rename source");
-            return createColumn(type, { ...state, renamedFromName: name });
+            return createColumn(type, {
+                ...state,
+                renamedFromName: name,
+            });
         },
-        backfill: (value) => createColumn(type, { ...state, backfillValue: value }),
+        backfill: (value) => createColumn(type, {
+            ...state,
+            backfillValue: value,
+        }),
         references: (table, referencedColumn, options = {}) => {
             validateSchemaName(table, "Referenced table");
             validateSchemaName(referencedColumn, "Referenced column");
@@ -100,6 +153,19 @@ function createColumn(type, state = {}) {
                 defaultSpec: { kind: "expression", sql: expression },
             });
         }),
+        generatedSql: (sql) => {
+            const expression = sql.trim();
+            if (expression.length === 0 || expression !== sql) {
+                throw new TypeError("Generated SQL must be a trimmed non-empty expression");
+            }
+            if (state.defaultSpec !== undefined) {
+                throw new TypeError("A generated column cannot also have a default");
+            }
+            return createColumn(type, {
+                ...state,
+                generatedSpec: { kind: "stored", sql: expression },
+            });
+        },
         autoIncrement: (() => {
             if (type !== "number") {
                 throw new TypeError("Auto-increment requires a number column");
@@ -145,6 +211,7 @@ export function columnFromState(state) {
         ...(state.renamedFromName === undefined ? {} : { renamedFromName: state.renamedFromName }),
         ...(state.reference === undefined ? {} : { reference: state.reference }),
         ...(state.defaultSpec === undefined ? {} : { defaultSpec: state.defaultSpec }),
+        ...(state.generatedSpec === undefined ? {} : { generatedSpec: state.generatedSpec }),
         ...(state.enumValues === undefined ? {} : { enumValues: state.enumValues }),
         ...(state.backfillValue === undefined ? {} : { backfillValue: state.backfillValue }),
     });
@@ -167,7 +234,9 @@ export const column = {
     /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
     date: () => createColumn("string", { sqlDomain: { kind: "date" } }),
     time: () => createColumn("string", { sqlDomain: { kind: "time" } }),
-    interval: () => createColumn("string", { sqlDomain: { kind: "interval" } }),
+    interval: () => createColumn("string", {
+        sqlDomain: { kind: "interval" },
+    }),
     /** JSON array text at the JavaScript boundary, with the SQL element type retained in metadata. */
     array: (element) => createColumn("string", {
         sqlDomain: validateSqlDomain({ kind: "array", element }, "array column"),
@@ -252,6 +321,10 @@ export function table(name, columns, options = {}) {
     if (uniqueEntry?.[1].isNullable === true) {
         throw new TypeError(`Table ${name} unique column must not be nullable: ${uniqueEntry[0]}`);
     }
+    const generatedColumns = entries.map(([columnName, definition]) => ({
+        name: columnName,
+        ...(definition.generatedSpec === undefined ? {} : { generatedValue: definition.generatedSpec }),
+    }));
     for (const [columnName, definition] of entries) {
         validateSchemaName(columnName, "Column");
         if (definition.integer && definition.type !== "number") {
@@ -276,6 +349,15 @@ export function table(name, columns, options = {}) {
         if (backfill !== undefined && definition.isNullable) {
             throw new TypeError(`A nullable column needs no backfill: ${name}.${columnName}. Rows without it already read NULL.`);
         }
+        if (definition.generatedSpec !== undefined) {
+            if (definition.defaultSpec !== undefined || backfill !== undefined) {
+                throw new TypeError(`A generated column cannot also have a default or backfill: ${name}.${columnName}`);
+            }
+            compileGeneratedColumnExpression(name, columnName, definition.generatedSpec.sql, generatedColumns);
+            if (definition.isUnique || primaryKey.includes(columnName)) {
+                throw new TypeError(`Generated columns cannot be row-addressing keys: ${name}.${columnName}`);
+            }
+        }
         if (definition.reference?.onDelete === "set null" && !definition.isNullable) {
             throw new TypeError(`ON DELETE SET NULL requires a nullable column: ${name}.${columnName}`);
         }
@@ -483,6 +565,9 @@ export function view(name, definition) {
         if (columnDefinition.defaultSpec !== undefined) {
             throw new TypeError(`A view column cannot have a default: ${name}.${columnName}`);
         }
+        if (columnDefinition.generatedSpec !== undefined) {
+            throw new TypeError(`A view column cannot be generated: ${name}.${columnName}`);
+        }
     }
     return { kind: "view", name, sql: definition.sql, columns: definition.columns };
 }
@@ -636,6 +721,20 @@ export function assertColumnDroppable(record, column) {
             throw new TypeError(`CHECK ${check.name} still uses this column: ${where}`);
         }
     }
+    for (const dependent of record.columns) {
+        if (dependent.generatedValue === undefined)
+            continue;
+        let referenced;
+        try {
+            referenced = expressionColumns(compileCheckExpression(dependent.generatedValue.sql, `generated ${record.name}.${dependent.name}`));
+        }
+        catch {
+            throw new TypeError(`Generated column ${dependent.name} cannot be re-read, so ${where} is not droppable`);
+        }
+        if (referenced.includes(column.name)) {
+            throw new TypeError(`Generated column ${dependent.name} still uses this column: ${where}`);
+        }
+    }
 }
 function assertColumnRenamable(catalog, record, column) {
     const where = `${record.name}.${column.name}`;
@@ -654,6 +753,14 @@ function assertColumnRenamable(catalog, record, column) {
             throw new TypeError(`CHECK ${check.name} prevents renaming ${where}`);
         }
     }
+    for (const dependent of record.columns) {
+        if (dependent.generatedValue === undefined)
+            continue;
+        const referenced = expressionColumns(compileCheckExpression(dependent.generatedValue.sql, `generated ${record.name}.${dependent.name}`));
+        if (referenced.includes(column.name)) {
+            throw new TypeError(`Generated column ${dependent.name} prevents renaming ${where}`);
+        }
+    }
 }
 /**
  * Freezes a column's backfill. A generator runs exactly once — here, while the migration is being
@@ -793,6 +900,9 @@ export function planMigration(catalog, definition, options = {}) {
                 }
             }
             if (existing === undefined) {
+                if (columnDefinition.generatedSpec !== undefined) {
+                    throw new TypeError(`Generated columns cannot be added to an existing table without rewriting its rows: ${tableDefinition.name}.${columnName}`);
+                }
                 const backfill = resolveBackfill(columnDefinition);
                 if (!columnDefinition.isNullable && backfill === undefined) {
                     throw new TypeError(`Added columns must be nullable, or carry a backfill: ${tableDefinition.name}.${columnName}`);
@@ -890,13 +1000,24 @@ export function planMigration(catalog, definition, options = {}) {
                         columnName,
                         enabled: isAuto,
                     });
-                    continue;
                 }
+                else {
+                    steps.push({
+                        kind: "alter-default",
+                        tableName: tableDefinition.name,
+                        columnName,
+                        defaultValue: columnDefinition.defaultSpec ?? null,
+                    });
+                }
+            }
+            const existingGenerated = existing.generatedValue;
+            const definedGenerated = columnDefinition.generatedSpec;
+            if (JSON.stringify(existingGenerated ?? null) !== JSON.stringify(definedGenerated ?? null)) {
                 steps.push({
-                    kind: "alter-default",
+                    kind: "alter-generated",
                     tableName: tableDefinition.name,
                     columnName,
-                    defaultValue: columnDefinition.defaultSpec ?? null,
+                    generatedValue: definedGenerated ?? null,
                 });
             }
         }
@@ -1184,6 +1305,16 @@ export function applyColumnSteps(record, steps, createId) {
                 else
                     target.defaultValue = step.defaultValue;
             }
+            continue;
+        }
+        if (step.kind === "alter-generated") {
+            const target = columns.find(({ name }) => name === step.columnName);
+            if (target !== undefined) {
+                if (step.generatedValue === null)
+                    delete target.generatedValue;
+                else
+                    target.generatedValue = step.generatedValue;
+            }
         }
     }
     return columns;

package/dist/engine/sql-domains.d.ts

@@ -18,6 +18,14 @@ export declare function exactNumericCompare(left: unknown, right: unknown): numb
  */
 export declare function boundedJsonText(value: unknown, canonical: boolean, label?: string): string;
 export declare function jsonDomainValue(value: unknown, binary: boolean): string | null;
+/** Returns the JSON document carried by an internal JSON/JSONB scalar, if any. */
+export declare function jsonDomainDocument(value: unknown): string | undefined;
+/**
+ * Tags already-constructed JSON without parsing and re-stringifying it. The validation parse
+ * rejects malformed documents, while retaining duplicate object names and the constructor's
+ * exact member order for embedding in an outer JSON value.
+ */
+export declare function preservedJsonDomainValue(document: string, binary?: boolean): string;
 export declare function uuidDomainValue(value: unknown): string | null;
 /** Canonical, zoneless SQL DATE value. No JavaScript time zone participates in validation. */
 export declare function dateDomainValue(value: unknown): string | null;

package/dist/engine/sql-domains.js

@@ -313,6 +313,31 @@ export function jsonDomainValue(value, binary) {
     const text = boundedJsonText(parsed, binary, binary ? "JSONB value" : "JSON value");
     return boundedTaggedDomainValue(binary ? JSONB_VALUE : JSON_VALUE, text, binary ? "JSONB value" : "JSON value");
 }
+/** Returns the JSON document carried by an internal JSON/JSONB scalar, if any. */
+export function jsonDomainDocument(value) {
+    if (typeof value !== "string")
+        return undefined;
+    if (value.startsWith(JSONB_VALUE))
+        return value.slice(JSONB_VALUE.length);
+    if (value.startsWith(JSON_VALUE))
+        return value.slice(JSON_VALUE.length);
+    return undefined;
+}
+/**
+ * Tags already-constructed JSON without parsing and re-stringifying it. The validation parse
+ * rejects malformed documents, while retaining duplicate object names and the constructor's
+ * exact member order for embedding in an outer JSON value.
+ */
+export function preservedJsonDomainValue(document, binary = false) {
+    assertBoundedDomainString(document, binary ? "JSONB value" : "JSON value");
+    try {
+        JSON.parse(document);
+    }
+    catch {
+        throw new TypeError("Invalid JSON value");
+    }
+    return boundedTaggedDomainValue(binary ? JSONB_VALUE : JSON_VALUE, document, binary ? "JSONB value" : "JSON value");
+}
 export function uuidDomainValue(value) {
     if (value === null || value === undefined)
         return null;

package/dist/engine/sql-json.js

@@ -1,5 +1,5 @@
 import { stringArgument } from "./sql-semantics.js";
-import { externalSqlDomainValue } from "./sql-domains.js";
+import { externalSqlDomainValue, jsonDomainDocument } from "./sql-domains.js";
 import { MAX_CACHEABLE_TEXT_CHARACTERS, MAX_SQL_SCALAR_RESULT_CHARACTERS } from "./cache-limits.js";
 export function parseJsonPath(path, caller) {
     const text = stringArgument(caller, path).trim();
@@ -119,7 +119,7 @@ export function jsonConstructor(name, values) {
     }
     const members = [];
     for (let index = 0; index + 1 < values.length; index += 2) {
-        const rawKey = values[index];
+        const rawKey = externalSqlDomainValue(values[index]);
         if (rawKey === null || rawKey === undefined) {
             throw new TypeError("JSON_OBJECT keys cannot be NULL");
         }
@@ -136,12 +136,24 @@ export function jsonConstructor(name, values) {
         // Build JSON text directly. WITHOUT UNIQUE KEYS is the default, so duplicate names must be
         // preserved; assigning through a JavaScript object would collapse them and mishandle
         // special names such as "__proto__".
-        const encodedKey = boundedJsonValue(key, "JSON_OBJECT key");
+        // Keys are always JSON strings. In particular, a JSON-domain expression used as a key is
+        // its document text, not a raw object member token as JSON-domain values are below.
+        const encodedKey = boundedJsonString(key, "JSON_OBJECT key");
         const encodedValue = boundedJsonValue(member ?? null, "JSON_OBJECT value");
         members.push(`${encodedKey}:${encodedValue}`);
     }
     return joinBoundedJson("{", members, "}", "JSON_OBJECT result");
 }
+function boundedJsonString(value, label) {
+    if (value.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
+    return encoded;
+}
 function boundedJsonDocument(value, caller) {
     const document = stringArgument(caller, externalSqlDomainValue(value));
     if (document.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
@@ -150,6 +162,13 @@ function boundedJsonDocument(value, caller) {
     return document;
 }
 function boundedJsonValue(value, label) {
+    const domainDocument = jsonDomainDocument(value);
+    if (domainDocument !== undefined) {
+        if (domainDocument.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+            throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+        }
+        return domainDocument;
+    }
     const normalized = jsonValueOf(value);
     if (typeof normalized === "string" && normalized.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
         throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);

package/dist/engine/vector.d.ts

@@ -75,6 +75,8 @@ export interface QuerySpillStore {
 export interface AsyncQueryExecutionOptions {
     readonly spillStore?: QuerySpillStore;
     readonly spillPageRows?: number;
+    /** Stops before the next execution or spill-storage batch. */
+    readonly signal?: AbortSignal;
     /**
      * Makes the scan-source window [start, start + length) resident before each batch. Supplied by
      * a streaming preparation whose scan-source vectors hold only a sliding window; the executor
@@ -88,8 +90,6 @@ export interface AsyncQueryExecutionOptions {
 export interface QueryBatchExecutionOptions extends AsyncQueryExecutionOptions {
     /** Maximum result rows handed to the consumer at once. */
     readonly batchRows: number;
-    /** Stops before the next scan batch and is checked after every awaited storage read. */
-    readonly signal?: AbortSignal;
 }
 export interface PrepareVectorQueryOptions {
     readonly memoryContext?: QueryMemoryContext;