@laserdata/laser-sdk 0.1.1 → 0.2.1

package/dist/wire/query.js

@@ -1,48 +1,79 @@
-import { CodecError } from "../client/errors.js";
-import { encodeNamed, expectMap, expectString, field, singleVariantTag } from "./cbor.js";
+import { CodecError, InvalidError } from "../client/errors.js";
+import { decodeOne, encodeNamed, expectMap, expectString, field, singleVariantTag } from "./cbor.js";
+import { BackendResourceId, DestinationId, QueryExecutionId } from "./ids.js";
+import { decodeLogicalField, decodeTypedValue, encodeLogicalField, encodeTypedValue, validateResultFields, validateTypedValueAgainst, validateTypedValue } from "./schema.js";
+import { MAX_PAGE_SIZE, MAX_QUERY_CURSOR_BYTES, MAX_QUERY_FIELDS, MAX_QUERY_NAME_BYTES, MAX_QUERY_PARAMETERS, MAX_QUERY_PREDICATES, MAX_RAW_SQL_BYTES, MAX_TEXT_QUERY_BYTES, MAX_VECTOR_DIMENSIONS } from "./limits.js";
 import { QUERY_OP_VERSION } from "./codes.js";
-import { decodeValue, encodeValue } from "./value.js";
-export function encodeKeyMatch(match) {
-    return new Map([
-        ["field", match.field],
-        ["value", match.value]
+export function encodeQueryPageEnvelope(value) {
+    return mapOf([
+        ["v", value.v],
+        ["execution_id", value.executionId.toBytes()],
+        ["cursor", value.cursor],
+        ["deadline_micros", value.deadlineMicros]
     ]);
 }
-export function decodeKeyMatch(map, context) {
+export function encodeQueryCancelEnvelope(value) {
+    return mapOf([
+        ["v", value.v],
+        ["execution_id", value.executionId.toBytes()]
+    ]);
+}
+export function encodeQueryStatusEnvelope(value) {
+    return mapOf([
+        ["v", value.v],
+        ["execution_id", value.executionId.toBytes()]
+    ]);
+}
+export function decodeQueryPageEnvelope(map, context) {
     return {
-        field: field.requiredString(map, "field", context),
-        value: field.requiredString(map, "value", context)
+        v: field.requiredU32(map, "v", context),
+        executionId: QueryExecutionId.fromBytes(field.requiredBytes(map, "execution_id", context)),
+        cursor: field.requiredString(map, "cursor", context),
+        deadlineMicros: field.requiredU64(map, "deadline_micros", context)
     };
 }
-const CMP_OPS = new Set([
-    "eq",
-    "ne",
-    "lt",
-    "lte",
-    "gt",
-    "gte",
-    "in",
-    "contains",
-    "prefix"
-]);
-function parseCmpOp(word, context) {
-    if (!CMP_OPS.has(word)) {
-        throw new CodecError(`\`${word}\` is not a recognized comparison operator`, context, "op");
-    }
-    return word;
+export function decodeQueryCancelEnvelope(map, context) {
+    return {
+        v: field.requiredU32(map, "v", context),
+        executionId: QueryExecutionId.fromBytes(field.requiredBytes(map, "execution_id", context))
+    };
 }
-export function encodePredicate(predicate) {
-    return new Map([
-        ["field", predicate.field],
-        ["op", predicate.op],
-        ["value", encodeValue(predicate.value)]
-    ]);
+export function decodeQueryStatusEnvelope(map, context) {
+    return {
+        v: field.requiredU32(map, "v", context),
+        executionId: QueryExecutionId.fromBytes(field.requiredBytes(map, "execution_id", context))
+    };
+}
+export function encodeQueryPageEnvelopeFrame(value) {
+    return encodeNamed(encodeQueryPageEnvelope(value));
+}
+export function encodeQueryCancelEnvelopeFrame(value) {
+    return encodeNamed(encodeQueryCancelEnvelope(value));
+}
+export function encodeQueryStatusEnvelopeFrame(value) {
+    return encodeNamed(encodeQueryStatusEnvelope(value));
 }
-export function decodePredicate(map, context) {
+export function decodeQueryPageEnvelopeFrame(bytes) {
+    const context = "QueryPageEnvelope";
+    return decodeQueryPageEnvelope(expectMap(decodeOne(bytes, context), context), context);
+}
+export function decodeQueryCancelEnvelopeFrame(bytes) {
+    const context = "QueryCancelEnvelope";
+    return decodeQueryCancelEnvelope(expectMap(decodeOne(bytes, context), context), context);
+}
+export function decodeQueryStatusEnvelopeFrame(bytes) {
+    const context = "QueryStatusEnvelope";
+    return decodeQueryStatusEnvelope(expectMap(decodeOne(bytes, context), context), context);
+}
+export function operationalTarget(index) {
+    return { kind: "operational", index };
+}
+export function lakehouseTarget(destinationId, destinationGeneration, snapshot) {
     return {
-        field: field.requiredString(map, "field", context),
-        op: parseCmpOp(field.requiredString(map, "op", context), context),
-        value: decodeValue(map.get("value"), `${context}.value`)
+        kind: "lakehouse",
+        destinationId,
+        destinationGeneration,
+        ...(snapshot === undefined ? {} : { snapshot })
     };
 }
 export function filterAll(filters) {
@@ -57,542 +88,1036 @@ export function filterNegate(filter) {
 export function filterPred(fieldName, op, value) {
     return { kind: "pred", predicate: { field: fieldName, op, value } };
 }
-export function encodeFilter(filter) {
-    switch (filter.kind) {
-        case "all":
-            return new Map([["all", filter.filters.map((child) => encodeFilter(child))]]);
-        case "any":
-            return new Map([["any", filter.filters.map((child) => encodeFilter(child))]]);
-        case "not":
-            return new Map([["not", encodeFilter(filter.filter)]]);
-        case "pred":
-            return new Map([["pred", encodePredicate(filter.predicate)]]);
-    }
+export function newQuery(target, executionId, deadlineMicros) {
+    return {
+        executionId,
+        target,
+        deadlineMicros,
+        byKey: [],
+        order: [],
+        page: { limit: 50, offset: 0n, wantTotal: false },
+        distinct: false,
+        select: { fields: [], payload: false },
+        consistency: "eventual"
+    };
 }
-export function decodeFilter(value, context) {
-    const map = expectMap(value, context);
-    if (map.size !== 1) {
-        throw new CodecError(`expected exactly one filter tag in ${context}`, context, "filter");
+function optional(map, name, value, encode = (item) => item) {
+    if (value !== undefined)
+        map.set(name, encode(value));
+}
+function mapOf(entries) {
+    return new Map(entries);
+}
+function idBytes(id) {
+    return id.toBytes();
+}
+export function encodeQueryTarget(target) {
+    const map = new Map([["kind", target.kind]]);
+    if (target.kind === "operational")
+        map.set("index", target.index);
+    else {
+        map.set("destination_id", idBytes(target.destinationId));
+        map.set("destination_generation", target.destinationGeneration);
+        optional(map, "snapshot", target.snapshot, encodeSnapshotSelector);
     }
-    const [first] = Array.from(map.entries());
-    if (first === undefined) {
-        throw new CodecError(`expected exactly one filter tag in ${context}`, context, "filter");
+    return map;
+}
+export function decodeQueryTarget(map, context) {
+    const kind = field.requiredString(map, "kind", context);
+    if (kind === "operational")
+        return { kind, index: field.requiredString(map, "index", context) };
+    if (kind === "lakehouse") {
+        const snapshot = field.optionalMap(map, "snapshot", context);
+        return {
+            kind,
+            destinationId: DestinationId.fromBytes(field.requiredBytes(map, "destination_id", context)),
+            destinationGeneration: field.requiredU64(map, "destination_generation", context),
+            ...(snapshot === undefined
+                ? {}
+                : { snapshot: decodeSnapshotSelector(snapshot, `${context}.snapshot`) })
+        };
     }
-    const [tag, inner] = first;
-    switch (tag) {
+    throw new CodecError(`unknown query target \`${kind}\``, context, "kind");
+}
+function encodeSnapshotSelector(selector) {
+    return mapOf([
+        ["kind", selector.kind],
+        ["value", selector.value]
+    ]);
+}
+function decodeSnapshotSelector(map, context) {
+    const kind = field.requiredString(map, "kind", context);
+    const value = field.requiredI64(map, "value", context);
+    if (kind === "snapshot_id" || kind === "timestamp_micros")
+        return { kind, value };
+    throw new CodecError(`unknown snapshot selector \`${kind}\``, context, "kind");
+}
+function encodeKeyMatch(value) {
+    return mapOf([
+        ["field", value.field],
+        ["value", encodeTypedValue(value.value)]
+    ]);
+}
+function decodeKeyMatch(map, context) {
+    return {
+        field: field.requiredString(map, "field", context),
+        value: decodeTypedValue(map.get("value"), `${context}.value`)
+    };
+}
+function encodePredicate(value) {
+    return mapOf([
+        ["field", value.field],
+        ["op", value.op],
+        ["value", encodeTypedValue(value.value)]
+    ]);
+}
+function decodePredicate(map, context) {
+    return {
+        field: field.requiredString(map, "field", context),
+        op: decodeWord(map, "op", context, [
+            "eq",
+            "ne",
+            "lt",
+            "lte",
+            "gt",
+            "gte",
+            "in",
+            "contains",
+            "prefix"
+        ]),
+        value: decodeTypedValue(map.get("value"), `${context}.value`)
+    };
+}
+export function encodeFilter(value) {
+    switch (value.kind) {
         case "all":
-            return { kind: "all", filters: expectFilterArray(inner, context) };
+            return mapOf([["all", value.filters.map(encodeFilter)]]);
         case "any":
-            return { kind: "any", filters: expectFilterArray(inner, context) };
+            return mapOf([["any", value.filters.map(encodeFilter)]]);
         case "not":
-            return { kind: "not", filter: decodeFilter(inner, context) };
+            return mapOf([["not", encodeFilter(value.filter)]]);
         case "pred":
-            return { kind: "pred", predicate: decodePredicate(expectMap(inner, context), context) };
-        default:
-            throw new CodecError(`\`${String(tag)}\` is not a recognized filter tag`, context, "filter");
+            return mapOf([["pred", encodePredicate(value.predicate)]]);
     }
 }
-function expectFilterArray(value, context) {
-    if (!Array.isArray(value)) {
-        throw new CodecError(`expected an array in ${context}`, context, "filter");
+export function decodeFilter(value, context) {
+    const [tag, inner] = singleVariantTag(value, context);
+    if (tag === "all" || tag === "any") {
+        if (!Array.isArray(inner))
+            throw new CodecError("filter children must be an array", context, tag);
+        return {
+            kind: tag,
+            filters: inner.map((item, index) => decodeFilter(item, `${context}.${tag}[${String(index)}]`))
+        };
     }
-    return value.map((item, index) => decodeFilter(item, `${context}[${String(index)}]`));
+    if (tag === "not")
+        return { kind: tag, filter: decodeFilter(inner, `${context}.not`) };
+    if (tag === "pred")
+        return {
+            kind: tag,
+            predicate: decodePredicate(expectMap(inner, `${context}.pred`), `${context}.pred`)
+        };
+    throw new CodecError(`unknown filter \`${tag}\``, context, "filter");
 }
-export function encodeRawSql(rawSql) {
-    const map = new Map();
-    map.set("sql", rawSql.sql);
-    if (rawSql.params.length > 0)
-        map.set("params", rawSql.params.map((value) => encodeValue(value)));
+function encodeSort(value) {
+    const map = mapOf([["field", value.field]]);
+    if (value.dir !== "asc")
+        map.set("dir", value.dir);
     return map;
 }
-export function decodeRawSql(map, context) {
-    return {
-        sql: field.requiredString(map, "sql", context),
-        params: field.optionalArray(map, "params", context, (item, index) => decodeValue(item, `${context}.params[${String(index)}]`))
-    };
-}
-function parseDir(word, context) {
-    if (word !== "asc" && word !== "desc") {
-        throw new CodecError(`\`${word}\` is not a recognized sort direction`, context, "dir");
-    }
-    return word;
-}
-export function encodeSort(sort) {
-    return new Map([
-        ["field", sort.field],
-        ["dir", sort.dir]
-    ]);
-}
-export function decodeSort(map, context) {
-    const dir = field.optionalString(map, "dir", context);
+function decodeSort(map, context) {
     return {
         field: field.requiredString(map, "field", context),
-        dir: dir !== undefined ? parseDir(dir, context) : "asc"
+        dir: decodeOptionalWord(map, "dir", context, ["asc", "desc"]) ?? "asc"
     };
 }
-export function encodeTextQuery(text) {
+function encodeText(value) {
     const map = new Map();
-    if (text.field !== undefined)
-        map.set("field", text.field);
-    map.set("query", text.query);
+    optional(map, "field", value.field);
+    map.set("query", value.query);
     return map;
 }
-export function decodeTextQuery(map, context) {
+function decodeText(map, context) {
     const textField = field.optionalString(map, "field", context);
     return {
-        ...(textField !== undefined ? { field: textField } : {}),
+        ...(textField === undefined ? {} : { field: textField }),
         query: field.requiredString(map, "query", context)
     };
 }
-export function encodeVectorQuery(vector) {
-    return new Map([
-        ["field", vector.field],
-        ["embedding", [...vector.embedding]],
-        ["top_k", BigInt(vector.topK)]
+function encodeVector(value) {
+    return mapOf([
+        ["field", value.field],
+        ["embedding", [...value.embedding]],
+        ["top_k", value.topK]
     ]);
 }
-export function decodeVectorQuery(map, context) {
+function decodeVector(map, context) {
     return {
         field: field.requiredString(map, "field", context),
-        embedding: field.requiredArray(map, "embedding", context, (item, index) => expectNumber(item, `${context}.embedding[${String(index)}]`)),
+        embedding: field.requiredArray(map, "embedding", context, (item) => {
+            if (typeof item !== "number")
+                throw new CodecError("embedding value must be a number", context, "embedding");
+            return item;
+        }),
         topK: field.requiredU32(map, "top_k", context)
     };
 }
-function expectNumber(value, context) {
-    if (typeof value !== "number") {
-        throw new CodecError(`expected a number in ${context}`, context, "value");
-    }
-    return value;
-}
-const AGG_FUNC_WORDS = new Map([
-    ["count", "count"],
-    ["count_distinct", "countDistinct"],
-    ["sum", "sum"],
-    ["avg", "avg"],
-    ["min", "min"],
-    ["max", "max"],
-    ["percentile", "percentile"],
-    ["std_dev", "stdDev"]
-]);
-const AGG_FUNC_TO_WORD = new Map(Array.from(AGG_FUNC_WORDS.entries(), ([word, value]) => [value, word]));
-function parseAggFunc(word, context) {
-    const value = AGG_FUNC_WORDS.get(word);
-    if (value === undefined) {
-        throw new CodecError(`\`${word}\` is not a recognized aggregate function`, context, "func");
-    }
-    return value;
-}
-function aggFuncToWord(value) {
-    const word = AGG_FUNC_TO_WORD.get(value);
-    if (word === undefined) {
-        throw new CodecError(`\`${value}\` is not a recognized aggregate function`, "AggFunc", "func");
-    }
-    return word;
-}
-export function encodeAggCall(call) {
-    const map = new Map();
-    map.set("func", aggFuncToWord(call.func));
-    if (call.field !== undefined)
-        map.set("field", call.field);
-    if (call.arg !== undefined)
-        map.set("arg", call.arg);
-    map.set("alias", call.alias);
+function encodeAggCall(value) {
+    const map = mapOf([["func", value.func]]);
+    optional(map, "field", value.field);
+    optional(map, "arg", value.arg);
+    map.set("alias", value.alias);
     return map;
 }
-export function decodeAggCall(map, context) {
+function decodeAggCall(map, context) {
     const callField = field.optionalString(map, "field", context);
     const arg = field.optionalF64(map, "arg", context);
     return {
-        func: parseAggFunc(field.requiredString(map, "func", context), context),
-        ...(callField !== undefined ? { field: callField } : {}),
-        ...(arg !== undefined ? { arg } : {}),
+        func: decodeWord(map, "func", context, [
+            "count",
+            "count_distinct",
+            "sum",
+            "avg",
+            "min",
+            "max",
+            "percentile",
+            "std_dev"
+        ]),
+        ...(callField === undefined ? {} : { field: callField }),
+        ...(arg === undefined ? {} : { arg }),
         alias: field.requiredString(map, "alias", context)
     };
 }
-export function encodeWindow(window) {
-    return new Map([
-        ["field", window.field],
-        ["every_micros", window.everyMicros]
-    ]);
-}
-export function decodeWindow(map, context) {
-    return {
-        field: field.requiredString(map, "field", context),
-        everyMicros: field.requiredU64(map, "every_micros", context)
-    };
-}
-export function encodeAggregate(aggregate) {
+function encodeAggregate(value) {
     const map = new Map();
-    if (aggregate.groupBy.length > 0)
-        map.set("group_by", [...aggregate.groupBy]);
-    map.set("funcs", aggregate.funcs.map((call) => encodeAggCall(call)));
-    if (aggregate.window !== undefined)
-        map.set("window", encodeWindow(aggregate.window));
+    if (value.groupBy.length > 0)
+        map.set("group_by", [...value.groupBy]);
+    map.set("funcs", value.funcs.map(encodeAggCall));
+    optional(map, "window", value.window, (item) => mapOf([
+        ["field", item.field],
+        ["every_micros", item.everyMicros]
+    ]));
     return map;
 }
-export function decodeAggregate(map, context) {
-    const windowMap = field.optionalMap(map, "window", context);
+function decodeAggregate(map, context) {
+    const window = field.optionalMap(map, "window", context);
     return {
         groupBy: field.optionalArray(map, "group_by", context, (item, index) => expectString(item, `${context}.group_by[${String(index)}]`)),
         funcs: field.requiredArray(map, "funcs", context, (item, index) => decodeAggCall(expectMap(item, `${context}.funcs[${String(index)}]`), `${context}.funcs[${String(index)}]`)),
-        ...(windowMap !== undefined ? { window: decodeWindow(windowMap, `${context}.window`) } : {})
+        ...(window === undefined
+            ? {}
+            : {
+                window: {
+                    field: field.requiredString(window, "field", context),
+                    everyMicros: field.requiredU64(window, "every_micros", context)
+                }
+            })
     };
 }
-export function encodeSelect(select) {
+function encodeSelect(value) {
     const map = new Map();
-    if (select.fields.length > 0)
-        map.set("fields", [...select.fields]);
-    map.set("payload", select.payload);
+    if (value.fields.length > 0)
+        map.set("fields", [...value.fields]);
+    map.set("payload", value.payload);
     return map;
 }
-export function decodeSelect(map, context) {
+function decodeSelect(map, context) {
     return {
         fields: field.optionalArray(map, "fields", context, (item, index) => expectString(item, `${context}.fields[${String(index)}]`)),
         payload: field.optionalBoolean(map, "payload", context) ?? false
     };
 }
-export function parseConsistency(word, context) {
-    switch (word) {
-        case "eventual":
-            return "eventual";
-        case "read_your_writes":
-            return "readYourWrites";
-        case "strong":
-            return "strong";
-        default:
-            throw new CodecError(`\`${word}\` is not a recognized consistency level`, context, "consistency");
-    }
+function encodeRawSql(value) {
+    const map = mapOf([
+        ["dialect", value.dialect],
+        ["sql", value.sql]
+    ]);
+    if (value.params.length > 0)
+        map.set("params", value.params.map(encodeTypedValue));
+    return map;
 }
-export function consistencyToWord(value) {
-    switch (value) {
-        case "eventual":
-            return "eventual";
-        case "readYourWrites":
-            return "read_your_writes";
-        case "strong":
-            return "strong";
-    }
+function decodeRawSql(map, context) {
+    return {
+        dialect: decodeWord(map, "dialect", context, ["data_fusion", "postgres", "my_sql", "sqlite"]),
+        sql: field.requiredString(map, "sql", context),
+        params: field.optionalArray(map, "params", context, (item, index) => decodeTypedValue(item, `${context}.params[${String(index)}]`))
+    };
+}
+function encodePageRequest(value) {
+    const map = mapOf([["limit", value.limit]]);
+    optional(map, "offset", value.offset);
+    optional(map, "cursor", value.cursor);
+    if (value.wantTotal)
+        map.set("want_total", true);
+    return map;
+}
+function decodePageRequest(map, context) {
+    const offset = field.optionalU64(map, "offset", context);
+    const cursor = field.optionalString(map, "cursor", context);
+    return {
+        limit: field.requiredU32(map, "limit", context),
+        ...(offset === undefined ? {} : { offset }),
+        ...(cursor === undefined ? {} : { cursor }),
+        wantTotal: field.optionalBoolean(map, "want_total", context) ?? false
+    };
 }
 export function encodeQuery(query) {
-    const map = new Map();
-    map.set("index", query.index);
+    const map = mapOf([
+        ["execution_id", idBytes(query.executionId)],
+        ["target", encodeQueryTarget(query.target)],
+        ["deadline_micros", query.deadlineMicros]
+    ]);
     if (query.byKey.length > 0)
-        map.set("by_key", query.byKey.map((match) => encodeKeyMatch(match)));
-    if (query.messageType !== undefined)
-        map.set("message_type", query.messageType);
-    if (query.timeRange !== undefined)
-        map.set("time_range", [...query.timeRange]);
-    if (query.filter !== undefined)
-        map.set("filter", encodeFilter(query.filter));
-    if (query.vector !== undefined)
-        map.set("vector", encodeVectorQuery(query.vector));
-    if (query.text !== undefined)
-        map.set("text", encodeTextQuery(query.text));
+        map.set("by_key", query.byKey.map(encodeKeyMatch));
+    optional(map, "message_type", query.messageType);
+    optional(map, "time_range", query.timeRange, (item) => [...item]);
+    optional(map, "filter", query.filter, encodeFilter);
+    optional(map, "vector", query.vector, encodeVector);
+    optional(map, "text", query.text, encodeText);
     if (query.order.length > 0)
-        map.set("order", query.order.map((sort) => encodeSort(sort)));
-    map.set("limit", BigInt(query.limit));
-    map.set("offset", BigInt(query.offset));
-    if (query.aggregate !== undefined)
-        map.set("aggregate", encodeAggregate(query.aggregate));
-    if (query.having !== undefined)
-        map.set("having", encodeFilter(query.having));
+        map.set("order", query.order.map(encodeSort));
+    map.set("page", encodePageRequest(query.page));
+    optional(map, "aggregate", query.aggregate, encodeAggregate);
+    optional(map, "having", query.having, encodeFilter);
     if (query.distinct)
         map.set("distinct", true);
     map.set("select", encodeSelect(query.select));
-    if (query.fork !== undefined)
-        map.set("fork", query.fork);
-    if (query.rawSql !== undefined)
-        map.set("raw_sql", encodeRawSql(query.rawSql));
+    optional(map, "fork", query.fork);
+    optional(map, "raw_sql", query.rawSql, encodeRawSql);
     if (query.consistency !== "eventual")
-        map.set("consistency", consistencyToWord(query.consistency));
-    if (query.wantTotal)
-        map.set("want_total", true);
+        map.set("consistency", query.consistency);
     return map;
 }
 export function decodeQuery(map, context) {
     const messageType = field.optionalString(map, "message_type", context);
-    const timeRangeRaw = map.get("time_range");
-    const filterRaw = map.get("filter");
-    const vectorMap = field.optionalMap(map, "vector", context);
-    const textMap = field.optionalMap(map, "text", context);
-    const aggregateMap = field.optionalMap(map, "aggregate", context);
-    const havingRaw = map.get("having");
+    const timeRangeValue = map.get("time_range");
+    let timeRange;
+    if (timeRangeValue !== undefined) {
+        if (!Array.isArray(timeRangeValue) || timeRangeValue.length !== 2)
+            throw new CodecError("time range must contain two values", context, "time_range");
+        timeRange = [asU64(timeRangeValue[0], context), asU64(timeRangeValue[1], context)];
+    }
+    const filter = map.get("filter");
+    const vector = field.optionalMap(map, "vector", context);
+    const text = field.optionalMap(map, "text", context);
+    const aggregate = field.optionalMap(map, "aggregate", context);
+    const having = map.get("having");
     const fork = field.optionalString(map, "fork", context);
-    const rawSqlMap = field.optionalMap(map, "raw_sql", context);
-    const consistencyWord = field.optionalString(map, "consistency", context);
-    const selectMap = field.optionalMap(map, "select", context);
+    const rawSql = field.optionalMap(map, "raw_sql", context);
     return {
-        index: field.requiredString(map, "index", context),
+        executionId: QueryExecutionId.fromBytes(field.requiredBytes(map, "execution_id", context)),
+        target: decodeQueryTarget(field.requiredMap(map, "target", context), `${context}.target`),
+        deadlineMicros: field.requiredU64(map, "deadline_micros", context),
         byKey: field.optionalArray(map, "by_key", context, (item, index) => decodeKeyMatch(expectMap(item, `${context}.by_key[${String(index)}]`), `${context}.by_key[${String(index)}]`)),
-        ...(messageType !== undefined ? { messageType } : {}),
-        ...(timeRangeRaw !== undefined ? { timeRange: expectU64Pair(timeRangeRaw, context) } : {}),
-        ...(filterRaw !== undefined ? { filter: decodeFilter(filterRaw, `${context}.filter`) } : {}),
-        ...(vectorMap !== undefined
-            ? { vector: decodeVectorQuery(vectorMap, `${context}.vector`) }
-            : {}),
-        ...(textMap !== undefined ? { text: decodeTextQuery(textMap, `${context}.text`) } : {}),
+        ...(messageType === undefined ? {} : { messageType }),
+        ...(timeRange === undefined ? {} : { timeRange }),
+        ...(filter === undefined ? {} : { filter: decodeFilter(filter, `${context}.filter`) }),
+        ...(vector === undefined ? {} : { vector: decodeVector(vector, `${context}.vector`) }),
+        ...(text === undefined ? {} : { text: decodeText(text, `${context}.text`) }),
         order: field.optionalArray(map, "order", context, (item, index) => decodeSort(expectMap(item, `${context}.order[${String(index)}]`), `${context}.order[${String(index)}]`)),
-        limit: field.requiredU32(map, "limit", context),
-        offset: field.optionalU32(map, "offset", context) ?? 0,
-        ...(aggregateMap !== undefined
-            ? { aggregate: decodeAggregate(aggregateMap, `${context}.aggregate`) }
-            : {}),
-        ...(havingRaw !== undefined ? { having: decodeFilter(havingRaw, `${context}.having`) } : {}),
+        page: decodePageRequest(field.requiredMap(map, "page", context), `${context}.page`),
+        ...(aggregate === undefined
+            ? {}
+            : { aggregate: decodeAggregate(aggregate, `${context}.aggregate`) }),
+        ...(having === undefined ? {} : { having: decodeFilter(having, `${context}.having`) }),
         distinct: field.optionalBoolean(map, "distinct", context) ?? false,
-        select: selectMap !== undefined
-            ? decodeSelect(selectMap, `${context}.select`)
-            : { fields: [], payload: false },
-        ...(fork !== undefined ? { fork } : {}),
-        ...(rawSqlMap !== undefined ? { rawSql: decodeRawSql(rawSqlMap, `${context}.raw_sql`) } : {}),
-        consistency: consistencyWord !== undefined ? parseConsistency(consistencyWord, context) : "eventual",
-        wantTotal: field.optionalBoolean(map, "want_total", context) ?? false
+        select: decodeSelect(field.requiredMap(map, "select", context), `${context}.select`),
+        ...(fork === undefined ? {} : { fork }),
+        ...(rawSql === undefined ? {} : { rawSql: decodeRawSql(rawSql, `${context}.raw_sql`) }),
+        consistency: decodeOptionalWord(map, "consistency", context, ["eventual", "read_your_writes", "strong"]) ??
+            "eventual"
     };
 }
-function expectU64Pair(value, context) {
-    if (!Array.isArray(value) || value.length !== 2) {
-        throw new CodecError(`expected a 2-element array in ${context}.time_range`, context, "time_range");
+export function validateQuery(query) {
+    if (query.executionId.asU128() === 0n || query.deadlineMicros === 0n)
+        throw new InvalidError("query execution identity and deadline must be nonzero");
+    if (query.target.kind === "operational")
+        validateName(query.target.index);
+    else {
+        if (query.target.destinationId.asU128() === 0n || query.target.destinationGeneration === 0n)
+            throw new InvalidError("lakehouse target identity must be nonzero");
+        if (query.target.snapshot !== undefined && query.target.snapshot.value <= 0n)
+            throw new InvalidError("snapshot selector must be positive");
+        if (query.fork !== undefined)
+            throw new InvalidError("lakehouse queries cannot use an operational fork");
+    }
+    if (query.page.limit < 1 || query.page.limit > MAX_PAGE_SIZE)
+        throw new InvalidError("query page limit is invalid");
+    if (query.page.offset !== undefined && query.page.cursor !== undefined)
+        throw new InvalidError("query page cannot contain both an offset and a cursor");
+    if (query.page.cursor !== undefined)
+        validateCursor(query.page.cursor);
+    for (const [label, count] of [
+        ["exact matches", query.byKey.length],
+        ["sort fields", query.order.length],
+        ["selected fields", query.select.fields.length]
+    ]) {
+        if (count > MAX_QUERY_FIELDS)
+            throw new InvalidError(`query ${label} count exceeds cap ${String(MAX_QUERY_FIELDS)}`);
+    }
+    for (const match of query.byKey) {
+        validateName(match.field);
+        validateTypedValue(match.value);
+    }
+    if (query.messageType !== undefined)
+        validateName(query.messageType);
+    if (query.timeRange !== undefined && query.timeRange[0] >= query.timeRange[1])
+        throw new InvalidError("query time range must be a nonempty half-open interval");
+    for (const sort of query.order)
+        validateName(sort.field);
+    for (const field of query.select.fields)
+        validateName(field);
+    if (query.text !== undefined) {
+        if (query.text.query.trim().length === 0 ||
+            byteLength(query.text.query) > MAX_TEXT_QUERY_BYTES ||
+            hasControlCharacter(query.text.query))
+            throw new InvalidError("text query is invalid");
+        if (query.text.field !== undefined &&
+            (query.text.field.length === 0 ||
+                byteLength(query.text.field) > MAX_QUERY_NAME_BYTES ||
+                hasControlCharacter(query.text.field)))
+            throw new InvalidError("text query field is invalid");
+    }
+    if (query.vector !== undefined) {
+        validateName(query.vector.field);
+        if (query.vector.embedding.length === 0 ||
+            query.vector.embedding.length > MAX_VECTOR_DIMENSIONS ||
+            query.vector.embedding.some((value) => !Number.isFinite(value) || Object.is(value, -0)) ||
+            query.vector.topK < 1 ||
+            query.vector.topK > MAX_PAGE_SIZE)
+            throw new InvalidError("vector query is invalid");
+    }
+    const visit = (filter, depth = 1, count = { value: 0 }) => {
+        if (filter === undefined)
+            return;
+        count.value += 1;
+        if (count.value > MAX_QUERY_PREDICATES)
+            throw new InvalidError("query filter node count exceeds cap");
+        if (depth > 64)
+            throw new InvalidError("query filter depth exceeds cap");
+        if (filter.kind === "all" || filter.kind === "any") {
+            if (filter.filters.length === 0)
+                throw new InvalidError("filter conjunction cannot be empty");
+            for (const child of filter.filters)
+                visit(child, depth + 1, count);
+        }
+        else if (filter.kind === "not")
+            visit(filter.filter, depth + 1, count);
+        else {
+            validateName(filter.predicate.field);
+            validateTypedValue(filter.predicate.value);
+            if (filter.predicate.op === "in" &&
+                (filter.predicate.value.kind !== "list" || filter.predicate.value.value.length === 0))
+                throw new InvalidError("query IN predicate requires a nonempty typed list");
+            if (filter.predicate.op === "prefix" && filter.predicate.value.kind !== "string")
+                throw new InvalidError("query prefix predicate requires a string value");
+        }
+    };
+    visit(query.filter);
+    visit(query.having);
+    if (query.having !== undefined && query.aggregate === undefined)
+        throw new InvalidError("having requires an aggregate");
+    if (query.aggregate !== undefined) {
+        if (query.aggregate.funcs.length === 0 ||
+            query.aggregate.funcs.length > MAX_QUERY_PARAMETERS ||
+            query.aggregate.groupBy.length > MAX_QUERY_FIELDS)
+            throw new InvalidError("aggregate function or group count is invalid");
+        for (const field of query.aggregate.groupBy)
+            validateName(field);
+        const aliases = new Set();
+        for (const call of query.aggregate.funcs) {
+            validateName(call.alias);
+            if (aliases.has(call.alias))
+                throw new InvalidError("aggregate aliases must be unique");
+            aliases.add(call.alias);
+            if (call.field !== undefined)
+                validateName(call.field);
+            if (call.func === "count") {
+                if (call.arg !== undefined)
+                    throw new InvalidError("count aggregate cannot carry an argument");
+            }
+            else if (call.func === "percentile") {
+                if (call.field === undefined ||
+                    call.arg === undefined ||
+                    !Number.isFinite(call.arg) ||
+                    call.arg < 0 ||
+                    call.arg > 1)
+                    throw new InvalidError("percentile aggregate is invalid");
+            }
+            else if (call.field === undefined || call.arg !== undefined) {
+                throw new InvalidError("aggregate field and argument do not match its function");
+            }
+        }
+        if (query.aggregate.window !== undefined) {
+            validateName(query.aggregate.window.field);
+            if (query.aggregate.window.everyMicros === 0n)
+                throw new InvalidError("aggregate window duration must be nonzero");
+        }
+        if (query.select.fields.length > 0 || query.select.payload)
+            throw new InvalidError("aggregate query cannot select rows");
+    }
+    if (query.rawSql !== undefined) {
+        if (query.rawSql.sql.trim().length === 0 ||
+            byteLength(query.rawSql.sql) > MAX_RAW_SQL_BYTES ||
+            hasDisallowedSqlControl(query.rawSql.sql) ||
+            query.rawSql.params.length > MAX_QUERY_PARAMETERS)
+            throw new InvalidError("raw SQL is invalid");
+        for (const param of query.rawSql.params)
+            validateTypedValue(param);
+        if (query.byKey.length > 0 ||
+            query.messageType !== undefined ||
+            query.timeRange !== undefined ||
+            query.filter !== undefined ||
+            query.vector !== undefined ||
+            query.text !== undefined ||
+            query.order.length > 0 ||
+            query.aggregate !== undefined ||
+            query.having !== undefined ||
+            query.distinct ||
+            query.select.fields.length > 0 ||
+            query.select.payload)
+            throw new InvalidError("raw SQL cannot be combined with the structured query expression");
     }
-    const [start, end] = value;
-    return [expectU64Value(start, context), expectU64Value(end, context)];
 }
-function expectU64Value(value, context) {
-    if (typeof value === "bigint")
-        return value;
-    if (typeof value === "number" && Number.isInteger(value) && value >= 0)
-        return BigInt(value);
-    throw new CodecError(`expected an unsigned integer in ${context}.time_range`, context, "time_range");
+export function validateQueryEnvelope(envelope) {
+    validateQueryControl(envelope.v, envelope.query.executionId);
+    validateQuery(envelope.query);
+}
+export function validateQueryPageEnvelope(envelope) {
+    validateQueryControl(envelope.v, envelope.executionId);
+    validateCursor(envelope.cursor);
+    if (envelope.deadlineMicros === 0n)
+        throw new InvalidError("query page deadline must be nonzero");
+}
+export function validateQueryCancelEnvelope(envelope) {
+    validateQueryControl(envelope.v, envelope.executionId);
+}
+export function validateQueryStatusEnvelope(envelope) {
+    validateQueryControl(envelope.v, envelope.executionId);
+}
+function validateQueryControl(version, executionId) {
+    if (version !== QUERY_OP_VERSION)
+        throw new InvalidError(`query version must be ${String(QUERY_OP_VERSION)}`);
+    if (executionId.asU128() === 0n)
+        throw new InvalidError("query execution id must be nonzero");
+}
+function validateCursor(cursor) {
+    if (cursor.length === 0 ||
+        byteLength(cursor) > MAX_QUERY_CURSOR_BYTES ||
+        hasControlCharacter(cursor))
+        throw new InvalidError("query cursor is invalid");
 }
 export function encodeQueryEnvelope(envelope) {
-    return new Map([
-        ["v", BigInt(QUERY_OP_VERSION)],
+    return mapOf([
+        ["v", envelope.v],
         ["query", encodeQuery(envelope.query)]
     ]);
 }
 export function decodeQueryEnvelope(map, context) {
-    field.requiredU32(map, "v", context);
-    return { query: decodeQuery(field.requiredMap(map, "query", context), `${context}.query`) };
+    return {
+        v: field.requiredU32(map, "v", context),
+        query: decodeQuery(field.requiredMap(map, "query", context), `${context}.query`)
+    };
 }
 export function encodeQueryEnvelopeFrame(envelope) {
     return encodeNamed(encodeQueryEnvelope(envelope), { forceFloatNumbers: true });
 }
-export function encodePage(page) {
+export function decodeQueryEnvelopeFrame(bytes) {
+    return decodeQueryEnvelope(expectMap(decodeOne(bytes, "QueryEnvelope"), "QueryEnvelope"), "QueryEnvelope");
+}
+function encodeRow(value) {
+    const map = mapOf([["values", value.values.map(encodeTypedValue)]]);
+    optional(map, "score", value.score);
+    return map;
+}
+function decodeRow(map, context) {
+    const score = field.optionalF64(map, "score", context);
+    return {
+        values: field.requiredArray(map, "values", context, (item, index) => decodeTypedValue(item, `${context}.values[${String(index)}]`)),
+        ...(score === undefined ? {} : { score })
+    };
+}
+function encodePage(value) {
     const map = new Map();
-    map.set("offset", BigInt(page.offset));
-    map.set("limit", BigInt(page.limit));
-    if (page.total !== undefined)
-        map.set("total", page.total);
-    map.set("has_more", page.hasMore);
+    optional(map, "offset", value.offset);
+    map.set("limit", value.limit);
+    optional(map, "total", value.total);
+    map.set("has_more", value.hasMore);
+    optional(map, "next_cursor", value.nextCursor);
     return map;
 }
-export function decodePage(map, context) {
+function decodePage(map, context) {
+    const offset = field.optionalU64(map, "offset", context);
     const total = field.optionalU64(map, "total", context);
+    const nextCursor = field.optionalString(map, "next_cursor", context);
     return {
-        offset: field.requiredU32(map, "offset", context),
+        ...(offset === undefined ? {} : { offset }),
         limit: field.requiredU32(map, "limit", context),
-        ...(total !== undefined ? { total } : {}),
-        hasMore: field.requiredBoolean(map, "has_more", context)
+        ...(total === undefined ? {} : { total }),
+        hasMore: field.requiredBoolean(map, "has_more", context),
+        ...(nextCursor === undefined ? {} : { nextCursor })
     };
 }
-export function pageAtLeast(page, rowsOnPage) {
-    return page.offset + rowsOnPage;
-}
-export function pageTotalPages(page) {
-    if (page.total === undefined || page.limit === 0)
-        return undefined;
-    return (page.total + BigInt(page.limit) - 1n) / BigInt(page.limit);
+function encodeEngine(value) {
+    const map = mapOf([
+        ["name", value.name],
+        ["version", value.version]
+    ]);
+    optional(map, "dialect", value.dialect);
+    return map;
 }
-function encodeStringMap(entries) {
-    return new Map(entries);
+function decodeEngine(map, context) {
+    const dialect = decodeOptionalWord(map, "dialect", context, [
+        "data_fusion",
+        "postgres",
+        "my_sql",
+        "sqlite"
+    ]);
+    return {
+        name: field.requiredString(map, "name", context),
+        version: field.requiredString(map, "version", context),
+        ...(dialect === undefined ? {} : { dialect })
+    };
 }
-function decodeStringMap(map, context) {
-    const result = new Map();
-    for (const [key, value] of map) {
-        if (typeof key !== "string" || typeof value !== "string") {
-            throw new CodecError(`${context} must map strings to strings`, context, "value");
-        }
-        result.set(key, value);
+function encodeResolvedTarget(value) {
+    const map = mapOf([["kind", value.kind]]);
+    if (value.kind === "operational")
+        map.set("index", value.index);
+    else {
+        map.set("destination_id", idBytes(value.destinationId));
+        map.set("destination_generation", value.destinationGeneration);
+        map.set("table_uuid", value.tableUuid);
+        map.set("namespace", [...value.namespace]);
+        map.set("table", value.table);
+        map.set("snapshot_id", value.snapshotId);
+        map.set("schema_id", value.schemaId);
+        map.set("partition_spec_id", value.partitionSpecId);
     }
-    return result;
+    map.set("backend_resource_id", idBytes(value.backendResourceId));
+    map.set("backend_generation", value.backendGeneration);
+    map.set("runtime_configuration_revision", value.runtimeConfigurationRevision);
+    return map;
 }
-export function encodeRow(row) {
-    const map = new Map();
-    map.set("headers", encodeStringMap(row.headers));
-    if (row.metadata.size > 0)
-        map.set("metadata", encodeStringMap(row.metadata));
-    if (row.partition !== undefined)
-        map.set("partition", BigInt(row.partition));
-    if (row.offset !== undefined)
-        map.set("offset", row.offset);
-    if (row.stream !== undefined)
-        map.set("stream", BigInt(row.stream));
-    if (row.topic !== undefined)
-        map.set("topic", BigInt(row.topic));
-    if (row.payload !== undefined)
-        map.set("payload", row.payload);
-    if (row.score !== undefined)
-        map.set("score", row.score);
+function decodeResolvedTarget(map, context) {
+    const kind = field.requiredString(map, "kind", context);
+    const common = {
+        backendResourceId: BackendResourceId.fromBytes(field.requiredBytes(map, "backend_resource_id", context)),
+        backendGeneration: field.requiredU64(map, "backend_generation", context),
+        runtimeConfigurationRevision: field.requiredU64(map, "runtime_configuration_revision", context)
+    };
+    if (kind === "operational")
+        return { kind, index: field.requiredString(map, "index", context), ...common };
+    if (kind === "lakehouse")
+        return {
+            kind,
+            destinationId: DestinationId.fromBytes(field.requiredBytes(map, "destination_id", context)),
+            destinationGeneration: field.requiredU64(map, "destination_generation", context),
+            ...common,
+            tableUuid: fixedBytes(field.requiredBytes(map, "table_uuid", context), 16, context),
+            namespace: field.requiredArray(map, "namespace", context, (item, index) => expectString(item, `${context}.namespace[${String(index)}]`)),
+            table: field.requiredString(map, "table", context),
+            snapshotId: field.requiredI64(map, "snapshot_id", context),
+            schemaId: field.requiredI32(map, "schema_id", context),
+            partitionSpecId: field.requiredI32(map, "partition_spec_id", context)
+        };
+    throw new CodecError(`unknown resolved target \`${kind}\``, context, "kind");
+}
+function encodeContext(value) {
+    const map = mapOf([
+        ["execution_id", idBytes(value.executionId)],
+        ["engine", encodeEngine(value.engine)],
+        ["resolved_target", encodeResolvedTarget(value.resolvedTarget)],
+        ["requested_consistency", value.requestedConsistency],
+        ["delivered_consistency", value.deliveredConsistency]
+    ]);
+    optional(map, "boundary", value.boundary, (item) => mapOf([
+        ["digest", item.digest],
+        ["relation_to_current", item.relationToCurrent]
+    ]));
+    optional(map, "checkpoint_revision", value.checkpointRevision);
+    optional(map, "global_state_revision", value.globalStateRevision);
+    map.set("truncated", value.truncated);
+    map.set("elapsed_micros", value.elapsedMicros);
+    map.set("scanned_bytes", value.scannedBytes);
+    map.set("produced_bytes", value.producedBytes);
+    map.set("row_count", value.rowCount);
     return map;
 }
-export function decodeRow(map, context) {
-    const metadataMap = field.optionalMap(map, "metadata", context);
-    const partition = field.optionalU32(map, "partition", context);
-    const offset = field.optionalU64(map, "offset", context);
-    const stream = field.optionalU32(map, "stream", context);
-    const topic = field.optionalU32(map, "topic", context);
-    const payload = field.optionalBytes(map, "payload", context);
-    const score = field.optionalF64(map, "score", context);
+function decodeContext(map, context) {
+    const boundary = field.optionalMap(map, "boundary", context);
+    const checkpointRevision = field.optionalU64(map, "checkpoint_revision", context);
+    const globalStateRevision = field.optionalU64(map, "global_state_revision", context);
     return {
-        headers: decodeStringMap(field.requiredMap(map, "headers", context), `${context}.headers`),
-        metadata: metadataMap !== undefined ? decodeStringMap(metadataMap, `${context}.metadata`) : new Map(),
-        ...(partition !== undefined ? { partition } : {}),
-        ...(offset !== undefined ? { offset } : {}),
-        ...(stream !== undefined ? { stream } : {}),
-        ...(topic !== undefined ? { topic } : {}),
-        ...(payload !== undefined ? { payload } : {}),
-        ...(score !== undefined ? { score } : {})
+        executionId: QueryExecutionId.fromBytes(field.requiredBytes(map, "execution_id", context)),
+        engine: decodeEngine(field.requiredMap(map, "engine", context), `${context}.engine`),
+        resolvedTarget: decodeResolvedTarget(field.requiredMap(map, "resolved_target", context), `${context}.resolved_target`),
+        requestedConsistency: decodeWord(map, "requested_consistency", context, [
+            "eventual",
+            "read_your_writes",
+            "strong"
+        ]),
+        deliveredConsistency: decodeWord(map, "delivered_consistency", context, [
+            "eventual",
+            "read_your_writes",
+            "strong"
+        ]),
+        ...(boundary === undefined
+            ? {}
+            : {
+                boundary: {
+                    digest: fixedBytes(field.requiredBytes(boundary, "digest", context), 32, context),
+                    relationToCurrent: decodeWord(boundary, "relation_to_current", context, [
+                        "current",
+                        "historical",
+                        "ahead_of_observed_checkpoint"
+                    ])
+                }
+            }),
+        ...(checkpointRevision === undefined ? {} : { checkpointRevision }),
+        ...(globalStateRevision === undefined ? {} : { globalStateRevision }),
+        truncated: field.requiredBoolean(map, "truncated", context),
+        elapsedMicros: field.requiredU64(map, "elapsed_micros", context),
+        scannedBytes: field.requiredU64(map, "scanned_bytes", context),
+        producedBytes: field.requiredU64(map, "produced_bytes", context),
+        rowCount: field.requiredU64(map, "row_count", context)
     };
 }
-export function encodeQueryResult(result) {
-    return new Map([
-        ["rows", result.rows.map((row) => encodeRow(row))],
-        ["page", encodePage(result.page)]
+export function encodeQueryResult(value) {
+    return mapOf([
+        ["fields", value.fields.map(encodeLogicalField)],
+        ["rows", value.rows.map(encodeRow)],
+        ["page", encodePage(value.page)],
+        ["context", encodeContext(value.context)]
     ]);
 }
 export function decodeQueryResult(map, context) {
-    return {
+    const result = {
+        fields: field.requiredArray(map, "fields", context, (item, index) => decodeLogicalField(expectMap(item, `${context}.fields[${String(index)}]`), `${context}.fields[${String(index)}]`)),
         rows: field.requiredArray(map, "rows", context, (item, index) => decodeRow(expectMap(item, `${context}.rows[${String(index)}]`), `${context}.rows[${String(index)}]`)),
-        page: decodePage(field.requiredMap(map, "page", context), `${context}.page`)
+        page: decodePage(field.requiredMap(map, "page", context), `${context}.page`),
+        context: decodeContext(field.requiredMap(map, "context", context), `${context}.context`)
     };
+    validateQueryResult(result);
+    return result;
+}
+export function validateQueryResult(result) {
+    validateResultFields(result.fields);
+    for (const row of result.rows) {
+        if (row.values.length !== result.fields.length)
+            throw new InvalidError("query row value count does not match the result schema");
+        for (let index = 0; index < result.fields.length; index += 1) {
+            const field = result.fields[index];
+            const value = row.values[index];
+            if (field === undefined || value === undefined)
+                throw new InvalidError("query row value count does not match the result schema");
+            validateTypedValueAgainst(value, field.fieldType, field.required);
+        }
+        if (row.score !== undefined && !Number.isFinite(row.score))
+            throw new InvalidError("query row score must be finite");
+    }
+    if (result.context.executionId.asU128() === 0n)
+        throw new InvalidError("query result execution id must be nonzero");
+    if (result.context.rowCount !== BigInt(result.rows.length))
+        throw new InvalidError("query result row count does not match the page rows");
+    validateQueryContext(result.context);
+    if (result.page.limit < 1 || result.page.limit > MAX_PAGE_SIZE)
+        throw new InvalidError("query result page limit is invalid");
+    if (result.page.hasMore !== (result.page.nextCursor !== undefined))
+        throw new InvalidError("query result has_more and next_cursor must agree");
+    if (result.page.nextCursor !== undefined)
+        validateCursor(result.page.nextCursor);
+}
+function validateQueryContext(context) {
+    if (context.executionId.asU128() === 0n)
+        throw new InvalidError("query context execution id must be nonzero");
+    validateName(context.engine.name);
+    validateName(context.engine.version);
+    const consistencyRank = {
+        eventual: 0,
+        read_your_writes: 1,
+        strong: 2
+    };
+    if (consistencyRank[context.deliveredConsistency] < consistencyRank[context.requestedConsistency])
+        throw new InvalidError("delivered consistency is weaker than requested consistency");
+    const target = context.resolvedTarget;
+    if (target.kind === "operational") {
+        validateName(target.index);
+        if (target.backendResourceId.asU128() === 0n ||
+            target.backendGeneration === 0n ||
+            target.runtimeConfigurationRevision === 0n)
+            throw new InvalidError("operational query context is missing backend evidence");
+        if (context.boundary !== undefined ||
+            context.checkpointRevision !== undefined ||
+            context.globalStateRevision !== undefined)
+            throw new InvalidError("operational query context cannot carry lakehouse evidence");
+    }
+    else {
+        if (target.destinationId.asU128() === 0n ||
+            target.destinationGeneration === 0n ||
+            target.backendResourceId.asU128() === 0n ||
+            target.backendGeneration === 0n ||
+            target.runtimeConfigurationRevision === 0n ||
+            target.tableUuid.length !== 16 ||
+            target.namespace.length === 0 ||
+            target.snapshotId <= 0n ||
+            target.schemaId < 0 ||
+            target.partitionSpecId < 0 ||
+            context.boundary === undefined ||
+            context.checkpointRevision === undefined ||
+            context.globalStateRevision === undefined)
+            throw new InvalidError("lakehouse query context is missing resolved target evidence");
+        for (const part of target.namespace)
+            validateName(part);
+        validateName(target.table);
+    }
+    if (context.boundary !== undefined && context.boundary.digest.length !== 32)
+        throw new InvalidError("query materialization boundary digest must contain 32 bytes");
+}
+export function queryResultValue(result, row, name) {
+    const index = result.fields.findIndex((item) => item.name === name);
+    return index < 0 ? undefined : row.values[index];
+}
+function snakeToRustVariant(value) {
+    return value
+        .split("_")
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join("");
+}
+function rustVariantToSnake(value) {
+    return value.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
 }
 export function encodeQueryError(error) {
-    switch (error.kind) {
-        case "unsupported":
-            return new Map([["Unsupported", error.message]]);
-        case "unauthorized":
-            return new Map([["Unauthorized", error.message]]);
-        case "indexNotFound":
-            return new Map([["IndexNotFound", error.message]]);
-        case "forkNotFound":
-            return new Map([["ForkNotFound", error.message]]);
-        case "backend":
-            return new Map([["Backend", error.message]]);
-        case "unavailable":
-            return new Map([["Unavailable", error.message]]);
-        case "tooLarge":
-            return new Map([
-                [
-                    "TooLarge",
-                    new Map([
-                        ["what", error.what],
-                        ["size", BigInt(error.size)],
-                        ["cap", BigInt(error.cap)]
-                    ])
-                ]
-            ]);
-        case "version":
-            return new Map([
-                [
-                    "Version",
-                    new Map([
-                        ["expected", BigInt(error.expected)],
-                        ["got", BigInt(error.got)]
-                    ])
-                ]
-            ]);
-        case "stale":
-            return new Map([
-                [
-                    "Stale",
-                    new Map([
-                        ["what", error.what],
-                        ["applied", error.applied],
-                        ["required", error.required]
-                    ])
-                ]
-            ]);
-        case "unrecognized":
-            return new Map([[error.tag, error.value]]);
+    const tag = snakeToRustVariant(error.kind);
+    if ("message" in error)
+        return mapOf([[tag, error.message]]);
+    const body = new Map();
+    for (const [key, value] of Object.entries(error)) {
+        if (key === "kind")
+            continue;
+        const wireKey = key.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+        body.set(wireKey, value instanceof QueryExecutionId ? value.toBytes() : value);
     }
+    return mapOf([[tag, body]]);
 }
 export function decodeQueryError(value, context) {
-    const [tag, inner] = singleVariantTag(value, context);
-    switch (tag) {
-        case "Unsupported":
-            return { kind: "unsupported", message: expectString(inner, context) };
-        case "Unauthorized":
-            return { kind: "unauthorized", message: expectString(inner, context) };
-        case "IndexNotFound":
-            return { kind: "indexNotFound", message: expectString(inner, context) };
-        case "ForkNotFound":
-            return { kind: "forkNotFound", message: expectString(inner, context) };
-        case "Backend":
-            return { kind: "backend", message: expectString(inner, context) };
-        case "Unavailable":
-            return { kind: "unavailable", message: expectString(inner, context) };
-        case "TooLarge": {
-            const tooLargeMap = expectMap(inner, context);
+    const [tag, body] = singleVariantTag(value, context);
+    const kind = rustVariantToSnake(tag);
+    if ([
+        "unsupported",
+        "unauthorized",
+        "index_not_found",
+        "fork_not_found",
+        "backend",
+        "unavailable"
+    ].includes(kind))
+        return { kind: kind, message: expectString(body, context) };
+    const map = expectMap(body, context);
+    switch (kind) {
+        case "too_large":
             return {
-                kind: "tooLarge",
-                what: field.requiredString(tooLargeMap, "what", context),
-                size: field.requiredU32(tooLargeMap, "size", context),
-                cap: field.requiredU32(tooLargeMap, "cap", context)
+                kind,
+                what: field.requiredString(map, "what", context),
+                size: field.requiredU64(map, "size", context),
+                cap: field.requiredU64(map, "cap", context)
             };
-        }
-        case "Version": {
-            const versionMap = expectMap(inner, context);
+        case "version":
             return {
-                kind: "version",
-                expected: field.requiredU32(versionMap, "expected", context),
-                got: field.requiredU32(versionMap, "got", context)
+                kind,
+                expected: field.requiredU32(map, "expected", context),
+                got: field.requiredU32(map, "got", context)
             };
-        }
-        case "Stale": {
-            const staleMap = expectMap(inner, context);
+        case "stale":
             return {
-                kind: "stale",
-                what: field.requiredString(staleMap, "what", context),
-                applied: field.requiredU64(staleMap, "applied", context),
-                required: field.requiredU64(staleMap, "required", context)
+                kind,
+                what: field.requiredString(map, "what", context),
+                applied: field.requiredU64(map, "applied", context),
+                required: field.requiredU64(map, "required", context)
+            };
+        case "cancelled":
+        case "deadline_exceeded":
+            return {
+                kind,
+                executionId: QueryExecutionId.fromBytes(field.requiredBytes(map, "execution_id", context))
+            };
+        case "expired_snapshot":
+            return { kind, snapshotId: field.requiredI64(map, "snapshot_id", context) };
+        case "stale_generation":
+            return {
+                kind,
+                what: field.requiredString(map, "what", context),
+                requested: field.requiredU64(map, "requested", context),
+                observed: field.requiredU64(map, "observed", context)
+            };
+        case "target_unavailable":
+            return { kind, reason: field.requiredString(map, "reason", context) };
+        case "resource_limit":
+            return {
+                kind,
+                resource: field.requiredString(map, "resource", context),
+                observed: field.requiredU64(map, "observed", context),
+                limit: field.requiredU64(map, "limit", context)
             };
-        }
         default:
-            return { kind: "unrecognized", tag, value: inner };
+            throw new CodecError(`unknown query error \`${tag}\``, context, "error");
     }
 }
-export function encodeQueryReply(reply) {
-    switch (reply.kind) {
-        case "ok":
-            return new Map([["Ok", encodeQueryResult(reply.result)]]);
-        case "err":
-            return new Map([["Err", encodeQueryError(reply.error)]]);
-        case "unrecognized":
-            return new Map([[reply.tag, reply.value]]);
-    }
+export function encodeQueryReplyFrame(reply) {
+    return encodeNamed(reply.kind === "ok"
+        ? mapOf([["Ok", encodeQueryResult(reply.result)]])
+        : mapOf([["Err", encodeQueryError(reply.error)]]), { forceFloatNumbers: true });
 }
 export function decodeQueryReply(value, context) {
-    const [tag, inner] = singleVariantTag(value, context);
-    switch (tag) {
-        case "Ok":
-            return { kind: "ok", result: decodeQueryResult(expectMap(inner, context), context) };
-        case "Err":
-            return { kind: "err", error: decodeQueryError(inner, context) };
-        default:
-            return { kind: "unrecognized", tag, value: inner };
-    }
+    const [tag, body] = singleVariantTag(value, context);
+    if (tag === "Ok")
+        return { kind: "ok", result: decodeQueryResult(expectMap(body, context), context) };
+    if (tag === "Err")
+        return { kind: "err", error: decodeQueryError(body, context) };
+    throw new CodecError(`unknown query reply \`${tag}\``, context, "reply");
 }
-export function encodeQueryReplyFrame(reply) {
-    return encodeNamed(encodeQueryReply(reply), { forceFloatNumbers: true });
+export function decodeQueryReplyFrame(bytes) {
+    return decodeQueryReply(decodeOne(bytes, "QueryReply"), "QueryReply");
 }
-export function consistencyGateIsCaughtUp(gate) {
-    return gate.applied >= gate.required;
+export function encodeQueryExecutionStatus(value) {
+    const map = mapOf([
+        ["execution_id", value.executionId.toBytes()],
+        ["state", value.state],
+        ["started_at_micros", value.startedAtMicros]
+    ]);
+    optional(map, "finished_at_micros", value.finishedAtMicros);
+    map.set("scanned_bytes", value.scannedBytes);
+    map.set("produced_bytes", value.producedBytes);
+    map.set("row_count", value.rowCount);
+    optional(map, "error", value.error, encodeQueryError);
+    return map;
 }
-export function consistencyGateCheck(gate, level, what) {
-    if (level === "eventual" || consistencyGateIsCaughtUp(gate)) {
-        return { ok: true };
-    }
-    return {
-        ok: false,
-        error: { kind: "stale", what, applied: gate.applied, required: gate.required }
+export function decodeQueryExecutionStatus(map, context) {
+    const finishedAtMicros = field.optionalU64(map, "finished_at_micros", context);
+    const error = map.get("error");
+    const status = {
+        executionId: QueryExecutionId.fromBytes(field.requiredBytes(map, "execution_id", context)),
+        state: decodeWord(map, "state", context, [
+            "queued",
+            "planning",
+            "running",
+            "completed",
+            "cancelled",
+            "failed",
+            "expired"
+        ]),
+        startedAtMicros: field.requiredU64(map, "started_at_micros", context),
+        ...(finishedAtMicros === undefined ? {} : { finishedAtMicros }),
+        scannedBytes: field.requiredU64(map, "scanned_bytes", context),
+        producedBytes: field.requiredU64(map, "produced_bytes", context),
+        rowCount: field.requiredU64(map, "row_count", context),
+        ...(error === undefined ? {} : { error: decodeQueryError(error, `${context}.error`) })
     };
+    validateQueryExecutionStatus(status);
+    return status;
+}
+export function validateQueryExecutionStatus(status) {
+    if (status.executionId.asU128() === 0n || status.startedAtMicros === 0n)
+        throw new InvalidError("query execution identity and start time must be nonzero");
+    const terminal = status.state === "completed" ||
+        status.state === "cancelled" ||
+        status.state === "failed" ||
+        status.state === "expired";
+    if ((terminal &&
+        (status.finishedAtMicros === undefined ||
+            status.finishedAtMicros < status.startedAtMicros)) ||
+        (!terminal && status.finishedAtMicros !== undefined))
+        throw new InvalidError("query execution finish time does not match its state");
+    if ((status.state === "failed") !== (status.error !== undefined))
+        throw new InvalidError("query execution error must be present exactly for failed state");
+}
+export function encodeQueryStatusReplyFrame(reply) {
+    return encodeNamed(reply.kind === "ok"
+        ? mapOf([["Ok", encodeQueryExecutionStatus(reply.status)]])
+        : mapOf([["Err", encodeQueryError(reply.error)]]));
+}
+export function decodeQueryStatusReply(value, context) {
+    const [tag, body] = singleVariantTag(value, context);
+    if (tag === "Ok")
+        return { kind: "ok", status: decodeQueryExecutionStatus(expectMap(body, context), context) };
+    if (tag === "Err")
+        return { kind: "err", error: decodeQueryError(body, context) };
+    throw new CodecError(`unknown query status reply \`${tag}\``, context, "reply");
+}
+export function decodeQueryStatusReplyFrame(bytes) {
+    return decodeQueryStatusReply(decodeOne(bytes, "QueryStatusReply"), "QueryStatusReply");
+}
+function decodeWord(map, key, context, allowed) {
+    const value = field.requiredString(map, key, context);
+    if (!allowed.includes(value))
+        throw new CodecError(`field \`${key}\` has unsupported value \`${value}\``, context, key);
+    return value;
+}
+function decodeOptionalWord(map, key, context, allowed) {
+    const value = field.optionalString(map, key, context);
+    if (value === undefined)
+        return undefined;
+    if (!allowed.includes(value))
+        throw new CodecError(`field \`${key}\` has unsupported value \`${value}\``, context, key);
+    return value;
+}
+function asU64(value, context) {
+    if (typeof value === "bigint" && value >= 0n)
+        return value;
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+        return BigInt(value);
+    throw new CodecError("value must fit u64", context, "value");
+}
+function fixedBytes(value, length, context) {
+    if (value.length !== length)
+        throw new CodecError(`expected ${String(length)} bytes`, context, "bytes");
+    return value;
+}
+function validateName(value) {
+    if (value.length === 0 ||
+        byteLength(value) > MAX_QUERY_NAME_BYTES ||
+        value.trim() !== value ||
+        hasControlCharacter(value))
+        throw new InvalidError("query name is invalid");
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+function hasControlCharacter(value) {
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code < 32 || code === 127)
+            return true;
+    }
+    return false;
+}
+function hasDisallowedSqlControl(value) {
+    for (const character of value) {
+        if (hasControlCharacter(character) &&
+            character !== "\n" &&
+            character !== "\r" &&
+            character !== "\t")
+            return true;
+    }
+    return false;
+}
+export function parseConsistency(value, context) {
+    if (value === "eventual" || value === "read_your_writes" || value === "strong")
+        return value;
+    throw new CodecError(`unknown consistency \`${value}\``, context, "consistency");
+}
+export function consistencyToWord(value) {
+    return value;
+}
+export function pageAtLeast(page, rowsOnPage) {
+    return page.offset === undefined ? undefined : page.offset + BigInt(rowsOnPage);
+}
+export function pageTotalPages(page) {
+    return page.total === undefined || page.limit === 0
+        ? undefined
+        : (page.total + BigInt(page.limit) - 1n) / BigInt(page.limit);
+}
+export function consistencyGateCheck(applied, required, consistency, what) {
+    return consistency === "eventual" || applied >= required
+        ? undefined
+        : { kind: "stale", what, applied, required };
 }
 //# sourceMappingURL=query.js.map