@db3.ai/app 0.1.0-beta.1

package/src/db/migrations/contracts/DatabaseMigration.ts

@@ -0,0 +1,143 @@
+import type { Knex } from 'knex';
+import type { ActiveRecordClass } from '../../ActiveRecord';
+import type { DatabaseDialect } from '../../dialects';
+import type { SchemaMigrationPlan } from './SchemaChange';
+
+/**
+ * Application-owned paths and runtime policy for database migration tooling.
+ */
+export interface DatabaseMigrationManagerOptions {
+	/** Knex connection used for migration execution and database inspection. */
+	db: Knex;
+
+	/** Complete set of ActiveRecord models owned by the application. */
+	models: readonly ActiveRecordClass[];
+
+	/** Dialect used to collect field schema metadata. MariaDB is supported first. */
+	dialect: DatabaseDialect;
+
+	/** Absolute directory containing permanent Knex migration files. */
+	migrationsDirectory: string;
+
+	/** Absolute path of the committed desired-schema snapshot. */
+	snapshotFile: string;
+
+	/** Knex migration ledger table. Its lock table follows Knex naming. */
+	migrationTableName?: string;
+
+	/** Optional database schema containing the Knex migration ledger. */
+	migrationSchemaName?: string;
+
+	/** Migration file extensions Knex may load. */
+	loadExtensions?: readonly string[];
+
+	/** Current application environment. Source generation is refused in production. */
+	environment?: string;
+
+	/** Absolute cross-process lock path used while generating source files. */
+	generationLockFile?: string;
+
+	/** Injectable clock used for deterministic migration filenames in tests. */
+	now?: () => Date;
+}
+
+/**
+ * Persisted and pending Knex migration names without mutating the ledger.
+ */
+export interface DatabaseMigrationState {
+	completed: string[];
+	pending: string[];
+	missingFiles: string[];
+}
+
+/**
+ * Combined model, snapshot, database, and Knex status for CLI or development UI.
+ */
+export interface DatabaseMigrationStatus {
+	snapshotExists: boolean;
+	modelsMatchSnapshot: boolean;
+	databaseMatchesModels: boolean;
+	generationPlan: SchemaMigrationPlan;
+	databasePlan: SchemaMigrationPlan;
+	migrations: DatabaseMigrationState;
+}
+
+/**
+ * Result returned after checking the live database against current models.
+ */
+export interface DatabaseCheckResult {
+	/** Whether the live model-owned schema satisfies current models. */
+	schemaMatches: boolean;
+
+	/** Whether current models have a corresponding committed snapshot. */
+	modelsMatchSnapshot: boolean;
+
+	/** Overall readiness including snapshot and Knex migration state. */
+	matches: boolean;
+
+	/** Differences between the live model-owned schema and current models. */
+	plan: SchemaMigrationPlan;
+
+	/** Differences between the committed snapshot and current models. */
+	snapshotPlan: SchemaMigrationPlan;
+
+	/** Completed, pending, and corrupt Knex migration history. */
+	migrations: DatabaseMigrationState;
+}
+
+/**
+ * Options accepted when generating one permanent migration file.
+ */
+export interface MakeMigrationOptions {
+	/** Human-readable migration name. A deterministic name is inferred when omitted. */
+	name?: string;
+
+	/**
+	 * When true, generate drop DDL for blocked column/index/foreign-key/table
+	 * removals after warning. Other blocked operations still refuse generation.
+	 */
+	allowDestructive?: boolean;
+}
+
+/**
+ * Result of comparing models with the committed snapshot and optionally writing
+ * a new migration.
+ */
+export interface MakeMigrationResult {
+	generated: boolean;
+	blocked: boolean;
+	file: string | null;
+	plan: SchemaMigrationPlan;
+}
+
+/**
+ * Options used when applying permanent Knex migrations.
+ */
+/**
+ * Optional controls for applying committed migrations.
+ */
+export interface MigrateOptions {
+	/**
+	 * Adopt all pending migrations without DDL when an existing untracked
+	 * database already matches the committed schema snapshot.
+	 */
+	baselineIfMatching?: boolean;
+}
+
+/**
+ * Result of applying pending Knex migrations.
+ */
+export interface MigrateResult {
+	applied: string[];
+	batch: number | null;
+	baselined: string[] | null;
+}
+
+/**
+ * Result of the development `make -> migrate -> check` convenience operation.
+ */
+export interface DatabaseSyncResult {
+	make: MakeMigrationResult;
+	migrate: MigrateResult | null;
+	check: DatabaseCheckResult | null;
+}

package/src/db/migrations/contracts/SchemaChange.ts

@@ -0,0 +1,113 @@
+import type { SchemaColumn, SchemaForeignKey, SchemaIndex, SchemaTable } from './SchemaSnapshot';
+
+/**
+ * Schema operation that the first migration generator can apply safely.
+ */
+export type SafeSchemaChange =
+	| {
+		kind: 'create_table';
+		table: SchemaTable;
+		description: string;
+	}
+	| {
+		kind: 'add_column';
+		tableName: string;
+		column: SchemaColumn;
+		description: string;
+	}
+	| {
+		kind: 'add_index';
+		tableName: string;
+		index: SchemaIndex;
+		description: string;
+	}
+	| {
+		kind: 'add_foreign_key';
+		tableName: string;
+		foreignKey: SchemaForeignKey;
+		description: string;
+	}
+	| {
+		kind: 'alter_column';
+		tableName: string;
+		column: SchemaColumn;
+		alterType: boolean;
+		alterNullable: boolean;
+		alterComment: boolean;
+		/** Whether the generated alteration changes or removes the database default. */
+		alterDefault: boolean;
+		description: string;
+	}
+	| {
+		kind: 'alter_table_comment';
+		tableName: string;
+		comment: string | null;
+		description: string;
+	}
+	| {
+		kind: 'drop_column';
+		tableName: string;
+		columnName: string;
+		description: string;
+	}
+	| {
+		kind: 'drop_index';
+		tableName: string;
+		indexName: string;
+		description: string;
+	}
+	| {
+		kind: 'drop_foreign_key';
+		tableName: string;
+		foreignKeyName: string;
+		description: string;
+	}
+	| {
+		kind: 'drop_table';
+		tableName: string;
+		description: string;
+	};
+
+/**
+ * Potentially destructive or ambiguous operation requiring a reviewed manual
+ * migration before the snapshot can advance.
+ */
+export interface BlockedSchemaChange {
+	kind: 'blocked_change';
+	operation:
+		| 'add_required_column'
+		| 'add_unique_column'
+		| 'add_index_to_existing_columns'
+		| 'add_foreign_key_to_existing_column'
+		| 'remove_table'
+		| 'remove_column'
+		| 'remove_index'
+		| 'remove_foreign_key'
+		| 'alter_column_type'
+		| 'tighten_column_nullability'
+		| 'alter_column_primary'
+		| 'alter_column_unique'
+		| 'alter_index'
+		| 'alter_foreign_key';
+	tableName: string;
+	columnName?: string;
+	objectName?: string;
+	description: string;
+}
+
+/**
+ * Pure result of comparing a previous snapshot with a desired snapshot.
+ */
+export interface SchemaMigrationPlan {
+	/** Stable hash of the previous schema snapshot. */
+	fromHash: string;
+
+	/** Stable hash of the desired schema snapshot. */
+	toHash: string;
+
+	/** Automatically renderable additive or widening changes. */
+	safeChanges: SafeSchemaChange[];
+
+	/** Changes that must stop automatic generation. */
+	blockedChanges: BlockedSchemaChange[];
+}

package/src/db/migrations/contracts/SchemaSnapshot.ts

@@ -0,0 +1,122 @@
+import type { DatabaseDialectName } from '../../dialects';
+
+/**
+ * JSON-safe value that can be frozen into a schema snapshot and migration.
+ */
+export type SchemaValue = null | string | number | boolean | SchemaValue[] | {
+	[key: string]: SchemaValue;
+};
+
+/**
+ * Normalized database column owned by an ActiveRecord model.
+ */
+export interface SchemaColumn {
+	/** Physical database column name. */
+	name: string;
+
+	/** Dialect-specific SQL column type. */
+	type: string;
+
+	/** Whether the database column accepts null values. */
+	nullable: boolean;
+
+	/** Whether the database column is the table primary key. */
+	primary: boolean;
+
+	/** Whether the database column has a single-column unique constraint. */
+	unique: boolean;
+
+	/** Static database default, when the model declares one. */
+	default?: SchemaValue;
+
+	/** Normalized database-native column comment. */
+	comment: string | null;
+}
+
+/**
+ * One ordered column in a normalized database index.
+ */
+export interface SchemaIndexColumn {
+	/** Physical database column name. */
+	name: string;
+
+	/** Optional explicit index ordering. */
+	order?: 'asc' | 'desc';
+}
+
+/**
+ * Named database index owned by an ActiveRecord model.
+ */
+export interface SchemaIndex {
+	/** Stable database index name. */
+	name: string;
+
+	/** Ordered columns included in the index. */
+	columns: SchemaIndexColumn[];
+
+	/** Whether values must be unique across the index columns. */
+	unique: boolean;
+
+	/** Database index implementation. */
+	type: 'normal' | 'vector';
+}
+
+/**
+ * Named foreign-key constraint owned by an ActiveRecord model.
+ */
+export interface SchemaForeignKey {
+	/** Stable database constraint name. */
+	name: string;
+
+	/** Local physical database column. */
+	column: string;
+
+	/** Referenced physical database table. */
+	referencesTable: string;
+
+	/** Referenced physical database column. */
+	referencesColumn: string;
+
+	/** Optional action applied when a referenced row is deleted. */
+	onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+
+	/** Optional action applied when a referenced key changes. */
+	onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+}
+
+/**
+ * Normalized database table owned by one ActiveRecord model.
+ */
+export interface SchemaTable {
+	/** Physical database table name. */
+	name: string;
+
+	/** Normalized database-native table comment. */
+	comment: string | null;
+
+	/** Columns sorted by physical name for deterministic serialization. */
+	columns: SchemaColumn[];
+
+	/** Indexes sorted by stable database name. */
+	indexes: SchemaIndex[];
+
+	/** Foreign keys sorted by stable database name. */
+	foreignKeys: SchemaForeignKey[];
+}
+
+/**
+ * Serializable desired database state collected from ActiveRecord models.
+ *
+ * Snapshots deliberately contain no model imports or executable values so an
+ * old migration remains reproducible after application models change.
+ */
+export interface SchemaSnapshot {
+	/** Snapshot format used to support future schema-tool upgrades. */
+	formatVersion: 1;
+
+	/** Database dialect used to resolve model field types. */
+	dialect: DatabaseDialectName;
+
+	/** Model-owned tables sorted by physical database name. */
+	tables: SchemaTable[];
+}

package/src/db/migrations/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from './DatabaseMigration';
+export * from './SchemaChange';
+export * from './SchemaSnapshot';

package/src/db/migrations/errors.ts

@@ -0,0 +1,45 @@
+import type { SchemaMigrationPlan } from './contracts';
+
+/**
+ * Error raised when another process already owns the source-generation lock.
+ */
+export class DatabaseMigrationLockError extends Error {
+	/**
+	 * Creates a generation-lock contention error.
+	 *
+	 * @param lockFile - Absolute lock file currently owned by another process.
+	 */
+	constructor(public readonly lockFile: string) {
+		super(`Database migration generation is already running (${lockFile}).`);
+		this.name = 'DatabaseMigrationLockError';
+	}
+}
+
+/**
+ * Error raised when an existing untracked database cannot safely adopt the
+ * sole initial migration without executing its DDL.
+ */
+export class DatabaseMigrationBaselineError extends Error {
+	/**
+	 * Creates a baseline mismatch error with its structured schema differences.
+	 *
+	 * @param plan - Differences between the existing database and initial snapshot.
+	 */
+	constructor(public readonly plan: SchemaMigrationPlan) {
+		super('Existing database does not match the initial schema snapshot.');
+		this.name = 'DatabaseMigrationBaselineError';
+	}
+}
+
+/**
+ * Error raised when a source-writing operation is attempted in production.
+ */
+export class DatabaseMigrationSourceGenerationError extends Error {
+	/**
+	 * Creates a production source-generation policy error.
+	 */
+	constructor() {
+		super('Database migration source generation is disabled in production.');
+		this.name = 'DatabaseMigrationSourceGenerationError';
+	}
+}

package/src/db/migrations/index.ts

@@ -0,0 +1,10 @@
+export * from './contracts';
+export * from './DatabaseMigrationManager';
+export * from './DatabaseSchemaInspector';
+export * from './errors';
+export * from './KnexMigrationRenderer';
+export * from './ModelSchemaCollector';
+export * from './promoteDestructiveSchemaChanges';
+export * from './SchemaDiffer';
+export * from './SchemaNames';
+export * from './SchemaSnapshotSerializer';

package/src/db/migrations/promoteDestructiveSchemaChanges.ts

@@ -0,0 +1,120 @@
+import type {
+	BlockedSchemaChange,
+	SafeSchemaChange,
+	SchemaMigrationPlan,
+} from './contracts';
+
+/**
+ * Blocked operations that may be promoted into generated DDL when the caller
+ * explicitly opts into destructive migration generation.
+ */
+const PROMOTABLE_DESTRUCTIVE_OPERATIONS = new Set<BlockedSchemaChange['operation']>([
+	'remove_column',
+	'remove_index',
+	'remove_foreign_key',
+	'remove_table',
+]);
+
+/**
+ * Promotes reviewed destructive removals into safe renderable changes.
+ *
+ * Non-destructive blocked operations (type changes, required-column adds, and
+ * similar) remain blocked so accidental data-loss still requires a review.
+ *
+ * @param plan - Diff plan that may contain blocked removals.
+ * @returns Plan with promoted drop operations, or the original plan when nothing
+ *   could be promoted / remaining blocked changes still exist.
+ */
+export function promoteDestructiveSchemaChanges(
+	plan: SchemaMigrationPlan,
+): SchemaMigrationPlan {
+	const remainingBlocked: BlockedSchemaChange[] = [];
+	const promoted: SafeSchemaChange[] = [];
+
+	for (const change of plan.blockedChanges) {
+		if (!PROMOTABLE_DESTRUCTIVE_OPERATIONS.has(change.operation)) {
+			remainingBlocked.push(change);
+			continue;
+		}
+
+		const safeChange = promotedSafeChange(change);
+
+		if (!safeChange) {
+			remainingBlocked.push(change);
+			continue;
+		}
+
+		promoted.push(safeChange);
+	}
+
+	if (promoted.length === 0) return plan;
+
+	return {
+		fromHash: plan.fromHash,
+		toHash: plan.toHash,
+		safeChanges: [...plan.safeChanges, ...promoted],
+		blockedChanges: remainingBlocked,
+	};
+}
+
+/**
+ * Reports whether a plan still contains only promotable destructive removals.
+ *
+ * @param plan - Diff plan before promotion.
+ * @returns True when every blocked change can be turned into a drop.
+ */
+export function planHasOnlyPromotableDestructiveChanges(
+	plan: SchemaMigrationPlan,
+): boolean {
+	return plan.blockedChanges.length > 0
+		&& plan.blockedChanges.every(change => {
+			return PROMOTABLE_DESTRUCTIVE_OPERATIONS.has(change.operation)
+				&& promotedSafeChange(change) !== null;
+		});
+}
+
+/**
+ * Converts one blocked removal into a renderable drop change.
+ *
+ * @param change - Blocked schema change.
+ * @returns Safe drop change, or null when the blocked change is incomplete.
+ */
+function promotedSafeChange(change: BlockedSchemaChange): SafeSchemaChange | null {
+	switch (change.operation) {
+		case 'remove_column':
+			if (!change.columnName) return null;
+
+			return {
+				kind: 'drop_column',
+				tableName: change.tableName,
+				columnName: change.columnName,
+				description: change.description,
+			};
+		case 'remove_index':
+			if (!change.objectName) return null;
+
+			return {
+				kind: 'drop_index',
+				tableName: change.tableName,
+				indexName: change.objectName,
+				description: change.description,
+			};
+		case 'remove_foreign_key':
+			if (!change.objectName) return null;
+
+			return {
+				kind: 'drop_foreign_key',
+				tableName: change.tableName,
+				foreignKeyName: change.objectName,
+				description: change.description,
+			};
+		case 'remove_table':
+			return {
+				kind: 'drop_table',
+				tableName: change.tableName,
+				description: change.description,
+			};
+		default:
+			return null;
+	}
+}