@lix-js/sdk 0.5.1 → 0.6.0-preview.0

package/src/engine/preprocessor/steps/rewrite-vtable-selects.ts

@@ -1,3751 +0,0 @@
-import {
-	type BetweenExpressionNode,
-	type BinaryExpressionNode,
-	type CompoundSelectNode,
-	type ExpressionNode,
-	type IdentifierNode,
-	type InListExpressionNode,
-	type ObjectNameNode,
-	type ParameterExpressionNode,
-	type RawFragmentNode,
-	type SegmentedStatementNode,
-	type SelectItemNode,
-	type SelectStatementNode,
-	type TableReferenceNode,
-	type RelationNode,
-	type WithClauseNode,
-} from "../sql-parser/nodes.js";
-import type {
-	PreprocessorStep,
-	PreprocessorStepContext,
-	PreprocessorTraceEntry,
-} from "../types.js";
-import { internalQueryBuilder } from "../../internal-query-builder.js";
-import {
-	getColumnName,
-	getColumnQualifier,
-	getIdentifierValue,
-	isSelectAllForTable,
-	normalizeIdentifierValue,
-	objectNameMatches,
-} from "../sql-parser/ast-helpers.js";
-import {
-	visitSelectStatement,
-	type AstVisitor,
-} from "../sql-parser/visitor.js";
-import { normalizeSegmentedStatement } from "../sql-parser/parse.js";
-import {
-	cacheTableNameToSchemaKey,
-	schemaKeyToCacheTableName,
-} from "../../../state/cache/create-schema-cache-table.js";
-import type {
-	VersionInheritanceMap,
-	VersionInheritanceNode,
-} from "../inheritance/version-inheritance-cache.js";
-
-export const INTERNAL_STATE_VTABLE = "lix_internal_state_vtable";
-const DEFAULT_ALIAS_KEY = normalizeIdentifierValue(INTERNAL_STATE_VTABLE);
-const ORIGINAL_TABLE_KEY = DEFAULT_ALIAS_KEY;
-const HIDDEN_SEGMENT_COLUMNS = ["_pk"] as const;
-const HIDDEN_SEGMENT_COLUMN_SET = new Set<string>(HIDDEN_SEGMENT_COLUMNS);
-const SNAPSHOT_JSON_ENTITY_PATHS = new Set<string>(["$.id", "$.entity_id"]);
-// Guarded until we can reliably map JSON paths to concrete entity identifiers.
-const SNAPSHOT_ENTITY_FILTER_PUSH_ENABLED = false;
-
-type SelectedProjection = {
-	column: string;
-	alias: string | null;
-};
-
-type ColumnSelectionSummary = {
-	selectedColumns: SelectedProjection[] | null;
-	requestedHiddenColumns: ReadonlySet<string>;
-	supportColumns: ReadonlySet<string>;
-};
-
-type SnapshotJsonPredicate = {
-	path: string;
-	values: readonly string[];
-};
-
-type ColumnPredicateSummary = {
-	count: number;
-	literals: string[];
-};
-
-type PredicateVisitContext = {
-	tableNames: Set<string>;
-	parameters: ReadonlyArray<unknown>;
-	allowUnqualified: boolean;
-};
-
-type SnapshotPredicateAccumulator = Map<string, Set<string>>;
-
-type TableReferenceInfo = {
-	relation: TableReferenceNode;
-	alias: string | null;
-	normalizedAlias: string | null;
-};
-
-type InlineRewriteMetadata = {
-	schemaKeys: readonly string[];
-	fileIds: readonly string[];
-	entityIds: readonly string[];
-	snapshotFilters: readonly SnapshotJsonPredicate[];
-	versionIds: readonly string[];
-	selectedColumns: SelectedProjection[] | null;
-	hiddenColumns: ReadonlySet<string>;
-	supportColumns: ReadonlySet<string>;
-	pruneInheritance: boolean;
-	pruneTransactionSegment: boolean;
-};
-
-type SubqueryPredicateMetadata = {
-	schemaKeys: readonly string[];
-	fileIds: readonly string[];
-	entityIds: readonly string[];
-	snapshotFilters: readonly SnapshotJsonPredicate[];
-	versionIds: readonly string[];
-	pruneInheritance: boolean;
-	pruneTransactionSegment: boolean;
-};
-
-/**
- * Rewrites internal state vtable references into inline union subqueries.
- *
- * @example
- * ```ts
- * const rewritten = rewriteVtableSelects({
- *   node: statement,
- *   getCacheTables,
- *   hasOpenTransaction,
- * });
- * ```
- */
-export const rewriteVtableSelects: PreprocessorStep = (context) => {
-	let anyChanges = false;
-	const rewrittenStatements = context.statements.map((statement) => {
-		const rewritten = rewriteSegmentedStatement(statement, context);
-		if (rewritten !== statement) {
-			anyChanges = true;
-		}
-		return rewritten;
-	});
-
-	return anyChanges ? rewrittenStatements : context.statements;
-};
-
-function rewriteSegmentedStatement(
-	statement: SegmentedStatementNode,
-	context: PreprocessorStepContext
-): SegmentedStatementNode {
-	let changed = false;
-	const segments = statement.segments.map((segment) => {
-		if (segment.node_kind === "select_statement") {
-			const rewritten = rewriteSelectStatement(segment, context);
-			if (rewritten !== segment) {
-				changed = true;
-			}
-			return rewritten;
-		}
-		if (segment.node_kind === "compound_select") {
-			const rewritten = rewriteCompoundSelect(segment, context);
-			if (rewritten !== segment) {
-				changed = true;
-			}
-			return rewritten;
-		}
-		return segment;
-	});
-
-	if (!changed) {
-		return statement;
-	}
-
-	return normalizeSegmentedStatement({
-		...statement,
-		segments,
-	});
-}
-
-function rewriteSelectStatement(
-	select: SelectStatementNode,
-	context: PreprocessorStepContext,
-	pushdownSchemaKeys: readonly string[] = [],
-	pushdownPruneInheritance = false,
-	pushdownPruneTransactions = false,
-	pushdownFileIds: readonly string[] = [],
-	pushdownEntityIds: readonly string[] = [],
-	pushdownVersionIds: readonly string[] = [],
-	pushdownSnapshotFilters: readonly SnapshotJsonPredicate[] = []
-): SelectStatementNode {
-	const parameters = context.parameters ?? [];
-	const ctePredicateMap = collectCtePredicateMap(
-		select,
-		parameters,
-		pushdownSchemaKeys,
-		pushdownPruneInheritance,
-		pushdownPruneTransactions,
-		pushdownFileIds,
-		pushdownEntityIds,
-		pushdownVersionIds,
-		pushdownSnapshotFilters
-	);
-	const selectWithRewrittenCtes = rewriteSelectWithClause(
-		select,
-		context,
-		ctePredicateMap,
-		pushdownSchemaKeys,
-		pushdownPruneInheritance,
-		pushdownPruneTransactions,
-		pushdownFileIds,
-		pushdownEntityIds,
-		pushdownVersionIds,
-		pushdownSnapshotFilters
-	);
-	const fallbackAliasNames = collectRelationAliasNames(selectWithRewrittenCtes);
-	const fallbackSchemaSummary = collectSchemaKeyPredicates(
-		selectWithRewrittenCtes.where_clause,
-		fallbackAliasNames,
-		parameters
-	);
-	const fallbackSchemaKeys = mergeStringLiterals(
-		pushdownSchemaKeys,
-		fallbackSchemaSummary.literals
-	);
-	const fallbackFileSummary = collectFileIdPredicates(
-		selectWithRewrittenCtes.where_clause,
-		fallbackAliasNames,
-		parameters
-	);
-	const fallbackFileIds = mergeStringLiterals(
-		pushdownFileIds,
-		fallbackFileSummary.literals
-	);
-	const fallbackEntitySummary = collectEntityIdPredicates(
-		selectWithRewrittenCtes.where_clause,
-		fallbackAliasNames,
-		parameters
-	);
-	const fallbackEntityIds = mergeStringLiterals(
-		pushdownEntityIds,
-		fallbackEntitySummary.literals
-	);
-	const fallbackVersionSummary = collectVersionIdPredicates(
-		selectWithRewrittenCtes.where_clause,
-		fallbackAliasNames,
-		parameters
-	);
-	const fallbackVersionIds = mergeStringLiterals(
-		pushdownVersionIds,
-		fallbackVersionSummary.literals
-	);
-	const fallbackSnapshotSummary = collectSnapshotJsonPredicates(
-		selectWithRewrittenCtes.where_clause,
-		fallbackAliasNames,
-		parameters
-	);
-	const fallbackSnapshotFilters = mergeSnapshotFilters(
-		pushdownSnapshotFilters,
-		fallbackSnapshotSummary
-	);
-	const fallbackPruneInheritance =
-		pushdownPruneInheritance ||
-		shouldPruneInheritance(
-			selectWithRewrittenCtes.where_clause,
-			fallbackAliasNames,
-			parameters
-		);
-	const fallbackPruneTransactions =
-		pushdownPruneTransactions ||
-		shouldPruneTransactionSegment(
-			selectWithRewrittenCtes.where_clause,
-			fallbackAliasNames,
-			parameters
-		);
-	const subqueryPredicateMap = collectSubqueryPredicateMap(
-		selectWithRewrittenCtes,
-		parameters,
-		pushdownSchemaKeys,
-		pushdownPruneInheritance,
-		pushdownPruneTransactions,
-		pushdownFileIds,
-		pushdownEntityIds,
-		pushdownVersionIds,
-		pushdownSnapshotFilters
-	);
-	const withRewrittenSubqueries = visitSelectStatement(
-		selectWithRewrittenCtes,
-		{
-			subquery(node, visitContext) {
-				const parentKind = visitContext.parent?.node_kind;
-				const aliasValue = getIdentifierValue(node.alias);
-				const normalizedAlias = aliasValue
-					? normalizeIdentifierValue(aliasValue)
-					: DEFAULT_ALIAS_KEY;
-				const predicateMetadata =
-					parentKind === "from_clause" || parentKind === "join_clause"
-						? subqueryPredicateMap.get(normalizedAlias)
-						: undefined;
-				const nextSchemaKeys =
-					predicateMetadata?.schemaKeys ?? fallbackSchemaKeys;
-				const nextPrune =
-					predicateMetadata?.pruneInheritance ?? fallbackPruneInheritance;
-				const nextPruneTransactions =
-					predicateMetadata?.pruneTransactionSegment ??
-					fallbackPruneTransactions;
-				const nextFileIds = predicateMetadata?.fileIds ?? fallbackFileIds;
-				const nextEntityIds = predicateMetadata?.entityIds ?? fallbackEntityIds;
-				const nextVersionIds =
-					predicateMetadata?.versionIds ?? fallbackVersionIds;
-				const nextSnapshotFilters =
-					predicateMetadata?.snapshotFilters ?? fallbackSnapshotFilters;
-				const rewrittenStatement =
-					node.statement.node_kind === "compound_select"
-						? rewriteCompoundSelect(
-								node.statement,
-								context,
-								nextSchemaKeys,
-								nextPrune,
-								nextPruneTransactions,
-								nextFileIds,
-								nextEntityIds,
-								nextVersionIds,
-								nextSnapshotFilters
-							)
-						: rewriteSelectStatement(
-								node.statement,
-								context,
-								nextSchemaKeys,
-								nextPrune,
-								nextPruneTransactions,
-								nextFileIds,
-								nextEntityIds,
-								nextVersionIds,
-								nextSnapshotFilters
-							);
-				if (rewrittenStatement !== node.statement) {
-					return {
-						...node,
-						statement: rewrittenStatement,
-					};
-				}
-				return node;
-			},
-		}
-	);
-
-	const references = collectInternalStateReferences(withRewrittenSubqueries);
-	if (references.length === 0) {
-		return withRewrittenSubqueries;
-	}
-
-	const aliasList = references
-		.map((reference) => reference.alias)
-		.filter((alias): alias is string => alias !== null);
-
-	const tableNamesForTrace = new Set<string>([
-		DEFAULT_ALIAS_KEY,
-		ORIGINAL_TABLE_KEY,
-		...references
-			.map((reference) => reference.normalizedAlias)
-			.filter((alias): alias is string => alias !== null),
-	]);
-
-	const schemaSummary = collectSchemaKeyPredicates(
-		withRewrittenSubqueries.where_clause,
-		tableNamesForTrace,
-		parameters
-	);
-	const mergedSchemaKeys = mergeStringLiterals(
-		pushdownSchemaKeys,
-		schemaSummary.literals
-	);
-	const schemaSummaryForTrace: ColumnPredicateSummary = {
-		count: schemaSummary.count,
-		literals: mergedSchemaKeys,
-	};
-
-	const projectionKind = determineProjectionKind(
-		withRewrittenSubqueries.projection,
-		tableNamesForTrace
-	);
-	const selectedColumnsSummaryForTrace = collectSelectedColumns(
-		withRewrittenSubqueries,
-		tableNamesForTrace
-	);
-
-	const metadata = buildInlineMetadata(
-		withRewrittenSubqueries,
-		references,
-		parameters,
-		pushdownSchemaKeys,
-		pushdownPruneInheritance,
-		pushdownPruneTransactions,
-		pushdownFileIds,
-		pushdownEntityIds,
-		pushdownVersionIds,
-		pushdownSnapshotFilters
-	);
-
-	const rewritten = visitSelectStatement(
-		withRewrittenSubqueries,
-		createInlineVisitor(metadata, context)
-	);
-
-	if (context.trace) {
-		const entry = buildTraceEntry({
-			aliasList,
-			projectionKind,
-			schemaSummary: schemaSummaryForTrace,
-			selectedColumns: selectedColumnsSummaryForTrace.selectedColumns,
-		});
-		context.trace.push(entry);
-	}
-
-	return rewritten;
-}
-
-function rewriteCompoundSelect(
-	compound: CompoundSelectNode,
-	context: PreprocessorStepContext,
-	pushdownSchemaKeys: readonly string[] = [],
-	pushdownPruneInheritance = false,
-	pushdownPruneTransactions = false,
-	pushdownFileIds: readonly string[] = [],
-	pushdownEntityIds: readonly string[] = [],
-	pushdownVersionIds: readonly string[] = [],
-	pushdownSnapshotFilters: readonly SnapshotJsonPredicate[] = []
-): CompoundSelectNode {
-	const rewrittenWithClause = compound.with_clause
-		? rewriteWithClauseNode(
-				compound.with_clause,
-				context,
-				new Map(),
-				pushdownSchemaKeys,
-				pushdownPruneInheritance,
-				pushdownPruneTransactions,
-				pushdownFileIds,
-				pushdownEntityIds,
-				pushdownVersionIds,
-				pushdownSnapshotFilters
-			)
-		: null;
-	let changed = false;
-	const first = rewriteSelectStatement(
-		compound.first,
-		context,
-		pushdownSchemaKeys,
-		pushdownPruneInheritance,
-		pushdownPruneTransactions,
-		pushdownFileIds,
-		pushdownEntityIds,
-		pushdownVersionIds,
-		pushdownSnapshotFilters
-	);
-	if (first !== compound.first) {
-		changed = true;
-	}
-
-	const branches = compound.compounds.map((branch) => {
-		const rewritten = rewriteSelectStatement(
-			branch.select,
-			context,
-			pushdownSchemaKeys,
-			pushdownPruneInheritance,
-			pushdownPruneTransactions,
-			pushdownFileIds,
-			pushdownEntityIds,
-			pushdownVersionIds,
-			pushdownSnapshotFilters
-		);
-		if (rewritten !== branch.select) {
-			changed = true;
-			return {
-				...branch,
-				select: rewritten,
-			};
-		}
-		return branch;
-	});
-
-	if (!changed) {
-		return rewrittenWithClause === compound.with_clause
-			? compound
-			: {
-					...compound,
-					with_clause: rewrittenWithClause,
-				};
-	}
-
-	return {
-		...compound,
-		first,
-		compounds: branches,
-		with_clause: rewrittenWithClause ?? compound.with_clause,
-	};
-}
-
-function collectInternalStateReferences(
-	select: SelectStatementNode
-): TableReferenceInfo[] {
-	const references: TableReferenceInfo[] = [];
-	for (const clause of select.from_clauses) {
-		const relation = clause.relation;
-		if (relation.node_kind === "table_reference") {
-			if (isInternalStateTable(relation)) {
-				references.push({
-					relation,
-					alias: getIdentifierValue(relation.alias),
-					normalizedAlias: normalizeAlias(relation.alias),
-				});
-			}
-		}
-		for (const join of clause.joins) {
-			const joinRelation = join.relation;
-			if (
-				joinRelation.node_kind === "table_reference" &&
-				isInternalStateTable(joinRelation)
-			) {
-				references.push({
-					relation: joinRelation,
-					alias: getIdentifierValue(joinRelation.alias),
-					normalizedAlias: normalizeAlias(joinRelation.alias),
-				});
-			}
-		}
-	}
-	return references;
-}
-
-function isInternalStateTable(table: TableReferenceNode): boolean {
-	return objectNameMatches(table.name, INTERNAL_STATE_VTABLE);
-}
-
-function normalizeAlias(alias: IdentifierNode | null): string | null {
-	const value = getIdentifierValue(alias);
-	return value ? normalizeIdentifierValue(value) : null;
-}
-
-function collectSubqueryPredicateMap(
-	select: SelectStatementNode,
-	parameters: ReadonlyArray<unknown>,
-	pushdownSchemaKeys: readonly string[],
-	pushdownPruneInheritance: boolean,
-	pushdownPruneTransactions: boolean,
-	pushdownFileIds: readonly string[],
-	pushdownEntityIds: readonly string[],
-	pushdownVersionIds: readonly string[],
-	pushdownSnapshotFilters: readonly SnapshotJsonPredicate[]
-): Map<string, SubqueryPredicateMetadata> {
-	const map = new Map<string, SubqueryPredicateMetadata>();
-	const register = (
-		relation: RelationNode,
-		joinFilter: ExpressionNode | RawFragmentNode | null
-	) => {
-		if (relation.node_kind !== "subquery") {
-			return;
-		}
-		const aliasValue = getIdentifierValue(relation.alias);
-		if (!aliasValue) {
-			return;
-		}
-		const normalizedAlias = normalizeIdentifierValue(aliasValue);
-		const tableNames = new Set<string>([
-			normalizedAlias,
-			DEFAULT_ALIAS_KEY,
-			ORIGINAL_TABLE_KEY,
-		]);
-		const whereSummary = collectSchemaKeyPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const joinSummary = collectSchemaKeyPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localKeys = mergeStringLiterals(
-			whereSummary.literals,
-			joinSummary.literals
-		);
-		const fileWhereSummary = collectFileIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const fileJoinSummary = collectFileIdPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localFileIds = mergeStringLiterals(
-			fileWhereSummary.literals,
-			fileJoinSummary.literals
-		);
-		const entityWhereSummary = collectEntityIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const entityJoinSummary = collectEntityIdPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localEntityIds = mergeStringLiterals(
-			entityWhereSummary.literals,
-			entityJoinSummary.literals
-		);
-		const snapshotWhereSummary = collectSnapshotJsonPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const snapshotJoinSummary = collectSnapshotJsonPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localSnapshotFilters = mergeSnapshotFilters(
-			snapshotWhereSummary,
-			snapshotJoinSummary
-		);
-
-		const versionWhereSummary = collectVersionIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const versionJoinSummary = collectVersionIdPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localVersionIds = mergeStringLiterals(
-			versionWhereSummary.literals,
-			versionJoinSummary.literals
-		);
-
-		const existing = map.get(normalizedAlias);
-		const merged = mergeStringLiterals(
-			existing?.schemaKeys ?? [],
-			pushdownSchemaKeys,
-			localKeys
-		);
-		const mergedFileIds = mergeStringLiterals(
-			existing?.fileIds ?? [],
-			pushdownFileIds,
-			localFileIds
-		);
-		const mergedEntityIds = mergeStringLiterals(
-			existing?.entityIds ?? [],
-			pushdownEntityIds,
-			localEntityIds
-		);
-		const mergedSnapshotFilters = mergeSnapshotFilters(
-			existing?.snapshotFilters ?? [],
-			pushdownSnapshotFilters,
-			localSnapshotFilters
-		);
-		const mergedVersionIds = mergeStringLiterals(
-			existing?.versionIds ?? [],
-			pushdownVersionIds,
-			localVersionIds
-		);
-		const pruneFromWhere = requiresNullPredicateForColumn(
-			select.where_clause,
-			tableNames,
-			parameters,
-			true
-		);
-		const pruneFromJoin = requiresNullPredicateForColumn(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const combinedPrune =
-			(existing?.pruneInheritance ?? false) ||
-			pushdownPruneInheritance ||
-			pruneFromWhere ||
-			pruneFromJoin;
-		const pruneTxnFromWhere = excludesColumnLiteralFromExpression(
-			select.where_clause,
-			tableNames,
-			parameters,
-			"source_tag",
-			"T",
-			true
-		);
-		const pruneTxnFromJoin = excludesColumnLiteralFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			"source_tag",
-			"T",
-			false
-		);
-		const combinedTxnPrune =
-			(existing?.pruneTransactionSegment ?? false) ||
-			pushdownPruneTransactions ||
-			pruneTxnFromWhere ||
-			pruneTxnFromJoin;
-		const finalFileIds = shouldPushFileFilter(merged, mergedFileIds)
-			? mergedFileIds
-			: [];
-		const finalEntityIds = shouldPushEntityFilter(merged, mergedEntityIds)
-			? mergedEntityIds
-			: [];
-		const finalSnapshotFilters = shouldPushSnapshotFilters(
-			merged,
-			mergedSnapshotFilters
-		)
-			? mergedSnapshotFilters
-			: [];
-		if (
-			merged.length > 0 ||
-			finalFileIds.length > 0 ||
-			finalEntityIds.length > 0 ||
-			finalSnapshotFilters.length > 0 ||
-			mergedVersionIds.length > 0 ||
-			combinedPrune ||
-			combinedTxnPrune
-		) {
-			map.set(normalizedAlias, {
-				schemaKeys: merged,
-				fileIds: finalFileIds,
-				entityIds: finalEntityIds,
-				snapshotFilters: finalSnapshotFilters,
-				versionIds: mergedVersionIds,
-				pruneInheritance: combinedPrune,
-				pruneTransactionSegment: combinedTxnPrune,
-			});
-		}
-	};
-
-	for (const clause of select.from_clauses) {
-		register(clause.relation, null);
-		for (const join of clause.joins) {
-			register(join.relation, join.on_expression);
-		}
-	}
-
-	return map;
-}
-
-function collectRelationAliasNames(select: SelectStatementNode): Set<string> {
-	const aliases = new Set<string>([DEFAULT_ALIAS_KEY, ORIGINAL_TABLE_KEY]);
-	const addAlias = (alias: IdentifierNode | null) => {
-		const value = getIdentifierValue(alias);
-		if (value) {
-			aliases.add(normalizeIdentifierValue(value));
-		}
-	};
-	for (const clause of select.from_clauses) {
-		addAlias(extractRelationAlias(clause.relation));
-		for (const join of clause.joins) {
-			addAlias(extractRelationAlias(join.relation));
-		}
-	}
-	return aliases;
-}
-
-function extractRelationAlias(relation: RelationNode): IdentifierNode | null {
-	if ("alias" in relation) {
-		const alias = (
-			relation as Extract<RelationNode, { alias?: IdentifierNode | null }>
-		).alias;
-		return alias ?? null;
-	}
-	return null;
-}
-
-function collectCtePredicateMap(
-	select: SelectStatementNode,
-	parameters: ReadonlyArray<unknown>,
-	pushdownSchemaKeys: readonly string[],
-	pushdownPruneInheritance: boolean,
-	pushdownPruneTransactions: boolean,
-	pushdownFileIds: readonly string[],
-	pushdownEntityIds: readonly string[],
-	pushdownVersionIds: readonly string[],
-	pushdownSnapshotFilters: readonly SnapshotJsonPredicate[]
-): Map<string, SubqueryPredicateMetadata> {
-	const withClause = select.with_clause;
-	if (!withClause || withClause.ctes.length === 0) {
-		return new Map();
-	}
-	const cteNames = new Set(
-		withClause.ctes
-			.map((cte) => normalizeIdentifierValue(cte.name.value))
-			.filter((name): name is string => !!name)
-	);
-	if (cteNames.size === 0) {
-		return new Map();
-	}
-	const map = new Map<string, SubqueryPredicateMetadata>();
-	const register = (
-		table: TableReferenceNode,
-		joinFilter: ExpressionNode | RawFragmentNode | null
-	) => {
-		const normalizedName = normalizeObjectName(table.name);
-		if (!normalizedName || !cteNames.has(normalizedName)) {
-			return;
-		}
-		const aliasValue = getIdentifierValue(table.alias);
-		const tableNames = new Set<string>([
-			normalizedName,
-			DEFAULT_ALIAS_KEY,
-			ORIGINAL_TABLE_KEY,
-		]);
-		if (aliasValue) {
-			tableNames.add(normalizeIdentifierValue(aliasValue));
-		}
-		const whereSummary = collectSchemaKeyPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const joinSummary = collectSchemaKeyPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localKeys = mergeStringLiterals(
-			whereSummary.literals,
-			joinSummary.literals
-		);
-		const fileWhereSummary = collectFileIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const fileJoinSummary = collectFileIdPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localFileIds = mergeStringLiterals(
-			fileWhereSummary.literals,
-			fileJoinSummary.literals
-		);
-		const entityWhereSummary = collectEntityIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const entityJoinSummary = collectEntityIdPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localEntityIds = mergeStringLiterals(
-			entityWhereSummary.literals,
-			entityJoinSummary.literals
-		);
-		const snapshotWhereSummary = collectSnapshotJsonPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const snapshotJoinSummary = collectSnapshotJsonPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localSnapshotFilters = mergeSnapshotFilters(
-			snapshotWhereSummary,
-			snapshotJoinSummary
-		);
-		const versionWhereSummary = collectVersionIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const versionJoinSummary = collectVersionIdPredicatesFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const localVersionIds = mergeStringLiterals(
-			versionWhereSummary.literals,
-			versionJoinSummary.literals
-		);
-		const existing = map.get(normalizedName);
-		const mergedSchemaKeys = mergeStringLiterals(
-			existing?.schemaKeys ?? [],
-			pushdownSchemaKeys,
-			localKeys
-		);
-		const mergedFileIds = mergeStringLiterals(
-			existing?.fileIds ?? [],
-			pushdownFileIds,
-			localFileIds
-		);
-		const mergedEntityIds = mergeStringLiterals(
-			existing?.entityIds ?? [],
-			pushdownEntityIds,
-			localEntityIds
-		);
-		const mergedSnapshotFilters = mergeSnapshotFilters(
-			existing?.snapshotFilters ?? [],
-			pushdownSnapshotFilters,
-			localSnapshotFilters
-		);
-		const mergedVersionIds = mergeStringLiterals(
-			existing?.versionIds ?? [],
-			pushdownVersionIds,
-			localVersionIds
-		);
-		const pruneFromWhere = requiresNullPredicateForColumn(
-			select.where_clause,
-			tableNames,
-			parameters,
-			true
-		);
-		const pruneFromJoin = requiresNullPredicateForColumn(
-			joinFilter,
-			tableNames,
-			parameters,
-			false
-		);
-		const combinedPrune =
-			(existing?.pruneInheritance ?? false) ||
-			pushdownPruneInheritance ||
-			pruneFromWhere ||
-			pruneFromJoin;
-		const pruneTxnFromWhere = excludesColumnLiteralFromExpression(
-			select.where_clause,
-			tableNames,
-			parameters,
-			"source_tag",
-			"T",
-			true
-		);
-		const pruneTxnFromJoin = excludesColumnLiteralFromExpression(
-			joinFilter,
-			tableNames,
-			parameters,
-			"source_tag",
-			"T",
-			false
-		);
-		const combinedTxnPrune =
-			(existing?.pruneTransactionSegment ?? false) ||
-			pushdownPruneTransactions ||
-			pruneTxnFromWhere ||
-			pruneTxnFromJoin;
-		const finalFileIds = shouldPushFileFilter(mergedSchemaKeys, mergedFileIds)
-			? mergedFileIds
-			: [];
-		const finalEntityIds = shouldPushEntityFilter(
-			mergedSchemaKeys,
-			mergedEntityIds
-		)
-			? mergedEntityIds
-			: [];
-		const finalSnapshotFilters = shouldPushSnapshotFilters(
-			mergedSchemaKeys,
-			mergedSnapshotFilters
-		)
-			? mergedSnapshotFilters
-			: [];
-		const entry = {
-			schemaKeys: mergedSchemaKeys,
-			fileIds: finalFileIds,
-			entityIds: finalEntityIds,
-			snapshotFilters: finalSnapshotFilters,
-			versionIds: mergedVersionIds,
-			pruneInheritance: combinedPrune,
-			pruneTransactionSegment: combinedTxnPrune,
-		};
-		map.set(normalizedName, entry);
-	};
-
-	for (const clause of select.from_clauses) {
-		if (clause.relation.node_kind === "table_reference") {
-			register(clause.relation, null);
-		}
-		for (const join of clause.joins) {
-			if (join.relation.node_kind === "table_reference") {
-				register(join.relation, join.on_expression);
-			}
-		}
-	}
-
-	return map;
-}
-
-function rewriteSelectWithClause(
-	select: SelectStatementNode,
-	context: PreprocessorStepContext,
-	predicateMap: Map<string, SubqueryPredicateMetadata>,
-	pushdownSchemaKeys: readonly string[],
-	pushdownPruneInheritance: boolean,
-	pushdownPruneTransactions: boolean,
-	pushdownFileIds: readonly string[],
-	pushdownEntityIds: readonly string[],
-	pushdownVersionIds: readonly string[],
-	pushdownSnapshotFilters: readonly SnapshotJsonPredicate[]
-): SelectStatementNode {
-	if (!select.with_clause) {
-		return select;
-	}
-	const rewritten = rewriteWithClauseNode(
-		select.with_clause,
-		context,
-		predicateMap,
-		pushdownSchemaKeys,
-		pushdownPruneInheritance,
-		pushdownPruneTransactions,
-		pushdownFileIds,
-		pushdownEntityIds,
-		pushdownVersionIds,
-		pushdownSnapshotFilters
-	);
-	if (rewritten === select.with_clause) {
-		return select;
-	}
-	return {
-		...select,
-		with_clause: rewritten,
-	};
-}
-
-function rewriteWithClauseNode(
-	withClause: WithClauseNode,
-	context: PreprocessorStepContext,
-	predicateMap: Map<string, SubqueryPredicateMetadata>,
-	pushdownSchemaKeys: readonly string[],
-	pushdownPruneInheritance: boolean,
-	pushdownPruneTransactions: boolean,
-	pushdownFileIds: readonly string[],
-	pushdownEntityIds: readonly string[],
-	pushdownVersionIds: readonly string[],
-	pushdownSnapshotFilters: readonly SnapshotJsonPredicate[]
-): WithClauseNode {
-	let changed = false;
-	const rewrittenCtes = withClause.ctes.map((cte) => {
-		const cteName = normalizeIdentifierValue(cte.name.value);
-		const metadata = cteName ? predicateMap.get(cteName) : undefined;
-		const nextSchemaKeys = metadata?.schemaKeys ?? pushdownSchemaKeys;
-		const nextPrune = metadata?.pruneInheritance ?? pushdownPruneInheritance;
-		const nextPruneTransactions =
-			metadata?.pruneTransactionSegment ?? pushdownPruneTransactions;
-		const nextFileIds = metadata?.fileIds ?? pushdownFileIds;
-		const nextEntityIds = metadata?.entityIds ?? pushdownEntityIds;
-		const nextVersionIds = metadata?.versionIds ?? pushdownVersionIds;
-		const nextSnapshotFilters =
-			metadata?.snapshotFilters ?? pushdownSnapshotFilters;
-		const statement =
-			cte.statement.node_kind === "compound_select"
-				? rewriteCompoundSelect(
-						cte.statement,
-						context,
-						nextSchemaKeys,
-						nextPrune,
-						nextPruneTransactions,
-						nextFileIds,
-						nextEntityIds,
-						nextVersionIds,
-						nextSnapshotFilters
-					)
-				: rewriteSelectStatement(
-						cte.statement,
-						context,
-						nextSchemaKeys,
-						nextPrune,
-						nextPruneTransactions,
-						nextFileIds,
-						nextEntityIds,
-						nextVersionIds,
-						nextSnapshotFilters
-					);
-		if (statement !== cte.statement) {
-			changed = true;
-			return {
-				...cte,
-				statement,
-			};
-		}
-		return cte;
-	});
-	if (!changed) {
-		return withClause;
-	}
-	return {
-		...withClause,
-		ctes: rewrittenCtes,
-	};
-}
-
-function buildInlineMetadata(
-	select: SelectStatementNode,
-	references: readonly TableReferenceInfo[],
-	parameters: ReadonlyArray<unknown>,
-	pushdownSchemaKeys: readonly string[],
-	pushdownPruneInheritance: boolean,
-	pushdownPruneTransactions: boolean,
-	pushdownFileIds: readonly string[],
-	pushdownEntityIds: readonly string[],
-	pushdownVersionIds: readonly string[],
-	pushdownSnapshotFilters: readonly SnapshotJsonPredicate[]
-): Map<string, InlineRewriteMetadata> {
-	const metadata = new Map<string, InlineRewriteMetadata>();
-	for (const reference of references) {
-		const aliasKey = reference.normalizedAlias ?? DEFAULT_ALIAS_KEY;
-		if (metadata.has(aliasKey)) {
-			continue;
-		}
-		const tableNames = new Set<string>([
-			aliasKey,
-			DEFAULT_ALIAS_KEY,
-			ORIGINAL_TABLE_KEY,
-		]);
-		const summary = collectSchemaKeyPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const schemaKeys = mergeStringLiterals(
-			pushdownSchemaKeys,
-			summary.literals
-		);
-		const fileSummary = collectFileIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const mergedFileIds = mergeStringLiterals(
-			pushdownFileIds,
-			fileSummary.literals
-		);
-		const entitySummary = collectEntityIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const mergedEntityIds = mergeStringLiterals(
-			pushdownEntityIds,
-			entitySummary.literals
-		);
-		const versionSummary = collectVersionIdPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const mergedVersionIds = mergeStringLiterals(
-			pushdownVersionIds,
-			versionSummary.literals
-		);
-		const snapshotSummary = collectSnapshotJsonPredicates(
-			select.where_clause,
-			tableNames,
-			parameters
-		);
-		const mergedSnapshotFilters = mergeSnapshotFilters(
-			pushdownSnapshotFilters,
-			snapshotSummary
-		);
-		const fileIds = shouldPushFileFilter(schemaKeys, mergedFileIds)
-			? mergedFileIds
-			: [];
-		const entityIds = shouldPushEntityFilter(schemaKeys, mergedEntityIds)
-			? mergedEntityIds
-			: [];
-		const columnSummary = collectSelectedColumns(select, tableNames);
-		const snapshotFilters = shouldPushSnapshotFilters(
-			schemaKeys,
-			mergedSnapshotFilters
-		)
-			? mergedSnapshotFilters
-			: [];
-		const pruneInheritance =
-			pushdownPruneInheritance ||
-			shouldPruneInheritance(select.where_clause, tableNames, parameters);
-		const pruneTransactionSegment =
-			pushdownPruneTransactions ||
-			shouldPruneTransactionSegment(
-				select.where_clause,
-				tableNames,
-				parameters
-			);
-		metadata.set(aliasKey, {
-			schemaKeys,
-			fileIds,
-			entityIds,
-			snapshotFilters,
-			versionIds: mergedVersionIds,
-			selectedColumns: columnSummary.selectedColumns,
-			hiddenColumns: new Set(columnSummary.requestedHiddenColumns),
-			supportColumns: new Set(columnSummary.supportColumns),
-			pruneInheritance,
-			pruneTransactionSegment,
-		});
-	}
-	return metadata;
-}
-
-function shouldPruneInheritance(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>
-): boolean {
-	return requiresNullPredicateForColumn(
-		whereClause,
-		tableNames,
-		parameters,
-		true
-	);
-}
-
-function shouldPruneTransactionSegment(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>
-): boolean {
-	return excludesColumnLiteralFromExpression(
-		whereClause,
-		tableNames,
-		parameters,
-		"source_tag",
-		"T",
-		true
-	);
-}
-
-function requiresNullPredicateForColumn(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified: boolean
-): boolean {
-	if (!expression) {
-		return false;
-	}
-	const context: PredicateVisitContext = {
-		tableNames,
-		parameters,
-		allowUnqualified,
-	};
-	return expressionRequiresNullForColumn(
-		expression,
-		"inherited_from_version_id",
-		context
-	);
-}
-
-function excludesColumnLiteralFromExpression(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	columnName: string,
-	literal: string,
-	allowUnqualified: boolean
-): boolean {
-	if (!expression) {
-		return false;
-	}
-	const context: PredicateVisitContext = {
-		tableNames,
-		parameters,
-		allowUnqualified,
-	};
-	return expressionExcludesColumnLiteral(
-		expression,
-		columnName,
-		literal,
-		context
-	);
-}
-
-function expressionExcludesColumnLiteral(
-	expression: ExpressionNode | RawFragmentNode,
-	columnName: string,
-	literal: string,
-	context: PredicateVisitContext
-): boolean {
-	if ("sql_text" in expression) {
-		return false;
-	}
-	switch (expression.node_kind) {
-		case "grouped_expression":
-			return expressionExcludesColumnLiteral(
-				expression.expression,
-				columnName,
-				literal,
-				context
-			);
-		case "binary_expression":
-			if (expression.operator === "and") {
-				return (
-					expressionExcludesColumnLiteral(
-						expression.left,
-						columnName,
-						literal,
-						context
-					) ||
-					expressionExcludesColumnLiteral(
-						expression.right,
-						columnName,
-						literal,
-						context
-					)
-				);
-			}
-			if (expression.operator === "or") {
-				return (
-					expressionExcludesColumnLiteral(
-						expression.left,
-						columnName,
-						literal,
-						context
-					) &&
-					expressionExcludesColumnLiteral(
-						expression.right,
-						columnName,
-						literal,
-						context
-					)
-				);
-			}
-			return (
-				columnComparisonExcludes(
-					expression,
-					expression.left,
-					expression.right,
-					columnName,
-					literal,
-					context
-				) ||
-				columnComparisonExcludes(
-					expression,
-					expression.right,
-					expression.left,
-					columnName,
-					literal,
-					context
-				)
-			);
-		case "in_list_expression": {
-			if (!isColumnReference(expression.operand, context, columnName)) {
-				return false;
-			}
-			const values = expression.items
-				.map((item) => extractStringLiteral(item, context))
-				.filter((value): value is string => typeof value === "string");
-			if (values.length === 0) {
-				return false;
-			}
-			if (expression.negated) {
-				return values.includes(literal);
-			}
-			return !values.includes(literal);
-		}
-		default:
-			return false;
-	}
-}
-
-function columnComparisonExcludes(
-	expression: BinaryExpressionNode,
-	columnSide: ExpressionNode | RawFragmentNode,
-	valueSide: ExpressionNode | RawFragmentNode,
-	columnName: string,
-	literal: string,
-	context: PredicateVisitContext
-): boolean {
-	if (!isColumnReference(columnSide, context, columnName)) {
-		return false;
-	}
-	const value = extractStringLiteral(valueSide, context);
-	if (typeof value !== "string") {
-		return false;
-	}
-	switch (expression.operator) {
-		case "=":
-		case "is":
-			return value !== literal;
-		case "!=":
-		case "<>":
-		case "is_not":
-			return value === literal;
-		default:
-			return false;
-	}
-}
-
-function extractStringLiteral(
-	expression: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext
-): string | null {
-	const node = unwrapExpression(expression);
-	if ("sql_text" in node) {
-		return null;
-	}
-	if (node.node_kind === "literal") {
-		return typeof node.value === "string" ? node.value : null;
-	}
-	if (node.node_kind === "parameter") {
-		return resolveParameterSchemaLiteral(node, context.parameters);
-	}
-	return null;
-}
-
-function createInlineVisitor(
-	metadata: Map<string, InlineRewriteMetadata>,
-	context: PreprocessorStepContext
-): AstVisitor {
-	return {
-		table_reference(node: TableReferenceNode) {
-			if (!isInternalStateTable(node)) {
-				return;
-			}
-			const aliasValue = getIdentifierValue(node.alias);
-			const aliasKey = aliasValue
-				? normalizeIdentifierValue(aliasValue)
-				: DEFAULT_ALIAS_KEY;
-			const metadataEntry = metadata.get(aliasKey);
-			if (!metadataEntry) {
-				return;
-			}
-			const aliasForSql =
-				aliasValue ??
-				getIdentifierValue(node.name.parts.at(-1) ?? null) ??
-				INTERNAL_STATE_VTABLE;
-			const inlineSql = buildVtableSelectRewrite({
-				schemaKeys: metadataEntry.schemaKeys,
-				fileIds: metadataEntry.fileIds,
-				entityIds: metadataEntry.entityIds,
-				snapshotFilters: metadataEntry.snapshotFilters,
-				versionIds: metadataEntry.versionIds,
-				cacheTables: context.getCacheTables!(),
-				selectedColumns: metadataEntry.selectedColumns,
-				hiddenColumns: metadataEntry.hiddenColumns,
-				supportColumns: metadataEntry.supportColumns,
-				hasOpenTransaction: context.hasOpenTransaction!(),
-				pruneInheritance: metadataEntry.pruneInheritance,
-				pruneTransactionSegment: metadataEntry.pruneTransactionSegment,
-				versionInheritance: context.getVersionInheritance
-					? context.getVersionInheritance()
-					: undefined,
-			}).trimEnd();
-			const fragment: RawFragmentNode = {
-				node_kind: "raw_fragment",
-				sql_text: `${inlineSql} AS ${quoteIdentifier(aliasForSql)}`,
-			};
-			return fragment;
-		},
-	};
-}
-
-function collectSchemaKeyPredicates(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified = true
-): ColumnPredicateSummary {
-	return collectColumnPredicates(
-		whereClause,
-		tableNames,
-		parameters,
-		"schema_key",
-		allowUnqualified
-	);
-}
-
-function collectSchemaKeyPredicatesFromExpression(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified: boolean
-): ColumnPredicateSummary {
-	return collectColumnPredicatesFromExpression(
-		expression,
-		tableNames,
-		parameters,
-		"schema_key",
-		allowUnqualified
-	);
-}
-
-function collectFileIdPredicates(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified = true
-): ColumnPredicateSummary {
-	return collectColumnPredicates(
-		whereClause,
-		tableNames,
-		parameters,
-		"file_id",
-		allowUnqualified
-	);
-}
-
-function collectFileIdPredicatesFromExpression(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified: boolean
-): ColumnPredicateSummary {
-	return collectColumnPredicatesFromExpression(
-		expression,
-		tableNames,
-		parameters,
-		"file_id",
-		allowUnqualified
-	);
-}
-
-function collectEntityIdPredicates(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified = true
-): ColumnPredicateSummary {
-	return collectColumnPredicates(
-		whereClause,
-		tableNames,
-		parameters,
-		"entity_id",
-		allowUnqualified
-	);
-}
-
-function collectEntityIdPredicatesFromExpression(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified: boolean
-): ColumnPredicateSummary {
-	return collectColumnPredicatesFromExpression(
-		expression,
-		tableNames,
-		parameters,
-		"entity_id",
-		allowUnqualified
-	);
-}
-
-function collectVersionIdPredicates(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified = true
-): ColumnPredicateSummary {
-	return collectColumnPredicates(
-		whereClause,
-		tableNames,
-		parameters,
-		"version_id",
-		allowUnqualified
-	);
-}
-
-function collectVersionIdPredicatesFromExpression(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified: boolean
-): ColumnPredicateSummary {
-	return collectColumnPredicatesFromExpression(
-		expression,
-		tableNames,
-		parameters,
-		"version_id",
-		allowUnqualified
-	);
-}
-
-function collectSnapshotJsonPredicates(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified = true
-): SnapshotJsonPredicate[] {
-	if (!whereClause) {
-		return [];
-	}
-	const context: PredicateVisitContext = {
-		tableNames,
-		parameters,
-		allowUnqualified,
-	};
-	const summary: SnapshotPredicateAccumulator = new Map();
-	collectSnapshotPredicatesFromExpression(whereClause, context, summary);
-	return snapshotSummaryToPredicates(summary);
-}
-
-function collectSnapshotJsonPredicatesFromExpression(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	allowUnqualified: boolean
-): SnapshotJsonPredicate[] {
-	if (!expression) {
-		return [];
-	}
-	const context: PredicateVisitContext = {
-		tableNames,
-		parameters,
-		allowUnqualified,
-	};
-	const summary: SnapshotPredicateAccumulator = new Map();
-	collectSnapshotPredicatesFromExpression(expression, context, summary);
-	return snapshotSummaryToPredicates(summary);
-}
-
-function collectSnapshotPredicatesFromExpression(
-	expression: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext,
-	summary: SnapshotPredicateAccumulator
-): void {
-	if ("sql_text" in expression) {
-		return;
-	}
-	switch (expression.node_kind) {
-		case "grouped_expression":
-			collectSnapshotPredicatesFromExpression(
-				expression.expression,
-				context,
-				summary
-			);
-			return;
-		case "binary_expression": {
-			if (isLogicalOperator(expression.operator)) {
-				collectSnapshotPredicatesFromExpression(
-					expression.left,
-					context,
-					summary
-				);
-				collectSnapshotPredicatesFromExpression(
-					expression.right,
-					context,
-					summary
-				);
-				return;
-			}
-			if (!isEqualityOperator(expression.operator)) {
-				return;
-			}
-			const leftPath = extractSnapshotJsonPath(expression.left, context);
-			if (leftPath) {
-				incrementSnapshotSummaryWithOperand(
-					summary,
-					leftPath,
-					expression.right,
-					context
-				);
-			}
-			const rightPath = extractSnapshotJsonPath(expression.right, context);
-			if (rightPath) {
-				incrementSnapshotSummaryWithOperand(
-					summary,
-					rightPath,
-					expression.left,
-					context
-				);
-			}
-			return;
-		}
-		case "in_list_expression": {
-			if (expression.negated) {
-				return;
-			}
-			const path = extractSnapshotJsonPath(expression.operand, context);
-			if (!path) {
-				return;
-			}
-			for (const item of expression.items) {
-				incrementSnapshotSummaryWithOperand(summary, path, item, context);
-			}
-			return;
-		}
-		case "unary_expression":
-			collectSnapshotPredicatesFromExpression(
-				expression.operand,
-				context,
-				summary
-			);
-			return;
-		default:
-			return;
-	}
-}
-
-function incrementSnapshotSummaryWithOperand(
-	summary: SnapshotPredicateAccumulator,
-	path: string,
-	operand: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext
-): void {
-	const value = extractStringLiteral(operand, context);
-	if (typeof value !== "string") {
-		return;
-	}
-	const existing = summary.get(path) ?? new Set<string>();
-	existing.add(value);
-	summary.set(path, existing);
-}
-
-function snapshotSummaryToPredicates(
-	summary: SnapshotPredicateAccumulator
-): SnapshotJsonPredicate[] {
-	return Array.from(summary.entries()).map(([path, values]) => ({
-		path,
-		values: Array.from(values),
-	}));
-}
-
-function extractSnapshotJsonPath(
-	expression: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext
-): string | null {
-	const node = unwrapExpression(expression);
-	if ("sql_text" in node) {
-		return null;
-	}
-	switch (node.node_kind) {
-		case "grouped_expression":
-			return extractSnapshotJsonPath(node.expression, context);
-		case "function_call": {
-			const functionName = node.name.value.toLowerCase();
-			if (functionName !== "json_extract") {
-				return null;
-			}
-			const [targetArg, pathArg] = node.arguments;
-			if (
-				!targetArg ||
-				!pathArg ||
-				targetArg.node_kind === "all_columns" ||
-				pathArg.node_kind === "all_columns"
-			) {
-				return null;
-			}
-			const referencedColumn = resolveReferencedColumn(
-				targetArg as ExpressionNode | RawFragmentNode,
-				context
-			);
-			if (referencedColumn !== "snapshot_content") {
-				return null;
-			}
-			return extractLiteralString(
-				pathArg as ExpressionNode | RawFragmentNode,
-				context.parameters
-			);
-		}
-		default:
-			return null;
-	}
-}
-
-function collectColumnPredicates(
-	whereClause: SelectStatementNode["where_clause"],
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	columnName: string,
-	allowUnqualified = true
-): ColumnPredicateSummary {
-	if (!whereClause) {
-		return { count: 0, literals: [] };
-	}
-	const context: PredicateVisitContext = {
-		tableNames,
-		parameters,
-		allowUnqualified,
-	};
-	return visitExpression(whereClause, context, columnName);
-}
-
-function collectColumnPredicatesFromExpression(
-	expression: ExpressionNode | RawFragmentNode | null,
-	tableNames: Set<string>,
-	parameters: ReadonlyArray<unknown>,
-	columnName: string,
-	allowUnqualified: boolean
-): ColumnPredicateSummary {
-	if (!expression) {
-		return { count: 0, literals: [] };
-	}
-	const context: PredicateVisitContext = {
-		tableNames,
-		parameters,
-		allowUnqualified,
-	};
-	return visitExpression(expression, context, columnName);
-}
-
-function expressionRequiresNullForColumn(
-	expression: ExpressionNode | RawFragmentNode,
-	columnName: string,
-	context: PredicateVisitContext
-): boolean {
-	if ("sql_text" in expression) {
-		return false;
-	}
-	switch (expression.node_kind) {
-		case "grouped_expression":
-			return expressionRequiresNullForColumn(
-				expression.expression,
-				columnName,
-				context
-			);
-		case "binary_expression":
-			if (expression.operator === "and") {
-				return (
-					expressionRequiresNullForColumn(
-						expression.left,
-						columnName,
-						context
-					) ||
-					expressionRequiresNullForColumn(expression.right, columnName, context)
-				);
-			}
-			if (expression.operator === "or") {
-				return (
-					expressionRequiresNullForColumn(
-						expression.left,
-						columnName,
-						context
-					) &&
-					expressionRequiresNullForColumn(expression.right, columnName, context)
-				);
-			}
-			if (expression.operator === "is") {
-				const leftMatches = isColumnReference(
-					expression.left,
-					context,
-					columnName
-				);
-				const rightMatches = isColumnReference(
-					expression.right,
-					context,
-					columnName
-				);
-				if (
-					(leftMatches &&
-						isNullLiteralExpression(expression.right, context.parameters)) ||
-					(rightMatches &&
-						isNullLiteralExpression(expression.left, context.parameters))
-				) {
-					return true;
-				}
-			}
-			return false;
-		default:
-			return false;
-	}
-}
-
-function visitExpression(
-	expression: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext,
-	columnName: string
-): ColumnPredicateSummary {
-	if ("sql_text" in expression) {
-		return { count: 0, literals: [] };
-	}
-
-	switch (expression.node_kind) {
-		case "grouped_expression":
-			return visitExpression(expression.expression, context, columnName);
-		case "binary_expression":
-			return visitBinaryExpression(expression, context, columnName);
-		case "unary_expression":
-			return visitExpression(expression.operand, context, columnName);
-		case "in_list_expression":
-			return visitInListExpression(expression, context, columnName);
-		case "between_expression":
-			return visitBetweenExpression(expression, context, columnName);
-		case "column_reference":
-		case "literal":
-		case "parameter":
-		default:
-			return { count: 0, literals: [] };
-	}
-}
-
-function visitBinaryExpression(
-	expression: BinaryExpressionNode,
-	context: PredicateVisitContext,
-	columnName: string
-): ColumnPredicateSummary {
-	if (isLogicalOperator(expression.operator)) {
-		return mergeSummaries(
-			visitExpression(expression.left, context, columnName),
-			visitExpression(expression.right, context, columnName)
-		);
-	}
-
-	if (!isEqualityOperator(expression.operator)) {
-		return { count: 0, literals: [] };
-	}
-
-	let summary: ColumnPredicateSummary = {
-		count: 0,
-		literals: [],
-	};
-
-	const leftMatches = isColumnReference(expression.left, context, columnName);
-	const rightMatches = isColumnReference(expression.right, context, columnName);
-
-	if (leftMatches) {
-		summary = incrementSummaryWithOperand(summary, expression.right, context);
-	}
-	if (rightMatches) {
-		summary = incrementSummaryWithOperand(summary, expression.left, context);
-	}
-
-	return summary;
-}
-
-function visitInListExpression(
-	expression: InListExpressionNode,
-	context: PredicateVisitContext,
-	columnName: string
-): ColumnPredicateSummary {
-	if (!isColumnReference(expression.operand, context, columnName)) {
-		return { count: 0, literals: [] };
-	}
-	let summary: ColumnPredicateSummary = {
-		count: 1,
-		literals: [],
-	};
-	for (const item of expression.items) {
-		summary = incrementSummaryWithOperand(summary, item, context);
-	}
-	return summary;
-}
-
-function visitBetweenExpression(
-	expression: BetweenExpressionNode,
-	context: PredicateVisitContext,
-	columnName: string
-): ColumnPredicateSummary {
-	if (!isColumnReference(expression.operand, context, columnName)) {
-		return { count: 0, literals: [] };
-	}
-	let summary: ColumnPredicateSummary = {
-		count: 1,
-		literals: [],
-	};
-	summary = incrementSummaryWithOperand(summary, expression.start, context);
-	summary = incrementSummaryWithOperand(summary, expression.end, context);
-	return summary;
-}
-
-function incrementSummaryWithOperand(
-	summary: ColumnPredicateSummary,
-	operand: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext
-): ColumnPredicateSummary {
-	const next = { ...summary };
-	const node = unwrapExpression(operand);
-	switch (node.node_kind) {
-		case "literal":
-			if (typeof node.value === "string") {
-				next.literals.push(node.value);
-			}
-			break;
-		case "parameter": {
-			const resolved = resolveParameterSchemaLiteral(node, context.parameters);
-			if (typeof resolved === "string") {
-				next.literals.push(resolved);
-			}
-			break;
-		}
-		default:
-			break;
-	}
-	next.count += 1;
-	return next;
-}
-
-function isNullLiteralExpression(
-	expression: ExpressionNode | RawFragmentNode,
-	parameters: ReadonlyArray<unknown>
-): boolean {
-	const node = unwrapExpression(expression);
-	if ("sql_text" in node) {
-		return false;
-	}
-	if (node.node_kind === "literal") {
-		return node.value === null;
-	}
-	if (node.node_kind === "parameter") {
-		return resolveParameterValue(node, parameters) === null;
-	}
-	return false;
-}
-
-function resolveParameterSchemaLiteral(
-	parameter: ParameterExpressionNode,
-	parameters: ReadonlyArray<unknown>
-): string | null {
-	const value = resolveParameterValue(parameter, parameters);
-	return typeof value === "string" ? value : null;
-}
-
-function resolveParameterValue(
-	parameter: ParameterExpressionNode,
-	parameters: ReadonlyArray<unknown>
-): unknown {
-	const index = parameter.position;
-	if (typeof index === "number" && index >= 0 && index < parameters.length) {
-		return parameters[index];
-	}
-	return undefined;
-}
-
-function unwrapExpression(
-	expression: ExpressionNode | RawFragmentNode
-): ExpressionNode | RawFragmentNode {
-	if ("sql_text" in expression) {
-		return expression;
-	}
-	if (expression.node_kind === "grouped_expression") {
-		return unwrapExpression(expression.expression);
-	}
-	return expression;
-}
-
-function isColumnReference(
-	expression: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext,
-	expectedColumn: string
-): boolean {
-	const column = resolveReferencedColumn(expression, context);
-	return column === expectedColumn;
-}
-
-function resolveReferencedColumn(
-	expression: ExpressionNode | RawFragmentNode,
-	context: PredicateVisitContext
-): string | null {
-	if ("sql_text" in expression) {
-		return null;
-	}
-	switch (expression.node_kind) {
-		case "column_reference": {
-			const qualifier = getColumnQualifier(expression);
-			const columnName = getColumnName(expression);
-			if (qualifier && context.tableNames.has(qualifier)) {
-				return columnName;
-			}
-			if (!qualifier && context.allowUnqualified) {
-				return columnName;
-			}
-			return null;
-		}
-		case "grouped_expression":
-			return resolveReferencedColumn(expression.expression, context);
-		case "function_call":
-			return resolveColumnFromFunctionCall(expression, context);
-		default:
-			return null;
-	}
-}
-
-function resolveColumnFromFunctionCall(
-	expression: Extract<ExpressionNode, { node_kind: "function_call" }>,
-	context: PredicateVisitContext
-): string | null {
-	const functionName = expression.name.value.toLowerCase();
-	if (functionName !== "json_extract") {
-		return null;
-	}
-	const [target, pathArg] = expression.arguments;
-	if (
-		!target ||
-		!pathArg ||
-		target.node_kind === "all_columns" ||
-		pathArg.node_kind === "all_columns"
-	) {
-		return null;
-	}
-	const targetExpr = target as ExpressionNode | RawFragmentNode;
-	const referencedColumn = resolveReferencedColumn(targetExpr, context);
-	if (referencedColumn !== "snapshot_content") {
-		return null;
-	}
-	if (!SNAPSHOT_ENTITY_FILTER_PUSH_ENABLED) {
-		return null;
-	}
-	const pathExpression = pathArg as ExpressionNode | RawFragmentNode;
-	const literalPath = extractLiteralString(pathExpression, context.parameters);
-	if (!literalPath) {
-		return null;
-	}
-	return mapSnapshotJsonColumnFromPath(literalPath);
-}
-
-function extractLiteralString(
-	expression: ExpressionNode | RawFragmentNode,
-	parameters: ReadonlyArray<unknown>
-): string | null {
-	const node = unwrapExpression(expression);
-	if ("sql_text" in node) {
-		return null;
-	}
-	if (node.node_kind === "literal" && typeof node.value === "string") {
-		return node.value;
-	}
-	if (node.node_kind === "parameter") {
-		const value = resolveParameterValue(node, parameters);
-		return typeof value === "string" ? value : null;
-	}
-	return null;
-}
-
-/**
- * Maps recognized json_extract paths to their corresponding physical columns.
- *
- * @param path - JSON path literal extracted from a json_extract() call.
- * @returns The name of the backing column or null when the path is unsupported.
- *
- * @example
- * ```ts
- * mapSnapshotJsonColumnFromPath("$.id");
- * // => "entity_id"
- * ```
- */
-function mapSnapshotJsonColumnFromPath(path: string): string | null {
-	const trimmed = path.trim();
-	const candidates = new Set<string>([trimmed]);
-	const unquoted = trimmed.replace(
-		/\."([^"]+)"(?=\.|$)/g,
-		(_, segment: string) => `.${segment}`
-	);
-	candidates.add(unquoted);
-	for (const candidate of candidates) {
-		if (SNAPSHOT_JSON_ENTITY_PATHS.has(candidate)) {
-			return "entity_id";
-		}
-	}
-	return null;
-}
-
-function isLogicalOperator(
-	operator: BinaryExpressionNode["operator"]
-): boolean {
-	return operator === "and" || operator === "or";
-}
-
-function isEqualityOperator(
-	operator: BinaryExpressionNode["operator"]
-): boolean {
-	return operator === "=" || operator === "is";
-}
-
-function mergeSummaries(
-	...summaries: ColumnPredicateSummary[]
-): ColumnPredicateSummary {
-	return summaries.reduce<ColumnPredicateSummary>(
-		(accumulator, current) => {
-			accumulator.count += current.count;
-			accumulator.literals.push(...current.literals);
-			return accumulator;
-		},
-		{ count: 0, literals: [] }
-	);
-}
-
-function mergeStringLiterals(
-	...lists: readonly (readonly string[])[]
-): string[] {
-	const seen = new Set<string>();
-	const merged: string[] = [];
-	for (const list of lists) {
-		for (const item of list) {
-			if (typeof item !== "string") {
-				continue;
-			}
-			if (!seen.has(item)) {
-				seen.add(item);
-				merged.push(item);
-			}
-		}
-	}
-	return merged;
-}
-
-function mergeSnapshotFilters(
-	...lists: readonly (readonly SnapshotJsonPredicate[] | undefined)[]
-): SnapshotJsonPredicate[] {
-	const merged = new Map<string, Set<string>>();
-	for (const list of lists) {
-		if (!list) {
-			continue;
-		}
-		for (const entry of list) {
-			if (!entry || typeof entry.path !== "string") {
-				continue;
-			}
-			const valueSet = merged.get(entry.path) ?? new Set<string>();
-			for (const value of entry.values ?? []) {
-				if (typeof value === "string") {
-					valueSet.add(value);
-				}
-			}
-			if (valueSet.size > 0) {
-				merged.set(entry.path, valueSet);
-			}
-		}
-	}
-	return Array.from(merged.entries()).map(([path, values]) => ({
-		path,
-		values: Array.from(values),
-	}));
-}
-
-function collectSelectedColumns(
-	select: SelectStatementNode,
-	tableNames: Set<string>
-): ColumnSelectionSummary {
-	const hiddenSelections = new Set<string>();
-	const supportColumns = new Set<string>();
-
-	if (select.projection.length === 0) {
-		return {
-			selectedColumns: null,
-			requestedHiddenColumns: hiddenSelections,
-			supportColumns,
-		};
-	}
-
-	const order: string[] = [];
-	const entries = new Map<string, SelectedProjection>();
-	let hasUnresolvedProjection = false;
-	let selectsAll = false;
-
-	for (const item of select.projection) {
-		if (isSelectAllForTable(item, tableNames)) {
-			selectsAll = true;
-			continue;
-		}
-		if (item.node_kind !== "select_expression") {
-			hasUnresolvedProjection = true;
-			continue;
-		}
-		const columnName = extractColumnFromExpression(item.expression, tableNames);
-		if (!columnName) {
-			hasUnresolvedProjection = true;
-			continue;
-		}
-		if (HIDDEN_SEGMENT_COLUMN_SET.has(columnName)) {
-			hiddenSelections.add(columnName);
-		}
-		const alias = getIdentifierValue(item.alias);
-		if (!entries.has(columnName)) {
-			order.push(columnName);
-			entries.set(columnName, {
-				column: columnName,
-				alias: alias ?? null,
-			});
-		} else if (alias) {
-			const existing = entries.get(columnName)!;
-			if (existing.alias === null) {
-				entries.set(columnName, {
-					column: columnName,
-					alias,
-				});
-			}
-		}
-	}
-
-	const referenced = collectReferencedColumnSummary(select, tableNames);
-	if (referenced.hasUnknownReferences) {
-		hasUnresolvedProjection = true;
-	}
-
-	for (const column of referenced.columns) {
-		if (HIDDEN_SEGMENT_COLUMN_SET.has(column)) {
-			hiddenSelections.add(column);
-		}
-		if (!entries.has(column)) {
-			supportColumns.add(column);
-		}
-	}
-
-	if (hasUnresolvedProjection || selectsAll) {
-		return {
-			selectedColumns: null,
-			requestedHiddenColumns: hiddenSelections,
-			supportColumns,
-		};
-	}
-
-	return {
-		selectedColumns: order.map((column) => entries.get(column)!),
-		requestedHiddenColumns: hiddenSelections,
-		supportColumns,
-	};
-}
-
-function collectReferencedColumnSummary(
-	select: SelectStatementNode,
-	tableNames: Set<string>
-): {
-	columns: Set<string>;
-	hasUnknownReferences: boolean;
-} {
-	const columns = new Set<string>();
-	let hasUnknownReferences = false;
-
-	const visit = (expression: ExpressionNode | RawFragmentNode | null) => {
-		if (hasUnknownReferences || !expression) {
-			return;
-		}
-		if ("sql_text" in expression) {
-			hasUnknownReferences = true;
-			return;
-		}
-		switch (expression.node_kind) {
-			case "column_reference": {
-				const qualifier = getColumnQualifier(expression);
-				if (qualifier && !tableNames.has(qualifier)) {
-					return;
-				}
-				const columnName = getColumnName(expression);
-				if (columnName) {
-					columns.add(columnName);
-				}
-				return;
-			}
-			case "binary_expression":
-				visit(expression.left);
-				visit(expression.right);
-				return;
-			case "unary_expression":
-				visit(expression.operand);
-				return;
-			case "grouped_expression":
-				visit(expression.expression);
-				return;
-			case "function_call":
-				for (const argument of expression.arguments) {
-					if (argument.node_kind === "all_columns") {
-						continue;
-					}
-					visit(argument);
-				}
-				return;
-			case "in_list_expression":
-				visit(expression.operand);
-				for (const item of expression.items) {
-					visit(item);
-				}
-				return;
-			case "between_expression":
-				visit(expression.operand);
-				visit(expression.start);
-				visit(expression.end);
-				return;
-			case "subquery_expression":
-				hasUnknownReferences = true;
-				return;
-			case "literal":
-			case "parameter":
-				return;
-			default:
-				return;
-		}
-	};
-
-	visit(select.where_clause);
-	for (const clause of select.from_clauses) {
-		for (const join of clause.joins) {
-			visit(join.on_expression);
-		}
-	}
-	for (const order of select.order_by) {
-		visit(order.expression);
-	}
-
-	return { columns, hasUnknownReferences };
-}
-
-function extractColumnFromExpression(
-	expression: ExpressionNode | RawFragmentNode,
-	tableNames: Set<string>
-): string | null {
-	if ("sql_text" in expression) {
-		return null;
-	}
-	switch (expression.node_kind) {
-		case "column_reference": {
-			const qualifier = getColumnQualifier(expression);
-			if (qualifier && !tableNames.has(qualifier)) {
-				return null;
-			}
-			return getColumnName(expression);
-		}
-		case "grouped_expression":
-			return extractColumnFromExpression(expression.expression, tableNames);
-		case "function_call":
-			return extractColumnFromFunctionCall(expression, tableNames);
-		default:
-			return null;
-	}
-}
-
-function extractColumnFromFunctionCall(
-	expression: Extract<ExpressionNode, { node_kind: "function_call" }>,
-	tableNames: Set<string>
-): string | null {
-	let referencedColumn: string | null = null;
-	for (const argument of expression.arguments) {
-		if (argument.node_kind === "all_columns") {
-			return null;
-		}
-		const extracted = extractColumnFromExpression(argument, tableNames);
-		if (extracted) {
-			if (referencedColumn && referencedColumn !== extracted) {
-				return null;
-			}
-			referencedColumn = extracted;
-			continue;
-		}
-		if (!isLiteralOrParameter(argument)) {
-			return null;
-		}
-	}
-	return referencedColumn;
-}
-
-function isLiteralOrParameter(
-	expression: ExpressionNode | RawFragmentNode
-): boolean {
-	if ("sql_text" in expression) {
-		return false;
-	}
-	switch (expression.node_kind) {
-		case "literal":
-		case "parameter":
-			return true;
-		case "grouped_expression":
-			return isLiteralOrParameter(expression.expression);
-		default:
-			return false;
-	}
-}
-
-function determineProjectionKind(
-	projection: readonly SelectItemNode[],
-	tableNames: Set<string>
-): "selectAll" | "partial" {
-	for (const item of projection) {
-		if (isSelectAllForTable(item, tableNames)) {
-			return "selectAll";
-		}
-	}
-	return "partial";
-}
-
-function buildTraceEntry(args: {
-	aliasList: readonly string[];
-	projectionKind: "selectAll" | "partial";
-	schemaSummary: ColumnPredicateSummary;
-	selectedColumns: SelectedProjection[] | null;
-}): PreprocessorTraceEntry {
-	const { aliasList, schemaSummary, projectionKind, selectedColumns } = args;
-	const referenceCount = aliasList.length === 0 ? 1 : aliasList.length;
-	return {
-		step: "rewrite_vtable_selects",
-		payload: {
-			reference_count: referenceCount,
-			aliases: aliasList,
-			projection: projectionKind,
-			schema_key_predicates: schemaSummary.count,
-			schema_key_literals: schemaSummary.literals,
-			selected_columns: selectedColumns
-				? selectedColumns.map((entry) => entry.column)
-				: null,
-		},
-	};
-}
-
-function buildVtableSelectRewrite(options: {
-	schemaKeys: readonly string[];
-	fileIds: readonly string[];
-	entityIds: readonly string[];
-	snapshotFilters: readonly SnapshotJsonPredicate[];
-	versionIds: readonly string[];
-	cacheTables: Map<string, unknown>;
-	selectedColumns: SelectedProjection[] | null;
-	hiddenColumns: ReadonlySet<string>;
-	supportColumns: ReadonlySet<string>;
-	hasOpenTransaction: boolean;
-	pruneInheritance: boolean;
-	pruneTransactionSegment: boolean;
-	versionInheritance?: VersionInheritanceMap;
-}): string {
-	const schemaFilterList = options.schemaKeys ?? [];
-	const requestedVersionIds = Array.from(new Set(options.versionIds ?? []));
-	const wantedVersionsCteName =
-		requestedVersionIds.length > 0 ? "wanted_versions" : null;
-	const { candidateColumns, rankedColumns } = buildProjectionColumnSet(
-		options.selectedColumns,
-		options.hiddenColumns,
-		options.supportColumns
-	);
-	candidateColumns.add("priority");
-	rankedColumns.add("priority");
-	const inheritancePlan = determineInheritancePlan({
-		requestedVersionIds: options.versionIds,
-		versionInheritance: options.versionInheritance,
-		forcedPrune: options.pruneInheritance,
-	});
-	const schemaFilter = buildSchemaFilter(schemaFilterList);
-	const fileFilter =
-		options.fileIds && options.fileIds.length > 0
-			? buildFileFilter(options.fileIds)
-			: null;
-	const entityFilter =
-		options.entityIds && options.entityIds.length > 0
-			? buildEntityFilter(options.entityIds)
-			: null;
-	const snapshotFilter = buildSnapshotContentFilter(options.snapshotFilters);
-	const txnFilter = combineFilters(
-		schemaFilter,
-		fileFilter,
-		entityFilter,
-		snapshotFilter
-	);
-	const inheritedFilter = combineFilters(
-		schemaFilter,
-		fileFilter,
-		entityFilter,
-		snapshotFilter
-	);
-	const buildVersionJoin = (alias: string, joinAlias: string) =>
-		buildWantedVersionJoinClause(wantedVersionsCteName, alias, joinAlias);
-	const txnVersionJoin = buildVersionJoin("txn", "wv_txn");
-	const untrackedVersionJoin = buildVersionJoin("unt", "wv_unt");
-	const cacheVersionJoin = buildVersionJoin("cache", "wv_cache");
-	const inheritanceVersionJoin = buildVersionJoin("vi", "wv_vi");
-	const parentVersionJoin = buildVersionJoin("vi", "wv_parent");
-	const needsWriterJoin = candidateColumns.has("writer_key");
-	if (needsWriterJoin) {
-		candidateColumns.add("inherited_from_version_id");
-		rankedColumns.add("inherited_from_version_id");
-	}
-	const needsChangeJoin = candidateColumns.has("metadata");
-	const projectionSql = buildRewriteProjectionSql(options.selectedColumns, {
-		supportColumns: options.supportColumns,
-		needsWriterJoin,
-		candidateColumns,
-	});
-	const cacheSource = buildCacheSource(
-		schemaFilterList,
-		options.cacheTables,
-		candidateColumns
-	);
-	const rankingOrder = [
-		"c.priority",
-		"c.created_at DESC",
-		"c.file_id",
-		"c.schema_key",
-		"c.entity_id",
-		"c.version_id",
-		"c.change_id",
-	];
-	const segments: string[] = [];
-	if (
-		options.hasOpenTransaction !== false &&
-		!options.pruneTransactionSegment
-	) {
-		segments.push(
-			buildTransactionSegment(txnFilter, candidateColumns, txnVersionJoin)
-		);
-	}
-	segments.push(
-		buildUntrackedSegment(txnFilter, candidateColumns, untrackedVersionJoin)
-	);
-	const cacheSegment = buildCacheSegment(
-		cacheSource,
-		txnFilter,
-		candidateColumns,
-		cacheVersionJoin
-	);
-	if (cacheSegment) {
-		segments.push(cacheSegment);
-	}
-	const shouldPruneInheritance = inheritancePlan.mode === "pruned";
-	let inheritanceJoinSource = "version_inheritance vi";
-	let parentJoinSource = "version_parent vi";
-	if (inheritancePlan.mode === "inline") {
-		inheritanceJoinSource = buildInlineInheritanceSource(
-			inheritancePlan.versionAncestorPairs
-		);
-		parentJoinSource = buildInlineParentSource(inheritancePlan.parentPairs);
-	}
-	let allSegments = segments;
-	if (!shouldPruneInheritance) {
-		const inheritedSegments: string[] = [];
-		if (cacheSegment) {
-			const inheritedCache = buildInheritedCacheSegment(
-				cacheSource,
-				inheritedFilter,
-				candidateColumns,
-				inheritanceJoinSource,
-				inheritanceVersionJoin
-			);
-			if (inheritedCache) {
-				inheritedSegments.push(inheritedCache);
-			}
-		}
-		inheritedSegments.push(
-			buildInheritedUntrackedSegment(
-				inheritedFilter,
-				candidateColumns,
-				inheritanceJoinSource,
-				inheritanceVersionJoin
-			)
-		);
-		if (options.hasOpenTransaction !== false) {
-			inheritedSegments.push(
-				buildInheritedTransactionSegment(
-					inheritedFilter,
-					candidateColumns,
-					parentJoinSource,
-					parentVersionJoin
-				)
-			);
-		}
-		allSegments = segments.concat(inheritedSegments);
-	}
-	const candidates = allSegments.join(`\n\n    UNION ALL\n\n`);
-
-	const writerJoinSql = needsWriterJoin
-		? `
-LEFT JOIN lix_internal_state_writer ws_dst ON
-  ws_dst.file_id = w.file_id AND
-  ws_dst.entity_id = w.entity_id AND
-  ws_dst.schema_key = w.schema_key AND
-  ws_dst.version_id = w.version_id
-LEFT JOIN lix_internal_state_writer ws_src ON
-  ws_src.file_id = w.file_id AND
-  ws_src.entity_id = w.entity_id AND
-  ws_src.schema_key = w.schema_key AND
-  ws_src.version_id = w.inherited_from_version_id`
-		: "";
-	const changeJoinSql = needsChangeJoin
-		? `
-LEFT JOIN lix_internal_change chc ON chc.id = w.change_id`
-		: "";
-	const transactionJoinSql =
-		options.hasOpenTransaction !== false
-			? `
-LEFT JOIN lix_internal_transaction_state itx ON itx.id = w.change_id`
-			: "";
-	const rankedSql = buildRankedSegment({
-		projectionColumns: rankedColumns,
-		rankingOrder,
-		candidatesSql: candidates,
-	});
-	const withClauses: string[] = [];
-	if (wantedVersionsCteName) {
-		withClauses.push(
-			buildWantedVersionsCte(wantedVersionsCteName, requestedVersionIds)
-		);
-	}
-	if (inheritancePlan.mode === "recursive") {
-		withClauses.push(buildVersionDescriptorCte());
-		withClauses.push(buildVersionInheritanceCte(wantedVersionsCteName));
-		withClauses.push(buildVersionParentCte(wantedVersionsCteName));
-	}
-	const withPrefix =
-		withClauses.length > 0
-			? `WITH
-${withClauses.map((clause) => indent(clause, 2)).join(",\n")}
-`
-			: "";
-
-	const body = `${withPrefix}SELECT
-${indent(projectionSql, 2)}
-FROM (
-${indent(rankedSql, 2)}
-) AS w
-${writerJoinSql}
-${changeJoinSql}
-${transactionJoinSql}
-WHERE w.rn = 1`;
-
-	return `(\n${body}\n)\n`;
-}
-
-function buildRewriteProjectionSql(
-	selectedColumns: SelectedProjection[] | null,
-	options: {
-		needsWriterJoin: boolean;
-		supportColumns: ReadonlySet<string>;
-		candidateColumns: ReadonlySet<string>;
-	}
-): string {
-	const builder = internalQueryBuilder as unknown as {
-		selectFrom: (table: string) => {
-			selectAll: (table: string) => { compile: () => { sql: string } };
-			select: (
-				callback: (eb: {
-					ref: (reference: string) => {
-						as: (alias: string) => unknown;
-					};
-					fn: any;
-				}) => unknown[]
-			) => { compile: () => { sql: string } };
-		};
-	};
-
-	const baseQuery = builder.selectFrom(`${INTERNAL_STATE_VTABLE} as w`);
-	const supportEntries =
-		selectedColumns === null
-			? []
-			: Array.from(options.supportColumns)
-					.filter(
-						(column) =>
-							!selectedColumns.some((entry) => entry.column === column) &&
-							!INTERNAL_ONLY_COLUMN_SET.has(column)
-					)
-					.map<SelectedProjection>((column) => ({
-						column,
-						alias: null,
-					}));
-	const combinedEntries =
-		selectedColumns === null ? null : [...selectedColumns, ...supportEntries];
-	const query =
-		combinedEntries === null || combinedEntries.length === 0
-			? undefined
-			: baseQuery.select((eb) =>
-					combinedEntries.map((entry) => {
-						if (options.needsWriterJoin && entry.column === "writer_key") {
-							return eb.fn
-								.coalesce(
-									eb.ref("ws_dst.writer_key"),
-									eb.ref("ws_src.writer_key"),
-									eb.ref("w.writer_key")
-								)
-								.as(entry.column) as unknown as any;
-						}
-						return eb.ref(`w.${entry.column}`).as(entry.column);
-					})
-				);
-
-	if (!query) {
-		const defaultColumns = buildDefaultProjectionColumns(
-			options.candidateColumns
-		);
-		return defaultColumns
-			.map((column) =>
-				options.needsWriterJoin && column === "writer_key"
-					? `COALESCE(ws_dst.writer_key, ws_src.writer_key, w.writer_key) AS ${quoteIdentifier(
-							column
-						)}`
-					: `w.${quoteIdentifier(column)} AS ${quoteIdentifier(column)}`
-			)
-			.join(",\n");
-	}
-
-	const { sql } = query.compile();
-	const match = sql.match(/^select\s+(?<projection>[\s\S]+?)\s+from\s+/i);
-	return match?.groups?.projection?.trim() ?? sql;
-}
-
-function buildDefaultProjectionColumns(
-	candidateColumns: ReadonlySet<string>
-): string[] {
-	const ordered = PROJECTION_COLUMN_ORDER.filter(
-		(column) =>
-			!INTERNAL_ONLY_COLUMN_SET.has(column) && candidateColumns.has(column)
-	) as string[];
-	const additional = Array.from(candidateColumns).filter(
-		(column) =>
-			!INTERNAL_ONLY_COLUMN_SET.has(column) && !ordered.includes(column)
-	);
-	return ordered.concat(additional.sort());
-}
-
-function buildProjectionColumnSet(
-	selectedColumns: SelectedProjection[] | null,
-	hiddenColumns: ReadonlySet<string>,
-	supportColumns: ReadonlySet<string>
-): {
-	candidateColumns: Set<string>;
-	rankedColumns: Set<string>;
-} {
-	const requestedHiddenColumns = new Set(hiddenColumns);
-	const seedColumns =
-		selectedColumns === null
-			? ALL_SEGMENT_COLUMNS
-			: Array.from(BASE_SEGMENT_COLUMNS);
-	const candidateColumns = new Set<string>();
-	const rankedColumns = new Set<string>();
-
-	for (const column of seedColumns) {
-		if (
-			HIDDEN_SEGMENT_COLUMN_SET.has(column) &&
-			!requestedHiddenColumns.has(column)
-		) {
-			continue;
-		}
-		candidateColumns.add(column);
-		rankedColumns.add(column);
-	}
-
-	if (selectedColumns && selectedColumns.length > 0) {
-		for (const entry of selectedColumns) {
-			candidateColumns.add(entry.column);
-			rankedColumns.add(entry.column);
-		}
-	}
-
-	for (const column of supportColumns) {
-		candidateColumns.add(column);
-		rankedColumns.add(column);
-	}
-
-	for (const hiddenColumn of requestedHiddenColumns) {
-		candidateColumns.add(hiddenColumn);
-		rankedColumns.add(hiddenColumn);
-	}
-
-	for (const hiddenColumn of HIDDEN_SEGMENT_COLUMN_SET) {
-		if (!requestedHiddenColumns.has(hiddenColumn)) {
-			candidateColumns.delete(hiddenColumn);
-			rankedColumns.delete(hiddenColumn);
-		}
-	}
-
-	// Internal rewrites rely on snapshot_content for JSON decoding and cache filtering.
-	candidateColumns.add("snapshot_content");
-	rankedColumns.add("snapshot_content");
-
-	return { candidateColumns, rankedColumns };
-}
-
-const NEWLINE = "\n";
-
-const ALL_SEGMENT_COLUMNS = [
-	"_pk",
-	"source_tag",
-	"entity_id",
-	"schema_key",
-	"file_id",
-	"plugin_key",
-	"snapshot_content",
-	"schema_version",
-	"version_id",
-	"created_at",
-	"updated_at",
-	"inherited_from_version_id",
-	"change_id",
-	"untracked",
-	"commit_id",
-	"metadata",
-	"writer_key",
-	"priority",
-] as const;
-
-const BASE_SEGMENT_COLUMNS = new Set<string>([
-	"entity_id",
-	"schema_key",
-	"file_id",
-	"version_id",
-	"created_at",
-	"change_id",
-	"priority",
-]);
-
-const CACHE_COLUMNS = [
-	"entity_id",
-	"schema_key",
-	"file_id",
-	"plugin_key",
-	"snapshot_content",
-	"schema_version",
-	"version_id",
-	"created_at",
-	"updated_at",
-	"inherited_from_version_id",
-	"change_id",
-	"commit_id",
-	"is_tombstone",
-] as const;
-
-const PROJECTION_COLUMN_ORDER = ALL_SEGMENT_COLUMNS.filter(
-	(column) => column !== "priority"
-);
-
-const INTERNAL_ONLY_COLUMN_SET = new Set<string>(["priority", "rn"]);
-
-function buildTransactionSegment(
-	segmentFilter: string | null,
-	projectionColumns: Set<string>,
-	versionJoinClause: string
-): string {
-	const rewrittenFilter = rewriteFilterForAlias(segmentFilter, "txn");
-	const filterClause = rewrittenFilter ? `WHERE ${rewrittenFilter}` : "";
-	const columns: Array<[string, string]> = [
-		[
-			"_pk",
-			`'T' || '~' || lix_encode_pk_part(txn.file_id) || '~' || lix_encode_pk_part(txn.entity_id) || '~' || lix_encode_pk_part(txn.version_id) AS _pk`,
-		],
-		["source_tag", "'T' AS source_tag"],
-		["entity_id", "txn.entity_id AS entity_id"],
-		["schema_key", "txn.schema_key AS schema_key"],
-		["file_id", "txn.file_id AS file_id"],
-		["plugin_key", "txn.plugin_key AS plugin_key"],
-		["snapshot_content", "json(txn.snapshot_content) AS snapshot_content"],
-		["schema_version", "txn.schema_version AS schema_version"],
-		["version_id", "txn.version_id AS version_id"],
-		["created_at", "txn.created_at AS created_at"],
-		["updated_at", "txn.created_at AS updated_at"],
-		["inherited_from_version_id", "NULL AS inherited_from_version_id"],
-		["change_id", "txn.id AS change_id"],
-		["untracked", "txn.untracked AS untracked"],
-		["commit_id", "'pending' AS commit_id"],
-		["metadata", "json(txn.metadata) AS metadata"],
-		["writer_key", "txn.writer_key AS writer_key"],
-		["priority", "1 AS priority"],
-	];
-	const columnSql = columns
-		.filter(([column]) => projectionColumns.has(column))
-		.map(([, sql]) => sql)
-		.join(",\n");
-	const joinClause = versionJoinClause ? `\n\t\t${versionJoinClause}` : "";
-	return stripIndent(`
-		SELECT
-${indent(columnSql, 4)}
-		FROM lix_internal_transaction_state txn${joinClause}
-		${filterClause}
-	`).trimEnd();
-}
-
-function buildUntrackedSegment(
-	segmentFilter: string | null,
-	projectionColumns: Set<string>,
-	versionJoinClause: string
-): string {
-	const rewrittenFilter = rewriteFilterForAlias(segmentFilter, "unt");
-	const columns: Array<[string, string]> = [
-		[
-			"_pk",
-			`'U' || '~' || lix_encode_pk_part(unt.file_id) || '~' || lix_encode_pk_part(unt.entity_id) || '~' || lix_encode_pk_part(unt.version_id) AS _pk`,
-		],
-		["source_tag", "'U' AS source_tag"],
-		["entity_id", "unt.entity_id AS entity_id"],
-		["schema_key", "unt.schema_key AS schema_key"],
-		["file_id", "unt.file_id AS file_id"],
-		["plugin_key", "unt.plugin_key AS plugin_key"],
-		["snapshot_content", "json(unt.snapshot_content) AS snapshot_content"],
-		["schema_version", "unt.schema_version AS schema_version"],
-		["version_id", "unt.version_id AS version_id"],
-		["created_at", "unt.created_at AS created_at"],
-		["updated_at", "unt.updated_at AS updated_at"],
-		["inherited_from_version_id", "NULL AS inherited_from_version_id"],
-		["change_id", "'untracked' AS change_id"],
-		["untracked", "1 AS untracked"],
-		["commit_id", "'untracked' AS commit_id"],
-		["metadata", "NULL AS metadata"],
-		["writer_key", "NULL AS writer_key"],
-		["priority", "2 AS priority"],
-	];
-	const columnSql = columns
-		.filter(([column]) => projectionColumns.has(column))
-		.map(([, sql]) => sql)
-		.join(",\n");
-	const joinClause = versionJoinClause ? `\n\t\t${versionJoinClause}` : "";
-	return stripIndent(`
-		SELECT
-${indent(columnSql, 4)}
-		FROM lix_internal_state_all_untracked unt${joinClause}
-		${rewrittenFilter ? `WHERE ${rewrittenFilter}` : ""}
-	`).trimEnd();
-}
-
-function buildCacheSegment(
-	cacheSource: string | null,
-	segmentFilter: string | null,
-	projectionColumns: Set<string>,
-	versionJoinClause: string
-): string | null {
-	if (!cacheSource) {
-		return null;
-	}
-	const rewrittenFilter = rewriteFilterForAlias(segmentFilter, "cache");
-	const sourceKeyword = cacheSource.trim().toLowerCase();
-	const sourceSql = sourceKeyword.startsWith("select")
-		? `(${cacheSource})`
-		: cacheSource;
-	const columns: Array<[string, string]> = [
-		[
-			"_pk",
-			`'C' || '~' || lix_encode_pk_part(cache.file_id) || '~' || lix_encode_pk_part(cache.entity_id) || '~' || lix_encode_pk_part(cache.version_id) AS _pk`,
-		],
-		["source_tag", "'C' AS source_tag"],
-		["entity_id", "cache.entity_id AS entity_id"],
-		["schema_key", "cache.schema_key AS schema_key"],
-		["file_id", "cache.file_id AS file_id"],
-		["plugin_key", "cache.plugin_key AS plugin_key"],
-		["snapshot_content", "json(cache.snapshot_content) AS snapshot_content"],
-		["schema_version", "cache.schema_version AS schema_version"],
-		["version_id", "cache.version_id AS version_id"],
-		["created_at", "cache.created_at AS created_at"],
-		["updated_at", "cache.updated_at AS updated_at"],
-		[
-			"inherited_from_version_id",
-			"cache.inherited_from_version_id AS inherited_from_version_id",
-		],
-		["change_id", "cache.change_id AS change_id"],
-		["untracked", "0 AS untracked"],
-		["commit_id", "cache.commit_id AS commit_id"],
-		["metadata", "NULL AS metadata"],
-		["writer_key", "NULL AS writer_key"],
-		["priority", "3 AS priority"],
-	];
-	const columnSql = columns
-		.filter(([column]) => projectionColumns.has(column))
-		.map(([, sql]) => sql)
-		.join(",\n");
-	const whereClause = rewrittenFilter ? `\n\t\tWHERE ${rewrittenFilter}` : "";
-	const joinClause = versionJoinClause ? `\n\t\t${versionJoinClause}` : "";
-	return stripIndent(`
-		SELECT
-${indent(columnSql, 4)}
-		FROM ${sourceSql} cache${joinClause}${whereClause}
-	`).trimEnd();
-}
-
-/**
- * Builds the base CTE extracting version descriptors for inheritance lookups.
- *
- * @returns SQL fragment for the version descriptor base CTE.
- *
- * @example
- * ```ts
- * const sql = buildVersionDescriptorCte();
- * ```
- */
-function buildVersionDescriptorCte(): string {
-	return stripIndent(`
-	version_descriptor_base AS (
-	  SELECT
-	    json_extract(desc.snapshot_content, '$.id') AS version_id,
-	    json_extract(desc.snapshot_content, '$.inherits_from_version_id') AS inherits_from_version_id
-	  FROM "lix_internal_state_cache_v1_lix_version_descriptor" desc
-	  WHERE desc.is_tombstone = 0
-	    AND desc.snapshot_content IS NOT NULL
-	)`).trim();
-}
-
-/**
- * Builds the recursive CTE that unfolds the full inheritance chain.
- *
- * @param seedCteName - Optional wanted version CTE that limits recursion seeds.
- * @returns SQL fragment for the version inheritance CTE.
- *
- * @example
- * ```ts
- * const sql = buildVersionInheritanceCte("wanted_versions");
- * ```
- */
-function buildVersionInheritanceCte(seedCteName: string | null): string {
-	const seedJoin = seedCteName
-		? `
-	  JOIN ${seedCteName} wv ON wv.version_id = vdb.version_id`
-		: "";
-	return stripIndent(`
-	version_inheritance(version_id, ancestor_version_id) AS (
-	  SELECT
-	    vdb.version_id,
-	    vdb.inherits_from_version_id
-	  FROM version_descriptor_base vdb${seedJoin}
-	  WHERE vdb.inherits_from_version_id IS NOT NULL
-
-	  UNION ALL
-
-	  SELECT
-	    vi.version_id,
-	    vdb.inherits_from_version_id
-	  FROM version_inheritance vi
-	  JOIN version_descriptor_base vdb ON vdb.version_id = vi.ancestor_version_id
-	  WHERE vdb.inherits_from_version_id IS NOT NULL
-	)`).trim();
-}
-
-/**
- * Builds the CTE mapping each version to its direct parent version.
- *
- * @param seedCteName - Optional wanted version CTE limiting descriptors.
- * @returns SQL fragment for the version parent CTE.
- *
- * @example
- * ```ts
- * const sql = buildVersionParentCte("wanted_versions");
- * ```
- */
-function buildVersionParentCte(seedCteName: string | null): string {
-	const seedJoin = seedCteName
-		? `
-	  JOIN ${seedCteName} wv ON wv.version_id = vdb.version_id`
-		: "";
-	return stripIndent(`
-	version_parent AS (
-	  SELECT
-	    vdb.version_id,
-	    vdb.inherits_from_version_id AS parent_version_id
-	  FROM version_descriptor_base vdb${seedJoin}
-	  WHERE vdb.inherits_from_version_id IS NOT NULL
-	)`).trim();
-}
-
-/**
- * Builds a CTE enumerating the requested versions for join-based filters.
- *
- * @param cteName - The identifier assigned to the CTE.
- * @param versionIds - Ordered list of version identifiers to include.
- * @returns SQL fragment for the wanted versions CTE.
- *
- * @example
- * ```ts
- * const sql = buildWantedVersionsCte("wanted_versions", ["v1", "v2"]);
- * ```
- */
-function buildWantedVersionsCte(
-	cteName: string,
-	versionIds: readonly string[]
-): string {
-	const selects = versionIds
-		.map((versionId) => `SELECT '${escapeSqlLiteral(versionId)}' AS version_id`)
-		.join("\nUNION ALL\n");
-	return stripIndent(`
-${cteName} AS (
-${indent(selects, 2)}
-)`).trim();
-}
-
-/**
- * Builds the inherited cache candidate segment that maps ancestor versions onto
- * the target schema version.
- *
- * @param cacheSource - The SQL producing the cache rows.
- * @param segmentFilter - Optional predicate scoped to the cache alias.
- * @param projectionColumns - Columns required for the projection.
- * @param versionJoinClause - SQL equi-join tying descendants to wanted versions.
- * @returns SQL fragment or null when no cache source exists.
- *
- * @example
- * ```ts
- * const sql = buildInheritedCacheSegment(
- *   '"cache_table"',
- *   "txn.schema_key = 'demo'",
- *   new Set(),
- *   "version_inheritance vi",
- *   "JOIN wanted_versions wv ON wv.version_id = vi.version_id"
- * );
- * ```
- */
-function buildInheritedCacheSegment(
-	cacheSource: string | null,
-	segmentFilter: string | null,
-	projectionColumns: Set<string>,
-	inheritanceJoin: string,
-	versionJoinClause: string
-): string | null {
-	if (!cacheSource) {
-		return null;
-	}
-	const rewrittenFilter = rewriteFilterForAlias(segmentFilter, "cache");
-	const sourceKeyword = cacheSource.trim().toLowerCase();
-	const sourceSql = sourceKeyword.startsWith("select")
-		? `(${cacheSource})`
-		: cacheSource;
-	const columns: Array<[string, string]> = [
-		[
-			"_pk",
-			`'CI' || '~' || lix_encode_pk_part(cache.file_id) || '~' || lix_encode_pk_part(cache.entity_id) || '~' || lix_encode_pk_part(vi.version_id) AS _pk`,
-		],
-		["source_tag", "'CI' AS source_tag"],
-		["entity_id", "cache.entity_id AS entity_id"],
-		["schema_key", "cache.schema_key AS schema_key"],
-		["file_id", "cache.file_id AS file_id"],
-		["plugin_key", "cache.plugin_key AS plugin_key"],
-		["snapshot_content", "json(cache.snapshot_content) AS snapshot_content"],
-		["schema_version", "cache.schema_version AS schema_version"],
-		["version_id", "vi.version_id AS version_id"],
-		["created_at", "cache.created_at AS created_at"],
-		["updated_at", "cache.updated_at AS updated_at"],
-		[
-			"inherited_from_version_id",
-			"cache.version_id AS inherited_from_version_id",
-		],
-		["change_id", "cache.change_id AS change_id"],
-		["untracked", "0 AS untracked"],
-		["commit_id", "cache.commit_id AS commit_id"],
-		["metadata", "NULL AS metadata"],
-		["writer_key", "NULL AS writer_key"],
-		["priority", "4 AS priority"],
-	];
-	const columnSql = columns
-		.filter(([column]) => projectionColumns.has(column))
-		.map(([, sql]) => sql)
-		.join(",\n");
-	const joinClause = versionJoinClause ? `\n\t\t${versionJoinClause}` : "";
-	return stripIndent(`
-		SELECT
-${indent(columnSql, 4)}
-		FROM ${inheritanceJoin}${joinClause}
-		JOIN ${sourceSql} cache ON cache.version_id = vi.ancestor_version_id
-		WHERE cache.is_tombstone = 0
-		  AND cache.snapshot_content IS NOT NULL${
-				rewrittenFilter ? ` AND ${rewrittenFilter}` : ""
-			}
-	`).trimEnd();
-}
-
-/**
- * Builds the inherited segment sourcing data from `lix_internal_state_all_untracked`.
- *
- * @param segmentFilter - Optional predicate scoped to the untracked alias.
- * @param projectionColumns - Columns required for the projection.
- * @param versionJoinClause - SQL equi-join tying descendants to wanted versions.
- * @returns SQL fragment selecting inherited untracked rows.
- *
- * @example
- * ```ts
- * const sql = buildInheritedUntrackedSegment(
- *   null,
- *   new Set(["entity_id"]),
- *   "version_inheritance vi",
- *   "JOIN wanted_versions wv ON wv.version_id = vi.version_id"
- * );
- * ```
- */
-function buildInheritedUntrackedSegment(
-	segmentFilter: string | null,
-	projectionColumns: Set<string>,
-	inheritanceJoin: string,
-	versionJoinClause: string
-): string {
-	const rewrittenFilter = rewriteFilterForAlias(segmentFilter, "unt");
-	const columns: Array<[string, string]> = [
-		[
-			"_pk",
-			`'UI' || '~' || lix_encode_pk_part(unt.file_id) || '~' || lix_encode_pk_part(unt.entity_id) || '~' || lix_encode_pk_part(vi.version_id) AS _pk`,
-		],
-		["source_tag", "'UI' AS source_tag"],
-		["entity_id", "unt.entity_id AS entity_id"],
-		["schema_key", "unt.schema_key AS schema_key"],
-		["file_id", "unt.file_id AS file_id"],
-		["plugin_key", "unt.plugin_key AS plugin_key"],
-		["snapshot_content", "json(unt.snapshot_content) AS snapshot_content"],
-		["schema_version", "unt.schema_version AS schema_version"],
-		["version_id", "vi.version_id AS version_id"],
-		["created_at", "unt.created_at AS created_at"],
-		["updated_at", "unt.updated_at AS updated_at"],
-		[
-			"inherited_from_version_id",
-			"unt.version_id AS inherited_from_version_id",
-		],
-		["change_id", "'untracked' AS change_id"],
-		["untracked", "1 AS untracked"],
-		["commit_id", "'untracked' AS commit_id"],
-		["metadata", "NULL AS metadata"],
-		["writer_key", "NULL AS writer_key"],
-		["priority", "5 AS priority"],
-	];
-	const columnSql = columns
-		.filter(([column]) => projectionColumns.has(column))
-		.map(([, sql]) => sql)
-		.join(",\n");
-	const joinClause = versionJoinClause ? `\n\t\t${versionJoinClause}` : "";
-	return stripIndent(`
-		SELECT
-${indent(columnSql, 4)}
-		FROM ${inheritanceJoin}${joinClause}
-		JOIN lix_internal_state_all_untracked unt ON unt.version_id = vi.ancestor_version_id
-		WHERE unt.is_tombstone = 0
-		  AND unt.snapshot_content IS NOT NULL${
-				rewrittenFilter ? ` AND ${rewrittenFilter}` : ""
-			}
-	`).trimEnd();
-}
-
-/**
- * Builds the inherited segment that projects transaction rows onto descendant
- * versions.
- *
- * @param segmentFilter - Optional predicate scoped to the transaction alias.
- * @param projectionColumns - Columns required for the projection.
- * @param versionJoinClause - SQL equi-join tying descendants to wanted versions.
- * @returns SQL fragment selecting inherited transaction rows.
- *
- * @example
- * ```ts
- * const sql = buildInheritedTransactionSegment(
- *   "txn.schema_key = 'demo'",
- *   new Set(["change_id"]),
- *   "version_parent vi",
- *   "JOIN wanted_versions wv ON wv.version_id = vi.version_id"
- * );
- * ```
- */
-function buildInheritedTransactionSegment(
-	segmentFilter: string | null,
-	projectionColumns: Set<string>,
-	parentJoinSource: string,
-	versionJoinClause: string
-): string {
-	const columns: Array<[string, string]> = [
-		[
-			"_pk",
-			`'TI' || '~' || lix_encode_pk_part(txn.file_id) || '~' || lix_encode_pk_part(txn.entity_id) || '~' || lix_encode_pk_part(vi.version_id) AS _pk`,
-		],
-		["source_tag", "'TI' AS source_tag"],
-		["entity_id", "txn.entity_id AS entity_id"],
-		["schema_key", "txn.schema_key AS schema_key"],
-		["file_id", "txn.file_id AS file_id"],
-		["plugin_key", "txn.plugin_key AS plugin_key"],
-		["snapshot_content", "json(txn.snapshot_content) AS snapshot_content"],
-		["schema_version", "txn.schema_version AS schema_version"],
-		["version_id", "vi.version_id AS version_id"],
-		["created_at", "txn.created_at AS created_at"],
-		["updated_at", "txn.created_at AS updated_at"],
-		[
-			"inherited_from_version_id",
-			"vi.parent_version_id AS inherited_from_version_id",
-		],
-		["change_id", "txn.id AS change_id"],
-		["untracked", "txn.untracked AS untracked"],
-		["commit_id", "'pending' AS commit_id"],
-		["metadata", "json(txn.metadata) AS metadata"],
-		["writer_key", "txn.writer_key AS writer_key"],
-		["priority", "6 AS priority"],
-	];
-	const columnSql = columns
-		.filter(([column]) => projectionColumns.has(column))
-		.map(([, sql]) => sql)
-		.join(",\n");
-	const rewrittenFilter = rewriteFilterForAlias(segmentFilter, "txn");
-	const joinClause = versionJoinClause ? `\n\t\t${versionJoinClause}` : "";
-	return stripIndent(`
-		SELECT
-${indent(columnSql, 4)}
-		FROM ${parentJoinSource}${joinClause}
-		JOIN lix_internal_transaction_state txn ON txn.version_id = vi.parent_version_id
-		WHERE vi.parent_version_id IS NOT NULL
-		  AND txn.snapshot_content IS NOT NULL${
-				rewrittenFilter ? ` AND ${rewrittenFilter}` : ""
-			}
-	`).trimEnd();
-}
-
-function buildRankedSegment(options: {
-	projectionColumns: Set<string>;
-	rankingOrder: string[];
-	candidatesSql: string;
-}): string {
-	const columns = ALL_SEGMENT_COLUMNS.filter((column) =>
-		options.projectionColumns.has(column)
-	).map((column) => `c.${column} AS ${column}`);
-	const orderClause = options.rankingOrder.join(", ");
-	const selectEntries = [
-		...columns,
-		`ROW_NUMBER() OVER (
-        PARTITION BY c.file_id, c.schema_key, c.entity_id, c.version_id
-        ORDER BY ${orderClause}
-      ) AS rn`,
-	];
-	return stripIndent(`
-		SELECT
-${indent(selectEntries.join(",\n"), 4)}
-		FROM (
-${indent(options.candidatesSql, 6)}
-		) AS c
-	`).trimEnd();
-}
-
-function buildSchemaFilter(schemaKeys: readonly string[]): string | null {
-	if (!schemaKeys || schemaKeys.length === 0) {
-		return null;
-	}
-	const values = schemaKeys.map((key) => `'${key}'`).join(", ");
-	return `txn.schema_key IN (${values})`;
-}
-
-function buildFileFilter(fileIds: readonly string[]): string | null {
-	if (!fileIds || fileIds.length === 0) {
-		return null;
-	}
-	const values = fileIds
-		.map((fileId) => `'${escapeSqlLiteral(fileId)}'`)
-		.join(", ");
-	return `txn.file_id IN (${values})`;
-}
-
-function buildEntityFilter(entityIds: readonly string[]): string | null {
-	if (!entityIds || entityIds.length === 0) {
-		return null;
-	}
-	const values = entityIds
-		.map((entityId) => `'${escapeSqlLiteral(entityId)}'`)
-		.join(", ");
-	return `txn.entity_id IN (${values})`;
-}
-
-function buildSnapshotContentFilter(
-	filters: readonly SnapshotJsonPredicate[]
-): string | null {
-	if (!filters || filters.length === 0) {
-		return null;
-	}
-	const clauses = filters
-		.map((filter) => buildSnapshotPredicateClause(filter))
-		.filter((clause): clause is string => typeof clause === "string");
-	if (clauses.length === 0) {
-		return null;
-	}
-	return clauses.map((clause) => `(${clause})`).join(" AND ");
-}
-
-function buildSnapshotPredicateClause(
-	filter: SnapshotJsonPredicate
-): string | null {
-	const uniqueValues = Array.from(new Set(filter.values));
-	if (uniqueValues.length === 0) {
-		return null;
-	}
-	const pathLiteral = `'${escapeSqlLiteral(filter.path)}'`;
-	if (uniqueValues.length === 1) {
-		const value = escapeSqlLiteral(uniqueValues[0]!);
-		return `json_extract(txn.snapshot_content, ${pathLiteral}) = '${value}'`;
-	}
-	const valueList = uniqueValues
-		.map((value) => `'${escapeSqlLiteral(value)}'`)
-		.join(", ");
-	return `json_extract(txn.snapshot_content, ${pathLiteral}) IN (${valueList})`;
-}
-
-/**
- * Builds an equi-join clause tying a table alias to the wanted versions CTE.
- *
- * @param cteName - Name of the wanted versions CTE.
- * @param targetAlias - Table alias exposing a `version_id` column.
- * @param joinAlias - Alias assigned to the join for readability.
- * @returns SQL JOIN clause or an empty string when no CTE is provided.
- *
- * @example
- * ```ts
- * const joinSql = buildWantedVersionJoinClause("wanted_versions", "txn", "wv_txn");
- * ```
- */
-function buildWantedVersionJoinClause(
-	cteName: string | null,
-	targetAlias: string,
-	joinAlias: string
-): string {
-	if (!cteName) {
-		return "";
-	}
-	return `JOIN ${cteName} ${joinAlias} ON ${joinAlias}.version_id = ${targetAlias}.version_id`;
-}
-
-function buildCacheSource(
-	schemaKeys: readonly string[],
-	cacheTables: Map<string, unknown>,
-	projectionColumns: Set<string>
-): string | null {
-	const requiredColumns = new Set(projectionColumns);
-	// Always keep structural columns that power tombstone filtering and ranking.
-	requiredColumns.add("snapshot_content");
-	requiredColumns.add("is_tombstone");
-	requiredColumns.add("file_id");
-	requiredColumns.add("entity_id");
-	requiredColumns.add("schema_key");
-	requiredColumns.add("version_id");
-	requiredColumns.add("change_id");
-	requiredColumns.add("created_at");
-	const uniqueKeys =
-		schemaKeys && schemaKeys.length > 0
-			? Array.from(new Set(schemaKeys))
-			: Array.from(cacheTables.keys());
-	const seenTables = new Set<string>();
-	const entries = uniqueKeys
-		.map((key) => {
-			const lookupKeys = new Set<string>([key]);
-			const sanitizedKey = cacheTableNameToSchemaKey(
-				schemaKeyToCacheTableName(key)
-			);
-			if (sanitizedKey !== key) {
-				lookupKeys.add(sanitizedKey);
-			}
-			for (const lookupKey of lookupKeys) {
-				const tableName = cacheTables.get(lookupKey);
-				if (
-					typeof tableName === "string" &&
-					tableName.length > 0 &&
-					!seenTables.has(tableName)
-				) {
-					seenTables.add(tableName);
-					return {
-						tableName,
-						sql: buildPhysicalCacheSelect(tableName, requiredColumns),
-					};
-				}
-			}
-			return null;
-		})
-		.filter(
-			(value): value is { tableName: string; sql: string } => value !== null
-		);
-
-	if (entries.length === 0) {
-		return null;
-	}
-	if (entries.length === 1) {
-		return quoteIdentifier(entries[0]!.tableName);
-	}
-	return entries.map((entry) => entry.sql).join(`\nUNION ALL\n`);
-}
-
-function buildPhysicalCacheSelect(
-	tableName: string,
-	requiredColumns: Set<string>
-): string {
-	const projection = CACHE_COLUMNS.filter((column) =>
-		requiredColumns.has(column)
-	)
-		.map((column) => quoteIdentifier(column))
-		.join(",\n    ");
-	return `SELECT
-    ${projection}
-  FROM ${quoteIdentifier(tableName)}`;
-}
-
-/**
- * Resolves the cache table name for the provided schema key, falling back to its sanitized form.
- *
- * @example
- * ```ts
- * resolveCacheTableName(new Map([["delete_cache_schema", "cache_table"]]), "delete_cache_schema");
- * // "cache_table"
- * ```
- */
-function stripIndent(value: string): string {
-	const trimmed = value.replace(/^\n+/, "").replace(/\n+$/, "");
-	const lines = trimmed.split(NEWLINE);
-	const indents = lines
-		.filter((line) => line.trim().length > 0)
-		.map((line) => line.match(/^\s*/)?.[0]?.length ?? 0);
-	const minIndent = indents.length > 0 ? Math.min(...indents) : 0;
-	return lines.map((line) => line.slice(minIndent)).join(NEWLINE);
-}
-
-function indent(value: string, spaces: number): string {
-	const pad = " ".repeat(spaces);
-	return value
-		.split(NEWLINE)
-		.map((line) => (line.length > 0 ? pad + line : line))
-		.join(NEWLINE);
-}
-
-function quoteIdentifier(identifier: string): string {
-	return `"${identifier.replace(/"/g, '""')}"`;
-}
-
-function shouldPushFileFilter(
-	schemaKeys: readonly string[],
-	fileIds: readonly string[]
-): boolean {
-	if (!schemaKeys || schemaKeys.length === 0) return false;
-	if (!fileIds || fileIds.length === 0) return false;
-	return schemaKeys.every(
-		(key) => typeof key === "string" && !key.startsWith("lix_")
-	);
-}
-
-function shouldPushEntityFilter(
-	schemaKeys: readonly string[],
-	entityIds: readonly string[]
-): boolean {
-	if (!schemaKeys || schemaKeys.length === 0) return false;
-	if (!entityIds || entityIds.length === 0) return false;
-	return schemaKeys.every(
-		(key) => typeof key === "string" && !key.startsWith("lix_")
-	);
-}
-
-function shouldPushSnapshotFilters(
-	schemaKeys: readonly string[],
-	filters: readonly SnapshotJsonPredicate[]
-): boolean {
-	if (!schemaKeys || schemaKeys.length === 0) return false;
-	if (!filters || filters.length === 0) return false;
-	return schemaKeys.every(
-		(key) => typeof key === "string" && !key.startsWith("lix_")
-	);
-}
-
-function combineFilters(
-	...filters: Array<string | null | undefined>
-): string | null {
-	const active = filters.filter(
-		(filter): filter is string =>
-			typeof filter === "string" && filter.length > 0
-	);
-	if (active.length === 0) {
-		return null;
-	}
-	if (active.length === 1) {
-		return active[0]!;
-	}
-	return active.map((filter) => `(${filter})`).join(" AND ");
-}
-
-function rewriteFilterForAlias(
-	filter: string | null,
-	alias: string
-): string | null {
-	if (!filter) {
-		return null;
-	}
-	return filter.replace(/txn\./g, `${alias}.`);
-}
-
-function normalizeObjectName(objectName: ObjectNameNode): string | null {
-	if (objectName.parts.length === 0) {
-		return null;
-	}
-	const last = objectName.parts[objectName.parts.length - 1]!;
-	return normalizeIdentifierValue(last.value);
-}
-
-function escapeSqlLiteral(value: string): string {
-	return value.replace(/'/g, "''");
-}
-
-type InheritancePlan =
-	| { mode: "pruned" }
-	| { mode: "recursive" }
-	| {
-			mode: "inline";
-			versionAncestorPairs: Array<{ versionId: string; ancestorId: string }>;
-			parentPairs: Array<{ versionId: string; parentId: string }>;
-	  };
-
-function determineInheritancePlan(args: {
-	requestedVersionIds: readonly string[];
-	versionInheritance?: VersionInheritanceMap;
-	forcedPrune: boolean;
-}): InheritancePlan {
-	const requested = Array.from(new Set(args.requestedVersionIds ?? []));
-
-	if (args.forcedPrune) {
-		return { mode: "pruned" };
-	}
-
-	if (requested.length === 0) {
-		return args.versionInheritance ? { mode: "recursive" } : { mode: "pruned" };
-	}
-
-	if (!args.versionInheritance || args.versionInheritance.size === 0) {
-		return { mode: "pruned" };
-	}
-
-	const ancestorPairs: Array<{ versionId: string; ancestorId: string }> = [];
-	const parentPairs: Array<{ versionId: string; parentId: string }> = [];
-	const ancestorSeen = new Set<string>();
-	const parentSeen = new Set<string>();
-
-	for (const versionId of requested) {
-		let current = versionId;
-		const chainVisited = new Set<string>([current]);
-		while (true) {
-			const node = args.versionInheritance.get(current);
-			if (!node) {
-				return {
-					mode: "recursive",
-				};
-			}
-			const parentId = node.inheritsFromVersionId;
-			if (!parentId) {
-				break;
-			}
-			if (chainVisited.has(parentId)) {
-				return {
-					mode: "recursive",
-				};
-			}
-			chainVisited.add(parentId);
-
-			const ancestorKey = `${versionId}::${parentId}`;
-			if (!ancestorSeen.has(ancestorKey)) {
-				ancestorSeen.add(ancestorKey);
-				ancestorPairs.push({ versionId, ancestorId: parentId });
-			}
-
-			const parentKey = `${current}::${parentId}`;
-			if (!parentSeen.has(parentKey)) {
-				parentSeen.add(parentKey);
-				parentPairs.push({ versionId: current, parentId });
-			}
-
-			current = parentId;
-		}
-	}
-
-	if (ancestorPairs.length === 0) {
-		return { mode: "pruned" };
-	}
-
-	return {
-		mode: "inline",
-		versionAncestorPairs: ancestorPairs,
-		parentPairs,
-	};
-}
-
-function buildInlineInheritanceSource(
-	pairs: Array<{ versionId: string; ancestorId: string }>
-): string {
-	return buildInlineValueSource(
-		pairs.map(({ versionId, ancestorId }) => [versionId, ancestorId]),
-		["version_id", "ancestor_version_id"]
-	);
-}
-
-function buildInlineParentSource(
-	pairs: Array<{ versionId: string; parentId: string }>
-): string {
-	return buildInlineValueSource(
-		pairs.map(({ versionId, parentId }) => [versionId, parentId]),
-		["version_id", "parent_version_id"]
-	);
-}
-
-function buildInlineValueSource(
-	rows: Array<[string, string]>,
-	columns: [string, string]
-): string {
-	const selects = rows
-		.map(
-			([left, right]) =>
-				`SELECT '${escapeSqlLiteral(left)}' AS ${columns[0]}, '${escapeSqlLiteral(right)}' AS ${columns[1]}`
-		)
-		.join("\nUNION ALL\n");
-	return `(\n${selects}\n) AS vi`;
-}