@quereus/quereus 4.19.4 → 4.20.0

package/dist/src/core/param.d.ts

@@ -1,5 +1,5 @@
 import type { ScalarType } from '../common/datatype.js';
-import { type SqlParameters } from '../common/types.js';
+import { type SqlParameters, type SqlValue } from '../common/types.js';
 /**
  * Generate type hints for parameters based on their JavaScript values.
  * This is used during planning to assign strong types to parameters.
@@ -17,6 +17,51 @@ import { type SqlParameters } from '../common/types.js';
  * @returns Map of parameter keys to their inferred ScalarTypes
  */
 export declare function getParameterTypes(params: SqlParameters | undefined): Map<string | number, ScalarType> | undefined;
+/**
+ * The parameter a bound-args entry names. A caller may spell a named parameter
+ * `:name`, `$name` or the bare `name` — the parser accepts `:` and `$` as
+ * interchangeable prefixes and keeps only the bare lexeme — and a positional slot
+ * `1`, `'1'`, `':1'` or `':01'`. All of those name one parameter, and this is the
+ * single function that says so.
+ *
+ * `@` is deliberately NOT stripped: the lexer has no `@` token, so `@p` can never
+ * appear in Quereus SQL and normalizing it would promise a binding for a parameter
+ * no statement can reference.
+ */
+export declare function boundKeyToParamKey(key: string): string | number;
+/**
+ * Canonicalizes a caller-supplied parameter object/array into the bound-args record
+ * every downstream reader agrees on: one key per parameter ({@link boundKeyToParamKey}),
+ * one canonical JS form per value ({@link canonicalizeSqlValue}).
+ *
+ * This is the ONLY place a bound key is decided. Normalizing at ingress is what makes
+ * "which spelling names this parameter?" unanswerable-by-divergence downstream: the
+ * runtime value lookup, the parameter type map, bind-time validation and change-scope
+ * substitution all read the same key because only one was ever written.
+ *
+ * Two spellings of one parameter in a single object (`{ p: 1, ':p': 2 }`) is a
+ * {@link MisuseError}, not a silent pick: either entry could be the one the caller
+ * meant, and discarding a value they passed is worse than refusing it. The rule is
+ * per-object — repeated `Statement.bind()` calls to one parameter stay last-wins,
+ * since each call is a separate statement of intent.
+ *
+ * Throws before returning anything, so a caller assigning the result keeps `bindAll`'s
+ * all-or-nothing contract for free.
+ *
+ * @param label the caller-facing operation name, used to prefix rejection messages
+ */
+export declare function normalizeBoundParams(params: SqlParameters | SqlValue[], label: string): Record<string | number, SqlValue>;
+/**
+ * An empty bound-args record, and the only shape one should ever start from.
+ *
+ * Null-prototype on purpose: bound args are looked up BY NAME with keys that come
+ * from user SQL, so a plain `{}` answers `:toString`, `:constructor`, `:valueOf`
+ * and friends with an inherited function instead of reporting the parameter
+ * unbound — `select :toString` returned a JS function as a SQL value rather than
+ * raising. Dropping the prototype makes that whole class unrepresentable at the
+ * source instead of asking every reader to remember `Object.hasOwn`.
+ */
+export declare function emptyBoundParams(): Record<string | number, SqlValue>;
 /**
  * Normalizes a parameter name to a number when it is an all-digits index,
  * matching how positional params are keyed elsewhere (array index + 1,

package/dist/src/core/param.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"param.d.ts","sourceRoot":"","sources":["../../../src/core/param.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,oBAAoB,CAAC;AAGvE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,CAuBjH;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAK/D"}
+{"version":3,"file":"param.d.ts","sourceRoot":"","sources":["../../../src/core/param.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAyC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAK9G;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,CAsBjH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAClC,KAAK,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,CAuBnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,CAEpE;AAQD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAK/D"}

package/dist/src/core/param.js

@@ -1,4 +1,7 @@
+import { describeSqlValueViolation, isSqlValue } from '../common/types.js';
 import { inferLogicalTypeFromValue } from '../common/type-inference.js';
+import { MisuseError } from '../common/errors.js';
+import { canonicalizeSqlValue } from '../util/numeric-canonical.js';
 /**
  * Generate type hints for parameters based on their JavaScript values.
  * This is used during planning to assign strong types to parameters.
@@ -28,18 +31,95 @@ export function getParameterTypes(params) {
         }
         else {
             Object.entries(params).forEach(([key, value]) => {
-                // For named params like ':name', ParameterScope expects 'name' as key for hints.
-                // A positional param bound after prepare (bind/bindAll) lands here too, keyed
-                // by its stringified index (`boundArgs[index + 1]`) — normalize it back to a
-                // number so it lines up with the array branch above and with ParameterScope's
-                // own key, rather than silently missing the hint lookup.
-                const name = key.startsWith(':') ? key.substring(1) : key;
-                results.set(normalizeParamKey(name), getParameterScalarType(value));
+                // ParameterScope keys hints by the bare name, or by the 1-based index for a
+                // positional slot — which arrives here stringified (`boundArgs[index + 1]`)
+                // and has to become a number again or the hint lookup silently misses.
+                // Bound args are already normalized and boundKeyToParamKey is idempotent on
+                // them; running it anyway keeps this correct for a caller passing a raw object.
+                results.set(boundKeyToParamKey(key), getParameterScalarType(value));
             });
         }
     }
     return results;
 }
+/**
+ * The parameter a bound-args entry names. A caller may spell a named parameter
+ * `:name`, `$name` or the bare `name` — the parser accepts `:` and `$` as
+ * interchangeable prefixes and keeps only the bare lexeme — and a positional slot
+ * `1`, `'1'`, `':1'` or `':01'`. All of those name one parameter, and this is the
+ * single function that says so.
+ *
+ * `@` is deliberately NOT stripped: the lexer has no `@` token, so `@p` can never
+ * appear in Quereus SQL and normalizing it would promise a binding for a parameter
+ * no statement can reference.
+ */
+export function boundKeyToParamKey(key) {
+    const bare = key.startsWith(':') || key.startsWith('$') ? key.substring(1) : key;
+    return normalizeParamKey(bare);
+}
+/**
+ * Canonicalizes a caller-supplied parameter object/array into the bound-args record
+ * every downstream reader agrees on: one key per parameter ({@link boundKeyToParamKey}),
+ * one canonical JS form per value ({@link canonicalizeSqlValue}).
+ *
+ * This is the ONLY place a bound key is decided. Normalizing at ingress is what makes
+ * "which spelling names this parameter?" unanswerable-by-divergence downstream: the
+ * runtime value lookup, the parameter type map, bind-time validation and change-scope
+ * substitution all read the same key because only one was ever written.
+ *
+ * Two spellings of one parameter in a single object (`{ p: 1, ':p': 2 }`) is a
+ * {@link MisuseError}, not a silent pick: either entry could be the one the caller
+ * meant, and discarding a value they passed is worse than refusing it. The rule is
+ * per-object — repeated `Statement.bind()` calls to one parameter stay last-wins,
+ * since each call is a separate statement of intent.
+ *
+ * Throws before returning anything, so a caller assigning the result keeps `bindAll`'s
+ * all-or-nothing contract for free.
+ *
+ * @param label the caller-facing operation name, used to prefix rejection messages
+ */
+export function normalizeBoundParams(params, label) {
+    const out = emptyBoundParams();
+    if (Array.isArray(params)) {
+        params.forEach((value, index) => {
+            assertSqlValue(value, `${label}: invalid value at index ${index}`);
+            out[index + 1] = canonicalizeSqlValue(value);
+        });
+        return out;
+    }
+    // Rejection messages name the CALLER's spelling, so validate while iterating the
+    // original entries rather than the normalized record.
+    const spellingOf = new Map();
+    for (const [key, value] of Object.entries(params)) {
+        assertSqlValue(value, `${label}: invalid value for key '${key}'`);
+        const paramKey = boundKeyToParamKey(key);
+        const previous = spellingOf.get(paramKey);
+        if (previous !== undefined) {
+            throw new MisuseError(`${label}: parameter '${paramKey}' bound twice, as '${previous}' and '${key}'`);
+        }
+        spellingOf.set(paramKey, key);
+        out[paramKey] = canonicalizeSqlValue(value);
+    }
+    return out;
+}
+/**
+ * An empty bound-args record, and the only shape one should ever start from.
+ *
+ * Null-prototype on purpose: bound args are looked up BY NAME with keys that come
+ * from user SQL, so a plain `{}` answers `:toString`, `:constructor`, `:valueOf`
+ * and friends with an inherited function instead of reporting the parameter
+ * unbound — `select :toString` returned a JS function as a SQL value rather than
+ * raising. Dropping the prototype makes that whole class unrepresentable at the
+ * source instead of asking every reader to remember `Object.hasOwn`.
+ */
+export function emptyBoundParams() {
+    return Object.create(null);
+}
+function assertSqlValue(value, context) {
+    if (!isSqlValue(value)) {
+        throw new MisuseError(`${context}: expected SqlValue, got ${describeSqlValueViolation(value)}`);
+    }
+}
 /**
  * Normalizes a parameter name to a number when it is an all-digits index,
  * matching how positional params are keyed elsewhere (array index + 1,

package/dist/src/core/param.js.map

@@ -1 +1 @@
-{"version":3,"file":"param.js","sourceRoot":"","sources":["../../../src/core/param.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAiC;IAClE,IAAI,OAAqD,CAAC;IAC1D,IAAI,MAAM,EAAE,CAAC;QACZ,OAAO,GAAG,IAAI,GAAG,EAA+B,CAAC;QACjD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE;gBACpC,uFAAuF;gBACvF,2EAA2E;gBAC3E,OAAQ,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,sBAAsB,CAAC,UAAU,CAAC,CAAC,CAAC;YAC7D,CAAC,CAAC,CAAC;QACJ,CAAC;aAAM,CAAC;YACP,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;gBAC/C,iFAAiF;gBACjF,8EAA8E;gBAC9E,6EAA6E;gBAC7E,8EAA8E;gBAC9E,yDAAyD;gBACzD,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;gBAC1D,OAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;YACtE,CAAC,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC7C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,6EAA6E;IAC7E,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAAC,KAAe;IAC9C,MAAM,WAAW,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAErD,OAAO;QACN,SAAS,EAAE,QAAQ;QACnB,WAAW;QACX,QAAQ,EAAE,KAAK,KAAK,IAAI;QACxB,UAAU,EAAE,IAAI;KAChB,CAAC;AACH,CAAC"}
+{"version":3,"file":"param.js","sourceRoot":"","sources":["../../../src/core/param.ts"],"names":[],"mappings":"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"}

package/dist/src/core/statement.d.ts

@@ -37,8 +37,23 @@ export declare class Statement {
     private needsCompile;
     private columnDefCache;
     private schemaChangeUnsubscriber;
-    /** Parameter types established at prepare time (either explicit or inferred from initial values) */
+    /**
+     * Types of the parameters that have one: the explicit hints handed to `prepare()`,
+     * or — when the caller supplied values instead — the type each parameter's FIRST
+     * bound value implied. Undefined while no parameter has a type at all; see
+     * {@link establishParameterTypes} for why that is not the same as an empty map.
+     */
     private parameterTypes;
+    /**
+     * True when {@link parameterTypes} came from an explicit hint map handed to
+     * `prepare()`. Such a map is CLOSED: a parameter it does not name stays ANY
+     * however it is later bound, and nothing is validated against it. That is a
+     * deliberate surface, not an oversight — `InternalStatementCache` prepares its FK
+     * probes with an EMPTY map precisely to get an affinity-neutral plan and no
+     * bind-time validation, so one cached statement can be rebound to an integer key
+     * on one row and a text key on the next.
+     */
+    private readonly parameterTypesDeclared;
     /**
      * Parameter names/indices used directly as a comparand in a scalar comparison
      * (`= <> < <= > >=` / `IN` / `BETWEEN`) against a non-object scalar operand.
@@ -51,6 +66,56 @@ export declare class Statement {
     nextStatement(): boolean;
     /** Returns the SQL fragment for the current statement, if available. */
     getBlockSql(): string;
+    /**
+     * Drops the compiled plan and everything derived from it, so the next
+     * {@link compile} rebuilds. THE one invalidation set — every caller that
+     * invalidates (schema change, statement advance, first bind onto a provisional
+     * plan) goes through here so none can forget a member and leave, say, a stale
+     * scheduler emitted from a discarded plan.
+     */
+    private invalidatePlan;
+    /**
+     * The parameter types to plan with, covering every parameter that has a bound
+     * value by the time this runs.
+     *
+     * Each parameter's type is established ONCE — by the first value ever bound to it
+     * — and is never re-inferred afterwards. That frozen contract is what
+     * {@link validateParameterTypes} checks and what lets repeated executions reuse one
+     * plan. Extending the map is not re-inferring: a parameter with no type yet has
+     * never been planned against anything, so taking its first value's type contradicts
+     * nothing already announced.
+     *
+     * Explicit hints short-circuit all of this — see {@link parameterTypesDeclared}.
+     *
+     * Returns undefined while NO parameter has a type. That state must not be recorded
+     * as an established-but-empty map: an empty map is indistinguishable from "typed,
+     * and there are none", and recording it would pin every parameter at ANY even
+     * after values arrive.
+     */
+    private establishParameterTypes;
+    /** True when some bound value belongs to a parameter that has no type yet. */
+    private hasUntypedBinding;
+    /**
+     * Called after every bind. A cached plan announces the parameter types that were
+     * established when it was built, so a bind that gives a value to a parameter that
+     * plan had NO type for — one compiled before any bind, or compiled while only some
+     * of the parameters were bound — no longer describes the query that will run.
+     * Discard it; the next compile plans against the newly available types.
+     *
+     * Costs at most one extra compile per parameter first bound after a compile, and
+     * none at all for a statement that binds before it plans.
+     *
+     * NOTE: `all(params)` / `get(params)` on a statement prepared WITHOUT values read
+     * `getColumnNames()` (which compiles) before handing `params` down, so they pay
+     * that extra compile on their first execution; `readConcurrency: 'committed'` adds
+     * {@link tryRouteConcurrent}'s compile ahead of it. Harmless: a result column's
+     * name and the column count come from the projection, and committed-read
+     * eligibility from the node kinds in the tree, so neither reads parameter types.
+     * If the extra compile ever shows up in a profile, bind at those call sites before
+     * reading names and pass `undefined` downstream, as {@link Database.get} already
+     * does.
+     */
+    private dropStalePlanOnBind;
     /**
      * Binds a user-provided argument value to a declared parameter name/index for the current statement.
      */

package/dist/src/core/statement.d.ts.map

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

package/dist/src/core/statement.js

@@ -13,7 +13,7 @@ import { Cached } from '../util/cached.js';
 import { isAsyncIterable, disconnectVTable } from '../runtime/utils.js';
 import { generateInstructionProgram, serializePlanTree } from '../planner/debug.js';
 import { EmissionContext } from '../runtime/emission-context.js';
-import { getParameterTypes } from './param.js';
+import { boundKeyToParamKey, emptyBoundParams, getParameterTypes, normalizeBoundParams } from './param.js';
 import { rowToObject } from './utils.js';
 import { getPhysicalType, physicalTypeName, PhysicalType } from '../types/logical-type.js';
 import { wrapAsyncIterator } from '../util/async-iterator.js';
@@ -42,7 +42,7 @@ export class Statement {
     astBatchIndex = -1;
     finalized = false;
     busy = false;
-    boundArgs = {};
+    boundArgs = emptyBoundParams();
     plan = null;
     emissionContext = null;
     /**
@@ -64,8 +64,23 @@ export class Statement {
     needsCompile = true;
     columnDefCache = new Cached(() => this.getColumnDefs());
     schemaChangeUnsubscriber = null;
-    /** Parameter types established at prepare time (either explicit or inferred from initial values) */
+    /**
+     * Types of the parameters that have one: the explicit hints handed to `prepare()`,
+     * or — when the caller supplied values instead — the type each parameter's FIRST
+     * bound value implied. Undefined while no parameter has a type at all; see
+     * {@link establishParameterTypes} for why that is not the same as an empty map.
+     */
     parameterTypes = undefined;
+    /**
+     * True when {@link parameterTypes} came from an explicit hint map handed to
+     * `prepare()`. Such a map is CLOSED: a parameter it does not name stays ANY
+     * however it is later bound, and nothing is validated against it. That is a
+     * deliberate surface, not an oversight — `InternalStatementCache` prepares its FK
+     * probes with an EMPTY map precisely to get an affinity-neutral plan and no
+     * bind-time validation, so one cached statement can be rebound to an integer key
+     * on one row and a text key on the next.
+     */
+    parameterTypesDeclared;
     /**
      * Parameter names/indices used directly as a comparand in a scalar comparison
      * (`= <> < <= > >=` / `IN` / `BETWEEN`) against a non-object scalar operand.
@@ -113,28 +128,25 @@ export class Statement {
             this.originalSql = this.astBatch.map(s => astToString(s)).join('; ');
         }
         // Handle explicit parameter types or initial values
+        this.parameterTypesDeclared = paramsOrTypes instanceof Map;
         if (paramsOrTypes instanceof Map) {
-            // Explicit parameter types provided
+            // Explicit parameter types provided — taken as given, never extended.
             this.parameterTypes = paramsOrTypes;
         }
         else if (paramsOrTypes !== undefined) {
-            // Initial parameter values - infer types and bind them
-            this.parameterTypes = getParameterTypes(paramsOrTypes);
-            // Also bind the initial values. Values canonicalize as they enter boundArgs
-            // (a safe-range bigint narrows to number, R1 — util/numeric-canonical.ts):
-            // per-bind, not per-row, and shared by all three ingress sites (here,
-            // bind, bindAll). Type inference above saw the raw values, but it maps a
-            // safe-range bigint and its number form to INTEGER alike, so no drift.
-            if (Array.isArray(paramsOrTypes)) {
-                paramsOrTypes.forEach((value, index) => {
-                    this.boundArgs[index + 1] = canonicalizeSqlValue(value);
-                });
-            }
-            else {
-                for (const [key, value] of Object.entries(paramsOrTypes)) {
-                    this.boundArgs[key] = canonicalizeSqlValue(value);
-                }
-            }
+            // Initial parameter values. Keys collapse onto one spelling per parameter and
+            // values canonicalize (a safe-range bigint narrows to number, R1 —
+            // util/numeric-canonical.ts) as they enter boundArgs: per-bind, not per-row,
+            // and shared by every ingress site (here, bind, bindAll, Database.exec,
+            // change-scope's bindParameters).
+            this.boundArgs = normalizeBoundParams(paramsOrTypes, 'prepare');
+            // Types follow from those values NOW, not at the first compile: prepare-time
+            // values are the declaration, so `prepare(sql, [1, 42]).run([2, 3.14])` must
+            // be a type mismatch and not a re-inference. Routed through the shared helper
+            // so the "no values is not an empty type map" rule holds here too — inferring
+            // inline is what let `prepare(sql, [])` freeze an established-but-EMPTY map
+            // and pin every later-bound parameter at ANY.
+            this.establishParameterTypes();
         }
         if (this.astBatch.length === 0 && initialAstIndex === 0) {
             // No statements to run, effectively. nextStatement will return false.
@@ -156,12 +168,11 @@ export class Statement {
             throw new MisuseError("Statement busy, reset or complete current iteration first.");
         if (this.astBatchIndex < this.astBatch.length - 1) {
             this.astBatchIndex++;
-            this.plan = null;
-            this.emissionContext = null;
-            this.scheduler = null;
-            this.needsCompile = true;
-            this.columnDefCache.clear();
-            this.parameterTypes = undefined;
+            this.invalidatePlan();
+            // Inferred types described the statement just left behind; a caller's explicit
+            // hint map was given for the whole prepared text and stays in force.
+            if (!this.parameterTypesDeclared)
+                this.parameterTypes = undefined;
             return true;
         }
         else {
@@ -175,6 +186,91 @@ export class Statement {
         }
         return astToString(this.getAstStatement());
     }
+    /**
+     * Drops the compiled plan and everything derived from it, so the next
+     * {@link compile} rebuilds. THE one invalidation set — every caller that
+     * invalidates (schema change, statement advance, first bind onto a provisional
+     * plan) goes through here so none can forget a member and leave, say, a stale
+     * scheduler emitted from a discarded plan.
+     */
+    invalidatePlan() {
+        this.needsCompile = true;
+        this.plan = null;
+        this.emissionContext = null;
+        this.scheduler = null;
+        this.columnDefCache.clear();
+    }
+    /**
+     * The parameter types to plan with, covering every parameter that has a bound
+     * value by the time this runs.
+     *
+     * Each parameter's type is established ONCE — by the first value ever bound to it
+     * — and is never re-inferred afterwards. That frozen contract is what
+     * {@link validateParameterTypes} checks and what lets repeated executions reuse one
+     * plan. Extending the map is not re-inferring: a parameter with no type yet has
+     * never been planned against anything, so taking its first value's type contradicts
+     * nothing already announced.
+     *
+     * Explicit hints short-circuit all of this — see {@link parameterTypesDeclared}.
+     *
+     * Returns undefined while NO parameter has a type. That state must not be recorded
+     * as an established-but-empty map: an empty map is indistinguishable from "typed,
+     * and there are none", and recording it would pin every parameter at ANY even
+     * after values arrive.
+     */
+    establishParameterTypes() {
+        if (this.parameterTypesDeclared)
+            return this.parameterTypes;
+        const inferred = getParameterTypes(this.boundArgs);
+        if (!inferred || inferred.size === 0)
+            return this.parameterTypes;
+        if (this.parameterTypes === undefined) {
+            this.parameterTypes = inferred;
+        }
+        else {
+            for (const [key, type] of inferred) {
+                if (!this.parameterTypes.has(key))
+                    this.parameterTypes.set(key, type);
+            }
+        }
+        return this.parameterTypes;
+    }
+    /** True when some bound value belongs to a parameter that has no type yet. */
+    hasUntypedBinding() {
+        for (const key of Object.keys(this.boundArgs)) {
+            if (!this.parameterTypes?.has(boundKeyToParamKey(key)))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Called after every bind. A cached plan announces the parameter types that were
+     * established when it was built, so a bind that gives a value to a parameter that
+     * plan had NO type for — one compiled before any bind, or compiled while only some
+     * of the parameters were bound — no longer describes the query that will run.
+     * Discard it; the next compile plans against the newly available types.
+     *
+     * Costs at most one extra compile per parameter first bound after a compile, and
+     * none at all for a statement that binds before it plans.
+     *
+     * NOTE: `all(params)` / `get(params)` on a statement prepared WITHOUT values read
+     * `getColumnNames()` (which compiles) before handing `params` down, so they pay
+     * that extra compile on their first execution; `readConcurrency: 'committed'` adds
+     * {@link tryRouteConcurrent}'s compile ahead of it. Harmless: a result column's
+     * name and the column count come from the projection, and committed-read
+     * eligibility from the node kinds in the tree, so neither reads parameter types.
+     * If the extra compile ever shows up in a profile, bind at those call sites before
+     * reading names and pass `undefined` downstream, as {@link Database.get} already
+     * does.
+     */
+    dropStalePlanOnBind() {
+        // A declared hint map never grows, so no bind can make the cached plan stale.
+        if (!this.plan || this.parameterTypesDeclared)
+            return;
+        if (!this.hasUntypedBinding())
+            return;
+        this.invalidatePlan();
+    }
     /** @internal Plans the current AST statement */
     compile() {
         if (this.plan && !this.needsCompile)
@@ -185,23 +281,16 @@ export class Statement {
         let plan;
         try {
             const currentAst = this.getAstStatement();
-            // On first compilation, establish the parameter types
-            // Use explicit types if provided, otherwise infer from bound args
-            // NOTE: this freezes on the FIRST compile, and empty bound args yield an empty
-            // (but established) map — so compiling before any bind (getColumnDefs()/isQuery()
-            // on a freshly prepared statement) permanently leaves every parameter at the
-            // default TEXT type, while binding first types them from the values. The
-            // execution paths bind before compiling, so this only shows through pre-bind
-            // introspection. Deliberate: re-inferring per bind would recompile the plan on
-            // every execution and defeat validateParameterTypes' frozen-type check. Revisit
-            // (invalidate the plan on a type-changing bind) if pre-bind introspection ever
-            // needs to agree with the executed plan.
-            if (this.parameterTypes === undefined) {
-                // Infer types from current bound args
-                this.parameterTypes = getParameterTypes(this.boundArgs);
-            }
+            // Types come from the values bound so far, never from emptiness: compiling
+            // with nothing bound leaves them undefined rather than freezing an empty (but
+            // established) map, which would pin every parameter at ANY for the statement's
+            // whole life. A parameter that already has a type keeps it — that frozen
+            // contract is what validateParameterTypes checks, and what lets repeated
+            // executions reuse one plan — while one bound for the FIRST time after this
+            // plan was built has already invalidated it (see dropStalePlanOnBind).
+            const parameterTypes = this.establishParameterTypes();
             // Pass parameter types directly to planning
-            const { plan: rawPlan, schemaDependencies: dependencies } = this.db._buildPlan([currentAst], this.parameterTypes, this._schemaPathOverride);
+            const { plan: rawPlan, schemaDependencies: dependencies } = this.db._buildPlan([currentAst], parameterTypes, this._schemaPathOverride);
             // Collect array-valued-scalar-param guard targets from the LOGICAL plan,
             // before the access-path optimizer folds `col = ?` comparisons into index
             // seeks (which erases the comparison node). See validateParameterTypes.
@@ -255,11 +344,7 @@ export class Statement {
                         (!dep.schemaName || dep.schemaName === event.schemaName));
                     if (affectedDependency) {
                         log('Schema change invalidated plan for statement: %s %s', event.type, event.objectName);
-                        this.needsCompile = true;
-                        this.plan = null;
-                        this.emissionContext = null;
-                        this.scheduler = null;
-                        this.columnDefCache.clear();
+                        this.invalidatePlan();
                     }
                 });
             }
@@ -296,17 +381,18 @@ export class Statement {
         if (!isSqlValue(value)) {
             throw new MisuseError(`bind: invalid value for key '${key}': expected SqlValue, got ${describeSqlValueViolation(value)}`);
         }
-        if (typeof key === 'number') {
-            if (key < 1)
-                throw new RangeError(`Argument index ${key} out of range (must be >= 1)`);
-            this.boundArgs[key] = canonicalizeSqlValue(value);
-        }
-        else if (typeof key === 'string') {
-            this.boundArgs[key] = canonicalizeSqlValue(value);
-        }
-        else {
+        if (typeof key !== 'number' && typeof key !== 'string') {
             throw new MisuseError("Invalid argument key type");
         }
+        // One spelling per parameter, as at every other ingress — ':p'/'$p'/'p' and
+        // '1'/':1'/':01' each collapse to one key. The index range check runs AFTER
+        // normalization so bind(':0') is rejected exactly as bind(0) is.
+        const paramKey = typeof key === 'number' ? key : boundKeyToParamKey(key);
+        if (typeof paramKey === 'number' && paramKey < 1) {
+            throw new RangeError(`Argument index ${key} out of range (must be >= 1)`);
+        }
+        this.boundArgs[paramKey] = canonicalizeSqlValue(value);
+        this.dropStalePlanOnBind();
         return this;
     }
     /**
@@ -316,31 +402,13 @@ export class Statement {
         this.validateStatement("bind all parameters for");
         if (this.busy)
             throw new MisuseError("Statement busy, reset first");
-        this.boundArgs = {};
-        if (Array.isArray(args)) {
-            // Convert array to object with 1-based numeric keys to match bind() and constructor
-            args.forEach((value, index) => {
-                if (!isSqlValue(value)) {
-                    throw new MisuseError(`bindAll: invalid value at index ${index}: expected SqlValue, got ${describeSqlValueViolation(value)}`);
-                }
-                this.boundArgs[index + 1] = canonicalizeSqlValue(value);
-            });
-        }
-        else if (typeof args === 'object' && args !== null) {
-            // Validate every entry before assigning any, so a rejected value leaves
-            // boundArgs empty rather than partially bound.
-            for (const [key, value] of Object.entries(args)) {
-                if (!isSqlValue(value)) {
-                    throw new MisuseError(`bindAll: invalid value for key '${key}': expected SqlValue, got ${describeSqlValueViolation(value)}`);
-                }
-            }
-            for (const [key, value] of Object.entries(args)) {
-                this.boundArgs[key] = canonicalizeSqlValue(value);
-            }
-        }
-        else {
+        if (!Array.isArray(args) && (typeof args !== 'object' || args === null)) {
             throw new MisuseError("Invalid parameters type for bindAll. Use array or object.");
         }
+        // Normalize first, assign second: a rejected object (bad value, or one parameter
+        // bound under two spellings) leaves the previous bindings untouched.
+        this.boundArgs = normalizeBoundParams(args, 'bindAll');
+        this.dropStalePlanOnBind();
         return this;
     }
     /** Checks if the current statement, when executed, is expected to produce rows. */
@@ -673,7 +741,7 @@ export class Statement {
         this.validateStatement("clear bindings for");
         if (this.busy)
             throw new MisuseError("Statement busy, reset first");
-        this.boundArgs = {};
+        this.boundArgs = emptyBoundParams();
         // Don't set needsCompile - parameter types are preserved
         return this;
     }
@@ -685,7 +753,7 @@ export class Statement {
             return;
         this.finalized = true;
         this.busy = false;
-        this.boundArgs = {};
+        this.boundArgs = emptyBoundParams();
         this.plan = null;
         this.emissionContext = null;
         this.scheduler = null;
@@ -907,11 +975,11 @@ export class Statement {
         // silently return no rows. The set is collected structurally at plan time
         // (JSON-vs-JSON comparisons are excluded), so this never over-fires.
         for (const key of this.scalarRequiredParams) {
-            // Presence check, not `??`: a parameter legitimately bound to `null` must
-            // use that binding, not fall through to the `:`-prefixed alternate key.
-            const value = typeof key === 'string'
-                ? (Object.hasOwn(this.boundArgs, key) ? this.boundArgs[key] : this.boundArgs[`:${key}`])
-                : this.boundArgs[key];
+            // `scalarRequiredParams` keys are plan-side (already bare / numeric) and
+            // boundArgs is normalized to the same keys at ingress, so one lookup finds
+            // the binding whatever spelling the caller used. `undefined` still means
+            // "not bound" — a parameter bound to `null` reads as `null` and is checked.
+            const value = this.boundArgs[key];
             if (value !== undefined && isObjectClassValue(value)) {
                 throw new QuereusError(`parameter ${typeof key === 'number' ? `?${key}` : `:${key}`} ` +
                     `bound to an array/object value but used in a scalar comparison`, StatusCode.MISMATCH);
@@ -979,10 +1047,7 @@ export class Statement {
      */
     getAnalysisPlan() {
         const currentAst = this.getAstStatement();
-        if (this.parameterTypes === undefined) {
-            this.parameterTypes = getParameterTypes(this.boundArgs);
-        }
-        const { plan: rawPlan } = this.db._buildPlan([currentAst], this.parameterTypes, this._schemaPathOverride);
+        const { plan: rawPlan } = this.db._buildPlan([currentAst], this.establishParameterTypes(), this._schemaPathOverride);
         return this.db.optimizer.optimizeForAnalysis(rawPlan, this.db);
     }
     /**