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

package/src/engine/preprocessor/entity-views/shared.ts

@@ -1,1560 +0,0 @@
-import type { IToken } from "chevrotain";
-import type { LixEngine } from "../../boot.js";
-import {
-	columnReference,
-	identifier,
-	type ColumnReferenceNode,
-	type CompoundSelectNode,
-	type ExpressionNode,
-	type FunctionCallExpressionNode,
-	type FunctionCallArgumentNode,
-	type LiteralNode,
-	type ParameterExpressionNode,
-	type RawFragmentNode,
-	type SelectStatementNode,
-	type OrderByItemNode,
-	type WindowSpecificationNode,
-	type WindowReferenceNode,
-	type WindowFrameNode,
-	type WindowFrameBoundNode,
-} from "../sql-parser/nodes.js";
-import { expressionToSql } from "../sql-parser/compile.js";
-import { getColumnName } from "../sql-parser/ast-helpers.js";
-import { Ident, QIdent } from "../../sql-parser/tokenizer.js";
-import {
-	parseJsonPointer,
-	buildSqliteJsonPath,
-} from "../../../schema-definition/json-pointer.js";
-import { isJsonType } from "../../../schema-definition/json-type.js";
-import type { CelEnvironment } from "../../cel-environment/cel-environment.js";
-import { getStoredSchema } from "../../../stored-schema/get-stored-schema.js";
-import type { LixSchemaDefinition } from "../../../schema-definition/definition.js";
-import { LixSchemaViewMap } from "../../../database/schema-view-map.js";
-
-export const escapeSqlString = (input: string): string =>
-	input.replace(/'/g, "''");
-
-export const literal = (value: unknown): string => {
-	if (value === undefined || value === null) {
-		return "NULL";
-	}
-	if (typeof value === "number") {
-		if (!Number.isFinite(value)) {
-			return "NULL";
-		}
-		return String(value);
-	}
-	if (typeof value === "bigint") {
-		return value.toString();
-	}
-	if (typeof value === "boolean") {
-		return value ? "1" : "0";
-	}
-	if (typeof value === "string") {
-		return `'${escapeSqlString(value)}'`;
-	}
-	if (value instanceof Uint8Array) {
-		let hex = "";
-		for (const byte of value) {
-			hex += byte.toString(16).padStart(2, "0");
-		}
-		return `X'${hex}'`;
-	}
-	if (value instanceof Date) {
-		return `'${escapeSqlString(value.toISOString())}'`;
-	}
-	const serialized = JSON.stringify(value);
-	if (serialized === undefined) {
-		return "NULL";
-	}
-	return `'${escapeSqlString(serialized)}'`;
-};
-
-/**
- * Result emitted by entity view rewriters. When null is returned the
- * preprocessor should fall back to executing the original statement.
- */
-export type RewriteResult = {
-	sql: string;
-};
-
-export type ExpressionValue = { kind: "expression"; sql: string };
-
-export const isExpressionValue = (value: unknown): value is ExpressionValue =>
-	typeof value === "object" &&
-	value !== null &&
-	(value as Partial<ExpressionValue>).kind === "expression" &&
-	typeof (value as Partial<ExpressionValue>).sql === "string";
-
-export function deserializeJsonParameter(value: unknown): unknown {
-	if (value == null) return null;
-	if (typeof value !== "string") {
-		return value;
-	}
-	return JSON.parse(value);
-}
-
-export function buildColumnValueMap(
-	columns: readonly string[],
-	values: readonly unknown[]
-): Map<string, unknown> | null {
-	if (columns.length !== values.length) return null;
-	const map = new Map<string, unknown>();
-	for (let i = 0; i < columns.length; i++) {
-		const columnName = columns[i];
-		if (columnName === undefined) return null;
-		map.set(columnName, values[i]);
-	}
-	return map;
-}
-
-export function buildColumnExpressionMap(
-	columns: readonly string[],
-	expressions: readonly string[]
-): Map<string, string> | null {
-	if (columns.length !== expressions.length) return null;
-	const map = new Map<string, string>();
-	for (let i = 0; i < columns.length; i++) {
-		const columnName = columns[i];
-		if (columnName === undefined) return null;
-		const expr = expressions[i];
-		if (expr === undefined) return null;
-		map.set(columnName, expr);
-	}
-	return map;
-}
-
-/**
- * Builds a map from lower-case property names to their canonical casing.
- *
- * @example
- * ```ts
- * const lookup = buildPropertyLookup(schema);
- * lookup.get("name"); // => "name"
- * ```
- */
-export function buildPropertyLookup(
-	schema: LixSchemaDefinition
-): Map<string, string> {
-	const map = new Map<string, string>();
-	const properties = schema.properties ?? {};
-	for (const property of Object.keys(properties)) {
-		map.set(property.toLowerCase(), property);
-	}
-	return map;
-}
-
-/**
- * Finds the index of a keyword in a token stream, starting at a given offset.
- */
-export function findKeyword(
-	tokens: IToken[],
-	start: number,
-	keyword: string
-): number {
-	const target = keyword.toUpperCase();
-	for (let i = start; i < tokens.length; i++) {
-		const image = tokens[i]?.image;
-		if (!image) continue;
-		if (image.toUpperCase() === target) {
-			return i;
-		}
-	}
-	return -1;
-}
-
-/**
- * Extracts the SQL identifier name from either a quoted or unquoted token.
- */
-export function extractIdentifier(token: IToken | undefined): string | null {
-	if (!token?.image) return null;
-	if (token.tokenType === QIdent) {
-		return token.image.slice(1, -1).replace(/""/g, '"');
-	}
-	if (token.tokenType === Ident) {
-		return token.image;
-	}
-	return null;
-}
-
-/**
- * Categorises an entity view by its suffix (base, _by_version, or _history).
- */
-export type EntityViewVariant = "base" | "by_version" | "history";
-
-export function classifyViewVariant(name: string): EntityViewVariant {
-	const lower = name.toLowerCase();
-	if (lower.endsWith("_by_version")) return "by_version";
-	if (lower.endsWith("_history")) return "history";
-	return "base";
-}
-
-/**
- * Removes variant suffixes from a view name to recover the stored schema key.
- */
-export function baseSchemaKey(name: string): string | null {
-	const lower = name.toLowerCase();
-	if (lower.endsWith("_by_version")) return name.slice(0, -11);
-	if (lower.endsWith("_history")) return name.slice(0, -8);
-	return name;
-}
-
-const VIEW_VARIANT_TO_KEY: Record<"base" | "by_version" | "history", string> = {
-	base: "state",
-	by_version: "state_by_version",
-	history: "state_history",
-};
-
-/**
- * Returns true if a specific view variant is enabled for the schema.
- */
-export function isEntityViewVariantEnabled(
-	schema: LixSchemaDefinition,
-	variant: "base" | "by_version" | "history"
-): boolean {
-	const selected = schema?.["x-lix-entity-views"];
-	if (!Array.isArray(selected)) {
-		return true;
-	}
-	const viewKey = VIEW_VARIANT_TO_KEY[variant];
-	return selected.some(
-		(entry): boolean =>
-			typeof entry === "string" && entry.toLowerCase() === viewKey
-	);
-}
-
-export function resolveStoredSchemaKey(
-	schema: LixSchemaDefinition,
-	fallbackKey: string
-): string {
-	const key = schema?.["x-lix-key"];
-	if (typeof key === "string" && key.length > 0) {
-		return key;
-	}
-	return fallbackKey;
-}
-
-function candidateStoredSchemaKeys(schemaKey: string): string[] {
-	if (!schemaKey) {
-		return [];
-	}
-	const candidates = [schemaKey];
-	if (!schemaKey.startsWith("lix_")) {
-		candidates.push(`lix_${schemaKey}`);
-	}
-	return candidates;
-}
-
-export function loadLixSchemaDefinition(
-	engine: Pick<LixEngine, "executeSync" | "runtimeCacheRef" | "hooks">,
-	schemaKey: string
-): LixSchemaDefinition | null {
-	for (const candidate of candidateStoredSchemaKeys(schemaKey)) {
-		const schema = getStoredSchema({ engine, key: candidate });
-		if (schema) {
-			return schema;
-		}
-	}
-	return null;
-}
-
-/**
- * Extracts the lower-cased primary key fields from a stored schema.
- */
-export interface PrimaryKeyDescriptor {
-	readonly column: string;
-	readonly rootColumn: string;
-	readonly path: readonly string[];
-}
-
-export function extractPrimaryKeys(
-	schema: LixSchemaDefinition
-): PrimaryKeyDescriptor[] | null {
-	const pk = schema["x-lix-primary-key"];
-	if (!Array.isArray(pk) || pk.length === 0) {
-		return null;
-	}
-
-	const descriptors: PrimaryKeyDescriptor[] = [];
-	for (const entry of pk) {
-		if (typeof entry !== "string" || entry.length === 0) {
-			return null;
-		}
-		if (!entry.startsWith("/")) {
-			return null;
-		}
-		const segments = parseJsonPointer(entry);
-		if (segments.length === 0) {
-			return null;
-		}
-		const root = segments[0]!.toLowerCase();
-		const column = segments[segments.length - 1]!.toLowerCase();
-		descriptors.push({
-			column,
-			rootColumn: root,
-			path: segments.map((segment) => segment),
-		});
-	}
-	return descriptors;
-}
-
-export interface PointerColumnDescriptor {
-	readonly alias: string;
-	readonly path: readonly string[];
-	readonly matchers: readonly string[];
-}
-
-/**
- * Derives column expressions for JSON pointers referenced by a schema's primary key.
- * These descriptors allow entity view rewrites to match WHERE clauses that target
- * nested structures using either the pointer name (e.g. `/value/x-lix-key`) or
- * friendly aliases such as `key`.
- *
- * @example
- * const columns = collectPointerColumnDescriptors({ schema });
- * // columns[0]?.alias === "key"
- * // columns[0]?.expression === `json_extract(snapshot_content, '$.value."x-lix-key"')`
- */
-export function collectPointerColumnDescriptors(args: {
-	schema: LixSchemaDefinition;
-	primaryKeys?: PrimaryKeyDescriptor[] | null;
-}): PointerColumnDescriptor[] {
-	const primaryKeys = args.primaryKeys ?? extractPrimaryKeys(args.schema);
-	if (!primaryKeys || primaryKeys.length === 0) {
-		return [];
-	}
-
-	const descriptors = new Map<string, PointerColumnDescriptor>();
-	for (const descriptor of primaryKeys) {
-		if (!descriptor.path || descriptor.path.length <= 1) {
-			continue;
-		}
-		const lastSegment = descriptor.path.at(-1) ?? "";
-		const aliasInfo = buildPointerAliasInfo(lastSegment);
-		if (!aliasInfo) continue;
-
-		const aliasLower = aliasInfo.alias.toLowerCase();
-		if (descriptors.has(aliasLower)) {
-			continue;
-		}
-
-		const expressionPath = descriptor.path;
-		const matcherSet = new Set<string>();
-		for (const matcher of aliasInfo.matchers) {
-			if (matcher.length > 0) {
-				matcherSet.add(matcher.toLowerCase());
-			}
-		}
-		if (descriptor.column.length > 0) {
-			matcherSet.add(descriptor.column.toLowerCase());
-		}
-
-		descriptors.set(aliasLower, {
-			alias: aliasInfo.alias,
-			path: expressionPath,
-			matchers: Array.from(matcherSet),
-		});
-	}
-
-	return Array.from(descriptors.values());
-}
-
-/**
- * Helper that returns an explicitly provided column value or a fallback default.
- */
-export function getColumnOrDefault(
-	columnMap: Map<string, unknown>,
-	column: string,
-	defaultValue: unknown
-): unknown {
-	if (columnMap.has(column)) {
-		return columnMap.get(column);
-	}
-	const lowerColumn = column.toLowerCase();
-	if (columnMap.has(lowerColumn)) {
-		return columnMap.get(lowerColumn);
-	}
-	return defaultValue;
-}
-
-/**
- * Evaluates metadata overrides defined via x-lix-override-lixcols. Values that are strings are treated
- * as CEL expressions; other primitive values are passed through unchanged.
- */
-export function resolveMetadataDefaults(args: {
-	defaults: unknown;
-	cel: CelEnvironment | null;
-	context?: Record<string, unknown>;
-}): Map<string, unknown> {
-	const { defaults, cel } = args;
-	const resolved = new Map<string, unknown>();
-	if (!defaults || typeof defaults !== "object") {
-		return resolved;
-	}
-
-	const context = args.context ?? {};
-	for (const [key, raw] of Object.entries(
-		defaults as Record<string, unknown>
-	)) {
-		if (typeof raw === "string") {
-			if (!cel) {
-				throw new Error(
-					`Encountered x-lix-override-lixcols entry "${key}" but CEL evaluation is not initialised.`
-				);
-			}
-			const value = cel.evaluate(raw, { ...context });
-			if (value !== undefined) {
-				resolved.set(key, value);
-				context[key] = value as unknown;
-			}
-			continue;
-		}
-		if (raw !== undefined) {
-			const normalized = normalizeOverrideValue(raw);
-			resolved.set(key, normalized);
-			context[key] = normalized as unknown;
-		}
-	}
-
-	return resolved;
-}
-
-export function normalizeOverrideValue(value: unknown): unknown {
-	if (typeof value !== "string") {
-		return value;
-	}
-	const trimmed = value.trim();
-	if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
-		try {
-			return JSON.parse(trimmed);
-		} catch (error) {
-			void error;
-		}
-	}
-	return value;
-}
-
-export function buildSnapshotObjectExpression(args: {
-	schema: LixSchemaDefinition;
-	columnMap: Map<string, unknown>;
-	columnExpressions: Map<string, string>;
-	literal: (value: unknown) => string;
-	cel: CelEnvironment | null;
-	context: Record<string, unknown>;
-	resolvedDefaults: Map<string, unknown>;
-}): string {
-	const properties = Object.keys(args.schema.properties ?? {});
-	if (properties.length === 0) {
-		return "json_object()";
-	}
-	const entries: string[] = [];
-	for (const prop of properties) {
-		const def = (args.schema.properties ?? {})[prop];
-		const lower = prop.toLowerCase();
-		if (!args.columnMap.has(lower)) {
-			const defaultExpr = renderDefaultSnapshotValue({
-				propertyName: prop,
-				definition: def,
-				literal: args.literal,
-				cel: args.cel,
-				context: args.context,
-				resolvedDefaults: args.resolvedDefaults,
-			});
-			entries.push(`'${escapeSqlString(prop)}', ${defaultExpr}`);
-			continue;
-		}
-		const rawValue = args.columnMap.get(lower);
-		const expression = args.columnExpressions.get(lower) ?? null;
-		const snapshotExpr = renderSnapshotValue({
-			definition: def,
-			value: rawValue,
-			expression,
-		});
-		entries.push(`'${escapeSqlString(prop)}', ${snapshotExpr}`);
-	}
-	return `json_object(${entries.join(", ")})`;
-}
-
-export function buildCelContext(args: {
-	columnMap: Map<string, unknown>;
-	propertyLowerToActual: Map<string, string>;
-}): Record<string, unknown> {
-	const context: Record<string, unknown> = {};
-	for (const [lowerName, actualName] of args.propertyLowerToActual.entries()) {
-		if (!args.columnMap.has(lowerName)) continue;
-		const raw = args.columnMap.get(lowerName);
-		if (raw === undefined || isExpressionValue(raw)) continue;
-		context[actualName] = raw;
-	}
-	return context;
-}
-
-export function renderPointerExpression(args: {
-	descriptor: PrimaryKeyDescriptor;
-	columnMap: Map<string, unknown>;
-	columnExpressions: Map<string, string>;
-}): string | null {
-	const path = args.descriptor.path;
-	if (path.length === 0) {
-		return null;
-	}
-	const root = path[0]!.toLowerCase();
-	const baseValue = args.columnMap.get(root);
-	const baseExpr = (() => {
-		const expr = args.columnExpressions.get(root);
-		if (expr) return expr;
-		if (baseValue === undefined) return null;
-		if (isExpressionValue(baseValue)) {
-			return baseValue.sql;
-		}
-		return literal(baseValue);
-	})();
-	if (!baseExpr) {
-		return null;
-	}
-	if (path.length === 1) {
-		return baseExpr;
-	}
-	const jsonPath = buildSqliteJsonPath(path.slice(1));
-	return `json_extract(${baseExpr}, '${jsonPath}')`;
-}
-
-export function renderDefaultSnapshotValue(args: {
-	propertyName: string;
-	definition: unknown;
-	literal: (value: unknown) => string;
-	cel: CelEnvironment | null;
-	context: Record<string, unknown>;
-	resolvedDefaults: Map<string, unknown>;
-}): string {
-	const {
-		propertyName,
-		definition,
-		literal: literalFn,
-		cel,
-		context,
-		resolvedDefaults,
-	} = args;
-
-	if (resolvedDefaults.has(propertyName)) {
-		const cached = resolvedDefaults.get(propertyName);
-		return renderSnapshotValue({ definition, value: cached, expression: null });
-	}
-
-	if (!definition || typeof definition !== "object") {
-		return "NULL";
-	}
-
-	const record = definition as Record<string, unknown>;
-	const celExpression = record["x-lix-default"];
-	if (typeof celExpression === "string") {
-		if (!cel) {
-			throw new Error(
-				`Encountered x-lix-default on ${propertyName} but CEL evaluation is not initialised.`
-			);
-		}
-		const value = cel.evaluate(celExpression, { ...context });
-		resolvedDefaults.set(propertyName, value);
-		return renderSnapshotValue({
-			definition,
-			value,
-			expression: null,
-		});
-	}
-
-	if (record.default !== undefined) {
-		resolvedDefaults.set(propertyName, record.default);
-		return literalFn(record.default);
-	}
-
-	return "NULL";
-}
-
-export function renderSnapshotValue(args: {
-	definition: unknown;
-	value: unknown;
-	expression: string | null;
-}): string {
-	const { definition, value, expression } = args;
-	if (expression && expression !== "NULL") {
-		if (
-			definition &&
-			typeof definition === "object" &&
-			isJsonType(definition)
-		) {
-			const trimmed = expression.trim().toLowerCase();
-			if (
-				trimmed.startsWith("json(") ||
-				trimmed.startsWith("json_quote(") ||
-				trimmed.startsWith("json_extract(") ||
-				trimmed.startsWith("json_set(") ||
-				trimmed.startsWith("case")
-			) {
-				return expression;
-			}
-			return `CASE WHEN json_valid(${expression}) THEN json(${expression}) ELSE json_quote(${expression}) END`;
-		}
-		return expression;
-	}
-	if (value === undefined || value === null) {
-		return "NULL";
-	}
-	if (definition && typeof definition === "object" && isJsonType(definition)) {
-		const literalExpr = literal(value);
-		return `CASE WHEN json_valid(${literalExpr}) THEN json(${literalExpr}) ELSE json_quote(${literalExpr}) END`;
-	}
-	if (isExpressionValue(value)) {
-		return value.sql;
-	}
-	return literal(value);
-}
-
-export function resolveSchemaDefinition(
-	storedSchemas: Map<string, unknown>,
-	viewName: string
-): LixSchemaDefinition | null {
-	const candidates = buildSchemaKeyCandidates(viewName);
-
-	for (const candidate of candidates) {
-		const direct = storedSchemas.get(candidate);
-		if (direct && isSchemaDefinition(direct)) {
-			return direct;
-		}
-	}
-
-	const normalizedCandidates = new Set(
-		candidates.map((candidate) => candidate.toLowerCase())
-	);
-
-	for (const [key, value] of storedSchemas) {
-		if (!value) continue;
-		if (!isSchemaDefinition(value)) continue;
-		if (normalizedCandidates.has(key.toLowerCase())) {
-			return value;
-		}
-	}
-
-	const builtin = resolveBuiltinSchemaDefinition(candidates);
-	if (builtin) {
-		return builtin;
-	}
-
-	return null;
-}
-
-function buildSchemaKeyCandidates(viewName: string): string[] {
-	const candidates = new Set<string>();
-	const addCandidate = (value: string | null | undefined) => {
-		if (typeof value === "string" && value.length > 0) {
-			candidates.add(value);
-		}
-	};
-
-	addCandidate(viewName);
-
-	const base = baseSchemaKey(viewName);
-	addCandidate(base);
-
-	const baseValue = base ?? viewName;
-	const lowerBase = baseValue.toLowerCase();
-	if (lowerBase.startsWith("lix_")) {
-		addCandidate(baseValue.slice(4));
-	} else {
-		addCandidate(`lix_${baseValue}`);
-	}
-
-	return Array.from(candidates);
-}
-
-function isSchemaDefinition(value: unknown): value is LixSchemaDefinition {
-	return typeof value === "object" && value !== null;
-}
-
-function resolveBuiltinSchemaDefinition(
-	candidates: readonly string[]
-): LixSchemaDefinition | null {
-	for (const candidate of candidates) {
-		if (!candidate) continue;
-		const normalized = stripLixPrefix(candidate);
-		const direct = LixSchemaViewMap[normalized];
-		if (direct) {
-			return direct;
-		}
-		const lower = normalized.toLowerCase();
-		for (const [key, schema] of Object.entries(LixSchemaViewMap)) {
-			if (key.toLowerCase() === lower) {
-				return schema;
-			}
-		}
-	}
-	return null;
-}
-
-function stripLixPrefix(candidate: string): string {
-	if (!candidate) return candidate;
-	if (candidate.toLowerCase().startsWith("lix_")) {
-		return candidate.slice(4);
-	}
-	return candidate;
-}
-
-function buildPointerAliasInfo(
-	segment: string
-): { alias: string; matchers: readonly string[] } | null {
-	if (!segment) {
-		return null;
-	}
-	const stripped = segment.replace(/^x-lix-/, "");
-	let alias = stripped.replace(/[^A-Za-z0-9_]/g, "_");
-	if (alias.length === 0) {
-		return null;
-	}
-	if (/^[0-9]/.test(alias)) {
-		alias = `_${alias}`;
-	}
-
-	const matchers = new Set<string>();
-	matchers.add(alias);
-	matchers.add(alias.toLowerCase());
-	if (stripped.length > 0) {
-		matchers.add(stripped);
-		matchers.add(stripped.toLowerCase());
-	}
-	matchers.add(segment);
-	matchers.add(segment.toLowerCase());
-	const sanitizedSegment = segment.replace(/[^A-Za-z0-9_]/g, "_");
-	if (sanitizedSegment.length > 0) {
-		matchers.add(sanitizedSegment);
-		matchers.add(sanitizedSegment.toLowerCase());
-	}
-
-	return {
-		alias,
-		matchers: Array.from(matchers),
-	};
-}
-
-export type ResolvedEntityView = {
-	readonly schema: LixSchemaDefinition;
-	readonly variant: Exclude<EntityViewVariant, "history">;
-	readonly storedSchemaKey: string;
-	readonly propertyLowerToActual: Map<string, string>;
-};
-
-export function resolveEntityView(args: {
-	storedSchemas?: Map<string, unknown>;
-	viewName: string | null;
-	rejectImmutable?: boolean;
-}): ResolvedEntityView | null {
-	const { storedSchemas, viewName } = args;
-	if (!storedSchemas || !viewName) {
-		return null;
-	}
-
-	const variant = classifyViewVariant(viewName);
-	if (variant === "history") {
-		return null;
-	}
-
-	const schema = resolveSchemaDefinition(storedSchemas, viewName);
-	if (!schema) {
-		return null;
-	}
-
-	if (!isEntityViewVariantEnabled(schema, variant)) {
-		return null;
-	}
-
-	if (args.rejectImmutable && schema["x-lix-immutable"]) {
-		throw new Error(`Schema ${schema["x-lix-key"] ?? viewName} is immutable`);
-	}
-
-	const storedSchemaKey = resolveStoredSchemaKey(
-		schema,
-		baseSchemaKey(viewName) ?? viewName
-	);
-
-	return {
-		schema,
-		variant,
-		storedSchemaKey,
-		propertyLowerToActual: buildPropertyLookup(schema),
-	};
-}
-
-export type EqualityCondition = {
-	readonly column: string;
-	readonly expression: ExpressionNode;
-};
-
-export function collectEqualityConditions(
-	whereClause: ExpressionNode | RawFragmentNode | null
-): EqualityCondition[] {
-	if (!whereClause) {
-		return [];
-	}
-	if ("sql_text" in whereClause) {
-		return [];
-	}
-
-	const conditions: EqualityCondition[] = [];
-	const visit = (expression: ExpressionNode) => {
-		switch (expression.node_kind) {
-			case "binary_expression":
-				if (expression.operator === "and") {
-					visit(expression.left);
-					visit(expression.right);
-					return;
-				}
-				if (expression.operator === "=") {
-					if (expression.left.node_kind === "column_reference") {
-						const column = getColumnName(expression.left).toLowerCase();
-						conditions.push({ column, expression: expression.right });
-						return;
-					}
-					if (expression.right.node_kind === "column_reference") {
-						const column = getColumnName(expression.right).toLowerCase();
-						conditions.push({ column, expression: expression.left });
-						return;
-					}
-				}
-				break;
-			case "grouped_expression":
-				visit(expression.expression);
-				return;
-			default:
-				return;
-		}
-	};
-
-	visit(whereClause);
-	return conditions;
-}
-
-function buildPrimaryKeyMatcherMap(
-	primaryKeys: PrimaryKeyDescriptor[] | null
-): Map<string, number> {
-	const map = new Map<string, number>();
-	if (!primaryKeys || primaryKeys.length === 0) {
-		return map;
-	}
-	for (let index = 0; index < primaryKeys.length; index++) {
-		const descriptor = primaryKeys[index];
-		if (!descriptor) continue;
-		const allSegments = new Set<string>();
-		allSegments.add(descriptor.column.toLowerCase());
-		allSegments.add(descriptor.rootColumn.toLowerCase());
-		for (const segment of descriptor.path) {
-			allSegments.add(segment.toLowerCase());
-		}
-		const aliasInfo = buildPointerAliasInfo(
-			descriptor.path.at(-1) ?? descriptor.column
-		);
-		if (aliasInfo) {
-			for (const matcher of aliasInfo.matchers) {
-				allSegments.add(matcher.toLowerCase());
-			}
-		}
-		for (const matcher of allSegments) {
-			if (!map.has(matcher)) {
-				map.set(matcher, index);
-			}
-		}
-	}
-	return map;
-}
-
-function serializeEqualityValue(expression: ExpressionNode): string | null {
-	switch (expression.node_kind) {
-		case "parameter": {
-			const position = expression.position ?? -1;
-			if (position >= 0) {
-				return `?${position + 1}`;
-			}
-			const placeholder = expression.placeholder ?? "?";
-			return placeholder === "" ? "?" : placeholder;
-		}
-		case "literal":
-			return expressionToSql(expression);
-		case "raw_fragment":
-			return expression.sql_text;
-		default:
-			return null;
-	}
-}
-
-export function collectPrimaryKeyEqualityExpressions(args: {
-	whereClause: ExpressionNode | RawFragmentNode | null;
-	primaryKeys: PrimaryKeyDescriptor[] | null;
-}): string[] | null {
-	const { whereClause, primaryKeys } = args;
-	if (!primaryKeys || primaryKeys.length === 0) {
-		return null;
-	}
-	const equalityConditions = collectEqualityConditions(whereClause);
-	if (equalityConditions.length === 0) {
-		return null;
-	}
-	const matcherMap = buildPrimaryKeyMatcherMap(primaryKeys);
-	if (matcherMap.size === 0) {
-		return null;
-	}
-	const matched = new Map<number, string>();
-	for (const condition of equalityConditions) {
-		const targetIndex = matcherMap.get(condition.column);
-		if (targetIndex === undefined) {
-			continue;
-		}
-		if (matched.has(targetIndex)) {
-			continue;
-		}
-		const sql = serializeEqualityValue(condition.expression);
-		if (!sql) {
-			return null;
-		}
-		matched.set(targetIndex, sql);
-	}
-	if (matched.size !== primaryKeys.length) {
-		return null;
-	}
-	const ordered = primaryKeys.map((_pk, index) => matched.get(index));
-	if (ordered.some((value) => value === undefined)) {
-		return null;
-	}
-	return ordered as string[];
-}
-
-export function buildEntityIdExpressionFromEquality(
-	parts: readonly string[] | null
-): string | null {
-	if (!parts || parts.length === 0) {
-		return null;
-	}
-	if (parts.some((part) => part.length === 0)) {
-		return null;
-	}
-	if (parts.length === 1) {
-		return parts[0] ?? null;
-	}
-	const wrapped = parts.map((part) => `(${part})`);
-	return `(${wrapped.join(" || '~' || ")})`;
-}
-
-const VIEW_METADATA_COLUMN_MAP: Record<string, string> = {
-	entity_id: "entity_id",
-	lixcol_entity_id: "entity_id",
-	schema_key: "schema_key",
-	lixcol_schema_key: "schema_key",
-	file_id: "file_id",
-	lixcol_file_id: "file_id",
-	plugin_key: "plugin_key",
-	lixcol_plugin_key: "plugin_key",
-	version_id: "version_id",
-	lixcol_version_id: "version_id",
-	metadata: "metadata",
-	lixcol_metadata: "metadata",
-	untracked: "untracked",
-	lixcol_untracked: "untracked",
-};
-
-export type PredicateRewriteResult = {
-	expression: ExpressionNode | null;
-	hasVersionReference: boolean;
-	usesJsonProperty: boolean;
-};
-
-export function rewriteViewWhereClause(
-	whereClause: ExpressionNode | RawFragmentNode | null,
-	options: {
-		propertyLowerToActual: Map<string, string>;
-		stateTableAlias: string;
-		pointerAliasToPath?: Map<string, readonly string[]>;
-		pushdownableJsonProperties?: ReadonlySet<string>;
-		rewriteSubqueryStatement?: (
-			statement: SelectStatementNode | CompoundSelectNode
-		) => SelectStatementNode | CompoundSelectNode;
-	}
-): PredicateRewriteResult | null {
-	if (!whereClause) {
-		return {
-			expression: null,
-			hasVersionReference: false,
-			usesJsonProperty: false,
-		};
-	}
-	if ("sql_text" in whereClause) {
-		return null;
-	}
-
-	const pointerFlags: PredicateRewriteFlags = {
-		hasVersionReference: false,
-		usesJsonProperty: false,
-	};
-	const rewritten = rewritePredicateExpression(
-		whereClause,
-		options.propertyLowerToActual,
-		options.stateTableAlias,
-		pointerFlags,
-		options.pointerAliasToPath,
-		options.pushdownableJsonProperties,
-		options.rewriteSubqueryStatement
-	);
-	if (!rewritten) {
-		return null;
-	}
-
-	return {
-		expression: rewritten,
-		hasVersionReference: pointerFlags.hasVersionReference,
-		usesJsonProperty: pointerFlags.usesJsonProperty,
-	};
-}
-
-type PredicateRewriteFlags = {
-	hasVersionReference: boolean;
-	usesJsonProperty: boolean;
-};
-
-function rewritePredicateExpression(
-	expression: ExpressionNode,
-	propertyLowerToActual: Map<string, string>,
-	stateTableAlias: string,
-	flags: PredicateRewriteFlags,
-	pointerAliasToPath?: Map<string, readonly string[]>,
-	pushdownableJsonProperties?: ReadonlySet<string>,
-	rewriteSubqueryStatement?: (
-		statement: SelectStatementNode | CompoundSelectNode
-	) => SelectStatementNode | CompoundSelectNode
-): ExpressionNode | null {
-	switch (expression.node_kind) {
-		case "binary_expression": {
-			const operator = expression.operator;
-			if (operator === "and" || operator === "or") {
-				const left = rewritePredicateExpression(
-					expression.left,
-					propertyLowerToActual,
-					stateTableAlias,
-					flags,
-					pointerAliasToPath,
-					pushdownableJsonProperties,
-					rewriteSubqueryStatement
-				);
-				if (!left) return null;
-				const right = rewritePredicateExpression(
-					expression.right,
-					propertyLowerToActual,
-					stateTableAlias,
-					flags,
-					pointerAliasToPath,
-					pushdownableJsonProperties,
-					rewriteSubqueryStatement
-				);
-				if (!right) return null;
-				return {
-					node_kind: "binary_expression",
-					left,
-					operator,
-					right,
-				};
-			}
-
-			const supportedOperators = new Set([
-				"=",
-				"!=",
-				"<>",
-				">",
-				">=",
-				"<",
-				"<=",
-				"like",
-				"not_like",
-				"match",
-				"glob",
-				"regexp",
-				"is",
-				"is_not",
-			]);
-			if (!supportedOperators.has(operator)) {
-				return null;
-			}
-
-			const left = rewritePredicateExpression(
-				expression.left,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				pointerAliasToPath,
-				pushdownableJsonProperties,
-				rewriteSubqueryStatement
-			);
-			if (!left) return null;
-			const right = rewritePredicateExpression(
-				expression.right,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				pointerAliasToPath,
-				pushdownableJsonProperties,
-				rewriteSubqueryStatement
-			);
-			if (!right) return null;
-			return {
-				node_kind: "binary_expression",
-				left,
-				operator,
-				right,
-			};
-		}
-		case "unary_expression": {
-			if (expression.operator === "minus" || expression.operator === "not") {
-				const operand = rewritePredicateExpression(
-					expression.operand,
-					propertyLowerToActual,
-					stateTableAlias,
-					flags,
-					pointerAliasToPath,
-					pushdownableJsonProperties,
-					rewriteSubqueryStatement
-				);
-				if (!operand) return null;
-				return {
-					node_kind: "unary_expression",
-					operator: expression.operator,
-					operand,
-				};
-			}
-			return null;
-		}
-		case "grouped_expression": {
-			const rewritten = rewritePredicateExpression(
-				expression.expression,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				pointerAliasToPath,
-				pushdownableJsonProperties,
-				rewriteSubqueryStatement
-			);
-			if (!rewritten) return null;
-			return {
-				node_kind: "grouped_expression",
-				expression: rewritten,
-			};
-		}
-		case "column_reference":
-			return rewriteColumnReference(
-				expression,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				pointerAliasToPath,
-				pushdownableJsonProperties
-			);
-		case "function_call": {
-			const args: FunctionCallArgumentNode[] = [];
-			for (const arg of expression.arguments) {
-				if (arg.node_kind === "all_columns") {
-					args.push(arg);
-					continue;
-				}
-				const rewritten = rewritePredicateExpression(
-					arg,
-					propertyLowerToActual,
-					stateTableAlias,
-					flags,
-					pointerAliasToPath,
-					pushdownableJsonProperties,
-					rewriteSubqueryStatement
-				);
-				if (!rewritten) return null;
-				args.push(rewritten);
-			}
-			const over = rewriteWindowOverForPredicate(
-				expression.over,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				pointerAliasToPath,
-				pushdownableJsonProperties
-			);
-			if (expression.over && !over) {
-				return null;
-			}
-			const call: FunctionCallExpressionNode = {
-				node_kind: "function_call",
-				name: expression.name,
-				arguments: args,
-				over,
-			};
-			return call;
-		}
-		case "in_list_expression": {
-			const operand = rewritePredicateExpression(
-				expression.operand,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				undefined,
-				undefined,
-				rewriteSubqueryStatement
-			);
-			if (!operand) return null;
-			const items: ExpressionNode[] = [];
-			for (const item of expression.items) {
-				const rewritten = rewritePredicateExpression(
-					item,
-					propertyLowerToActual,
-					stateTableAlias,
-					flags,
-					undefined,
-					undefined,
-					rewriteSubqueryStatement
-				);
-				if (!rewritten) return null;
-				items.push(rewritten);
-			}
-			return {
-				node_kind: "in_list_expression",
-				operand,
-				items,
-				negated: expression.negated,
-			};
-		}
-		case "between_expression": {
-			const operand = rewritePredicateExpression(
-				expression.operand,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				undefined,
-				undefined,
-				rewriteSubqueryStatement
-			);
-			if (!operand) return null;
-			const start = rewritePredicateExpression(
-				expression.start,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				undefined,
-				undefined,
-				rewriteSubqueryStatement
-			);
-			if (!start) return null;
-			const end = rewritePredicateExpression(
-				expression.end,
-				propertyLowerToActual,
-				stateTableAlias,
-				flags,
-				undefined,
-				undefined,
-				rewriteSubqueryStatement
-			);
-			if (!end) return null;
-			return {
-				node_kind: "between_expression",
-				operand,
-				start,
-				end,
-				negated: expression.negated,
-			};
-		}
-		case "literal":
-		case "parameter":
-			return expression;
-		case "subquery_expression": {
-			if (!rewriteSubqueryStatement) {
-				return expression;
-			}
-			const statement = rewriteSubqueryStatement(expression.statement);
-			if (statement === expression.statement) {
-				return expression;
-			}
-			return {
-				...expression,
-				statement,
-			};
-		}
-		default:
-			return null;
-	}
-}
-
-function rewriteColumnReference(
-	column: ColumnReferenceNode,
-	propertyLowerToActual: Map<string, string>,
-	stateTableAlias: string,
-	flags: PredicateRewriteFlags,
-	pointerAliasToPath?: Map<string, readonly string[]>,
-	pushdownableJsonProperties?: ReadonlySet<string>
-): ExpressionNode | null {
-	const terminal = column.path[column.path.length - 1];
-	if (!terminal) {
-		return null;
-	}
-	const columnName = terminal.value;
-	const lower = columnName.toLowerCase();
-
-	const pointerPath = pointerAliasToPath?.get(lower);
-	if (pointerPath) {
-		if (pushdownableJsonProperties && pushdownableJsonProperties.has(lower)) {
-			flags.usesJsonProperty = true;
-		}
-		return createJsonExtractExpressionFromPath(pointerPath, stateTableAlias);
-	}
-
-	const property = propertyLowerToActual.get(lower);
-	if (property) {
-		if (pushdownableJsonProperties && pushdownableJsonProperties.has(lower)) {
-			flags.usesJsonProperty = true;
-		}
-		return createJsonExtractExpression(property, stateTableAlias);
-	}
-
-	const metadata = VIEW_METADATA_COLUMN_MAP[lower];
-	if (metadata) {
-		if (metadata === "version_id") {
-			flags.hasVersionReference = true;
-		}
-		return columnReference([stateTableAlias, metadata]);
-	}
-
-	const aliasLower = stateTableAlias.toLowerCase();
-	if (
-		column.path.length === 2 &&
-		column.path[0]?.value.toLowerCase() === aliasLower
-	) {
-		const target = column.path[1]!.value;
-		if (target.toLowerCase() === "version_id") {
-			flags.hasVersionReference = true;
-		}
-		return columnReference([stateTableAlias, target]);
-	}
-
-	return null;
-}
-
-function rewriteWindowOverForPredicate(
-	over: WindowSpecificationNode | WindowReferenceNode | null,
-	propertyLowerToActual: Map<string, string>,
-	stateTableAlias: string,
-	flags: PredicateRewriteFlags,
-	pointerAliasToPath: Map<string, readonly string[]> | undefined,
-	pushdownableJsonProperties?: ReadonlySet<string>
-): WindowSpecificationNode | WindowReferenceNode | null {
-	if (!over) {
-		return null;
-	}
-	if (over.node_kind === "window_reference") {
-		return over;
-	}
-	const specification = rewriteWindowSpecificationForPredicate(
-		over,
-		propertyLowerToActual,
-		stateTableAlias,
-		flags,
-		pointerAliasToPath,
-		pushdownableJsonProperties
-	);
-	return specification;
-}
-
-function rewriteWindowSpecificationForPredicate(
-	spec: WindowSpecificationNode,
-	propertyLowerToActual: Map<string, string>,
-	stateTableAlias: string,
-	flags: PredicateRewriteFlags,
-	pointerAliasToPath: Map<string, readonly string[]> | undefined,
-	pushdownableJsonProperties?: ReadonlySet<string>
-): WindowSpecificationNode | null {
-	const partitionBy: ExpressionNode[] = [];
-	for (const expression of spec.partition_by) {
-		const rewritten = rewritePredicateExpression(
-			expression,
-			propertyLowerToActual,
-			stateTableAlias,
-			flags,
-			pointerAliasToPath,
-			pushdownableJsonProperties
-		);
-		if (!rewritten) {
-			return null;
-		}
-		partitionBy.push(rewritten);
-	}
-
-	const orderBy: OrderByItemNode[] = [];
-	for (const item of spec.order_by) {
-		const rewritten = rewritePredicateExpression(
-			item.expression,
-			propertyLowerToActual,
-			stateTableAlias,
-			flags,
-			pointerAliasToPath,
-			pushdownableJsonProperties
-		);
-		if (!rewritten) {
-			return null;
-		}
-		orderBy.push({
-			...item,
-			expression: rewritten,
-		});
-	}
-
-	let frame: WindowFrameNode | null = null;
-	if (spec.frame) {
-		frame = rewriteWindowFrameForPredicate(
-			spec.frame,
-			propertyLowerToActual,
-			stateTableAlias,
-			flags,
-			pointerAliasToPath,
-			pushdownableJsonProperties
-		);
-		if (!frame) {
-			return null;
-		}
-	}
-
-	return {
-		...spec,
-		partition_by: partitionBy,
-		order_by: orderBy,
-		frame,
-	};
-}
-
-function rewriteWindowFrameForPredicate(
-	frame: WindowFrameNode,
-	propertyLowerToActual: Map<string, string>,
-	stateTableAlias: string,
-	flags: PredicateRewriteFlags,
-	pointerAliasToPath: Map<string, readonly string[]> | undefined,
-	pushdownableJsonProperties?: ReadonlySet<string>
-): WindowFrameNode | null {
-	const start = rewriteWindowFrameBoundForPredicate(
-		frame.start,
-		propertyLowerToActual,
-		stateTableAlias,
-		flags,
-		pointerAliasToPath,
-		pushdownableJsonProperties
-	);
-	if (!start) {
-		return null;
-	}
-	let end: WindowFrameBoundNode | null = null;
-	if (frame.end) {
-		end = rewriteWindowFrameBoundForPredicate(
-			frame.end,
-			propertyLowerToActual,
-			stateTableAlias,
-			flags,
-			pointerAliasToPath,
-			pushdownableJsonProperties
-		);
-		if (!end) {
-			return null;
-		}
-	}
-	return {
-		...frame,
-		start,
-		end,
-	};
-}
-
-function rewriteWindowFrameBoundForPredicate(
-	bound: WindowFrameBoundNode,
-	propertyLowerToActual: Map<string, string>,
-	stateTableAlias: string,
-	flags: PredicateRewriteFlags,
-	pointerAliasToPath: Map<string, readonly string[]> | undefined,
-	pushdownableJsonProperties?: ReadonlySet<string>
-): WindowFrameBoundNode | null {
-	if (!bound.offset) {
-		return bound;
-	}
-	const offset = rewritePredicateExpression(
-		bound.offset,
-		propertyLowerToActual,
-		stateTableAlias,
-		flags,
-		pointerAliasToPath,
-		pushdownableJsonProperties
-	);
-	if (!offset) {
-		return null;
-	}
-	return {
-		...bound,
-		offset,
-	};
-}
-
-function createJsonExtractExpression(
-	property: string,
-	stateTableAlias: string
-): ExpressionNode {
-	const path = buildSqliteJsonPath([property]);
-	return {
-		node_kind: "function_call",
-		name: identifier("json_extract"),
-		arguments: [
-			columnReference([stateTableAlias, "snapshot_content"]),
-			createLiteralNode(path),
-		],
-		over: null,
-	};
-}
-
-function createJsonExtractExpressionFromPath(
-	pathSegments: readonly string[],
-	stateTableAlias: string
-): ExpressionNode {
-	const path = buildSqliteJsonPath(pathSegments);
-	return {
-		node_kind: "function_call",
-		name: identifier("json_extract"),
-		arguments: [
-			columnReference([stateTableAlias, "snapshot_content"]),
-			createLiteralNode(path),
-		],
-		over: null,
-	};
-}
-
-function createLiteralNode(
-	value: string | number | boolean | null
-): LiteralNode {
-	return {
-		node_kind: "literal",
-		value,
-	};
-}
-
-export function combineWithAnd(
-	left: ExpressionNode,
-	right: ExpressionNode
-): ExpressionNode {
-	const normalizedLeft = requiresGrouping(left)
-		? { node_kind: "grouped_expression" as const, expression: left }
-		: left;
-	const normalizedRight = requiresGrouping(right)
-		? { node_kind: "grouped_expression" as const, expression: right }
-		: right;
-	return {
-		node_kind: "binary_expression",
-		left: normalizedLeft,
-		operator: "and",
-		right: normalizedRight,
-	};
-}
-
-function requiresGrouping(expression: ExpressionNode): boolean {
-	if (expression.node_kind !== "binary_expression") {
-		return false;
-	}
-	return expression.operator === "or";
-}