@askdb/core 1.0.0-beta.41 → 1.0.0-beta.42

package/dist/logging/log-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"log-events.js","sourceRoot":"","sources":["../../src/logging/log-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,iBAAiB;IAC3B,MAAM,EAAE,eAAe;IACvB,QAAQ,EAAE,iBAAiB;IAC3B,kFAAkF;IAClF,YAAY,EAAE,qBAAqB;IACnC,qBAAqB,EAAE,+BAA+B;IACtD,wBAAwB,EAAE,kCAAkC;IAC5D,yFAAyF;IACzF,uBAAuB,EAAE,iCAAiC;IAC1D,4GAA4G;IAC5G,gCAAgC,EAAE,2CAA2C;IAC7E,yEAAyE;IACzE,cAAc,EAAE,uBAAuB;IACvC;;;OAGG;IACH,qBAAqB,EAAE,+BAA+B;IACtD;;;;OAIG;IACH,wBAAwB,EAAE,kCAAkC;IAC5D,mFAAmF;IACnF,oBAAoB,EAAE,8BAA8B;IACpD,yDAAyD;IACzD,mBAAmB,EAAE,6BAA6B;IAClD,yCAAyC;IACzC,qBAAqB,EAAE,+BAA+B;IACtD,iFAAiF;IACjF,qBAAqB,EAAE,+BAA+B;CAC9C,CAAC"}
+{"version":3,"file":"log-events.js","sourceRoot":"","sources":["../../src/logging/log-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,iBAAiB;IAC3B,MAAM,EAAE,eAAe;IACvB,QAAQ,EAAE,iBAAiB;IAC3B,kFAAkF;IAClF,YAAY,EAAE,qBAAqB;IACnC,qBAAqB,EAAE,+BAA+B;IACtD,wBAAwB,EAAE,kCAAkC;IAC5D,yFAAyF;IACzF,uBAAuB,EAAE,iCAAiC;IAC1D,4GAA4G;IAC5G,gCAAgC,EAAE,2CAA2C;IAC7E,yEAAyE;IACzE,cAAc,EAAE,uBAAuB;IACvC;;;OAGG;IACH,qBAAqB,EAAE,+BAA+B;IACtD;;;;OAIG;IACH,wBAAwB,EAAE,kCAAkC;IAC5D,mFAAmF;IACnF,oBAAoB,EAAE,8BAA8B;IACpD,yDAAyD;IACzD,mBAAmB,EAAE,6BAA6B;IAClD;;;;;OAKG;IACH,2BAA2B,EAAE,sCAAsC;IACnE,yCAAyC;IACzC,qBAAqB,EAAE,+BAA+B;IACtD,iFAAiF;IACjF,qBAAqB,EAAE,+BAA+B;IACtD;;;;OAIG;IACH,qBAAqB,EAAE,8BAA8B;CAC7C,CAAC"}

package/dist/sql/bind.d.ts

@@ -0,0 +1,100 @@
+import { type BuiltInDialectId, type DialectSpec } from "./dialect-spec.js";
+export type QueryParameterType = "string" | "number" | "boolean" | "date" | "datetime";
+export type QueryParameterValue = string | number | boolean;
+/** One slot in `BoundQuery.params` — a scalar, or an array for Postgres/CockroachDB listBinding. */
+export type QueryParamSlot = QueryParameterValue | QueryParameterValue[];
+/** One parameter as bound for this call — enough to render a form field. */
+export type QueryParameterBinding = {
+    name: string;
+    placeholder: string;
+    type: QueryParameterType;
+    cardinality: "one" | "many";
+    description?: string;
+    value: QueryParameterValue | QueryParameterValue[];
+    /** Driver markers this parameter fills in `unboundSql`, in order. */
+    markers: string[];
+    /** 0-based indices into `params` this parameter occupies, in order. */
+    indices: number[];
+    source: "question" | "tenant";
+};
+/** Serializable input to bindPreparedQuery(). Definitions and template only — no values. */
+export type PreparedQuery = {
+    version: 1;
+    dialect: BuiltInDialectId;
+    /** SQL with unquoted `:name` / `:tenant_*` placeholders intact. */
+    namedSql: string;
+    parameters: Array<{
+        name: string;
+        placeholder: string;
+        type: QueryParameterType;
+        cardinality: "one" | "many";
+        description?: string;
+        source: "question" | "tenant";
+    }>;
+};
+export type BoundQuery = {
+    /** Ready to run as-is — every placeholder replaced with an escaped literal. */
+    sql: string;
+    /** Same statement with driver markers instead of literals. */
+    unboundSql: string;
+    params: QueryParamSlot[];
+    bindings: QueryParameterBinding[];
+};
+export type SqlSpanKind = "code" | "quoted";
+export type SqlSpan = {
+    kind: SqlSpanKind;
+    start: number;
+    end: number;
+};
+/**
+ * Tokenize SQL into contiguous code vs quoted regions.
+ * Recognizes single-quoted strings (doubled-quote escapes), double-quoted
+ * identifiers, PostgreSQL dollar-quoting, MySQL backticks, and SQL Server brackets.
+ */
+export declare function tokenizeSqlSpans(sql: string): SqlSpan[];
+/**
+ * Strip quoted regions for keyword / multi-statement checks.
+ * Preserves historical replacement markers for quotes the old stripper knew
+ * about (`''`, `""`, `$$`); new quote forms (backticks, brackets) become spaces.
+ */
+export declare function stripSqlStringLiterals(sql: string): string;
+export type PlaceholderOccurrence = {
+    /** Name without the leading colon, e.g. "state_name" or "tenant_agency_ids". */
+    name: string;
+    /** Full token including colon, e.g. ":state_name". */
+    placeholder: string;
+    start: number;
+    end: number;
+};
+/**
+ * Find `:name` placeholders only outside quoted regions, in source order.
+ * A quoted `':name'` is invisible by construction.
+ */
+export declare function scanPlaceholders(sql: string): PlaceholderOccurrence[];
+export declare function scanTenantPlaceholders(sql: string): PlaceholderOccurrence[];
+/**
+ * A `many` placeholder must be the sole expression inside `IN (...)` / `NOT IN (...)`,
+ * or the sole argument of `= ANY(...)` on array dialects.
+ */
+export declare function isValidListContext(sql: string, occurrence: PlaceholderOccurrence, listBinding: "array" | "expand"): boolean;
+/**
+ * Escape a scalar value as a SQL literal for the given dialect.
+ * Never includes the raw parameter value in thrown error messages.
+ */
+export declare function escapeSqlLiteral(value: QueryParameterValue, dialect: Pick<DialectSpec, "backslashEscapes"> | undefined): string;
+export declare function escapeSqlLiteralList(values: readonly QueryParameterValue[], dialect: Pick<DialectSpec, "backslashEscapes"> | undefined): string;
+/** Quote-doubling only — used when no dialect is supplied (legacy tenant path). */
+export declare function escapeSqlLiteralLegacy(value: string): string;
+export type MarkerStyle = "dollar" | "question" | "atp";
+export declare function markerStyleForDialect(id: BuiltInDialectId): MarkerStyle;
+export declare function formatMarker(style: MarkerStyle, ordinal: number): string;
+/**
+ * Pure, synchronous binder. Substitutes placeholders with escaped literals and
+ * allocates dialect-correct driver markers. Does not authorize tenant IDs.
+ */
+export declare function bindPreparedQuery(prepared: PreparedQuery, values: Record<string, QueryParameterValue | readonly QueryParameterValue[]>): BoundQuery;
+/**
+ * Compare two SQL strings structurally for the parameterize consistency check.
+ */
+export declare function sqlStructurallyEqual(a: string, b: string): boolean;
+//# sourceMappingURL=bind.d.ts.map

package/dist/sql/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../src/sql/bind.ts"],"names":[],"mappings":"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"}

package/dist/sql/bind.js

@@ -0,0 +1,560 @@
+import { QueryParameterError, } from "../errors.js";
+import { BUILT_IN_DIALECTS, } from "./dialect-spec.js";
+import { validateSelectSql } from "./validate.js";
+/**
+ * Tokenize SQL into contiguous code vs quoted regions.
+ * Recognizes single-quoted strings (doubled-quote escapes), double-quoted
+ * identifiers, PostgreSQL dollar-quoting, MySQL backticks, and SQL Server brackets.
+ */
+export function tokenizeSqlSpans(sql) {
+    const spans = [];
+    let i = 0;
+    let codeStart = 0;
+    const pushCode = (end) => {
+        if (end > codeStart)
+            spans.push({ kind: "code", start: codeStart, end });
+    };
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch === "'") {
+            pushCode(i);
+            const start = i;
+            i++;
+            while (i < sql.length) {
+                if (sql[i] === "'" && sql[i + 1] === "'") {
+                    i += 2;
+                    continue;
+                }
+                if (sql[i] === "'") {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            spans.push({ kind: "quoted", start, end: i });
+            codeStart = i;
+            continue;
+        }
+        if (ch === '"') {
+            pushCode(i);
+            const start = i;
+            i++;
+            while (i < sql.length && sql[i] !== '"') {
+                if (sql[i] === "\\")
+                    i++;
+                i++;
+            }
+            if (i < sql.length)
+                i++;
+            spans.push({ kind: "quoted", start, end: i });
+            codeStart = i;
+            continue;
+        }
+        if (ch === "`") {
+            pushCode(i);
+            const start = i;
+            i++;
+            while (i < sql.length && sql[i] !== "`") {
+                if (sql[i] === "\\")
+                    i++;
+                i++;
+            }
+            if (i < sql.length)
+                i++;
+            spans.push({ kind: "quoted", start, end: i });
+            codeStart = i;
+            continue;
+        }
+        if (ch === "[") {
+            pushCode(i);
+            const start = i;
+            i++;
+            while (i < sql.length && sql[i] !== "]") {
+                i++;
+            }
+            if (i < sql.length)
+                i++;
+            spans.push({ kind: "quoted", start, end: i });
+            codeStart = i;
+            continue;
+        }
+        // Dollar-quoting: $tag$ … $tag$. Do not treat $1 as a dollar quote.
+        if (ch === "$" && /^\$\w*\$/.test(sql.slice(i))) {
+            const tagMatch = /^\$(\w*)\$/.exec(sql.slice(i));
+            const opener = tagMatch[0];
+            const closerAt = sql.indexOf(opener, i + opener.length);
+            if (closerAt === -1) {
+                // Unterminated — treat remainder as code (matches prior fail-open).
+                break;
+            }
+            pushCode(i);
+            const end = closerAt + opener.length;
+            spans.push({ kind: "quoted", start: i, end });
+            i = end;
+            codeStart = i;
+            continue;
+        }
+        i++;
+    }
+    pushCode(sql.length);
+    return spans;
+}
+/**
+ * Strip quoted regions for keyword / multi-statement checks.
+ * Preserves historical replacement markers for quotes the old stripper knew
+ * about (`''`, `""`, `$$`); new quote forms (backticks, brackets) become spaces.
+ */
+export function stripSqlStringLiterals(sql) {
+    // Walk with the same control flow as the historical stripper for ', ", and $$,
+    // then additionally skip backticks and brackets — producing equivalent output
+    // for previously-supported forms.
+    let out = "";
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch === "'") {
+            i++;
+            while (i < sql.length) {
+                if (sql[i] === "'" && sql[i + 1] === "'") {
+                    i += 2;
+                    continue;
+                }
+                if (sql[i] === "'") {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            out += "''";
+            continue;
+        }
+        if (ch === '"') {
+            i++;
+            while (i < sql.length && sql[i] !== '"') {
+                if (sql[i] === "\\")
+                    i++;
+                i++;
+            }
+            if (i < sql.length)
+                i++;
+            out += '""';
+            continue;
+        }
+        if (ch === "`") {
+            i++;
+            while (i < sql.length && sql[i] !== "`") {
+                if (sql[i] === "\\")
+                    i++;
+                i++;
+            }
+            if (i < sql.length)
+                i++;
+            out += "``";
+            continue;
+        }
+        if (ch === "[") {
+            i++;
+            while (i < sql.length && sql[i] !== "]") {
+                i++;
+            }
+            if (i < sql.length)
+                i++;
+            out += "[]";
+            continue;
+        }
+        if (ch === "$" && /^\$\w*\$/.test(sql.slice(i))) {
+            // Match historical indexOf-based closer scan for observable parity.
+            const end = sql.indexOf("$", i + 1);
+            const tagEnd = sql.indexOf("$", end + 1);
+            if (tagEnd === -1)
+                return out + sql.slice(i);
+            i = tagEnd + 1;
+            out += "$$";
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+const PLACEHOLDER_TOKEN_RE = /:([a-z][a-z0-9_]*)/g;
+/**
+ * Find `:name` placeholders only outside quoted regions, in source order.
+ * A quoted `':name'` is invisible by construction.
+ */
+export function scanPlaceholders(sql) {
+    const spans = tokenizeSqlSpans(sql);
+    const out = [];
+    for (const span of spans) {
+        if (span.kind !== "code")
+            continue;
+        const segment = sql.slice(span.start, span.end);
+        PLACEHOLDER_TOKEN_RE.lastIndex = 0;
+        let m;
+        while ((m = PLACEHOLDER_TOKEN_RE.exec(segment)) !== null) {
+            const name = m[1];
+            const start = span.start + m.index;
+            const end = start + m[0].length;
+            out.push({ name, placeholder: m[0], start, end });
+        }
+    }
+    return out;
+}
+export function scanTenantPlaceholders(sql) {
+    return scanPlaceholders(sql).filter((p) => /^tenant_[a-z0-9_]+_ids$/.test(p.name));
+}
+// ---------------------------------------------------------------------------
+// List-context validation
+// ---------------------------------------------------------------------------
+/**
+ * A `many` placeholder must be the sole expression inside `IN (...)` / `NOT IN (...)`,
+ * or the sole argument of `= ANY(...)` on array dialects.
+ */
+export function isValidListContext(sql, occurrence, listBinding) {
+    const before = sql.slice(0, occurrence.start);
+    const after = sql.slice(occurrence.end);
+    const inBefore = /(?:NOT\s+)?IN\s*\(\s*$/i.exec(before);
+    if (inBefore) {
+        return /^\s*\)/.test(after);
+    }
+    if (listBinding === "array") {
+        const anyBefore = /=\s*ANY\s*\(\s*$/i.exec(before);
+        if (anyBefore) {
+            return /^\s*\)/.test(after);
+        }
+    }
+    return false;
+}
+/** Detect whether an occurrence sits inside IN ( … ) and return the span of `IN (` … `)`. */
+function inListSpan(sql, occ) {
+    const before = sql.slice(0, occ.start);
+    const after = sql.slice(occ.end);
+    const inBefore = /(?:NOT\s+)?IN\s*\(\s*$/i.exec(before);
+    if (!inBefore || !/^\s*\)/.test(after))
+        return undefined;
+    const closeMatch = /^\s*\)/.exec(after);
+    return {
+        start: occ.start - inBefore[0].length,
+        end: occ.end + closeMatch[0].length,
+        isNot: /^NOT\s+/i.test(inBefore[0]),
+    };
+}
+function anySpan(sql, occ) {
+    const before = sql.slice(0, occ.start);
+    const after = sql.slice(occ.end);
+    const anyBefore = /=\s*ANY\s*\(\s*$/i.exec(before);
+    if (!anyBefore || !/^\s*\)/.test(after))
+        return undefined;
+    const closeMatch = /^\s*\)/.exec(after);
+    return {
+        start: occ.start - anyBefore[0].length,
+        end: occ.end + closeMatch[0].length,
+    };
+}
+// ---------------------------------------------------------------------------
+// Dialect-aware literal escaping
+// ---------------------------------------------------------------------------
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+/**
+ * Escape a scalar value as a SQL literal for the given dialect.
+ * Never includes the raw parameter value in thrown error messages.
+ */
+export function escapeSqlLiteral(value, dialect) {
+    if (typeof value === "boolean") {
+        return value ? "TRUE" : "FALSE";
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw paramError("INVALID_VALUE", "Numeric parameter must be a finite number.");
+        }
+        return String(value);
+    }
+    if (CONTROL_CHAR_RE.test(value)) {
+        throw paramError("INVALID_VALUE", "String parameter contains a disallowed control character.");
+    }
+    let escaped = value.replace(/'/g, "''");
+    if (dialect?.backslashEscapes === true) {
+        escaped = escaped.replace(/\\/g, "\\\\");
+    }
+    return `'${escaped}'`;
+}
+export function escapeSqlLiteralList(values, dialect) {
+    return `(${values.map((v) => escapeSqlLiteral(v, dialect)).join(", ")})`;
+}
+/** Quote-doubling only — used when no dialect is supplied (legacy tenant path). */
+export function escapeSqlLiteralLegacy(value) {
+    return "'" + value.replace(/'/g, "''") + "'";
+}
+export function markerStyleForDialect(id) {
+    switch (id) {
+        case "postgres":
+        case "cockroachdb":
+            return "dollar";
+        case "sqlserver":
+            return "atp";
+        case "mysql":
+        case "mariadb":
+        case "sqlite":
+            return "question";
+    }
+}
+export function formatMarker(style, ordinal) {
+    switch (style) {
+        case "dollar":
+            return `$${ordinal}`;
+        case "question":
+            return "?";
+        case "atp":
+            return `@p${ordinal}`;
+    }
+}
+function listBindingOf(spec) {
+    return spec.listBinding ?? "expand";
+}
+function nextMarker(style, counters) {
+    switch (style) {
+        case "dollar":
+            return formatMarker("dollar", counters.dollar++);
+        case "atp":
+            return formatMarker("atp", counters.atp++);
+        case "question":
+            return formatMarker("question", 0);
+    }
+}
+// ---------------------------------------------------------------------------
+// bindPreparedQuery
+// ---------------------------------------------------------------------------
+function paramError(reason, message) {
+    return new QueryParameterError(message, reason);
+}
+function lookupValue(values, name, placeholder) {
+    if (Object.prototype.hasOwnProperty.call(values, placeholder)) {
+        return values[placeholder];
+    }
+    if (Object.prototype.hasOwnProperty.call(values, name)) {
+        return values[name];
+    }
+    return undefined;
+}
+function assertValueMatchesDeclaration(value, type, cardinality) {
+    if (cardinality === "many") {
+        if (!Array.isArray(value)) {
+            throw paramError("INVALID_VALUE", "List parameter requires a non-empty array value.");
+        }
+        if (value.length === 0) {
+            throw paramError("INVALID_VALUE", "List parameter requires a non-empty array value.");
+        }
+        return value.map((v) => assertScalar(v, type));
+    }
+    if (Array.isArray(value)) {
+        throw paramError("INVALID_VALUE", "Scalar parameter must not be an array.");
+    }
+    return assertScalar(value, type);
+}
+function assertScalar(value, type) {
+    if (value === null || value === undefined) {
+        throw paramError("INVALID_VALUE", "Parameter value must not be null or undefined.");
+    }
+    if (typeof value === "object") {
+        throw paramError("INVALID_VALUE", "Parameter value must be a string, number, or boolean.");
+    }
+    switch (type) {
+        case "string":
+        case "date":
+        case "datetime":
+            if (typeof value !== "string") {
+                throw paramError("INVALID_VALUE", `Parameter of type ${type} requires a string value.`);
+            }
+            if (type === "date" && !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+                throw paramError("INVALID_VALUE", "Date parameter must be an ISO date string (YYYY-MM-DD).");
+            }
+            if (type === "datetime" &&
+                !/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/.test(value)) {
+                throw paramError("INVALID_VALUE", "Datetime parameter must be an ISO datetime string.");
+            }
+            return value;
+        case "number":
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                throw paramError("INVALID_VALUE", "Numeric parameter must be a finite number.");
+            }
+            return value;
+        case "boolean":
+            if (typeof value !== "boolean") {
+                throw paramError("INVALID_VALUE", "Boolean parameter requires a boolean value.");
+            }
+            return value;
+    }
+}
+/**
+ * Pure, synchronous binder. Substitutes placeholders with escaped literals and
+ * allocates dialect-correct driver markers. Does not authorize tenant IDs.
+ */
+export function bindPreparedQuery(prepared, values) {
+    const spec = BUILT_IN_DIALECTS[prepared.dialect];
+    if (!spec) {
+        throw paramError("DIALECT_UNSUPPORTED", `Unknown dialect '${prepared.dialect}'.`);
+    }
+    const listBinding = listBindingOf(spec);
+    const style = markerStyleForDialect(prepared.dialect);
+    const namedSql = prepared.namedSql;
+    const occurrences = scanPlaceholders(namedSql);
+    const declByName = new Map(prepared.parameters.map((p) => [p.name, p]));
+    for (const p of prepared.parameters) {
+        if (!occurrences.some((o) => o.name === p.name)) {
+            throw paramError("UNRESOLVED_PLACEHOLDER", `Declared parameter '${p.name}' does not appear in namedSql.`);
+        }
+    }
+    for (const occ of occurrences) {
+        if (!declByName.has(occ.name)) {
+            throw paramError("UNRESOLVED_PLACEHOLDER", `Placeholder '${occ.placeholder}' has no matching parameter declaration.`);
+        }
+    }
+    const resolvedValues = new Map();
+    for (const p of prepared.parameters) {
+        const raw = lookupValue(values, p.name, p.placeholder);
+        if (raw === undefined) {
+            throw paramError("MISSING_VALUE", `Missing value for parameter '${p.name}'.`);
+        }
+        resolvedValues.set(p.name, assertValueMatchesDeclaration(raw, p.type, p.cardinality));
+    }
+    for (const occ of occurrences) {
+        const decl = declByName.get(occ.name);
+        if (decl.cardinality === "many" && !isValidListContext(namedSql, occ, listBinding)) {
+            throw paramError("INVALID_LIST_CONTEXT", `List parameter '${occ.name}' must appear as the sole expression inside IN (...)` +
+                (listBinding === "array" ? " or = ANY(...)" : "") +
+                ".");
+        }
+    }
+    const edits = [];
+    const params = [];
+    const bindings = [];
+    const bindingByName = new Map();
+    const counters = { dollar: 1, atp: 0 };
+    const ensureBinding = (decl, value) => {
+        let binding = bindingByName.get(decl.name);
+        if (!binding) {
+            binding = {
+                name: decl.name,
+                placeholder: decl.placeholder,
+                type: decl.type,
+                cardinality: decl.cardinality,
+                description: decl.description,
+                value,
+                markers: [],
+                indices: [],
+                source: decl.source,
+            };
+            bindingByName.set(decl.name, binding);
+            bindings.push(binding);
+        }
+        return binding;
+    };
+    for (const occ of occurrences) {
+        const decl = declByName.get(occ.name);
+        const value = resolvedValues.get(occ.name);
+        if (decl.cardinality === "many") {
+            const list = value;
+            const listLiteral = escapeSqlLiteralList(list, spec);
+            const binding = ensureBinding(decl, value);
+            if (listBinding === "array") {
+                // One array-typed driver param. unboundSql uses = ANY($n); bound sql uses IN (...).
+                const marker = nextMarker(style, counters);
+                const indices = [params.length];
+                params.push(list);
+                binding.markers.push(marker);
+                binding.indices.push(...indices);
+                const inSp = inListSpan(namedSql, occ);
+                const anySp = anySpan(namedSql, occ);
+                if (inSp) {
+                    edits.push({
+                        start: inSp.start,
+                        end: inSp.end,
+                        literal: `${inSp.isNot ? "NOT " : ""}IN ${listLiteral}`,
+                        marker: inSp.isNot ? `<> ALL(${marker})` : `= ANY(${marker})`,
+                    });
+                }
+                else if (anySp) {
+                    edits.push({
+                        start: anySp.start,
+                        end: anySp.end,
+                        literal: `IN ${listLiteral}`,
+                        marker: `= ANY(${marker})`,
+                    });
+                }
+                else {
+                    // Validated above; defensive.
+                    edits.push({
+                        start: occ.start,
+                        end: occ.end,
+                        literal: listLiteral,
+                        marker,
+                    });
+                }
+            }
+            else {
+                // expand: one marker / literal element per value
+                const markerTexts = [];
+                for (const item of list) {
+                    const marker = nextMarker(style, counters);
+                    markerTexts.push(marker);
+                    binding.indices.push(params.length);
+                    binding.markers.push(marker);
+                    params.push(item);
+                }
+                const inSp = inListSpan(namedSql, occ);
+                if (inSp) {
+                    // Replace only the placeholder — outer IN ( ) stays; emit bare list.
+                    edits.push({
+                        start: occ.start,
+                        end: occ.end,
+                        literal: list.map((v) => escapeSqlLiteral(v, spec)).join(", "),
+                        marker: markerTexts.join(", "),
+                    });
+                }
+                else {
+                    edits.push({
+                        start: occ.start,
+                        end: occ.end,
+                        literal: listLiteral,
+                        marker: `(${markerTexts.join(", ")})`,
+                    });
+                }
+            }
+        }
+        else {
+            const scalar = value;
+            const literal = escapeSqlLiteral(scalar, spec);
+            const marker = nextMarker(style, counters);
+            const binding = ensureBinding(decl, value);
+            binding.markers.push(marker);
+            binding.indices.push(params.length);
+            params.push(scalar);
+            edits.push({ start: occ.start, end: occ.end, literal, marker });
+        }
+    }
+    edits.sort((a, b) => b.start - a.start);
+    let sql = namedSql;
+    let unboundSql = namedSql;
+    for (const edit of edits) {
+        sql = sql.slice(0, edit.start) + edit.literal + sql.slice(edit.end);
+        unboundSql = unboundSql.slice(0, edit.start) + edit.marker + unboundSql.slice(edit.end);
+    }
+    if (scanPlaceholders(sql).length > 0 || scanPlaceholders(unboundSql).length > 0) {
+        throw paramError("UNRESOLVED_PLACEHOLDER", "One or more placeholders remain after binding.");
+    }
+    validateSelectSql(spec, sql);
+    validateSelectSql(spec, unboundSql);
+    return { sql, unboundSql, params, bindings };
+}
+/**
+ * Compare two SQL strings structurally for the parameterize consistency check.
+ */
+export function sqlStructurallyEqual(a, b) {
+    const norm = (s) => s
+        .trim()
+        .replace(/;\s*$/, "")
+        .replace(/\s+/g, " ")
+        .toLowerCase();
+    return norm(a) === norm(b);
+}
+//# sourceMappingURL=bind.js.map