@noormdev/sdk 1.0.0-alpha.2 → 1.0.0-alpha.20

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.
  *
@@ -63,10 +71,6 @@ export interface ConnectionConfig {
  *         user: 'postgres',
  *         password: 'postgres',
  *     },
- *     paths: {
- *         sql: './sql',
- *         changes: './changes',
- *     },
  * }
  * ```
  */
@@ -76,194 +80,871 @@ export interface Config {
 	isTest: boolean;
 	protected: boolean;
 	connection: ConnectionConfig;
-	paths: {
-		sql: string;
-		changes: string;
-	};
 	identity?: string;
 }
-/**
- * Settings Types
- *
- * Settings define project-wide build behavior and stage configuration.
- * Unlike encrypted configs (credentials), settings are version controlled
- * and shared across the team via .noorm/settings.yml
- */
-/**
- * Secret type hints for CLI input handling.
- *
- * - string: Plain text input
- * - password: Masked input, no echo
- * - api_key: Masked input, validated format
- * - connection_string: Validated as URI
- */
-export type SecretType = "string" | "password" | "api_key" | "connection_string";
-/**
- * Required secret definition for a stage.
- *
- * @example
- * ```yaml
- * secrets:
- *     - key: DB_PASSWORD
- *       type: password
- *       description: Database password
- *       required: true
- * ```
- */
-export interface StageSecret {
-	/** Secret key name (e.g., DB_PASSWORD) */
-	key: string;
-	/** Type hint for CLI input handling */
-	type: SecretType;
-	/** Human-readable description shown in CLI prompts */
-	description?: string;
-	/** Whether the secret is required (default: true) */
-	required?: boolean;
-}
-/**
- * Stage defaults that can be overridden when creating a config.
- *
- * These provide initial values. Some are enforceable constraints:
- * - protected: true - Cannot be overridden to false
- * - isTest: true - Cannot be overridden to false
- * - dialect - Cannot be changed after creation
- */
-export interface StageDefaults {
-	dialect?: "postgres" | "mysql" | "sqlite" | "mssql";
-	host?: string;
-	port?: number;
-	database?: string;
-	user?: string;
-	password?: string;
-	ssl?: boolean;
-	isTest?: boolean;
-	protected?: boolean;
+export type Events<Shape> = keyof Shape;
+declare namespace ObserverEngine {
+	interface EventCallback<Shape> {
+		(data: Shape, info?: {
+			event: string;
+			listener: Function;
+		} | undefined): void;
+	}
+	type RgxEmitData<Shape> = {
+		event: Events<Shape>;
+		data: Shape[Events<Shape>];
+	};
+	type Cleanup = () => void;
+	type Component<Ev extends Record<string, any>> = {
+		on: ObserverEngine<Ev>["on"];
+		once: ObserverEngine<Ev>["once"];
+		emit: ObserverEngine<Ev>["emit"];
+		off: ObserverEngine<Ev>["off"];
+	};
+	type Child<C, Ev extends Record<string, any>> = C & Component<Ev> & {
+		cleanup: Cleanup;
+		clear: Cleanup;
+	};
+	type Instance<Ev extends Record<string, any>> = Component<Ev> & {
+		observe: ObserverEngine<Ev>["observe"];
+		$observer: ObserverEngine<Ev>;
+	};
+	type FuncName = "on" | "once" | "off" | "emit" | "cleanup";
+	type SpyAction<Ev extends Record<string, any>> = {
+		event: keyof Ev | RegExp | "*";
+		listener?: Function | null | undefined;
+		data?: unknown | undefined;
+		fn: FuncName;
+		context: ObserverEngine<any>;
+	};
+	interface Spy<Ev extends Record<string, any>> {
+		(action: SpyAction<Ev>): void;
+	}
+	interface EmitValidator<Ev extends Record<string, any>> {
+		(event: keyof Ev, data: Ev[keyof Ev], context: ObserverEngine<Ev>): void;
+		(event: RegExp, data: unknown, context: ObserverEngine<Ev>): void;
+		(event: "*", data: unknown, context: ObserverEngine<Ev>): void;
+	}
+	type Options<Ev extends Record<string, any>> = {
+		name?: string | undefined;
+		spy?: Spy<Ev> | undefined;
+		emitValidator?: EmitValidator<Ev> | undefined;
+		signal?: AbortSignal | undefined;
+	};
+	type ListenerOptions = {
+		signal?: AbortSignal | undefined;
+	};
+	type ObserveOptions = {
+		signal?: AbortSignal | undefined;
+	};
+	type TransferOptions<Ev extends Record<string, any>> = {
+		filter?: (Events<Ev> | RegExp)[];
+		exclude?: (Events<Ev> | RegExp)[];
+	};
 }
 /**
- * Stage definition - a preconfigured config template.
+ * Generic function type for type-safe function signatures.
  *
- * Stages are team-defined config templates with defaults, constraints,
- * and required secrets. They're managed via version control.
+ * Enables consistent typing across utility functions and higher-order functions
+ * where function parameters need to be strongly typed.
  *
  * @example
- * ```yaml
- * stages:
- *     prod:
- *         description: Production database
- *         locked: true
- *         defaults:
- *             dialect: postgres
- *             protected: true
- *         secrets:
- *             - key: DB_PASSWORD
- *               type: password
- * ```
- */
-export interface Stage {
-	/** Human-readable description shown in CLI */
-	description?: string;
-	/** If true, configs linked to this stage cannot be deleted */
-	locked?: boolean;
-	/** Default values when creating config from this stage */
-	defaults?: StageDefaults;
-	/** Required secrets that must be set before config is usable */
-	secrets?: StageSecret[];
-}
-/**
- * Conditions for rule matching.
- *
- * All conditions in a rule are AND'd together.
- * A rule matches when ALL specified conditions are true.
+ * function memoize<A extends any[], R>(fn: Func<A, R>): Func<A, R>
+ * function debounce<A extends any[]>(fn: Func<A, void>, ms: number): Func<A, void>
  */
-export interface RuleMatch {
-	/** Config name (exact match) */
-	name?: string;
-	/** Protected config flag */
-	protected?: boolean;
-	/** Test database flag */
-	isTest?: boolean;
-	/** Connection type */
-	type?: "local" | "remote";
-}
+export type Func<A extends any[] = any[], R = any> = (...args: A) => R;
 /**
- * Stage-based rule for conditional include/exclude.
+ * Represents a value that can be either synchronous or asynchronous.
  *
- * Rules control which files/folders are included or excluded
- * based on the active config's properties.
+ * Critical for utility functions that need to handle both sync and async
+ * operations uniformly, enabling flexible API design.
  *
  * @example
- * ```yaml
- * rules:
- *     - match:
- *           isTest: true
- *       include:
- *           - sql/seeds
- *     - match:
- *           protected: true
- *       exclude:
- *           - sql/dangerous
- * ```
+ * function processData<T>(processor: () => MaybePromise<T>): Promise<T>
+ * function transform<T, U>(value: T, transformer: (val: T) => MaybePromise<U>): Promise<U>
  */
-export interface Rule {
-	/** User-friendly description (e.g., "test seeds", "prod config") */
-	description?: string;
-	/** Conditions that must all match */
-	match: RuleMatch;
-	/** Folders to include when rule matches */
-	include?: string[];
-	/** Folders to exclude when rule matches */
-	exclude?: string[];
+export type MaybePromise<T> = T | Promise<T>;
+export interface EventGeneratorOptions {
+	signal?: AbortSignal | undefined;
 }
-/**
- * Build configuration - controls file inclusion and execution order.
- */
-export interface BuildConfig {
+declare class EventGenerator<S extends Record<string, any>, E extends Events<S> | RegExp = Events<S>> {
+	cleanup: ObserverEngine.Cleanup;
+	next: () => Promise<EventData<S, E>>;
+	constructor(observer: ObserverEngine<S>, event: E | RegExp, options?: EventGeneratorOptions);
+	[Symbol.asyncIterator](): AsyncGenerator<Awaited<EventData<S, E>>, undefined, unknown>;
+	get lastValue(): E extends Events<S> ? S[E] : E extends RegExp ? ObserverEngine.RgxEmitData<S> : S[Events<S>];
+	get done(): boolean;
+	emit(data?: (E extends Events<S> ? S[E] : S[Events<S>])): void;
+}
+declare class ObserverEngine<Shape extends Record<string, any> = Record<string, any>> {
+	constructor(options?: ObserverEngine.Options<Shape>);
+	name: string;
 	/**
-	 * Folders to include, executed in this order.
-	 * First listed = first executed.
+	 * Returns facts about the the internal state of the observable instance.
 	 */
-	include?: string[];
-	/** Folders to exclude from all builds */
-	exclude?: string[];
-}
-/**
- * Path configuration - override default locations.
- */
-export interface PathConfig {
-	/** Path to SQL files (relative to project root) */
-	sql?: string;
-	/** Path to change files (relative to project root) */
-	changes?: string;
-}
-/**
- * Strict mode configuration.
- *
- * When enabled, requires certain stages to exist before operations can run.
- */
-export interface StrictConfig {
-	/** Enable strict mode */
-	enabled?: boolean;
-	/** Required stage names that must have configs */
-	stages?: string[];
-}
-/**
- * Logging configuration.
- */
-export interface LoggingConfig {
-	/** Enable file logging */
-	enabled?: boolean;
-	/** Minimum level to capture: silent, error, warn, info, verbose */
-	level?: "silent" | "error" | "warn" | "info" | "verbose";
-	/** Log file path (relative to project root) */
-	file?: string;
-	/** Rotate log when size exceeded (e.g., '10mb') */
-	maxSize?: string;
-	/** Number of rotated files to keep */
-	maxFiles?: number;
-}
-/**
- * Teardown configuration.
- *
+	$facts(): {
+		listeners: (keyof Shape)[];
+		rgxListeners: string[];
+		listenerCounts: Record<string, number>;
+		hasSpy: boolean;
+	};
+	/**
+	 * The internals of the observable instance.
+	 *
+	 * NOTE: Do not use this to try to meddle with the
+	 * internals of the observable instance. This is for
+	 * debugging purposes only.
+	 */
+	$internals(): {
+		listenerMap: Map<keyof Shape, Set<Func>>;
+		rgxListenerMap: Map<string, Set<Func>>;
+		internalListener: EventTarget;
+		name: string;
+		spy: ObserverEngine.Spy<Shape> | undefined;
+	};
+	/**
+	 * Returns if the observable instance has the given event
+	 */
+	$has(event: Events<Shape>): boolean;
+	/**
+	 * Returns if the observable instance has a regex event
+	 */
+	$has(event: RegExp): boolean;
+	/**
+	 * Returns if the observable instance has the given event
+	 */
+	$has(event: string): boolean;
+	/**
+	 * Enables or disables debugging for the observable instance.
+	 * Works in conjunction with your spy function. Provides a
+	 * stack trace of events that are triggered, listened to, and
+	 * cleaned up.
+	 *
+	 * @param on Whether to enable or disable debugging
+	 */
+	debug(on?: boolean): void;
+	/**
+	 * Sets the spy function for the observable instance.
+	 * @param spy The spy function to set
+	 * @param force Whether to force the spy function to be set even if one is already set
+	 */
+	spy(spy: ObserverEngine.Spy<Shape>, force?: boolean): void;
+	/**
+	 * Observes given component as an extension of this observable instance.
+	 * @param component Component to wrap events around
+	 * @param options Optional configuration including signal for cleanup
+	 *
+	 * @example
+	 *
+	 * const obs = new ObserverEngine();
+	 *
+	 * const modal = {};
+	 *
+	 * obs.observe(modal);
+	 *
+	 * modal.on('modal-open', () => {});
+	 *
+	 * obs.trigger('modal-open'); // opens modal
+	 * modal.trigger('modal-open'); // opens modal
+	 *
+	 * modal.cleanup(); // clears all event listeners
+	 */
+	observe<C>(component: C, options?: ObserverEngine.ObserveOptions): ObserverEngine.Child<C, Shape>;
+	/**
+	 * Returns an event generator that will listen for the specified event
+	 *
+	 * @example
+	 *
+	 * const obs = new ObserverEngine();
+	 *
+	 * const something = obs.on('something');
+	 * const data = await something.next(); // waits for next event
+	 * something.emit('special'); // emits data to listeners
+	 *
+	 * something.cleanup(); // stops listening for events
+	 */
+	on<E extends Events<Shape>>(event: E, options?: ObserverEngine.ListenerOptions): EventGenerator<Shape, E>;
+	on<E extends string>(event: E, options?: ObserverEngine.ListenerOptions): EventGenerator<Record<E, any>>;
+	/**
+	 * Listens for the specified event and executes the given callback
+	 *
+	 * @example
+	 *
+	 * const obs = new ObserverEngine();
+	 *
+	 * obs.on('something', (data) => {
+	 *    console.log(data);
+	 * });
+	 */
+	on<E extends Events<Shape>>(event: E, listener: ObserverEngine.EventCallback<Shape[E]>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	on<E extends string>(event: E, listener: ObserverEngine.EventCallback<Record<E, any>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	/**
+	 * Returns an event generator that will listen for all events matching the regex
+	 *
+	 * @example
+	 *
+	 * const obs = new ObserverEngine();
+	 *
+	 * const onEvent = obs.on(/some/);
+	 * const { event, data } = await onEvent.next(); // waits for next event
+	 * onEvent.emit('something'); // emits data to listeners
+	 *
+	 * onEvent.cleanup(); // stops listening for events
+	 */
+	on(event: RegExp, options?: ObserverEngine.ListenerOptions): EventGenerator<Shape, RegExp>;
+	/**
+	 * Listens for all events matching the regex and executes the given callback
+	 *
+	 * @example
+	 *
+	 * const obs = new ObserverEngine();
+	 *
+	 * obs.on(/some/, ({ event, data }) => {
+	 *     console.log(event, data);
+	 * });
+	 */
+	on(event: RegExp, listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	/**
+	 * Returns an event promise that resolves when
+	 * the specified event is emitted
+	 */
+	once<E extends Events<Shape>>(event: E, options?: ObserverEngine.ListenerOptions): EventPromise<Shape[E]>;
+	/**
+	 * Returns an event promise that resolves when
+	 * the specified event is emitted. This overload
+	 * is untyped and can be used to listen for any
+	 * event that is emitted.
+	 */
+	once<E extends string>(event: E, options?: ObserverEngine.ListenerOptions): EventPromise<Record<E, any>>;
+	/**
+	 * Executes a callback once when the specified
+	 * event is emitted
+	 */
+	once<E extends Events<Shape>>(event: E, listener: ObserverEngine.EventCallback<Shape[E]>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	/**
+	 * Executes a callback once when the specified
+	 * event is emitted. This overload is untyped
+	 * and can be used to listen for any event that
+	 * is emitted.
+	 */
+	once<E extends string>(event: E, listener: ObserverEngine.EventCallback<Record<E, any>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	/**
+	 * Returns an event promise that resolves when
+	 * any events matching the regex are emitted
+	 */
+	once(event: RegExp, options?: ObserverEngine.ListenerOptions): EventPromise<ObserverEngine.RgxEmitData<Shape>>;
+	/**
+	 * Executes a callback once when any events
+	 * matching the regex are emitted
+	 */
+	once(event: RegExp, listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	/**
+	 * Stop listening for an event
+	 * @param event
+	 * @param listener
+	 */
+	off(event: Events<Shape> | RegExp | string, listener?: Function): void;
+	/** Emits an event */
+	emit<E extends Events<Shape> | RegExp | string>(event: E, data?: E extends Events<Shape> ? Shape[E] : E extends string ? Record<E, any>[E] : unknown): void;
+	clear(): void;
+	queue<E extends Events<Shape> | RegExp>(event: E, process: (data: EventData<Shape, E>) => MaybePromise<any>, options: QueueOpts): EventQueue<Shape, E>;
+	/**
+	 * Transfers all matching listeners from source to target, removing
+	 * them from the source. Target's existing listeners are preserved.
+	 *
+	 * Useful when cloning an engine (e.g. FetchEngine) and carrying
+	 * over observability listeners to the new instance.
+	 *
+	 * @example
+	 *
+	 *     const old = new ObserverEngine();
+	 *     const next = new ObserverEngine();
+	 *
+	 *     old.on('ready', handler);
+	 *
+	 *     ObserverEngine.transfer(old, next);
+	 *     // `next` now owns the 'ready' listener; `old` has none
+	 *
+	 * @example
+	 *
+	 *     // Transfer only specific events
+	 *     ObserverEngine.transfer(old, next, {
+	 *         filter: ['ready', /^user\./]
+	 *     });
+	 */
+	static transfer<Shape extends Record<string, any>>(source: ObserverEngine<Shape>, target: ObserverEngine<Shape>, options?: ObserverEngine.TransferOptions<Shape>): void;
+	/**
+	 * Copies all matching listeners from source to target without
+	 * removing them from the source. Target's existing listeners
+	 * are preserved.
+	 *
+	 * Useful when forking an engine so both instances react to the
+	 * same events independently.
+	 *
+	 * @example
+	 *
+	 *     const primary = new ObserverEngine();
+	 *     const mirror = new ObserverEngine();
+	 *
+	 *     primary.on('update', handler);
+	 *
+	 *     ObserverEngine.copy(primary, mirror);
+	 *     // Both engines now have the 'update' listener
+	 *
+	 * @example
+	 *
+	 *     // Copy everything except internal events
+	 *     ObserverEngine.copy(primary, mirror, {
+	 *         exclude: [/^__/]
+	 *     });
+	 */
+	static copy<Shape extends Record<string, any>>(source: ObserverEngine<Shape>, target: ObserverEngine<Shape>, options?: ObserverEngine.TransferOptions<Shape>): void;
+}
+export type EventData<S, E extends Events<S> | RegExp = Events<S>> = (E extends Events<S> ? S[E] : E extends RegExp ? ObserverEngine.RgxEmitData<S> : S[Events<S>]);
+declare class EventPromise<T> extends Promise<T> {
+	cleanup?: () => void;
+	reject?: (err: Error | string) => void;
+	resolve?: (value: T) => void;
+}
+declare class InternalQueueEvent<T = unknown> {
+	readonly data: T;
+	constructor(data: T);
+}
+declare enum QueueRejectionReason {
+	full = "Queue is full",
+	notRunning = "Queue is not running"
+}
+export type QueueEventData<S, E extends Events<S> | RegExp = Events<S>> = {
+	data?: EventData<S, E>;
+	_taskId?: string;
+	priority?: number;
+	reason?: QueueRejectionReason;
+	startedAt?: number;
+	rateLimited?: boolean;
+	elapsed?: number;
+	error?: Error;
+	force?: boolean;
+	pending?: number;
+	flushed?: number;
+	drained?: number;
+	count?: number;
+};
+export type QueueEvents<S extends Record<string, any>, E extends Events<S> | RegExp = Events<S>> = {
+	added: QueueEventData<S, E>;
+	start: void;
+	started: void;
+	stopped: void;
+	processing: QueueEventData<S, E> & {
+		startedAt: number;
+		rateLimited: boolean;
+	};
+	success: QueueEventData<S, E> & {
+		startedAt: number;
+		elapsed: number;
+		rateLimited: boolean;
+	};
+	error: QueueEventData<S, E> & {
+		error: Error;
+		rateLimited: boolean;
+	};
+	timeout: QueueEventData<S, E> & {
+		error: Error;
+		rateLimited: boolean;
+	};
+	rejected: QueueEventData<S, E> & {
+		reason: QueueRejectionReason;
+	};
+	"rate-limited": QueueEventData<S, E> & {
+		rateLimited: boolean;
+	};
+	empty: void;
+	idle: void;
+	drain: {
+		pending: number;
+	};
+	drained: {
+		pending?: number;
+		drained?: number;
+	};
+	flush: {
+		pending: number;
+	};
+	flushed: {
+		flushed: number;
+	};
+	paused: void;
+	resumed: void;
+	cleanup: void;
+	purged: {
+		count: number;
+	};
+	shutdown: {
+		force: boolean;
+		pending?: number;
+	};
+};
+declare enum QueueState {
+	running = "running",
+	paused = "paused",
+	stopped = "stopped",
+	draining = "draining"
+}
+/**
+ * The options for the queue
+ */
+export interface QueueOpts {
+	/**
+	 * The name of the queue
+	 */
+	name: string;
+	/**
+	 * The type of queue to use
+	 *
+	 * @default 'fifo'
+	 */
+	type?: "fifo" | "lifo";
+	/**
+	 * The concurrency of the queue
+	 *
+	 * @default 1
+	 */
+	concurrency?: number;
+	/**
+	 * The poll interval in milliseconds before the queue will
+	 * check for new items after idle.
+	 *
+	 * @default 100
+	 */
+	pollIntervalMs?: number;
+	/**
+	 * The jitter percentage to displace
+	 * the next process time. This stops all concurrent
+	 * processes from happening at the same time.
+	 *
+	 * @range [0, 1]
+	 * @default 1
+	 */
+	jitterFactor?: number;
+	/**
+	 * The interval in milliseconds before picking up the next item
+	 *
+	 * @note If the interval is 0, the queue will not wait between items
+	 *
+	 * @default 0
+	 */
+	processIntervalMs?: number;
+	/**
+	 * The timeout in milliseconds before the task is considered timed out
+	 *
+	 * @note If the timeout is 0, the task will not be considered timed out
+	 *
+	 * @default 0
+	 */
+	taskTimeoutMs?: number;
+	/**
+	 * The maximum size of the queue
+	 *
+	 * @default 999_999_999
+	 */
+	maxQueueSize?: number;
+	/**
+	 * The rate limit of the queue in items per window
+	 *
+	 * @default 999_999_999
+	 */
+	rateLimitCapacity?: number;
+	/**
+	 * The rate limit window in milliseconds
+	 *
+	 * @default 1000
+	 */
+	rateLimitIntervalMs?: number;
+	/**
+	 * Automatically start the queue
+	 *
+	 * @default true
+	 */
+	autoStart?: boolean;
+	/**
+	 * Whether to enable debug mode. Can be set to 'info' or 'verbose' to
+	 * get more detailed output.
+	 *
+	 * @default false
+	 */
+	debug?: boolean | "info" | "verbose";
+}
+declare class EventQueue<S extends Record<string, any>, E extends Events<S> | RegExp = Events<S>> {
+	private opts;
+	constructor(opts: QueueOpts & {
+		event: E | RegExp;
+		process: (data: EventData<S, E>) => Promise<void>;
+		observer?: ObserverEngine<S>;
+	});
+	/**
+	 * Start the queue if it is not already started
+	 */
+	start(): Promise<void> | undefined;
+	/**
+	 * Stop the queue
+	 */
+	stop(): void;
+	/**
+	 * Pause the queue
+	 */
+	pause(): Promise<void> | undefined;
+	/**
+	 * Resume the queue
+	 */
+	resume(): Promise<void> | undefined;
+	/**
+	 * Empty and process all items in the queue and
+	 * then stop the queue. Returns the number of items
+	 * processed.
+	 */
+	shutdown(force?: boolean): Promise<number>;
+	/**
+	 * Executes `limit` items in the queue
+	 * and then emits a `flush` event. Returns the number
+	 * of items processed.
+	 */
+	flush(limit?: number): Promise<number>;
+	/**
+	 * Clears the queue and emits a `purge` event. Returns
+	 * the number of items purged.
+	 */
+	purge(): number;
+	/**
+	 * Emit an event to the observer, which then gets
+	 * picked up by the queue and processed.
+	 *
+	 * @param data The data to add to the queue
+	 * @param priority The priority of the data
+	 *
+	 * @note If priority is provided, it will be used to determine the order of the data in the queue.
+	 *       The higher the priority, the sooner the data will be processed.
+	 *
+	 * @note If priority is not provided, the data will be added to the queue with a priority of 0.
+	 */
+	add(data: EventData<S, E>, priority?: number): boolean;
+	debug(on?: boolean | "info" | "verbose"): void;
+	on<K extends keyof QueueEvents<S, E>>(event: K, listener: ((payload: InternalQueueEvent<QueueEvents<S, E>[K]>) => void)): ObserverEngine.Cleanup;
+	on<K extends keyof QueueEvents<S, E>>(event: K): EventGenerator<QueueEvents<S, E>, K>;
+	once<K extends keyof QueueEvents<S, E>>(event: K): EventPromise<InternalQueueEvent<QueueEvents<S, E>[K]>>;
+	once<K extends keyof QueueEvents<S, E>>(event: K, listener: ((payload: InternalQueueEvent<QueueEvents<S, E>[K]>) => void)): ObserverEngine.Cleanup;
+	off<K extends keyof QueueEvents<S, E>>(event: K, listener?: Function): void;
+	/**
+	 * The name of the queue
+	 */
+	get name(): string;
+	/**
+	 * Whether the queue is waiting for the
+	 * the
+	 */
+	get isWaiting(): boolean;
+	/**
+	 * Whether the queue is idle
+	 */
+	get isIdle(): boolean;
+	/**
+	 * Whether the queue is running
+	 */
+	get isRunning(): boolean;
+	/**
+	 * Whether the queue is paused
+	 */
+	get isPaused(): boolean;
+	/**
+	 * Whether the queue is stopped
+	 */
+	get isStopped(): boolean;
+	/**
+	 * Whether the queue is draining
+	 */
+	get isDraining(): boolean;
+	/**
+	 * The current state of the queue
+	 */
+	get state(): QueueState;
+	/**
+	 * The number of items in the queue
+	 */
+	get pending(): number;
+	/**
+	 * The stats of the queue
+	 */
+	get stats(): {
+		processed: number;
+		processing: number;
+		avgProcessingTime: number;
+		success: number;
+		error: number;
+		rejected: number;
+	};
+	get snapshot(): {
+		name: string;
+		state: QueueState;
+		pending: number;
+		stats: {
+			processed: number;
+			processing: number;
+			avgProcessingTime: number;
+			success: number;
+			error: number;
+			rejected: number;
+		};
+		rateLimiter: {
+			currentTokens: number;
+			capacity: number;
+			refillIntervalMs: number;
+			totalRequests: number;
+			rejectedRequests: number;
+			successfulRequests: number;
+			rejectionRate: number;
+			totalWaitTime: number;
+			waitCount: number;
+			averageWaitTime: number;
+			uptime: number;
+			createdAt: number;
+		};
+		activeRunners: number;
+		runningNodes: Set<`${number}-${number}`>;
+		isIdle: boolean;
+		isWaiting: boolean;
+		isRunning: boolean;
+		isPaused: boolean;
+		isStopped: boolean;
+		isDraining: boolean;
+		isEmpty: boolean;
+	};
+}
+/**
+ * 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[];
+}
+/**
+ * Settings Types
+ *
+ * Settings define project-wide build behavior and stage configuration.
+ * Unlike encrypted configs (credentials), settings are version controlled
+ * and shared across the team via .noorm/settings.yml
+ */
+/**
+ * Secret type hints for CLI input handling.
+ *
+ * - string: Plain text input
+ * - password: Masked input, no echo
+ * - api_key: Masked input, validated format
+ * - connection_string: Validated as URI
+ */
+export type SecretType = "string" | "password" | "api_key" | "connection_string";
+/**
+ * Required secret definition for a stage.
+ *
+ * @example
+ * ```yaml
+ * secrets:
+ *     - key: DB_PASSWORD
+ *       type: password
+ *       description: Database password
+ *       required: true
+ * ```
+ */
+export interface StageSecret {
+	/** Secret key name (e.g., DB_PASSWORD) */
+	key: string;
+	/** Type hint for CLI input handling */
+	type: SecretType;
+	/** Human-readable description shown in CLI prompts */
+	description?: string;
+	/** Whether the secret is required (default: true) */
+	required?: boolean;
+}
+/**
+ * Stage defaults that can be overridden when creating a config.
+ *
+ * These provide initial values. Some are enforceable constraints:
+ * - protected: true - Cannot be overridden to false
+ * - isTest: true - Cannot be overridden to false
+ * - dialect - Cannot be changed after creation
+ */
+export interface StageDefaults {
+	dialect?: "postgres" | "mysql" | "sqlite" | "mssql";
+	host?: string;
+	port?: number;
+	database?: string;
+	user?: string;
+	password?: string;
+	ssl?: boolean;
+	isTest?: boolean;
+	protected?: boolean;
+}
+/**
+ * Stage definition - a preconfigured config template.
+ *
+ * Stages are team-defined config templates with defaults, constraints,
+ * and required secrets. They're managed via version control.
+ *
+ * @example
+ * ```yaml
+ * stages:
+ *     prod:
+ *         description: Production database
+ *         locked: true
+ *         defaults:
+ *             dialect: postgres
+ *             protected: true
+ *         secrets:
+ *             - key: DB_PASSWORD
+ *               type: password
+ * ```
+ */
+export interface Stage {
+	/** Human-readable description shown in CLI */
+	description?: string;
+	/** If true, configs linked to this stage cannot be deleted */
+	locked?: boolean;
+	/** Default values when creating config from this stage */
+	defaults?: StageDefaults;
+	/** Required secrets that must be set before config is usable */
+	secrets?: StageSecret[];
+}
+/**
+ * Conditions for rule matching.
+ *
+ * All conditions in a rule are AND'd together.
+ * A rule matches when ALL specified conditions are true.
+ */
+export interface RuleMatch {
+	/** Config name (exact match) */
+	name?: string;
+	/** Protected config flag */
+	protected?: boolean;
+	/** Test database flag */
+	isTest?: boolean;
+	/** Connection type */
+	type?: "local" | "remote";
+}
+/**
+ * Stage-based rule for conditional include/exclude.
+ *
+ * Rules control which files/folders are included or excluded
+ * based on the active config's properties.
+ *
+ * @example
+ * ```yaml
+ * rules:
+ *     - match:
+ *           isTest: true
+ *       include:
+ *           - sql/seeds
+ *     - match:
+ *           protected: true
+ *       exclude:
+ *           - sql/dangerous
+ * ```
+ */
+export interface Rule {
+	/** User-friendly description (e.g., "test seeds", "prod config") */
+	description?: string;
+	/** Conditions that must all match */
+	match: RuleMatch;
+	/** Folders to include when rule matches */
+	include?: string[];
+	/** Folders to exclude when rule matches */
+	exclude?: string[];
+}
+/**
+ * Build configuration - controls file inclusion and execution order.
+ */
+export interface BuildConfig {
+	/**
+	 * Folders to include, executed in this order.
+	 * First listed = first executed.
+	 */
+	include?: string[];
+	/** Folders to exclude from all builds */
+	exclude?: string[];
+}
+/**
+ * Path configuration - override default locations.
+ */
+export interface PathConfig {
+	/** Path to SQL files (relative to project root) */
+	sql?: string;
+	/** Path to change files (relative to project root) */
+	changes?: string;
+}
+/**
+ * Strict mode configuration.
+ *
+ * When enabled, requires certain stages to exist before operations can run.
+ */
+export interface StrictConfig {
+	/** Enable strict mode */
+	enabled?: boolean;
+	/** Required stage names that must have configs */
+	stages?: string[];
+}
+/**
+ * Logging configuration.
+ */
+export interface LoggingConfig {
+	/** Enable file logging */
+	enabled?: boolean;
+	/** Minimum level to capture: silent, error, warn, info, verbose */
+	level?: "silent" | "error" | "warn" | "info" | "verbose";
+	/** Log file path (relative to project root) */
+	file?: string;
+	/** Rotate log when size exceeded (e.g., '10mb') */
+	maxSize?: string;
+	/** Number of rotated files to keep */
+	maxFiles?: number;
+}
+/**
+ * Teardown configuration.
+ *
  * Controls database reset and teardown behavior.
  *
  * @example
@@ -378,37 +1059,26 @@ export interface SettingsEvents {
 	};
 }
 /**
- * Identity types.
- *
- * Two types of identity in noorm:
- * 1. Audit Identity - Simple name/email for tracking "who executed this"
- * 2. Cryptographic Identity - Full keypair system for config sharing and team discovery
- */
-/**
- * Source of audit identity resolution.
- */
-export type IdentitySource = "state" | "config" | "env" | "git" | "system";
-/**
- * Resolved audit identity.
- *
- * Used for tracking "who" executed a change or SQL file.
- *
- * @example
- * ```typescript
- * const identity: Identity = {
- *     name: 'John Doe',
- *     email: 'john@example.com',
- *     source: 'git',
- * }
- * ```
- */
-export interface Identity {
-	/** User's name */
-	name: string;
-	/** User's email (optional) */
-	email?: string;
-	/** How the identity was resolved */
-	source: IdentitySource;
+ * 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.
@@ -421,220 +1091,224 @@ export interface Identity {
  */
 export type OperationStatus = "pending" | "success" | "failed" | "reverted" | "stale";
 /**
- * Direction values.
- */
-export type Direction = "change" | "revert";
-/**
- * File execution status values.
+ * Change type values.
  */
-export type ExecutionStatus = "pending" | "success" | "failed" | "skipped";
+export type ChangeType = "build" | "run" | "change";
 /**
- * Overview counts for all categories.
+ * Direction values.
  */
-export interface ExploreOverview {
-	tables: number;
-	views: number;
-	procedures: number;
-	functions: number;
-	types: number;
-	indexes: number;
-	foreignKeys: number;
-	triggers: number;
-	locks: number;
-	connections: number;
-}
+export type Direction = "change" | "revert";
 /**
- * Table summary for list display.
+ * Change tracking table.
+ *
+ * Tracks all operation batches—changes, builds, and ad-hoc runs.
+ * See: plan/datamodel.md#__noorm_change__
  */
-export interface TableSummary {
+export interface NoormChangeTable {
+	/** Primary key */
+	id: Generated<number>;
+	/** Operation identifier */
 	name: string;
-	schema?: string;
-	columnCount: number;
-	rowCountEstimate?: number;
+	/** '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>;
 }
 /**
- * Index summary for list display.
+ * File execution status values.
  */
-export interface IndexSummary {
-	name: string;
-	schema?: string;
-	tableName: string;
-	tableSchema?: string;
-	columns: string[];
-	isUnique: boolean;
-	isPrimary: boolean;
-}
+export type ExecutionStatus = "pending" | "success" | "failed" | "skipped";
 /**
- * Foreign key summary for list display.
+ * File type values.
  */
-export interface ForeignKeySummary {
-	name: string;
-	schema?: string;
-	tableName: string;
-	tableSchema?: string;
-	columns: string[];
-	referencedTable: string;
-	referencedSchema?: string;
-	referencedColumns: string[];
-	onDelete?: string;
-	onUpdate?: string;
-}
+export type FileType = "sql" | "txt";
 /**
- * Column detail for tables/views.
+ * Executions tracking table.
+ *
+ * Tracks individual file executions within an operation.
+ * See: plan/datamodel.md#__noorm_executions__
  */
-export interface ColumnDetail {
-	name: string;
-	dataType: string;
-	isNullable: boolean;
-	defaultValue?: string;
-	isPrimaryKey: boolean;
-	ordinalPosition: number;
+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>;
 }
 /**
- * Full table detail.
+ * Lock table.
+ *
+ * Prevents concurrent operations on the same database.
+ * See: plan/datamodel.md#__noorm_lock__
  */
-export interface TableDetail {
-	name: string;
-	schema?: string;
-	columns: ColumnDetail[];
-	indexes: IndexSummary[];
-	foreignKeys: ForeignKeySummary[];
-	rowCountEstimate?: number;
+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>;
 }
 /**
- * Result of a truncate operation.
+ * 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 TruncateResult {
-	/** Tables that were truncated */
-	truncated: string[];
-	/** Tables that were preserved */
-	preserved: string[];
-	/** SQL statements executed (or would execute in dry-run) */
-	statements: string[];
-	/** Duration in milliseconds */
-	durationMs: number;
+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;
 }
 /**
- * Result of a teardown operation.
- */
-export interface TeardownResult {
-	/** Objects dropped by category */
-	dropped: {
-		tables: string[];
-		views: string[];
-		functions: string[];
-		procedures: string[];
-		types: string[];
-		foreignKeys: string[];
-	};
-	/** Objects preserved */
-	preserved: string[];
-	/** SQL statements executed (or would execute in dry-run) */
-	statements: string[];
-	/** Duration in milliseconds */
-	durationMs: number;
-	/** Post-script execution result (if any) */
-	postScriptResult?: {
-		executed: boolean;
-		error?: string;
-	};
-	/** Number of changes marked as stale (if configName provided) */
-	staleCount?: number;
-	/** ID of the reset record created (if configName provided) */
-	resetRecordId?: number;
+ * 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>;
 }
 /**
- * Options for running SQL files.
+ * Schema-qualified database interface for pg/mssql.
  *
- * @example
- * ```typescript
- * const options: RunOptions = {
- *     force: true,        // Re-run even if unchanged
- *     abortOnError: false // Continue on failures
- * }
- * ```
+ * Used with db.withSchema('noorm') — table names have no prefix.
  */
-export interface RunOptions {
-	/** Re-run files even if unchanged. Default: false */
-	force?: boolean;
-	/** Number of files to run in parallel. Default: 1 (sequential for DDL safety) */
-	concurrency?: number;
-	/** Stop execution on first failure. Default: true */
-	abortOnError?: boolean;
-	/** Report what would run without executing. Default: false */
-	dryRun?: boolean;
-	/** Output rendered SQL without executing. Default: false */
-	preview?: boolean;
-	/** Write preview output to file instead of stdout. Default: null */
-	output?: string | null;
+export interface NoormSchemaDb {
+	version: NoormVersionTable;
+	change: NoormChangeTable;
+	executions: NoormExecutionsTable;
+	lock: NoormLockTable;
+	identities: NoormIdentitiesTable;
+	vault: NoormVaultTable;
 }
 /**
- * Why a file was skipped.
+ * Prefixed database interface for sqlite/mysql.
+ *
+ * Used directly — table names have __noorm_ prefix.
  */
-export type SkipReason = "unchanged" | "already-run";
+export interface NoormPrefixDb {
+	__noorm_version__: NoormVersionTable;
+	__noorm_change__: NoormChangeTable;
+	__noorm_executions__: NoormExecutionsTable;
+	__noorm_lock__: NoormLockTable;
+	__noorm_identities__: NoormIdentitiesTable;
+	__noorm_vault__: NoormVaultTable;
+}
 /**
- * Result of executing a single file.
+ * Combined database interface for all noorm tracking tables.
+ *
+ * Intersection of schema-qualified (pg/mssql) and prefixed (sqlite/mysql)
+ * interfaces. Both key sets are valid — use getNoormTables(dialect) to get
+ * the correct keys for your dialect.
  *
  * @example
  * ```typescript
- * const result: FileResult = {
- *     filepath: '/project/sql/001.sql',
- *     checksum: 'abc123...',
- *     status: 'success',
- *     durationMs: 42,
- * }
+ * const tables = getNoormTables(dialect);
+ * const ndb = noormDb(db, dialect);
+ * await ndb.selectFrom(tables.change).selectAll().execute();
  * ```
  */
-export interface FileResult {
-	/** Absolute path to the file */
-	filepath: string;
-	/** SHA-256 hash of file contents */
-	checksum: string;
-	/** Execution status */
-	status: ExecutionStatus;
-	/** Why the file was skipped (only when status is 'skipped') */
-	skipReason?: SkipReason;
-	/** Execution time in milliseconds */
-	durationMs?: number;
-	/** Error message if failed */
-	error?: string;
-	/** Rendered SQL (only in preview mode) */
-	renderedSql?: string;
-}
+export type NoormDatabase = NoormSchemaDb & NoormPrefixDb;
 /**
- * Overall status of a batch operation.
+ * Identity types.
+ *
+ * Two types of identity in noorm:
+ * 1. Audit Identity - Simple name/email for tracking "who executed this"
+ * 2. Cryptographic Identity - Full keypair system for config sharing and team discovery
  */
-export type BatchStatus = "success" | "failed" | "partial";
 /**
- * Result of a batch operation (build, dir).
+ * Source of audit identity resolution.
+ */
+export type IdentitySource = "state" | "config" | "env" | "git" | "system";
+/**
+ * Resolved audit identity.
+ *
+ * Used for tracking "who" executed a change or SQL file.
  *
  * @example
  * ```typescript
- * const result: BatchResult = {
- *     status: 'success',
- *     files: [...],
- *     filesRun: 5,
- *     filesSkipped: 2,
- *     filesFailed: 0,
- *     durationMs: 1234,
+ * const identity: Identity = {
+ *     name: 'John Doe',
+ *     email: 'john@example.com',
+ *     source: 'git',
  * }
  * ```
  */
-export interface BatchResult {
-	/** Overall status */
-	status: BatchStatus;
-	/** Results for each file */
-	files: FileResult[];
-	/** Number of files executed */
-	filesRun: number;
-	/** Number of files skipped */
-	filesSkipped: number;
-	/** Number of files that failed */
-	filesFailed: number;
-	/** Total execution time in milliseconds */
-	durationMs: number;
-	/** Change ID in tracking table */
-	changeId?: number;
+export interface Identity {
+	/** User's name */
+	name: string;
+	/** User's email (optional) */
+	email?: string;
+	/** How the identity was resolved */
+	source: IdentitySource;
 }
 /**
  * File extension type in changes.
@@ -669,6 +1343,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 +1453,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.
  *
@@ -830,174 +1582,290 @@ export interface ChangeHistoryRecord {
 	/** Duration in milliseconds */
 	durationMs: number;
 	/** Error message if failed */
-	errorMessage: string | null;
-	/** Checksum of files */
-	checksum: string;
+	errorMessage: string | null;
+	/** 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;
+}
+/**
+ * Options for creating a new change.
+ */
+export interface CreateChangeOptions {
+	/** Description for the change name */
+	description: string;
+	/** Optional date (defaults to today) */
+	date?: Date;
+}
+/**
+ * Options for adding a file to a change.
+ */
+export interface AddFileOptions {
+	/** Descriptive name for the file */
+	name: string;
+	/** File type */
+	type: ChangeFileType;
+	/** For 'txt' type, the paths to include */
+	paths?: string[];
+	/** Initial content (optional) */
+	content?: string;
+}
+/**
+ * Error when change structure is invalid.
+ */
+export declare class ChangeValidationError extends Error {
+	readonly changeName: string;
+	readonly issue: string;
+	readonly name: "ChangeValidationError";
+	constructor(changeName: string, issue: string);
+}
+/**
+ * Error when change is not found.
+ */
+export declare class ChangeNotFoundError extends Error {
+	readonly changeName: string;
+	readonly name: "ChangeNotFoundError";
+	constructor(changeName: string);
+}
+/**
+ * Error when change is already applied.
+ */
+export declare class ChangeAlreadyAppliedError extends Error {
+	readonly changeName: string;
+	readonly appliedAt: Date;
+	readonly name: "ChangeAlreadyAppliedError";
+	constructor(changeName: string, appliedAt: Date);
+}
+/**
+ * Error when trying to revert an unapplied change.
+ */
+export declare class ChangeNotAppliedError extends Error {
+	readonly changeName: string;
+	readonly name: "ChangeNotAppliedError";
+	constructor(changeName: string);
+}
+/**
+ * Error when change is orphaned (in DB but not on disk).
+ */
+export declare class ChangeOrphanedError extends Error {
+	readonly changeName: string;
+	readonly name: "ChangeOrphanedError";
+	constructor(changeName: string);
+}
+/**
+ * Error when .txt manifest has invalid references.
+ */
+export declare class ManifestReferenceError extends Error {
+	readonly manifestPath: string;
+	readonly missingPath: string;
+	readonly name: "ManifestReferenceError";
+	constructor(manifestPath: string, missingPath: string);
+}
+/**
+ * Options for running SQL files.
+ *
+ * @example
+ * ```typescript
+ * const options: RunOptions = {
+ *     force: true,        // Re-run even if unchanged
+ *     abortOnError: false // Continue on failures
+ * }
+ * ```
+ */
+export interface RunOptions {
+	/** Re-run files even if unchanged. Default: false */
+	force?: boolean;
+	/** Number of files to run in parallel. Default: 1 (sequential for DDL safety) */
+	concurrency?: number;
+	/** Stop execution on first failure. Default: true */
+	abortOnError?: boolean;
+	/** Report what would run without executing. Default: false */
+	dryRun?: boolean;
+	/** Output rendered SQL without executing. Default: false */
+	preview?: boolean;
+	/** Write preview output to file instead of stdout. Default: null */
+	output?: string | null;
+}
+/**
+ * Why a file was skipped.
+ */
+export type SkipReason = "unchanged" | "already-run";
+/**
+ * Result of executing a single file.
+ *
+ * @example
+ * ```typescript
+ * const result: FileResult = {
+ *     filepath: '/project/sql/001.sql',
+ *     checksum: 'abc123...',
+ *     status: 'success',
+ *     durationMs: 42,
+ * }
+ * ```
+ */
+export interface FileResult {
+	/** Absolute path to the file */
+	filepath: string;
+	/** SHA-256 hash of file contents */
+	checksum: string;
+	/** Execution status */
+	status: ExecutionStatus;
+	/** Why the file was skipped (only when status is 'skipped') */
+	skipReason?: SkipReason;
+	/** Execution time in milliseconds */
+	durationMs?: number;
+	/** Error message if failed */
+	error?: string;
+	/** Rendered SQL (only in preview mode) */
+	renderedSql?: string;
 }
 /**
- * Lock manager types.
- *
- * Defines the shape of locks and options for acquiring them.
- * Used to prevent concurrent operations on the same database.
- *
- * WHY: Concurrent DDL operations can corrupt database state.
- * Locks ensure only one process modifies the schema at a time.
- */
-/**
- * Lock state returned after acquisition.
- *
- * @example
- * ```typescript
- * const lock = await lockManager.acquire('dev', 'alice@example.com')
- * console.log(lock.lockedBy)   // 'alice@example.com'
- * console.log(lock.expiresAt)  // Date object
- * ```
+ * Overall status of a batch operation.
  */
-interface Lock$1 {
-	/** Identity string of holder */
-	lockedBy: string;
-	/** When acquired */
-	lockedAt: Date;
-	/** Auto-expiry time */
-	expiresAt: Date;
-	/** Optional reason for acquiring */
-	reason?: string;
-}
+export type BatchStatus = "success" | "failed" | "partial";
 /**
- * Options for acquiring a lock.
+ * Result of a batch operation (build, dir).
  *
  * @example
  * ```typescript
- * // Wait up to 30s for lock, polling every 500ms
- * const options: LockOptions = {
- *     timeout: 60_000,        // Lock expires after 60s
- *     wait: true,             // Block until available
- *     waitTimeout: 30_000,    // Max wait time
- *     pollInterval: 500,      // Check every 500ms
- *     reason: 'Running migrations',
+ * const result: BatchResult = {
+ *     status: 'success',
+ *     files: [...],
+ *     filesRun: 5,
+ *     filesSkipped: 2,
+ *     filesFailed: 0,
+ *     durationMs: 1234,
  * }
  * ```
  */
-interface LockOptions$1 {
+export interface BatchResult {
+	/** Overall status */
+	status: BatchStatus;
+	/** Results for each file */
+	files: FileResult[];
+	/** Number of files executed */
+	filesRun: number;
+	/** Number of files skipped */
+	filesSkipped: number;
+	/** Number of files that failed */
+	filesFailed: number;
+	/** Total execution time in milliseconds */
+	durationMs: number;
+	/** Change ID in tracking table */
+	changeId?: number;
+	/** Error message when batch fails before file execution (e.g. tracking setup failure) */
+	error?: string;
+}
+declare class ChangeManager {
+	#private;
+	constructor(context: ChangeContext);
 	/**
-	 * Database dialect for date formatting.
+	 * List all changes with status.
 	 *
-	 * SQLite stores dates as ISO strings, other dialects can use Date objects.
-	 * @default 'postgres'
+	 * Merges changes from disk with status from database.
+	 * Includes orphaned changes (in DB but not on disk).
+	 *
+	 * @returns Array of changes with merged status
 	 */
-	dialect?: "postgres" | "mysql" | "sqlite" | "mssql";
+	list(): Promise<ChangeListItem[]>;
 	/**
-	 * Lock duration in milliseconds.
+	 * Run a specific change by name.
 	 *
-	 * After this time, the lock expires and can be claimed by others.
-	 * @default 300_000 (5 minutes)
+	 * @param name - Change name
+	 * @param options - Execution options
+	 * @returns Execution result
 	 */
-	timeout?: number;
+	run(name: string, options?: ChangeOptions): Promise<ChangeResult>;
 	/**
-	 * Block until lock is available?
+	 * Run a change object directly.
+	 */
+	runChange(change: Change, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Revert a specific change by name.
 	 *
-	 * If true, will poll until the lock is acquired or waitTimeout is reached.
-	 * @default false
+	 * @param name - Change name
+	 * @param options - Execution options
+	 * @returns Execution result
 	 */
-	wait?: boolean;
+	revert(name: string, options?: ChangeOptions): Promise<ChangeResult>;
 	/**
-	 * Max time to wait for lock in milliseconds.
+	 * Revert a change object directly.
+	 */
+	revertChange(change: Change, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Run next N pending changes.
 	 *
-	 * Only used if wait is true.
-	 * @default 30_000 (30 seconds)
+	 * @param count - Number of changes to run (default: 1)
+	 * @param options - Execution options
+	 * @returns Batch result
 	 */
-	waitTimeout?: number;
+	next(count?: number, options?: BatchChangeOptions): Promise<BatchChangeResult>;
 	/**
-	 * How often to poll when waiting, in milliseconds.
+	 * Fast-forward: run all pending changes.
 	 *
-	 * Only used if wait is true.
-	 * @default 1_000 (1 second)
+	 * @param options - Execution options
+	 * @returns Batch result
 	 */
-	pollInterval?: number;
+	ff(options?: BatchChangeOptions): Promise<BatchChangeResult>;
 	/**
-	 * Optional reason for acquiring the lock.
+	 * Rewind: revert changes in reverse order.
 	 *
-	 * Shown to users who are blocked by this lock.
+	 * @param target - Number of changes to revert, or name to revert to
+	 * @param options - Execution options
+	 * @returns Batch result
 	 */
-	reason?: string;
-}
-/**
- * Result of a lock status check.
- */
-export interface LockStatus {
-	/** Whether the lock is currently held */
-	isLocked: boolean;
-	/** Lock details if held, null if not */
-	lock: Lock$1 | null;
-}
-/**
- * Lock-related errors.
- *
- * WHY: Specific error types allow callers to handle lock failures
- * differently from other errors (e.g., prompt user to wait vs retry).
- */
-/**
- * Error when lock cannot be acquired.
- *
- * Thrown when another process holds the lock and wait=false,
- * or when waitTimeout is exceeded.
- *
- * @example
- * ```typescript
- * const [lock, err] = await attempt(() => lockManager.acquire(config, identity))
- * if (err instanceof LockAcquireError) {
- *     console.log(`Blocked by ${err.holder} since ${err.heldSince}`)
- * }
- * ```
- */
-export declare class LockAcquireError extends Error {
-	readonly configName: string;
-	readonly holder: string;
-	readonly heldSince: Date;
-	readonly expiresAt: Date;
-	readonly reason?: string | undefined;
-	readonly name: "LockAcquireError";
-	constructor(configName: string, holder: string, heldSince: Date, expiresAt: Date, reason?: string | undefined);
-}
-/**
- * Error when lock expires during operation.
- *
- * Thrown when validating lock before a critical operation
- * and discovering it has expired.
- *
- * @example
- * ```typescript
- * // Before committing transaction
- * const [, err] = await attempt(() => lockManager.validate(configName, identity))
- * if (err instanceof LockExpiredError) {
- *     await transaction.rollback()
- *     throw new Error('Lock expired, operation aborted')
- * }
- * ```
- */
-export declare class LockExpiredError extends Error {
-	readonly configName: string;
-	readonly identity: string;
-	readonly expiredAt: Date;
-	readonly name: "LockExpiredError";
-	constructor(configName: string, identity: string, expiredAt: Date);
-}
-/**
- * Result of processing a SQL file.
- */
-interface ProcessResult {
+	rewind(target: number | string, options?: BatchChangeOptions): Promise<BatchChangeResult>;
 	/**
-	 * The SQL content (rendered if template, raw if .sql).
+	 * Get execution history.
+	 *
+	 * @param name - Optional change name (all if not provided)
+	 * @param limit - Max records to return
+	 * @returns Array of history records
 	 */
-	sql: string;
+	getHistory(name?: string, limit?: number): Promise<ChangeHistoryRecord[]>;
 	/**
-	 * Whether the file was a template.
+	 * Get file execution history for an operation.
 	 */
-	isTemplate: boolean;
+	getFileHistory(operationId: number): Promise<FileHistoryRecord[]>;
 	/**
-	 * Render duration in milliseconds (only for templates).
+	 * Remove a change from disk, database, or both.
+	 *
+	 * @param name - Change name
+	 * @param options - What to remove
 	 */
-	durationMs?: number;
+	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>;
 }
 /**
  * SDK Types.
@@ -1052,35 +1920,6 @@ export interface CreateContextOptions {
 	/** Stage name for stage defaults (from settings.yml) */
 	stage?: string;
 }
-/**
- * Result of an execute() call.
- */
-export interface ExecuteResult {
-	/** Number of rows affected (if available) */
-	rowsAffected?: number;
-}
-/**
- * Transaction context for use within transaction callbacks.
- *
- * @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
- * })
- * ```
- */
-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>;
-}
 /**
  * Options for build operations.
  */
@@ -1088,588 +1927,1128 @@ export interface BuildOptions {
 	/** Skip checksum checks, rebuild everything. Default: false */
 	force?: boolean;
 }
-export type Events<Shape> = keyof Shape;
-declare namespace ObserverEngine {
-	interface EventCallback<Shape> {
-		(data: Shape, info?: {
-			event: string;
-			listener: Function;
-		} | undefined): void;
-	}
-	type RgxEmitData<Shape> = {
-		event: Events<Shape>;
-		data: Shape[Events<Shape>];
-	};
-	type Cleanup = () => void;
-	type Component<Ev extends Record<string, any>> = {
-		on: ObserverEngine<Ev>["on"];
-		once: ObserverEngine<Ev>["once"];
-		emit: ObserverEngine<Ev>["emit"];
-		off: ObserverEngine<Ev>["off"];
-	};
-	type Child<C, Ev extends Record<string, any>> = C & Component<Ev> & {
-		cleanup: Cleanup;
-		clear: Cleanup;
-	};
-	type Instance<Ev extends Record<string, any>> = Component<Ev> & {
-		observe: ObserverEngine<Ev>["observe"];
-		$observer: ObserverEngine<Ev>;
-	};
-	type FuncName = "on" | "once" | "off" | "emit" | "cleanup";
-	type SpyAction<Ev extends Record<string, any>> = {
-		event: keyof Ev | RegExp | "*";
-		listener?: Function | null | undefined;
-		data?: unknown | undefined;
-		fn: FuncName;
-		context: ObserverEngine<Ev>;
-	};
-	interface Spy<Ev extends Record<string, any>> {
-		(action: SpyAction<Ev>): void;
-	}
-	interface EmitValidator<Ev extends Record<string, any>> {
-		(event: keyof Ev, data: Ev[keyof Ev], context: ObserverEngine<Ev>): void;
-		(event: RegExp, data: unknown, context: ObserverEngine<Ev>): void;
-		(event: "*", data: unknown, context: ObserverEngine<Ev>): void;
-	}
-	type Options<Ev extends Record<string, any>> = {
-		name?: string | undefined;
-		spy?: Spy<Ev> | undefined;
-		emitValidator?: EmitValidator<Ev> | undefined;
-		signal?: AbortSignal | undefined;
-	};
-	type ListenerOptions = {
-		signal?: AbortSignal | undefined;
-	};
-	type ObserveOptions = {
-		signal?: AbortSignal | undefined;
-	};
-}
 /**
- * Generic function type for type-safe function signatures.
+ * Options for exporting a table to a .dt file.
  *
- * Enables consistent typing across utility functions and higher-order functions
- * where function parameters need to be strongly typed.
+ * Connection details (db, dialect) come from the context automatically.
  *
  * @example
- * function memoize<A extends any[], R>(fn: Func<A, R>): Func<A, R>
- * function debounce<A extends any[]>(fn: Func<A, void>, ms: number): Func<A, void>
+ * ```typescript
+ * const [result, err] = await ctx.exportTable('users', './exports/users.dtz', {
+ *     passphrase: 'secret',
+ *     batchSize: 5000,
+ * });
+ * ```
  */
-export type Func<A extends any[] = any[], R = any> = (...args: A) => R;
+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;
+}
 /**
- * Represents a value that can be either synchronous or asynchronous.
+ * Options for importing a .dt file into the database.
  *
- * Critical for utility functions that need to handle both sync and async
- * operations uniformly, enabling flexible API design.
+ * Connection details (db, dialect) come from the context automatically.
  *
  * @example
- * function processData<T>(processor: () => MaybePromise<T>): Promise<T>
- * function transform<T, U>(value: T, transformer: (val: T) => MaybePromise<U>): Promise<U>
+ * ```typescript
+ * const [result, err] = await ctx.importFile('./exports/users.dtz', {
+ *     onConflict: 'skip',
+ *     truncate: true,
+ * });
+ * ```
  */
-export type MaybePromise<T> = T | Promise<T>;
-export interface EventGeneratorOptions {
-	signal?: AbortSignal | undefined;
+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;
 }
-declare class EventGenerator<S extends Record<string, any>, E extends Events<S> | RegExp = Events<S>> {
-	#private;
-	cleanup: ObserverEngine.Cleanup;
-	next: () => Promise<EventData<S, E>>;
-	constructor(observer: ObserverEngine<S>, event: E | RegExp, options?: EventGeneratorOptions);
-	[Symbol.asyncIterator](): AsyncGenerator<Awaited<EventData<S, E>>, undefined, unknown>;
-	get lastValue(): E extends Events<S> ? S[E] : E extends RegExp ? ObserverEngine.RgxEmitData<S> : S[Events<S>];
-	get done(): boolean;
-	emit(data?: (E extends Events<S> ? S[E] : S[Events<S>])): void;
+export interface ContextState {
+	connection: ConnectionResult | null;
+	config: Config;
+	settings: Settings;
+	identity: Identity;
+	options: CreateContextOptions;
+	projectRoot: string;
+	changeManager: ChangeManager | null;
 }
-declare class ObserverEngine<Shape extends Record<string, any> = Record<string, any>> {
+export declare class ChangesNamespace {
 	#private;
-	constructor(options?: ObserverEngine.Options<Shape>);
-	name: string;
+	constructor(state: ContextState);
 	/**
-	 * Returns facts about the the internal state of the observable instance.
+	 * Create a new change directory with change/ and revert/ folders.
+	 *
+	 * @example
+	 * ```typescript
+	 * const change = await ctx.noorm.changes.create({ description: 'add-user-roles' })
+	 * ```
 	 */
-	$facts(): {
-		listeners: (keyof Shape)[];
-		rgxListeners: string[];
-		listenerCounts: Record<string, number>;
-		hasSpy: boolean;
-	};
+	create(options: CreateChangeOptions): Promise<Change>;
 	/**
-	 * The internals of the observable instance.
+	 * Add a file to a change.
 	 *
-	 * NOTE: Do not use this to try to meddle with the
-	 * internals of the observable instance. This is for
-	 * debugging purposes only.
+	 * @example
+	 * ```typescript
+	 * const updated = await ctx.noorm.changes.addFile(change, 'change', {
+	 *     name: 'create-table',
+	 *     type: 'sql',
+	 * })
+	 * ```
 	 */
-	$internals(): {
-		listenerMap: Map<keyof Shape, Set<Func>>;
-		rgxListenerMap: Map<string, Set<Func>>;
-		internalListener: EventTarget;
-		name: string;
-		spy: ObserverEngine.Spy<Shape> | undefined;
-	};
+	addFile(change: Change, folder: "change" | "revert", options: AddFileOptions): Promise<Change>;
 	/**
-	 * Returns if the observable instance has the given event
+	 * Remove a file from a change.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.changes.removeFile(change, 'change', '001_create-table.sql')
+	 * ```
 	 */
-	$has(event: Events<Shape>): boolean;
+	removeFile(change: Change, folder: "change" | "revert", filename: string): Promise<Change>;
 	/**
-	 * Returns if the observable instance has a regex event
+	 * Rename a file in a change.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.changes.renameFile(change, 'change', '001_old.sql', 'new-name')
+	 * ```
 	 */
-	$has(event: RegExp): boolean;
+	renameFile(change: Change, folder: "change" | "revert", oldFilename: string, newDescription: string): Promise<Change>;
 	/**
-	 * Returns if the observable instance has the given event
+	 * Reorder files in a change folder.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.changes.reorderFiles(change, 'change', ['002_b.sql', '001_a.sql'])
+	 * ```
 	 */
-	$has(event: string): boolean;
+	reorderFiles(change: Change, folder: "change" | "revert", newOrder: string[]): Promise<Change>;
 	/**
-	 * Enables or disables debugging for the observable instance.
-	 * Works in conjunction with your spy function. Provides a
-	 * stack trace of events that are triggered, listened to, and
-	 * cleaned up.
+	 * Delete a change directory from disk.
 	 *
-	 * @param on Whether to enable or disable debugging
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.changes.delete(change)
+	 * ```
 	 */
-	debug(on?: boolean): void;
+	delete(change: Change): Promise<void>;
 	/**
-	 * Sets the spy function for the observable instance.
-	 * @param spy The spy function to set
-	 * @param force Whether to force the spy function to be set even if one is already set
+	 * Discover all changes on disk.
+	 *
+	 * @example
+	 * ```typescript
+	 * const changes = await ctx.noorm.changes.discover()
+	 * ```
 	 */
-	spy(spy: ObserverEngine.Spy<Shape>, force?: boolean): void;
+	discover(): Promise<Change[]>;
+	/**
+	 * Parse a single change from disk by name.
+	 *
+	 * @example
+	 * ```typescript
+	 * const change = await ctx.noorm.changes.parse('2024-01-15-add-users')
+	 * ```
+	 */
+	parse(name: string): Promise<Change>;
+	/**
+	 * Validate a change's structure.
+	 *
+	 * @throws ChangeValidationError if invalid
+	 *
+	 * @example
+	 * ```typescript
+	 * ctx.noorm.changes.validate(change)
+	 * ```
+	 */
+	validate(change: Change): void;
+	/**
+	 * Apply a specific change.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.changes.apply('2024-01-15-add-users')
+	 * ```
+	 */
+	apply(name: string, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Revert a specific change.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.changes.revert('2024-01-15-add-users')
+	 * ```
+	 */
+	revert(name: string, options?: ChangeOptions): Promise<ChangeResult>;
+	/**
+	 * Apply all pending changes.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.changes.ff()
+	 * ```
+	 */
+	ff(): Promise<BatchChangeResult>;
+	/**
+	 * Get status of all changes (merged disk + DB).
+	 *
+	 * @example
+	 * ```typescript
+	 * const all = await ctx.noorm.changes.status()
+	 * ```
+	 */
+	status(): Promise<ChangeListItem[]>;
+	/**
+	 * Get only pending (unapplied or reverted) changes.
+	 *
+	 * @example
+	 * ```typescript
+	 * const pending = await ctx.noorm.changes.pending()
+	 * ```
+	 */
+	pending(): Promise<ChangeListItem[]>;
+	/**
+	 * Get execution history.
+	 *
+	 * @example
+	 * ```typescript
+	 * const history = await ctx.noorm.changes.history(10)
+	 * ```
+	 */
+	history(limit?: number): Promise<ChangeHistoryRecord[]>;
+}
+export declare class RunNamespace {
+	#private;
+	constructor(state: ContextState);
+	/**
+	 * Discover SQL files in a directory.
+	 *
+	 * @example
+	 * ```typescript
+	 * const files = await ctx.noorm.run.discover('sql/')
+	 * ```
+	 */
+	discover(dirpath?: string): Promise<string[]>;
+	/**
+	 * Preview SQL files — render templates without executing.
+	 *
+	 * @example
+	 * ```typescript
+	 * const results = await ctx.noorm.run.preview(['sql/001.sql', 'sql/002.sql'])
+	 * ```
+	 */
+	preview(filepaths: string[], output?: string | null): Promise<FileResult[]>;
+	/**
+	 * Execute a single SQL file.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.run.file('seeds/test-data.sql')
+	 * ```
+	 */
+	file(filepath: string, options?: RunOptions): Promise<FileResult>;
+	/**
+	 * Execute multiple SQL files sequentially.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.run.files(['functions/utils.sql', 'triggers/audit.sql'])
+	 * ```
+	 */
+	files(filepaths: string[], options?: RunOptions): Promise<BatchResult>;
+	/**
+	 * Execute all SQL files in a directory.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.run.dir('seeds/')
+	 * ```
+	 */
+	dir(dirpath: string, options?: RunOptions): Promise<BatchResult>;
+	/**
+	 * Execute all SQL files in the schema directory.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.run.build({ force: true })
+	 * ```
+	 */
+	build(options?: BuildOptions): Promise<BatchResult>;
+}
+/**
+ * Overview counts for all categories.
+ */
+export interface ExploreOverview {
+	tables: number;
+	views: number;
+	procedures: number;
+	functions: number;
+	types: number;
+	indexes: number;
+	foreignKeys: number;
+	triggers: number;
+	locks: number;
+	connections: number;
+}
+/**
+ * Table summary for list display.
+ */
+export interface TableSummary {
+	name: string;
+	schema?: string;
+	columnCount: number;
+	rowCountEstimate?: number;
+}
+/**
+ * Index summary for list display.
+ */
+export interface IndexSummary {
+	name: string;
+	schema?: string;
+	tableName: string;
+	tableSchema?: string;
+	columns: string[];
+	isUnique: boolean;
+	isPrimary: boolean;
+}
+/**
+ * Foreign key summary for list display.
+ */
+export interface ForeignKeySummary {
+	name: string;
+	schema?: string;
+	tableName: string;
+	tableSchema?: string;
+	columns: string[];
+	referencedTable: string;
+	referencedSchema?: string;
+	referencedColumns: string[];
+	onDelete?: string;
+	onUpdate?: string;
+}
+/**
+ * Column detail for tables/views.
+ */
+export interface ColumnDetail {
+	name: string;
+	dataType: string;
+	isNullable: boolean;
+	defaultValue?: string;
+	isPrimaryKey: boolean;
+	ordinalPosition: number;
+}
+/**
+ * Full table detail.
+ */
+export interface TableDetail {
+	name: string;
+	schema?: string;
+	columns: ColumnDetail[];
+	indexes: IndexSummary[];
+	foreignKeys: ForeignKeySummary[];
+	rowCountEstimate?: number;
+}
+/**
+ * Result of a truncate operation.
+ */
+export interface TruncateResult {
+	/** Tables that were truncated */
+	truncated: string[];
+	/** Tables that were preserved */
+	preserved: string[];
+	/** SQL statements executed (or would execute in dry-run) */
+	statements: string[];
+	/** Duration in milliseconds */
+	durationMs: number;
+}
+/**
+ * Result of a teardown operation.
+ */
+export interface TeardownResult {
+	/** Objects dropped by category */
+	dropped: {
+		tables: string[];
+		views: string[];
+		functions: string[];
+		procedures: string[];
+		types: string[];
+		foreignKeys: string[];
+	};
+	/** Objects preserved */
+	preserved: string[];
+	/** SQL statements executed (or would execute in dry-run) */
+	statements: string[];
+	/** Duration in milliseconds */
+	durationMs: number;
+	/** Post-script execution result (if any) */
+	postScriptResult?: {
+		executed: boolean;
+		error?: string;
+	};
+	/** Number of changes marked as stale (if configName provided) */
+	staleCount?: number;
+	/** ID of the reset record created (if configName provided) */
+	resetRecordId?: number;
+}
+/**
+ * Preview of what would be affected by teardown.
+ */
+export interface TeardownPreview {
+	/** Objects that would be dropped */
+	toDrop: {
+		tables: string[];
+		views: string[];
+		functions: string[];
+		procedures: string[];
+		types: string[];
+		foreignKeys: string[];
+	};
+	/** Objects that would be preserved */
+	toPreserve: string[];
+	/** SQL statements that would execute */
+	statements: string[];
+}
+export declare class DbNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * Observes given component as an extension of this observable instance.
-	 * @param component Component to wrap events around
-	 * @param options Optional configuration including signal for cleanup
+	 * List all tables in the database.
 	 *
 	 * @example
-	 *
-	 * const obs = new ObserverEngine();
-	 *
-	 * const modal = {};
-	 *
-	 * obs.observe(modal);
-	 *
-	 * modal.on('modal-open', () => {});
-	 *
-	 * obs.trigger('modal-open'); // opens modal
-	 * modal.trigger('modal-open'); // opens modal
-	 *
-	 * modal.cleanup(); // clears all event listeners
+	 * ```typescript
+	 * const tables = await ctx.noorm.db.listTables()
+	 * ```
 	 */
-	observe<C>(component: C, options?: ObserverEngine.ObserveOptions): ObserverEngine.Child<C, Shape>;
+	listTables(): Promise<TableSummary[]>;
 	/**
-	 * Returns an event generator that will listen for the specified event
+	 * Get detailed information about a table.
 	 *
 	 * @example
-	 *
-	 * const obs = new ObserverEngine();
-	 *
-	 * const something = obs.on('something');
-	 * const data = await something.next(); // waits for next event
-	 * something.emit('special'); // emits data to listeners
-	 *
-	 * something.cleanup(); // stops listening for events
+	 * ```typescript
+	 * const detail = await ctx.noorm.db.describeTable('users')
+	 * ```
 	 */
-	on<E extends Events<Shape>>(event: E, options?: ObserverEngine.ListenerOptions): EventGenerator<Shape, E>;
-	on<E extends string>(event: E, options?: ObserverEngine.ListenerOptions): EventGenerator<Record<E, any>>;
+	describeTable(name: string, schema?: string): Promise<TableDetail | null>;
 	/**
-	 * Listens for the specified event and executes the given callback
+	 * Get database overview with counts of all object types.
 	 *
 	 * @example
-	 *
-	 * const obs = new ObserverEngine();
-	 *
-	 * obs.on('something', (data) => {
-	 *    console.log(data);
-	 * });
+	 * ```typescript
+	 * const overview = await ctx.noorm.db.overview()
+	 * ```
 	 */
-	on<E extends Events<Shape>>(event: E, listener: ObserverEngine.EventCallback<Shape[E]>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
-	on<E extends string>(event: E, listener: ObserverEngine.EventCallback<Record<E, any>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	overview(): Promise<ExploreOverview>;
 	/**
-	 * Returns an event generator that will listen for all events matching the regex
+	 * Preview what teardown would drop without executing.
 	 *
 	 * @example
-	 *
-	 * const obs = new ObserverEngine();
-	 *
-	 * const onEvent = obs.on(/some/);
-	 * const { event, data } = await onEvent.next(); // waits for next event
-	 * onEvent.emit('something'); // emits data to listeners
-	 *
-	 * onEvent.cleanup(); // stops listening for events
+	 * ```typescript
+	 * const preview = await ctx.noorm.db.previewTeardown()
+	 * ```
 	 */
-	on(event: RegExp, options?: ObserverEngine.ListenerOptions): EventGenerator<Shape, RegExp>;
+	previewTeardown(): Promise<TeardownPreview>;
 	/**
-	 * Listens for all events matching the regex and executes the given callback
+	 * Wipe all data, keeping the schema intact.
 	 *
 	 * @example
-	 *
-	 * const obs = new ObserverEngine();
-	 *
-	 * obs.on(/some/, ({ event, data }) => {
-	 *     console.log(event, data);
-	 * });
-	 */
-	on(event: RegExp, listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
-	/**
-	 * Returns an event promise that resolves when
-	 * the specified event is emitted
-	 */
-	once<E extends Events<Shape>>(event: E, options?: ObserverEngine.ListenerOptions): EventPromise<Shape[E]>;
-	/**
-	 * Returns an event promise that resolves when
-	 * the specified event is emitted. This overload
-	 * is untyped and can be used to listen for any
-	 * event that is emitted.
-	 */
-	once<E extends string>(event: E, options?: ObserverEngine.ListenerOptions): EventPromise<Record<E, any>>;
-	/**
-	 * Executes a callback once when the specified
-	 * event is emitted
-	 */
-	once<E extends Events<Shape>>(event: E, listener: ObserverEngine.EventCallback<Shape[E]>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
-	/**
-	 * Executes a callback once when the specified
-	 * event is emitted. This overload is untyped
-	 * and can be used to listen for any event that
-	 * is emitted.
-	 */
-	once<E extends string>(event: E, listener: ObserverEngine.EventCallback<Record<E, any>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
-	/**
-	 * Returns an event promise that resolves when
-	 * any events matching the regex are emitted
+	 * ```typescript
+	 * const result = await ctx.noorm.db.truncate()
+	 * ```
 	 */
-	once(event: RegExp, options?: ObserverEngine.ListenerOptions): EventPromise<ObserverEngine.RgxEmitData<Shape>>;
+	truncate(): Promise<TruncateResult>;
 	/**
-	 * Executes a callback once when any events
-	 * matching the regex are emitted
+	 * Drop all database objects except noorm tracking tables.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.db.teardown()
+	 * ```
 	 */
-	once(event: RegExp, listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>, options?: ObserverEngine.ListenerOptions): ObserverEngine.Cleanup;
+	teardown(): Promise<TeardownResult>;
 	/**
-	 * Stop listening for an event
-	 * @param event
-	 * @param listener
+	 * Full rebuild: teardown + build.
+	 *
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.db.reset()
+	 * ```
 	 */
-	off(event: Events<Shape> | RegExp | string, listener?: Function): void;
-	/** Emits an event */
-	emit<E extends Events<Shape> | RegExp | string>(event: E, data?: E extends Events<Shape> ? Shape[E] : E extends string ? Record<E, any>[E] : unknown): void;
-	clear(): void;
-	queue<E extends Events<Shape> | RegExp>(event: E, process: (data: EventData<Shape, E>) => MaybePromise<any>, options: QueueOpts): EventQueue<Shape, E>;
-}
-export type EventData<S, E extends Events<S> | RegExp = Events<S>> = (E extends Events<S> ? S[E] : E extends RegExp ? ObserverEngine.RgxEmitData<S> : S[Events<S>]);
-declare class EventPromise<T> extends Promise<T> {
-	cleanup?: () => void;
-	reject?: (err: Error | string) => void;
-	resolve?: (value: T) => void;
-}
-declare class InternalQueueEvent<T = unknown> {
-	readonly data: T;
-	constructor(data: T);
-}
-declare enum QueueRejectionReason {
-	full = "Queue is full",
-	notRunning = "Queue is not running"
+	reset(): Promise<void>;
+	/** @internal Used by NoormOps to wire up reset -> build. */
+	set _buildFn(fn: (opts?: BuildOptions) => Promise<unknown>);
 }
-export type QueueEventData<S, E extends Events<S> | RegExp = Events<S>> = {
-	data?: EventData<S, E>;
-	_taskId?: string;
-	priority?: number;
-	reason?: QueueRejectionReason;
-	startedAt?: number;
-	rateLimited?: boolean;
-	elapsed?: number;
-	error?: Error;
-	force?: boolean;
-	pending?: number;
-	flushed?: number;
-	drained?: number;
-	count?: number;
-};
-export type QueueEvents<S extends Record<string, any>, E extends Events<S> | RegExp = Events<S>> = {
-	added: QueueEventData<S, E>;
-	start: void;
-	started: void;
-	stopped: void;
-	processing: QueueEventData<S, E> & {
-		startedAt: number;
-		rateLimited: boolean;
-	};
-	success: QueueEventData<S, E> & {
-		startedAt: number;
-		elapsed: number;
-		rateLimited: boolean;
-	};
-	error: QueueEventData<S, E> & {
-		error: Error;
-		rateLimited: boolean;
-	};
-	timeout: QueueEventData<S, E> & {
-		error: Error;
-		rateLimited: boolean;
-	};
-	rejected: QueueEventData<S, E> & {
-		reason: QueueRejectionReason;
-	};
-	"rate-limited": QueueEventData<S, E> & {
-		rateLimited: boolean;
-	};
-	empty: void;
-	idle: void;
-	drain: {
-		pending: number;
-	};
-	drained: {
-		pending?: number;
-		drained?: number;
-	};
-	flush: {
-		pending: number;
-	};
-	flushed: {
-		flushed: number;
-	};
-	paused: void;
-	resumed: void;
-	cleanup: void;
-	purged: {
-		count: number;
-	};
-	shutdown: {
-		force: boolean;
-		pending?: number;
-	};
-};
-declare enum QueueState {
-	running = "running",
-	paused = "paused",
-	stopped = "stopped",
-	draining = "draining"
+/**
+ * Lock manager types.
+ *
+ * Defines the shape of locks and options for acquiring them.
+ * Used to prevent concurrent operations on the same database.
+ *
+ * WHY: Concurrent DDL operations can corrupt database state.
+ * Locks ensure only one process modifies the schema at a time.
+ */
+/**
+ * Lock state returned after acquisition.
+ *
+ * @example
+ * ```typescript
+ * const lock = await lockManager.acquire('dev', 'alice@example.com')
+ * console.log(lock.lockedBy)   // 'alice@example.com'
+ * console.log(lock.expiresAt)  // Date object
+ * ```
+ */
+interface Lock$1 {
+	/** Identity string of holder */
+	lockedBy: string;
+	/** When acquired */
+	lockedAt: Date;
+	/** Auto-expiry time */
+	expiresAt: Date;
+	/** Optional reason for acquiring */
+	reason?: string;
 }
 /**
- * The options for the queue
+ * Options for acquiring a lock.
+ *
+ * @example
+ * ```typescript
+ * // Wait up to 30s for lock, polling every 500ms
+ * const options: LockOptions = {
+ *     timeout: 60_000,        // Lock expires after 60s
+ *     wait: true,             // Block until available
+ *     waitTimeout: 30_000,    // Max wait time
+ *     pollInterval: 500,      // Check every 500ms
+ *     reason: 'Running migrations',
+ * }
+ * ```
  */
-export interface QueueOpts {
+interface LockOptions$1 {
 	/**
-	 * The name of the queue
+	 * Database dialect for date formatting.
+	 *
+	 * SQLite stores dates as ISO strings, other dialects can use Date objects.
+	 * @default 'postgres'
+	 */
+	dialect?: "postgres" | "mysql" | "sqlite" | "mssql";
+	/**
+	 * Lock duration in milliseconds.
+	 *
+	 * After this time, the lock expires and can be claimed by others.
+	 * @default 300_000 (5 minutes)
+	 */
+	timeout?: number;
+	/**
+	 * Block until lock is available?
+	 *
+	 * If true, will poll until the lock is acquired or waitTimeout is reached.
+	 * @default false
 	 */
-	name: string;
+	wait?: boolean;
 	/**
-	 * The type of queue to use
+	 * Max time to wait for lock in milliseconds.
 	 *
-	 * @default 'fifo'
+	 * Only used if wait is true.
+	 * @default 30_000 (30 seconds)
 	 */
-	type?: "fifo" | "lifo";
+	waitTimeout?: number;
 	/**
-	 * The concurrency of the queue
+	 * How often to poll when waiting, in milliseconds.
 	 *
-	 * @default 1
+	 * Only used if wait is true.
+	 * @default 1_000 (1 second)
 	 */
-	concurrency?: number;
+	pollInterval?: number;
 	/**
-	 * The poll interval in milliseconds before the queue will
-	 * check for new items after idle.
+	 * Optional reason for acquiring the lock.
 	 *
-	 * @default 100
+	 * Shown to users who are blocked by this lock.
 	 */
-	pollIntervalMs?: number;
+	reason?: string;
+}
+/**
+ * Result of a lock status check.
+ */
+export interface LockStatus {
+	/** Whether the lock is currently held */
+	isLocked: boolean;
+	/** Lock details if held, null if not */
+	lock: Lock$1 | null;
+}
+/**
+ * Lock-related errors.
+ *
+ * WHY: Specific error types allow callers to handle lock failures
+ * differently from other errors (e.g., prompt user to wait vs retry).
+ */
+/**
+ * Error when lock cannot be acquired.
+ *
+ * Thrown when another process holds the lock and wait=false,
+ * or when waitTimeout is exceeded.
+ *
+ * @example
+ * ```typescript
+ * const [lock, err] = await attempt(() => lockManager.acquire(config, identity))
+ * if (err instanceof LockAcquireError) {
+ *     console.log(`Blocked by ${err.holder} since ${err.heldSince}`)
+ * }
+ * ```
+ */
+export declare class LockAcquireError extends Error {
+	readonly configName: string;
+	readonly holder: string;
+	readonly heldSince: Date;
+	readonly expiresAt: Date;
+	readonly reason?: string | undefined;
+	readonly name: "LockAcquireError";
+	constructor(configName: string, holder: string, heldSince: Date, expiresAt: Date, reason?: string | undefined);
+}
+/**
+ * Error when lock expires during operation.
+ *
+ * Thrown when validating lock before a critical operation
+ * and discovering it has expired.
+ *
+ * @example
+ * ```typescript
+ * // Before committing transaction
+ * const [, err] = await attempt(() => lockManager.validate(configName, identity))
+ * if (err instanceof LockExpiredError) {
+ *     await transaction.rollback()
+ *     throw new Error('Lock expired, operation aborted')
+ * }
+ * ```
+ */
+export declare class LockExpiredError extends Error {
+	readonly configName: string;
+	readonly identity: string;
+	readonly expiredAt: Date;
+	readonly name: "LockExpiredError";
+	constructor(configName: string, identity: string, expiredAt: Date);
+}
+export declare class LockNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * The jitter percentage to displace
-	 * the next process time. This stops all concurrent
-	 * processes from happening at the same time.
+	 * Acquire a database lock.
 	 *
-	 * @range [0, 1]
-	 * @default 1
+	 * @example
+	 * ```typescript
+	 * const lock = await ctx.noorm.lock.acquire({ timeout: 60000 })
+	 * ```
 	 */
-	jitterFactor?: number;
+	acquire(options?: LockOptions$1): Promise<Lock$1>;
 	/**
-	 * The interval in milliseconds before picking up the next item
-	 *
-	 * @note If the interval is 0, the queue will not wait between items
+	 * Release the current lock.
 	 *
-	 * @default 0
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.lock.release()
+	 * ```
 	 */
-	processIntervalMs?: number;
+	release(): Promise<void>;
 	/**
-	 * The timeout in milliseconds before the task is considered timed out
+	 * Get current lock status.
 	 *
-	 * @note If the timeout is 0, the task will not be considered timed out
-	 *
-	 * @default 0
+	 * @example
+	 * ```typescript
+	 * const status = await ctx.noorm.lock.status()
+	 * ```
 	 */
-	taskTimeoutMs?: number;
+	status(): Promise<LockStatus>;
 	/**
-	 * The maximum size of the queue
+	 * Execute an operation with automatic lock acquisition and release.
 	 *
-	 * @default 999_999_999
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.lock.withLock(async () => {
+	 *     await ctx.noorm.run.build()
+	 * })
+	 * ```
 	 */
-	maxQueueSize?: number;
+	withLock<T>(fn: () => Promise<T>, options?: LockOptions$1): Promise<T>;
 	/**
-	 * The rate limit of the queue in items per window
+	 * Force release any database lock regardless of ownership.
 	 *
-	 * @default 999_999_999
+	 * @example
+	 * ```typescript
+	 * await ctx.noorm.lock.forceRelease()
+	 * ```
 	 */
-	rateLimitCapacity?: number;
+	forceRelease(): Promise<boolean>;
+}
+/**
+ * Vault secret entry (decrypted).
+ */
+export interface VaultSecret {
+	/** Secret key name */
+	key: string;
+	/** Decrypted value */
+	value: string;
+	/** Identity who set this secret */
+	setBy: string;
+	/** When created */
+	createdAt: Date;
+	/** When last updated */
+	updatedAt: Date;
+}
+/**
+ * Result of vault copy operation.
+ */
+export interface VaultCopyResult {
+	/** Keys that were successfully copied */
+	copied: string[];
+	/** Keys that were skipped (already exist and force not set) */
+	skipped: string[];
+	/** Keys that failed with errors */
+	errors: Array<{
+		key: string;
+		error: string;
+	}>;
+}
+/**
+ * Result of vault propagation.
+ */
+export interface VaultPropagationResult {
+	/** Identity hashes that received the vault key */
+	propagatedTo: string[];
+	/** Count of users who already had access */
+	alreadyHadAccess: number;
+}
+/**
+ * Vault status for the current user.
+ */
+export interface VaultStatus {
+	/** Whether the vault is initialized (at least one user has the vault key) */
+	isInitialized: boolean;
+	/** Whether the current user has access to the vault */
+	hasAccess: boolean;
+	/** Number of secrets in the vault */
+	secretCount: number;
+	/** Number of users with vault access */
+	usersWithAccess: number;
+	/** Number of users without vault access */
+	usersWithoutAccess: number;
+}
+/**
+ * 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;
+	};
+}
+/**
+ * Options for vault copy operation.
+ */
+export interface VaultCopyOptions {
+	/** Overwrite existing secrets in destination (default: false) */
+	force?: boolean;
+}
+export declare class VaultNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * The rate limit window in milliseconds
+	 * Initialize the vault for this database.
 	 *
-	 * @default 1000
+	 * @example
+	 * ```typescript
+	 * const [vaultKey, err] = await ctx.noorm.vault.init()
+	 * ```
 	 */
-	rateLimitIntervalMs?: number;
+	init(): Promise<[
+		Buffer | null,
+		Error | null
+	]>;
 	/**
-	 * Automatically start the queue
+	 * Get vault status.
 	 *
-	 * @default true
+	 * @example
+	 * ```typescript
+	 * const status = await ctx.noorm.vault.status()
+	 * ```
 	 */
-	autoStart?: boolean;
+	status(): Promise<VaultStatus>;
 	/**
-	 * Whether to enable debug mode. Can be set to 'info' or 'verbose' to
-	 * get more detailed output.
+	 * Set a vault secret.
 	 *
-	 * @default false
+	 * @example
+	 * ```typescript
+	 * const [, err] = await ctx.noorm.vault.set('API_KEY', 'sk-live-...', privateKey)
+	 * ```
 	 */
-	debug?: boolean | "info" | "verbose";
-}
-declare class EventQueue<S extends Record<string, any>, E extends Events<S> | RegExp = Events<S>> {
-	#private;
-	private opts;
-	constructor(opts: QueueOpts & {
-		event: E | RegExp;
-		process: (data: EventData<S, E>) => Promise<void>;
-		observer?: ObserverEngine<S>;
-	});
+	set(key: string, value: string, privateKey: string): Promise<[
+		void,
+		Error | null
+	]>;
 	/**
-	 * Start the queue if it is not already started
+	 * Get a vault secret by key.
+	 *
+	 * @example
+	 * ```typescript
+	 * const value = await ctx.noorm.vault.get('API_KEY', privateKey)
+	 * ```
 	 */
-	start(): Promise<void> | undefined;
+	get(key: string, privateKey: string): Promise<string | null>;
 	/**
-	 * Stop the queue
+	 * Get all vault secrets.
+	 *
+	 * @example
+	 * ```typescript
+	 * const all = await ctx.noorm.vault.getAll(privateKey)
+	 * ```
 	 */
-	stop(): void;
+	getAll(privateKey: string): Promise<Record<string, VaultSecret>>;
 	/**
-	 * Pause the queue
+	 * List all vault secret keys (without decrypting values).
+	 *
+	 * @example
+	 * ```typescript
+	 * const keys = await ctx.noorm.vault.list()
+	 * ```
 	 */
-	pause(): Promise<void> | undefined;
+	list(): Promise<string[]>;
 	/**
-	 * Resume the queue
+	 * Delete a vault secret.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [deleted, err] = await ctx.noorm.vault.delete('OLD_KEY')
+	 * ```
 	 */
-	resume(): Promise<void> | undefined;
+	delete(key: string): Promise<[
+		boolean,
+		Error | null
+	]>;
 	/**
-	 * Empty and process all items in the queue and
-	 * then stop the queue. Returns the number of items
-	 * processed.
+	 * Check if a vault secret exists.
+	 *
+	 * @example
+	 * ```typescript
+	 * const exists = await ctx.noorm.vault.exists('API_KEY')
+	 * ```
 	 */
-	shutdown(force?: boolean): Promise<number>;
+	exists(key: string): Promise<boolean>;
 	/**
-	 * Executes `limit` items in the queue
-	 * and then emits a `flush` event. Returns the number
-	 * of items processed.
+	 * Propagate vault key to all users without access.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.vault.propagate(privateKey)
+	 * ```
 	 */
-	flush(limit?: number): Promise<number>;
+	propagate(privateKey: string): Promise<VaultPropagationResult>;
 	/**
-	 * Clears the queue and emits a `purge` event. Returns
-	 * the number of items purged.
+	 * Copy vault secrets to another config's database.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [result, err] = await ctx.noorm.vault.copy(destConfig, ['API_KEY'], privateKey)
+	 * ```
 	 */
-	purge(): number;
+	copy(destConfig: Config, keys: string[] | "all", privateKey: string, options?: VaultCopyOptions): Promise<[
+		VaultCopyResult | null,
+		Error | null
+	]>;
+}
+export declare class SecretsNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * Emit an event to the observer, which then gets
-	 * picked up by the queue and processed.
-	 *
-	 * @param data The data to add to the queue
-	 * @param priority The priority of the data
-	 *
-	 * @note If priority is provided, it will be used to determine the order of the data in the queue.
-	 *       The higher the priority, the sooner the data will be processed.
+	 * Get a config-scoped secret.
 	 *
-	 * @note If priority is not provided, the data will be added to the queue with a priority of 0.
+	 * @example
+	 * ```typescript
+	 * const apiKey = ctx.noorm.secrets.get('API_KEY')
+	 * ```
 	 */
-	add(data: EventData<S, E>, priority?: number): boolean;
-	debug(on?: boolean | "info" | "verbose"): void;
-	on<K extends keyof QueueEvents<S, E>>(event: K, listener: ((payload: InternalQueueEvent<QueueEvents<S, E>[K]>) => void)): ObserverEngine.Cleanup;
-	on<K extends keyof QueueEvents<S, E>>(event: K): EventGenerator<QueueEvents<S, E>, K>;
-	once<K extends keyof QueueEvents<S, E>>(event: K): EventPromise<InternalQueueEvent<QueueEvents<S, E>[K]>>;
-	once<K extends keyof QueueEvents<S, E>>(event: K, listener: ((payload: InternalQueueEvent<QueueEvents<S, E>[K]>) => void)): ObserverEngine.Cleanup;
-	off<K extends keyof QueueEvents<S, E>>(event: K, listener?: Function): void;
+	get(key: string): string | undefined;
+}
+/**
+ * Result of processing a SQL file.
+ */
+interface ProcessResult {
 	/**
-	 * The name of the queue
+	 * The SQL content (rendered if template, raw if .sql).
 	 */
-	get name(): string;
+	sql: string;
 	/**
-	 * Whether the queue is waiting for the
-	 * the
+	 * Whether the file was a template.
 	 */
-	get isWaiting(): boolean;
+	isTemplate: boolean;
 	/**
-	 * Whether the queue is idle
+	 * Render duration in milliseconds (only for templates).
 	 */
-	get isIdle(): boolean;
+	durationMs?: number;
+}
+export declare class TemplatesNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * Whether the queue is running
+	 * Render a template file without executing.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.templates.render('sql/001_users.sql.tmpl')
+	 * ```
 	 */
-	get isRunning(): boolean;
+	render(filepath: string): Promise<ProcessResult>;
+}
+/**
+ * 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;
+}
+export declare class TransferNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * Whether the queue is paused
+	 * Transfer data to a destination database.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [result, err] = await ctx.noorm.transfer.to(destConfig, {
+	 *     tables: ['users', 'posts'],
+	 *     onConflict: 'skip',
+	 * })
+	 * ```
 	 */
-	get isPaused(): boolean;
+	to(destConfig: Config, options?: TransferOptions): Promise<[
+		TransferResult | null,
+		Error | null
+	]>;
 	/**
-	 * Whether the queue is stopped
+	 * Generate a transfer plan without executing.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [plan, err] = await ctx.noorm.transfer.plan(destConfig)
+	 * ```
 	 */
-	get isStopped(): boolean;
+	plan(destConfig: Config, options?: TransferOptions): Promise<[
+		TransferPlan | null,
+		Error | null
+	]>;
+}
+export declare class DtNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * Whether the queue is draining
+	 * Export a table to a .dt file.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [result, err] = await ctx.noorm.dt.exportTable('users', './exports/users.dtz')
+	 * ```
 	 */
-	get isDraining(): boolean;
+	exportTable(tableName: string, filepath: string, options?: ExportOptions): Promise<[
+		{
+			rowsWritten: number;
+			bytesWritten: number;
+		} | null,
+		Error | null
+	]>;
 	/**
-	 * The current state of the queue
+	 * Import a .dt file into the connected database.
+	 *
+	 * @example
+	 * ```typescript
+	 * const [result, err] = await ctx.noorm.dt.importFile('./exports/users.dtz', {
+	 *     onConflict: 'skip',
+	 * })
+	 * ```
 	 */
-	get state(): QueueState;
+	importFile(filepath: string, options?: ImportOptions): Promise<[
+		{
+			rowsImported: number;
+			rowsSkipped: number;
+		} | null,
+		Error | null
+	]>;
+}
+export declare class UtilsNamespace {
+	#private;
+	constructor(state: ContextState);
 	/**
-	 * The number of items in the queue
+	 * Compute SHA-256 checksum for a file.
+	 *
+	 * @example
+	 * ```typescript
+	 * const checksum = await ctx.noorm.utils.checksum('sql/001_users.sql')
+	 * ```
 	 */
-	get pending(): number;
+	checksum(filepath: string): Promise<string>;
 	/**
-	 * The stats of the queue
+	 * Tests if the connection can be established.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await ctx.noorm.utils.testConnection()
+	 * ```
 	 */
-	get stats(): {
-		processed: number;
-		processing: number;
-		avgProcessingTime: number;
-		success: number;
-		error: number;
-		rejected: number;
-	};
-	get snapshot(): {
-		name: string;
-		state: QueueState;
-		pending: number;
-		stats: {
-			processed: number;
-			processing: number;
-			avgProcessingTime: number;
-			success: number;
-			error: number;
-			rejected: number;
-		};
-		rateLimiter: {
-			currentTokens: number;
-			capacity: number;
-			refillIntervalMs: number;
-			totalRequests: number;
-			rejectedRequests: number;
-			successfulRequests: number;
-			rejectionRate: number;
-			totalWaitTime: number;
-			waitCount: number;
-			averageWaitTime: number;
-			uptime: number;
-			createdAt: number;
-		};
-		activeRunners: number;
-		runningNodes: Set<`${number}-${number}`>;
-		isIdle: boolean;
-		isWaiting: boolean;
-		isRunning: boolean;
-		isPaused: boolean;
-		isStopped: boolean;
-		isDraining: boolean;
-		isEmpty: boolean;
-	};
+	testConnection(): Promise<{
+		ok: boolean;
+		error?: string;
+	}>;
 }
 /**
  * Shutdown phases in order of execution.
@@ -1689,6 +3068,288 @@ 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;
+	};
+}
+/**
+ * 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[];
+	};
+	/** A batch of rows arrived from the Connection Worker. */
+	"dt:export:loaded": {
+		table: string;
+		loaded: number;
+		totalRows: number;
+	};
+	/** A compute worker finished serializing a row. */
+	"dt:export:processed": {
+		table: string;
+		processed: number;
+		totalRows: number;
+	};
+	/** Order buffer flushed consecutive rows to DtWriter. */
+	"dt:export:saved": {
+		table: string;
+		saved: number;
+		totalRows: number;
+	};
+	/** A batch of lines read from file by DtReader. */
+	"dt:import:loaded": {
+		table: string;
+		loaded: number;
+		totalRows: number;
+	};
+	/** A compute worker finished deserializing a row. */
+	"dt:import:processed": {
+		table: string;
+		processed: number;
+		totalRows: number;
+	};
+	/** Deserialized rows inserted into the database. */
+	"dt:import:saved": {
+		table: string;
+		saved: number;
+		totalRows: number;
+	};
+	/** Modify operation begins. */
+	"dt:modify:start": {
+		inputPath: string;
+		outputPath: string;
+		recipeLength: number;
+	};
+	/** After each row processed during modify. */
+	"dt:modify:progress": {
+		rowsRead: number;
+		rowsWritten: number;
+		rowsFiltered: number;
+	};
+	/** Modify operation finished. */
+	"dt:modify:complete": {
+		result: {
+			rowsRead: number;
+			rowsWritten: number;
+			rowsFiltered: number;
+			columnsDropped: number;
+			columnsAdded: number;
+			columnsRenamed: number;
+			outputPath: string;
+			durationMs: number;
+		};
+	};
+}
 /**
  * All events emitted by noorm core modules.
  *
@@ -1706,9 +3367,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 +3390,9 @@ export interface NoormEvents extends SettingsEvents {
 	};
 	"file:dry-run": {
 		filepath: string;
-		outputPath: string;
+		status: "success" | "failed";
+		outputPath?: string;
+		error?: string;
 	};
 	"change:created": {
 		name: string;
@@ -1763,6 +3429,7 @@ export interface NoormEvents extends SettingsEvents {
 		filesSkipped: number;
 		filesFailed: number;
 		durationMs: number;
+		error?: string;
 	};
 	"run:file": {
 		filepath: string;
@@ -1893,6 +3560,7 @@ export interface NoormEvents extends SettingsEvents {
 		registered: boolean;
 		knownUsersCount: number;
 	};
+	"identity:not-found": void;
 	"connection:open": {
 		configName: string;
 		dialect: string;
@@ -1944,66 +3612,208 @@ export interface NoormEvents extends SettingsEvents {
 	};
 }
 export type NoormEventNames = Events<NoormEvents>;
+/**
+ * Noorm-specific operations accessed via ctx.noorm.
+ *
+ * Domain-aligned sub-namespaces mirror the TUI home screen:
+ * changes, run, db, lock, vault, secrets, templates, transfer, dt, utils.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await createContext({ config: 'dev' })
+ * await ctx.connect()
+ *
+ * await ctx.noorm.run.build()
+ * await ctx.noorm.changes.ff()
+ * const tables = await ctx.noorm.db.listTables()
+ * ```
+ */
+export declare class NoormOps {
+	#private;
+	constructor(state: ContextState);
+	get config(): Config;
+	get settings(): Settings;
+	get identity(): Identity;
+	get observer(): ObserverEngine<NoormEvents>;
+	get changes(): ChangesNamespace;
+	get run(): RunNamespace;
+	get db(): DbNamespace;
+	get lock(): LockNamespace;
+	get vault(): VaultNamespace;
+	get secrets(): SecretsNamespace;
+	get templates(): TemplatesNamespace;
+	get transfer(): TransferNamespace;
+	get dt(): DtNamespace;
+	get utils(): UtilsNamespace;
+}
+/**
+ * Scoped query interface bound to a dedicated impersonated connection.
+ *
+ * All queries route through a single pool connection running under
+ * the impersonated principal. Mirrors Context's query surface without
+ * lifecycle or noorm ops.
+ */
+export interface ImpersonatedScope<DB = unknown, Procs = object, Funcs = object> {
+	kysely: Kysely<DB>;
+	proc: <T = unknown, N extends keyof Procs & string = keyof Procs & string>(name: N, ...args: Procs[N] extends void ? [
+	] : [
+		params: Procs[N]
+	]) => Promise<T[]>;
+	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>;
+	transaction: <T>(fn: (trx: Transaction<DB>) => Promise<T>) => Promise<T>;
+	revert: () => Promise<void>;
+}
+/**
+ * Thrown when impersonation fails.
+ *
+ * Covers unsupported dialects and invalid usernames.
+ */
+export declare class ImpersonationError extends Error {
+	constructor(message: string);
+}
 /**
  * SDK Context implementation.
  *
- * Provides programmatic access to all noorm operations.
+ * 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()
  *
- * // Run queries
- * const users = await ctx.query('SELECT * FROM users')
+ * // Top-level — SQL focused
+ * const users = await ctx.kysely
+ *     .selectFrom('users')
+ *     .selectAll()
+ *     .execute()
+ *
+ * // Noorm operations — under namespace
+ * await ctx.noorm.run.build()
+ * await ctx.noorm.changes.ff()
  *
- * // Clean disconnect
  * await ctx.disconnect()
  * ```
  */
-export declare class Context<DB = unknown> {
+export declare class Context<DB = unknown, Procs = object, Funcs = object> {
 	#private;
 	constructor(config: Config, settings: Settings, identity: Identity, options: CreateContextOptions, projectRoot: string);
-	get config(): Config;
-	get settings(): Settings;
-	get identity(): Identity;
 	get dialect(): Dialect;
 	get connected(): boolean;
-	get observer(): ObserverEngine<NoormEvents>;
 	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.run.build()
+	 * await ctx.noorm.changes.ff()
+	 * const tables = await ctx.noorm.db.listTables()
+	 * ```
+	 */
+	get noorm(): NoormOps;
 	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>;
-	listTables(): Promise<TableSummary[]>;
-	describeTable(name: string, schema?: string): Promise<TableDetail | null>;
-	overview(): Promise<ExploreOverview>;
-	truncate(): Promise<TruncateResult>;
-	teardown(): Promise<TeardownResult>;
-	build(options?: BuildOptions): Promise<BatchResult>;
-	reset(): Promise<void>;
-	runFile(filepath: string, options?: RunOptions): Promise<FileResult>;
-	runFiles(filepaths: string[], options?: RunOptions): Promise<BatchResult>;
-	runDir(dirpath: string, options?: RunOptions): Promise<BatchResult>;
-	applyChange(name: string, options?: ChangeOptions): Promise<ChangeResult>;
-	revertChange(name: string, options?: ChangeOptions): Promise<ChangeResult>;
-	fastForward(): Promise<BatchChangeResult>;
-	getChangeStatus(): Promise<ChangeListItem[]>;
-	getPendingChanges(): Promise<ChangeListItem[]>;
-	getSecret(key: string): string | undefined;
-	acquireLock(options?: LockOptions$1): Promise<Lock$1>;
-	releaseLock(): Promise<void>;
-	getLockStatus(): Promise<LockStatus>;
-	withLock<T>(fn: () => Promise<T>, options?: LockOptions$1): Promise<T>;
-	forceReleaseLock(): Promise<boolean>;
-	renderTemplate(filepath: string): Promise<ProcessResult>;
-	getHistory(limit?: number): Promise<ChangeHistoryRecord[]>;
-	computeChecksum(filepath: string): Promise<string>;
-	testConnection(): Promise<{
-		ok: boolean;
-		error?: string;
-	}>;
+	/**
+	 * 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>;
+	/**
+	 * Execute queries as a specific database principal.
+	 *
+	 * Borrows a dedicated connection from the pool, switches identity
+	 * via dialect-specific SQL, and provides a scoped query interface.
+	 * Two modes: callback (auto-reverts) and explicit (caller reverts).
+	 *
+	 * @example
+	 * ```typescript
+	 * // Callback mode — auto-reverts, even on throw
+	 * const result = await ctx.impersonate('username', async (scope) => {
+	 *     return scope.kysely.selectFrom('users').selectAll().execute();
+	 * });
+	 *
+	 * // Explicit mode — caller owns lifecycle
+	 * const scope = await ctx.impersonate('username');
+	 * const users = await scope.kysely.selectFrom('users').selectAll().execute();
+	 * await scope.revert();
+	 * ```
+	 */
+	impersonate<T>(username: string, fn: (scope: ImpersonatedScope<DB, Procs, Funcs>) => Promise<T>): Promise<T>;
+	impersonate(username: string): Promise<ImpersonatedScope<DB, Procs, Funcs>>;
 }
 /**
  * Error thrown when requireTest is enabled but config.isTest is false.
@@ -2072,7 +3882,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,