@happyvertical/smrt-core 0.40.69 → 0.41.0

package/dist/schema/generator.js

@@ -1,6 +1,8 @@
+import { classnameToTablename } from "../utils/naming.js";
 import { formatDefaultValue, quoteIdentifier, quoteStringLiteral } from "./sql-identifiers.js";
+import { assertIdentifierFits, enforceIdentifierLimits, shortenIdentifier } from "./index-utils.js";
 import { getDDLStrategy } from "./ddl/index.js";
-import { classnameToTablename } from "../utils/naming.js";
+import { conflictIndexName, resolveConflictColumns, resolveTenantColumn, servesSlugLookup } from "./conflict-target.js";
 import { createHash } from "node:crypto";
 //#region src/schema/generator.ts
 /**
@@ -17,14 +19,21 @@ var SchemaGenerator = class {
 		const indexes = this.generateIndexes(objectDef, columns);
 		const triggers = this.generateTriggers(objectDef, tableName);
 		const foreignKeys = this.extractForeignKeys(columns);
+		const dependencies = this.extractDependencies(objectDef, foreignKeys);
+		const version = this.generateVersion(objectDef);
+		this.ensureDefaultListOrderingIndex(indexes, columns, tableName);
+		this.ensurePolymorphicAssociationIndex(indexes, columns, tableName);
+		this.ensureReferenceColumnIndexes(indexes, columns, tableName);
+		enforceIdentifierLimits(tableName, indexes);
+		for (const trigger of triggers) trigger.name = shortenIdentifier(trigger.name);
 		return {
 			tableName,
 			columns,
 			indexes,
 			triggers,
 			foreignKeys,
-			dependencies: this.extractDependencies(objectDef, foreignKeys),
-			version: this.generateVersion(objectDef),
+			dependencies,
+			version,
 			packageName: this.extractPackageName(objectDef.filePath),
 			baseClass: objectDef.extends
 		};
@@ -138,6 +147,412 @@ var SchemaGenerator = class {
 		return columns;
 	}
 	/**
+	* Whether an existing index already leads with `leadingColumns`, in order.
+	*
+	* Only an UNQUALIFIED index (no partial `WHERE`, no JSON-path expression)
+	* counts. A partial index such as `... WHERE _meta_type = 'Article'` cannot
+	* serve a base-class polymorphic query, which carries no subtype predicate,
+	* so it must not suppress the standalone index (#2359, review of #2384).
+	*
+	* A B-tree serves any prefix of its column list, so an index over
+	* `(tenant_id, created_at, status)` covers both `(tenant_id)` equality
+	* lookups and `(tenant_id, created_at)` ordering — hence the prefix test
+	* rather than an exact match (#2363).
+	*/
+	hasUnqualifiedLeadingColumns(indexes, leadingColumns) {
+		return indexes.some((index) => !index.where && !index.jsonPath && (index.columns?.length ?? 0) >= leadingColumns.length && leadingColumns.every((column, i) => index.columns[i] === column));
+	}
+	/**
+	* Whether an existing index already serves equality lookups on `column`.
+	*
+	* Single-column shorthand for {@link hasUnqualifiedLeadingColumns}.
+	*/
+	hasUnqualifiedLeadingIndex(indexes, column) {
+		return this.hasUnqualifiedLeadingColumns(indexes, [column]);
+	}
+	/**
+	* The column list of the default list-ordering index for a table.
+	*
+	* Every generated list surface — REST, MCP, and the SvelteKit list route —
+	* pages with `ORDER BY created_at DESC, <pk> ASC` (`DEFAULT_LIST_ORDER_BY`,
+	* #2367). On a tenant-scoped table that page is always preceded by a
+	* `tenant_id = ?` equality filter from the tenancy interceptor, so the
+	* serving index leads with the tenant column and orders inside it.
+	*
+	* `created_at` is generator-owned on every path — a declared `createdAt`
+	* field is rewritten to the same `TIMESTAMP NOT NULL DEFAULT
+	* current_timestamp` column — so it is never a primary key and never
+	* inline-UNIQUE. That is why only `indexes` needs checking for existing
+	* coverage: no constraint-backed index can already order this column.
+	*
+	* Returns `null` when the table has no `created_at` column (no path emits
+	* such a table today, but the helper stays total).
+	*/
+	getDefaultListOrderingColumns(columns) {
+		if (!columns.created_at) return null;
+		const tenantColumn = Object.entries(columns).find(([, columnDef]) => columnDef?.referenceKind === "tenantId")?.[0];
+		return tenantColumn ? [tenantColumn, "created_at"] : ["created_at"];
+	}
+	/**
+	* Ensure the table can serve its own default list page from an index.
+	*
+	* Generated REST/MCP/SvelteKit list routes all page with
+	* `ORDER BY created_at DESC, <pk> ASC LIMIT n` and no `created_at` index
+	* existed on any schema path (the dead AST path indexed `updated_at`
+	* instead), so every default list page was a sequential scan plus a top-N
+	* sort of the whole table — 21 ms against 0.1 ms with the right composite on
+	* the workload the assessment measured (#2363, finding A2).
+	*
+	* Emitted shape:
+	*
+	* - tenant-scoped table → `(<tenant column>, created_at)`. The tenancy
+	*   interceptor adds `tenant_id = ?` to every list, so the tenant column
+	*   leads and `created_at` orders within it.
+	* - otherwise → `(created_at)`.
+	*
+	* No `DESC` declaration: PostgreSQL scans a B-tree backwards just as
+	* cheaply, and `IndexDefinition` carries no per-column direction. The
+	* trailing primary-key tiebreak is left out deliberately — its direction is
+	* opposite to `created_at`'s, so no single-direction index can satisfy the
+	* whole key anyway; the leading columns turn a full sort into an index scan
+	* with an incremental sort over rows that share a timestamp.
+	*
+	* Call this AFTER {@link appendDeclaredIndexes} and BEFORE
+	* {@link ensureReferenceColumnIndexes}: a declared composite that already
+	* leads with the same columns suppresses this one, and this composite in
+	* turn suppresses the standalone tenant index that would otherwise be a
+	* redundant prefix of it.
+	*/
+	ensureDefaultListOrderingIndex(indexes, columns, tableName) {
+		const orderingColumns = this.getDefaultListOrderingColumns(columns);
+		if (!orderingColumns) return;
+		if (this.hasUnqualifiedLeadingColumns(indexes, orderingColumns)) return;
+		const name = `${tableName}_${orderingColumns.join("_")}_idx`;
+		if (indexes.some((index) => index.name === name)) return;
+		indexes.push({
+			name,
+			columns: orderingColumns
+		});
+	}
+	/**
+	* The `(meta_type, meta_id)` owner-lookup columns for a polymorphic
+	* association table, or `null` when the table isn't one.
+	*
+	* `SmrtPolymorphicAssociation` contributes `metaType`/`metaId`/`role` (and
+	* `sortOrder`) to any concrete subclass's manifest — the scanner's
+	* `FRAMEWORK_ABSTRACT_BASE_NAMES` wiring merges the abstract base's fields
+	* directly into the subclass, because the base carries no `@smrt()`
+	* decorator of its own to declare an index on. Detected structurally, by
+	* the same three-column test `cascade.ts`'s `isPolymorphicAssociationClass`
+	* uses on registry field maps: requiring all three keeps an unrelated class
+	* that merely happens to carry a `metaType` column from being treated as an
+	* association table.
+	*/
+	getPolymorphicAssociationOwnerColumns(columns) {
+		if (!Object.hasOwn(columns, "meta_type") || !Object.hasOwn(columns, "meta_id") || !Object.hasOwn(columns, "role")) return null;
+		return ["meta_type", "meta_id"];
+	}
+	/**
+	* Ensure a polymorphic association table indexes its owner lookup
+	* `(meta_type, meta_id)` (#2364, epic #2382 finding A3).
+	*
+	* A concrete association's `conflictColumns` lead with its own FK (e.g.
+	* `AssetAssociation`'s `asset_id, meta_type, meta_id, role`), so
+	* `meta_type`/`meta_id` sit in the *middle* of that unique index — a
+	* lookup like `AssetAssociationCollection.byLeft(metaType, metaId)`
+	* ("what points at this target") filters columns 2-3 of a 4-column index
+	* and cannot use it as a leading prefix. `metaId` is deliberately a bare
+	* string, never a typed `@foreignKey`/`@crossPackageRef` (there is no
+	* single target table), so {@link ensureReferenceColumnIndexes} never
+	* covers it either.
+	*
+	* Call this alongside {@link ensureDefaultListOrderingIndex}, before
+	* {@link ensureReferenceColumnIndexes}.
+	*
+	* Blast radius: this applies retroactively to every
+	* `SmrtPolymorphicAssociation` subclass across every package on the next
+	* `db:migrate`, not only the ones a given change touches — roll the wave
+	* out with `smrt db:migrate --postgres-safe` (#2362), same as any other
+	* bulk index addition.
+	*/
+	ensurePolymorphicAssociationIndex(indexes, columns, tableName) {
+		const ownerColumns = this.getPolymorphicAssociationOwnerColumns(columns);
+		if (!ownerColumns) return;
+		if (this.hasUnqualifiedLeadingColumns(indexes, ownerColumns)) return;
+		const name = `${tableName}_${ownerColumns.join("_")}_idx`;
+		if (indexes.some((index) => index.name === name)) return;
+		indexes.push({
+			name,
+			columns: ownerColumns
+		});
+	}
+	/**
+	* Append `@smrt({ indexes: [...] })` declarations to a generated index set
+	* (#2357).
+	*
+	* Shared by every schema path — build-time AST, runtime registry CTI/STI, and
+	* manifest CTI/STI — so one declaration behaves identically however the schema
+	* was derived. Call it *first*, ahead of
+	* {@link ensureDefaultListOrderingIndex} (#2363) and
+	* {@link ensureReferenceColumnIndexes}: a declared composite leading with a
+	* reference column (e.g. `tenant_id`), or with the default ordering columns,
+	* is exactly what those helpers' leads-with check is meant to defer to, and
+	* appending afterwards would leave the table with a redundant standalone
+	* index (#2384, #2359).
+	*
+	* Nothing is dropped quietly. A column that resolves to no column on the
+	* table, a malformed entry, and a name collision with a different index are
+	* all hard errors — a silently missing index is a production performance bug
+	* that surfaces only under load.
+	*
+	* @param indexes - Generated index set, appended in place
+	* @param declared - The object's `indexes` config, from any config source
+	* @param columns - Emitted columns, keyed by column name
+	* @param tableName - Table the indexes belong to (for error messages)
+	*/
+	appendDeclaredIndexes(indexes, declared, columns, tableName) {
+		if (declared === void 0 || declared === null) return;
+		if (!Array.isArray(declared)) throw new Error(`@smrt({ indexes }) on "${tableName}" must be an array of index declarations.`);
+		for (const entry of declared) {
+			const spec = this.validateDeclaredIndex(entry, tableName);
+			const mappedColumns = spec.columns.map((column) => this.resolveDeclaredIndexColumn(column, columns));
+			const unknownColumns = mappedColumns.filter((column) => !Object.hasOwn(columns, column));
+			if (unknownColumns.length > 0) throw new Error(`Declared index "${spec.name}" on "${tableName}" references unknown column(s): ${unknownColumns.join(", ")}. Declared index columns must name a field or column on the object.`);
+			const index = {
+				name: spec.name,
+				columns: mappedColumns,
+				...spec.unique === true ? { unique: true } : {},
+				...spec.where !== void 0 ? { where: spec.where } : {}
+			};
+			const existing = indexes.find((other) => other.name === index.name);
+			if (existing) {
+				if (this.sameIndexTarget(existing, index)) continue;
+				throw new Error(`Declared index "${index.name}" on "${tableName}" collides with a different index of the same name. Rename the declared index.`);
+			}
+			indexes.push(index);
+		}
+	}
+	/** Narrow one raw `indexes[]` entry, rejecting anything unusable. */
+	validateDeclaredIndex(entry, tableName) {
+		const spec = entry;
+		const describe = () => {
+			try {
+				return JSON.stringify(entry) ?? String(entry);
+			} catch {
+				return String(entry);
+			}
+		};
+		if (typeof spec !== "object" || spec === null || Array.isArray(spec)) throw new Error(`Declared index on "${tableName}" must be an object: got ${describe()}.`);
+		if (typeof spec.name !== "string" || spec.name.length === 0) throw new Error(`Declared index on "${tableName}" needs a non-empty "name": got ${describe()}.`);
+		assertIdentifierFits(spec.name, "Declared index", `table "${tableName}"`);
+		if (!Array.isArray(spec.columns) || spec.columns.length === 0 || !spec.columns.every((column) => typeof column === "string" && column.length > 0)) throw new Error(`Declared index "${spec.name}" on "${tableName}" needs a non-empty "columns" array of field or column names.`);
+		if (spec.unique !== void 0 && typeof spec.unique !== "boolean") throw new Error(`Declared index "${spec.name}" on "${tableName}" has a non-boolean "unique": got ${describe()}.`);
+		if (spec.where !== void 0 && (typeof spec.where !== "string" || spec.where.trim().length === 0)) throw new Error(`Declared index "${spec.name}" on "${tableName}" has an empty or non-string "where" predicate.`);
+		return spec;
+	}
+	/**
+	* Resolve a declared index column to an emitted column name.
+	*
+	* Declarations name SMRT fields, but only the runtime/manifest paths
+	* snake_case them into columns — the build-time AST path keys columns by the
+	* field name itself. Prefer an exact column hit, then the snake_case form, and
+	* otherwise return the input unchanged so the caller reports it as unknown.
+	*/
+	resolveDeclaredIndexColumn(name, columns) {
+		if (Object.hasOwn(columns, name)) return name;
+		const snakeCased = this.toSnakeCase(name);
+		return Object.hasOwn(columns, snakeCased) ? snakeCased : name;
+	}
+	/** Whether two index definitions describe the same database object. */
+	sameIndexTarget(a, b) {
+		return a.columns.length === b.columns.length && a.columns.every((column, i) => column === b.columns[i]) && (a.unique ?? false) === (b.unique ?? false) && (a.where ?? null) === (b.where ?? null);
+	}
+	/**
+	* Ensure every reference column — `@foreignKey`, `@crossPackageRef`, and the
+	* tenancy-injected `tenant_id` — has an index leading with it.
+	*
+	* These are the columns every relationship load, `include:` batch, reverse
+	* ownership lookup and tenant-scoped read filters on. Before #2359 only the
+	* registry (test) paths indexed foreign keys, the manifest (production)
+	* paths indexed none of them, and `tenant_id` was indexed nowhere (#2356):
+	* 196/231 `@foreignKey` and 91/92 `@crossPackageRef` columns shipped with no
+	* serving index. Every schema path now calls this helper so the four paths
+	* stay in step (see `schema-path-parity.test.ts`).
+	*
+	* "Leading with it" rather than "always add": a table that already has an
+	* unqualified index starting on the column (commonly the `conflictColumns`
+	* unique index, or an `indexed: true` opt-in) is already served, and a
+	* standalone duplicate would only cost writes. A *partial* index does not
+	* count — see {@link hasUnqualifiedLeadingIndex}.
+	*
+	* Reference columns are therefore always indexed; `indexed: true` on one of
+	* them is redundant and harmless.
+	*
+	* Call this LAST in every path, after every other index (conflict, opt-in,
+	* unique, the declared composites, the default list-ordering composite, and
+	* any future addition) has been appended, so the leads-with suppression sees
+	* the full set. In particular {@link ensureDefaultListOrderingIndex} runs
+	* first on a tenant-scoped table: its `(tenant_id, created_at)` composite
+	* serves the tenant equality filter too, so no standalone tenant index is
+	* added (#2363).
+	*/
+	ensureReferenceColumnIndexes(indexes, columns, tableName) {
+		for (const [columnName, columnDef] of Object.entries(columns)) {
+			const kind = columnDef?.referenceKind;
+			if (kind !== "foreignKey" && kind !== "crossPackageRef" && kind !== "tenantId") continue;
+			if (columnDef?.primaryKey || columnDef?.unique) continue;
+			if (this.hasUnqualifiedLeadingIndex(indexes, columnName)) continue;
+			const name = `${tableName}_${columnName}_idx`;
+			if (indexes.some((index) => index.name === name)) continue;
+			indexes.push({
+				name,
+				columns: [columnName]
+			});
+		}
+	}
+	/**
+	* Whether `conflictColumns` names exactly the primary key column(s).
+	*
+	* `ON CONFLICT (id)` binds to the primary-key constraint on every engine, so
+	* a separate unique index over the same column set is a second B-tree over
+	* the same random UUIDs with nothing to add (#2359, finding A5).
+	*/
+	conflictColumnsArePrimaryKey(conflictColumns, columns) {
+		const primaryKeyColumns = Object.entries(columns).filter(([, columnDef]) => columnDef?.primaryKey === true).map(([name]) => name);
+		return primaryKeyColumns.length > 0 && primaryKeyColumns.length === conflictColumns.length && primaryKeyColumns.every((column) => conflictColumns.includes(column));
+	}
+	/**
+	* The table's tenant column as the generated columns describe it: the
+	* column carrying `referenceKind: 'tenantId'` (set from the field's
+	* `__tenancy.isTenantIdField` marker on every path).
+	*/
+	findTenantColumn(columns) {
+		for (const [columnName, columnDef] of Object.entries(columns)) if (columnDef?.referenceKind === "tenantId") return columnName;
+	}
+	/**
+	* Resolve the conflict target the unique conflict index must cover
+	* (#2360). `config.conflictColumns` wins when the caller resolved it —
+	* registry callers pass `ObjectRegistry.getConflictColumns()`, the manifest
+	* pipeline passes the normalized `decoratorConfig` — otherwise the strategy
+	* default, led by the tenant column when `config.tenantScoped` names a
+	* tenant field that exists as a column. Both roads apply the same rule as
+	* `ObjectRegistry.getConflictColumns()`, so schema and upsert agree by
+	* construction (`schema-path-parity.test.ts`).
+	*/
+	resolveConflictTarget(strategy, columns, config) {
+		const tenantColumn = this.findTenantColumn(columns);
+		if (config?.conflictColumns && config.conflictColumns.length > 0) return {
+			conflictColumns: [...config.conflictColumns],
+			tenantColumn
+		};
+		const tenantScoped = config?.tenantScoped;
+		return {
+			conflictColumns: resolveConflictColumns({
+				strategy,
+				tenantColumn: tenantScoped ? resolveTenantColumn(typeof tenantScoped === "object" ? tenantScoped.field ?? "tenantId" : "tenantId", (fieldName) => Boolean(columns[this.toSnakeCase(fieldName)]), (fieldName) => this.toSnakeCase(fieldName)) : void 0
+			}),
+			tenantColumn
+		};
+	}
+	/**
+	* Keep `(slug, context)` lookups served when `conflictColumns` are custom.
+	*
+	* The default conflict index is `(slug, context)`, and `loadFromSlug()`,
+	* `getId()` and `getSavedId()` all filter on `slug`/`context` regardless of
+	* the configured conflict key. A class that declares custom conflict
+	* columns replaces that unique index and, before #2359, left those lookups
+	* with no index at all — 120 tables (finding A7).
+	*
+	* Emitting a plain `(slug, context)` index is the safer of the two fixes:
+	* routing the lookups through the conflict key would change which row a
+	* slug resolves to on every such class, whereas an extra non-unique index
+	* is purely additive. It is skipped when an unqualified index already
+	* serves the lookup — one leading with `slug` (e.g. custom conflict columns
+	* that still start with it), or the tenant-led default key
+	* `(tenant_id, slug, context)` of a tenant-scoped table (#2360): every slug
+	* lookup on such a table carries the tenant predicate (#2365) and is served
+	* by that prefix, so a second index would only cost writes.
+	*/
+	ensureSlugLookupIndex(indexes, columns, tableName) {
+		if (!columns.slug || !columns.context) return;
+		const tenantColumn = this.findTenantColumn(columns);
+		if (indexes.some((index) => !index.where && !index.jsonPath && servesSlugLookup(index.columns ?? [], tenantColumn))) return;
+		const name = `${tableName}_slug_context_idx`;
+		if (indexes.some((index) => index.name === name)) return;
+		indexes.push({
+			name,
+			columns: ["slug", "context"]
+		});
+	}
+	/**
+	* Emit the unique conflict index of an STI table from the resolved
+	* conflict target (#2360): the STI default `(slug, context, _meta_type)`,
+	* a custom `@smrt({ conflictColumns })` declared on the STI root, or the
+	* default led by the tenant column when the root is tenant-scoped. Shared
+	* by the registry and manifest STI paths so they cannot drift.
+	*
+	* No index is emitted when the target is the primary key itself
+	* (`ON CONFLICT (id)` binds to the PK constraint), matching the CTI paths.
+	*/
+	emitStiConflictIndex(indexes, columns, tableName, config) {
+		const { conflictColumns, tenantColumn } = this.resolveConflictTarget("sti", columns, config);
+		if (this.conflictColumnsArePrimaryKey(conflictColumns, columns)) return;
+		indexes.push({
+			name: conflictIndexName(tableName, conflictColumns, tenantColumn),
+			columns: conflictColumns,
+			unique: true
+		});
+	}
+	/**
+	* Emit unique indexes for `@field({ unique: true })` columns on an STI table.
+	*
+	* STI columns are the union of every class in the hierarchy, all nullable,
+	* so a column-level `UNIQUE` (what CTI renders inline) is not enough on its
+	* own: the migration differ cannot add a column constraint to an existing
+	* table, but it can add an index. Two shapes (#2359, finding A4):
+	*
+	* - declared on the STI **base** (and therefore inherited by every class in
+	*   the table): one full unique index, table-wide like CTI;
+	* - declared only on a **descendant**: one partial unique index per class
+	*   that carries the flag (the declaring class and, through inherited field
+	*   metadata, its own descendants), `WHERE _meta_type = '<qualified>'`, so
+	*   siblings that merely share the column name are not constrained.
+	*   Uniqueness is then enforced per concrete class, not across the subtree
+	*   — a documented limitation of the discriminator-partial shape. Engines
+	*   without partial indexes (DuckDB, JSON) skip this shape entirely rather
+	*   than widen it to a table-wide UNIQUE (see DuckDBStrategy.generateIndexes
+	*   and SchemaComparer.compareIndexes).
+	*
+	* @param declarers - column name → classes whose field metadata carries
+	*   `unique: true` for that column, in hierarchy order (base first).
+	*/
+	emitStiUniqueIndexes(indexes, declarers, baseClassName, tableName) {
+		for (const [columnName, classNames] of declarers.entries()) {
+			if (classNames.has(baseClassName)) {
+				indexes.push({
+					name: `${tableName}_${columnName}_unique_idx`,
+					columns: [columnName],
+					unique: true
+				});
+				continue;
+			}
+			for (const className of classNames) {
+				const simpleName = className.includes(":") ? className.slice(className.lastIndexOf(":") + 1) : className;
+				let name = `${tableName}_${columnName}_${this.toSnakeCase(simpleName)}_unique_idx`;
+				if (indexes.some((index) => index.name === name)) {
+					const digest = createHash("sha256").update(className).digest("hex").slice(0, 6);
+					name = `${tableName}_${columnName}_${this.toSnakeCase(simpleName)}_${digest}_unique_idx`;
+				}
+				indexes.push({
+					name,
+					columns: [columnName],
+					unique: true,
+					where: `_meta_type = ${quoteStringLiteral(className)}`
+				});
+			}
+		}
+	}
+	/**
 	* Generate index definitions
 	*/
 	generateIndexes(objectDef, columns) {
@@ -159,6 +574,7 @@ var SchemaGenerator = class {
 			unique: true,
 			description: `Unique index for ${columnName}`
 		});
+		this.appendDeclaredIndexes(indexes, objectDef.decoratorConfig?.indexes, columns, tableName);
 		return indexes;
 	}
 	/**
@@ -331,37 +747,25 @@ var SchemaGenerator = class {
 		this.reconcileRegistryForeignKeyColumnTypes(columns, fields, config?.registry);
 		const indexes = [];
 		if (!hasCustomPK) {
-			indexes.push({
-				name: `${tableName}_id_idx`,
-				columns: ["id"],
-				description: "Primary key index"
-			});
-			const conflictColumns = config?.conflictColumns || ["slug", "context"];
-			const conflictIndexName = conflictColumns.length > 2 ? `${tableName}_${conflictColumns.slice(0, 2).join("_")}_idx` : `${tableName}_${conflictColumns.join("_")}_idx`;
-			indexes.push({
-				name: conflictIndexName,
+			const { conflictColumns, tenantColumn } = this.resolveConflictTarget("cti", columns, config);
+			if (!this.conflictColumnsArePrimaryKey(conflictColumns, columns)) indexes.push({
+				name: conflictIndexName(tableName, conflictColumns, tenantColumn),
 				columns: conflictColumns,
 				unique: true,
 				description: `Unique conflict index for ${className}`
 			});
-		} else for (const [colName, colDef] of Object.entries(columns)) if (colDef.primaryKey) {
-			indexes.push({
-				name: `${tableName}_${colName}_idx`,
-				columns: [colName],
-				description: `Primary key index`
-			});
-			break;
 		}
-		for (const [colName, colDef] of Object.entries(columns)) if (colDef.foreignKey) indexes.push({
-			name: `idx_${tableName}_${colName}`,
-			columns: [colName],
-			description: `Foreign key index for ${colName}`
-		});
+		this.ensureSlugLookupIndex(indexes, columns, tableName);
 		for (const colName of indexedColumns) indexes.push({
 			name: `${tableName}_${colName}_idx`,
 			columns: [colName],
 			description: `Index for ${colName}`
 		});
+		this.appendDeclaredIndexes(indexes, config?.indexes, columns, tableName);
+		this.ensureDefaultListOrderingIndex(indexes, columns, tableName);
+		this.ensurePolymorphicAssociationIndex(indexes, columns, tableName);
+		this.ensureReferenceColumnIndexes(indexes, columns, tableName);
+		enforceIdentifierLimits(tableName, indexes);
 		return {
 			tableName,
 			columns,
@@ -381,7 +785,14 @@ var SchemaGenerator = class {
 	* - _meta_type: Discriminator column to identify class type
 	* - _meta_data: JSON column for flexible field storage
 	* - Union of all FK columns from descendants (all nullable)
-	* - Partial indexes for FK columns (filtered by _meta_type)
+	* - One plain index per reference column (FK / cross-package ref /
+	*   tenant_id). Plain rather than partial-by-class: base-class polymorphic
+	*   queries carry no `_meta_type` predicate, so a partial index could not
+	*   serve them, while a plain index serves both those and the child
+	*   collections' `_meta_type = X AND fk = ?` filters — one index per column
+	*   instead of one per (column, class) (#2359).
+	* - Unique indexes for `@field({ unique: true })` columns — see
+	*   {@link emitStiUniqueIndexes}.
 	*
 	* @param baseClassName - Base class name for the STI hierarchy
 	* @param tableName - Shared table name (from base class)
@@ -441,12 +852,11 @@ var SchemaGenerator = class {
 		let hasUpdatedAt = false;
 		const descendants = ObjectRegistry.getDescendants(baseClassName);
 		const allClassNames = [baseClassName, ...descendants];
-		const fkColumnsByClass = /* @__PURE__ */ new Map();
 		const indexedMetaFields = /* @__PURE__ */ new Set();
 		const indexedStiColumns = /* @__PURE__ */ new Set();
+		const uniqueColumnDeclarers = /* @__PURE__ */ new Map();
 		for (const className of allClassNames) {
 			const classFields = await ObjectRegistry.getAllFields(className);
-			fkColumnsByClass.set(className, /* @__PURE__ */ new Set());
 			for (const [fieldName, field] of classFields.entries()) {
 				if (field.transient || field._meta?.transient) continue;
 				if (field.type === "meta" && (field.indexed === true || field._meta?.indexed === true)) indexedMetaFields.add(fieldName);
@@ -476,6 +886,14 @@ var SchemaGenerator = class {
 				if (field.type === "oneToMany" || field.type === "manyToMany") continue;
 				if (field.type === "meta") continue;
 				const columnName = this.toSnakeCase(fieldName);
+				if (field._meta?.unique === true) {
+					let declarers = uniqueColumnDeclarers.get(columnName);
+					if (!declarers) {
+						declarers = /* @__PURE__ */ new Set();
+						uniqueColumnDeclarers.set(columnName, declarers);
+					}
+					declarers.add(className);
+				}
 				if (columns[columnName]) continue;
 				const columnDef = {
 					type: this.getRelationshipColumnType(field),
@@ -489,15 +907,12 @@ var SchemaGenerator = class {
 				if (field.type === "foreignKey") {
 					const relatedName = field.related;
 					const onDeleteAction = field._meta?.onDelete;
-					if (relatedName) {
-						columnDef.foreignKey = {
-							table: this.classNameToTableName(relatedName),
-							column: "id",
-							onDelete: onDeleteAction || "CASCADE",
-							onUpdate: "CASCADE"
-						};
-						fkColumnsByClass.get(className)?.add(columnName);
-					}
+					if (relatedName) columnDef.foreignKey = {
+						table: this.classNameToTableName(relatedName),
+						column: "id",
+						onDelete: onDeleteAction || "CASCADE",
+						onUpdate: "CASCADE"
+					};
 				}
 				if ((field._meta?.indexed === true || field.indexed === true) && !columnDef.foreignKey) indexedStiColumns.add(columnName);
 				columns[columnName] = columnDef;
@@ -520,32 +935,14 @@ var SchemaGenerator = class {
 			this.reconcileRegistryForeignKeyColumnTypes(columns, classFields, ObjectRegistry);
 		}
 		const indexes = [];
-		indexes.push({
-			name: `${tableName}_id_idx`,
-			columns: ["id"],
-			description: "Primary key index"
-		});
-		indexes.push({
-			name: `${tableName}_slug_context_meta_type_idx`,
-			columns: [
-				"slug",
-				"context",
-				"_meta_type"
-			],
-			unique: true,
-			description: "Unique index for slug, context, and type"
-		});
+		this.emitStiConflictIndex(indexes, columns, tableName, config);
 		indexes.push({
 			name: `${tableName}_meta_type_idx`,
 			columns: ["_meta_type"],
 			description: "Index for type discriminator queries"
 		});
-		for (const [className, fkColumns] of fkColumnsByClass.entries()) for (const fkColumn of fkColumns) indexes.push({
-			name: `idx_${tableName}_${fkColumn}_${className.toLowerCase()}`,
-			columns: [fkColumn],
-			where: `_meta_type = ${quoteStringLiteral(className)}`,
-			description: `Partial index for ${fkColumn} in ${className} rows`
-		});
+		this.emitStiUniqueIndexes(indexes, uniqueColumnDeclarers, baseClassName, tableName);
+		this.ensureSlugLookupIndex(indexes, columns, tableName);
 		for (const fieldName of indexedMetaFields) indexes.push({
 			name: `${tableName}_meta_${this.toSnakeCase(fieldName)}_idx`,
 			columns: [],
@@ -560,6 +957,11 @@ var SchemaGenerator = class {
 			columns: [colName],
 			description: `Index for ${colName}`
 		});
+		this.appendDeclaredIndexes(indexes, config?.indexes, columns, tableName);
+		this.ensureDefaultListOrderingIndex(indexes, columns, tableName);
+		this.ensurePolymorphicAssociationIndex(indexes, columns, tableName);
+		this.ensureReferenceColumnIndexes(indexes, columns, tableName);
+		enforceIdentifierLimits(tableName, indexes);
 		return {
 			tableName,
 			columns,
@@ -624,15 +1026,15 @@ var SchemaGenerator = class {
 			notNull: true,
 			default: "current_timestamp"
 		};
-		const descendants = this.findDescendantsInManifest(baseClassName, manifest);
-		const allClassNames = [baseClassName, ...descendants];
-		const fkColumnsByClass = /* @__PURE__ */ new Map();
+		const baseKey = this.resolveManifestClassKey(baseClassName, manifest);
+		const descendants = this.findDescendantsInManifest(baseKey, manifest);
+		const allClassNames = [baseKey, ...descendants];
 		const indexedMetaFields = /* @__PURE__ */ new Set();
 		const indexedStiColumns = /* @__PURE__ */ new Set();
+		const uniqueColumnDeclarers = /* @__PURE__ */ new Map();
 		for (const className of allClassNames) {
 			const objDef = manifest.objects[className];
 			if (!objDef) continue;
-			fkColumnsByClass.set(className, /* @__PURE__ */ new Set());
 			for (const [fieldName, field] of Object.entries(objDef.fields)) {
 				if (field.transient || field._meta?.transient) continue;
 				const indexedField = field;
@@ -641,6 +1043,14 @@ var SchemaGenerator = class {
 				if (field.type === "oneToMany" || field.type === "manyToMany") continue;
 				if (field.type === "meta") continue;
 				const columnName = this.toSnakeCase(fieldName);
+				if (field._meta?.unique === true) {
+					let declarers = uniqueColumnDeclarers.get(columnName);
+					if (!declarers) {
+						declarers = /* @__PURE__ */ new Set();
+						uniqueColumnDeclarers.set(columnName, declarers);
+					}
+					declarers.add(className);
+				}
 				if (columns[columnName]) continue;
 				const columnDef = {
 					type: this.getRelationshipColumnType(field),
@@ -648,29 +1058,18 @@ var SchemaGenerator = class {
 					notNull: false
 				};
 				if (field.default !== void 0 && this.shouldEmitDefault(field, field.default)) columnDef.default = field.default;
-				if (field.type === "foreignKey") fkColumnsByClass.get(className)?.add(columnName);
 				if ((indexedField.indexed === true || field._meta?.indexed === true) && field.type !== "foreignKey") indexedStiColumns.add(columnName);
 				columns[columnName] = columnDef;
 			}
 		}
 		const indexes = [];
-		indexes.push({
-			name: `${tableName}_id_idx`,
-			columns: ["id"]
-		});
-		indexes.push({
-			name: `${tableName}_slug_context_meta_type_idx`,
-			columns: [
-				"slug",
-				"context",
-				"_meta_type"
-			],
-			unique: true
-		});
+		this.emitStiConflictIndex(indexes, columns, tableName, config);
 		indexes.push({
 			name: `${tableName}_meta_type_idx`,
 			columns: ["_meta_type"]
 		});
+		this.emitStiUniqueIndexes(indexes, uniqueColumnDeclarers, baseKey, tableName);
+		this.ensureSlugLookupIndex(indexes, columns, tableName);
 		for (const fieldName of indexedMetaFields) indexes.push({
 			name: `${tableName}_meta_${this.toSnakeCase(fieldName)}_idx`,
 			columns: [],
@@ -683,6 +1082,11 @@ var SchemaGenerator = class {
 			name: `${tableName}_${colName}_idx`,
 			columns: [colName]
 		});
+		this.appendDeclaredIndexes(indexes, config?.indexes, columns, tableName);
+		this.ensureDefaultListOrderingIndex(indexes, columns, tableName);
+		this.ensurePolymorphicAssociationIndex(indexes, columns, tableName);
+		this.ensureReferenceColumnIndexes(indexes, columns, tableName);
+		enforceIdentifierLimits(tableName, indexes);
 		const schemaDefinition = {
 			tableName,
 			columns: this.convertManifestColumnsToSchemaColumns(columns),
@@ -764,21 +1168,22 @@ var SchemaGenerator = class {
 			columns[columnName] = columnDef;
 		}
 		const indexes = [];
-		indexes.push({
-			name: `${tableName}_id_idx`,
-			columns: ["id"]
-		});
-		const conflictColumns = config?.conflictColumns || ["slug", "context"];
-		const indexName = conflictColumns.length > 2 ? `${tableName}_${conflictColumns.slice(0, 2).join("_")}_idx` : `${tableName}_${conflictColumns.join("_")}_idx`;
-		indexes.push({
-			name: indexName,
+		const { conflictColumns, tenantColumn } = this.resolveConflictTarget("cti", columns, config);
+		if (!this.conflictColumnsArePrimaryKey(conflictColumns, columns)) indexes.push({
+			name: conflictIndexName(tableName, conflictColumns, tenantColumn),
 			columns: conflictColumns,
 			unique: true
 		});
+		this.ensureSlugLookupIndex(indexes, columns, tableName);
 		for (const colName of indexedColumns) indexes.push({
 			name: `${tableName}_${colName}_idx`,
 			columns: [colName]
 		});
+		this.appendDeclaredIndexes(indexes, config?.indexes, columns, tableName);
+		this.ensureDefaultListOrderingIndex(indexes, columns, tableName);
+		this.ensurePolymorphicAssociationIndex(indexes, columns, tableName);
+		this.ensureReferenceColumnIndexes(indexes, columns, tableName);
+		enforceIdentifierLimits(tableName, indexes);
 		const schemaDefinition = {
 			tableName,
 			columns: this.convertManifestColumnsToSchemaColumns(columns),
@@ -807,6 +1212,18 @@ var SchemaGenerator = class {
 		};
 	}
 	/**
+	* Resolve a class name (simple or qualified) to the key it is stored under
+	* in `manifest.objects`. Falls back to the input when the manifest does not
+	* carry the class (e.g. an external STI base absent from the aggregated
+	* manifest), so callers can keep using it as an opaque label.
+	*/
+	resolveManifestClassKey(className, manifest) {
+		if (manifest.objects[className]) return className;
+		const simpleName = className.includes(":") ? className.slice(className.lastIndexOf(":") + 1) : className;
+		for (const [key, obj] of Object.entries(manifest.objects)) if (obj.qualifiedName === className || obj.className === simpleName) return key;
+		return className;
+	}
+	/**
 	* Find all descendants of a class in the manifest
 	*
 	* Note: Manifest keys are now qualified names (@pkg:ClassName) but `extends` field
@@ -851,13 +1268,19 @@ var SchemaGenerator = class {
 		return str.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
 	}
 	/**
-	* Generate SQL CREATE TABLE statement from schema definition
+	* Generate the CREATE TABLE statement for a schema definition.
 	*
-	* This is the single source of truth for SQL generation, consolidating
-	* logic that was previously duplicated across multiple code paths.
+	* With an `engine` this delegates to that engine's DDL strategy. Without
+	* one it renders the engine-neutral preview stored in `schema.ddl` and
+	* `manifest.json`: abstract SQL types, no indexes, no triggers. That
+	* preview is NOT an executable representation of the table (#2358) —
+	* executable paths (`db:migrate`, `MigrationGenerator`, `SchemaAggregator`,
+	* `createIsolatedTestDbFromManifest`) render `schema.columns` and
+	* `schema.indexes` through `getDDLStrategy(engine)` instead.
 	*
 	* @param schema - Schema definition object
-	* @returns SQL CREATE TABLE statement with indexes
+	* @param engine - Optional target engine; omit for the neutral preview
+	* @returns SQL CREATE TABLE statement (no indexes)
 	*/
 	generateSQL(schema, engine) {
 		if (engine) return getDDLStrategy(engine).generateCreateTable(schema);