@minnowdb/core 0.6.5 → 0.6.7

package/dist/engine/schema.d.ts

@@ -49,12 +49,16 @@ export interface TableForeignKey<TColumnName extends string = string> {
  */
 export declare function foreignKeyName(tableName: string, columnName: string): string;
 /**
- * A flavored value: a column whose slot the engine can fill, so inserts may omit it. The brand
- * is an optional phantom property — plain values stay assignable in both directions.
+ * A JSON column's select value carrying a declared document shape. The value is still JSON
+ * text — the brand is an optional phantom property, so plain strings stay assignable in both
+ * directions — and adapters read the shape to offer typed traversal. The tuple wrapper keeps
+ * `never` and union shapes intact through inference.
  */
-export type HasDefault<TValue> = TValue & {
-    readonly __minnowHasDefault?: true;
+export type JsonShape<TShape> = string & {
+    readonly __minnowJsonShape?: readonly [TShape];
 };
+/** A JSON column without a declared shape selects as exactly `string`, with no brand. */
+type JsonColumnValue<TShape> = [TShape] extends [never] ? string : JsonShape<TShape>;
 export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boolean, TUnique extends boolean = false, THasDefault extends boolean = false, TInput extends SchemaValue = TValue, TDomain extends SqlDomain["kind"] | undefined = undefined, TGenerated extends boolean = false> {
     readonly kind: "column";
     readonly type: SchemaColumnType;
@@ -160,11 +164,6 @@ interface AnyColumn {
     readonly renamedFromName?: string;
     readonly reference?: ColumnReferenceSpec;
 }
-/**
- * Rebuilds a column carrying an exact default spec — the wire layer's escape hatch, since the
- * public `.default()` accepts literals and cannot express auto-increment catalog metadata.
- */
-export declare function columnWithDefaultSpec(base: Pick<AnyColumn, "type" | "isNullable" | "isUnique" | "renamedFromName" | "reference" | "enumValues"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain">>, spec: ColumnDefault): AnyColumn;
 /** Rebuilds a fluent column from structured-clone-safe metadata. */
 export declare function columnFromState(state: Pick<AnyColumn, "type" | "isNullable" | "isUnique"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain" | "renamedFromName" | "reference" | "defaultSpec" | "generatedSpec" | "enumValues" | "backfillValue">>): AnyColumn;
 export declare const column: {
@@ -179,8 +178,13 @@ export declare const column: {
         precision?: number;
         scale?: number;
     }) => ColumnBuilder<string, false, false, false, string | number, "numeric", false>;
-    json: () => ColumnBuilder<string, false, false, false, string, "json", false>;
-    jsonb: () => ColumnBuilder<string, false, false, false, string, "jsonb", false>;
+    /**
+     * JSON text at the JavaScript boundary. Optionally declare the document's shape —
+     * `column.json<{ name: string }>()` — for adapters to type `->`/`->>` traversal; the runtime
+     * value stays JSON text either way.
+     */
+    json: <TShape = never>() => ColumnBuilder<JsonColumnValue<TShape>, false, false, false, string, "json", false>;
+    jsonb: <TShape = never>() => ColumnBuilder<JsonColumnValue<TShape>, false, false, false, string, "jsonb", false>;
     uuid: () => ColumnBuilder<string, false, false, false, string, "uuid", false>;
     /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
     date: () => ColumnBuilder<string, false, false, false, string, "date", false>;

package/dist/engine/schema.js

@@ -184,23 +184,6 @@ function validateSchemaName(name, kind) {
         throw new TypeError(`${kind} name cannot start or end with whitespace: ${JSON.stringify(name)}`);
     }
 }
-/**
- * Rebuilds a column carrying an exact default spec — the wire layer's escape hatch, since the
- * public `.default()` accepts literals and cannot express auto-increment catalog metadata.
- */
-export function columnWithDefaultSpec(base, spec) {
-    return columnFromState({
-        type: base.type,
-        isNullable: base.isNullable,
-        isUnique: base.isUnique,
-        integer: base.integer ?? false,
-        ...(base.sqlDomain === undefined ? {} : { sqlDomain: base.sqlDomain }),
-        ...(base.renamedFromName === undefined ? {} : { renamedFromName: base.renamedFromName }),
-        ...(base.reference === undefined ? {} : { reference: base.reference }),
-        ...(base.enumValues === undefined ? {} : { enumValues: base.enumValues }),
-        defaultSpec: spec,
-    });
-}
 /** Rebuilds a fluent column from structured-clone-safe metadata. */
 export function columnFromState(state) {
     return createColumn(state.type, {
@@ -228,8 +211,17 @@ export const column = {
         const sqlDomain = validateSqlDomain({ kind: "numeric", ...options }, "numeric column");
         return createColumn("string", { sqlDomain });
     },
-    json: () => createColumn("string", { sqlDomain: { kind: "json" } }),
-    jsonb: () => createColumn("string", { sqlDomain: { kind: "jsonb" } }),
+    /**
+     * JSON text at the JavaScript boundary. Optionally declare the document's shape —
+     * `column.json<{ name: string }>()` — for adapters to type `->`/`->>` traversal; the runtime
+     * value stays JSON text either way.
+     */
+    json: () => createColumn("string", {
+        sqlDomain: { kind: "json" },
+    }),
+    jsonb: () => createColumn("string", {
+        sqlDomain: { kind: "jsonb" },
+    }),
     uuid: () => createColumn("string", { sqlDomain: { kind: "uuid" } }),
     /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
     date: () => createColumn("string", { sqlDomain: { kind: "date" } }),

package/dist/engine/sort-keys.d.ts

@@ -19,7 +19,7 @@
  * next, so what a multi-term sort pays for its later terms is proportional to how many rows tie
  * on the earlier ones.
  */
-export interface SortKeyColumn {
+interface SortKeyColumn {
     /**
      * Ascending comparison with NULL smallest. This is the column's raw comparison, not SQL's
      * default placement: the sorter applies PostgreSQL's NULLS LAST for ASC and NULLS FIRST for
@@ -45,8 +45,6 @@ export interface SortKeyTerm {
     readonly descending: boolean;
     readonly nulls: "first" | "last" | undefined;
 }
-/** Unwraps a datetime to the number the comparisons use; every other value passes through. */
-export declare function comparableSortValue(value: unknown): unknown;
 /**
  * Extracts one term's values into a comparison-ready column. `valueAt` is called once per row,
  * so a caller that reads through a row object or a vector pays that cost once rather than once
@@ -72,3 +70,4 @@ export declare function buildSortKeyColumn(count: number, valueAt: (index: numbe
  * is already in order before doing anything else, since a scan often arrives sorted.
  */
 export declare function sortKeyIndexes(count: number, terms: readonly SortKeyTerm[]): Uint32Array;
+export {};

package/dist/engine/sort-keys.js

@@ -1,7 +1,7 @@
 import { dateMilliseconds } from "../date-value.js";
 import { compareSqlStrings, compareSqlValues } from "./sql-semantics.js";
 /** Unwraps a datetime to the number the comparisons use; every other value passes through. */
-export function comparableSortValue(value) {
+function comparableSortValue(value) {
     return value instanceof Date ? dateMilliseconds(value) : value;
 }
 /**

package/dist/engine/sql-domains.d.ts

@@ -9,7 +9,24 @@ export declare function protectedSqlTextValue(value: string): string;
 export declare function externalSqlTextValue(value: unknown): unknown;
 export declare function isExactNumeric(value: unknown): value is string;
 export declare function exactNumericValue(value: unknown, precision?: number, scale?: number): string | null;
-export declare function exactNumericBinary(operator: "+" | "-" | "*" | "/" | "%", left: unknown, right: unknown): string | null | undefined;
+/**
+ * Tags a SQL numeric constant with its exact digits, as written. Unlike `exactNumericValue`
+ * this does not canonicalize: trailing fractional zeros are PostgreSQL display scale, and
+ * division selects its result scale from the operands' scales, so a literal's digits are part
+ * of its meaning. Scientific notation is the exception — PostgreSQL expands the exponent when
+ * it parses the literal, so `1.5e2` is `150` and `1e400` is the full digit string, and the
+ * display scale comes from that expansion. The text is still validated and bounded.
+ */
+export declare function exactNumericLiteral(text: string): string;
+/**
+ * The Float64 this exact numeric value reads back identically from — the nearest float's
+ * canonical rendering re-parses to the same decimal value, so `0.1` qualifies while
+ * `9007199254740993` does not — or undefined when the trip through a number would visibly
+ * round. A value that survives stays an ordinary number so every number-typed path keeps
+ * running; only visibly rounded values stay tagged NUMERIC.
+ */
+export declare function exactNumericAsNumber(value: string): number | undefined;
+export declare function exactNumericBinary(operator: "+" | "-" | "*" | "/" | "%", left: unknown, right: unknown, minimumQuotientScale?: number, canonicalize?: boolean): string | null | undefined;
 export declare function exactNumericCompare(left: unknown, right: unknown): number | undefined;
 /**
  * Serializes a JSON value while bounding traversal, nesting, and output before concatenation.
@@ -33,7 +50,6 @@ export declare function isDateDomainValue(value: unknown): value is string;
 export declare function timeDomainValue(value: unknown): string | null;
 export declare function intervalDomainValue(value: unknown): string | null;
 export declare function arrayDomainValue(values: readonly unknown[]): string;
-export declare function enumDomainValue(value: unknown, name: string, values: readonly string[]): string | null;
 export declare function enumDomainCompare(left: unknown, right: unknown): number | undefined;
 export declare function normalizeSqlDomainValue(domain: SqlDomain, value: unknown): string | null;
 export declare function collatedDomainValue(value: unknown, collation: unknown): string | null;
@@ -48,4 +64,13 @@ export declare function collatedDomainCompare(left: unknown, right: unknown): nu
  */
 export declare function externalSqlDomainColumnValue(value: unknown, domain: SqlDomain | null | undefined): unknown;
 export declare function externalSqlDomainValue(value: unknown): unknown;
+/**
+ * SQL `||` over internal string values, shared by both executors and constant folding so the
+ * three paths cannot disagree. PostgreSQL resolves `||` to text concatenation only when one
+ * side is text: its array and JSONB `||` operators are structural concatenation, which this
+ * engine does not implement, and two non-text operands have no `||` operator at all. Refusing
+ * those shapes keeps `||` from inventing a text concatenation PostgreSQL does not have —
+ * and from ever concatenating internal domain encodings.
+ */
+export declare function concatenatedSqlValue(left: string, right: string): string;
 export declare function isSqlDomainValue(value: unknown): value is string;

package/dist/engine/sql-domains.js

@@ -53,6 +53,9 @@ function decimalParts(value) {
     let coefficient = BigInt(digits || "0") * (match[1] === "-" ? -1n : 1n);
     let scale = fraction.length - exponent;
     if (scale < 0) {
+        if (-scale > 100_000) {
+            throw new RangeError(`NUMERIC exponent is outside the supported range: ${source}`);
+        }
         coefficient *= pow10(-scale);
         scale = 0;
     }
@@ -122,7 +125,79 @@ export function exactNumericValue(value, precision, scale) {
     }
     return boundedTaggedDomainValue(NUMERIC, formatDecimal(normalizeDecimal(adjusted)), "NUMERIC value");
 }
-export function exactNumericBinary(operator, left, right) {
+/**
+ * Tags a SQL numeric constant with its exact digits, as written. Unlike `exactNumericValue`
+ * this does not canonicalize: trailing fractional zeros are PostgreSQL display scale, and
+ * division selects its result scale from the operands' scales, so a literal's digits are part
+ * of its meaning. Scientific notation is the exception — PostgreSQL expands the exponent when
+ * it parses the literal, so `1.5e2` is `150` and `1e400` is the full digit string, and the
+ * display scale comes from that expansion. The text is still validated and bounded.
+ */
+export function exactNumericLiteral(text) {
+    const parts = decimalParts(text);
+    const plain = /[eE]/.test(text) ? formatDecimal(parts) : text;
+    return boundedTaggedDomainValue(NUMERIC, plain, "NUMERIC literal");
+}
+/**
+ * The Float64 this exact numeric value reads back identically from — the nearest float's
+ * canonical rendering re-parses to the same decimal value, so `0.1` qualifies while
+ * `9007199254740993` does not — or undefined when the trip through a number would visibly
+ * round. A value that survives stays an ordinary number so every number-typed path keeps
+ * running; only visibly rounded values stay tagged NUMERIC.
+ */
+export function exactNumericAsNumber(value) {
+    const parts = taggedDecimalParts(value);
+    if (parts === undefined)
+        return undefined;
+    const candidate = Number(value.slice(NUMERIC.length));
+    if (!Number.isFinite(candidate))
+        return undefined;
+    const roundTrip = normalizeDecimal(decimalParts(String(candidate)));
+    const exact = normalizeDecimal(parts);
+    return roundTrip.coefficient === exact.coefficient && roundTrip.scale === exact.scale
+        ? candidate
+        : undefined;
+}
+/**
+ * The leading base-10000 digit of a decimal, aligned at the decimal point the way PostgreSQL's
+ * NUMERIC digit array is: group k covers the decimal digits at 10^(4k)..10^(4k+3). `weight` is
+ * the group index of the first nonzero group and `firstDigit` its value (1..9999); zero reports
+ * both as 0, matching PostgreSQL's defaults when no nonzero digit exists.
+ */
+function nbaseLeading(parts) {
+    const magnitude = parts.coefficient < 0n ? -parts.coefficient : parts.coefficient;
+    if (magnitude === 0n)
+        return { weight: 0, firstDigit: 0 };
+    const fractionGroups = Math.ceil(parts.scale / 4);
+    const aligned = magnitude * pow10(fractionGroups * 4 - parts.scale);
+    const groups = Math.ceil(aligned.toString().length / 4);
+    return {
+        weight: groups - 1 - fractionGroups,
+        firstDigit: Number(aligned / pow10((groups - 1) * 4)),
+    };
+}
+/**
+ * PostgreSQL's `select_div_scale`: the fractional digits a NUMERIC quotient is computed and
+ * rounded to. The estimated quotient weight guarantees roughly sixteen significant digits, and
+ * the result never displays fewer fractional digits than either operand. `minimumScale` stands
+ * in for display scale the canonical encoding cannot carry: PostgreSQL floors this selection at
+ * each operand's dscale, which for an AVG over a declared-scale column is that declared scale.
+ */
+function quotientScale(a, b, minimumScale) {
+    const leftLeading = nbaseLeading(a);
+    const rightLeading = nbaseLeading(b);
+    let estimatedWeight = leftLeading.weight - rightLeading.weight;
+    if (leftLeading.firstDigit <= rightLeading.firstDigit)
+        estimatedWeight -= 1;
+    const scale = Math.max(16 - estimatedWeight * 4, a.scale, b.scale, minimumScale, 0);
+    return Math.min(scale, 1000);
+}
+export function exactNumericBinary(operator, left, right, minimumQuotientScale = 0, 
+// Stored and returned values are canonical (trailing fractional zeros stripped). Constant
+// folding keeps the computed scale instead: PostgreSQL carries display scale through each
+// step — max for +, -, %, the operands' sum for *, the selected scale for / — and a later
+// division selects its own scale from it, so folding must not strip what execution never sees.
+canonicalize = true) {
     const leftTagged = taggedDecimalParts(left);
     const rightTagged = taggedDecimalParts(right);
     if (leftTagged === undefined && rightTagged === undefined)
@@ -149,9 +224,10 @@ export function exactNumericBinary(operator, left, right) {
         };
     }
     else {
-        // PostgreSQL NUMERIC division is arbitrary precision. Twenty fractional digits gives a
-        // deterministic exact decimal rounding boundary without ever crossing binary Float64.
-        const scale = Math.max(20, a.scale, b.scale);
+        // PostgreSQL NUMERIC division computes to its selected result scale and rounds the final
+        // digit half away from zero; matching the scale selection keeps every rendered digit in
+        // agreement, deterministically and without ever crossing binary Float64.
+        const scale = quotientScale(a, b, minimumQuotientScale);
         const numerator = a.coefficient * pow10(scale + b.scale);
         const denominator = b.coefficient * pow10(a.scale);
         let coefficient = numerator / denominator;
@@ -162,7 +238,7 @@ export function exactNumericBinary(operator, left, right) {
         }
         result = { coefficient, scale };
     }
-    return boundedTaggedDomainValue(NUMERIC, formatDecimal(normalizeDecimal(result)), "NUMERIC result");
+    return boundedTaggedDomainValue(NUMERIC, formatDecimal(canonicalize ? normalizeDecimal(result) : result), "NUMERIC result");
 }
 export function exactNumericCompare(left, right) {
     const leftTagged = taggedDecimalParts(left);
@@ -470,7 +546,7 @@ export function intervalDomainValue(value) {
 export function arrayDomainValue(values) {
     return boundedTaggedDomainValue(ARRAY_VALUE, boundedJsonText(values.map(externalSqlDomainValue), true, "ARRAY value"), "ARRAY value");
 }
-export function enumDomainValue(value, name, values) {
+function enumDomainValue(value, name, values) {
     if (value === null || value === undefined)
         return null;
     if (typeof value !== "string")
@@ -667,6 +743,44 @@ export function externalSqlDomainValue(value) {
     }
     return value;
 }
+/**
+ * The domain kind carried by an internal string value, or undefined for ordinary text. The
+ * protected-TEXT wrapper and collated text are both ordinary text to PostgreSQL's operator
+ * resolution, so they report no kind.
+ */
+function concatenationDomainKind(value) {
+    if (!value.startsWith(PREFIX))
+        return undefined;
+    if (value.startsWith(TEXT_VALUE) || value.startsWith(COLLATION_VALUE))
+        return undefined;
+    const rest = value.slice(PREFIX.length);
+    const colon = rest.indexOf(":");
+    return colon === -1 ? undefined : rest.slice(0, colon);
+}
+/**
+ * SQL `||` over internal string values, shared by both executors and constant folding so the
+ * three paths cannot disagree. PostgreSQL resolves `||` to text concatenation only when one
+ * side is text: its array and JSONB `||` operators are structural concatenation, which this
+ * engine does not implement, and two non-text operands have no `||` operator at all. Refusing
+ * those shapes keeps `||` from inventing a text concatenation PostgreSQL does not have —
+ * and from ever concatenating internal domain encodings.
+ */
+export function concatenatedSqlValue(left, right) {
+    const leftKind = concatenationDomainKind(left);
+    const rightKind = concatenationDomainKind(right);
+    for (const kind of [leftKind, rightKind]) {
+        if (kind === "array") {
+            throw new TypeError("PostgreSQL array concatenation (||) is not supported");
+        }
+        if (kind === "jsonb") {
+            throw new TypeError("PostgreSQL JSONB concatenation (||) is not supported");
+        }
+    }
+    if (leftKind !== undefined && rightKind !== undefined) {
+        throw new TypeError(`No || operator for ${leftKind} and ${rightKind} values`);
+    }
+    return protectedSqlTextValue(String(externalSqlDomainValue(left)) + String(externalSqlDomainValue(right)));
+}
 export function isSqlDomainValue(value) {
     return typeof value === "string" && value.startsWith(PREFIX);
 }

package/dist/engine/sql-json.d.ts

@@ -29,8 +29,6 @@ export declare function jsonArrowStep(document: unknown, key: unknown, caller: s
 };
 /** Whether a value is JSON text of the requested shape (T825). */
 export declare function jsonIsValid(document: unknown, kind: string): boolean;
-/** A SQL value as its JSON counterpart: datetimes serialize as ISO text, like every cast. */
-export declare function jsonValueOf(value: unknown): unknown;
 /**
  * JSON_ARRAY(v, ...) and JSON_OBJECT(k, v, ...) (T811/T812). The omitted null-handling clause is
  * `NULL ON NULL`: SQL NULL becomes a JSON null. `ABSENT ON NULL` is a separate spelling rather

package/dist/engine/sql-json.js

@@ -143,7 +143,7 @@ export function jsonIsValid(document, kind) {
     }
 }
 /** A SQL value as its JSON counterpart: datetimes serialize as ISO text, like every cast. */
-export function jsonValueOf(value) {
+function jsonValueOf(value) {
     const external = externalSqlDomainValue(value);
     return external instanceof Date ? dateIsoString(external) : external;
 }

package/dist/engine/sql-semantics.d.ts

@@ -19,7 +19,7 @@ export declare function encodeSqlEqualityValue(value: unknown): readonly unknown
  */
 export declare function roundSqlNumber(value: number, precision?: number): number;
 /** A whole-string SQL pattern matcher. Unlike RegExp, test never coerces its input. */
-export interface SqlPatternMatcher {
+interface SqlPatternMatcher {
     test(value: string): boolean;
 }
 /** Compiles SQL LIKE without exposing input to the host regular-expression engine. */
@@ -34,3 +34,4 @@ export declare function defineSqlResultProperty(target: Record<string, unknown>,
  * a silent coercion here would make `LENGTH(42)` answer instead of failing.
  */
 export declare function stringArgument(name: string, value: unknown): string;
+export {};

package/dist/engine/typed-live.js

@@ -1,42 +1,4 @@
-import { dateMilliseconds } from "../date-value.js";
-function sameLiveValue(left, right) {
-    if (Object.is(left, right))
-        return true;
-    if (left instanceof Date || right instanceof Date) {
-        return (left instanceof Date &&
-            right instanceof Date &&
-            Object.is(dateMilliseconds(left), dateMilliseconds(right)));
-    }
-    if (Array.isArray(left) || Array.isArray(right)) {
-        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
-            return false;
-        for (let index = 0; index < left.length; index += 1) {
-            if (!sameLiveValue(left[index], right[index]))
-                return false;
-        }
-        return true;
-    }
-    if (typeof left !== "object" || left === null || typeof right !== "object" || right === null) {
-        return false;
-    }
-    const leftRecord = left;
-    const rightRecord = right;
-    const leftKeys = Object.keys(leftRecord);
-    const rightKeys = Object.keys(rightRecord);
-    if (leftKeys.length !== rightKeys.length)
-        return false;
-    for (let index = 0; index < leftKeys.length; index += 1) {
-        const key = leftKeys[index];
-        if (key === undefined || key !== rightKeys[index])
-            return false;
-        if (!sameLiveValue(leftRecord[key], rightRecord[key]))
-            return false;
-    }
-    return true;
-}
-function sameRows(left, right) {
-    return sameLiveValue(left, right);
-}
+import { sameLiveValue } from "./live-equal.js";
 function immutableRows(rows) {
     // Adapters own their values. Copy the array so mutating the returned builder result cannot
     // change the snapshot identity retained for exact suppression.
@@ -191,10 +153,10 @@ export class LiveQuery {
                 const previous = this.#snapshot.rows;
                 if (this.#snapshot.status === "ready" &&
                     this.#snapshot.version === invalidation.manifestVersion &&
-                    sameRows(previous, rows)) {
+                    sameLiveValue(previous, rows)) {
                     continue;
                 }
-                if (sameRows(previous, rows) && this.#snapshot.status !== "loading") {
+                if (sameLiveValue(previous, rows) && this.#snapshot.status !== "loading") {
                     // Advance the version without replacing the immutable row array.
                     this.#snapshot = {
                         status: "ready",

package/dist/engine/vector.d.ts

@@ -2,7 +2,7 @@ import type { DatabaseRow } from "./database.js";
 import type { CompiledQuery, QueryResult, QueryValue } from "./query.js";
 import { type FtsStats } from "./fts.js";
 import { QueryMemoryContext, type QueryMemoryUsage } from "./memory.js";
-export type VectorType = "boolean" | "number" | "string" | "datetime";
+type VectorType = "boolean" | "number" | "string" | "datetime";
 /**
  * A resident slice of a logically longer streamed column. Window arrays index rows relative to
  * `start`; `length` on the vector remains the logical table length.
@@ -16,25 +16,25 @@ interface VectorBase {
     readonly length: number;
     readonly window?: VectorWindow;
 }
-export interface BooleanVector extends VectorBase {
+interface BooleanVector extends VectorBase {
     readonly kind: "boolean";
     readonly values: Uint8Array;
 }
-export interface NumberVector extends VectorBase {
+interface NumberVector extends VectorBase {
     readonly kind: "number";
     readonly values: Float64Array;
 }
-export interface DateTimeVector extends VectorBase {
+interface DateTimeVector extends VectorBase {
     readonly kind: "datetime";
     readonly values: Float64Array;
 }
-export interface StringVector extends VectorBase {
+interface StringVector extends VectorBase {
     readonly kind: "string";
     readonly codes: Uint32Array;
     readonly dictionary: readonly string[];
 }
 export type ColumnVector = BooleanVector | NumberVector | DateTimeVector | StringVector;
-export interface ColumnarColumnInput {
+interface ColumnarColumnInput {
     readonly type: VectorType;
     readonly values: readonly QueryValue[];
 }
@@ -91,7 +91,7 @@ export interface QueryBatchExecutionOptions extends AsyncQueryExecutionOptions {
     /** Maximum result rows handed to the consumer at once. */
     readonly batchRows: number;
 }
-export interface PrepareVectorQueryOptions {
+interface PrepareVectorQueryOptions {
     readonly memoryContext?: QueryMemoryContext;
     /**
      * Exact BM25 corpus statistics served by the persisted full-text index, keyed by each

package/dist/engine/vector.js

@@ -1,4 +1,5 @@
 import { dateMilliseconds } from "../date-value.js";
+import { crossJoinPlan, isCrossJoinPlan } from "../plan/model.js";
 import { MAX_TEMP_RUN_BATCH_BYTES, MAX_TEMP_RUN_PAGE_BYTES, MAX_TEMP_RUN_PAGES_PER_BATCH, } from "../storage/types.js";
 import { throwIfAborted } from "./cancellation.js";
 import { cachedListMembership, childExpressions, distinctFromComparison, nullOrder, isScalarFunctionName, likeMatches, orderOutputName, parseQuantified, quantifiedComparison, scalarFunctionValue, unknownColumnDomains, } from "./query.js";
@@ -9,7 +10,7 @@ import { ByteJoinIndex } from "./join-index.js";
 import { UnknownTableError } from "./errors.js";
 import { QueryMemoryBudgetError, QueryMemoryContext, } from "./memory.js";
 import { compareSqlValues, compileSimilarPattern, defineSqlResultProperty, } from "./sql-semantics.js";
-import { exactNumericBinary, externalSqlDomainValue, isDateDomainValue, isExactNumeric, preservedJsonDomainValue, protectedSqlTextValue, } from "./sql-domains.js";
+import { concatenatedSqlValue, exactNumericBinary, externalSqlDomainValue, isDateDomainValue, isExactNumeric, preservedJsonDomainValue, protectedSqlTextValue, } from "./sql-domains.js";
 import { buildSortKeyColumn, sortKeyIndexes } from "./sort-keys.js";
 const DEFAULT_BATCH_ROWS = 2_048;
 /** Above this, locating each IN member separately costs more than scanning between them. */
@@ -409,7 +410,7 @@ function disjunctiveNormalForm(predicate) {
 function orderCartesianJoins(plan, tables) {
     if (plan.joins.length < 2 ||
         plan.select.some((item) => item.expression.kind === "wildcard") ||
-        plan.joins.some((join) => !isCartesianJoin(join))) {
+        plan.joins.some((join) => !isCrossJoinPlan(join))) {
         return plan;
     }
     const entries = [
@@ -454,21 +455,11 @@ function orderCartesianJoins(plan, tables) {
             return plan;
         const keyIndex = predicates.findIndex((predicate) => predicateJoinsSource(predicate, sourceIndex, available, entries, sourceTables));
         const key = keyIndex < 0 ? undefined : predicates.splice(keyIndex, 1)[0];
-        joins.push(key === undefined ? cartesianJoin(source) : keyedInnerJoin(source, key));
+        joins.push(key === undefined ? crossJoinPlan(source) : keyedInnerJoin(source, key));
         available.add(sourceIndex);
     }
     return { ...plan, base: plan.base, joins, predicates };
 }
-function isCartesianJoin(join) {
-    const condition = join.on;
-    return (join.kind === "inner" &&
-        condition?.kind === "condition" &&
-        condition.operator === "=" &&
-        condition.left.kind === "literal" &&
-        condition.left.value === 1 &&
-        condition.right.kind === "literal" &&
-        condition.right.value === 1);
-}
 function tableSourceOf(join) {
     const { kind, left, right, on, full, natural, ...source } = join;
     void kind;
@@ -479,20 +470,6 @@ function tableSourceOf(join) {
     void natural;
     return source;
 }
-function cartesianJoin(source) {
-    return {
-        ...source,
-        kind: "inner",
-        left: { kind: "literal", value: null },
-        right: { kind: "literal", value: null },
-        on: {
-            kind: "condition",
-            operator: "=",
-            left: { kind: "literal", value: 1 },
-            right: { kind: "literal", value: 1 },
-        },
-    };
-}
 function keyedInnerJoin(source, predicate) {
     return {
         ...source,
@@ -892,6 +869,9 @@ function bindExpression(expression, sources, aggregateSpecs, aggregateIndexes, m
             ...(expression.distinct === true ? { distinct: true } : {}),
             ...(rawDatetime === undefined ? {} : { rawDatetime }),
             ...(rawNumber === undefined ? {} : { rawNumber }),
+            ...(expression.avgArgumentScale === undefined
+                ? {}
+                : { avgScale: expression.avgArgumentScale }),
         });
     }
     return {
@@ -4029,8 +4009,9 @@ function evaluateFinalExpression(plan, expression, group) {
     if (expression.name === "SUM")
         return isExactNumeric(value) ? value : (group.sums[aggregateIndex] ?? 0);
     if (expression.name === "AVG") {
-        if (isExactNumeric(value))
-            return exactNumericBinary("/", value, count);
+        if (isExactNumeric(value)) {
+            return exactNumericBinary("/", value, count, plan.aggregates[aggregateIndex]?.avgScale);
+        }
         return (group.sums[aggregateIndex] ?? 0) / count;
     }
     // Raw-millisecond datetime extremes re-box into a Date only here, once per surviving group.
@@ -4764,7 +4745,7 @@ function binaryValue(operator, left, right) {
         if (typeof left !== "string" || typeof right !== "string") {
             throw new TypeError("|| requires string operands");
         }
-        return protectedSqlTextValue(String(externalSqlDomainValue(left)) + String(externalSqlDomainValue(right)));
+        return concatenatedSqlValue(left, right);
     }
     const exact = exactNumericBinary(operator, left, right);
     if (exact !== undefined)

package/dist/engine/write-block-planner.d.ts

@@ -4,7 +4,7 @@ export interface WriteColumnValues {
     readonly values: readonly unknown[];
     readonly stringByteLengths?: readonly number[];
 }
-export interface WriteBlockRange {
+interface WriteBlockRange {
     readonly start: number;
     readonly end: number;
 }
@@ -16,3 +16,4 @@ export interface WriteBlockRange {
 export declare function planAlignedWriteBlockRanges(columns: readonly WriteColumnValues[], rowCount: number, maximumRows: number, targetBytes: number, measureString?: (value: string) => number): WriteBlockRange[];
 /** Conservative first estimate used by both physical compaction planners. */
 export declare function estimateCompactionRowsPerOutput(targetBlockBytes: number, maximumEncodedBytesPerRow: number): number;
+export {};

package/dist/plan/model.d.ts

@@ -40,6 +40,14 @@ export type Expression = {
     value: QueryValue;
     internalSqlValue?: true;
     sqlDomain?: SqlDomain;
+    /**
+     * A numeric constant's exact source digits, kept when the value survives the number
+     * boundary but the spelling carries more (`1.000000000000000000000000` is the number 1
+     * with display scale 24).
+     * Constant folding reads these so seeded arithmetic runs in exact decimal space, the way
+     * PostgreSQL types every decimal constant NUMERIC before evaluating it.
+     */
+    exactText?: string;
 }
 /** A `?` or `$n` placeholder; `index` is 0-based. Replaced by a literal at bind time. */
  | {
@@ -68,6 +76,13 @@ export type Expression = {
         direction: "asc" | "desc";
         nulls?: "first" | "last";
     }>;
+    /**
+     * AVG over a declared-scale NUMERIC column: the argument's declared scale, annotated by a
+     * schema-aware pass before execution. PostgreSQL floors its quotient scale at the summed
+     * operand's display scale; canonical NUMERIC encoding strips trailing zeros, so without
+     * this the internal division cannot know the digits the declared scale will render.
+     */
+    avgArgumentScale?: number;
 } | {
     kind: "list";
     items: Expression[];
@@ -175,6 +190,13 @@ export interface JoinPlan extends TableSource {
     full?: boolean;
     natural?: boolean;
 }
+/**
+ * A cross join rides the nested-loop inner-join path with a condition every row pair satisfies:
+ * 1 = 1 over null literal key expressions. Producers build the shape with crossJoinPlan and
+ * consumers recognize it with isCrossJoinPlan, so the encoding lives in exactly one place.
+ */
+export declare function crossJoinPlan(source: TableSource): JoinPlan;
+export declare function isCrossJoinPlan(join: JoinPlan): boolean;
 export type SetOperator = "union" | "union all" | "intersect" | "intersect all" | "except" | "except all";
 export interface RecursiveCte {
     reference: string;