@dbsp/types 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,3058 @@
+/**
+ * @module model-ir
+ * ModelIR (Model Intermediate Representation) type definitions.
+ * Represents database tables, columns, and relations with planning metadata.
+ *
+ * Runtime functions (createPseudoColumnMetadata, createRecursiveMetadata, etc.)
+ * remain in @dbsp/core.
+ */
+/** Column data types supported by the planner */
+type ColumnType = 'string' | 'text' | 'number' | 'integer' | 'bigint' | 'decimal' | 'boolean' | 'date' | 'time' | 'datetime' | 'timestamp' | 'json' | 'jsonb' | 'uuid' | 'daterange' | 'tsrange' | 'tstzrange' | 'int4range' | 'int8range' | 'numrange';
+/** Foreign key delete behavior */
+type OnDeleteAction = 'CASCADE' | 'SET NULL' | 'SET DEFAULT' | 'RESTRICT' | 'NO ACTION';
+/** Relation types */
+type RelationType = 'hasOne' | 'hasMany' | 'belongsTo' | 'belongsToMany';
+/**
+ * CLI-NQL: Relation kind for natural query language.
+ * Maps to SQL/database perspective rather than ORM perspective.
+ * - 'many-to-one': Child → Parent (e.g., post.author)
+ * - 'one-to-many': Parent → Children (e.g., author.posts)
+ * - 'many-to-many': M:N via junction (e.g., post.tags)
+ * - 'recursive-up': Ancestors (e.g., category.ancestors)
+ * - 'recursive-down': Descendants (e.g., category.descendants)
+ */
+type RelationKind = 'many-to-one' | 'one-to-many' | 'many-to-many' | 'recursive-up' | 'recursive-down';
+/**
+ * CLI-NQL: Recursive relation metadata.
+ * For self-referential tables like categories with parentId.
+ */
+interface RecursiveMetadata {
+    /**
+     * Direction of traversal.
+     * - 'up': Traverse to ancestors (parent → grandparent → ...)
+     * - 'down': Traverse to descendants (children → grandchildren → ...)
+     */
+    readonly direction: 'up' | 'down';
+    /**
+     * Maximum recursion depth to prevent infinite loops.
+     * @default 10
+     */
+    readonly maxDepth: number;
+    /**
+     * The relation name to follow for recursion.
+     * For 'up': typically 'parent' relation
+     * For 'down': typically 'children' relation
+     */
+    readonly through: string;
+}
+/**
+ * Metadata for auto-generated pseudo-columns from self-referential FKs.
+ * These enable intuitive traversal in NQL: parent.name, ascendant.title, etc.
+ */
+interface PseudoColumnMetadata {
+    /** The table this pseudo-column belongs to */
+    readonly table: string;
+    /** The FK column that creates this self-reference */
+    readonly foreignKeyColumn: string;
+    /** Target column in the same table (usually 'id') */
+    readonly targetColumn: string;
+    /**
+     * Role names for traversal directions.
+     * parentRole: singular upward (e.g., 'parent', 'manager')
+     * childRole: plural downward (e.g., 'children', 'subordinates')
+     */
+    readonly parentRole: string;
+    readonly childRole: string;
+    /**
+     * Keywords for recursive traversal.
+     * ascendantKeyword: recursive upward (e.g., 'ascendant', 'manager.ascendant')
+     * descendantKeyword: recursive downward (e.g., 'descendant', 'manager.descendant')
+     */
+    readonly ascendantKeyword: string;
+    readonly descendantKeyword: string;
+}
+/** Cardinality for planning */
+type Cardinality = 'one' | 'many';
+/** Optionality for join type inference */
+type Optionality = 'required' | 'optional';
+/**
+ * Include strategy for fetching related data.
+ * - 'join': Use JOIN (efficient for to-one, risk of row explosion for to-many)
+ * - 'subquery': Use subquery query (safe for to-many, N+1 if not batched)
+ * - 'cte': Use CTE-based include (good for recursive/hierarchical)
+ * - 'lateral': Use LATERAL JOIN (PostgreSQL/MSSQL CROSS APPLY, handles LIMIT)
+ * - 'json_agg': Use JSON aggregation (PostgreSQL/MySQL/DuckDB, single row per parent)
+ * - 'auto': Planner decides based on relation type + dialect capabilities
+ */
+type IncludeStrategy = 'join' | 'subquery' | 'cte' | 'lateral' | 'json_agg' | 'auto';
+/** Strategy for filtering by relation */
+type FilterStrategy = 'exists' | 'join' | 'auto';
+/** Default join type when joining */
+type JoinDefault = 'left' | 'inner' | 'auto';
+/**
+ * Column definition
+ */
+interface ColumnIR {
+    /** Column name in database */
+    readonly name: string;
+    /** Data type for TypeScript inference */
+    readonly type: ColumnType;
+    /** Whether NULL is allowed */
+    readonly nullable: boolean;
+    /** Default value (optional) */
+    readonly default?: unknown;
+    /**
+     * Original database type string from introspection.
+     * Preserves precision/scale/length info that may be lost in `type`.
+     *
+     * @example
+     * - 'varchar(255)' when type is 'string'
+     * - 'numeric(10,2)' when type is 'number'
+     * - 'timestamptz' when type is 'datetime'
+     *
+     * This is optional and only populated by introspection.
+     * Manually defined schemas may not have this field.
+     */
+    readonly originalDbType?: string;
+    /** Whether column has a UNIQUE constraint */
+    readonly unique?: boolean;
+    /** Whether column auto-increments (SERIAL, IDENTITY, AUTOINCREMENT) */
+    readonly autoIncrement?: boolean;
+    /** Collation name for string columns */
+    readonly collation?: string;
+    /** Column comment (COMMENT ON COLUMN) */
+    readonly comment?: string;
+    /** Identity column generation strategy (GENERATED {ALWAYS|BY DEFAULT} AS IDENTITY) */
+    readonly identity?: 'always' | 'byDefault';
+}
+/**
+ * Foreign key constraint
+ */
+interface ForeignKeyIR {
+    /** Local columns that form the FK */
+    readonly columns: readonly string[];
+    /** Referenced table and columns */
+    readonly references: {
+        readonly table: string;
+        readonly columns: readonly string[];
+    };
+    /** Delete behavior */
+    readonly onDelete?: OnDeleteAction;
+    /** Update behavior */
+    readonly onUpdate?: OnDeleteAction;
+    /** Whether this FK constraint is deferrable (DEFERRABLE INITIALLY DEFERRED) */
+    readonly deferred?: boolean;
+    /** If true, add the constraint WITHOUT scanning existing rows (NOT VALID). Use validate_constraint to validate later. */
+    readonly notValid?: boolean;
+}
+/**
+ * CHECK constraint definition
+ */
+/**
+ * PostgreSQL ENUM type definition
+ */
+/**
+ * PostgreSQL sequence definition
+ */
+interface SequenceIR {
+    /** Sequence name */
+    readonly name: string;
+    /** Start value */
+    readonly startWith?: number;
+    /** Increment step */
+    readonly incrementBy?: number;
+    /** Minimum value */
+    readonly minValue?: number;
+    /** Maximum value */
+    readonly maxValue?: number;
+    /** Whether to cycle */
+    readonly cycle?: boolean;
+    /** Schema name (if not default) */
+    readonly schema?: string;
+}
+interface EnumIR {
+    /** Enum type name */
+    readonly name: string;
+    /** Ordered list of enum values */
+    readonly values: readonly string[];
+    /** Schema name (if not in default schema) */
+    readonly schema?: string;
+}
+interface CheckConstraintIR {
+    /** Constraint name in database */
+    readonly name: string;
+    /** CHECK expression in canonical form (from pg_get_constraintdef) */
+    readonly expression: string;
+    /** If true, add the constraint WITHOUT scanning existing rows (NOT VALID). Use validate_constraint to validate later. */
+    readonly notValid?: boolean;
+}
+/**
+ * Row-Level Security policy definition.
+ *
+ * Models PostgreSQL's CREATE POLICY. Other dialects (Oracle VPD, MSSQL security predicates)
+ * use fundamentally different mechanisms — this interface captures the PG-style model which
+ * is the most common. Adapters without RLS support skip policies via capability negotiation.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   name: 'tenant_isolation',
+ *   command: 'ALL',
+ *   roles: ['app_user'],
+ *   using: "tenant_id = current_setting('app.current_tenant')::uuid",
+ *   withCheck: "tenant_id = current_setting('app.current_tenant')::uuid",
+ * }
+ * ```
+ */
+interface PolicyIR {
+    /** Policy name (must be unique per table) */
+    readonly name: string;
+    /** SQL command the policy applies to (default: ALL) */
+    readonly command?: 'ALL' | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
+    /** Database roles the policy applies to (default: PUBLIC) */
+    readonly roles?: readonly string[];
+    /** Whether the policy is permissive or restrictive (default: PERMISSIVE) */
+    readonly permissive?: boolean;
+    /** USING expression — SQL predicate for row visibility (SELECT, UPDATE, DELETE) */
+    readonly using?: string;
+    /** WITH CHECK expression — SQL predicate for new/modified rows (INSERT, UPDATE) */
+    readonly withCheck?: string;
+}
+/**
+ * Table partition configuration (parent table only).
+ * Child partition management is out of scope (DDL-PARTITION-MGMT).
+ */
+interface PartitionIR {
+    /** Partition strategy */
+    readonly strategy: 'RANGE' | 'LIST' | 'HASH';
+    /** Partition key columns */
+    readonly columns: readonly string[];
+}
+/**
+ * Index definition (single or composite)
+ */
+interface IndexIR {
+    /** Index name (auto-generated if not provided: idx_{table}_{columns}) */
+    readonly name?: string;
+    /** Columns included in the index (1+ columns) */
+    readonly columns: readonly string[];
+    /** Whether this is a unique index */
+    readonly unique?: boolean;
+    /** Index access method (default: btree) */
+    readonly method?: string;
+    /** Partial index predicate (WHERE clause) */
+    readonly where?: string;
+    /** Expression-based index entries (used instead of/alongside columns) */
+    readonly expressions?: readonly string[];
+    /** Non-key columns to include (INCLUDE clause, PG11+) */
+    readonly include?: readonly string[];
+    /** Per-column operator class overrides (non-default only). Key = column name, value = opclass name */
+    readonly opclass?: Readonly<Record<string, string>>;
+    /** Index storage parameters (WITH clause). Key = param name, value = param value */
+    readonly with?: Readonly<Record<string, string>>;
+}
+/**
+ * Table definition
+ */
+interface TableIR {
+    /** Table name in database */
+    readonly name: string;
+    /** Column definitions */
+    readonly columns: readonly ColumnIR[];
+    /** Primary key (single column or composite); omitted for junction tables without explicit PK */
+    readonly primaryKey?: string | readonly string[];
+    /** Foreign key constraints */
+    readonly foreignKeys: readonly ForeignKeyIR[];
+    /** Index definitions */
+    readonly indexes: readonly IndexIR[];
+    /** CHECK constraints */
+    readonly checkConstraints?: readonly CheckConstraintIR[];
+    /**
+     * Auto-generated pseudo-columns from self-referential FKs.
+     * Each self-ref FK generates: parent/child roles + ascendant/descendant keywords.
+     * For multi-FK tables, roles are scoped (e.g., manager.ascendant).
+     */
+    readonly pseudoColumns?: readonly PseudoColumnMetadata[];
+    /** Table-level comment (COMMENT ON TABLE) */
+    readonly comment?: string;
+    /** Partition configuration (parent table). Child management deferred to DDL-PARTITION-MGMT. */
+    readonly partition?: PartitionIR;
+    /** Whether Row-Level Security is enabled on this table */
+    readonly rlsEnabled?: boolean;
+    /** Row-Level Security policies */
+    readonly policies?: readonly PolicyIR[];
+}
+/**
+ * Relation definition with planning metadata
+ */
+interface RelationIR {
+    /** Relation name (used in queries) */
+    readonly name: string;
+    /** Relation type */
+    readonly type: RelationType;
+    /** Source table name */
+    readonly source: string;
+    /** Target table name */
+    readonly target: string;
+    /** Junction table for M:N relations */
+    readonly through?: string | undefined;
+    /** Foreign key column(s) on the "many" side */
+    readonly foreignKey?: string | readonly string[] | undefined;
+    /**
+     * For M:N relations: foreign key column on junction table pointing to target.
+     * Example: In posts-tags via postTags, otherKey = 'tagId'
+     */
+    readonly otherKey?: string | undefined;
+    /** Cardinality affects strategy selection */
+    readonly cardinality: Cardinality;
+    /** Optionality affects LEFT vs INNER join */
+    readonly optionality: Optionality;
+    /**
+     * How to fetch related data when included.
+     * - 'join': Use JOIN (efficient for to-one)
+     * - 'subquery': Use subquery query (avoids row explosion for to-many)
+     * - 'auto': Planner decides based on cardinality
+     * @default 'auto'
+     */
+    readonly includeStrategy: IncludeStrategy;
+    /**
+     * How to filter by this relation.
+     * - 'exists': Use EXISTS subquery (no row multiplication)
+     * - 'join': Use JOIN (may cause row explosion on to-many)
+     * - 'auto': Planner decides (defaults to EXISTS for to-many)
+     * @default 'auto'
+     */
+    readonly filterStrategy: FilterStrategy;
+    /**
+     * Default join type when joining.
+     * - 'left': LEFT JOIN (keep parent even if no child)
+     * - 'inner': INNER JOIN (parent must have child)
+     * - 'auto': Inferred from optionality + filters
+     * @default 'auto'
+     */
+    readonly joinDefault: JoinDefault;
+    /** Column on source table that FK on target references; set when generated relation overrides the default PK. */
+    readonly sourceKey?: string | undefined;
+    /** Column on target table that the FK points to; set when generated relation overrides the default PK. */
+    readonly targetKey?: string | undefined;
+    /**
+     * CLI-NQL: Recursive relation metadata for ancestors/descendants.
+     * Only present for self-referential relations (source === target).
+     */
+    readonly recursive?: RecursiveMetadata | undefined;
+}
+/**
+ * Result of checking for ambiguous relations
+ */
+interface AmbiguityCheckResult {
+    /** Whether the relation path is ambiguous */
+    readonly ambiguous: boolean;
+    /** Available relation names if ambiguous */
+    readonly options: readonly string[];
+}
+/**
+ * Complete model intermediate representation
+ */
+interface ModelIR {
+    /** Table definitions indexed by name */
+    readonly tables: ReadonlyMap<string, TableIR>;
+    /** Relation definitions indexed by "source.name" */
+    readonly relations: ReadonlyMap<string, RelationIR>;
+    /** ENUM type definitions indexed by name */
+    readonly enums?: ReadonlyMap<string, EnumIR>;
+    /** Extension names to ensure (CREATE EXTENSION IF NOT EXISTS) */
+    readonly extensions?: readonly string[];
+    /** Sequence definitions */
+    readonly sequences?: ReadonlyMap<string, SequenceIR>;
+    /**
+     * Get table by logical name.
+     *
+     * @param name - Logical table name (camelCase, e.g. "postComments").
+     *   This is the model-level name, NOT the database name (e.g. "post_comments").
+     *   Use adapter-side naming utilities to convert DB names to logical names.
+     */
+    getTable(name: string): TableIR | undefined;
+    /** Get relation by qualified name "source.relationName" */
+    getRelation(qualifiedName: string): RelationIR | undefined;
+    /** Get all relations from a source table */
+    getRelationsFrom(sourceTable: string): readonly RelationIR[];
+    /** Get all relations to a target table */
+    getRelationsTo(targetTable: string): readonly RelationIR[];
+    /** Check if relation path is ambiguous (multiple relations to same target) */
+    isAmbiguous(sourceTable: string, targetTable: string): AmbiguityCheckResult;
+}
+/**
+ * Hierarchy pattern detected during database introspection.
+ * Describes adjacency-list or edge-table patterns on self-referencing tables.
+ */
+interface HierarchyIR {
+    /** How the hierarchy is represented in the schema */
+    readonly type: 'adjacency' | 'edge-table';
+    /** Table that contains the nodes */
+    readonly nodeTable: string;
+    /** Edge table (for edge-table type only) */
+    readonly edgeTable?: string;
+    /** Column pointing to the parent node (adjacency) or source node (edge-table) */
+    readonly parentColumn: string;
+    /** Column pointing to the child node (edge-table type only) */
+    readonly childColumn?: string;
+    /** Column holding the node's own identifier */
+    readonly nodeIdColumn: string;
+}
+
+/**
+ * @module dialects
+ * Dialect type definitions - DialectCapabilities, DialectName, column type unions.
+ *
+ * Runtime constants (POSTGRESQL_CAPABILITIES, etc.) and functions
+ * (registerDialect, getDialectCapabilities, etc.) remain in @dbsp/core.
+ */
+
+/** Known dialect identifiers */
+type DialectName = 'postgresql' | 'mysql' | 'sqlite' | 'duckdb' | 'mssql';
+/** PostgreSQL-only column types (range types + jsonb) */
+type PostgresOnlyColumnType = 'daterange' | 'tsrange' | 'tstzrange' | 'int4range' | 'int8range' | 'numrange' | 'jsonb';
+/** Column types common to all dialects */
+type CommonColumnType = Exclude<ColumnType, PostgresOnlyColumnType>;
+/** PostgreSQL supports all column types */
+type PostgresColumnType = ColumnType;
+/** MySQL column types (common + json) */
+type MySQLColumnType = CommonColumnType | 'json';
+/** SQLite column types (common + json) */
+type SQLiteColumnType = CommonColumnType | 'json';
+/** DuckDB column types (common + json) */
+type DuckDBColumnType = CommonColumnType | 'json';
+/** MSSQL column types (common + json) */
+type MSSQLColumnType = CommonColumnType | 'json';
+/** Maps a dialect name to its supported column types */
+type SupportedColumnTypes<D extends DialectName> = D extends 'postgresql' ? PostgresColumnType : D extends 'mysql' ? MySQLColumnType : D extends 'sqlite' ? SQLiteColumnType : D extends 'duckdb' ? DuckDBColumnType : D extends 'mssql' ? MSSQLColumnType : CommonColumnType;
+/** Whether a column type is supported in a given dialect */
+type IsTypeSupported<T extends ColumnType, D extends DialectName> = T extends SupportedColumnTypes<D> ? true : false;
+interface DialectCapabilities {
+    /** Dialect identifier (e.g., 'postgresql', 'mysql', 'sqlite') */
+    readonly name: string;
+    /** Supports RETURNING clause for INSERT/UPDATE/DELETE */
+    readonly supportsReturning: boolean;
+    /** Supports recursive CTEs (WITH RECURSIVE) */
+    readonly supportsRecursiveCTE: boolean;
+    /** Supports window functions (ROW_NUMBER, RANK, etc.) */
+    readonly supportsWindowFunctions: boolean;
+    /** Supports native array types (e.g., PostgreSQL ARRAY) */
+    readonly supportsArrayType: boolean;
+    /** Supports native range types (PostgreSQL only: daterange, int4range, etc.) */
+    readonly supportsRangeTypes: boolean;
+    /** Supports native JSON/JSONB types */
+    readonly supportsJsonType: boolean;
+    /** Supports JSON path/extract/contains operators (PG: ->, ->>, @>, <@, ?, #>, #>>) */
+    readonly supportsJsonOperators: boolean;
+    /** Supports schema prefixes (e.g., schema.table) */
+    readonly supportsSchemas: boolean;
+    /**
+     * How to build paths in recursive CTEs.
+     * - 'array': PostgreSQL ARRAY[] || ARRAY[item]
+     * - 'string': MySQL/SQLite CONCAT(path, '/', item)
+     * - 'json': JSON array append
+     */
+    readonly recursivePathStyle: 'array' | 'string' | 'json';
+    /**
+     * String concatenation style.
+     * - 'operator': Uses || operator (PostgreSQL, SQLite)
+     * - 'function': Uses CONCAT() function (MySQL)
+     */
+    readonly stringConcatStyle: 'operator' | 'function';
+    /**
+     * Identifier quoting character.
+     * - '"': PostgreSQL, SQLite (standard SQL)
+     * - '`': MySQL
+     * - '[': MSSQL
+     */
+    readonly identifierQuote: '"' | '`' | '[';
+    /**
+     * Parameter placeholder style.
+     * - 'dollar': $1, $2, $3 (PostgreSQL)
+     * - 'question': ? (MySQL, SQLite)
+     * - 'named': :param (some drivers)
+     */
+    readonly parameterStyle: 'dollar' | 'question' | 'named';
+    /**
+     * Limit/offset syntax.
+     * - 'limit-offset': LIMIT x OFFSET y (most databases)
+     * - 'top': TOP x (MSSQL)
+     * - 'fetch': FETCH FIRST x ROWS ONLY (standard SQL:2008)
+     */
+    readonly limitStyle: 'limit-offset' | 'top' | 'fetch';
+    /**
+     * Boolean literal style.
+     * - 'native': TRUE/FALSE keywords
+     * - 'numeric': 1/0 values
+     */
+    readonly booleanStyle: 'native' | 'numeric';
+    /**
+     * Supports LATERAL JOIN (PostgreSQL) or CROSS APPLY (MSSQL).
+     * Enables per-row subqueries with LIMIT for hasMany relations.
+     */
+    readonly supportsLateralJoin: boolean;
+    /**
+     * Supports JSON aggregation functions.
+     * - PostgreSQL: json_agg(), jsonb_agg()
+     * - MySQL: JSON_ARRAYAGG()
+     * - DuckDB: json_group_array()
+     */
+    readonly supportsJsonAgg: boolean;
+    /** ENUM types (PG: CREATE TYPE, MySQL: inline ENUM(), SQLite: CHECK) */
+    readonly supportsDDLEnumTypes?: boolean;
+    /** Sequences (PG: CREATE SEQUENCE, MySQL: N/A uses AUTO_INCREMENT) */
+    readonly supportsDDLSequences?: boolean;
+    /** Extensions (PG: CREATE EXTENSION, others: N/A or load_extension) */
+    readonly supportsDDLExtensions?: boolean;
+    /** Table partitioning (PG/MySQL: PARTITION BY, SQLite: N/A) */
+    readonly supportsDDLPartitioning?: boolean;
+    /** CHECK constraints (PG/MySQL 8.0.16+/SQLite: CHECK) */
+    readonly supportsDDLCheckConstraints?: boolean;
+    /** ON UPDATE actions on FK (CASCADE, SET NULL, etc.) */
+    readonly supportsDDLOnUpdateFK?: boolean;
+    /** DEFERRABLE INITIALLY DEFERRED on FK constraints */
+    readonly supportsDDLDeferredFK?: boolean;
+    /** Identity columns — GENERATED {ALWAYS|BY DEFAULT} AS IDENTITY */
+    readonly supportsDDLIdentityColumns?: boolean;
+    /** Column collation (COLLATE) */
+    readonly supportsDDLCollation?: boolean;
+    /** COMMENT ON TABLE/COLUMN (PG: COMMENT ON, MySQL: inline COMMENT) */
+    readonly supportsDDLComments?: boolean;
+    /** Non-btree index methods (GIN, GiST, HASH, BRIN, HNSW) */
+    readonly supportsDDLIndexMethods?: boolean;
+    /** Per-column operator class (gin_trgm_ops, vector_cosine_ops) */
+    readonly supportsDDLIndexOpclass?: boolean;
+    /** INCLUDE non-key columns (PG11+, Oracle 18c+, MSSQL) */
+    readonly supportsDDLIndexInclude?: boolean;
+    /** Partial indexes (WHERE clause) */
+    readonly supportsDDLPartialIndexes?: boolean;
+    /** Expression/functional indexes */
+    readonly supportsDDLExpressionIndexes?: boolean;
+    /** Row-Level Security policies (PG: CREATE POLICY, ALTER TABLE ENABLE ROW LEVEL SECURITY) */
+    readonly supportsDDLRowLevelSecurity?: boolean;
+}
+
+/**
+ * Shared utility types used across all @dbsp packages
+ * @module @dbsp/types/shared/utils
+ */
+/**
+ * Sort direction for ORDER BY clauses
+ * @public
+ */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Range value representation for PostgreSQL range types.
+ * Supports: daterange, tsrange, tstzrange, int4range, int8range, numrange
+ * @public
+ */
+interface RangeValue {
+    readonly lower: unknown;
+    readonly upper: unknown;
+    /** Bounds specification: '[)' (default), '[]', '()', '(]' */
+    readonly bounds?: '[)' | '[]' | '()' | '(]';
+}
+
+/**
+ * @module intent/operators
+ * Comparison and logical operator types for intent AST.
+ */
+/** Comparison operators for scalar values */
+type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'isDistinctFrom';
+/** String operators */
+type StringOperator = 'like';
+/** Array operators */
+type ArrayOperator = 'in';
+/** Null operators */
+type NullOperator = 'isNull' | 'isNotNull';
+/** Logical operators */
+type LogicalOperator = 'and' | 'or' | 'not';
+/** Relation filter operators */
+type RelationOperator = 'exists' | 'notExists';
+
+/**
+ * @module intent/recursive-types
+ * Recursive relation types for hierarchical queries.
+ */
+/**
+ * Direction of recursion for ancestors/descendants traversal.
+ * - 'up': Traverse to ancestors (parent → grandparent → ...)
+ * - 'down': Traverse to descendants (children → grandchildren → ...)
+ */
+type RecursiveDirection = 'up' | 'down';
+/**
+ * Options for recursive EXISTS checks.
+ * Used when checking existence through a recursive path (ancestors/descendants).
+ *
+ * @example
+ * // Check if any ancestor has name = 'Electronics'
+ * { direction: 'up', through: 'parent', maxDepth: 10 }
+ */
+interface RecursiveExistsOptions {
+    /** Direction of recursion: up (ancestors) or down (descendants) */
+    readonly direction: RecursiveDirection;
+    /** The relation name to follow for recursion (e.g., 'parent' for ancestors) */
+    readonly through: string;
+    /** Maximum recursion depth (default: 10) */
+    readonly maxDepth?: number;
+}
+
+/**
+ * @module intent/where-intent
+ * Where intent types for filter conditions.
+ */
+
+/**
+ * Typed field reference for cross-table column comparisons in relation filters.
+ *
+ * When using aliased relation filters like `some(orders as o, o.total > minOrder)`,
+ * the RHS `minOrder` is a reference to the parent table's column, not a literal value.
+ * FieldRef captures this distinction so the adapter can compile it as a column reference
+ * instead of a parameterized value.
+ *
+ * @example
+ * // some(rel as r, r.col > bareCol) → value: { kind: 'fieldRef', column: 'bareCol', scope: 'outer' }
+ * // some(rel as r, r.col > r.otherCol) → value: { kind: 'fieldRef', column: 'otherCol', scope: 'inner' }
+ * // some(a as x, some(b as y, y.f > x.g)) → value: { kind: 'fieldRef', column: 'g', scope: 'outer', alias: 'x' }
+ */
+interface FieldRef {
+    readonly kind: 'fieldRef';
+    readonly column: string;
+    readonly scope: 'inner' | 'outer';
+    /** Named alias for outer scope (when referencing a specific outer alias in nested filters) */
+    readonly alias?: string;
+}
+/**
+ * Type guard for FieldRef values
+ */
+declare function isFieldRef(value: unknown): value is FieldRef;
+interface WhereComparisonIntent {
+    readonly kind: 'comparison';
+    readonly field: string;
+    readonly operator: ComparisonOperator;
+    readonly value: unknown;
+    /** JSON path extraction before comparison (e.g., data->'key' = 'val') */
+    readonly jsonPath?: readonly string[];
+    /** JSON extraction mode: 'json' = ->, 'text' = ->> */
+    readonly jsonMode?: 'json' | 'text';
+}
+/**
+ * String filter: field like pattern
+ */
+interface WhereLikeIntent {
+    readonly kind: 'like';
+    readonly field: string;
+    readonly pattern: string;
+    /** Case-insensitive matching */
+    readonly caseInsensitive?: boolean;
+    /** Escape character for LIKE pattern (e.g. '\\' to escape _ and %) */
+    readonly escape?: string;
+}
+/**
+ * Array filter: field in [values]
+ */
+interface WhereInIntent {
+    readonly kind: 'in';
+    readonly field: string;
+    readonly values: readonly unknown[];
+    /** Optional subquery producing the value set (when present, values is empty) */
+    readonly subquery?: QueryIntent;
+}
+/**
+ * Array membership filter using PostgreSQL ANY() operator.
+ * Compiles to: "col" = ANY($N::type[])
+ */
+interface WhereAnyIntent {
+    readonly kind: 'any';
+    readonly field: string;
+    readonly values: readonly unknown[];
+}
+/**
+ * Range operator for PostgreSQL range types.
+ * - overlaps: && (ranges have common points)
+ * - contains: @> (range contains value or range)
+ * - containedBy: <@ (range is contained by another range)
+ */
+type RangeOperator = 'overlaps' | 'contains' | 'containedBy' | 'between';
+/**
+ * Range filter: field overlaps/contains/containedBy range value
+ * PostgreSQL range types: daterange, tsrange, tstzrange, int4range, int8range, numrange
+ *
+ * @example
+ * // Check if booking dates overlap a period
+ * { kind: 'range', field: 'dates', operator: 'overlaps', value: { lower: '2025-01-15', upper: '2025-01-20' } }
+ *
+ * // Check if salary range contains a value
+ * { kind: 'range', field: 'salary_range', operator: 'contains', value: 50000 }
+ */
+interface WhereRangeIntent {
+    readonly kind: 'range';
+    readonly field: string;
+    readonly operator: RangeOperator;
+    /** Can be a RangeValue (for range-to-range ops) or scalar (for contains/containedBy with point) */
+    readonly value: RangeValue | unknown;
+}
+/**
+ * Null filter: field is null / is not null
+ */
+interface WhereNullIntent {
+    readonly kind: 'null';
+    readonly field: string;
+    readonly operator: NullOperator;
+}
+/**
+ * Logical AND: all conditions must match
+ */
+interface WhereAndIntent {
+    readonly kind: 'and';
+    readonly conditions: readonly WhereIntent[];
+}
+/**
+ * Logical OR: at least one condition must match
+ */
+interface WhereOrIntent {
+    readonly kind: 'or';
+    readonly conditions: readonly WhereIntent[];
+}
+/**
+ * Logical NOT: condition must not match
+ */
+interface WhereNotIntent {
+    readonly kind: 'not';
+    readonly condition: WhereIntent;
+}
+/**
+ * Relation exists filter: filter by existence of related records
+ * Critical for Q1 golden test - enables EXISTS subquery strategy
+ *
+ * @example
+ * // Find users who have at least one published post
+ * { kind: 'exists', relation: 'posts', where: { kind: 'comparison', field: 'status', operator: 'eq', value: 'published' } }
+ */
+interface WhereExistsIntent {
+    readonly kind: 'exists';
+    /** Relation name to check existence */
+    readonly relation: string;
+    /** Optional filter on related records */
+    readonly where?: WhereIntent;
+    /**
+     * Recursive options for ancestor/descendant existence checks.
+     * When present, generates a recursive CTE instead of simple EXISTS.
+     */
+    readonly recursive?: RecursiveExistsOptions;
+    /**
+     * Optional JOIN declarations inside the EXISTS subquery.
+     * Keys are relation names (used as aliases), values specify join type.
+     * Enables filtering on joined tables inside the subquery.
+     *
+     * @example
+     * exists('callers', {
+     *   include: { callerFile: { join: 'inner' } },
+     *   where: eq('callerFile.project_id', projectId)
+     * })
+     */
+    readonly include?: Readonly<Record<string, {
+        join?: 'inner' | 'left';
+    }>>;
+}
+/**
+ * Relation not exists filter: filter by absence of related records
+ *
+ * @example
+ * // Find users who have no posts
+ * { kind: 'notExists', relation: 'posts' }
+ */
+interface WhereNotExistsIntent {
+    readonly kind: 'notExists';
+    /** Relation name to check absence */
+    readonly relation: string;
+    /** Optional filter on related records */
+    readonly where?: WhereIntent;
+    /**
+     * Recursive options for ancestor/descendant absence checks.
+     * When present, generates a recursive CTE instead of simple NOT EXISTS.
+     */
+    readonly recursive?: RecursiveExistsOptions;
+    /**
+     * Optional JOIN declarations inside the NOT EXISTS subquery.
+     * Keys are relation names (used as aliases), values specify join type.
+     * Enables filtering on joined tables inside the subquery.
+     *
+     * @example
+     * notExists('callers', {
+     *   include: { callerFile: { join: 'inner' } },
+     *   where: eq('callerFile.project_id', projectId)
+     * })
+     */
+    readonly include?: Readonly<Record<string, {
+        join?: 'inner' | 'left';
+    }>>;
+}
+/**
+ * Raw EXISTS subquery filter using an arbitrary QueryIntent.
+ * Unlike WhereExistsIntent (which uses FK-resolved relation names),
+ * this wraps a fully-specified subquery for correlated EXISTS checks.
+ *
+ * @example
+ * // EXISTS (SELECT 1 FROM symbols WHERE symbols.id = calls.symbol_id AND ...)
+ * exists(subquery('symbols').where(eq('id', ref('calls.symbol_id'))))
+ */
+interface WhereRawExistsIntent {
+    readonly kind: 'rawExists';
+    /** The subquery producing rows for the EXISTS check */
+    readonly subquery: QueryIntent;
+}
+/**
+ * Raw NOT EXISTS subquery filter using an arbitrary QueryIntent.
+ *
+ * @example
+ * // NOT EXISTS (SELECT 1 FROM symbols WHERE ...)
+ * notExists(subquery('symbols').where(...))
+ */
+interface WhereRawNotExistsIntent {
+    readonly kind: 'rawNotExists';
+    /** The subquery producing rows for the NOT EXISTS check */
+    readonly subquery: QueryIntent;
+}
+/**
+ * Relation filter: filter parent by conditions on related records
+ * More flexible than exists - allows filtering by related record attributes
+ *
+ * @example
+ * // Find users whose latest post was created in 2024
+ * { kind: 'relationFilter', relation: 'posts', where: {...}, mode: 'some' }
+ */
+interface WhereRelationFilterIntent {
+    readonly kind: 'relationFilter';
+    /**
+     * Relation path for filtering.
+     * - Single relation: 'posts' or ['posts']
+     * - Multi-hop (SPEC-002): ['author', 'company'] for author.company traversal
+     */
+    readonly relation: string | readonly string[];
+    /** Filter conditions on related records */
+    readonly where: WhereIntent;
+    /**
+     * Match mode:
+     * - 'some': At least one related record matches (default)
+     * - 'every': All related records match
+     * - 'none': No related records match
+     */
+    readonly mode: 'some' | 'every' | 'none';
+    /** Optional alias for complex conditions (SPEC-002) */
+    readonly alias?: string | undefined;
+}
+/**
+ * Reference to a parent query column in a subquery.
+ * Used to create correlated subqueries.
+ *
+ * @example
+ * // Reference parent 'id' column in subquery WHERE
+ * { kind: 'ref', column: 'id' }
+ * { kind: 'ref', column: 't0.id' }  // with alias
+ */
+interface SubqueryRefIntent {
+    readonly kind: 'ref';
+    /** Column name or aliased column (e.g., 'id' or 't0.id') */
+    readonly column: string;
+}
+/**
+ * Subquery intent for scalar subquery comparisons.
+ * Produces correlated subqueries in SQL.
+ *
+ * @example
+ * // Find products where price equals max price of category
+ * {
+ *   kind: 'subquery',
+ *   field: 'price',
+ *   operator: 'eq',
+ *   subquery: { from: 'products', select: { kind: 'aggregate', fn: 'max', field: 'price' } }
+ * }
+ */
+interface WhereSubqueryIntent {
+    readonly kind: 'subquery';
+    /** Field to compare on the parent query */
+    readonly field: string;
+    /** Comparison operator */
+    readonly operator: ComparisonOperator;
+    /** Subquery producing scalar value */
+    readonly subquery: QueryIntent;
+}
+/**
+ * Scalar subquery intent - produces a single value.
+ * Simplified QueryIntent for subquery context.
+ */
+/** @deprecated Use QueryIntent instead — subqueries are full queries with contextual validation */
+type ScalarSubqueryIntent = QueryIntent;
+/**
+ * JSON containment filter: col @> value or col <@ value.
+ * @example { kind: 'jsonContains', field: 'data', value: '{"active":true}', reversed: false }
+ *          → WHERE "data" @> $1
+ */
+interface WhereJsonContainsIntent {
+    readonly kind: 'jsonContains';
+    readonly field: string;
+    readonly value: unknown;
+    /** false = @> (field contains value), true = <@ (field contained by value) */
+    readonly reversed: boolean;
+}
+/**
+ * JSON key existence filter: col ? 'key'.
+ * @example { kind: 'jsonExists', field: 'data', key: 'email' }
+ *          → WHERE "data" ? $1
+ */
+interface WhereJsonExistsIntent {
+    readonly kind: 'jsonExists';
+    readonly field: string;
+    readonly key: string;
+}
+/** WHERE clause using a custom expression with comparison */
+interface WhereExpressionIntent {
+    readonly kind: 'expression';
+    readonly expr: ExpressionIntent;
+    readonly operator: ComparisonOperator;
+    readonly value: unknown;
+}
+/**
+ * Where intent - filter conditions union type
+ * Discriminated union using 'kind' field
+ */
+type WhereIntent = WhereComparisonIntent | WhereLikeIntent | WhereInIntent | WhereAnyIntent | WhereNullIntent | WhereRangeIntent | WhereAndIntent | WhereOrIntent | WhereNotIntent | WhereExistsIntent | WhereNotExistsIntent | WhereRawExistsIntent | WhereRawNotExistsIntent | WhereRelationFilterIntent | WhereSubqueryIntent | WhereJsonContainsIntent | WhereJsonExistsIntent | WhereExpressionIntent;
+
+/** Null handling in sort */
+type NullsPosition = 'first' | 'last';
+/**
+ * Select all columns
+ */
+interface SelectAllIntent {
+    readonly type: 'all';
+}
+/**
+ * Select specific fields
+ */
+interface SelectFieldsIntent {
+    readonly type: 'fields';
+    /** Field names to select */
+    readonly fields: readonly string[];
+}
+/** Aggregate function types */
+type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'array_agg' | 'string_agg';
+/**
+ * Aggregate operation intent
+ * @example { function: 'count' } → COUNT(*)
+ * @example { function: 'sum', field: 'price' } → SUM(price)
+ */
+interface AggregateIntent {
+    /** Aggregate function */
+    readonly function: AggregateFunction;
+    /** Field to aggregate (optional for count without field) */
+    readonly field?: string;
+    /** Alias for result column */
+    readonly as?: string;
+    /** Whether to apply DISTINCT to the aggregate (e.g., COUNT(DISTINCT field)) */
+    readonly distinct?: boolean;
+    /** FILTER (WHERE ...) clause for conditional aggregation */
+    readonly filter?: WhereIntent;
+}
+/**
+ * Select with aggregate functions
+ */
+interface SelectAggregateIntent {
+    readonly type: 'aggregate';
+    /** Aggregate operations */
+    readonly aggregates: readonly AggregateIntent[];
+    /** Non-aggregate fields (for GROUP BY) */
+    readonly fields?: readonly string[];
+}
+/**
+ * Select with expressions (computed columns).
+ * Columns are ExpressionIntent directly - matches NQL compiler output.
+ */
+interface SelectWithExpressionsIntent {
+    readonly type: 'expressions';
+    /** Columns as ExpressionIntent (NQL format) */
+    readonly columns: readonly ExpressionIntent[];
+}
+/**
+ * Select intent - what columns to retrieve
+ */
+type SelectIntent = SelectAllIntent | SelectFieldsIntent | SelectAggregateIntent | SelectWithExpressionsIntent;
+
+/**
+ * @module intent/expression-intent
+ * Expression intent types for computed/derived values in SELECT.
+ */
+
+/**
+ * COALESCE expression: returns first non-null value from a list of fields
+ * @example { kind: 'coalesce', fields: ['name_fr', 'name_en'], as: 'display_name' }
+ *          → COALESCE(name_fr, name_en) AS display_name
+ */
+interface CoalesceExpressionIntent {
+    readonly kind: 'coalesce';
+    /** Fields to check in order (first non-null wins) */
+    readonly fields: readonly string[];
+    /** Required alias for the result column */
+    readonly as: string;
+}
+/**
+ * Raw SQL expression (escape hatch for advanced use cases)
+ * @example { kind: 'raw', sql: 'NOW()', as: 'current_time' }
+ *          → NOW() AS current_time
+ * @warning Use sparingly - bypasses type safety and SQL injection protection
+ */
+interface RawExpressionIntent {
+    readonly kind: 'raw';
+    /** Raw SQL fragment (must be safe, no user input!) */
+    readonly sql: string;
+    /** Required alias for the result column */
+    readonly as: string;
+}
+/**
+ * Simple column expression: just a column reference, optionally aliased
+ * Used by NQL when a column is selected without modification
+ * @example { kind: 'column', column: 'name' }
+ *          → SELECT "name"
+ * @example { kind: 'column', column: 'name', as: 'userName' }
+ *          → SELECT "name" AS "userName"
+ */
+interface ColumnExpressionIntent {
+    readonly kind: 'column';
+    /** Column name to select */
+    readonly column: string;
+    /** Optional alias for the result column */
+    readonly as?: string;
+}
+/**
+ * Column alias expression: simple column reference with alias
+ * Uses native Kysely eb.ref().as() - type-safe and dialect-portable
+ * @example { kind: 'columnAlias', column: 'name', alias: 'userName' }
+ *          → SELECT "name" AS "userName"
+ */
+interface ColumnAliasIntent {
+    readonly kind: 'columnAlias';
+    /** Column name to select */
+    readonly column: string;
+    /** Alias for the result column */
+    readonly alias: string;
+}
+/**
+ * Relation column expression: select a column from a related table
+ * Auto-creates JOIN via include mechanism and selects with custom alias
+ * @example { kind: 'relationColumn', relation: 'category', column: 'name', as: 'categoryName' }
+ *          → SELECT t1."name" AS "categoryName" (where t1 is the joined category table)
+ * @example { kind: 'relationColumn', relation: 'category.parent', column: 'name', as: 'parentCategoryName' }
+ *          → Multi-level join: products → category → parent, select parent.name
+ */
+interface RelationColumnIntent {
+    readonly kind: 'relationColumn';
+    /** Relation path to traverse (dot-separated for multi-level) */
+    readonly relation: string;
+    /** Column name to select from the target relation */
+    readonly column: string;
+    /** Alias for the result column */
+    readonly as: string;
+}
+/**
+ * Aggregate expression intent for SELECT expressions
+ * @example { kind: 'aggregate', function: 'count', as: 'total' } → COUNT(*) AS total
+ * @example { kind: 'aggregate', function: 'sum', field: 'price', as: 'total_price' } → SUM(price) AS total_price
+ * @example { kind: 'aggregate', function: 'count', field: 'id', distinct: true, as: 'unique_count' }
+ *          → COUNT(DISTINCT id) AS unique_count
+ */
+interface AggregateExpressionIntent {
+    readonly kind: 'aggregate';
+    /** Aggregate function */
+    readonly function: AggregateFunction;
+    /** Field to aggregate (or '*' for count) */
+    readonly field: string | '*';
+    /** Alias for result column */
+    readonly as?: string | undefined;
+    /** Whether to apply DISTINCT to the aggregate */
+    readonly distinct?: boolean | undefined;
+    /** Extra arguments for multi-arg aggregates like string_agg(field, separator) */
+    readonly extraArgs?: readonly unknown[] | undefined;
+    /** FILTER (WHERE ...) clause for conditional aggregation */
+    readonly filter?: WhereIntent | undefined;
+}
+/**
+ * Pseudo-column traversal keyword for self-referential relations.
+ * Used by NQL to traverse hierarchical/tree structures.
+ *
+ * Default keywords: 'parent', 'child', 'ascendant', 'descendant'.
+ * Custom keywords are supported via schema configuration
+ * (e.g., 'manager', 'managee' via parentRole/childRole).
+ */
+type PseudoColumnTraversal = string;
+/**
+ * Pseudo-column expression intent for self-referential traversal.
+ * Enables access to columns on related rows in hierarchical structures.
+ *
+ * @example { kind: 'pseudoColumn', traversal: 'parent', targetColumn: 'name', as: 'parent.name' }
+ *          → SELECT parent_row.name AS "parent.name" via CTE join
+ * @example { kind: 'pseudoColumn', traversal: 'ascendant', targetColumn: 'title', as: 'ancestor_title' }
+ *          → Recursive CTE to find all ancestors, return their title column
+ */
+interface PseudoColumnExpressionIntent {
+    readonly kind: 'pseudoColumn';
+    /** Traversal type: single-hop (parent/child) or recursive (ascendant/descendant) */
+    readonly traversal: PseudoColumnTraversal;
+    /** The column to access on the target row(s) */
+    readonly targetColumn: string;
+    /** Alias for result column (required) */
+    readonly as: string;
+    /** Optional bounded depth for ascendant[N] / descendant[N] syntax */
+    readonly depth?: number;
+    /** Custom role name for multi-FK tables (e.g., 'manager' in manager.ascendant) */
+    readonly role?: string;
+    /**
+     * Chained traversals for multi-hop navigation (e.g., parent.parent.name → ['parent', 'parent']).
+     * When present, overrides single `traversal` field. Each element generates a successive self-join.
+     */
+    readonly traversals?: readonly PseudoColumnTraversal[];
+}
+/**
+ * Generic function expression (e.g., now(), upper(name), coalesce(a, b)).
+ * Used for SQL functions that are not aggregates.
+ */
+interface FunctionExpressionIntent {
+    readonly kind: 'function';
+    /** Function name (e.g., 'upper', 'now', 'coalesce') */
+    readonly name: string;
+    /** Function arguments */
+    readonly args: readonly unknown[];
+    /** Alias for result column */
+    readonly as?: string | undefined;
+}
+/**
+ * Scalar subquery in SELECT clause.
+ * Produces a single value from a nested query.
+ */
+interface SubqueryExpressionIntent {
+    readonly kind: 'subquery';
+    /** The nested query */
+    readonly query: QueryIntent;
+    /** Alias for result column */
+    readonly as?: string | undefined;
+}
+/**
+ * Arithmetic expression (e.g., price * quantity).
+ * Binary operation with left operand, operator, and right operand.
+ */
+interface ArithmeticExpressionIntent {
+    readonly kind: 'arithmetic';
+    /** Left operand (column name or value) */
+    readonly left: string | number | unknown;
+    /** Arithmetic operator */
+    readonly operator: '+' | '-' | '*' | '/' | '%';
+    /** Right operand (column name or value) */
+    readonly right: string | number | unknown;
+    /** Alias for result column */
+    readonly as?: string | undefined;
+}
+/**
+ * Literal value expression: string, number, boolean, or null.
+ * Used in CASE THEN/ELSE clauses for constant values.
+ */
+interface LiteralExpressionIntent {
+    readonly kind: 'literal';
+    /** The literal value */
+    readonly value: string | number | boolean | null;
+    /** Optional alias */
+    readonly as?: string | undefined;
+}
+/**
+ * Comparison expression: left operator right.
+ * Used in CASE WHEN conditions.
+ */
+interface ComparisonExpressionIntent {
+    readonly kind: 'comparison';
+    /** Left side column reference */
+    readonly column: string;
+    /** Comparison operator */
+    readonly operator: '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like';
+    /** Right side value */
+    readonly value: unknown;
+}
+/**
+ * CASE expression: conditional logic in SELECT.
+ * CASE WHEN condition THEN result [WHEN ...] [ELSE default] END
+ */
+interface CaseExpressionIntent {
+    readonly kind: 'case';
+    /** Array of WHEN-THEN pairs */
+    readonly when: ReadonlyArray<{
+        readonly condition: WhereIntent;
+        readonly result: ExpressionIntent;
+    }>;
+    /** Optional ELSE clause */
+    readonly else?: ExpressionIntent | undefined;
+    /** Alias for result column */
+    readonly as?: string | undefined;
+}
+/**
+ * JSON path extraction: col->'key' or col->>'key' (chained paths supported).
+ * Also used for function notation: json_extract(col, 'key'), json_extract_text(col, 'key').
+ */
+interface JsonExtractIntent {
+    readonly kind: 'jsonExtract';
+    readonly field: string;
+    readonly path: readonly string[];
+    /** 'json' = returns JSON value (->), 'text' = returns text (->>) */
+    readonly mode: 'json' | 'text';
+    readonly as?: string | undefined;
+}
+/**
+ * JSON containment: col @> value (contains) or col <@ value (contained by).
+ */
+interface JsonContainsIntent {
+    readonly kind: 'jsonContains';
+    readonly field: string;
+    readonly value: unknown;
+    /** true = <@ (contained by), false = @> (contains) */
+    readonly reversed: boolean;
+}
+/**
+ * JSON key existence: col ? 'key'.
+ */
+interface JsonExistsIntent {
+    readonly kind: 'jsonExists';
+    readonly field: string;
+    readonly key: string;
+}
+/**
+ * JSON path extraction with array path: col #> '{a,b}' or col #>> '{a,b}'.
+ */
+interface JsonPathExtractIntent {
+    readonly kind: 'jsonPathExtract';
+    readonly field: string;
+    /** PostgreSQL array literal path, e.g. '{a,b,c}' */
+    readonly path: string;
+    /** 'json' = returns JSON (#>), 'text' = returns text (#>>) */
+    readonly mode: 'json' | 'text';
+    readonly as?: string | undefined;
+}
+/** Custom binary operator expression (e.g., <=> for pgvector) */
+interface CustomOpExpressionIntent {
+    readonly kind: 'customOp';
+    readonly operator: string;
+    readonly left: ExpressionIntent;
+    readonly right: ExpressionIntent;
+    readonly as?: string;
+}
+/** Custom function call (e.g., paradedb.score) */
+/** Represents a single ORDER BY entry inside an aggregate function. */
+interface AggOrderByArg {
+    /** Discriminator to distinguish from regular expression args. */
+    readonly __aggOrderBy: true;
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+interface CustomFnExpressionIntent {
+    readonly kind: 'customFn';
+    readonly name: string;
+    readonly args: readonly ExpressionIntent[];
+    readonly as?: string;
+    /** FILTER (WHERE ...) clause for conditional aggregation */
+    readonly filter?: WhereIntent | undefined;
+    /** ORDER BY clause for ordered aggregates (e.g. array_agg(x ORDER BY y)) */
+    readonly aggOrderBy?: readonly AggOrderByArg[] | undefined;
+}
+/** Column reference in custom expressions */
+interface RefExpressionIntent {
+    readonly kind: 'ref';
+    readonly column: string;
+}
+/** Parameterized value with automatic $N binding */
+interface ParamExpressionIntent {
+    readonly kind: 'param';
+    readonly value: unknown;
+}
+/** Type cast expression */
+interface CastExpressionIntent {
+    readonly kind: 'cast';
+    readonly expr: ExpressionIntent;
+    readonly typeName: string;
+}
+/** Named argument in a function call: name => value */
+interface NamedArgExpressionIntent {
+    readonly kind: 'namedArg';
+    readonly name: string;
+    readonly value: ExpressionIntent;
+}
+/** Star/wildcard expression (*) — used in COUNT(*), SELECT *, etc. */
+interface StarExpressionIntent {
+    readonly kind: 'star';
+}
+/** PostgreSQL ARRAY constructor: ARRAY[item1, item2, ...] */
+interface ArrayExpressionIntent {
+    readonly kind: 'array';
+    readonly elements: readonly ExpressionIntent[];
+    readonly as?: string;
+}
+/** Unary operator expression (e.g., NOT, -, ~) */
+interface UnaryExpressionIntent {
+    readonly kind: 'unary';
+    readonly operator: string;
+    readonly operand: ExpressionIntent;
+    readonly as?: string;
+}
+/**
+ * Expression intent union type - computed/derived values in SELECT
+ * Extensible for future expression types
+ */
+type ExpressionIntent = ColumnExpressionIntent | CoalesceExpressionIntent | RawExpressionIntent | ColumnAliasIntent | RelationColumnIntent | WindowIntent | AggregateExpressionIntent | PseudoColumnExpressionIntent | FunctionExpressionIntent | SubqueryExpressionIntent | ArithmeticExpressionIntent | LiteralExpressionIntent | ComparisonExpressionIntent | CaseExpressionIntent | JsonExtractIntent | JsonContainsIntent | JsonExistsIntent | JsonPathExtractIntent | CustomOpExpressionIntent | CustomFnExpressionIntent | RefExpressionIntent | ParamExpressionIntent | CastExpressionIntent | UnaryExpressionIntent | NamedArgExpressionIntent | StarExpressionIntent | ArrayExpressionIntent;
+/**
+ * Window function types for OVER clause analytics.
+ * - Ranking: row_number, rank, dense_rank (no field required)
+ * - Aggregate: sum, avg, count, min, max (field required)
+ * - Offset: lag, lead (field required, offset/default deferred to P3+)
+ */
+type WindowFunction = 'row_number' | 'rank' | 'dense_rank' | 'sum' | 'avg' | 'count' | 'min' | 'max' | 'lag' | 'lead';
+/**
+ * Order specification for window OVER clause.
+ */
+interface WindowOrderBy {
+    readonly field: string;
+    readonly direction?: 'asc' | 'desc';
+}
+/**
+ * Window function intent for analytics over partitions.
+ * Produces SQL like: ROW_NUMBER() OVER (PARTITION BY x ORDER BY y) AS alias
+ *
+ * @example Row numbering
+ * {
+ *   kind: 'window',
+ *   function: 'row_number',
+ *   alias: 'rn',
+ *   over: { orderBy: [{ field: 'created_at', direction: 'desc' }] }
+ * }
+ *
+ * @example Running total
+ * {
+ *   kind: 'window',
+ *   function: 'sum',
+ *   field: 'amount',
+ *   alias: 'running_total',
+ *   over: { partitionBy: ['account_id'], orderBy: [{ field: 'date' }] }
+ * }
+ */
+interface WindowIntent {
+    readonly kind: 'window';
+    /** Window function to apply */
+    readonly function: WindowFunction;
+    /** Field for aggregate/offset functions (required for sum/avg/count/min/max/lag/lead) */
+    readonly field?: string | undefined;
+    /** Result column alias (required) */
+    readonly alias: string;
+    /** Offset for lag/lead (default: 1 in PostgreSQL) */
+    readonly offset?: number | undefined;
+    /** Default value for lag/lead when row doesn't exist */
+    readonly defaultValue?: unknown;
+    /** OVER clause specification */
+    readonly over: {
+        /** PARTITION BY columns (optional) */
+        readonly partitionBy?: readonly string[] | undefined;
+        /** ORDER BY specification (optional but recommended for ranking) */
+        readonly orderBy?: readonly WindowOrderBy[] | undefined;
+    };
+}
+/**
+ * Ranking window functions (no field required)
+ */
+type RankingWindowFunction = 'row_number' | 'rank' | 'dense_rank';
+/**
+ * Aggregate window functions (field required)
+ */
+type AggregateWindowFunction = 'sum' | 'avg' | 'count' | 'min' | 'max';
+/**
+ * Offset window functions (field required, offset/default deferred)
+ */
+type OffsetWindowFunction = 'lag' | 'lead';
+
+/**
+ * @module intent/include-intent
+ * Include intent types for relation loading and ordering.
+ */
+
+/**
+ * CLI-012c: Options for recursive include (self-referential relations only).
+ *
+ * Enables WITH RECURSIVE CTE generation for hierarchical data traversal
+ * (org charts, category trees, bill of materials).
+ *
+ * For complex recursive queries (bidirectional, custom traversal expressions),
+ * use `RecursiveIntent` directly.
+ *
+ * Note: Named `IncludeRecursiveOptions` to avoid conflict with DX-layer
+ * `RecursiveIncludeOptions` in dx/types.ts.
+ */
+interface IncludeRecursiveOptions {
+    /**
+     * Maximum recursion depth (default: 100).
+     * Safety limit to prevent infinite recursion.
+     * @example maxDepth: 10 - fetch up to 10 levels deep
+     */
+    readonly maxDepth?: number;
+    /**
+     * Track additional metadata during recursion.
+     */
+    readonly track?: {
+        /**
+         * Include depth counter (starts at 0 for root nodes).
+         * Set to true for default column name 'depth', or object for custom alias.
+         */
+        readonly depth?: boolean | {
+            readonly as?: string;
+        };
+        /**
+         * Include path array for cycle detection/debugging.
+         * Set to true for default column name 'path', or object for custom alias.
+         */
+        readonly path?: boolean | {
+            readonly as?: string;
+        };
+    };
+    /**
+     * Foreign key column for recursion.
+     * If not specified, will be inferred from relation definition.
+     * @example 'parentId' for self-referential category tree
+     */
+    readonly foreignKey?: string;
+}
+interface IncludeIntent {
+    /** Relation name to include */
+    readonly relation: string;
+    /** What columns to select from related records */
+    readonly select?: SelectIntent | undefined;
+    /** Filter conditions on related records */
+    readonly where?: WhereIntent | undefined;
+    /** Nested includes for deep loading */
+    readonly include?: readonly IncludeIntent[] | undefined;
+    /**
+     * Explicit relation path for disambiguation.
+     * Use when multiple relations exist between same tables.
+     * @example 'author' or 'editor' when User has both relations to Post
+     */
+    readonly via?: string | undefined;
+    /**
+     * Maximum number of related records to include per parent.
+     * Only effective with LATERAL JOIN strategy (PostgreSQL/DuckDB/MSSQL).
+     * @example limit: 5 - fetch at most 5 related records per parent
+     */
+    readonly limit?: number | undefined;
+    /**
+     * Order by for related records (used with limit).
+     * @example orderBy: [{ field: 'createdAt', direction: 'desc' }]
+     */
+    readonly orderBy?: readonly OrderByIntent[] | undefined;
+    /**
+     * CLI-012c: Enable recursive CTE for self-referential relations.
+     * Only valid when relation.source === relation.target (e.g., categories → parent).
+     *
+     * @example
+     * include: [{
+     *   relation: 'children',
+     *   recursive: { maxDepth: 10, track: { depth: true } }
+     * }]
+     */
+    readonly recursive?: IncludeRecursiveOptions | undefined;
+    /**
+     * NQL v2.1: Override include output strategy for this relation.
+     *
+     * This is an **output strategy** (flat vs nested), not an implementation strategy.
+     * The planner decides the best implementation (join, subquery, lateral, cte)
+     * based on relation type and dialect capabilities.
+     *
+     * - 'auto': Let planner decide freely, including json_agg (default)
+     * - 'flat': Exclude json_agg from candidates; planner picks best flat strategy
+     *
+     * @example
+     * // NQL: orders | select *, customer.* | flat
+     * // Results in: include: [{ relation: 'customer', strategy: 'flat' }]
+     * // Planner then picks lateral, join, subquery, or cte (never json_agg)
+     */
+    readonly strategy?: 'auto' | 'flat' | undefined;
+    /**
+     * Join type for the include when using the 'join' strategy.
+     * - 'left' (default): LEFT JOIN — all root rows returned, NULL for unmatched relations
+     * - 'inner': INNER JOIN — only root rows WITH a matching related record are returned
+     *
+     * Forces the 'join' include strategy (overrides auto-selection).
+     *
+     * @example
+     * // Only return symbols that have a matching file
+     * include('file', { join: 'inner' })
+     * // → INNER JOIN files ON files.id = symbols.file_id
+     * // → Only symbols WITH a matching file are returned
+     */
+    readonly join?: 'inner' | 'left' | undefined;
+}
+/**
+ * OrderBy intent - sort results
+ */
+interface OrderByIntent {
+    /** Field name to sort by */
+    readonly field?: string;
+    /** Expression to sort by (alternative to field) */
+    readonly expression?: ExpressionIntent;
+    /** Sort direction */
+    readonly direction: SortDirection;
+    /**
+     * Where to place NULL values
+     * @default 'last' for 'asc', 'first' for 'desc' (database default)
+     */
+    readonly nulls?: NullsPosition;
+}
+
+/**
+ * Row-level locking intent for SELECT queries (E15).
+ *
+ * Maps to PostgreSQL's FOR UPDATE/SHARE/NO KEY UPDATE/KEY SHARE
+ * with SKIP LOCKED / NOWAIT wait policies.
+ */
+/** Row-level lock strength for SELECT queries. */
+type LockStrength = 'forUpdate' | 'forNoKeyUpdate' | 'forShare' | 'forKeyShare';
+/**
+ * Wait policy when a lock conflict is encountered.
+ *
+ * - `block`: Wait indefinitely (default PostgreSQL behavior)
+ * - `skipLocked`: Skip already-locked rows (job queue pattern)
+ * - `noWait`: Error immediately if any row is locked
+ */
+type LockWaitPolicy = 'block' | 'skipLocked' | 'noWait';
+/** Declarative lock intent for SELECT queries. */
+interface LockIntent {
+    readonly strength: LockStrength;
+    readonly waitPolicy: LockWaitPolicy;
+}
+
+/**
+ * @module intent/query-intent
+ * Query intent - complete query definition, main entry point for the intent AST.
+ */
+
+/**
+ * BatchValues join payload — the data needed to compile an unnest() JOIN.
+ * Embedded inside JoinIntent when the user calls .join(batchValuesRef, ...).
+ */
+type BatchValuesJoinPayload = {
+    /** Column-major data arrays: one array per column */
+    readonly data: readonly unknown[][];
+    /** Column names for the unnest alias clause */
+    readonly columns: readonly string[];
+    /** PostgreSQL type names for CAST ($1::type[]) */
+    readonly types: readonly string[];
+    /** SQL alias (carries over from BatchValuesRef.alias) */
+    readonly alias: string;
+    /** WITH ORDINALITY flag */
+    readonly ordinality: boolean;
+};
+/**
+ * Join intent — represents a SQL JOIN clause on the root query.
+ *
+ * Two discrimination modes (based on `on` presence):
+ * - **Relation mode** (`relation` set, no `on`): FK auto-resolved, like `include` but flat (no hydration).
+ * - **Table mode** (`table` set, `on` required): Explicit table name + ON condition. Required for self-joins.
+ *
+ * @example
+ * ```typescript
+ * // Relation mode — FK auto-resolved
+ * orm.from(calls).join('caller')
+ * orm.from(calls).join('callerFile', { type: 'left' })
+ *
+ * // Table mode — explicit ON condition
+ * orm.from(embeddings).join('embeddings', {
+ *   on: lt(ref('embeddings.id'), ref('e2.id')),
+ *   as: 'e2',
+ *   type: 'inner',
+ * })
+ * ```
+ */
+type JoinIntent = {
+    /** FK-based join — relation name resolved to table + FK automatically */
+    readonly relation: string;
+    readonly table?: never;
+    readonly batchValues?: never;
+    readonly on?: never;
+    readonly alias?: string;
+    readonly type: 'inner' | 'left';
+} | {
+    /** Explicit table join — ON condition required */
+    readonly table: string;
+    readonly relation?: never;
+    readonly batchValues?: never;
+    readonly on: WhereIntent;
+    readonly alias?: string;
+    readonly type: 'inner' | 'left';
+} | {
+    /** BatchValues join — unnest($N::type[],...) AS alias(...) with explicit ON */
+    readonly batchValues: BatchValuesJoinPayload;
+    readonly relation?: never;
+    readonly table?: never;
+    readonly on: WhereIntent;
+    readonly alias?: string;
+    readonly type: 'inner' | 'left';
+};
+/**
+ * Query intent - complete query definition
+ * Main entry point for the intent AST
+ */
+interface QueryIntent {
+    /** Query type - currently only 'select' supported */
+    readonly type: 'select';
+    /** Target table name */
+    readonly from: string;
+    /** Columns to retrieve */
+    readonly select?: SelectIntent;
+    /** Filter conditions */
+    readonly where?: WhereIntent;
+    /** Relations to include */
+    readonly include?: readonly IncludeIntent[];
+    /** Sort order */
+    readonly orderBy?: readonly OrderByIntent[];
+    /**
+     * Fields to group by for aggregate queries.
+     * When specified, SELECT must include only grouped fields and aggregates.
+     */
+    readonly groupBy?: readonly string[];
+    /**
+     * Filter on aggregate results (applied after GROUP BY).
+     * Similar to WHERE but operates on aggregated values.
+     */
+    readonly having?: WhereIntent;
+    /**
+     * Whether to apply SELECT DISTINCT to deduplicate rows.
+     */
+    readonly distinct?: boolean;
+    /**
+     * Columns for PostgreSQL DISTINCT ON (...) clause.
+     * Produces: SELECT DISTINCT ON ("col1", "col2") ...
+     * Takes precedence over `distinct` when set.
+     */
+    readonly distinctOn?: readonly string[];
+    /** Maximum number of rows */
+    readonly limit?: number;
+    /** Number of rows to skip */
+    readonly offset?: number;
+    /**
+     * When true, the adapter wraps the query in SELECT EXISTS(...).
+     * The inner SELECT list is replaced with `1` and the result is `{ exists: boolean }`.
+     */
+    readonly existsWrap?: boolean;
+    /**
+     * Row-level lock for SELECT queries (e.g., FOR UPDATE SKIP LOCKED).
+     * Only valid in SELECT context — incompatible with GROUP BY, set operations.
+     */
+    readonly lock?: LockIntent;
+    /**
+     * Explicit SQL JOIN clauses (non-hydrating, flat result).
+     * Columns from joined tables appear in the flat result row.
+     * Two modes: relation-based (FK auto-resolved) or table-based (explicit ON condition).
+     */
+    readonly joins?: readonly JoinIntent[];
+    /**
+     * When present, the FROM clause is a BatchValues unnest() source instead of a table.
+     * `from` still holds the alias string for column references.
+     */
+    readonly batchValuesSource?: BatchValuesJoinPayload;
+}
+/**
+ * Set operation type: SQL standard set operations.
+ */
+type SetOperationType = 'union' | 'intersect' | 'except';
+/**
+ * Set operation that combines two queries.
+ * The result is a tree: each side can itself be a SetOperationIntent.
+ *
+ * @example
+ * ```
+ * users | select name | union (admins | select name)
+ * → { op: 'union', all: false, left: QueryIntent, right: QueryIntent }
+ * ```
+ */
+interface SetOperationIntent {
+    readonly kind: 'setOperation';
+    readonly op: SetOperationType;
+    readonly all: boolean;
+    readonly left: QueryIntent | SetOperationIntent;
+    readonly right: QueryIntent | SetOperationIntent;
+}
+
+/**
+ * CTE backed by unnest() arrays, optionally with WITH ORDINALITY for 0-based indexing.
+ *
+ * Generates:
+ *   SELECT t."col1", t."col2", (t.ordinality - 1) AS "idx"
+ *   FROM unnest(CAST($1 AS type[]), CAST($2 AS type[])) WITH ORDINALITY AS t("col1", "col2", ordinality)
+ */
+interface UnnestCteIntent {
+    readonly kind: 'unnestCte';
+    readonly name: string;
+    /** Column name → array of values. All arrays must have the same length. */
+    readonly columns: Record<string, readonly unknown[]>;
+    /** Optional column name for the 0-based ordinality index. */
+    readonly indexColumn?: string;
+}
+/**
+ * Full CTE query: one or more CTE definitions + an outer query.
+ */
+/**
+ * CTE backed by explicit base and step QueryIntent instances (WITH RECURSIVE).
+ *
+ * Used by `orm.recursive(name, { base, step })` to build arbitrary
+ * WITH RECURSIVE queries from query builder instances.
+ *
+ * Generates:
+ *   WITH RECURSIVE "name" AS (
+ *     <base SELECT>
+ *     UNION ALL   -- or UNION when unionAll: false
+ *     <step SELECT> [WHERE depth_col < maxDepth]
+ *   )
+ */
+interface RawCteIntent {
+    readonly kind: 'rawCte';
+    readonly name: string;
+    readonly base: QueryIntent;
+    readonly step: QueryIntent;
+    /** When true, use UNION ALL (default). When false, use UNION (deduplicates). */
+    readonly unionAll: boolean;
+    /** Optional depth guard: inject WHERE <depthColumn> < maxDepth in the recursive step. */
+    readonly maxDepth?: number;
+    /** Column name tracking depth in the step query, for maxDepth injection. */
+    readonly depthColumn?: string;
+}
+/**
+ * CTE backed by a standard NQL query (non-recursive, non-unnest).
+ *
+ * Generated by `WITH name AS (query)` syntax in NQL.
+ * Produces: `name AS (SELECT ...)`
+ */
+interface SimpleCteIntent {
+    readonly kind: 'simpleCte';
+    readonly name: string;
+    readonly query: QueryIntent;
+}
+interface CteQueryIntent {
+    readonly kind: 'cteQuery';
+    readonly ctes: readonly (UnnestCteIntent | RawCteIntent | SimpleCteIntent)[];
+    readonly query: QueryIntent;
+}
+
+/**
+ * @module intent/mutation-intent
+ * Mutation intent types for Insert, Update, Delete, Upsert (DX-010).
+ */
+
+/**
+ * Insert intent - insert one or more rows into a table.
+ * @example { type: 'insert', table: 'users', values: [{ name: 'Alice' }] }
+ */
+interface InsertIntent {
+    readonly type: 'insert';
+    /** Target table name */
+    readonly table: string;
+    /** Values to insert (single object or array for bulk insert) */
+    readonly values: readonly Record<string, unknown>[];
+    /**
+     * Columns to return from inserted rows (DX-026).
+     * Requires adapter capability: supportsReturning
+     * @example ['id', 'created_at']
+     */
+    readonly returning?: readonly string[];
+}
+/**
+ * Insert-from intent - insert rows from a SELECT query.
+ * @example { type: 'insert_from', table: 'archived_users', source: 'users', where: {...} }
+ */
+interface InsertFromIntent {
+    readonly type: 'insert_from';
+    /** Target table to insert into */
+    readonly table: string;
+    /** Source table to select from (table name or bound reference) */
+    readonly source: string;
+    /** Optional source query (when source is a bound reference from `| bind`) */
+    readonly sourceQuery?: QueryIntent | undefined;
+    /** Optional column mapping (defaults to same column names) */
+    readonly columns?: readonly string[] | undefined;
+    /** Filter condition for source rows */
+    readonly where?: WhereIntent | undefined;
+    /** Limit number of rows to insert */
+    readonly limit?: number | undefined;
+    /**
+     * Columns to return from inserted rows (DX-026).
+     * Requires adapter capability: supportsReturning
+     * @example ['id', 'created_at']
+     */
+    readonly returning?: readonly string[];
+}
+/**
+ * Upsert from intent - bulk upsert by selecting rows from a source table or CTE.
+ * Produces: INSERT INTO target SELECT ... FROM source ON CONFLICT (columns) DO UPDATE SET ...
+ * @example upsert into authors on id from counts
+ */
+interface UpsertFromIntent {
+    readonly type: 'upsert_from';
+    /** Target table to upsert into */
+    readonly table: string;
+    /** Source table or bound CTE reference */
+    readonly source: string;
+    /** Optional source query (when source is a bound reference from `| bind`) */
+    readonly sourceQuery?: QueryIntent | undefined;
+    /** Conflict target columns for ON CONFLICT */
+    readonly conflictColumns: readonly string[];
+    /** Optional column mapping (defaults to same column names) */
+    readonly columns?: readonly string[] | undefined;
+    /** Filter condition for source rows */
+    readonly where?: WhereIntent | undefined;
+    /** Limit number of rows */
+    readonly limit?: number | undefined;
+    /**
+     * Columns to return from affected rows.
+     * Requires adapter capability: supportsReturning
+     */
+    readonly returning?: readonly string[];
+}
+/**
+ * Update intent - update rows matching a condition.
+ * @example { type: 'update', table: 'users', set: { name: 'Bob' }, where: ... }
+ */
+interface UpdateIntent {
+    readonly type: 'update';
+    /** Target table name */
+    readonly table: string;
+    /** Fields to update with new values */
+    readonly set: Record<string, unknown>;
+    /** Filter condition (required for safety, unless allowAll is true) */
+    readonly where?: WhereIntent;
+    /** Explicitly allow update without WHERE (for updateAll) */
+    readonly allowAll?: boolean;
+    /**
+     * Columns to return from updated rows (DX-026).
+     * Requires adapter capability: supportsReturning
+     * @example ['id', 'updated_at']
+     */
+    readonly returning?: readonly string[];
+}
+/**
+ * Delete intent - delete rows matching a condition.
+ * @example { type: 'delete', table: 'users', where: ... }
+ */
+interface DeleteIntent {
+    readonly type: 'delete';
+    /** Target table name */
+    readonly table: string;
+    /** Filter condition (required for safety, unless allowAll is true) */
+    readonly where?: WhereIntent;
+    /** Explicitly allow delete without WHERE (for deleteAll) */
+    readonly allowAll?: boolean;
+    /**
+     * Relations to cascade delete.
+     * - undefined: no cascade
+     * - true: cascade all relations
+     * - string[]: cascade specific relations
+     */
+    readonly cascade?: boolean | readonly string[];
+    /**
+     * Columns to return from deleted rows (DX-026).
+     * Requires adapter capability: supportsReturning
+     * @example ['id', 'email']
+     */
+    readonly returning?: readonly string[];
+}
+/**
+ * Upsert conflict target - specifies which columns determine uniqueness.
+ */
+type UpsertConflictTarget = {
+    readonly columns: readonly string[];
+} | {
+    readonly constraint: string;
+};
+/**
+ * Upsert conflict action - what to do when conflict occurs.
+ */
+type UpsertConflictAction = {
+    readonly type: 'doNothing';
+} | {
+    readonly type: 'doUpdate';
+    /** Fields to update on conflict. If undefined, updates all non-conflict columns. */
+    readonly set?: Record<string, unknown>;
+    /** Optional WHERE clause for conditional update */
+    readonly where?: WhereIntent;
+};
+/**
+ * Upsert intent - insert or update on conflict (DX-026).
+ * Implements INSERT ... ON CONFLICT ... DO UPDATE/NOTHING pattern.
+ *
+ * @example doNothing
+ * {
+ *   type: 'upsert',
+ *   table: 'users',
+ *   values: [{ email: 'a@b.com', name: 'Alice' }],
+ *   onConflict: { columns: ['email'] },
+ *   action: { type: 'doNothing' }
+ * }
+ *
+ * @example doUpdate
+ * {
+ *   type: 'upsert',
+ *   table: 'users',
+ *   values: [{ email: 'a@b.com', name: 'Alice' }],
+ *   onConflict: { columns: ['email'] },
+ *   action: { type: 'doUpdate', set: { name: 'Alice Updated' } }
+ * }
+ */
+interface UpsertIntent {
+    readonly type: 'upsert';
+    /** Target table name */
+    readonly table: string;
+    /** Values to insert (single object or array for bulk upsert) */
+    readonly values: readonly Record<string, unknown>[];
+    /** Conflict target - columns or constraint name */
+    readonly onConflict: UpsertConflictTarget;
+    /** Action to take on conflict */
+    readonly action: UpsertConflictAction;
+    /**
+     * Columns to return from affected rows (DX-026).
+     * Requires adapter capability: supportsReturning
+     * @example ['id', 'created_at', 'updated_at']
+     */
+    readonly returning?: readonly string[];
+}
+/**
+ * Union of all mutation intents.
+ */
+/**
+ * Batch update intent - update multiple rows using unnest FROM strategy.
+ * Generates: UPDATE "table" SET "col" = t."col" FROM unnest($1::type[], ...) AS t("match", "col") WHERE "table"."match" = t."match"
+ *
+ * @example { type: 'batchUpdate', table: 'calls', matchColumns: ['id'], updates: [{id: 1, callee_id: 42}] }
+ */
+interface BatchUpdateIntent {
+    readonly type: 'batchUpdate';
+    /** Target table name */
+    readonly table: string;
+    /** Column(s) used to match rows (WHERE clause join condition) */
+    readonly matchColumns: readonly string[];
+    /** Array of row objects containing match + update column values */
+    readonly updates: readonly Record<string, unknown>[];
+    /** Optional scalar values applied to ALL rows (non-array SET clause) */
+    readonly scalarSet?: Record<string, unknown>;
+    /** Columns to return from updated rows (RETURNING clause) */
+    readonly returning?: readonly string[];
+    /** Optional WHERE guard applied in addition to match columns (e.g., AND EXISTS(...)) */
+    readonly where?: WhereIntent;
+}
+type MutationIntent = InsertIntent | InsertFromIntent | UpsertFromIntent | UpdateIntent | BatchUpdateIntent | DeleteIntent | UpsertIntent;
+
+/**
+ * @module intent/recursive-intent
+ * Recursive CTE intent types for hierarchical data traversal (RFC-001).
+ */
+
+/**
+ * Node ID expression for recursive CTE anchor.
+ * Used to define the join key for recursive traversal.
+ */
+type RecursiveNodeIdExpr = {
+    readonly kind: 'column';
+    readonly name: string;
+    readonly as?: string;
+} | {
+    readonly kind: 'literal';
+    readonly value: unknown;
+    readonly as?: string;
+} | {
+    readonly kind: 'binary';
+    readonly left: RecursiveNodeIdExpr;
+    readonly op: string;
+    readonly right: RecursiveNodeIdExpr;
+    readonly as?: string;
+};
+/**
+ * Get the alias for a node ID expression.
+ * Used by both planner and compiler for consistent CTE column naming.
+ *
+ * @param expr - The node ID expression
+ * @returns The alias to use (explicit alias, column name, or 'node_id' fallback)
+ */
+declare function getNodeIdAlias(expr: RecursiveNodeIdExpr): string;
+/**
+ * Adjacency-list traversal (self-referential table).
+ * Example: roles.parent_id → roles.id
+ */
+interface AdjacencyTraversal {
+    readonly kind: 'adjacency';
+    /** Table containing hierarchical data */
+    readonly nodeTable: string;
+    /** Primary key column (e.g., "id") */
+    readonly nodeId: string;
+    /** Foreign key pointing to parent (e.g., "parent_id") */
+    readonly parentId: string;
+    /** Traversal direction */
+    readonly direction: 'descendants' | 'ancestors';
+    /** Filter applied to each step (e.g., active = true) */
+    readonly stepWhere?: WhereIntent;
+}
+/**
+ * Edge-table traversal (separate join table).
+ * Example: role_inheritance(from_role_id, to_role_id)
+ */
+interface EdgeTableTraversal {
+    readonly kind: 'edge-table';
+    /** Node table containing hierarchical data */
+    readonly nodeTable: string;
+    /** Edge table containing relationships */
+    readonly edgeTable: string;
+    /** Primary key column in node table (e.g., "id") */
+    readonly nodeId: string;
+    /** Source column in edge table (e.g., "from_role_id") */
+    readonly edgeFrom: string;
+    /** Target column in edge table (e.g., "to_role_id") */
+    readonly edgeTo: string;
+    /** Traversal direction */
+    readonly direction: 'out' | 'in' | 'both';
+    /** Filter on edges (e.g., relationship_type = 'inheritance') */
+    readonly edgeWhere?: WhereIntent;
+    /** Filter on nodes (e.g., active = true) */
+    readonly nodeWhere?: WhereIntent;
+    /** Edge attributes to include in result */
+    readonly edgeSelect?: readonly string[];
+    /**
+     * Hint for edge storage semantics (only affects `direction: 'both'`).
+     *
+     * - 'unknown' (default): Edges may exist in both directions (A→B and B→A).
+     *   Uses UNION (distinct) to avoid duplicates. Safe but slower.
+     * - 'directed-only': Caller guarantees edges are stored once only.
+     *   Uses UNION ALL for performance. INCORRECT if duplicates exist.
+     */
+    readonly edgeStorageHint?: 'unknown' | 'directed-only';
+}
+/**
+ * Custom traversal for complex cases (P2 escape hatch).
+ */
+interface CustomTraversal {
+    readonly kind: 'custom';
+    /** Explicit step query builder - reserved for P2 */
+    readonly stepBuilder?: unknown;
+}
+/**
+ * Recursive traversal type union.
+ */
+type RecursiveTraversal = AdjacencyTraversal | EdgeTableTraversal | CustomTraversal;
+/**
+ * Tracking options for recursive traversal.
+ */
+interface RecursiveTrackOptions {
+    /** Depth counter (starts at 0) */
+    readonly depth?: {
+        readonly as?: string;
+    };
+    /** Path tracking for cycle detection + debugging */
+    readonly path?: {
+        /** Columns to trace in path (default: nodeId only) */
+        readonly by?: 'nodeId' | readonly string[];
+        /** Result column name (default: "path") */
+        readonly as?: string;
+        /** Storage strategy (default: 'array' for PostgreSQL, 'string' for others) */
+        readonly strategy?: 'array' | 'string';
+        /** Separator for string strategy (default: '/') */
+        readonly separator?: string;
+    };
+    /** Cycle detection marker */
+    readonly isCycle?: {
+        readonly as?: string;
+    };
+}
+/**
+ * Join clause for CTE emit composition.
+ * Allows joining the CTE result with additional tables for final projection.
+ */
+interface EmitJoinClause {
+    /** Table to join with */
+    readonly table: string;
+    /** Join type (default: 'inner') */
+    readonly type?: 'inner' | 'left';
+    /** Alias for this table (auto-generated if not provided) */
+    readonly as?: string;
+    /** Join condition */
+    readonly on: {
+        /** Column from CTE or previous joined table */
+        readonly left: string;
+        /** Column from this table */
+        readonly right: string;
+    };
+    /** Columns to select from this table */
+    readonly select?: readonly (string | {
+        readonly column: string;
+        readonly as: string;
+    })[];
+}
+/**
+ * Emit options for recursive CTE final projection.
+ */
+interface RecursiveEmitOptions {
+    /** Fields to select from CTE */
+    readonly select?: readonly string[];
+    /** Filter on generated rows */
+    readonly where?: WhereIntent;
+    /** Ordering */
+    readonly orderBy?: readonly OrderByIntent[];
+    /** Join CTE result with additional tables for composition */
+    readonly joinWith?: readonly EmitJoinClause[];
+    /** Apply DISTINCT to final result */
+    readonly distinct?: boolean;
+}
+/**
+ * PostgreSQL-specific options for recursive CTE (capability-gated).
+ */
+interface RecursiveAdvancedOptions {
+    /**
+     * Cycle detection strategy (adapter-specific implementation).
+     * - 'error': Throw on cycle detection
+     * - 'stop': Stop traversal at cycle (prune branch)
+     * - 'mark': Add is_cycle column to results
+     *
+     * PostgreSQL 14+ uses native CYCLE clause.
+     * Other adapters may use application-level detection.
+     */
+    readonly cycle?: 'error' | 'stop' | 'mark';
+    /**
+     * Traversal search order (adapter-specific implementation).
+     * - 'depth': Depth-first search order
+     * - 'breadth': Breadth-first search order
+     *
+     * PostgreSQL 14+ uses native SEARCH clause.
+     * Other adapters may use ORDER BY on depth column.
+     */
+    readonly search?: 'depth' | 'breadth';
+}
+/**
+ * Deduplication strategy for recursive CTE.
+ *
+ * - 'none': No dedup. May return same node multiple times via different paths.
+ *   Fastest. Use when you need all paths or when graph is known to be a tree.
+ *
+ * - 'final': One row per nodeId in final output.
+ *   Implemented via `DISTINCT ON (nodeId)` (PostgreSQL) or
+ *   `ROW_NUMBER() OVER (PARTITION BY nodeId)` fallback.
+ *   ⚠️ NOT the same as `query.distinct()` which dedupes on entire row!
+ *
+ * Note: 'global' (UNION instead of UNION ALL) was considered but not implemented.
+ * 'final' provides the same end result with better performance characteristics.
+ */
+type RecursiveDedupe = 'none' | 'final';
+/**
+ * Recursive CTE intent for hierarchical data traversal.
+ *
+ * Key invariant: anchor and step MUST produce identical column shape.
+ * The planner validates this and auto-injects nodeIdExpr.
+ *
+ * @see RFC-001 for detailed specification
+ */
+interface RecursiveIntent {
+    readonly type: 'recursive';
+    /** CTE name for the recursive query */
+    readonly cteName: string;
+    readonly start: {
+        /** Source table for anchor query */
+        readonly from: string;
+        /** Filter for seed rows (e.g., where id = $userId) */
+        readonly where?: WhereIntent;
+        /**
+         * REQUIRED: Expression for node ID. Auto-injected into select.
+         * This ensures the recursive join always has the key column.
+         */
+        readonly nodeIdExpr: RecursiveNodeIdExpr;
+        /** Additional fields to select (beyond nodeId) */
+        readonly select?: readonly string[];
+    };
+    /** Traversal configuration (adjacency-list or edge-table) */
+    readonly traversal: RecursiveTraversal;
+    /** Tracking options for depth, path, and cycle detection */
+    readonly track?: RecursiveTrackOptions;
+    /** Maximum recursion depth (REQUIRED) */
+    readonly maxDepth: number;
+    /** Maximum rows (optional safety limit) */
+    readonly maxRows?: number;
+    /** Deduplication strategy */
+    readonly dedupe?: RecursiveDedupe;
+    /** Final projection options */
+    readonly emit?: RecursiveEmitOptions;
+    /** Advanced recursive options (cycle detection, search order) */
+    readonly advancedOptions?: RecursiveAdvancedOptions;
+}
+
+/**
+ * @module intent/type-guards
+ * Type guard functions for all intent AST types.
+ */
+
+/**
+ * Check if an intent is a window function intent
+ */
+declare function isWindowIntent(intent: unknown): intent is WindowIntent;
+/**
+ * Check if a window function requires a field (aggregate or offset functions)
+ */
+declare function isAggregateWindowFunction(fn: WindowFunction): fn is AggregateWindowFunction | OffsetWindowFunction;
+/**
+ * Check if a window function is a ranking function (no field required)
+ */
+declare function isRankingWindowFunction(fn: WindowFunction): fn is RankingWindowFunction;
+/**
+ * Check if a where intent is a comparison
+ */
+declare function isWhereComparison(where: WhereIntent): where is WhereComparisonIntent;
+/**
+ * Check if a where intent is a like filter
+ */
+declare function isWhereLike(where: WhereIntent): where is WhereLikeIntent;
+/**
+ * Check if a where intent is a subquery filter
+ */
+declare function isWhereSubquery(where: WhereIntent): where is WhereSubqueryIntent;
+/**
+ * Check if a value is a subquery ref (column reference in subquery)
+ */
+declare function isSubqueryRef(value: unknown): value is SubqueryRefIntent;
+/**
+ * Check if a where intent is an in filter
+ */
+declare function isWhereIn(where: WhereIntent): where is WhereInIntent;
+/**
+ * Check if a where intent is an any filter (= ANY($N::type[]))
+ */
+declare function isWhereAny(where: WhereIntent): where is WhereAnyIntent;
+/**
+ * Check if a where intent is a null filter
+ */
+declare function isWhereNull(where: WhereIntent): where is WhereNullIntent;
+/**
+ * Check if a where intent is a range filter (PostgreSQL range types)
+ */
+declare function isWhereRange(where: WhereIntent): where is WhereRangeIntent;
+/**
+ * Check if a where intent is a logical AND
+ */
+declare function isWhereAnd(where: WhereIntent): where is WhereAndIntent;
+/**
+ * Check if a where intent is a logical OR
+ */
+declare function isWhereOr(where: WhereIntent): where is WhereOrIntent;
+/**
+ * Check if a where intent is a logical NOT
+ */
+declare function isWhereNot(where: WhereIntent): where is WhereNotIntent;
+/**
+ * Check if a where intent is an exists filter
+ */
+declare function isWhereExists(where: WhereIntent): where is WhereExistsIntent;
+/**
+ * Check if a where intent is a not exists filter
+ */
+declare function isWhereNotExists(where: WhereIntent): where is WhereNotExistsIntent;
+/**
+ * Check if a where intent is a relation filter
+ */
+declare function isWhereRelationFilter(where: WhereIntent): where is WhereRelationFilterIntent;
+/**
+ * Check if a where intent is any relation-based filter
+ */
+declare function isWhereRelationBased(where: WhereIntent): where is WhereExistsIntent | WhereNotExistsIntent | WhereRelationFilterIntent;
+/**
+ * Check if a where intent is a logical operator (and/or/not)
+ */
+declare function isWhereLogical(where: WhereIntent): where is WhereAndIntent | WhereOrIntent | WhereNotIntent;
+/**
+ * Check if a select intent selects all columns
+ */
+declare function isSelectAll(select: SelectIntent): select is SelectAllIntent;
+/**
+ * Check if a select intent selects specific fields
+ */
+declare function isSelectFields(select: SelectIntent): select is SelectFieldsIntent;
+/**
+ * Check if a select intent is an aggregate select
+ */
+declare function isSelectAggregate(select: SelectIntent): select is SelectAggregateIntent;
+/**
+ * Check if a select intent has expressions
+ */
+declare function isSelectWithExpressions(select: SelectIntent): select is SelectWithExpressionsIntent;
+/**
+ * Check if an expression is a COALESCE expression
+ */
+declare function isCoalesceExpression(expr: ExpressionIntent): expr is CoalesceExpressionIntent;
+/**
+ * Check if an expression is a raw SQL expression
+ */
+declare function isRawExpression(expr: ExpressionIntent): expr is RawExpressionIntent;
+/**
+ * Check if an expression is a column alias expression
+ */
+declare function isColumnAliasExpression(expr: ExpressionIntent): expr is ColumnAliasIntent;
+/**
+ * Check if an expression is a relation column expression
+ */
+declare function isRelationColumnExpression(expr: ExpressionIntent): expr is RelationColumnIntent;
+/**
+ * Check if a traversal is adjacency-list based
+ */
+declare function isAdjacencyTraversal(traversal: RecursiveTraversal): traversal is AdjacencyTraversal;
+/**
+ * Check if a traversal is edge-table based
+ */
+declare function isEdgeTableTraversal(traversal: RecursiveTraversal): traversal is EdgeTableTraversal;
+/**
+ * Check if a traversal is custom
+ */
+declare function isCustomTraversal(traversal: RecursiveTraversal): traversal is CustomTraversal;
+/**
+ * Check if an intent is a recursive CTE intent
+ */
+declare function isRecursiveIntent(intent: QueryIntent | RecursiveIntent): intent is RecursiveIntent;
+/**
+ * Check if an intent is an insert intent
+ */
+declare function isInsertIntent(intent: QueryIntent | RecursiveIntent | MutationIntent): intent is InsertIntent;
+/**
+ * Check if an intent is an update intent
+ */
+declare function isUpdateIntent(intent: QueryIntent | RecursiveIntent | MutationIntent): intent is UpdateIntent;
+/**
+ * Check if an intent is a delete intent
+ */
+declare function isDeleteIntent(intent: QueryIntent | RecursiveIntent | MutationIntent): intent is DeleteIntent;
+/**
+ * Check if an intent is an upsert intent (DX-026)
+ */
+declare function isUpsertIntent(intent: QueryIntent | RecursiveIntent | MutationIntent): intent is UpsertIntent;
+/**
+ * Check if an intent is any mutation intent
+ */
+declare function isMutationIntent(intent: QueryIntent | RecursiveIntent | MutationIntent): intent is MutationIntent;
+
+/**
+ * @module planner
+ * Planner type definitions - PlanReport, PlanDecision, PlanWarning, etc.
+ *
+ * Runtime functions (plan(), planRecursive(), etc.) remain in @dbsp/core.
+ */
+
+/**
+ * Decision types made by the planner
+ */
+type DecisionType = 'filter-strategy' | 'join-type' | 'include-strategy' | 'cte-extraction' | 'ambiguity' | 'recursive-cte' | 'bidirectional-edges';
+interface PlanDecision {
+    /** Unique identifier for the decision */
+    readonly id: string;
+    /** Type of decision */
+    readonly type: DecisionType;
+    /** Context: what triggered this decision */
+    readonly context: {
+        /** Source table in the decision */
+        readonly sourceTable: string;
+        /** Target table or relation name */
+        readonly target?: string;
+        /** Relation name if applicable */
+        readonly relation?: string;
+        /** Relation type (belongsTo, hasMany, hasOne, manyToMany) */
+        readonly relationType?: string;
+        /** Intent path (e.g., "where.exists.posts") */
+        readonly intentPath?: string;
+        /** Full relation path for multi-hop (SPEC-002), e.g., "author.company" */
+        readonly relationPath?: string;
+        /** User-provided include alias (e.g., 'author' from .include('author')) */
+        readonly includeAlias?: string;
+        /** Foreign key column(s) for include-strategy (Phase 3) */
+        readonly foreignKey?: string | readonly string[];
+        /** Whether the relation is self-referential (source === target) */
+        readonly isSelfRef?: boolean;
+    };
+    /** The choice made */
+    readonly choice: string;
+    /**
+     * Join type for include-strategy decisions using the 'join' strategy.
+     * Set when the user explicitly requests 'inner' or 'left' via IncludeIntent.join.
+     * When absent, the join handler defaults to LEFT JOIN.
+     */
+    readonly joinType?: 'inner' | 'left';
+    /** Human-readable reasoning */
+    readonly reasoning: string;
+    /** Other options that were available */
+    readonly alternatives: readonly string[];
+}
+type PlanWarningCode = 'AMBIGUOUS_RELATION' | 'POTENTIAL_ROW_EXPLOSION' | 'CIRCULAR_INCLUDE' | 'MISSING_INDEX_HINT' | 'DEEP_NESTING' | 'INVALID_RECURSIVE_INCLUDE' | 'RAW_SQL_USAGE';
+interface PlanWarning {
+    /** Warning code for programmatic handling */
+    readonly code: PlanWarningCode;
+    /** Human-readable message */
+    readonly message: string;
+    /** Suggested action to resolve */
+    readonly suggestion?: string;
+    /** Related decision ID if applicable */
+    readonly relatedDecision?: string;
+}
+interface CTEDefinition {
+    /** CTE name (used in WITH clause) */
+    readonly name: string;
+    /** Purpose of this CTE */
+    readonly purpose: string;
+    /** Which query parts reference this CTE */
+    readonly referencedBy: readonly string[];
+    /** The intent fragment this CTE represents */
+    readonly sourceIntent: string;
+    /**
+     * CLI-012c: Whether this CTE should use WITH RECURSIVE.
+     * Set when include.recursive is specified and relation is self-referential.
+     */
+    readonly recursive?: boolean;
+}
+interface PlanReport {
+    /** Root table for the query */
+    readonly rootTable: string;
+    /** All decisions made during planning */
+    readonly decisions: readonly PlanDecision[];
+    /** Warnings about the plan */
+    readonly warnings: readonly PlanWarning[];
+    /** CTEs to be extracted */
+    readonly ctes: readonly CTEDefinition[];
+    /** Original intent (for reference) */
+    readonly intent: QueryIntent;
+    /** Planning metadata */
+    readonly metadata: {
+        /** Planning duration in ms */
+        readonly planningTimeMs: number;
+        /** Number of relations traversed */
+        readonly relationsAnalyzed: number;
+        /** Whether the plan is ambiguous */
+        readonly isAmbiguous: boolean;
+        /** Ambiguous relation options (if isAmbiguous) */
+        readonly ambiguousOptions?: readonly string[];
+    };
+}
+interface PlanOptions {
+    /**
+     * Force a specific filter strategy (overrides auto-detection)
+     */
+    forceFilterStrategy?: 'exists' | 'join';
+    /**
+     * Force a specific join type (overrides auto-detection)
+     */
+    forceJoinType?: 'left' | 'inner';
+    /**
+     * Enable CTE extraction for repeated subqueries
+     * @default true
+     */
+    enableCTEs?: boolean;
+    /**
+     * Threshold for CTE extraction (min references)
+     * @default 2
+     */
+    cteThreshold?: number;
+    /**
+     * Maximum include depth before warning
+     * @default 5
+     */
+    maxIncludeDepth?: number;
+    /**
+     * Disambiguation hints for ambiguous relations
+     * Map of "sourceTable.targetTable" -> relation name
+     */
+    disambiguate?: Record<string, string>;
+    /**
+     * Default include strategy for relations when set to 'auto'.
+     * - 'join': Use JOIN (single query, database optimizes) - RECOMMENDED for to-one
+     * - 'subquery': Use subquery queries (N+1 style with batching) - safe for to-many
+     * - 'cte': Use CTE-based include (good for recursive/hierarchical)
+     * - 'lateral': Use LATERAL JOIN (PostgreSQL) / CROSS APPLY (MSSQL)
+     * - 'json_agg': Use JSON aggregation (PostgreSQL/MySQL/DuckDB)
+     * - 'auto': Smart selection based on relation type + dialect capabilities
+     * @default 'auto'
+     */
+    defaultIncludeStrategy?: IncludeStrategy;
+    /**
+     * Dialect capabilities for smart strategy selection.
+     * When provided, 'auto' strategy uses dialect-aware selection.
+     * When absent, 'auto' falls back to 'join'.
+     */
+    dialectCapabilities?: DialectCapabilities;
+}
+interface RecursivePlanReport extends Omit<PlanReport, 'intent' | 'metadata'> {
+    readonly intent: RecursiveIntent;
+    readonly metadata: PlanReport['metadata'] & {
+        readonly isRecursive: true;
+        readonly traversalKind: 'adjacency' | 'edge-table' | 'custom';
+        readonly usesBidirectional: boolean;
+        readonly dedupeStrategy: 'none' | 'final';
+    };
+}
+interface RecursivePlanOptions {
+    /** Force bidirectional edge handling strategy */
+    readonly forceBidirectionalStrategy?: 'union' | 'union-all';
+}
+/** Include strategy after 'auto' has been resolved to a concrete strategy */
+type ResolvedIncludeStrategy = Exclude<IncludeStrategy, 'auto'>;
+
+/**
+ * @module adapter
+ * Adapter interface type definitions.
+ *
+ * Runtime functions (assertCapability, supportsExecution, etc.) and
+ * error classes (AdapterRequiredError, UnsupportedCapabilityError)
+ * remain in @dbsp/core.
+ */
+
+/**
+ * Minimal logger interface for adapter debug/error logging.
+ * Adapters accept an optional logger for observability without
+ * coupling to any specific logging framework.
+ */
+interface AdapterLogger {
+    debug?(message: string, ...args: unknown[]): void;
+    warn?(message: string, ...args: unknown[]): void;
+    error?(message: string, ...args: unknown[]): void;
+}
+/**
+ * Adapter capabilities - what the underlying database/ORM supports.
+ * Used for feature detection and graceful degradation.
+ */
+interface AdapterCapabilities {
+    readonly supportsReturning: boolean;
+    readonly supportsSchemas: boolean;
+    readonly supportsStreaming: boolean;
+    readonly supportsRecursiveCTE: boolean;
+    readonly supportsWindowFunctions: boolean;
+    readonly supportsArrayType: boolean;
+}
+/**
+ * A compiled query ready for execution.
+ *
+ * @typeParam T - The expected result type (phantom type for inference)
+ */
+interface CompiledQuery<T = unknown> {
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+    /** Phantom type for result inference - not used at runtime */
+    readonly __resultType?: T;
+}
+/**
+ * Base compile options shared across all adapters.
+ * Adapters can extend this with adapter-specific options.
+ */
+interface CompileOptionsBase {
+    /** Schema name for schema-scoped/multi-tenant queries */
+    readonly schemaName?: string;
+    /** Query name for logging */
+    readonly queryName?: string;
+    /** Correlation ID for distributed tracing */
+    readonly correlationId?: string;
+    /**
+     * Row count threshold for switching INSERT compilation from VALUES to unnest strategy.
+     * Rows <= threshold use VALUES ($1,$2),... Rows > threshold use SELECT unnest($1::type[]),...
+     * Set to 0 to force unnest for all batch sizes.
+     * @default 50
+     */
+    readonly batchThreshold?: number;
+    /**
+     * Maximum allowed batch size for INSERT operations.
+     * If set and the number of rows exceeds this limit, an InvalidOperationError is thrown.
+     * Useful to prevent accidental unbounded inserts.
+     * @default undefined (no limit)
+     */
+    readonly maxBatchSize?: number;
+}
+/**
+ * Options for streaming query results.
+ */
+interface AdapterStreamOptions {
+    /** Number of rows to fetch per chunk */
+    readonly chunkSize?: number;
+}
+/**
+ * Alias mode for included relation columns.
+ *
+ * - `'always'` (default): Alias all columns from included tables (e.g., `"author.id"`, `"author.name"`)
+ * - `'onCollision'`: Only alias columns that exist in multiple tables (e.g., `id`, `createdAt`)
+ *
+ * Note: `'never'` is intentionally excluded as it would cause data loss from duplicate column names.
+ */
+type AliasIncludedColumnsMode = 'always' | 'onCollision';
+/**
+ * Describes the casing convention used for column names in the database.
+ * This is the intuitive "what does your DB look like?" type:
+ *
+ * - `'snake_case'`: DB columns use snake_case → adapter transforms to camelCase for JS
+ * - `'camelCase'`: DB columns use camelCase → no transformation needed
+ * - `'preserve'`: No transformation applied
+ */
+type DbCasing = 'snake_case' | 'camelCase' | 'preserve';
+/**
+ * Options for query compilation.
+ * Extends CompileOptionsBase with core-specific options.
+ */
+interface CompileOptions extends CompileOptionsBase {
+    /** Model IR for relation lookups during compilation */
+    readonly model?: ModelIR;
+    /**
+     * Alias mode for included relation columns.
+     * @default 'always'
+     */
+    readonly aliasIncludedColumns?: AliasIncludedColumnsMode;
+}
+/**
+ * Metadata for a subquery include query.
+ * Used when planner decides include-strategy: 'subquery' for hasMany/manyToMany relations.
+ */
+interface SubqueryIncludeInfo {
+    /** Name of the relation being included */
+    readonly relationName: string;
+    /** Target table to fetch from */
+    readonly targetTable: string;
+    /** Foreign key column(s) in target table */
+    readonly foreignKey: string | readonly string[];
+    /** Source key column(s) in parent table */
+    readonly sourceKey: string | readonly string[];
+    /** Optional select clause from include intent */
+    readonly select?: SelectIntent;
+    /** Optional where clause from include intent */
+    readonly where?: WhereIntent;
+    /** Optional nested includes (for recursive hydration) */
+    readonly nestedIncludes?: readonly SubqueryIncludeInfo[];
+    /** Junction table for M:N relations (e.g., 'postTags') */
+    readonly through?: string;
+    /** FK in junction table pointing to source (e.g., 'postId') */
+    readonly throughSourceKey?: string;
+    /** FK in junction table pointing to target (e.g., 'tagId') */
+    readonly throughTargetKey?: string;
+    /** Relation type for to-one unwrapping (belongsTo/hasOne → single object) */
+    readonly relationType?: string;
+    /** Source/parent table name for subquery optimization */
+    readonly sourceTable?: string;
+    /** Parent query's WHERE conditions for subquery optimization */
+    readonly parentWhere?: WhereIntent;
+}
+/**
+ * Result of compiling a query with subquery includes.
+ */
+interface CompileResultWithIncludes<T = unknown> {
+    /** The main query (includes any JOIN includes) */
+    readonly main: CompiledQuery<T>;
+    /** Metadata for subquery include queries (empty if all includes use JOIN) */
+    readonly subqueryIncludes: readonly SubqueryIncludeInfo[];
+}
+/**
+ * Metadata for a query dump.
+ */
+interface DumpMeta {
+    readonly schema?: string;
+    readonly queryName?: string;
+    readonly correlationId?: string;
+    readonly compiledAt?: Date;
+}
+/**
+ * A dump contains the plan, compiled SQL, and parameters for observability.
+ */
+interface Dump {
+    readonly plan?: PlanReport | undefined;
+    readonly sql: string;
+    readonly params: readonly unknown[];
+    readonly meta?: DumpMeta;
+}
+/**
+ * Base adapter interface - core capabilities all adapters must have.
+ */
+interface BaseAdapter {
+    /** Adapter capabilities for feature detection */
+    readonly capabilities: AdapterCapabilities;
+    /**
+     * Dialect capabilities for planner strategy selection.
+     * Determines which SQL features the adapter's database supports
+     * (LATERAL JOIN, json_agg, window functions, etc.).
+     */
+    readonly dialectCapabilities: DialectCapabilities;
+    /**
+     * Validate an identifier (table name, column name, schema name).
+     * Throws if the identifier contains unsafe characters.
+     */
+    validateIdentifier(value: string, type: string): void;
+}
+/**
+ * Compiling adapter - can compile plans to SQL queries.
+ */
+interface CompilingAdapter extends BaseAdapter {
+    /** Compile a plan to executable SQL. */
+    compile<T = unknown>(plan: PlanReport, options?: CompileOptions): CompiledQuery<T>;
+    /** Compile a plan with includes, returning subquery include metadata (DX-033). */
+    compileWithIncludes<T = unknown>(plan: PlanReport, options?: CompileOptions): CompileResultWithIncludes<T>;
+    /** Compile a subquery include query for given parent IDs (DX-033). */
+    compileSubqueryInclude(info: SubqueryIncludeInfo, parentIds: readonly unknown[], options?: CompileOptions): CompiledQuery;
+    /** Compile an insert intent to executable SQL. */
+    compileInsert(intent: InsertIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile an insert-from intent to executable SQL (NQL-ALIGN). */
+    compileInsertFrom(intent: InsertFromIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile an update intent to executable SQL. */
+    compileUpdate(intent: UpdateIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile a batch update intent to executable SQL (BATCH-001). */
+    compileBatchUpdate(intent: BatchUpdateIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile a delete intent to executable SQL. */
+    compileDelete(intent: DeleteIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile an upsert intent to executable SQL (DX-026). */
+    compileUpsert(intent: UpsertIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile an upsert-from intent to executable SQL (NQL-BIND). */
+    compileUpsertFrom(intent: UpsertFromIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile a recursive CTE plan to executable SQL. */
+    compileRecursive(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    /** Compile a CTE query backed by unnest() arrays (BATCH-001). */
+    compileCteQuery(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery;
+    /** Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL. */
+    compileSetOperation(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    /** Compile a FROM-less SELECT expression to SQL (e.g. SELECT nextval('seq')). */
+    compileSelectExpression(expr: ExpressionIntent): CompiledQuery;
+    /** Create a dump for observability. */
+    createDump(plan: PlanReport, query: CompiledQuery, meta?: DumpMeta): Dump;
+}
+/**
+ * Executing adapter - can execute compiled queries.
+ */
+interface ExecutingAdapter extends BaseAdapter {
+    /** Execute a query and return all results. */
+    execute<T>(query: CompiledQuery<T>): Promise<T[]>;
+    /** Execute a query and return the first result or null. */
+    executeOne<T>(query: CompiledQuery<T>): Promise<T | null>;
+    /** Execute a query and return the first result or throw. */
+    executeOneOrThrow<T>(query: CompiledQuery<T>): Promise<T>;
+}
+/**
+ * Streaming adapter - can stream query results.
+ */
+interface StreamingAdapter extends BaseAdapter {
+    /** Stream query results as an async iterable iterator. */
+    stream<T>(query: CompiledQuery<T>, options?: AdapterStreamOptions): AsyncIterableIterator<T>;
+}
+/**
+ * Options for database introspection.
+ */
+interface IntrospectionOptions {
+    /** Schema name to introspect (default: 'public' for PostgreSQL) */
+    readonly schema?: string;
+    /** Tables to include (default: all). Applied before exclude. */
+    readonly include?: readonly string[];
+    /** Tables to exclude (glob patterns: * matches any chars) */
+    readonly exclude?: readonly string[];
+}
+/**
+ * Result of database introspection.
+ * Extends ModelIR with introspection-specific metadata.
+ */
+interface IntrospectionResult extends ModelIR {
+    /** Timestamp when introspection was performed */
+    readonly introspectedAt: Date;
+    /** Warnings from introspection (e.g., unsupported types) */
+    readonly warnings?: readonly string[];
+    /** Hierarchy patterns detected during introspection (adjacency-list / edge-table) */
+    readonly hierarchies?: readonly HierarchyIR[];
+}
+/**
+ * Introspecting adapter - can introspect database schema.
+ */
+interface IntrospectingAdapter extends BaseAdapter {
+    /** Database column casing convention */
+    readonly dbCasing?: DbCasing;
+    /** Introspect the database schema and return a ModelIR. */
+    introspect(options?: IntrospectionOptions): Promise<IntrospectionResult>;
+}
+/**
+ * Transactional adapter - supports database transactions.
+ */
+interface TransactionalAdapter<DB = unknown> extends BaseAdapter {
+    /** Execute a callback within a database transaction. */
+    transaction<T>(fn: (adapter: Adapter<DB>) => Promise<T>): Promise<T>;
+    /** Create a schema-scoped adapter for multi-tenant queries. */
+    withSchema(schemaName: string): Adapter<DB>;
+}
+/**
+ * Raw SQL adapter - can execute raw SQL directly.
+ *
+ * @warning **SECURITY RISK: POTENTIAL SQL INJECTION**
+ * Use parameter placeholders ($1, $2, etc.) for ALL values.
+ */
+interface RawSqlAdapter extends BaseAdapter {
+    /**
+     * Execute raw SQL directly - the ultimate escape hatch.
+     *
+     * @param sql - Raw SQL string with parameter placeholders
+     * @param parameters - Parameter values (safely bound by driver)
+     */
+    executeRaw<T = unknown>(sql: string, parameters?: readonly unknown[]): Promise<T[]>;
+}
+/**
+ * PostgreSQL index access method.
+ */
+type IndexMethod = 'btree' | 'hash' | 'gist' | 'gin' | 'brin' | 'hnsw' | 'ivfflat' | 'bm25';
+/** A column reference in an index: either a column name or an expression. */
+type IndexColumnDef = string | {
+    expression: string;
+    opclass?: string;
+};
+/** Options for CREATE INDEX. */
+type CreateIndexOptions = {
+    name: string;
+    columns: IndexColumnDef[];
+    method?: IndexMethod;
+    opclass?: Record<string, string>;
+    include?: string[];
+    with?: Record<string, unknown>;
+    where?: string;
+    unique?: boolean;
+    ifNotExists?: boolean;
+    concurrently?: boolean;
+};
+/** Options for DROP INDEX. */
+type DropIndexOptions = {
+    ifExists?: boolean;
+    cascade?: boolean;
+    concurrently?: boolean;
+    schema?: string;
+};
+/** Options for VACUUM. */
+type VacuumOptions = {
+    full?: boolean;
+    analyze?: boolean;
+};
+/** Options for TRUNCATE. */
+type TruncateOptions = {
+    cascade?: boolean;
+    restartIdentity?: boolean;
+};
+/** Options for ALTER COLUMN. */
+type AlterColumnOptions = {
+    type?: string;
+    using?: string;
+    setNotNull?: boolean;
+    setDefault?: unknown;
+    dropDefault?: boolean;
+};
+/** Index metadata returned by listIndexes(). */
+type IndexInfo = {
+    name: string;
+    definition: string;
+    unique: boolean;
+    method: string;
+};
+/**
+ * Optional mixin for adapters that can generate table-scoped DDL SQL strings.
+ * When present on an adapter, buildTableDDL in core delegates SQL generation
+ * to these methods instead of generating SQL inline.
+ */
+interface TableDDLGeneratorAdapter {
+    /**
+     * Generate SQL for TRUNCATE TABLE.
+     */
+    generateTruncate?(table: string, schema?: string, options?: TruncateOptions): string;
+    /**
+     * Generate SQL for VACUUM.
+     */
+    generateVacuum?(table: string, schema?: string, options?: VacuumOptions): string;
+    /**
+     * Generate SQL for ALTER TABLE ... ALTER COLUMN.
+     */
+    generateAlterColumn?(table: string, column: string, options: AlterColumnOptions, schema?: string): string;
+    /**
+     * Generate SQL for CREATE INDEX.
+     */
+    generateCreateIndex?(table: string, options: CreateIndexOptions, schema?: string): string;
+    /**
+     * Generate SQL for DROP INDEX.
+     */
+    generateDropIndex?(name: string, options?: DropIndexOptions): string;
+    /**
+     * List all indexes on a table, with optional name pattern filter.
+     */
+    listIndexes?(table: string, schema?: string, options?: {
+        namePattern?: string;
+    }): Promise<IndexInfo[]>;
+    /**
+     * Check whether an index with the given name exists on a table.
+     */
+    indexExists?(name: string, table: string, schema?: string): Promise<boolean>;
+    /**
+     * Return the total storage size of a table in bytes.
+     * Requires a live pool connection — compile-only adapters must throw.
+     */
+    storageSize?(table: string, schema?: string): Promise<number>;
+}
+/**
+ * DDL-generating adapter - can generate DDL (CREATE TABLE statements) from a schema.
+ */
+interface DDLGeneratingAdapter extends BaseAdapter {
+    /**
+     * Generate DDL statements from a schema.
+     *
+     * @param schema - The ModelIR schema to generate DDL from
+     * @param options - Optional adapter-specific options (e.g., includeDropStatements)
+     * @returns Array of DDL statements (CREATE TABLE, CREATE INDEX, etc.)
+     */
+    generateDDL(schema: ModelIR, options?: Record<string, unknown>): string[];
+}
+/**
+ * Compile-only adapter - can compile SQL and generate DDL, but cannot execute
+ * queries or stream results. Useful for tooling, CLI, and testing without a
+ * live database connection.
+ *
+ * Includes DDLGeneratingAdapter because DDL generation is purely compile-time
+ * (no DB connection required — same rationale as SQL compilation).
+ *
+ * Explicitly excludes execution interfaces so that type-checking catches
+ * misuse (e.g. calling execute() on a compile-only instance) at compile time.
+ */
+type CompileOnlyAdapter = CompilingAdapter & DDLGeneratingAdapter & {
+    /** Naming convention used by this adapter. */
+    readonly dbCasing: DbCasing;
+    /**
+     * Create a schema-scoped compile-only adapter.
+     * Purely a schema-name prefix — no DB interaction required.
+     */
+    withSchema(schemaName: string): CompileOnlyAdapter;
+    readonly execute?: never;
+    readonly executeOne?: never;
+    readonly executeOneOrThrow?: never;
+    readonly stream?: never;
+    readonly introspect?: never;
+    readonly transaction?: never;
+    readonly executeRaw?: never;
+    readonly executeDDL?: never;
+};
+/**
+ * Database adapter interface - full adapter with all capabilities.
+ *
+ * @typeParam DB - Database schema type for type inference
+ */
+interface Adapter<DB = unknown> extends CompilingAdapter, ExecutingAdapter, StreamingAdapter, IntrospectingAdapter, TransactionalAdapter<DB>, RawSqlAdapter, DDLGeneratingAdapter, TableDDLGeneratorAdapter {
+    /**
+     * Naming convention used by this adapter.
+     *
+     * @since ARCH-006
+     */
+    readonly dbCasing: DbCasing;
+    /**
+     * Execute a DDL statement directly (e.g. TRUNCATE, VACUUM, ALTER TABLE, CREATE INDEX).
+     * Optional — compile-only adapters do not implement this.
+     *
+     * @since DDL-TABLE-001
+     */
+    executeDDL?(sql: string): Promise<void>;
+    /**
+     * Whether this adapter instance is scoped inside a transaction.
+     * Used by table DDL methods to guard against unsafe operations (e.g. VACUUM).
+     *
+     * @since DDL-TABLE-001
+     */
+    readonly inTransaction?: boolean;
+}
+/** Behavior when schema uses features the adapter doesn't support */
+type UnsupportedFeatureBehavior = 'error' | 'warning' | 'ignore';
+/** Aligned with DialectCapabilities supportsDDL* flags (1:1 mapping) */
+type DDLFeature = 'enum' | 'sequence' | 'extension' | 'partition' | 'checkConstraint' | 'onUpdateFK' | 'deferredFK' | 'identity' | 'collation' | 'comment' | 'indexMethod' | 'indexOpclass' | 'indexInclude' | 'partialIndex' | 'expressionIndex';
+/** Version range for a DDL feature — resolved at createDialectCapabilities() time */
+interface DDLFeatureVersionRange {
+    /** Minimum database version required (inclusive). E.g., '8.0.16' */
+    readonly min?: string;
+    /** Maximum database version supported (inclusive, optional). For deprecation. */
+    readonly max?: string;
+}
+/** Per-feature behavior overrides (global default + optional per-feature) */
+interface FeatureBehaviorConfig {
+    /** Global default behavior (default: 'warning') */
+    readonly default: UnsupportedFeatureBehavior;
+    /** Per-feature overrides */
+    readonly overrides?: Partial<Record<DDLFeature, UnsupportedFeatureBehavior>>;
+}
+/** Error thrown when behavior = 'error' and unsupported feature detected */
+declare class UnsupportedFeatureError extends Error {
+    readonly feature: string;
+    readonly adapter: string;
+    readonly element: string;
+    constructor(feature: string, adapter: string, element: string);
+}
+/** Warning emitted when behavior = 'warning' */
+interface FeatureWarning {
+    readonly feature: string;
+    readonly adapter: string;
+    readonly element: string;
+    readonly message: string;
+}
+/** Type-safe element map: DDLFeature → IR type (INV-12) */
+interface DDLFeatureElementMap {
+    enum: EnumIR;
+    sequence: SequenceIR;
+    extension: string;
+    partition: PartitionIR;
+    checkConstraint: CheckConstraintIR;
+    onUpdateFK: ForeignKeyIR;
+    deferredFK: ForeignKeyIR;
+    identity: ColumnIR;
+    collation: ColumnIR;
+    comment: {
+        target: 'table' | 'column';
+        name: string;
+        comment: string;
+    };
+    indexMethod: IndexIR;
+    indexOpclass: IndexIR;
+    indexInclude: IndexIR;
+    partialIndex: IndexIR;
+    expressionIndex: IndexIR;
+}
+/**
+ * Interface for translating IR features to dialect-specific SQL.
+ * Adapters register translators to handle features their way.
+ *
+ * @example PG enum translator
+ * ```typescript
+ * const pgEnumTranslator: FeatureTranslator<'enum'> = {
+ *   feature: 'enum',
+ *   translate(element, context) {
+ *     return [`CREATE TYPE "${element.name}" AS ENUM (${element.values.map(v => `'${v}'`).join(', ')})`];
+ *   },
+ * };
+ * ```
+ */
+interface FeatureTranslator<F extends DDLFeature = DDLFeature> {
+    /** Which IR feature this translator handles */
+    readonly feature: F;
+    /** Generate SQL for this feature. Return null to skip (use default behavior). */
+    translate(element: DDLFeatureElementMap[F], context: TranslationContext): string[] | null;
+}
+interface TranslationContext {
+    readonly schemaName?: string;
+    readonly tableName?: string;
+    readonly dialectCapabilities: DialectCapabilities;
+}
+
+/**
+ * Canonical shape of a `schema()` factory result as produced by
+ * `createOrm({schema: ...})` callers and consumed by tooling
+ * (cli, gui sidecar, mcp-server).
+ *
+ * ARCH-005: Schema type from schema() function.
+ * Contains the definition, pre-computed ModelIR, and table names.
+ */
+interface LoadedSchema {
+    readonly definition: Record<string, unknown>;
+    readonly model: ModelIR;
+    readonly tableNames: string[];
+}
+/**
+ * Runtime type guard for `LoadedSchema` — verifies the object has
+ * `definition`, `model` (with nested `tables` + `relations`), and
+ * `tableNames` as an array. Structural check only — does not validate
+ * the inner values of any field.
+ *
+ * Type guard for ARCH-005 schema() output.
+ */
+declare function isValidSchema(schema: unknown): schema is LoadedSchema;
+
+export { type Adapter, type AdapterCapabilities, type AdapterLogger, type AdapterStreamOptions, type AdjacencyTraversal, type AggOrderByArg, type AggregateExpressionIntent, type AggregateFunction, type AggregateIntent, type AggregateWindowFunction, type AliasIncludedColumnsMode, type AlterColumnOptions, type AmbiguityCheckResult, type ArithmeticExpressionIntent, type ArrayExpressionIntent, type ArrayOperator, type BaseAdapter, type BatchUpdateIntent, type BatchValuesJoinPayload, type CTEDefinition, type Cardinality, type CaseExpressionIntent, type CastExpressionIntent, type CheckConstraintIR, type CoalesceExpressionIntent, type ColumnAliasIntent, type ColumnExpressionIntent, type ColumnIR, type ColumnType, type CommonColumnType, type ComparisonExpressionIntent, type ComparisonOperator, type CompileOnlyAdapter, type CompileOptions, type CompileOptionsBase, type CompileResultWithIncludes, type CompiledQuery, type CompilingAdapter, type CreateIndexOptions, type CteQueryIntent, type CustomFnExpressionIntent, type CustomOpExpressionIntent, type CustomTraversal, type DDLFeature, type DDLFeatureElementMap, type DDLFeatureVersionRange, type DDLGeneratingAdapter, type DbCasing, type DecisionType, type DeleteIntent, type DialectCapabilities, type DialectName, type DropIndexOptions, type DuckDBColumnType, type Dump, type DumpMeta, type EdgeTableTraversal, type EmitJoinClause, type EnumIR, type ExecutingAdapter, type ExpressionIntent, type FeatureBehaviorConfig, type FeatureTranslator, type FeatureWarning, type FieldRef, type FilterStrategy, type ForeignKeyIR, type FunctionExpressionIntent, type HierarchyIR, type IncludeIntent, type IncludeRecursiveOptions, type IncludeStrategy, type IndexColumnDef, type IndexIR, type IndexInfo, type IndexMethod, type InsertFromIntent, type InsertIntent, type IntrospectingAdapter, type IntrospectionOptions, type IntrospectionResult, type IsTypeSupported, type JoinDefault, type JoinIntent, type JsonContainsIntent, type JsonExistsIntent, type JsonExtractIntent, type JsonPathExtractIntent, type LiteralExpressionIntent, type LoadedSchema, type LockIntent, type LockStrength, type LockWaitPolicy, type LogicalOperator, type MSSQLColumnType, type ModelIR, type MutationIntent, type MySQLColumnType, type NamedArgExpressionIntent, type NullOperator, type NullsPosition, type OffsetWindowFunction, type OnDeleteAction, type Optionality, type OrderByIntent, type ParamExpressionIntent, type PartitionIR, type PlanDecision, type PlanOptions, type PlanReport, type PlanWarning, type PlanWarningCode, type PolicyIR, type PostgresColumnType, type PostgresOnlyColumnType, type PseudoColumnExpressionIntent, type PseudoColumnMetadata, type PseudoColumnTraversal, type QueryIntent, type RangeOperator, type RangeValue, type RankingWindowFunction, type RawCteIntent, type RawExpressionIntent, type RawSqlAdapter, type RecursiveAdvancedOptions, type RecursiveDedupe, type RecursiveDirection, type RecursiveEmitOptions, type RecursiveExistsOptions, type RecursiveIntent, type RecursiveMetadata, type RecursiveNodeIdExpr, type RecursivePlanOptions, type RecursivePlanReport, type RecursiveTrackOptions, type RecursiveTraversal, type RefExpressionIntent, type RelationColumnIntent, type RelationIR, type RelationKind, type RelationOperator, type RelationType, type ResolvedIncludeStrategy, type SQLiteColumnType, type ScalarSubqueryIntent, type SelectAggregateIntent, type SelectAllIntent, type SelectFieldsIntent, type SelectIntent, type SelectWithExpressionsIntent, type SequenceIR, type SetOperationIntent, type SetOperationType, type SimpleCteIntent, type SortDirection, type StarExpressionIntent, type StreamingAdapter, type StringOperator, type SubqueryExpressionIntent, type SubqueryIncludeInfo, type SubqueryRefIntent, type SupportedColumnTypes, type TableDDLGeneratorAdapter, type TableIR, type TransactionalAdapter, type TranslationContext, type TruncateOptions, type UnaryExpressionIntent, type UnnestCteIntent, type UnsupportedFeatureBehavior, UnsupportedFeatureError, type UpdateIntent, type UpsertConflictAction, type UpsertConflictTarget, type UpsertFromIntent, type UpsertIntent, type VacuumOptions, type WhereAndIntent, type WhereAnyIntent, type WhereComparisonIntent, type WhereExistsIntent, type WhereExpressionIntent, type WhereInIntent, type WhereIntent, type WhereJsonContainsIntent, type WhereJsonExistsIntent, type WhereLikeIntent, type WhereNotExistsIntent, type WhereNotIntent, type WhereNullIntent, type WhereOrIntent, type WhereRangeIntent, type WhereRawExistsIntent, type WhereRawNotExistsIntent, type WhereRelationFilterIntent, type WhereSubqueryIntent, type WindowFunction, type WindowIntent, type WindowOrderBy, getNodeIdAlias, isAdjacencyTraversal, isAggregateWindowFunction, isCoalesceExpression, isColumnAliasExpression, isCustomTraversal, isDeleteIntent, isEdgeTableTraversal, isFieldRef, isInsertIntent, isMutationIntent, isRankingWindowFunction, isRawExpression, isRecursiveIntent, isRelationColumnExpression, isSelectAggregate, isSelectAll, isSelectFields, isSelectWithExpressions, isSubqueryRef, isUpdateIntent, isUpsertIntent, isValidSchema, isWhereAnd, isWhereAny, isWhereComparison, isWhereExists, isWhereIn, isWhereLike, isWhereLogical, isWhereNot, isWhereNotExists, isWhereNull, isWhereOr, isWhereRange, isWhereRelationBased, isWhereRelationFilter, isWhereSubquery, isWindowIntent };