@noormdev/sdk 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { Kysely } from 'kysely';
+import { Generated, Kysely, Transaction } from 'kysely';
 
 /**
  * Supported database dialects.
@@ -45,6 +45,14 @@ export interface ConnectionConfig {
 		key?: string;
 	};
 }
+/**
+ * Result of creating a connection.
+ */
+export interface ConnectionResult {
+	db: Kysely<unknown>;
+	dialect: Dialect;
+	destroy: () => Promise<void>;
+}
 /**
  * Full configuration object.
  *
@@ -377,6 +385,211 @@ export interface SettingsEvents {
 		stageName?: string;
 	};
 }
+/**
+ * Version tracking table.
+ *
+ * Tracks noorm CLI version and all internal schema versions for migrations.
+ * See: plan/datamodel.md#__noorm_version__
+ */
+export interface NoormVersionTable {
+	/** Primary key */
+	id: Generated<number>;
+	/** CLI semver (e.g., "1.2.3") */
+	cli_version: string;
+	/** Database tracking tables version */
+	noorm_version: number;
+	/** State file (state.enc) schema version */
+	state_version: number;
+	/** Settings file (settings.yml) schema version */
+	settings_version: number;
+	/** First installation timestamp */
+	installed_at: Generated<Date>;
+	/** Last upgrade timestamp */
+	upgraded_at: Generated<Date>;
+}
+/**
+ * Operation status values.
+ *
+ * - pending: Operation started but not finished
+ * - success: Operation completed successfully
+ * - failed: Operation failed with error
+ * - reverted: Operation was reverted
+ * - stale: Operation's schema objects were torn down (needs re-run)
+ */
+export type OperationStatus = "pending" | "success" | "failed" | "reverted" | "stale";
+/**
+ * Change type values.
+ */
+export type ChangeType = "build" | "run" | "change";
+/**
+ * Direction values.
+ */
+export type Direction = "change" | "revert";
+/**
+ * Change tracking table.
+ *
+ * Tracks all operation batches—changes, builds, and ad-hoc runs.
+ * See: plan/datamodel.md#__noorm_change__
+ */
+export interface NoormChangeTable {
+	/** Primary key */
+	id: Generated<number>;
+	/** Operation identifier */
+	name: string;
+	/** 'build', 'run', or 'change' */
+	change_type: ChangeType;
+	/** 'change' or 'revert' */
+	direction: Direction;
+	/** SHA-256 of sorted file checksums */
+	checksum: Generated<string>;
+	/** When executed */
+	executed_at: Generated<Date>;
+	/** Identity string */
+	executed_by: Generated<string>;
+	/** Which config was used */
+	config_name: Generated<string>;
+	/** noorm version */
+	cli_version: Generated<string>;
+	/** 'pending', 'success', 'failed', 'reverted' */
+	status: OperationStatus;
+	/** Error details (empty = no error) */
+	error_message: Generated<string>;
+	/** Execution time (0 = never ran) */
+	duration_ms: Generated<number>;
+}
+/**
+ * File execution status values.
+ */
+export type ExecutionStatus = "pending" | "success" | "failed" | "skipped";
+/**
+ * File type values.
+ */
+export type FileType = "sql" | "txt";
+/**
+ * Executions tracking table.
+ *
+ * Tracks individual file executions within an operation.
+ * See: plan/datamodel.md#__noorm_executions__
+ */
+export interface NoormExecutionsTable {
+	/** Primary key */
+	id: Generated<number>;
+	/** Parent operation (FK to __noorm_change__) */
+	change_id: number;
+	/** File that was executed */
+	filepath: string;
+	/** 'sql' or 'txt' */
+	file_type: FileType;
+	/** SHA-256 of file contents */
+	checksum: Generated<string>;
+	/** noorm version */
+	cli_version: Generated<string>;
+	/** 'pending', 'success', 'failed', 'skipped' */
+	status: ExecutionStatus;
+	/** Error details (empty = no error) */
+	error_message: Generated<string>;
+	/** 'unchanged', 'already-run', 'change failed' */
+	skip_reason: Generated<string>;
+	/** Execution time (0 = never ran) */
+	duration_ms: Generated<number>;
+}
+/**
+ * Lock table.
+ *
+ * Prevents concurrent operations on the same database.
+ * See: plan/datamodel.md#__noorm_lock__
+ */
+export interface NoormLockTable {
+	/** Primary key */
+	id: Generated<number>;
+	/** Lock scope (config name) */
+	config_name: string;
+	/** Identity of holder */
+	locked_by: string;
+	/** When acquired */
+	locked_at: Generated<Date>;
+	/** Auto-expiry time */
+	expires_at: Date;
+	/** Lock reason (empty = none) */
+	reason: Generated<string>;
+}
+/**
+ * Identities table.
+ *
+ * Stores user identities for team discovery.
+ * Auto-populated on first connect when identity is set up.
+ * See: plan/datamodel.md#__noorm_identities__
+ */
+export interface NoormIdentitiesTable {
+	/** Primary key */
+	id: Generated<number>;
+	/** SHA-256(email + name + machine + os) */
+	identity_hash: string;
+	/** User email */
+	email: string;
+	/** Display name */
+	name: string;
+	/** Machine hostname */
+	machine: string;
+	/** OS platform and version */
+	os: string;
+	/** X25519 public key (hex) */
+	public_key: string;
+	/** First registration */
+	registered_at: Generated<Date>;
+	/** Last activity */
+	last_seen_at: Generated<Date>;
+	/** Vault key encrypted with user's public key (nullable for users without vault access) */
+	encrypted_vault_key: string | null;
+}
+/**
+ * Vault secrets table.
+ *
+ * Stores encrypted secrets shared across the team.
+ * Secrets are encrypted with a vault key that is distributed
+ * to team members via their public keys.
+ */
+export interface NoormVaultTable {
+	/** Primary key */
+	id: Generated<number>;
+	/** Secret key name (e.g., 'API_KEY', 'DB_PASSWORD') */
+	secret_key: string;
+	/** AES-256-GCM encrypted value (JSON: {iv, authTag, ciphertext}) */
+	encrypted_value: string;
+	/** Identity who set this secret */
+	set_by: string;
+	/** When created */
+	created_at: Generated<Date>;
+	/** When last updated */
+	updated_at: Generated<Date>;
+}
+/**
+ * Combined database interface for all noorm tracking tables.
+ *
+ * Use this with Kysely<NoormDatabase> for type-safe queries.
+ *
+ * @example
+ * ```typescript
+ * import { NoormDatabase, NOORM_TABLES } from './shared'
+ *
+ * const db = new Kysely<NoormDatabase>({ dialect })
+ *
+ * const version = await db
+ *     .selectFrom(NOORM_TABLES.version)
+ *     .selectAll()
+ *     .orderBy('id', 'desc')
+ *     .limit(1)
+ *     .executeTakeFirst()
+ * ```
+ */
+export interface NoormDatabase {
+	__noorm_version__: NoormVersionTable;
+	__noorm_change__: NoormChangeTable;
+	__noorm_executions__: NoormExecutionsTable;
+	__noorm_lock__: NoormLockTable;
+	__noorm_identities__: NoormIdentitiesTable;
+	__noorm_vault__: NoormVaultTable;
+}
 /**
  * Identity types.
  *
@@ -410,24 +623,6 @@ export interface Identity {
 	/** How the identity was resolved */
 	source: IdentitySource;
 }
-/**
- * Operation status values.
- *
- * - pending: Operation started but not finished
- * - success: Operation completed successfully
- * - failed: Operation failed with error
- * - reverted: Operation was reverted
- * - stale: Operation's schema objects were torn down (needs re-run)
- */
-export type OperationStatus = "pending" | "success" | "failed" | "reverted" | "stale";
-/**
- * Direction values.
- */
-export type Direction = "change" | "revert";
-/**
- * File execution status values.
- */
-export type ExecutionStatus = "pending" | "success" | "failed" | "skipped";
 /**
  * Overview counts for all categories.
  */
@@ -669,6 +864,40 @@ export interface ChangeFile {
 	/** Why the file was skipped */
 	skipReason?: string;
 }
+/**
+ * A change parsed from disk.
+ *
+ * Contains the folder structure with change and revert files.
+ *
+ * @example
+ * ```typescript
+ * const change: Change = {
+ *     name: '2024-01-15-add-email-verification',
+ *     path: '/project/changes/2024-01-15-add-email-verification',
+ *     date: new Date('2024-01-15'),
+ *     description: 'add-email-verification',
+ *     changeFiles: [...],
+ *     revertFiles: [...],
+ *     hasChangelog: true,
+ * }
+ * ```
+ */
+export interface Change {
+	/** Folder name (e.g., "2024-01-15-add-email-verification") */
+	name: string;
+	/** Absolute path to change folder */
+	path: string;
+	/** Date parsed from name (null if no date prefix) */
+	date: Date | null;
+	/** Human-readable description from name */
+	description: string;
+	/** Files in change/ folder */
+	changeFiles: ChangeFile[];
+	/** Files in revert/ folder */
+	revertFiles: ChangeFile[];
+	/** Whether changelog.md exists */
+	hasChangelog: boolean;
+}
 /**
  * A change with merged disk and database information.
  *
@@ -745,6 +974,50 @@ export interface ChangeOptions {
 	/** Write preview output to file. Default: null */
 	output?: string | null;
 }
+/**
+ * Options for batch operations (next, ff, rewind).
+ */
+export interface BatchChangeOptions extends ChangeOptions {
+	/** Stop on first failure. Default: true */
+	abortOnError?: boolean;
+}
+/**
+ * Context required to execute changes.
+ *
+ * @example
+ * ```typescript
+ * const context: ChangeContext = {
+ *     db,
+ *     configName: 'dev',
+ *     identity: { name: 'Alice', email: 'alice@example.com' },
+ *     projectRoot: '/project',
+ *     changesDir: '/project/changes',
+ *     sqlDir: '/project/sql',
+ * }
+ * ```
+ */
+export interface ChangeContext {
+	/** Kysely database connection */
+	db: Kysely<NoormDatabase>;
+	/** Name of the active config */
+	configName: string;
+	/** User identity for tracking */
+	identity: Identity;
+	/** Project root for template resolution */
+	projectRoot: string;
+	/** Directory containing changes */
+	changesDir: string;
+	/** Schema directory for resolving .txt references */
+	sqlDir: string;
+	/** Config object for template context */
+	config?: Record<string, unknown>;
+	/** Secrets for template context */
+	secrets?: Record<string, string>;
+	/** Global secrets for template context */
+	globalSecrets?: Record<string, string>;
+	/** Database dialect for lock formatting. Default: 'postgres' */
+	dialect?: "postgres" | "mysql" | "sqlite" | "mssql";
+}
 /**
  * Result of executing a single change.
  *
@@ -834,6 +1107,119 @@ export interface ChangeHistoryRecord {
 	/** Checksum of files */
 	checksum: string;
 }
+/**
+ * File execution record from history.
+ */
+export interface FileHistoryRecord {
+	/** Record ID */
+	id: number;
+	/** Parent change ID */
+	changeId: number;
+	/** File path */
+	filepath: string;
+	/** File type */
+	fileType: ChangeFileType;
+	/** File checksum */
+	checksum: string;
+	/** Execution status */
+	status: ExecutionStatus;
+	/** Skip reason if skipped */
+	skipReason: string | null;
+	/** Error message if failed */
+	errorMessage: string | null;
+	/** Duration in milliseconds */
+	durationMs: number;
+}
+declare class ChangeManager {
+	#private;
+	constructor(context: ChangeContext);
+	/**
+	 * List all changes with status.
+	 *
+	 * Merges changes from disk with status from database.
+	 * Includes orphaned changes (in DB but not on disk).
+	 *
+	 * @returns Array of changes with merged status
+	 */
+	list(): Promise<ChangeListItem[]>;
+	/**
+	 * Run a specific change by name.
+	 *
+	 * @param name - Change name
+	 * @param options - Execution options
+	 * @returns Execution result
+	 */
+	run(name: string, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Run a change object directly.
+	 */
+	runChange(change: Change, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Revert a specific change by name.
+	 *
+	 * @param name - Change name
+	 * @param options - Execution options
+	 * @returns Execution result
+	 */
+	revert(name: string, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Revert a change object directly.
+	 */
+	revertChange(change: Change, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Run next N pending changes.
+	 *
+	 * @param count - Number of changes to run (default: 1)
+	 * @param options - Execution options
+	 * @returns Batch result
+	 */
+	next(count?: number, options?: BatchChangeOptions): Promise<BatchChangeResult>;
+	/**
+	 * Fast-forward: run all pending changes.
+	 *
+	 * @param options - Execution options
+	 * @returns Batch result
+	 */
+	ff(options?: BatchChangeOptions): Promise<BatchChangeResult>;
+	/**
+	 * Rewind: revert changes in reverse order.
+	 *
+	 * @param target - Number of changes to revert, or name to revert to
+	 * @param options - Execution options
+	 * @returns Batch result
+	 */
+	rewind(target: number | string, options?: BatchChangeOptions): Promise<BatchChangeResult>;
+	/**
+	 * Get execution history.
+	 *
+	 * @param name - Optional change name (all if not provided)
+	 * @param limit - Max records to return
+	 * @returns Array of history records
+	 */
+	getHistory(name?: string, limit?: number): Promise<ChangeHistoryRecord[]>;
+	/**
+	 * Get file execution history for an operation.
+	 */
+	getFileHistory(operationId: number): Promise<FileHistoryRecord[]>;
+	/**
+	 * Remove a change from disk, database, or both.
+	 *
+	 * @param name - Change name
+	 * @param options - What to remove
+	 */
+	remove(name: string, options: {
+		disk?: boolean;
+		db?: boolean;
+	}): Promise<void>;
+	/**
+	 * Get a specific change by name.
+	 */
+	get(name: string): Promise<ChangeListItem | null>;
+	/**
+	 * Load a change from disk.
+	 */
+	load(name: string): Promise<Change>;
+}
 /**
  * Lock manager types.
  *
@@ -999,6 +1385,168 @@ interface ProcessResult {
 	 */
 	durationMs?: number;
 }
+/**
+ * Simple types stored as native JSON values. No encoding tuple needed.
+ */
+export type SimpleType = "string" | "int" | "bigint" | "float" | "decimal" | "bool" | "timestamp" | "date" | "uuid";
+/**
+ * Encoded types that always use a `[value, encoding]` tuple in .dt files.
+ */
+export type EncodedType = "json" | "binary" | "vector" | "array" | "text" | "custom";
+/**
+ * All universal types recognized by the .dt format.
+ */
+export type UniversalType = SimpleType | EncodedType;
+/**
+ * Column definition within a .dt schema.
+ *
+ * @example
+ * ```typescript
+ * const col: DtColumn = {
+ *     name: 'embedding',
+ *     type: 'vector',
+ *     sourceType: 'vector(1536)',
+ *     nullable: false,
+ * };
+ * ```
+ */
+export interface DtColumn {
+	/** Column name as it appears in the source database. */
+	name: string;
+	/** Universal type classification. */
+	type: UniversalType;
+	/** Original database-specific type (e.g., `jsonb`, `vector(1536)`). */
+	sourceType?: string;
+	/** Whether NULL values are permitted. Default: true. */
+	nullable?: boolean;
+}
+/**
+ * Schema validation result.
+ */
+export interface SchemaValidationResult {
+	/** Whether the schema is compatible with the target. */
+	valid: boolean;
+	/** Blocking errors that prevent transfer. */
+	errors: string[];
+	/** Non-blocking warnings about potential issues. */
+	warnings: string[];
+}
+/**
+ * Strategy for handling primary key conflicts during transfer.
+ *
+ * - `fail`: Abort on first conflict (default)
+ * - `skip`: Skip conflicting rows, continue transfer
+ * - `update`: Update existing rows with source data
+ * - `replace`: Delete and re-insert conflicting rows
+ */
+export type ConflictStrategy = "fail" | "skip" | "update" | "replace";
+/**
+ * Options for data transfer operations.
+ *
+ * @example
+ * ```typescript
+ * const options: TransferOptions = {
+ *     tables: ['users', 'posts'],
+ *     onConflict: 'skip',
+ *     batchSize: 5000,
+ *     truncateFirst: false,
+ * };
+ * ```
+ */
+export interface TransferOptions {
+	/** Tables to transfer. Empty = all user tables. */
+	tables?: string[];
+	/** How to handle primary key conflicts. Default: 'fail' */
+	onConflict?: ConflictStrategy;
+	/** Rows per batch for cross-server transfers. Default: 1000 */
+	batchSize?: number;
+	/** Disable foreign key checks during transfer. Default: true */
+	disableForeignKeys?: boolean;
+	/** Preserve identity/auto-increment values. Default: true */
+	preserveIdentity?: boolean;
+	/** Truncate destination tables before transfer. Default: false */
+	truncateFirst?: boolean;
+	/** Validate only, don't execute. Default: false */
+	dryRun?: boolean;
+	/** Export to .dt file instead of DB insert. */
+	exportPath?: string;
+	/** Passphrase for .dtzx export encryption. */
+	passphrase?: string;
+}
+/**
+ * Plan for a single table transfer.
+ */
+export interface TransferTablePlan {
+	/** Table name */
+	name: string;
+	/** Table schema (if applicable) */
+	schema?: string;
+	/** Estimated row count */
+	rowCount: number;
+	/** Whether table has identity/auto-increment column */
+	hasIdentity: boolean;
+	/** Identity column name if present */
+	identityColumn?: string;
+	/** Primary key columns */
+	primaryKey: string[];
+	/** All column names */
+	columns: string[];
+	/** Tables this table depends on (FK references) */
+	dependsOn: string[];
+	/** Column type definitions for cross-dialect transfers. */
+	columnTypes?: DtColumn[];
+}
+/**
+ * Complete transfer plan.
+ *
+ * Contains ordered list of tables and transfer metadata.
+ */
+export interface TransferPlan {
+	/** Tables in dependency order (parents before children) */
+	tables: TransferTablePlan[];
+	/** Whether source and destination are on same server */
+	sameServer: boolean;
+	/** Total estimated rows across all tables */
+	estimatedRows: number;
+	/** Warnings about potential issues */
+	warnings: string[];
+	/** Whether this is a cross-dialect transfer. */
+	crossDialect: boolean;
+	/** Source database dialect. */
+	sourceDialect: Dialect;
+	/** Destination database dialect. */
+	destinationDialect: Dialect;
+}
+/**
+ * Result for a single table transfer.
+ */
+export interface TransferTableResult {
+	/** Table name */
+	table: string;
+	/** Transfer status */
+	status: "success" | "skipped" | "failed";
+	/** Rows successfully transferred */
+	rowsTransferred: number;
+	/** Rows skipped due to conflicts */
+	rowsSkipped: number;
+	/** Duration in milliseconds */
+	durationMs: number;
+	/** Error message if failed */
+	error?: string;
+}
+/**
+ * Complete transfer result.
+ */
+export interface TransferResult {
+	/** Overall status */
+	status: "success" | "partial" | "failed";
+	/** Results per table */
+	tables: TransferTableResult[];
+	/** Total rows transferred */
+	totalRows: number;
+	/** Total duration in milliseconds */
+	durationMs: number;
+}
 /**
  * SDK Types.
  *
@@ -1053,40 +1601,64 @@ export interface CreateContextOptions {
 	stage?: string;
 }
 /**
- * Result of an execute() call.
+ * Options for build operations.
  */
-export interface ExecuteResult {
-	/** Number of rows affected (if available) */
-	rowsAffected?: number;
+export interface BuildOptions {
+	/** Skip checksum checks, rebuild everything. Default: false */
+	force?: boolean;
 }
 /**
- * Transaction context for use within transaction callbacks.
+ * Options for exporting a table to a .dt file.
+ *
+ * Connection details (db, dialect) come from the context automatically.
  *
  * @example
  * ```typescript
- * await ctx.transaction(async (tx) => {
- *     const [user] = await tx.query('SELECT * FROM users WHERE id = $1', [id])
- *     await tx.execute('UPDATE users SET login_count = login_count + 1 WHERE id = $1', [id])
- *     return user
- * })
+ * const [result, err] = await ctx.exportTable('users', './exports/users.dtz', {
+ *     passphrase: 'secret',
+ *     batchSize: 5000,
+ * });
  * ```
  */
-export interface TransactionContext {
-	/**
-	 * Execute a SELECT query within the transaction.
-	 */
-	query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
-	/**
-	 * Execute an INSERT/UPDATE/DELETE within the transaction.
-	 */
-	execute(sql: string, params?: unknown[]): Promise<ExecuteResult>;
+export interface ExportOptions {
+	/** Passphrase for .dtzx encryption. */
+	passphrase?: string;
+	/** Schema/namespace (e.g., 'public' for PostgreSQL). */
+	schema?: string;
+	/** Rows per batch. Default: 1000. */
+	batchSize?: number;
 }
 /**
- * Options for build operations.
+ * Options for importing a .dt file into the database.
+ *
+ * Connection details (db, dialect) come from the context automatically.
+ *
+ * @example
+ * ```typescript
+ * const [result, err] = await ctx.importFile('./exports/users.dtz', {
+ *     onConflict: 'skip',
+ *     truncate: true,
+ * });
+ * ```
  */
-export interface BuildOptions {
-	/** Skip checksum checks, rebuild everything. Default: false */
-	force?: boolean;
+export interface ImportOptions {
+	/** Passphrase for .dtzx decryption. */
+	passphrase?: string;
+	/** Rows per batch. Default: 1000. */
+	batchSize?: number;
+	/** Conflict strategy. Default: 'fail'. */
+	onConflict?: "fail" | "skip" | "update" | "replace";
+	/** Truncate target table before import. Default: false. */
+	truncate?: boolean;
+}
+export interface ContextState {
+	connection: ConnectionResult | null;
+	config: Config;
+	settings: Settings;
+	identity: Identity;
+	options: CreateContextOptions;
+	projectRoot: string;
+	changeManager: ChangeManager | null;
 }
 export type Events<Shape> = keyof Shape;
 declare namespace ObserverEngine {
@@ -1689,6 +2261,277 @@ export type ShutdownReason = "signal" | "user" | "error" | "programmatic";
  * Application mode.
  */
 export type AppMode = "tui" | "headless";
+/**
+ * Type definitions for auto-update feature.
+ *
+ * Includes global settings structure and update check/result types.
+ */
+/**
+ * Dismissable alert preference.
+ *
+ * Controls how alerts are handled after user makes a choice:
+ * - 'ask': Show the alert and ask user each time (default)
+ * - 'always': Always perform the action without asking
+ * - 'never': Never perform the action, auto-deny
+ */
+export type DismissablePreference = "ask" | "always" | "never";
+/**
+ * Global settings stored in ~/.noorm/settings.yml
+ *
+ * These are user-level settings, separate from project settings.
+ * Used for preferences that apply across all projects.
+ */
+export interface GlobalSettings {
+	/** Check for updates on TUI launch (default: true) */
+	checkUpdates: boolean;
+	/** Auto-install updates without prompting (default: false) */
+	autoUpdate: boolean;
+	/** Last check timestamp (ISO string) */
+	lastCheck?: string;
+	/** Cached latest version from last check */
+	cachedVersion?: string;
+	/**
+	 * Dismissable alert preferences.
+	 *
+	 * Stores user decisions for alerts that can be permanently dismissed.
+	 * Keys are alert identifiers (e.g., 'majorVersionUpdate').
+	 */
+	dismissable?: Record<string, DismissablePreference>;
+}
+/**
+ * Events emitted by the update module.
+ *
+ * Used to integrate with the observer event system.
+ */
+export interface UpdateEvents {
+	"update:checking": Record<string, never>;
+	"update:available": {
+		currentVersion: string;
+		latestVersion: string;
+	};
+	"update:major-available": {
+		currentVersion: string;
+		latestVersion: string;
+	};
+	"update:not-available": {
+		currentVersion: string;
+	};
+	"update:check-failed": {
+		error: string;
+	};
+	"update:installing": {
+		version: string;
+	};
+	"update:complete": {
+		previousVersion: string;
+		newVersion: string;
+	};
+	"update:failed": {
+		version: string;
+		error: string;
+	};
+	"update:skipped": {
+		version: string;
+		reason: "user-denied" | "user-deferred";
+	};
+	"global-settings:loaded": {
+		settings: GlobalSettings;
+	};
+	"global-settings:updated": {
+		key: string;
+		value: unknown;
+	};
+}
+/**
+ * Vault event types.
+ *
+ * All events emitted by the vault module. These are merged into
+ * NoormEvents via the VaultEvents interface.
+ */
+/**
+ * Vault events for observer integration.
+ *
+ * Events follow the naming convention `vault:{operation}`.
+ */
+export interface VaultEvents {
+	/** Vault was initialized for the first time */
+	"vault:initialized": {
+		identityHash: string;
+	};
+	/** New vault secret was created */
+	"vault:secret:created": {
+		key: string;
+		setBy: string;
+	};
+	/** Existing vault secret was updated */
+	"vault:secret:updated": {
+		key: string;
+		setBy: string;
+	};
+	/** Vault secret was deleted */
+	"vault:secret:deleted": {
+		key: string;
+	};
+	/** Vault key was propagated to a user */
+	"vault:propagated": {
+		toIdentityHash: string;
+		toEmail: string;
+	};
+	/** Vault copy operation started */
+	"vault:copy:starting": {
+		source: string;
+		destination: string;
+		keys: "all" | number;
+	};
+	/** Vault copy operation completed */
+	"vault:copy:completed": {
+		source: string;
+		destination: string;
+		copied: number;
+		skipped: number;
+		errors: number;
+	};
+}
+/**
+ * Transfer event types for observer integration.
+ *
+ * Events emitted during data transfer operations for CLI progress display.
+ */
+/**
+ * Events emitted by the transfer module.
+ *
+ * Subscribe to these events to track transfer progress in the CLI.
+ */
+export interface TransferEvents {
+	/** Emitted when transfer planning starts */
+	"transfer:planning": {
+		source: string;
+		destination: string;
+	};
+	/** Emitted when transfer plan is ready */
+	"transfer:plan:ready": {
+		sameServer: boolean;
+		tableCount: number;
+		estimatedRows: number;
+		warnings: string[];
+	};
+	/** Emitted when transfer execution starts */
+	"transfer:starting": {
+		tableCount: number;
+		sameServer: boolean;
+	};
+	/** Emitted before transferring each table */
+	"transfer:table:before": {
+		table: string;
+		index: number;
+		total: number;
+		rowCount: number;
+	};
+	/** Emitted during table transfer with progress */
+	"transfer:table:progress": {
+		table: string;
+		rowsTransferred: number;
+		rowsTotal: number;
+		rowsSkipped: number;
+	};
+	/** Emitted after transferring each table */
+	"transfer:table:after": {
+		table: string;
+		status: "success" | "skipped" | "failed";
+		rowsTransferred: number;
+		rowsSkipped: number;
+		durationMs: number;
+		error?: string;
+	};
+	/** Emitted when transfer completes */
+	"transfer:complete": {
+		status: "success" | "partial" | "failed";
+		totalRows: number;
+		tableCount: number;
+		durationMs: number;
+	};
+}
+/**
+ * Events emitted by the dt module.
+ *
+ * Subscribe to these events to track .dt operation progress in the CLI.
+ */
+export interface DtEvents {
+	/** Export begins for a table. */
+	"dt:export:start": {
+		filepath: string;
+		table: string;
+		columnCount: number;
+	};
+	/** After each batch flush during export. */
+	"dt:export:progress": {
+		filepath: string;
+		table: string;
+		rowsWritten: number;
+		bytesWritten: number;
+	};
+	/** Export finished for a table. */
+	"dt:export:complete": {
+		filepath: string;
+		table: string;
+		rowsWritten: number;
+		bytesWritten: number;
+		durationMs: number;
+	};
+	/** Import begins for a file. */
+	"dt:import:start": {
+		filepath: string;
+		sourceDialect: string;
+		sourceVersion: string;
+		table: string;
+	};
+	/** Schema parsed and validated during import. */
+	"dt:import:schema": {
+		filepath: string;
+		table: string;
+		columns: number;
+		validation: SchemaValidationResult;
+	};
+	/** After each batch insert during import. */
+	"dt:import:progress": {
+		filepath: string;
+		table: string;
+		rowsImported: number;
+		rowsSkipped: number;
+	};
+	/** Import finished for a file. */
+	"dt:import:complete": {
+		filepath: string;
+		table: string;
+		rowsImported: number;
+		rowsSkipped: number;
+		durationMs: number;
+	};
+	/** Cross-dialect stream begins. */
+	"dt:stream:start": {
+		table: string;
+		sourceDialect: string;
+		targetDialect: string;
+	};
+	/** After each batch conversion during streaming. */
+	"dt:stream:progress": {
+		table: string;
+		rowsConverted: number;
+	};
+	/** Cross-dialect stream finished. */
+	"dt:stream:complete": {
+		table: string;
+		rowsConverted: number;
+		durationMs: number;
+	};
+	/** Schema validation completed. */
+	"dt:validate:result": {
+		table: string;
+		valid: boolean;
+		errors: string[];
+		warnings: string[];
+	};
+}
 /**
  * All events emitted by noorm core modules.
  *
@@ -1706,9 +2549,12 @@ export type AppMode = "tui" | "headless";
  * - `identity:*` - Identity resolution
  * - `connection:*` - Database connections
  * - `settings:*` - Settings lifecycle and mutations
+ * - `vault:*` - Vault operations
+ * - `transfer:*` - Data transfer operations
+ * - `dt:*` - .dt format export/import/stream operations
  * - `error` - Catch-all errors
  */
-export interface NoormEvents extends SettingsEvents {
+export interface NoormEvents extends SettingsEvents, UpdateEvents, VaultEvents, TransferEvents, DtEvents {
 	"file:before": {
 		filepath: string;
 		checksum: string;
@@ -1726,7 +2572,9 @@ export interface NoormEvents extends SettingsEvents {
 	};
 	"file:dry-run": {
 		filepath: string;
-		outputPath: string;
+		status: "success" | "failed";
+		outputPath?: string;
+		error?: string;
 	};
 	"change:created": {
 		name: string;
@@ -1893,6 +2741,7 @@ export interface NoormEvents extends SettingsEvents {
 		registered: boolean;
 		knownUsersCount: number;
 	};
+	"identity:not-found": void;
 	"connection:open": {
 		configName: string;
 		dialect: string;
@@ -1945,65 +2794,439 @@ export interface NoormEvents extends SettingsEvents {
 }
 export type NoormEventNames = Events<NoormEvents>;
 /**
- * SDK Context implementation.
+ * Noorm-specific operations accessed via ctx.noorm.
  *
- * Provides programmatic access to all noorm operations.
+ * All database management operations — schema, changes, locks,
+ * runner, explore, transfer, DT — live here. The shared ContextState
+ * keeps connection state in sync with the parent Context.
  *
  * @example
  * ```typescript
  * const ctx = await createContext({ config: 'dev' })
  * await ctx.connect()
  *
- * // Run queries
- * const users = await ctx.query('SELECT * FROM users')
- *
- * // Clean disconnect
- * await ctx.disconnect()
+ * await ctx.noorm.build()
+ * await ctx.noorm.fastForward()
+ * const tables = await ctx.noorm.listTables()
  * ```
  */
-export declare class Context<DB = unknown> {
+export declare class NoormOps {
 	#private;
-	constructor(config: Config, settings: Settings, identity: Identity, options: CreateContextOptions, projectRoot: string);
+	constructor(state: ContextState);
 	get config(): Config;
 	get settings(): Settings;
 	get identity(): Identity;
-	get dialect(): Dialect;
-	get connected(): boolean;
 	get observer(): ObserverEngine<NoormEvents>;
-	get kysely(): Kysely<DB>;
-	connect(): Promise<void>;
-	disconnect(): Promise<void>;
-	query<T = Record<string, unknown>>(sqlStr: string, _params?: unknown[]): Promise<T[]>;
-	execute(sqlStr: string, _params?: unknown[]): Promise<ExecuteResult>;
-	transaction<T>(fn: (tx: TransactionContext) => Promise<T>): Promise<T>;
+	/**
+	 * List all tables in the database.
+	 *
+	 * @example
+	 * ```typescript
+	 * const tables = await ctx.noorm.listTables()
+	 * ```
+	 */
 	listTables(): Promise<TableSummary[]>;
+	/**
+	 * Get detailed information about a table.
+	 *
+	 * @example
+	 * ```typescript
+	 * const detail = await ctx.noorm.describeTable('users')
+	 * ```
+	 */
 	describeTable(name: string, schema?: string): Promise<TableDetail | null>;
+	/**
+	 * Get database overview with counts of all object types.
+	 *
+	 * @example
+	 * ```typescript
+	 * const overview = await ctx.noorm.overview()
+	 * ```
+	 */
 	overview(): Promise<ExploreOverview>;
+	/**
+	 * Wipe all data, keeping the schema intact.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.truncate()
+	 * ```
+	 */
 	truncate(): Promise<TruncateResult>;
+	/**
+	 * Drop all database objects except noorm tracking tables.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.teardown()
+	 * ```
+	 */
 	teardown(): Promise<TeardownResult>;
+	/**
+	 * Execute all SQL files in the schema directory.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.build({ force: true })
+	 * ```
+	 */
 	build(options?: BuildOptions): Promise<BatchResult>;
+	/**
+	 * Full rebuild: teardown + build.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.reset()
+	 * ```
+	 */
 	reset(): Promise<void>;
+	/**
+	 * Execute a single SQL file.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.runFile('seeds/test-data.sql')
+	 * ```
+	 */
 	runFile(filepath: string, options?: RunOptions): Promise<FileResult>;
+	/**
+	 * Execute multiple SQL files sequentially.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.runFiles(['functions/utils.sql', 'triggers/audit.sql'])
+	 * ```
+	 */
 	runFiles(filepaths: string[], options?: RunOptions): Promise<BatchResult>;
+	/**
+	 * Execute all SQL files in a directory.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.runDir('seeds/')
+	 * ```
+	 */
 	runDir(dirpath: string, options?: RunOptions): Promise<BatchResult>;
+	/**
+	 * Apply a specific change.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.applyChange('2024-01-15-add-users')
+	 * ```
+	 */
 	applyChange(name: string, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Revert a specific change.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.revertChange('2024-01-15-add-users')
+	 * ```
+	 */
 	revertChange(name: string, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Apply all pending changes.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.fastForward()
+	 * ```
+	 */
 	fastForward(): Promise<BatchChangeResult>;
+	/**
+	 * Get status of all changes.
+	 *
+	 * @example
+	 * ```typescript
+	 * const changes = await ctx.noorm.getChangeStatus()
+	 * ```
+	 */
 	getChangeStatus(): Promise<ChangeListItem[]>;
+	/**
+	 * Get only pending changes.
+	 *
+	 * @example
+	 * ```typescript
+	 * const pending = await ctx.noorm.getPendingChanges()
+	 * ```
+	 */
 	getPendingChanges(): Promise<ChangeListItem[]>;
+	/**
+	 * Get a config-scoped secret.
+	 *
+	 * @example
+	 * ```typescript
+	 * const apiKey = ctx.noorm.getSecret('API_KEY')
+	 * ```
+	 */
 	getSecret(key: string): string | undefined;
+	/**
+	 * Acquire a database lock.
+	 *
+	 * @example
+	 * ```typescript
+	 * const lock = await ctx.noorm.acquireLock({ timeout: 60000 })
+	 * ```
+	 */
 	acquireLock(options?: LockOptions$1): Promise<Lock$1>;
+	/**
+	 * Release the current lock.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.releaseLock()
+	 * ```
+	 */
 	releaseLock(): Promise<void>;
+	/**
+	 * Get current lock status.
+	 *
+	 * @example
+	 * ```typescript
+	 * const status = await ctx.noorm.getLockStatus()
+	 * ```
+	 */
 	getLockStatus(): Promise<LockStatus>;
+	/**
+	 * Execute an operation with automatic lock acquisition and release.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.withLock(async () => {
+	 *     await ctx.noorm.build()
+	 *     await ctx.noorm.fastForward()
+	 * })
+	 * ```
+	 */
 	withLock<T>(fn: () => Promise<T>, options?: LockOptions$1): Promise<T>;
+	/**
+	 * Force release any database lock regardless of ownership.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.forceReleaseLock()
+	 * ```
+	 */
 	forceReleaseLock(): Promise<boolean>;
+	/**
+	 * Render a template file without executing.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.renderTemplate('sql/001_users.sql.tmpl')
+	 * ```
+	 */
 	renderTemplate(filepath: string): Promise<ProcessResult>;
+	/**
+	 * Get execution history.
+	 *
+	 * @example
+	 * ```typescript
+	 * const history = await ctx.noorm.getHistory(10)
+	 * ```
+	 */
 	getHistory(limit?: number): Promise<ChangeHistoryRecord[]>;
+	/**
+	 * Compute SHA-256 checksum for a file.
+	 *
+	 * @example
+	 * ```typescript
+	 * const checksum = await ctx.noorm.computeChecksum('sql/001_users.sql')
+	 * ```
+	 */
 	computeChecksum(filepath: string): Promise<string>;
+	/**
+	 * Tests if the connection can be established.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.testConnection()
+	 * ```
+	 */
 	testConnection(): Promise<{
 		ok: boolean;
 		error?: string;
 	}>;
+	/**
+	 * Transfer data from this context's database to a destination context.
+	 *
+	 * Both contexts must be connected. Uses each context's config for
+	 * connection management.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [result, err] = await source.noorm.transferTo(dest, {
+	 *     tables: ['users', 'posts'],
+	 *     onConflict: 'skip',
+	 * })
+	 * ```
+	 */
+	transferTo(destConfig: Config, options?: TransferOptions): Promise<[
+		TransferResult | null,
+		Error | null
+	]>;
+	/**
+	 * Generate a transfer plan without executing.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [plan, err] = await source.noorm.transferPlan(destConfig)
+	 * ```
+	 */
+	transferPlan(destConfig: Config, options?: TransferOptions): Promise<[
+		TransferPlan | null,
+		Error | null
+	]>;
+	/**
+	 * Export a table to a .dt file.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [result, err] = await ctx.noorm.exportTable('users', './exports/users.dtz')
+	 * ```
+	 */
+	exportTable(tableName: string, filepath: string, options?: ExportOptions): Promise<[
+		{
+			rowsWritten: number;
+			bytesWritten: number;
+		} | null,
+		Error | null
+	]>;
+	/**
+	 * Import a .dt file into the connected database.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [result, err] = await ctx.noorm.importFile('./exports/users.dtz', {
+	 *     onConflict: 'skip',
+	 * })
+	 * ```
+	 */
+	importFile(filepath: string, options?: ImportOptions): Promise<[
+		{
+			rowsImported: number;
+			rowsSkipped: number;
+		} | null,
+		Error | null
+	]>;
+}
+/**
+ * SDK Context implementation.
+ *
+ * Provides SQL-focused programmatic access to the database.
+ * Noorm management operations are accessible via ctx.noorm.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await createContext({ config: 'dev' })
+ * await ctx.connect()
+ *
+ * // Top-level — SQL focused
+ * const users = await ctx.kysely
+ *     .selectFrom('users')
+ *     .selectAll()
+ *     .execute()
+ *
+ * // Noorm operations — under namespace
+ * await ctx.noorm.build()
+ * await ctx.noorm.fastForward()
+ *
+ * await ctx.disconnect()
+ * ```
+ */
+export declare class Context<DB = unknown, Procs = object, Funcs = object> {
+	#private;
+	constructor(config: Config, settings: Settings, identity: Identity, options: CreateContextOptions, projectRoot: string);
+	get dialect(): Dialect;
+	get connected(): boolean;
+	get kysely(): Kysely<DB>;
+	/**
+	 * Noorm management operations.
+	 *
+	 * Lazily instantiated on first access. Returns the same instance
+	 * on repeated access (singleton per Context).
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.build()
+	 * await ctx.noorm.fastForward()
+	 * const tables = await ctx.noorm.listTables()
+	 * ```
+	 */
+	get noorm(): NoormOps;
+	connect(): Promise<void>;
+	disconnect(): Promise<void>;
+	/**
+	 * Execute operations within a database transaction.
+	 *
+	 * The callback receives a full Kysely Transaction instance with
+	 * query builder, `sql` template literal, and all Kysely features.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.transaction(async (trx) => {
+	 *     await trx
+	 *         .updateTable('accounts')
+	 *         .set({ balance: sql`balance - ${amount}` })
+	 *         .where('id', '=', fromId)
+	 *         .execute();
+	 *     await trx
+	 *         .updateTable('accounts')
+	 *         .set({ balance: sql`balance + ${amount}` })
+	 *         .where('id', '=', toId)
+	 *         .execute();
+	 * });
+	 * ```
+	 */
+	transaction<T>(fn: (trx: Transaction<DB>) => Promise<T>): Promise<T>;
+	/**
+	 * Call a stored procedure and return the result set.
+	 *
+	 * Generates dialect-specific SQL: EXEC (MSSQL), CALL (PG/MySQL).
+	 * Named params use dialect-appropriate syntax; MySQL falls back
+	 * to positional. SQLite throws — no procedure support.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Named params
+	 * const users = await ctx.proc<User>('get_users', { department_id: 1 });
+	 *
+	 * // Positional params
+	 * await ctx.proc('simple_proc', [42, 'hello']);
+	 *
+	 * // No params
+	 * await ctx.proc('refresh_cache');
+	 * ```
+	 */
+	proc<T = unknown, N extends keyof Procs & string = keyof Procs & string>(name: N, ...args: Procs[N] extends void ? [
+	] : [
+		params: Procs[N]
+	]): Promise<T[]>;
+	/**
+	 * Call a database function and return the scalar result.
+	 *
+	 * Generates SELECT name(...) AS column. Named params only on PG;
+	 * other dialects fall back to positional. SQLite throws.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Named params + column alias
+	 * const result = await ctx.func<{ total: number }>('calc_total', { order_id: 42 }, 'total');
+	 *
+	 * // Positional params + column alias
+	 * const sum = await ctx.func<{ result: number }>('add_numbers', [1, 2], 'result');
+	 *
+	 * // No params — just column alias
+	 * const ver = await ctx.func<{ v: string }>('get_version', 'v');
+	 * ```
+	 */
+	func<T = unknown, N extends keyof Funcs & string = keyof Funcs & string>(name: N, ...args: Funcs[N] extends void ? [
+		column: string
+	] : [
+		params: Funcs[N],
+		column: string
+	]): Promise<T>;
 }
 /**
  * Error thrown when requireTest is enabled but config.isTest is false.
@@ -2072,7 +3295,7 @@ export declare class ProtectedConfigError extends Error {
  * const ctx = await createContext()
  * ```
  */
-export declare function createContext<DB = unknown>(options?: CreateContextOptions): Promise<Context<DB>>;
+export declare function createContext<DB = unknown, Procs = object, Funcs = object>(options?: CreateContextOptions): Promise<Context<DB, Procs, Funcs>>;
 
 export {
 	Lock$1 as Lock,