@db3.ai/app 0.1.0-beta.1

package/dist/db/migrations/contracts/DatabaseMigration.js

@@ -0,0 +1 @@
+export {};

package/dist/db/migrations/contracts/SchemaChange.d.ts

@@ -0,0 +1,83 @@
+import type { SchemaColumn, SchemaForeignKey, SchemaIndex, SchemaTable } from './SchemaSnapshot.js';
+/**
+ * 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/dist/db/migrations/contracts/SchemaChange.js

@@ -0,0 +1 @@
+export {};

package/dist/db/migrations/contracts/SchemaSnapshot.d.ts

@@ -0,0 +1,94 @@
+import type { DatabaseDialectName } from '../../dialects/index.js';
+/**
+ * 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/dist/db/migrations/contracts/SchemaSnapshot.js

@@ -0,0 +1 @@
+export {};

package/dist/db/migrations/contracts/index.d.ts

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

package/dist/db/migrations/contracts/index.js

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

package/dist/db/migrations/errors.d.ts

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

package/dist/db/migrations/errors.js

@@ -0,0 +1,45 @@
+/**
+ * Error raised when another process already owns the source-generation lock.
+ */
+export class DatabaseMigrationLockError extends Error {
+    lockFile;
+    /**
+     * Creates a generation-lock contention error.
+     *
+     * @param lockFile - Absolute lock file currently owned by another process.
+     */
+    constructor(lockFile) {
+        super(`Database migration generation is already running (${lockFile}).`);
+        this.lockFile = 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 {
+    plan;
+    /**
+     * Creates a baseline mismatch error with its structured schema differences.
+     *
+     * @param plan - Differences between the existing database and initial snapshot.
+     */
+    constructor(plan) {
+        super('Existing database does not match the initial schema snapshot.');
+        this.plan = plan;
+        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/dist/db/migrations/index.d.ts

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

package/dist/db/migrations/index.js

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

package/dist/db/migrations/promoteDestructiveSchemaChanges.d.ts

@@ -0,0 +1,19 @@
+import type { SchemaMigrationPlan } from './contracts/index.js';
+/**
+ * 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 declare function promoteDestructiveSchemaChanges(plan: SchemaMigrationPlan): SchemaMigrationPlan;
+/**
+ * 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 declare function planHasOnlyPromotableDestructiveChanges(plan: SchemaMigrationPlan): boolean;

package/dist/db/migrations/promoteDestructiveSchemaChanges.js

@@ -0,0 +1,102 @@
+/**
+ * Blocked operations that may be promoted into generated DDL when the caller
+ * explicitly opts into destructive migration generation.
+ */
+const PROMOTABLE_DESTRUCTIVE_OPERATIONS = new Set([
+    '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) {
+    const remainingBlocked = [];
+    const promoted = [];
+    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) {
+    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) {
+    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;
+    }
+}

package/dist/db/queryMonitor.d.ts

@@ -0,0 +1,142 @@
+import type { Knex } from 'knex';
+import { type DevtoolsEnvironment, type DevtoolsEventDispatcher, type HttpEventDispatcherOptions } from '../devtools/index.js';
+export type QueryMonitorMode = 'dev' | 'slow' | 'full';
+export type QueryMonitorStatus = 'ok' | 'error';
+export interface QueryMonitorOptions {
+    /**
+     * Human-readable source name copied to every emitted query event.
+     */
+    source?: string;
+    /**
+     * Number of recent completed query events retained in memory.
+     */
+    maxEntries?: number;
+    /**
+     * Minimum completed query duration required before an event is retained.
+     */
+    slowMs?: number;
+    /**
+     * Whether query bindings should be copied to emitted events.
+     */
+    includeBindings?: boolean;
+    /**
+     * Optional event sink that receives every retained query event.
+     */
+    dispatch?: QueryMonitorDispatcher;
+}
+/**
+ * HTTP delivery configuration for query monitor events.
+ */
+export type HttpQueryMonitorDispatcherOptions = HttpEventDispatcherOptions;
+export interface QueryMonitorEvent {
+    type: 'db.query';
+    id: string;
+    source: string;
+    timestamp: string;
+    /** Framework operation category associated with the query, when supplied. */
+    category?: string;
+    sql: string;
+    durationMs: number;
+    status: QueryMonitorStatus;
+    bindings?: unknown[];
+    errorMessage?: string;
+    transactionId?: string;
+    connectionId?: string;
+}
+export type QueryMonitorListener = (event: QueryMonitorEvent) => void;
+export type QueryMonitorDispatcher = (event: QueryMonitorEvent) => void;
+interface QueryMonitorEnvironment extends DevtoolsEnvironment {
+    PLATFORM_DEVTOOLS_PORT?: string;
+    PLATFORM_QUERY_MONITOR?: string;
+    PLATFORM_QUERY_MONITOR_BINDINGS?: string;
+    PLATFORM_QUERY_MONITOR_MAX?: string;
+    PLATFORM_QUERY_MONITOR_SLOW_MS?: string;
+    PLATFORM_QUERY_MONITOR_SOURCE?: string;
+    npm_package_name?: string;
+}
+/**
+ * Runs database work under a framework category copied onto monitored query events.
+ *
+ * Categories let development tooling separate framework bookkeeping from application
+ * queries without parsing SQL or changing how the database operation itself behaves.
+ *
+ * @param category - Stable framework operation category such as `queue`.
+ * @param callback - Database work to execute inside the category context.
+ * @returns The callback result without changing its sync or async behavior.
+ */
+export declare function withQueryMonitorCategory<TResult>(category: string, callback: () => TResult): TResult;
+/**
+ * Captures completed Knex query timings from one database connection.
+ */
+export declare class QueryMonitor {
+    private readonly connection;
+    private readonly starts;
+    private readonly entries;
+    private readonly listeners;
+    private readonly maxEntries;
+    private readonly source;
+    private readonly slowMs;
+    private readonly includeBindings;
+    private readonly dispatch?;
+    private readonly eventedConnection;
+    private readonly handleQueryBound;
+    private readonly handleQueryResponseBound;
+    private readonly handleQueryErrorBound;
+    /**
+     * Attaches monitor listeners to a Knex connection.
+     */
+    constructor(connection: Knex, options?: QueryMonitorOptions);
+    /**
+     * Returns completed query events retained in memory.
+     */
+    recent(): QueryMonitorEvent[];
+    /**
+     * Removes completed query events from the in-memory buffer.
+     */
+    clear(): void;
+    /**
+     * Subscribes to completed query events and returns an unsubscribe callback.
+     */
+    subscribe(listener: QueryMonitorListener): () => void;
+    /**
+     * Removes Knex event listeners registered by this monitor.
+     */
+    destroy(): void;
+    /**
+     * Stores the start metadata needed to calculate query duration.
+     */
+    private handleQuery;
+    /**
+     * Publishes a successful completed query event.
+     */
+    private handleQueryResponse;
+    /**
+     * Publishes a failed completed query event.
+     */
+    private handleQueryError;
+    /**
+     * Converts a Knex completion event into the public monitor event shape.
+     */
+    private complete;
+    /**
+     * Retains an event and notifies local plus external subscribers.
+     */
+    private record;
+}
+/**
+ * Returns the existing monitor for a connection or attaches a new one.
+ */
+export declare function queryMonitorFor(connection: Knex, options?: QueryMonitorOptions): QueryMonitor;
+/**
+ * Enables the environment-default query monitor when the runtime opts in.
+ */
+export declare function enableDefaultQueryMonitor(connection: Knex, options?: QueryMonitorOptions | false | undefined, env?: QueryMonitorEnvironment): QueryMonitor | null;
+/**
+ * Resolves query monitor defaults from development and observability env vars.
+ */
+export declare function defaultQueryMonitorOptions(env?: QueryMonitorEnvironment): QueryMonitorOptions | null;
+/**
+ * Creates a fire-and-forget batched HTTP dispatcher for query events.
+ */
+export declare function createHttpQueryMonitorDispatcher(options?: HttpQueryMonitorDispatcherOptions): DevtoolsEventDispatcher<QueryMonitorEvent>;
+export {};