@quereus/quereus 4.10.0 → 4.12.0

package/dist/src/schema/manager.js

@@ -2,11 +2,13 @@ import { Schema } from './schema.js';
 import { normalizeCollationName } from '../util/comparison.js';
 import { quereusError, QuereusError, RelationNotFoundError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
-import { buildColumnIndexMap, columnDefToSchema, findPKDefinition, opsToMask, mutationContextVarToSchema, extractGeneratedColumnDependencies, topoSortGeneratedColumns, requireVtabModule, resolveNamedConstraintClass, appendIndexToTableSchema } from './table.js';
+import { foldDefaultToType } from '../types/validation.js';
+import { buildColumnIndexMap, columnDefToSchema, findPKDefinition, opsToMask, mutationContextVarToSchema, extractGeneratedColumnDependencies, topoSortGeneratedColumns, requireVtabModule, resolveNamedConstraintClass, appendIndexToTableSchema, collectDeclaredConstraintNames, disambiguateAutoConstraintName } from './table.js';
 import { buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, validateForeignKeyCollations } from './constraint-builder.js';
+import { buildColumnSourceResolver } from './column-source-resolver.js';
 import { normalizeBackingModule } from './view.js';
 import { isMaintainedTable } from './derivation.js';
-import { isHiddenImplicitIndex, isImplicitCoveringIndex, findExposedImplicitConstraintIndex, assertNoDuplicateUniqueConstraints } from './catalog.js';
+import { isHiddenImplicitIndex, isImplicitCoveringIndex, findExposedImplicitConstraintIndex, assertNoDuplicateUniqueConstraints, assertNoDuplicateUniqueConstraintBackingNames, assertNoDuplicateConstraintNames } from './catalog.js';
 import { assertCatalogObjectPersistable } from './catalog-persistability.js';
 import { buildLensBasisFkGate } from './lens-fk-discovery.js';
 import { createLogger } from '../common/logger.js';
@@ -63,6 +65,18 @@ function maintainedImportFromTableStmt(stmt) {
         tags: stmt.tags,
     };
 }
+/**
+ * Shared rejection for a non-deterministic call found in a schema-level expression
+ * at declaration time — one wording across the CHECK and GENERATED gates, so the
+ * two surfaces cannot drift apart in how they explain the same rule.
+ *
+ * @param site Where the call was found, e.g. `CHECK constraint 'c' on table 't'`.
+ */
+function nonDeterministicDeclarationError(site, offendingExpr) {
+    return new QuereusError(`Non-deterministic expression not allowed in ${site}. ` +
+        `Function '${offendingExpr.name}' is not deterministic. ` +
+        `Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`, StatusCode.ERROR);
+}
 /**
  * Manages all schemas associated with a database connection (main, temp, attached).
  * Handles lookup resolution according to SQLite's rules.
@@ -1470,14 +1484,20 @@ export class SchemaManager {
     }
     /**
      * Extracts CHECK constraints from AST column and table constraint definitions.
+     *
+     * An unnamed column-level CHECK is minted `_check_<col>`; two on one column are
+     * legal, so the mint disambiguates through the statement-wide `takenNames` set
+     * (`_check_b`, then `_check_b_2`) — see `disambiguateAutoConstraintName`. An
+     * unnamed table-level CHECK keeps no name at all (unchanged), so it cannot
+     * collide.
      */
-    extractCheckConstraints(astColumns, astConstraints) {
+    extractCheckConstraints(astColumns, astConstraints, takenNames) {
         const result = [];
         for (const colDef of astColumns) {
             for (const con of colDef.constraints ?? []) {
                 if (con.type === 'check' && con.expr) {
                     result.push({
-                        name: con.name ?? `_check_${colDef.name}`,
+                        name: con.name ?? disambiguateAutoConstraintName(`_check_${colDef.name}`, takenNames),
                         expr: con.expr,
                         operations: opsToMask(con.operations),
                         defaultConflict: con.onConflict,
@@ -1504,7 +1524,7 @@ export class SchemaManager {
      * Resolves column indices in the child table. Parent table resolution is deferred
      * to enforcement time (the parent table may not exist yet during declarative schema setup).
      */
-    extractForeignKeys(astColumns, astConstraints, columnIndexMap, tableName, schemaName) {
+    extractForeignKeys(astColumns, astConstraints, columnIndexMap, tableName, schemaName, takenNames) {
         const result = [];
         // Column-level foreign keys
         for (const colDef of astColumns) {
@@ -1521,11 +1541,13 @@ export class SchemaManager {
                         throw new QuereusError(`FK constraint '${con.name ?? `_fk_${tableName}_${colDef.name}`}' on table '${tableName}': child column count (1) does not match parent column count (${fk.columns.length})`, StatusCode.ERROR);
                     }
                     result.push({
-                        name: con.name ?? `_fk_${tableName}_${colDef.name}`,
+                        // Two FKs on one child column (different parents) are legal SQL,
+                        // so a colliding mint disambiguates (`_fk_C_x`, then `_fk_C_x_2`)
+                        // rather than rejecting — see `disambiguateAutoConstraintName`.
+                        name: con.name ?? disambiguateAutoConstraintName(`_fk_${tableName}_${colDef.name}`, takenNames),
                         columns: Object.freeze([childColIndex]),
                         referencedTable: fk.table,
                         referencedSchema: fk.schema ?? schemaName,
-                        referencedColumns: Object.freeze([]), // resolved at enforcement time
                         referencedColumnNames: fk.columns, // deferred resolution via resolveReferencedColumns
                         onDelete: fk.onDelete ?? 'restrict',
                         onUpdate: fk.onUpdate ?? 'restrict',
@@ -1539,7 +1561,7 @@ export class SchemaManager {
         // `ADD CONSTRAINT` path and CREATE TABLE produce byte-identical schemas.
         for (const con of astConstraints ?? []) {
             if (con.type === 'foreignKey' && con.foreignKey && con.columns) {
-                result.push(buildForeignKeyConstraintSchema(con, columnIndexMap, tableName, schemaName));
+                result.push(buildForeignKeyConstraintSchema(con, columnIndexMap, tableName, schemaName, takenNames));
             }
         }
         return result;
@@ -1597,17 +1619,25 @@ export class SchemaManager {
         const defaultNotNull = defaultNullability === 'not_null';
         const astColumns = stmt.columns || [];
         const { columns, pkDefinition, pkDefaultConflict } = this.buildColumnSchemas(astColumns, stmt.constraints, defaultNotNull, defaultCollation);
-        const checkConstraints = this.extractCheckConstraints(astColumns, stmt.constraints);
+        // Statement-wide taken-set the CHECK / FK mint sites disambiguate against:
+        // seeded with every user-written constraint name up front, then accumulating
+        // each mint, so a colliding auto-name gets a `_<N>` suffix instead of
+        // producing two constraints one name addresses. Shared across the extractors
+        // — one name space, not three.
+        const takenConstraintNames = collectDeclaredConstraintNames(astColumns, stmt.constraints);
+        const checkConstraints = this.extractCheckConstraints(astColumns, stmt.constraints, takenConstraintNames);
         const columnIndexMap = buildColumnIndexMap(columns);
-        const foreignKeys = this.extractForeignKeys(astColumns, stmt.constraints, columnIndexMap, tableName, targetSchemaName);
+        const foreignKeys = this.extractForeignKeys(astColumns, stmt.constraints, columnIndexMap, tableName, targetSchemaName, takenConstraintNames);
         const uniqueConstraints = this.extractUniqueConstraints(astColumns, stmt.constraints, columnIndexMap);
         const mutationContextSchemas = stmt.contextDefinitions
             ? stmt.contextDefinitions.map(varDef => mutationContextVarToSchema(varDef, defaultNotNull))
             : undefined;
         // Extract generated-column dependencies and validate that they form a DAG.
         // Cycle detection runs before module.create so an invalid schema never
-        // reaches storage.
-        const rawGenDeps = extractGeneratedColumnDependencies(columns, tableName);
+        // reaches storage. The catalog resolver serves the scope-aware analysis's
+        // inner-FROM questions; the table being created is answered from the
+        // in-flight `columns` (it is not in the catalog yet).
+        const rawGenDeps = extractGeneratedColumnDependencies(columns, tableName, targetSchemaName, buildColumnSourceResolver(this.db));
         const genTopoOrder = rawGenDeps.size > 0
             ? topoSortGeneratedColumns(columns, rawGenDeps)
             : undefined;
@@ -1646,6 +1676,13 @@ export class SchemaManager {
      * registered or executed; its compiled effective body is registered as a
      * `ViewSchema`. Module association / indexes / storage are rejected upstream
      * by the lens compiler before this is called.
+     *
+     * NOTE: `assertNoDuplicateConstraintNames` is deliberately NOT run here — it
+     * guards `createTable` only. A logical table is never a `DROP CONSTRAINT` /
+     * `RENAME CONSTRAINT` target, so a colliding user-written name in a lens
+     * declaration costs nothing today; running the guard would instead risk
+     * refusing a lens declaration that deployed before the guard existed. Revisit
+     * if named-constraint lifecycle verbs ever address a logical table.
      */
     buildLogicalTableSchema(stmt, schemaName) {
         const tableName = stmt.table.name;
@@ -1655,9 +1692,12 @@ export class SchemaManager {
         const defaultCollation = normalizeCollationName(this.db.options.getStringOption('default_collation'));
         const astColumns = stmt.columns || [];
         const { columns, pkDefinition, pkDefaultConflict } = this.buildColumnSchemas(astColumns, stmt.constraints, defaultNotNull, defaultCollation);
-        const checkConstraints = this.extractCheckConstraints(astColumns, stmt.constraints);
+        // Same statement-wide mint disambiguation as buildTableSchemaFromAST, so a
+        // logical spec and the physical table it describes mint identical names.
+        const takenConstraintNames = collectDeclaredConstraintNames(astColumns, stmt.constraints);
+        const checkConstraints = this.extractCheckConstraints(astColumns, stmt.constraints, takenConstraintNames);
         const columnIndexMap = buildColumnIndexMap(columns);
-        const foreignKeys = this.extractForeignKeys(astColumns, stmt.constraints, columnIndexMap, tableName, schemaName);
+        const foreignKeys = this.extractForeignKeys(astColumns, stmt.constraints, columnIndexMap, tableName, schemaName, takenConstraintNames);
         const uniqueConstraints = this.extractUniqueConstraints(astColumns, stmt.constraints, columnIndexMap);
         return {
             name: tableName,
@@ -1791,6 +1831,7 @@ export class SchemaManager {
             schemaDependencies: new BuildTimeDependencyTracker(),
             schemaCache: new Map(),
             cteReferenceCache: new Map(),
+            cteDescriptors: new Map(),
             outputScopes: new Map()
         };
     }
@@ -1908,30 +1949,76 @@ export class SchemaManager {
             });
             if (allowNonDeterministic)
                 continue;
-            let offendingExpr;
-            traverseAst(cc.expr, {
-                enterNode: (node) => {
-                    if (offendingExpr)
-                        return false;
-                    if (node.type !== 'function')
-                        return;
-                    const fnNode = node;
-                    const argCount = fnNode.args?.length ?? 0;
-                    const funcSchema = this.findFunction(fnNode.name, argCount)
-                        ?? this.findFunction(fnNode.name, -1);
-                    if (funcSchema && (funcSchema.flags & FunctionFlags.DETERMINISTIC) === 0) {
-                        offendingExpr = fnNode;
-                        return false;
-                    }
-                },
-            });
+            const offendingExpr = this.findNonDeterministicCall(cc.expr);
             if (offendingExpr) {
-                throw new QuereusError(`Non-deterministic expression not allowed in CHECK constraint '${constraintName}' on table '${tableName}'. ` +
-                    `Function '${offendingExpr.name}' is not deterministic. ` +
-                    `Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`, StatusCode.ERROR);
+                throw nonDeterministicDeclarationError(`CHECK constraint '${constraintName}' on table '${tableName}'`, offendingExpr);
             }
         }
     }
+    /**
+     * Validates that `GENERATED ALWAYS AS` expressions don't call non-deterministic
+     * functions, so a declaration no write could ever satisfy is refused where it is
+     * written rather than at every later INSERT/UPDATE.
+     *
+     * Called from {@link createTable} beside the CHECK / DEFAULT gates rather than from
+     * the shared {@link buildTableSchemaFromAST}, and for the same reason those two are:
+     * the import/rehydrate path shares that builder, and `nondeterministic_schema` is a
+     * *session* option — a table legitimately declared while the pragma was on must still
+     * reload into a session that has it off, instead of failing the whole catalog open.
+     * `ALTER TABLE ADD COLUMN` runs its own equivalent gate (see
+     * `planner/building/alter-table.ts`), so both authoring surfaces agree.
+     *
+     * NOTE: the sibling generated-column gate — `unboundQualifierError` in `./table.ts`,
+     * reached from the builder — deliberately DOES fire on reload, and the two are not
+     * meant to converge. A body naming something nothing binds is unwritable in every
+     * session, so no reload of it can be legitimate; a non-deterministic body is
+     * legitimately writable whenever the pragma is on, so rejecting it on reload would
+     * close a database this same build opened. Revisit both together if reload ever
+     * gains a general "refuse schemas no write can satisfy" pass.
+     */
+    validateGeneratedColumnDeterminism(columns, tableName, allowNonDeterministic = false) {
+        if (allowNonDeterministic)
+            return;
+        for (const col of columns) {
+            if (!col.generated || !col.generatedExpr)
+                continue;
+            const offendingExpr = this.findNonDeterministicCall(col.generatedExpr);
+            if (offendingExpr) {
+                throw nonDeterministicDeclarationError(`GENERATED ALWAYS AS for column '${col.name}' in table '${tableName}'`, offendingExpr);
+            }
+        }
+    }
+    /**
+     * The first function call under `expr` whose registry entry lacks
+     * `FunctionFlags.DETERMINISTIC`, or undefined if every call is deterministic.
+     * A name the registry cannot resolve is skipped — an unknown function still
+     * surfaces at write time, not here.
+     *
+     * Shared by the CHECK and GENERATED declaration-time gates. Both walk the raw
+     * AST rather than building the expression the way {@link validateDefaultDeterminism}
+     * does: their bodies name the table's own columns, whose scope does not exist
+     * yet at declaration time.
+     */
+    findNonDeterministicCall(expr) {
+        let offendingExpr;
+        traverseAst(expr, {
+            enterNode: (node) => {
+                if (offendingExpr)
+                    return false;
+                if (node.type !== 'function')
+                    return;
+                const fnNode = node;
+                const argCount = fnNode.args?.length ?? 0;
+                const funcSchema = this.findFunction(fnNode.name, argCount)
+                    ?? this.findFunction(fnNode.name, -1);
+                if (funcSchema && (funcSchema.flags & FunctionFlags.DETERMINISTIC) === 0) {
+                    offendingExpr = fnNode;
+                    return false;
+                }
+            },
+        });
+        return offendingExpr;
+    }
     /**
      * Registers a table schema after module.create() returns, correcting
      * name/schema if the module returned different values.
@@ -1995,7 +2082,7 @@ export class SchemaManager {
             }
             throw new QuereusError(`Index ${indexName} already exists on table ${tableName}`, StatusCode.CONSTRAINT, undefined, stmt.index.loc?.start.line, stmt.index.loc?.start.column);
         }
-        // Index names are unique per schema, not per table (docs/sql-ddl.md §6.3).
+        // Index names are unique per schema, not per table (docs/sql-vtab.md §6.3).
         // Every by-name index resolver — `dropIndex`, `updateIndexTags`, sync's
         // `findIndexOwner` — locates the owning table by first-match scan over the
         // schema's tables, and "first" is registration order, which is not stable
@@ -2084,7 +2171,7 @@ export class SchemaManager {
      * schema-wide name-uniqueness check ({@link findIndexNameOwnerElsewhere}) and
      * `@quereus/sync`'s replicated index DDL all funnel here.
      *
-     * Index names are unique per schema, not per table (docs/sql-ddl.md §6.3), and
+     * Index names are unique per schema, not per table (docs/sql-vtab.md §6.3), and
      * {@link createIndex} rejects a name already taken elsewhere in the schema, so
      * first-match is unambiguous by construction. That invariant is what makes
      * replication safe: a replicated `drop index "main"."idx"` carries no table name
@@ -2347,6 +2434,25 @@ export class SchemaManager {
         const allowNonDet = this.db.options.getBooleanOption('nondeterministic_schema');
         this.validateDefaultDeterminism(baseTableSchema.columns, tableName, hasMutationContext, allowNonDet);
         this.validateCheckConstraintDeterminism(baseTableSchema.checkConstraints, tableName, allowNonDet);
+        this.validateGeneratedColumnDeterminism(baseTableSchema.columns, tableName, allowNonDet);
+        // A literal DEFAULT must be convertible to its own column's declared type — the same
+        // check ADD COLUMN and SET NOT NULL backfill already run — so an unconvertible one is
+        // refused here rather than surfacing later as an INSERT failure blaming the insert
+        // instead of the declaration. Engine-side and pre-`module.create`, same rationale as
+        // the guards below: one gate covers every backend, and a refusal leaves no storage
+        // behind. Non-literal defaults (a function call, `new.<col>`, a bare column reference)
+        // fold to `undefined` and stay deferred to write time, unchanged.
+        for (const col of baseTableSchema.columns) {
+            foldDefaultToType(col.defaultValue, col.logicalType, col.name);
+        }
+        // Refuse a CREATE TABLE carrying two user-written constraint names that collide —
+        // one case-folded name space across CHECK / UNIQUE / FK, so the same-class shape
+        // (DROP removes both) and the cross-class shape (permanently un-droppable as
+        // ambiguous) are both refused at birth. Same rule every ALTER path enforces via
+        // `assertConstraintNameFree`; reads the raw declaration, so engine-minted names
+        // (two unnamed CHECKs on one column — legal) are not compared. Placement shares
+        // the duplicate-UNIQUE guard's rationale below.
+        assertNoDuplicateConstraintNames(stmt.columns ?? [], stmt.constraints, `create table '${tableName}'`);
         // Refuse a CREATE TABLE that declares the same plain UNIQUE twice — the same rule
         // `ALTER TABLE ADD CONSTRAINT` / `ADD COLUMN … unique` apply, so a duplicate is
         // refused identically wherever it is written. Before `module.create`, so the
@@ -2355,6 +2461,32 @@ export class SchemaManager {
         // still open a catalog written before this guard existed (same placement rationale
         // as the FK-collation check below).
         assertNoDuplicateUniqueConstraints(baseTableSchema.uniqueConstraints ?? [], baseTableSchema.columns, `create table '${tableName}'`);
+        // Two DIFFERENT UNIQUE constraints (different column sets, so the duplicate guard
+        // above passes) may still derive ONE backing structure name — via a constraint name
+        // written with the engine's reserved `_uc_` prefix, or via the `_`-joined auto-name
+        // colliding on ordinary column names (`unique (a_b)` beside `unique (a, b)`). The
+        // second constraint then adopts the first's structure and is enforced by one keyed on
+        // the OTHER constraint's columns, so it silently stops rejecting duplicates. Every
+        // ALTER path refuses this; refused here too, so one declaration gets one answer
+        // wherever it is written. After the duplicate guard (a genuine duplicate must keep its
+        // constraint-worded message) and before `module.create` (a refusal leaves no storage).
+        assertNoDuplicateUniqueConstraintBackingNames(baseTableSchema.uniqueConstraints ?? [], baseTableSchema.columns, `create table '${tableName}'`);
+        // Ask every registered module whether it could durably persist this table's
+        // definition — the same veto CREATE VIEW / CREATE MATERIALIZED VIEW / the RENAME
+        // dependent scan already run (see assertCatalogObjectPersistable). Without it, a
+        // definition the storage backend cannot encode (e.g. an unpaired surrogate in a
+        // column name or a DEFAULT/CHECK string literal) creates successfully and then is
+        // silently dropped by the swallowing SchemaChangeNotifier / persist-queue layers —
+        // worse, if the table is never touched again, nothing ever surfaces the loss.
+        // Before `module.create`, same as the duplicate-UNIQUE guard above, so a refusal
+        // leaves no storage behind. `baseTableSchema` (pre-`module.create`) rather than the
+        // post-create `completeTableSchema` is safe here: the veto reads only the rendered
+        // DDL text, and the one thing `finalizeCreatedTableSchema` still changes —
+        // collation reconciliation — can only substitute an engine-known collation name,
+        // never introduce an unencodable character. Not run on the import/rehydrate path
+        // (`buildTableSchemaFromAST` itself, `importTable`/`importDDL`) — a catalog written
+        // before this guard existed must still open.
+        assertCatalogObjectPersistable(this.db, 'table', baseTableSchema);
         let tableInstance;
         try {
             // `preferBacking` (set only by the maintained-table create path) routes