@minnowdb/core 0.6.4 → 0.6.6

package/dist/engine/result-wire.d.ts

@@ -13,7 +13,7 @@ import type { QueryResult, QueryRow, QueryValue } from "./query.js";
  * a byte mask, and a column name like `__proto__` comes back as the own property the engine
  * defined — never as a prototype assignment.
  */
-export type WireResultColumn = {
+type WireResultColumn = {
     kind: "number";
     values: Float64Array;
     nulls?: Uint8Array;
@@ -67,3 +67,4 @@ export declare function encodeQueryResult(result: QueryResult): EncodedQueryResu
 export declare function encodeQueryRows(rows: readonly QueryRow[]): EncodedQueryResult;
 export declare function decodeQueryResult(payload: unknown): QueryResult;
 export declare function isWireQueryResult(value: unknown): value is WireQueryResult;
+export {};

package/dist/engine/schema.d.ts

@@ -55,6 +55,17 @@ export declare function foreignKeyName(tableName: string, columnName: string): s
 export type HasDefault<TValue> = TValue & {
     readonly __minnowHasDefault?: true;
 };
+/**
+ * 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 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;
@@ -179,8 +190,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

@@ -228,8 +228,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,10 +50,27 @@ 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;
 export declare function collatedDomainCompare(left: unknown, right: unknown): number | undefined;
+/**
+ * Renders one result value at the JavaScript boundary using its column's logical domain.
+ * A NUMERIC column with a declared scale displays PostgreSQL-style at exactly that scale:
+ * the physical encoding is canonical (trailing fractional zeros stripped), so the declared
+ * scale is restored by padding — never rounding — and a value carrying more fractional
+ * digits than the declaration keeps every digit it has. Every other domain, and every value
+ * without one, renders exactly as externalSqlDomainValue.
+ */
+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")
@@ -621,6 +697,29 @@ function collatorFor(locale, displayName) {
     collators.set(locale, created);
     return created;
 }
+/**
+ * Renders one result value at the JavaScript boundary using its column's logical domain.
+ * A NUMERIC column with a declared scale displays PostgreSQL-style at exactly that scale:
+ * the physical encoding is canonical (trailing fractional zeros stripped), so the declared
+ * scale is restored by padding — never rounding — and a value carrying more fractional
+ * digits than the declaration keeps every digit it has. Every other domain, and every value
+ * without one, renders exactly as externalSqlDomainValue.
+ */
+export function externalSqlDomainColumnValue(value, domain) {
+    if (domain?.kind === "numeric" &&
+        domain.scale !== undefined &&
+        domain.scale > 0 &&
+        typeof value === "string" &&
+        value.startsWith(NUMERIC)) {
+        const text = value.slice(NUMERIC.length);
+        const dot = text.indexOf(".");
+        const fractionDigits = dot === -1 ? 0 : text.length - dot - 1;
+        if (fractionDigits >= domain.scale)
+            return text;
+        return (dot === -1 ? `${text}.` : text) + "0".repeat(domain.scale - fractionDigits);
+    }
+    return externalSqlDomainValue(value);
+}
 export function externalSqlDomainValue(value) {
     if (typeof value !== "string")
         return value;
@@ -644,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

@@ -15,10 +15,20 @@ export declare function jsonAtPath(document: unknown, path: unknown, caller: str
     found: boolean;
     value?: unknown;
 };
+/**
+ * One step of PostgreSQL's `->`/`->>` access. A text key selects an object member; an integer
+ * key selects an array element, counting from the end when negative. The behaviour follows
+ * PostgreSQL's `json` type: a document of the wrong shape for the key selects nothing (NULL)
+ * rather than jsonb's scalar-as-one-element-array reading. Unlike the SQL/JSON functions, whose
+ * standard ON ERROR default swallows malformed documents, PostgreSQL's operators only exist on
+ * values already parsed as json, so a document that is not JSON is an error here.
+ */
+export declare function jsonArrowStep(document: unknown, key: unknown, caller: string): {
+    found: boolean;
+    value?: unknown;
+};
 /** 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

@@ -75,6 +75,46 @@ export function jsonAtPath(document, path, caller) {
     }
     return { found: true, value: current };
 }
+/**
+ * One step of PostgreSQL's `->`/`->>` access. A text key selects an object member; an integer
+ * key selects an array element, counting from the end when negative. The behaviour follows
+ * PostgreSQL's `json` type: a document of the wrong shape for the key selects nothing (NULL)
+ * rather than jsonb's scalar-as-one-element-array reading. Unlike the SQL/JSON functions, whose
+ * standard ON ERROR default swallows malformed documents, PostgreSQL's operators only exist on
+ * values already parsed as json, so a document that is not JSON is an error here.
+ */
+export function jsonArrowStep(document, key, caller) {
+    const source = boundedJsonDocument(document, caller);
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new TypeError(`${caller} requires a JSON document`);
+    }
+    const step = externalSqlDomainValue(key);
+    if (typeof step === "number") {
+        if (!Number.isInteger(step)) {
+            throw new TypeError(`${caller} array positions are integers`);
+        }
+        if (!Array.isArray(parsed))
+            return { found: false };
+        const index = step < 0 ? parsed.length + step : step;
+        if (index < 0 || index >= parsed.length)
+            return { found: false };
+        return { found: true, value: parsed[index] };
+    }
+    if (typeof step === "string") {
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return { found: false };
+        }
+        const members = parsed;
+        if (!Object.hasOwn(members, step))
+            return { found: false };
+        return { found: true, value: members[step] };
+    }
+    throw new TypeError(`${caller} keys are member names or array positions`);
+}
 /** Whether a value is JSON text of the requested shape (T825). */
 export function jsonIsValid(document, kind) {
     document = externalSqlDomainValue(document);
@@ -103,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/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

@@ -9,7 +9,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. */
@@ -892,6 +892,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 +4032,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 +4768,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

@@ -18,6 +18,10 @@ export type AggregateName = "COUNT" | "SUM" | "AVG" | "MIN" | "MAX" | "JSON_ARRA
 /** Optimizer-only aggregate that enforces scalar-subquery cardinality. */
  | "MINNOW_SINGLE_VALUE";
 export type ScalarFunctionName = "ROUND" | "COALESCE" | "DATE_TRUNC" | "DATE_ADD" | "UPPER" | "LOWER" | "LENGTH" | "ABS" | "TRIM" | "LTRIM" | "RTRIM" | "SUBSTR" | "REPLACE" | "INSTR" | "NULLIF" | "GREATEST" | "LEAST" | "FLOOR" | "CEIL" | "MOD" | "POWER" | "SQRT" | "EXTRACT" | "CAST" | "OCTET_LENGTH" | "LPAD" | "RPAD" | "OVERLAY" | "CURRENT_DATE" | "CURRENT_TIMESTAMP" | "LOCALTIME" | "GROUPING" | "JSON_VALUE" | "JSON_QUERY" | "JSON_EXISTS" | "JSON_OBJECT" | "JSON_ARRAY" | "IS_JSON" | "ARRAY"
+/** Parser-produced `->` JSON member/element access returning a JSON value. */
+ | "MINNOW_JSON_GET"
+/** Parser-produced `->>` JSON member/element access returning text. */
+ | "MINNOW_JSON_GET_TEXT"
 /** Optimizer-only, prefix-free equality key for hashable multi-column decorrelation. */
  | "MINNOW_TUPLE_KEY"
 /** Parser-produced wrapper carrying one explicit collation through ordering/comparison. */
@@ -36,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. */
  | {
@@ -64,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[];

package/dist/storage/opfs/leader.d.ts

@@ -4,8 +4,6 @@ import { type Placement } from "../toolkit/extents.js";
 /** A failed checkpoint may defer compaction, but the recovery log itself stays bounded. */
 export declare const MAX_OPFS_WAL_BYTES: number;
 export declare const MAX_OPFS_CHECKPOINT_BYTES: number;
-/** Failed physical reclamation cannot permit byte-growing work forever. */
-export declare const MAX_OPFS_CLEANUP_DEBT_BYTES: number;
 interface IdPlacement {
     id: string;
     placement: Placement;
@@ -459,6 +457,4 @@ export declare class OpfsLeader {
 export declare function assertBlockReadBatchByteLimit(placements: ReadonlyArray<{
     length: number;
 } | undefined>): void;
-/** Conservative retained-heap model for one decoded postings chunk and its nested arrays. */
-export declare function modeledFtsChunkBytes(chunk: readonly FtsPosting[]): number;
 export {};

package/dist/storage/opfs/leader.js

@@ -17,7 +17,7 @@ const CHECKPOINT_ENTRIES = 1024;
 export const MAX_OPFS_WAL_BYTES = 256 * 1024 * 1024;
 export const MAX_OPFS_CHECKPOINT_BYTES = 256 * 1024 * 1024;
 /** Failed physical reclamation cannot permit byte-growing work forever. */
-export const MAX_OPFS_CLEANUP_DEBT_BYTES = 64 * 1024 * 1024;
+const MAX_OPFS_CLEANUP_DEBT_BYTES = 64 * 1024 * 1024;
 /** Decoded full-text base cache: bounded primarily by modeled retained heap, count secondarily. */
 const FTS_CHUNK_CACHE_BYTES = 16 * 1024 * 1024;
 const FTS_CHUNK_CACHE_SIZE = 64;
@@ -5035,7 +5035,7 @@ function samePlacement(left, right) {
         left.checksum === right.checksum);
 }
 /** Conservative retained-heap model for one decoded postings chunk and its nested arrays. */
-export function modeledFtsChunkBytes(chunk) {
+function modeledFtsChunkBytes(chunk) {
     let bytes = 64;
     for (const posting of chunk) {
         bytes += 64 + posting.term.length * 2 + posting.rowIds.length * 40;

package/dist/storage/opfs/snapshot-ledger.d.ts

@@ -1,8 +1,8 @@
 import { type SnapshotFrame, type SnapshotFrameKind } from "../types.js";
 import { type Placement } from "../toolkit/extents.js";
 import { OpfsTree } from "./files.js";
-export type SnapshotLedgerKind = "export" | "import" | "completed";
-export interface SnapshotLedgerRecord {
+type SnapshotLedgerKind = "export" | "import" | "completed";
+interface SnapshotLedgerRecord {
     readonly sequence: number;
     readonly kind: SnapshotFrameKind;
     readonly itemCount: number;
@@ -38,3 +38,4 @@ export declare class SnapshotFrameLedger {
     adoptLength(length: number): void;
     close(): void;
 }
+export {};