@quereus/quereus 4.5.0 → 4.7.0

package/dist/src/schema/manager.js

@@ -1,12 +1,12 @@
 import { Schema } from './schema.js';
 import { normalizeCollationName } from '../util/comparison.js';
-import { quereusError, QuereusError } from '../common/errors.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 { buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, validateForeignKeyCollations } from './constraint-builder.js';
 import { normalizeBackingModule } from './view.js';
 import { isMaintainedTable } from './derivation.js';
-import { isHiddenImplicitIndex, isImplicitCoveringIndex, findExposedImplicitConstraintIndex } from './catalog.js';
+import { isHiddenImplicitIndex, isImplicitCoveringIndex, findExposedImplicitConstraintIndex, assertNoDuplicateUniqueConstraints } from './catalog.js';
 import { assertCatalogObjectPersistable } from './catalog-persistability.js';
 import { buildLensBasisFkGate } from './lens-fk-discovery.js';
 import { createLogger } from '../common/logger.js';
@@ -549,17 +549,19 @@ export class SchemaManager {
         return this._findTable(tableName, dbName, schemaPath);
     }
     /**
-     * Finds all schemas that contain a table with the given name.
-     * Useful for generating helpful error messages.
+     * Finds all schemas holding a relation (table OR view) with the given name.
+     * Useful for generating helpful "did you mean" error messages — an
+     * unqualified name resolves through the path across both kinds
+     * ({@link findSchemaItem}), so the hint must span both too.
      *
-     * @param tableName Name of the table to search for
-     * @returns Array of schema names that contain the table
+     * @param itemName Name of the relation to search for
+     * @returns Array of schema names that hold a relation of that name
      */
-    findSchemasContainingTable(tableName) {
-        const lowerTableName = tableName.toLowerCase();
+    findSchemasContainingRelation(itemName) {
+        const lowerItemName = itemName.toLowerCase();
         const schemaNames = [];
         for (const [schemaName, schema] of this.schemas) {
-            if (schema.getTable(lowerTableName)) {
+            if (schema.getTable(lowerItemName) || schema.getView(lowerItemName)) {
                 schemaNames.push(schemaName);
             }
         }
@@ -648,6 +650,32 @@ export class SchemaManager {
             return view;
         return schema.getTable(itemName);
     }
+    /**
+     * Resolves a table-or-view name the way an unqualified name resolves: one
+     * search-path entry at a time, checking that schema's tables AND views
+     * together before moving to the next entry. Tables and views share one
+     * namespace within a schema, so at most one of the two can match per entry.
+     *
+     * @param itemName Name of the table or view
+     * @param dbName Optional explicit schema (a qualified name searches only it)
+     * @param schemaPath Optional ordered search path (default: main, then temp)
+     * @returns The TableSchema or ViewSchema, or undefined if not found
+     */
+    findSchemaItem(itemName, dbName, schemaPath) {
+        if (dbName)
+            return this.getSchemaItem(dbName, itemName);
+        // NOTE: the no-path fallback restates `_findTable`'s default order. The
+        // session `schema_path` option always yields a path in practice, so this
+        // branch is effectively dead — but if the default order ever changes,
+        // change it in both or the two resolvers disagree.
+        const path = schemaPath && schemaPath.length > 0 ? schemaPath : ['main', 'temp'];
+        for (const schemaName of path) {
+            const item = this.getSchemaItem(schemaName, itemName);
+            if (item)
+                return item;
+        }
+        return undefined;
+    }
     /**
      * Gets metadata tags for a table.
      *
@@ -1049,13 +1077,13 @@ export class SchemaManager {
         // Primary path: a materialized IndexSchema — every real index, plus the
         // memory backend's materialized implicit covering index. Tags live on the
         // matched IndexSchema. A *hidden* implicit index is not user-addressable and
-        // is skipped here; it then fails the exposed-constraint fallback below
-        // (its name is materialized, so it is not "exposed and unmaterialized") and
-        // surfaces as NOTFOUND — preserving Phase 22/37 behavior.
-        for (const table of schema.getAllTables()) {
-            const matched = table.indexes?.find(idx => idx.name.toLowerCase() === lower);
-            if (!matched || isHiddenImplicitIndex(table, matched.name))
-                continue;
+        // is skipped by the `tag-addressable` scope; it then fails the
+        // exposed-constraint fallback below (its name is materialized, so it is not
+        // "exposed and unmaterialized") and surfaces as NOTFOUND — preserving
+        // Phase 22/37 behavior.
+        const match = this.findIndexOwner(targetSchemaName, indexName, { scope: 'tag-addressable' });
+        if (match) {
+            const { table, index: matched } = match;
             // Compute before rebuilding the index array so a drop-of-absent NOTFOUND
             // aborts before any swap.
             const nextTags = compute(matched.tags);
@@ -1305,16 +1333,12 @@ export class SchemaManager {
                 objectName: tableSchema.name,
                 oldObject: tableSchema
             });
-            // Emit auto schema event for modules without native event support
-            const moduleReg = tableSchema.vtabModuleName ? this.getModule(tableSchema.vtabModuleName) : undefined;
-            if (this.db._needsSchemaEvents() && !hasNativeEventSupport(moduleReg?.module)) {
-                this.db._getEventEmitter().emitAutoSchemaEvent(tableSchema.vtabModuleName ?? 'memory', {
-                    type: 'drop',
-                    objectType: 'table',
-                    schemaName: tableSchema.schemaName,
-                    objectName: tableSchema.name,
-                });
-            }
+            this.emitAutoSchemaEventIfNeeded(tableSchema.vtabModuleName, {
+                type: 'drop',
+                objectType: 'table',
+                schemaName: tableSchema.schemaName,
+                objectName: tableSchema.name,
+            });
         }
         return removed; // True if removed from schema, false if not found and ifExists was true.
     }
@@ -1948,14 +1972,23 @@ export class SchemaManager {
         const indexName = stmt.index.name;
         const tableSchema = this.getTable(targetSchemaName, tableName);
         if (!tableSchema) {
-            throw new QuereusError(`no such table: ${tableName}`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
+            throw new RelationNotFoundError(`no such table: ${tableName}`, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
         }
         const vtabModule = requireVtabModule(tableSchema);
         if (!vtabModule.createIndex) {
             throw new QuereusError(`Virtual table module '${tableSchema.vtabModuleName}' for table '${tableName}' does not support CREATE INDEX.`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
         }
         const existingIndex = tableSchema.indexes?.find(idx => idx.name.toLowerCase() === indexName.toLowerCase());
-        if (existingIndex) {
+        // The implicit-covering term is what makes this refusal backend-independent.
+        // Memory materializes a constraint's backing structure as a real `IndexSchema`
+        // entry (so `existingIndex` alone catches it); the store keeps it out of the
+        // engine-facing `indexes` list entirely, and without this term `create index
+        // uq_email` would land on the *same* physical key-value store as the
+        // constraint's backing structure (`buildIndexStoreName` is a pure function of
+        // schema + table + index name). `isImplicitCoveringIndex` reads only
+        // `uniqueConstraints`, which both backends carry, so one term covers both.
+        const shadowsConstraintStructure = isImplicitCoveringIndex(tableSchema, indexName);
+        if (existingIndex || shadowsConstraintStructure) {
             if (stmt.ifNotExists) {
                 log(`Skipping CREATE INDEX: Index %s.%s already exists (IF NOT EXISTS).`, targetSchemaName, indexName);
                 return;
@@ -2042,17 +2075,66 @@ export class SchemaManager {
             tags: stmt.tags && Object.keys(stmt.tags).length > 0 ? Object.freeze({ ...stmt.tags }) : undefined,
         };
     }
+    /**
+     * The table in `schemaName` owning the index named `indexName`, paired with the
+     * matched {@link IndexSchema} — or `undefined` when nothing in scope carries the
+     * name. The one by-name index-owner resolver: `DROP INDEX` ({@link dropIndex} and
+     * the strict-DDL-policy gate in `runtime/emit/drop-index.ts`),
+     * `ALTER INDEX … TAGS` ({@link resolveIndexTagSwap}), `CREATE INDEX`'s
+     * 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
+     * {@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
+     * (the DROP INDEX grammar has no slot for one), so without it each receiver would
+     * resolve the owner by its own table-registration order and two devices could drop
+     * different indexes while both believing they converged.
+     *
+     * An out-of-scope match is **skipped and the scan continues** — never stopped at.
+     * That is what lets one table's constraint-backed `uq_email` coexist with another
+     * table's real index of the same name (constraint names are unique per *table*, so
+     * two tables may each declare `constraint uq_email unique (email)`). Both scope
+     * predicates read only `uniqueConstraints`, which every backend carries, so the
+     * filter behaves the same on the store as in memory.
+     *
+     * Case-insensitive on both `indexName` and `options.excludeTable`, like every
+     * other index-name comparison in the engine. An unknown `schemaName` yields
+     * `undefined` rather than throwing — callers that must distinguish a missing
+     * schema from a missing index check for it themselves first.
+     *
+     * @param options.scope Which part of the namespace to consider; defaults to
+     *   `'user-indexes'` (see {@link IndexLookupScope}).
+     * @param options.excludeTable Skip this table entirely — used by the
+     *   name-uniqueness check, which asks about *other* tables only.
+     */
+    findIndexOwner(schemaName, indexName, options) {
+        const schema = this.getSchema(schemaName);
+        if (!schema)
+            return undefined;
+        const outOfScope = options?.scope === 'tag-addressable' ? isHiddenImplicitIndex : isImplicitCoveringIndex;
+        const lowerIndexName = indexName.toLowerCase();
+        const lowerExcluded = options?.excludeTable?.toLowerCase();
+        for (const table of schema.getAllTables()) {
+            if (lowerExcluded !== undefined && table.name.toLowerCase() === lowerExcluded)
+                continue;
+            const index = table.indexes?.find(idx => idx.name.toLowerCase() === lowerIndexName);
+            if (!index || outOfScope(table, index.name))
+                continue;
+            return { table, index };
+        }
+        return undefined;
+    }
     /**
      * The table in `targetSchemaName` — other than `ownerTableName` — that already
      * carries a **user** index named `indexName`, or `undefined` when the name is
      * free. Backs the schema-wide index-name uniqueness rule enforced by
      * {@link createIndex} and warned about by {@link importIndex}.
      *
-     * Implicit covering structures are skipped. The auto-built secondary BTree
-     * backing a `UNIQUE` constraint is named after that constraint (or `_uc_<cols>`),
-     * and constraint names are unique per *table*, so two tables may legitimately
-     * each declare `constraint uq_email unique (email)` and each materialize an
-     * index named `uq_email`. Counting those would reject a valid schema.
+     * Implicit covering structures are skipped (the default
+     * {@link findIndexOwner} scope): counting them would reject a valid schema in
+     * which two tables each declare `constraint uq_email unique (email)`.
      *
      * NOTE: an *exposed* implicit covering index (constraint tagged
      * `quereus.expose_implicit_index`) IS user-addressable by `ALTER INDEX`, so two
@@ -2062,25 +2144,23 @@ export class SchemaManager {
      * per schema.
      */
     findIndexNameOwnerElsewhere(targetSchemaName, ownerTableName, indexName) {
-        const schema = this.getSchema(targetSchemaName);
-        if (!schema)
-            return undefined;
-        const lowerIndexName = indexName.toLowerCase();
-        const lowerOwnerName = ownerTableName.toLowerCase();
-        for (const table of schema.getAllTables()) {
-            if (table.name.toLowerCase() === lowerOwnerName)
-                continue;
-            const matched = table.indexes?.find(idx => idx.name.toLowerCase() === lowerIndexName);
-            if (!matched || isImplicitCoveringIndex(table, matched.name))
-                continue;
-            return table;
-        }
-        return undefined;
+        return this.findIndexOwner(targetSchemaName, indexName, { excludeTable: ownerTableName })?.table;
     }
     /**
      * Drops a secondary index from the table that owns it.
      * Searches all tables in the target schema to find the owning table.
      *
+     * An implicit covering structure — the auto-built secondary BTree backing a
+     * declared `UNIQUE` constraint, named after that constraint (or `_uc_<cols>`) —
+     * is NOT droppable this way, exposed or not: its lifecycle belongs to the
+     * constraint, so removing it means `ALTER TABLE … DROP CONSTRAINT`. The owner
+     * scan therefore *skips and keeps scanning* past such a match rather than
+     * stopping at it, so a real user index of the same name on another table is
+     * still found (constraint names are unique per table, not per schema — see
+     * {@link findIndexNameOwnerElsewhere}). With no owner found this falls through
+     * to the `IF EXISTS` / `no such index` handling below, matching what
+     * `ALTER INDEX … SET TAGS` already does with the same name.
+     *
      * @param schemaName The schema to search in (e.g., "main")
      * @param indexName The name of the index to drop
      * @param ifExists If true, silently return if the index is not found
@@ -2092,29 +2172,33 @@ export class SchemaManager {
                 return;
             throw new QuereusError(`Schema not found: ${schemaName}`, StatusCode.ERROR);
         }
-        // Find which table owns this index
+        // Find which table owns this index.
+        // NOTE: a table may hold a UNIQUE constraint whose name equals an unrelated
+        // user index's name on that same table (`create index foo on t (b); alter
+        // table t add constraint foo unique (a);` — both succeed today). There the
+        // out-of-scope predicate is true and this refuses the drop even though a real
+        // index also carries the name. That state is already broken in worse ways
+        // (memory materializes two entries literally named `foo`) and is tracked as
+        // bug-unique-constraint-name-collides-with-index-name; refusing is the
+        // conservative outcome — do not shape-match around it here.
         const lowerIndexName = indexName.toLowerCase();
-        let ownerTable;
-        for (const table of schema.getAllTables()) {
-            if (table.indexes?.some(idx => idx.name.toLowerCase() === lowerIndexName)) {
-                ownerTable = table;
-                break;
-            }
-        }
-        if (!ownerTable) {
+        const ownerMatch = this.findIndexOwner(schemaName, indexName);
+        if (!ownerMatch) {
             if (ifExists) {
                 log(`Index %s.%s not found, but IF EXISTS specified`, schemaName, indexName);
                 return;
             }
             throw new QuereusError(`no such index: ${indexName}`, StatusCode.ERROR);
         }
+        const ownerTable = ownerMatch.table;
         // Stored display casing of the dropped index — the raw `indexName` arg may
-        // differ in case. Computed *before* the module call so module.dropIndex
-        // receives the stored name (the module-facing stored-name contract; see
-        // canonicalSchemaName), keeping a case-divergent `DROP INDEX iDx` from
-        // missing a module handle/registry keyed by the stored `idx` (e.g. the
-        // store's StoreTable.indexStores cache). Also reused by the events below.
-        const storedIndexName = ownerTable.indexes.find(idx => idx.name.toLowerCase() === lowerIndexName).name;
+        // differ in case. Taken from the matched IndexSchema, i.e. *before* the module
+        // call, so module.dropIndex receives the stored name (the module-facing
+        // stored-name contract; see canonicalSchemaName), keeping a case-divergent
+        // `DROP INDEX iDx` from missing a module handle/registry keyed by the stored
+        // `idx` (e.g. the store's StoreTable.indexStores cache). Also reused by the
+        // events below.
+        const storedIndexName = ownerMatch.index.name;
         // Call module.dropIndex if the module supports it
         const moduleReg = ownerTable.vtabModuleName ? this.getModule(ownerTable.vtabModuleName) : undefined;
         if (moduleReg?.module?.dropIndex) {
@@ -2161,13 +2245,23 @@ export class SchemaManager {
      * if the engine needs schema events — i.e. any `onSchemaChange` or
      * `onTransactionCommit` listener is registered (see `Database._needsSchemaEvents`).
      *
-     * NOTE: the auto event carries no `ddl` — the callers have only the (schema,
-     * object) names here, not the object schema each generator needs. Fine today:
-     * the only consumer that reads `ddl` is sync replication, which runs over the
-     * store module, and that module has native event support so this fallback never
-     * fires for it. If a module without native events ever needs to replicate,
-     * thread the object schema in and call the `schema/ddl-generator.ts` generators
-     * here the way the store and memory modules do at their own emit sites.
+     * NOTE: the auto events raised from THIS class (create/drop table, create/drop
+     * index) carry no `ddl` — the callers have only the (schema, object) names here,
+     * not the object schema each generator needs. Fine today: the only consumer that
+     * reads `ddl` is sync replication, which runs over the store module, and that
+     * module has native event support so this fallback never fires for it. If a
+     * module without native events ever needs to replicate creates/drops, thread the
+     * object schema in and call the `schema/ddl-generator.ts` generators here the way
+     * the store and memory modules do at their own emit sites. The ALTER TABLE arms
+     * are the exception: they pass through this same gate WITH `ddl` (the statement's
+     * plan-build rendering — see `runtime/emit/alter-schema-event.ts`), so an ALTER's
+     * auto event announces the same text an emitter-backed module does.
+     *
+     * Public because the `ALTER TABLE` arms live outside this class
+     * (`runtime/emit/alter-table.ts`, `runtime/emit/add-constraint.ts`) and must reach the
+     * SAME gate. Re-deciding "no listener / module has its own emitter" at a second site is
+     * exactly what produced the data-channel double-emit the store package's
+     * `database-events.spec.ts` guards against — keep one gate.
      */
     emitAutoSchemaEventIfNeeded(moduleName, event) {
         const moduleReg = moduleName ? this.getModule(moduleName) : undefined;
@@ -2253,6 +2347,14 @@ export class SchemaManager {
         const allowNonDet = this.db.options.getBooleanOption('nondeterministic_schema');
         this.validateDefaultDeterminism(baseTableSchema.columns, tableName, hasMutationContext, allowNonDet);
         this.validateCheckConstraintDeterminism(baseTableSchema.checkConstraints, tableName, allowNonDet);
+        // 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
+        // statement leaves no storage behind. Deliberately here rather than in
+        // `buildTableSchemaFromAST`: the import/rehydrate path shares that builder and must
+        // 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}'`);
         let tableInstance;
         try {
             // `preferBacking` (set only by the maintained-table create path) routes
@@ -2601,7 +2703,7 @@ export class SchemaManager {
         // deliberately BEFORE any drop, so a not-yet-resolvable body (the store's
         // MV-over-MV fixpoint: a dependent fails until its upstream's round lands)
         // errors per-entry with any pre-existing backing preserved — data-safe.
-        const shape = deriveBackingShape(this.db, def.bodySql, def.columns);
+        const shape = deriveBackingShape(this.db, def.schemaName, def.bodySql, def.columns);
         // Declared-column arity mismatch: the entry can NEVER materialize, so throw
         // with the backing preserved rather than dropping durable rows for nothing.
         assertDeclaredColumnArity(def, shape);
@@ -2786,11 +2888,41 @@ export class SchemaManager {
         // once per imported index, so a cold open costs O(indexes × tables). Fine at
         // present schema sizes; if opening a large catalog ever shows up as slow, build
         // one name→owner map for the whole import instead of re-scanning per index.
+        //
+        // NOTE: this path deliberately does NOT consult `isImplicitCoveringIndex`, so a
+        // catalog written before the write paths refused a name held by that table's own
+        // UNIQUE constraint still imports its shadowing index — after which the name
+        // resolves to a real index that `dropIndex` then refuses to drop. Only reachable
+        // by opening such a pre-existing database; it warns (below) and proceeds rather
+        // than bricking the open. If that ever needs stronger handling, reject or rename
+        // the shadowing index here rather than loosening the write-path guards.
         const collidingOwner = this.findIndexNameOwnerElsewhere(targetSchemaName, tableSchema.name, indexName);
         if (collidingOwner) {
             warnLog(`Imported index '%s' on table '%s' collides with an existing index of the same name on table '%s' in schema '%s'; `
                 + `index names are expected to be unique per schema — DROP/ALTER INDEX by this name resolves to whichever table registered first`, indexName, tableSchema.name, collidingOwner.name, targetSchemaName);
         }
+        // Same warn-and-proceed treatment for the same-table variant: the name is already
+        // the implicit backing structure of one of this table's own UNIQUE constraints.
+        // Both write paths now refuse this (`createIndex` from the index side,
+        // `assertUniqueConstraintIndexNameFree` from the constraint side), so a catalog
+        // carrying it was written before those guards existed. `importDDL` imports the
+        // CREATE TABLE (constraints included) ahead of every CREATE INDEX, so the
+        // constraint is always the one already present when the collision is seen.
+        //
+        // NOTE: the resulting state is worse than "shadowed and undroppable". Measured on
+        // the memory backend (test/index-ddl-roundtrip.spec.ts), the table ends up with two
+        // index entries under the one name, `index_info()` reports NEITHER, `DROP INDEX`
+        // answers `no such index`, and a predicate over the imported index's column stops
+        // filtering — `where b = 'q'` returns every row. No write path can produce such a
+        // catalog any more, so this is only reachable by opening a database written before
+        // the guards (backwards compatibility is waived project-wide) or by handing
+        // `importCatalog` a collided bundle directly. If either becomes real, reject or
+        // rename the shadowing index HERE rather than loosening the write-path guards.
+        if (isImplicitCoveringIndex(tableSchema, indexName)) {
+            warnLog(`Imported index '%s' on table '%s' collides with the implicit backing index of a UNIQUE constraint of the same name `
+                + `on that table; the index shadows the constraint's structure, DROP INDEX will refuse to drop it, and predicates `
+                + `over its columns stop filtering — rename either the index or the constraint`, indexName, tableSchema.name);
+        }
         // Append the index (and synthesize the derived UNIQUE constraint when
         // unique) without calling module.createIndex() — the storage already exists.
         const updatedTableSchema = appendIndexToTableSchema(tableSchema, indexSchema);