@noormdev/sdk 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,2083 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { Kysely } from 'kysely';
+
+/**
+ * Supported database dialects.
+ */
+export type Dialect = "postgres" | "mysql" | "sqlite" | "mssql";
+/**
+ * Database connection configuration.
+ *
+ * @example
+ * ```typescript
+ * const postgresConfig: ConnectionConfig = {
+ *     dialect: 'postgres',
+ *     host: 'localhost',
+ *     port: 5432,
+ *     database: 'myapp',
+ *     user: 'postgres',
+ *     password: 'secret',
+ * }
+ *
+ * const sqliteConfig: ConnectionConfig = {
+ *     dialect: 'sqlite',
+ *     database: './data.db',
+ * }
+ * ```
+ */
+export interface ConnectionConfig {
+	dialect: Dialect;
+	host?: string;
+	port?: number;
+	user?: string;
+	password?: string;
+	database: string;
+	filename?: string;
+	pool?: {
+		min?: number;
+		max?: number;
+	};
+	ssl?: boolean | {
+		rejectUnauthorized?: boolean;
+		ca?: string;
+		cert?: string;
+		key?: string;
+	};
+}
+/**
+ * Full configuration object.
+ *
+ * @example
+ * ```typescript
+ * const config: Config = {
+ *     name: 'dev',
+ *     type: 'local',
+ *     isTest: false,
+ *     protected: false,
+ *     connection: {
+ *         dialect: 'postgres',
+ *         host: 'localhost',
+ *         port: 5432,
+ *         database: 'myapp_dev',
+ *         user: 'postgres',
+ *         password: 'postgres',
+ *     },
+ *     paths: {
+ *         sql: './sql',
+ *         changes: './changes',
+ *     },
+ * }
+ * ```
+ */
+export interface Config {
+	name: string;
+	type: "local" | "remote";
+	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;
+}
+/**
+ * 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
+ * ```yaml
+ * teardown:
+ *     preserveTables:
+ *         - AppSettings
+ *         - UserRoles
+ *     postScript: "sql/teardown/cleanup.sql"
+ * ```
+ */
+export interface TeardownConfig {
+	/** Tables to always preserve during truncate operations */
+	preserveTables?: string[];
+	/** SQL script to run after schema teardown (relative to project root) */
+	postScript?: string;
+}
+/**
+ * Complete settings configuration.
+ *
+ * Stored in .noorm/settings.yml and version controlled.
+ */
+export interface Settings {
+	/** Build configuration */
+	build?: BuildConfig;
+	/** Path overrides */
+	paths?: PathConfig;
+	/** Stage-based rules for conditional include/exclude */
+	rules?: Rule[];
+	/** Preconfigured config templates */
+	stages?: Record<string, Stage>;
+	/** Strict mode requiring specific stages */
+	strict?: StrictConfig;
+	/** Logging configuration */
+	logging?: LoggingConfig;
+	/** Universal secrets required by ALL stages */
+	secrets?: StageSecret[];
+	/** Database teardown/reset configuration */
+	teardown?: TeardownConfig;
+}
+/**
+ * Settings events emitted by the settings module.
+ */
+export interface SettingsEvents {
+	/** Settings loaded from file or defaults */
+	"settings:loaded": {
+		path: string;
+		settings: Settings;
+		fromFile: boolean;
+	};
+	/** Settings saved to disk */
+	"settings:saved": {
+		path: string;
+	};
+	/** Settings file initialized */
+	"settings:initialized": {
+		path: string;
+		force: boolean;
+	};
+	/** Stage added or updated */
+	"settings:stage-set": {
+		name: string;
+		stage: Stage;
+	};
+	/** Stage removed */
+	"settings:stage-removed": {
+		name: string;
+	};
+	/** Rule added */
+	"settings:rule-added": {
+		rule: Rule;
+	};
+	/** Rule removed */
+	"settings:rule-removed": {
+		index: number;
+		rule: Rule;
+	};
+	/** Build config updated */
+	"settings:build-updated": {
+		build: BuildConfig;
+	};
+	/** Paths config updated */
+	"settings:paths-updated": {
+		paths: PathConfig;
+	};
+	/** Strict mode config updated */
+	"settings:strict-updated": {
+		strict: StrictConfig;
+	};
+	/** Logging config updated */
+	"settings:logging-updated": {
+		logging: LoggingConfig;
+	};
+	/** Secret added (universal or stage-scoped) */
+	"settings:secret-added": {
+		secret: StageSecret;
+		scope: "universal" | "stage";
+		stageName?: string;
+	};
+	/** Secret updated (universal or stage-scoped) */
+	"settings:secret-updated": {
+		key: string;
+		secret: StageSecret;
+		scope: "universal" | "stage";
+		stageName?: string;
+	};
+	/** Secret removed (universal or stage-scoped) */
+	"settings:secret-removed": {
+		key: string;
+		scope: "universal" | "stage";
+		stageName?: string;
+	};
+}
+/**
+ * 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;
+}
+/**
+ * Operation status values.
+ *
+ * - pending: Operation started but not finished
+ * - success: Operation completed successfully
+ * - failed: Operation failed with error
+ * - reverted: Operation was reverted
+ * - stale: Operation's schema objects were torn down (needs re-run)
+ */
+export type OperationStatus = "pending" | "success" | "failed" | "reverted" | "stale";
+/**
+ * Direction values.
+ */
+export type Direction = "change" | "revert";
+/**
+ * File execution status values.
+ */
+export type ExecutionStatus = "pending" | "success" | "failed" | "skipped";
+/**
+ * Overview counts for all categories.
+ */
+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;
+}
+/**
+ * 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;
+}
+/**
+ * Overall status of a batch operation.
+ */
+export type BatchStatus = "success" | "failed" | "partial";
+/**
+ * Result of a batch operation (build, dir).
+ *
+ * @example
+ * ```typescript
+ * const result: BatchResult = {
+ *     status: 'success',
+ *     files: [...],
+ *     filesRun: 5,
+ *     filesSkipped: 2,
+ *     filesFailed: 0,
+ *     durationMs: 1234,
+ * }
+ * ```
+ */
+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;
+}
+/**
+ * File extension type in changes.
+ *
+ * - 'sql' for direct SQL files (.sql, .sql.tmpl)
+ * - 'txt' for manifest files referencing build SQL
+ */
+export type ChangeFileType = "sql" | "txt";
+/**
+ * A single file within a change.
+ *
+ * @example
+ * ```typescript
+ * const file: ChangeFile = {
+ *     filename: '001_alter-users.sql',
+ *     path: '/project/changes/2024-01-15-add-users/change/001_alter-users.sql',
+ *     type: 'sql',
+ * }
+ * ```
+ */
+export interface ChangeFile {
+	/** Filename (e.g., "001_alter-users.sql") */
+	filename: string;
+	/** Absolute path to file */
+	path: string;
+	/** File type */
+	type: ChangeFileType;
+	/** For .txt files, the resolved SQL paths (relative to schema dir) */
+	resolvedPaths?: string[];
+	/** Execution status after running */
+	status?: ExecutionStatus;
+	/** Why the file was skipped */
+	skipReason?: string;
+}
+/**
+ * A change with merged disk and database information.
+ *
+ * Used by the list command to show all changes with status.
+ *
+ * @example
+ * ```typescript
+ * const item: ChangeListItem = {
+ *     // From disk
+ *     name: '2024-01-15-add-users',
+ *     path: '/project/changes/...',
+ *     // ...other Change fields
+ *
+ *     // From DB
+ *     status: 'success',
+ *     appliedAt: new Date(),
+ *     // ...other ChangeStatus fields
+ *
+ *     // Computed
+ *     isNew: false,
+ *     orphaned: false,
+ * }
+ * ```
+ */
+export interface ChangeListItem {
+	/** Change name (always present) */
+	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;
+	/** Current status */
+	status: OperationStatus;
+	/** When last applied (null if never) */
+	appliedAt: Date | null;
+	/** Who applied it */
+	appliedBy: string | null;
+	/** When reverted (null if not reverted) */
+	revertedAt: Date | null;
+	/** Error message if failed */
+	errorMessage: string | null;
+	/** True if exists on disk but no DB record */
+	isNew: boolean;
+	/** True if exists in DB but folder deleted from disk */
+	orphaned: boolean;
+}
+/**
+ * Options for executing a change.
+ *
+ * @example
+ * ```typescript
+ * const options: ChangeOptions = {
+ *     force: false,
+ *     dryRun: false,
+ *     preview: false,
+ * }
+ * ```
+ */
+export interface ChangeOptions {
+	/** Re-run even if already applied. Default: false */
+	force?: boolean;
+	/** Render to tmp/ without executing. Default: false */
+	dryRun?: boolean;
+	/** Output rendered SQL without executing. Default: false */
+	preview?: boolean;
+	/** Write preview output to file. Default: null */
+	output?: string | null;
+}
+/**
+ * Result of executing a single change.
+ *
+ * @example
+ * ```typescript
+ * const result: ChangeResult = {
+ *     name: '2024-01-15-add-users',
+ *     direction: 'change',
+ *     status: 'success',
+ *     files: [...],
+ *     durationMs: 1234,
+ * }
+ * ```
+ */
+export interface ChangeResult {
+	/** Change name */
+	name: string;
+	/** Operation direction */
+	direction: Direction;
+	/** Final status */
+	status: OperationStatus;
+	/** Individual file results */
+	files: ChangeFileResult[];
+	/** Total execution time */
+	durationMs: number;
+	/** Error message if failed */
+	error?: string;
+	/** Operation ID in tracking table */
+	operationId?: number;
+}
+/**
+ * Result of executing a single file within a change.
+ */
+export interface ChangeFileResult {
+	/** File path */
+	filepath: string;
+	/** File checksum */
+	checksum: string;
+	/** Execution status */
+	status: ExecutionStatus;
+	/** Why skipped (if skipped) */
+	skipReason?: string;
+	/** Execution time in milliseconds */
+	durationMs?: number;
+	/** Error message if failed */
+	error?: string;
+	/** Rendered SQL (only in preview mode) */
+	renderedSql?: string;
+}
+/**
+ * Result of a batch operation (next, ff, rewind).
+ */
+export interface BatchChangeResult {
+	/** Overall status */
+	status: "success" | "failed" | "partial";
+	/** Results for each change */
+	changes: ChangeResult[];
+	/** Number of changes executed */
+	executed: number;
+	/** Number of changes skipped */
+	skipped: number;
+	/** Number of changes that failed */
+	failed: number;
+	/** Total execution time */
+	durationMs: number;
+}
+/**
+ * A single execution record from history.
+ */
+export interface ChangeHistoryRecord {
+	/** Record ID */
+	id: number;
+	/** Change name */
+	name: string;
+	/** Operation direction */
+	direction: Direction;
+	/** Status */
+	status: OperationStatus;
+	/** When executed */
+	executedAt: Date;
+	/** Who executed */
+	executedBy: string;
+	/** Duration in milliseconds */
+	durationMs: number;
+	/** Error message if failed */
+	errorMessage: string | null;
+	/** Checksum of files */
+	checksum: 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
+ * ```
+ */
+interface Lock$1 {
+	/** Identity string of holder */
+	lockedBy: string;
+	/** When acquired */
+	lockedAt: Date;
+	/** Auto-expiry time */
+	expiresAt: Date;
+	/** Optional reason for acquiring */
+	reason?: string;
+}
+/**
+ * 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',
+ * }
+ * ```
+ */
+interface LockOptions$1 {
+	/**
+	 * 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
+	 */
+	wait?: boolean;
+	/**
+	 * Max time to wait for lock in milliseconds.
+	 *
+	 * Only used if wait is true.
+	 * @default 30_000 (30 seconds)
+	 */
+	waitTimeout?: number;
+	/**
+	 * How often to poll when waiting, in milliseconds.
+	 *
+	 * Only used if wait is true.
+	 * @default 1_000 (1 second)
+	 */
+	pollInterval?: number;
+	/**
+	 * Optional reason for acquiring the lock.
+	 *
+	 * Shown to users who are blocked by this lock.
+	 */
+	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 {
+	/**
+	 * The SQL content (rendered if template, raw if .sql).
+	 */
+	sql: string;
+	/**
+	 * Whether the file was a template.
+	 */
+	isTemplate: boolean;
+	/**
+	 * Render duration in milliseconds (only for templates).
+	 */
+	durationMs?: number;
+}
+/**
+ * SDK Types.
+ *
+ * All interfaces and types for the noorm programmatic SDK.
+ */
+/**
+ * Options for creating an SDK context.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with stored config
+ * const ctx = await createContext({ config: 'dev' })
+ *
+ * // Require test database for safety
+ * const ctx = await createContext({
+ *     config: 'test',
+ *     requireTest: true,
+ * })
+ *
+ * // Allow destructive ops on protected config
+ * const ctx = await createContext({
+ *     config: 'staging',
+ *     allowProtected: true,
+ * })
+ *
+ * // Env-only mode (CI/CD) - no stored config needed
+ * // Requires NOORM_CONNECTION_DIALECT and NOORM_CONNECTION_DATABASE
+ * const ctx = await createContext()
+ *
+ * // Override stored config via NOORM_* env vars
+ * // NOORM_CONNECTION_HOST=override.host
+ * const ctx = await createContext({ config: 'prod' })
+ * ```
+ */
+export interface CreateContextOptions {
+	/**
+	 * Config name from state.
+	 *
+	 * If omitted:
+	 * - Uses `NOORM_CONFIG` env var if set
+	 * - Falls back to env-only mode if `NOORM_CONNECTION_DIALECT`
+	 *   and `NOORM_CONNECTION_DATABASE` are set
+	 */
+	config?: string;
+	/** Project root directory. Defaults to process.cwd() */
+	projectRoot?: string;
+	/** Refuse if config.isTest !== true. Default: false */
+	requireTest?: boolean;
+	/** Allow destructive ops on protected configs. Default: false */
+	allowProtected?: boolean;
+	/** 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.
+ */
+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.
+ *
+ * Enables consistent typing across utility functions and higher-order functions
+ * where function parameters need to be strongly typed.
+ *
+ * @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>
+ */
+export type Func<A extends any[] = any[], R = any> = (...args: A) => R;
+/**
+ * Represents a value that can be either synchronous or asynchronous.
+ *
+ * Critical for utility functions that need to handle both sync and async
+ * operations uniformly, enabling flexible API design.
+ *
+ * @example
+ * function processData<T>(processor: () => MaybePromise<T>): Promise<T>
+ * function transform<T, U>(value: T, transformer: (val: T) => MaybePromise<U>): Promise<U>
+ */
+export type MaybePromise<T> = T | Promise<T>;
+export interface EventGeneratorOptions {
+	signal?: AbortSignal | undefined;
+}
+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;
+}
+declare class ObserverEngine<Shape extends Record<string, any> = Record<string, any>> {
+	#private;
+	constructor(options?: ObserverEngine.Options<Shape>);
+	name: string;
+	/**
+	 * Returns facts about the the internal state of the observable instance.
+	 */
+	$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>;
+}
+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;
+	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;
+	};
+}
+/**
+ * Shutdown phases in order of execution.
+ *
+ * Each phase has a specific purpose in the graceful shutdown sequence.
+ */
+export type ShutdownPhase = "stopping" | "completing" | "releasing" | "flushing" | "exiting";
+/**
+ * Shutdown phase status.
+ */
+export type PhaseStatus = "pending" | "running" | "completed" | "timeout" | "skipped";
+/**
+ * Reasons for shutdown.
+ */
+export type ShutdownReason = "signal" | "user" | "error" | "programmatic";
+/**
+ * Application mode.
+ */
+export type AppMode = "tui" | "headless";
+/**
+ * All events emitted by noorm core modules.
+ *
+ * Events are namespaced by module:
+ * - `file:*` - Individual SQL file execution
+ * - `build:*` - Schema build operations
+ * - `run:*` - Ad-hoc file/dir execution
+ * - `change:*` - Change execution
+ * - `lock:*` - Lock acquisition/release
+ * - `state:*` - State load/persist
+ * - `config:*` - Config CRUD
+ * - `secret:*` - Secret CRUD
+ * - `db:*` - Database lifecycle
+ * - `template:*` - Template rendering
+ * - `identity:*` - Identity resolution
+ * - `connection:*` - Database connections
+ * - `settings:*` - Settings lifecycle and mutations
+ * - `error` - Catch-all errors
+ */
+export interface NoormEvents extends SettingsEvents {
+	"file:before": {
+		filepath: string;
+		checksum: string;
+		configName: string;
+	};
+	"file:after": {
+		filepath: string;
+		status: "success" | "failed";
+		durationMs: number;
+		error?: string;
+	};
+	"file:skip": {
+		filepath: string;
+		reason: "unchanged" | "already-run";
+	};
+	"file:dry-run": {
+		filepath: string;
+		outputPath: string;
+	};
+	"change:created": {
+		name: string;
+		path: string;
+	};
+	"change:start": {
+		name: string;
+		direction: "change" | "revert";
+		files: string[];
+	};
+	"change:file": {
+		change: string;
+		filepath: string;
+		index: number;
+		total: number;
+	};
+	"change:complete": {
+		name: string;
+		direction: "change" | "revert";
+		status: "success" | "failed";
+		durationMs: number;
+	};
+	"change:skip": {
+		name: string;
+		reason: string;
+	};
+	"build:start": {
+		sqlPath: string;
+		fileCount: number;
+	};
+	"build:complete": {
+		status: "success" | "failed" | "partial";
+		filesRun: number;
+		filesSkipped: number;
+		filesFailed: number;
+		durationMs: number;
+	};
+	"run:file": {
+		filepath: string;
+		configName: string;
+	};
+	"run:dir": {
+		dirpath: string;
+		fileCount: number;
+		configName: string;
+	};
+	"lock:acquiring": {
+		configName: string;
+		identity: string;
+	};
+	"lock:acquired": {
+		configName: string;
+		identity: string;
+		expiresAt: Date;
+	};
+	"lock:released": {
+		configName: string;
+		identity: string;
+	};
+	"lock:blocked": {
+		configName: string;
+		holder: string;
+		heldSince: Date;
+	};
+	"lock:expired": {
+		configName: string;
+		previousHolder: string;
+	};
+	"state:loaded": {
+		configCount: number;
+		activeConfig: string | null;
+		version: string;
+	};
+	"state:persisted": {
+		configCount: number;
+	};
+	"state:migrated": {
+		from: string;
+		to: string;
+	};
+	"config:created": {
+		name: string;
+	};
+	"config:updated": {
+		name: string;
+		fields: string[];
+	};
+	"config:deleted": {
+		name: string;
+	};
+	"config:activated": {
+		name: string;
+		previous: string | null;
+	};
+	"secret:set": {
+		configName: string;
+		key: string;
+	};
+	"secret:deleted": {
+		configName: string;
+		key: string;
+	};
+	"global-secret:set": {
+		key: string;
+	};
+	"global-secret:deleted": {
+		key: string;
+	};
+	"known-user:added": {
+		email: string;
+		source: string;
+	};
+	"db:creating": {
+		configName: string;
+		database: string;
+	};
+	"db:created": {
+		configName: string;
+		database: string;
+		durationMs: number;
+	};
+	"db:destroying": {
+		configName: string;
+		database: string;
+	};
+	"db:destroyed": {
+		configName: string;
+		database: string;
+	};
+	"db:bootstrap": {
+		configName: string;
+		tables: string[];
+	};
+	"template:render": {
+		filepath: string;
+		durationMs: number;
+	};
+	"template:load": {
+		filepath: string;
+		format: string;
+	};
+	"template:helpers": {
+		filepath: string;
+		count: number;
+	};
+	"identity:resolved": {
+		name: string;
+		email?: string;
+		source: "state" | "git" | "system" | "config" | "env";
+	};
+	"identity:created": {
+		identityHash: string;
+		name: string;
+		email: string;
+		machine: string;
+	};
+	"identity:registered": {
+		identityHash: string;
+		name: string;
+		email: string;
+	};
+	"identity:synced": {
+		configName: string;
+		registered: boolean;
+		knownUsersCount: number;
+	};
+	"connection:open": {
+		configName: string;
+		dialect: string;
+	};
+	"connection:close": {
+		configName: string;
+	};
+	"connection:error": {
+		configName: string;
+		error: string;
+	};
+	"app:starting": {
+		mode: AppMode;
+	};
+	"app:ready": {
+		mode: AppMode;
+		startedAt: Date;
+	};
+	"app:shutdown": {
+		reason: ShutdownReason;
+		exitCode: number;
+	};
+	"app:shutdown:phase": {
+		phase: ShutdownPhase;
+		status: PhaseStatus;
+		durationMs?: number;
+		error?: Error;
+	};
+	"app:exit": {
+		code: number;
+	};
+	"app:fatal": {
+		error: Error;
+		type?: "exception" | "rejection";
+	};
+	"router:navigated": {
+		from: string;
+		to: string;
+		params: Record<string, string | number | boolean | undefined>;
+	};
+	"router:popped": {
+		popped: string;
+		to: string;
+	};
+	error: {
+		source: string;
+		error: Error;
+		context?: Record<string, unknown>;
+	};
+}
+export type NoormEventNames = Events<NoormEvents>;
+/**
+ * SDK Context implementation.
+ *
+ * Provides programmatic access to all noorm operations.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await createContext({ config: 'dev' })
+ * await ctx.connect()
+ *
+ * // Run queries
+ * const users = await ctx.query('SELECT * FROM users')
+ *
+ * // Clean disconnect
+ * await ctx.disconnect()
+ * ```
+ */
+export declare class Context<DB = unknown> {
+	#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>;
+	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;
+	}>;
+}
+/**
+ * Error thrown when requireTest is enabled but config.isTest is false.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await createContext({
+ *     config: 'prod',
+ *     requireTest: true,  // Will throw RequireTestError
+ * })
+ * ```
+ */
+export declare class RequireTestError extends Error {
+	readonly configName: string;
+	readonly name: "RequireTestError";
+	constructor(configName: string);
+}
+/**
+ * Error thrown when attempting destructive operations on protected configs.
+ *
+ * @example
+ * ```typescript
+ * // If config.protected is true and allowProtected is false
+ * await ctx.truncate()  // Throws ProtectedConfigError
+ * ```
+ */
+export declare class ProtectedConfigError extends Error {
+	readonly configName: string;
+	readonly operation: string;
+	readonly name: "ProtectedConfigError";
+	constructor(configName: string, operation: string);
+}
+/**
+ * Create an SDK context for programmatic database access.
+ *
+ * Configuration is resolved using the full priority chain:
+ * defaults <- stage <- stored <- env <- flags
+ *
+ * This enables:
+ * - ENV var overrides (`NOORM_*`) for stored configs
+ * - Env-only mode (no stored config) for CI/CD
+ *
+ * @param options - Context creation options
+ * @returns Unconnected context (call connect() to use)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with stored config
+ * const ctx = await createContext({ config: 'dev' })
+ * await ctx.connect()
+ *
+ * // Require test database for safety in tests
+ * const ctx = await createContext({
+ *     config: 'test',
+ *     requireTest: true,
+ * })
+ *
+ * // Allow destructive ops on protected config
+ * const ctx = await createContext({
+ *     config: 'staging',
+ *     allowProtected: true,
+ * })
+ *
+ * // Env-only mode (CI/CD) - no stored config needed
+ * // Requires NOORM_CONNECTION_DIALECT and NOORM_CONNECTION_DATABASE
+ * const ctx = await createContext()
+ * ```
+ */
+export declare function createContext<DB = unknown>(options?: CreateContextOptions): Promise<Context<DB>>;
+
+export {
+	Lock$1 as Lock,
+	LockOptions$1 as LockOptions,
+	ProcessResult as TemplateResult,
+};
+
+export {};