@quereus/quereus 4.9.0 → 4.10.0

package/dist/src/runtime/scalar-fusion.js

@@ -0,0 +1,275 @@
+import { StatusCode } from '../common/types.js';
+import { QuereusError } from '../common/errors.js';
+import { PlanNodeType } from '../planner/nodes/plan-node-type.js';
+import { isScalarFunctionSchema } from '../schema/function.js';
+import { assertSpecArity } from './emit/scalar-op.js';
+import { buildScalarFunctionRun } from './emit/scalar-function.js';
+import { buildLiteralSpec } from './emit/literal.js';
+import { buildColumnReferenceSpec } from './emit/column-reference.js';
+import { buildParameterSpec } from './emit/parameter.js';
+import { buildCastSpec } from './emit/cast.js';
+import { buildUnaryOpSpec } from './emit/unary.js';
+import { buildBetweenSpec } from './emit/between.js';
+import { buildBinaryOpSpec } from './emit/binary.js';
+import { buildCaseMatcher } from './emit/case.js';
+import { isTruthy } from '../util/comparison.js';
+/**
+ * Largest fused subtree depth. Fused closures nest on the JS call stack where the
+ * scheduler's linearized instruction loop did not, so a pathologically deep expression
+ * (`a+a+a+…` thousands of terms) could overflow the stack where it works unfused.
+ * Past this depth the expression offered to {@link tryFuseScalar} falls back whole to the
+ * sub-program path — correct, just unoptimized. Fusion is still retried from depth 0 at
+ * every nested `emitCallFromPlan` site the fallback emission reaches (CASE branches, an
+ * AND/OR short-circuit right leg), so a deep tree fuses in pieces below those seams rather
+ * than not at all. 32 is far above any real expression's nesting.
+ */
+export const MAX_FUSION_DEPTH = 32;
+/**
+ * Compile `plan` into a single closure, or return undefined if any node in the subtree
+ * cannot be fused (an unsupported node type, a subquery, anything that can return a
+ * Promise, or a subtree deeper than {@link MAX_FUSION_DEPTH}). Undefined is the normal
+ * answer for most of the plan tree; the caller falls back to the sub-program path
+ * unchanged.
+ *
+ * Every fused body comes from the node's own {@link ScalarOpSpec} builder (or, for
+ * CASE, from `buildCaseMatcher`) — the same functions the instruction emitters run —
+ * so a fused expression and its instruction form cannot disagree on semantics, error
+ * messages, or evaluation counts. This compiler only changes HOW operand values reach
+ * those bodies: direct nested calls instead of scheduler slots.
+ *
+ * A scalar function call fuses only when it is provably synchronous — see
+ * {@link fuseScalarFunctionCall}. The AND/OR short-circuit form declines through
+ * `buildBinaryOpSpec` returning undefined, and subquery/window/aggregate/relational
+ * nodes decline as unknown node types — which also keeps every `emitCallFromPlan` call
+ * site that passes a relational plan (cache sources, join legs, view-mutation programs)
+ * on the sub-program path for free.
+ */
+export function tryFuseScalar(plan, ctx) {
+    return fuseNode(plan, ctx, 0);
+}
+// NOTE: a subtree that declines partway has already built every spec above the declining
+// node — resolving collations, compiling a constant LIKE matcher — and those are then
+// rebuilt by the fallback `emitPlanNode`. Emit-time only, bounded by subtree size, and the
+// idempotent work (collation lookups record into a Set) cannot diverge. Fine today; if emit
+// latency ever shows up on function-heavy expressions, pre-walk the subtree for unfusable
+// node types before building any spec.
+/** Per-node dispatch. `depth` counts the closure frames already wrapping this node. */
+function fuseNode(plan, ctx, depth) {
+    if (depth > MAX_FUSION_DEPTH)
+        return undefined;
+    switch (plan.nodeType) {
+        case PlanNodeType.Literal: {
+            // Undefined when the literal holds an unresolved async constant-fold result —
+            // the scheduler resolves that Promise; a fused closure could not.
+            const spec = buildLiteralSpec(plan);
+            return spec && fuseSpec(spec, ctx, depth);
+        }
+        case PlanNodeType.ColumnReference:
+            return fuseSpec(buildColumnReferenceSpec(plan), ctx, depth);
+        case PlanNodeType.ParameterReference:
+            return fuseSpec(buildParameterSpec(plan), ctx, depth);
+        case PlanNodeType.Collate:
+            // No runtime effect (mirrors emitCollate) — fuse straight through to the
+            // operand. Adds no closure frame, so depth is unchanged.
+            return fuseNode(plan.operand, ctx, depth);
+        case PlanNodeType.Cast:
+            return fuseSpec(buildCastSpec(plan), ctx, depth);
+        case PlanNodeType.UnaryOp:
+            return fuseSpec(buildUnaryOpSpec(plan), ctx, depth);
+        case PlanNodeType.Between:
+            return fuseSpec(buildBetweenSpec(plan, ctx), ctx, depth);
+        case PlanNodeType.BinaryOp: {
+            // Undefined for the AND/OR short-circuit form (subquery right operand),
+            // whose right leg is a deferred sub-program rather than a value.
+            const spec = buildBinaryOpSpec(plan, ctx);
+            return spec && fuseSpec(spec, ctx, depth);
+        }
+        case PlanNodeType.CaseExpr:
+            return fuseCase(plan, ctx, depth);
+        case PlanNodeType.ScalarFunctionCall:
+            return fuseScalarFunctionCall(plan, ctx, depth);
+        default:
+            return undefined;
+    }
+}
+/**
+ * The `AsyncFunction` constructor, which has no global binding — reachable only off an
+ * instance. An `async function` / `async` arrow carries `AsyncFunction.prototype` on its
+ * prototype chain, so `impl instanceof AsyncFunction` recognizes one.
+ *
+ * NOTE: `instanceof` is realm-local. A plugin loaded into a *different* JS realm (a worker,
+ * an iframe, a `node:vm` context) carries that realm's `AsyncFunction.prototype`, so its
+ * async implementation would not be recognized and would fall to step 4's guard — a thrown
+ * error with the `isAsync` remedy rather than a wrong answer. No loader in this repo crosses
+ * a realm (plugin-loader uses same-realm dynamic `import()`); if one ever does, widen this
+ * to also accept `impl[Symbol.toStringTag] === 'AsyncFunction'`, which is realm-agnostic.
+ */
+const AsyncFunction = (async () => { }).constructor;
+/**
+ * Fuse a scalar function call, but only when its implementation is provably
+ * synchronous. A fused node's contract is a plain `SqlValue`, while a `ScalarFunc` is
+ * typed `(...args) => MaybePromise<SqlValue>`; admitting `MaybePromise` into the fused
+ * contract would put a Promise check and a `.then` path on every node in the chain,
+ * which is the sub-program overhead this compiler exists to delete. So the decision is
+ * made once here, at emit time, in this order:
+ *
+ * 1. **A `customEmitter` never fuses.** It builds its own `Instruction` — possibly with
+ *    sub-programs or async behavior — and this compiler cannot see inside it. Today that
+ *    excludes `nullif`, `greatest`, `least`, `json_schema` and `mutation_ordinal`;
+ *    giving custom emitters a fusion hook is parked in
+ *    `tickets/backlog/feat-fuse-custom-emitter-scalar-functions.md`.
+ * 2. **`isAsync === true` never fuses** — the author's explicit declaration.
+ * 3. **A declared `async` implementation never fuses**, auto-detected, so the ordinary
+ *    async UDF needs no flag.
+ * 4. **Otherwise fuse, with a guard**: a non-`async` implementation that returns a
+ *    Promise anyway is invisible to step 3, so the fused body checks and throws a
+ *    `QuereusError` naming the function and the `isAsync` remedy. One `instanceof` per
+ *    call — negligible beside the sub-program it replaces — and it converts a silent
+ *    wrong answer (a Promise flowing on as if it were a value, comparing as garbage)
+ *    into a loud, actionable error.
+ *
+ * The body itself is {@link buildScalarFunctionRun}, the same one
+ * `emitScalarFunctionCallDefault` gives the scheduler, so a fused call and an
+ * instruction call cannot disagree on error text, arity checking or the `REPR_STRICT`
+ * return check. Operands compose by arity like every other fused node — including the
+ * variadic case (`numArgs === -1`, e.g. `coalesce`), which needs no special handling
+ * because the composition switches on `operands.length`, not on the declared arity.
+ */
+function fuseScalarFunctionCall(plan, ctx, depth) {
+    const schema = plan.functionSchema;
+    // Not a scalar schema at all: `emitScalarFunctionCall` reports that, and the unfused
+    // path it falls back to still does. Decline rather than duplicate the diagnosis.
+    if (!isScalarFunctionSchema(schema))
+        return undefined;
+    if (schema.customEmitter)
+        return undefined;
+    if (schema.isAsync)
+        return undefined;
+    if (schema.implementation instanceof AsyncFunction)
+        return undefined;
+    const body = buildScalarFunctionRun(plan);
+    const functionName = plan.expression.name.toLowerCase();
+    const loc = plan.expression.loc?.start;
+    const guarded = (rctx, ...args) => {
+        const result = body(rctx, ...args);
+        if (result instanceof Promise) {
+            throw new QuereusError(`Function ${functionName} returned a Promise but is not declared asynchronous. `
+                + `Declare isAsync: true on its registration so the engine keeps it off the fused expression path.`, StatusCode.ERROR, undefined, loc?.line, loc?.column);
+        }
+        return result;
+    };
+    return composeFused(guarded, plan.operands, ctx, depth);
+}
+/** Check the spec's body arity, then compose it with its fused operands. */
+function fuseSpec(spec, ctx, depth) {
+    assertSpecArity(spec);
+    return composeFused(spec.run, spec.operands, ctx, depth);
+}
+/**
+ * Compose a synchronous body with its fused operands, specialized by arity so the common
+ * cases allocate nothing per row and stay monomorphic. Closure composition only — no
+ * `new Function`/`eval`, which are unavailable under a Content-Security-Policy and under
+ * React Native.
+ *
+ * Shared by the {@link ScalarOpSpec} nodes and by {@link fuseScalarFunctionCall}, whose
+ * variadic body has no fixed parameter count to assert (hence the assert living in
+ * {@link fuseSpec}, not here). The switch is on how many operands are actually
+ * evaluated, so a variadic function's call site lands in whichever fixed arm matches
+ * its argument count.
+ */
+function composeFused(run, operands, ctx, depth) {
+    switch (operands.length) {
+        case 0:
+            // The body already IS the fused closure — wrapping it would add a call frame
+            // per row to the two most common leaves in any query (column refs, literals).
+            return run;
+        case 1: {
+            const a = fuseNode(operands[0], ctx, depth + 1);
+            return a && ((rctx) => run(rctx, a(rctx)));
+        }
+        case 2: {
+            const a = fuseNode(operands[0], ctx, depth + 1);
+            if (!a)
+                return undefined;
+            const b = fuseNode(operands[1], ctx, depth + 1);
+            return b && ((rctx) => run(rctx, a(rctx), b(rctx)));
+        }
+        case 3: {
+            const a = fuseNode(operands[0], ctx, depth + 1);
+            if (!a)
+                return undefined;
+            const b = fuseNode(operands[1], ctx, depth + 1);
+            if (!b)
+                return undefined;
+            const c = fuseNode(operands[2], ctx, depth + 1);
+            return c && ((rctx) => run(rctx, a(rctx), b(rctx), c(rctx)));
+        }
+        default: {
+            // No spec is wider than 3 operands; a wide variadic call (`coalesce(a,b,c,d)`)
+            // lands here. An args array + spread is still far cheaper than a sub-program.
+            const fused = [];
+            for (const operand of operands) {
+                const f = fuseNode(operand, ctx, depth + 1);
+                if (!f)
+                    return undefined;
+                fused.push(f);
+            }
+            return (rctx) => run(rctx, ...fused.map(f => f(rctx)));
+        }
+    }
+}
+/**
+ * CASE is the one covered node that is not a flat {@link ScalarOpSpec}: its branches are
+ * lazy. Fuse it only when the base (if any) AND every WHEN/THEN/ELSE fuse — all-or-nothing
+ * avoids a mixed contract where some branches are closures and some are sub-programs
+ * returning `MaybePromise`. The fused body keeps SQL's evaluation rules exactly as
+ * `emitCaseExpr` has them: WHEN clauses left to right, stop at the first match, evaluate
+ * ONLY the selected result, never touch a later clause. Match decisions come from
+ * `buildCaseMatcher`, so a fused CASE and an instruction CASE cannot disagree.
+ *
+ * Branch closures are invoked from inside the CASE closure, so their frames stack —
+ * they count toward the depth cap (depth + 1), same as spec operands.
+ */
+function fuseCase(plan, ctx, depth) {
+    const whens = [];
+    const thens = [];
+    for (const clause of plan.whenThenClauses) {
+        const when = fuseNode(clause.when, ctx, depth + 1);
+        if (!when)
+            return undefined;
+        const then = fuseNode(clause.then, ctx, depth + 1);
+        if (!then)
+            return undefined;
+        whens.push(when);
+        thens.push(then);
+    }
+    const elseFn = plan.elseExpr ? fuseNode(plan.elseExpr, ctx, depth + 1) : undefined;
+    if (plan.elseExpr && !elseFn)
+        return undefined;
+    const clauseCount = whens.length;
+    // Simple CASE: base compared against each WHEN under the per-clause pre-resolved
+    // comparator (collation + type routing). A NULL base matches nothing.
+    if (plan.baseExpr) {
+        const base = fuseNode(plan.baseExpr, ctx, depth + 1);
+        if (!base)
+            return undefined;
+        const matcher = buildCaseMatcher(plan, ctx);
+        return (rctx) => {
+            const baseValue = base(rctx);
+            for (let i = 0; i < clauseCount; i++) {
+                if (matcher.matches(i, baseValue, whens[i](rctx)))
+                    return thens[i](rctx);
+            }
+            return elseFn ? elseFn(rctx) : null;
+        };
+    }
+    // Searched CASE: first truthy WHEN selects its THEN.
+    return (rctx) => {
+        for (let i = 0; i < clauseCount; i++) {
+            if (isTruthy(whens[i](rctx)))
+                return thens[i](rctx);
+        }
+        return elseFn ? elseFn(rctx) : null;
+    };
+}
+//# sourceMappingURL=scalar-fusion.js.map

package/dist/src/runtime/scalar-fusion.js.map

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

package/dist/src/runtime/strict-flags.d.ts

@@ -19,4 +19,13 @@ export declare const FORK_STRICT: boolean;
  * § Invariant: source-attr contexts and child pulls.
  */
 export declare const CONTEXT_STRICT: boolean;
+/**
+ * `QUEREUS_REPR_STRICT` — physical-representation assertions. Verifies at four
+ * runtime seams (vtab scan output, DML write, UDF return, statement row egress)
+ * that every value is in the JavaScript form its declared type promises — R1
+ * (canonical numeric form) and R2 (per-declared-type value space) of
+ * docs/types.md § Physical representation. Off, the checks are a single
+ * already-false branch. See strict-representation.ts.
+ */
+export declare const REPR_STRICT: boolean;
 //# sourceMappingURL=strict-flags.d.ts.map

package/dist/src/runtime/strict-flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-flags.d.ts","sourceRoot":"","sources":["../../../src/runtime/strict-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,sFAAsF;AACtF,eAAO,MAAM,WAAW,SAAkC,CAAC;AAE3D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,SAAqC,CAAC"}
+{"version":3,"file":"strict-flags.d.ts","sourceRoot":"","sources":["../../../src/runtime/strict-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,sFAAsF;AACtF,eAAO,MAAM,WAAW,SAAkC,CAAC;AAE3D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,SAAqC,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,SAAkC,CAAC"}

package/dist/src/runtime/strict-flags.js

@@ -23,4 +23,13 @@ export const FORK_STRICT = readFlag('QUEREUS_FORK_STRICT');
  * § Invariant: source-attr contexts and child pulls.
  */
 export const CONTEXT_STRICT = readFlag('QUEREUS_CONTEXT_STRICT');
+/**
+ * `QUEREUS_REPR_STRICT` — physical-representation assertions. Verifies at four
+ * runtime seams (vtab scan output, DML write, UDF return, statement row egress)
+ * that every value is in the JavaScript form its declared type promises — R1
+ * (canonical numeric form) and R2 (per-declared-type value space) of
+ * docs/types.md § Physical representation. Off, the checks are a single
+ * already-false branch. See strict-representation.ts.
+ */
+export const REPR_STRICT = readFlag('QUEREUS_REPR_STRICT');
 //# sourceMappingURL=strict-flags.js.map

package/dist/src/runtime/strict-flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"strict-flags.js","sourceRoot":"","sources":["../../../src/runtime/strict-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,SAAS,QAAQ,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,MAAM,CAAC;AAC1C,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC,qBAAqB,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"strict-flags.js","sourceRoot":"","sources":["../../../src/runtime/strict-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,SAAS,QAAQ,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,MAAM,CAAC;AAC1C,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC,qBAAqB,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC,wBAAwB,CAAC,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/src/runtime/strict-fork.js

@@ -14,7 +14,7 @@ import { FORK_STRICT, CONTEXT_STRICT } from './strict-flags.js';
  *      forks is being driven throws. State is tracked **per parent map** (not
  *      globally) so concurrent unrelated drivers don't interfere, forks may mutate
  *      their own fresh maps freely, and sub-forks are independently tracked.
- *      See docs/runtime.md § Parallel runtime fork contract.
+ *      See docs/runtime-parallel.md § Parallel runtime fork contract.
  *
  *   2. **`QUEREUS_CONTEXT_STRICT`** — stale-shadow detection. Maintains a per-
  *      descriptor epoch and a per-attribute index-winner map so `assertNoShadow`
@@ -39,7 +39,7 @@ export function strictForkEnabled() {
 }
 function violation(target, count) {
     throw new QuereusError(`strict-fork: parent context mutated ${target} while ${count} fork(s) are active. ` +
-        `This is a fork-contract violation. See docs/runtime.md § Parallel runtime fork contract.`, StatusCode.INTERNAL);
+        `This is a fork-contract violation. See docs/runtime-parallel.md § Parallel runtime fork contract.`, StatusCode.INTERNAL);
 }
 /**
  * Wrap a fresh `tableContexts` Map. In non-strict mode returns the input

package/dist/src/runtime/strict-fork.js.map

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

package/dist/src/runtime/strict-representation.d.ts

@@ -0,0 +1,78 @@
+import { QuereusError } from '../common/errors.js';
+import { type DeepReadonly, type Row, type SqlValue } from '../common/types.js';
+import { type LogicalType } from '../types/logical-type.js';
+/**
+ * Off-by-default physical-representation assertions (`QUEREUS_REPR_STRICT`).
+ *
+ * The engine canonicalizes every value it MINTS itself (see
+ * `util/numeric-canonical.ts` and docs/types.md § Physical representation). Two
+ * ingress boundaries are deliberately left uncoerced because coercing them costs
+ * per row where there is nothing to win:
+ *
+ * - rows returned by a virtual-table module's `query()`, including third-party
+ *   modules the engine cannot vet;
+ * - values returned by user-defined functions.
+ *
+ * For those the contract is **declared and checked, not enforced**: a module or UDF
+ * is obliged to return canonical values, and this harness verifies it when the flag
+ * is on. Same shape as the parallel-fork (`QUEREUS_FORK_STRICT`) and stale-context
+ * (`QUEREUS_CONTEXT_STRICT`) harnesses in `strict-fork.ts`.
+ *
+ * The two rules checked here, restated from docs/types.md § Physical representation:
+ *
+ * - **R1 — canonical numeric form.** A `SqlValue` is a JS `bigint` only when its
+ *   magnitude is outside the safe-integer range. Applies to every value, whatever its
+ *   declared type, including `ANY` positions.
+ * - **R2 — per-declared-type value space.** A value in a position of a declared type
+ *   inhabits that type's JS value space (INTEGER → safe-integer `number` or `bigint`,
+ *   TEXT → `string`, BLOB → `Uint8Array`, …). Implies R1.
+ *
+ * `null` is always admissible: nullability is `not null` constraint enforcement's
+ * job and lives elsewhere.
+ *
+ * **No capability flag.** A `representationFidelity` declaration on
+ * `VirtualTableModule` was considered and rejected — nothing would BEHAVE differently
+ * based on it, since the engine tolerates both numeric forms everywhere and will
+ * continue to. The obligation lives in the module contract prose (`vtab/module.ts`)
+ * and is enforced here in tests.
+ *
+ * Every call site is guarded by `if (REPR_STRICT)` read from the module-level const in
+ * `strict-flags.ts`, so with the flag off each seam is one already-false branch and
+ * nothing is built at emit time on this module's behalf.
+ */
+/**
+ * A declared type as this checker reads it. Only `name` and `physicalType` are
+ * consulted, and the parameter is `DeepReadonly` so both a raw `LogicalType` (column
+ * schema) and the frozen one a `ScalarType` carries are accepted without a cast.
+ */
+export type DeclaredType = DeepReadonly<LogicalType>;
+/** A violation of R1/R2. Distinct class so a seam inside a re-wrapping `catch`
+ *  (the vtab scan) can rethrow it unchanged instead of burying it in a generic
+ *  "error during query" message. */
+export declare class RepresentationError extends QuereusError {
+    constructor(message: string);
+}
+/**
+ * R1 for one value: no `bigint` may hold a safe-range integer. Needs no declared type,
+ * so this is the check for `ANY` and untyped positions.
+ *
+ * `where` names the seam and the position (column / argument) and is quoted verbatim
+ * into the message — make it something a plugin author who has never read this code
+ * can act on, e.g. `` `module 'memory' scan of main.t column 2 (id)` ``.
+ */
+export declare function assertCanonicalValue(value: SqlValue, where: string): void;
+/**
+ * R2 for one value in a position of declared type `type` (implies R1).
+ * See {@link assertCanonicalValue} for what `where` should say.
+ */
+export declare function assertConformsToType(value: SqlValue, type: DeclaredType, where: string): void;
+/**
+ * Row form of {@link assertConformsToType}. `types[i]` may be `undefined` — an ANY /
+ * untyped position, which is normal and gets R1 only, never a reported violation.
+ * A cell past the end of `types` is treated the same way.
+ *
+ * `columnNames[i]`, when supplied, is folded into the `where` text so the message
+ * names the column a plugin author declared rather than an ordinal.
+ */
+export declare function assertRowConforms(row: Row, types: readonly (DeclaredType | undefined)[], where: string, columnNames?: readonly (string | undefined)[]): void;
+//# sourceMappingURL=strict-representation.d.ts.map

package/dist/src/runtime/strict-representation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-representation.d.ts","sourceRoot":"","sources":["../../../src/runtime/strict-representation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAc,KAAK,YAAY,EAAE,KAAK,GAAG,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAI1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;AAErD;;oCAEoC;AACpC,qBAAa,mBAAoB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM;CAK3B;AAiGD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOzE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAS7F;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,SAAS,CAAC,YAAY,GAAG,SAAS,CAAC,EAAE,EAC5C,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAC3C,IAAI,CAWN"}

package/dist/src/runtime/strict-representation.js

@@ -0,0 +1,159 @@
+import { QuereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+import { PhysicalType } from '../types/logical-type.js';
+import { isCanonicalNumeric } from '../util/numeric-canonical.js';
+import { valueToText } from '../util/value-text.js';
+/** A violation of R1/R2. Distinct class so a seam inside a re-wrapping `catch`
+ *  (the vtab scan) can rethrow it unchanged instead of burying it in a generic
+ *  "error during query" message. */
+export class RepresentationError extends QuereusError {
+    constructor(message) {
+        super(message, StatusCode.INTERNAL);
+        this.name = 'RepresentationError';
+        Object.setPrototypeOf(this, RepresentationError.prototype);
+    }
+}
+/** Longest value rendering included in a violation message before truncation. */
+const MAX_RENDERED_VALUE = 80;
+/**
+ * Render a value for a diagnostic. Routes through {@link valueToText}, which is total
+ * over `SqlValue` — deliberately NOT `JSON.stringify`, whose BigInt arm throws
+ * ("Do not know how to serialize a BigInt") on exactly the values this checker exists
+ * to catch.
+ *
+ * `valueToText` still stringifies a JSON *document*, so a document holding a value
+ * outside `JsonSqlValue` (a nested `bigint`) can throw here. That is itself
+ * representation drift, so the failure is folded into the message rather than
+ * allowed to replace the violation with a serializer error.
+ */
+function renderValue(value) {
+    let text;
+    try {
+        text = valueToText(value) ?? 'null';
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        return `<unrenderable ${jsTypeOf(value)}: ${reason}>`;
+    }
+    return text.length > MAX_RENDERED_VALUE ? `${text.slice(0, MAX_RENDERED_VALUE)}…` : text;
+}
+/** The JS form of a value, named the way a plugin author would recognize it. */
+function jsTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (value instanceof Uint8Array)
+        return 'Uint8Array';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/** The JS forms a declared type admits, for the "expected" half of a message. */
+function admissibleForms(type) {
+    switch (type.physicalType) {
+        case PhysicalType.INTEGER: return 'a safe-integer number, or a bigint outside the safe-integer range';
+        case PhysicalType.REAL: return type.name === 'NUMERIC'
+            ? 'a number, or a bigint outside the safe-integer range'
+            : 'a number';
+        case PhysicalType.TEXT: return 'a string';
+        case PhysicalType.BLOB: return 'a Uint8Array';
+        case PhysicalType.BOOLEAN: return 'a boolean';
+        case PhysicalType.OBJECT: return 'a JSON object/array, or a JSON scalar (string/number/boolean)';
+        default: return 'any value in canonical form';
+    }
+}
+/**
+ * R2 for one non-null value that has already passed R1.
+ *
+ * Keyed on `physicalType` rather than the type's identity so plugin-registered types
+ * are covered too. Two arms need the type NAME as well:
+ *
+ * - **NUMERIC** shares REAL's `physicalType` (see the NOTE on `NUMERIC_TYPE` in
+ *   `types/builtin-types.ts`) but its value space includes `bigint`.
+ *   NOTE: matched by NAME, not by identity against the `NUMERIC_TYPE` singleton the way
+ *   `isSeekKeySpaceNumeric` matches, because the surrounding switch is deliberately keyed
+ *   on `physicalType` so plugin-registered types are covered. The cost is that a
+ *   plugin-registered REAL-physical type *named* `NUMERIC` would silently inherit
+ *   bigint admission. No such type exists in tree; if one is ever registered, give
+ *   `LogicalType` an explicit "admits bigint" property and switch on that instead.
+ * - **`ANY`/NULL** (`PhysicalType.NULL`) impose no R2 constraint at all — R1 already
+ *   passed, and an `ANY` position may legitimately hold any storage class.
+ *
+ * TIMESTAMP needs no special case: it declares `physicalType` INTEGER because it IS an
+ * integer instant, so it takes INTEGER's rule. The string temporals (DATE / TIME /
+ * DATETIME / TIMESPAN) declare TEXT and take TEXT's — R2 must not demand a `Temporal`
+ * object for them.
+ */
+function conformsToType(value, type) {
+    switch (type.physicalType) {
+        case PhysicalType.INTEGER:
+            return typeof value === 'bigint' || (typeof value === 'number' && Number.isSafeInteger(value));
+        case PhysicalType.REAL:
+            return typeof value === 'number' || (typeof value === 'bigint' && type.name === 'NUMERIC');
+        case PhysicalType.TEXT:
+            return typeof value === 'string';
+        case PhysicalType.BLOB:
+            return value instanceof Uint8Array;
+        case PhysicalType.BOOLEAN:
+            return typeof value === 'boolean';
+        case PhysicalType.OBJECT:
+            // Mirrors JSON_TYPE.validate: a native object/array (a blob is not one), or a
+            // JSON scalar — a JSON string scalar is physically a plain `string`.
+            return (typeof value === 'object' && !(value instanceof Uint8Array))
+                || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+        default:
+            // PhysicalType.NULL (ANY / NULL) and any unrecognized plugin code: R1 only.
+            return true;
+    }
+}
+const DOC_POINTER = 'See docs/types.md § Physical representation.';
+/**
+ * R1 for one value: no `bigint` may hold a safe-range integer. Needs no declared type,
+ * so this is the check for `ANY` and untyped positions.
+ *
+ * `where` names the seam and the position (column / argument) and is quoted verbatim
+ * into the message — make it something a plugin author who has never read this code
+ * can act on, e.g. `` `module 'memory' scan of main.t column 2 (id)` ``.
+ */
+export function assertCanonicalValue(value, where) {
+    if (value === null || isCanonicalNumeric(value))
+        return;
+    throw new RepresentationError(`repr-strict: non-canonical numeric at ${where}: the bigint ${renderValue(value)} is inside the ` +
+        `safe-integer range and must be a JS number (rule R1). Return the canonical form — ` +
+        `\`canonicalizeInteger\` / \`canonicalizeSqlValue\` in util/numeric-canonical.ts do this. ${DOC_POINTER}`);
+}
+/**
+ * R2 for one value in a position of declared type `type` (implies R1).
+ * See {@link assertCanonicalValue} for what `where` should say.
+ */
+export function assertConformsToType(value, type, where) {
+    if (value === null)
+        return;
+    assertCanonicalValue(value, where);
+    if (conformsToType(value, type))
+        return;
+    throw new RepresentationError(`repr-strict: representation mismatch at ${where}: declared type ${type.name} admits ` +
+        `${admissibleForms(type)}, but the value is a JS ${jsTypeOf(value)} (${renderValue(value)}) ` +
+        `(rule R2). ${DOC_POINTER}`);
+}
+/**
+ * Row form of {@link assertConformsToType}. `types[i]` may be `undefined` — an ANY /
+ * untyped position, which is normal and gets R1 only, never a reported violation.
+ * A cell past the end of `types` is treated the same way.
+ *
+ * `columnNames[i]`, when supplied, is folded into the `where` text so the message
+ * names the column a plugin author declared rather than an ordinal.
+ */
+export function assertRowConforms(row, types, where, columnNames) {
+    for (let i = 0; i < row.length; i++) {
+        const name = columnNames?.[i];
+        const at = name ? `${where} column ${i} (${name})` : `${where} column ${i}`;
+        const type = types[i];
+        if (type === undefined) {
+            assertCanonicalValue(row[i], at);
+        }
+        else {
+            assertConformsToType(row[i], type, at);
+        }
+    }
+}
+//# sourceMappingURL=strict-representation.js.map

package/dist/src/runtime/strict-representation.js.map

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