@ferricstore/ferricstore 0.5.0 → 0.5.2

package/dist/index.cjs

@@ -85,7 +85,7 @@ __export(index_exports, {
   WorkflowWorker: () => WorkflowWorker,
   classifyServerError: () => classifyServerError,
   complete: () => complete,
-  fail: () => fail,
+  fail: () => fail2,
   isOutcome: () => isOutcome,
   isReconnectableClosedConnectionError: () => isReconnectableClosedConnectionError,
   mapException: () => mapException,
@@ -107,7 +107,7 @@ function assertSafeVariadicDispatch(argumentCount, arrayCapability) {
 // src/native-adapter.ts
 var import_node_net3 = require("net");
 var import_node_tls3 = require("tls");
-var import_node_buffer31 = require("buffer");
+var import_node_buffer32 = require("buffer");
 
 // src/errors.ts
 var FerricStoreError = class extends Error {
@@ -1237,10 +1237,10 @@ var NativeFlowControl = class {
 
 // src/native-heartbeat.ts
 var NativeHeartbeat = class {
-  constructor(intervalMs, send, fail2) {
+  constructor(intervalMs, send, fail3) {
     this.intervalMs = intervalMs;
     this.send = send;
-    this.fail = fail2;
+    this.fail = fail3;
   }
   intervalMs;
   send;
@@ -1287,9 +1287,11 @@ var FLOW_QUERY_LANGUAGE_VERSION = "FQL1";
 var FLOW_QUERY_MAX_BYTES = 16 * 1024;
 var FLOW_QUERY_MAX_PARAMETERS = 64;
 var FLOW_QUERY_MAX_PARAMETER_NAME_BYTES = 128;
+var FLOW_QUERY_MAX_PARAMETER_VALUE_BYTES = 65535;
 var MIN_I64 = -(1n << 63n);
 var MAX_I64 = (1n << 63n) - 1n;
 var INDEX_ID = /^[A-Za-z0-9_.:-]{1,64}$/u;
+var PARAMETER_NAME = /^[A-Za-z0-9_.-]+$/u;
 function flowQueryArgs(query, params = {}) {
   validateFlowQueryText(query);
   const entries = flowQueryParameterEntries(params);
@@ -1343,9 +1345,34 @@ function validateFlowQueryIndexId(indexId) {
   }
 }
 function hasFlowExplainPrefix(query) {
-  const source = query.trimStart();
-  const prefix = source.slice(0, 7);
-  return prefix.toUpperCase() === "EXPLAIN" && (source.length === 7 || /[\t\n\r ]/u.test(source[7] ?? ""));
+  const source = trimFlowQueryAsciiWhitespaceStart(query);
+  return matchesFlowQueryAsciiKeyword(source, 0, "EXPLAIN") && (source.length === 7 || isFlowQueryAsciiWhitespaceCode(source.charCodeAt(7)));
+}
+function matchesFlowQueryAsciiKeyword(value, offset, keyword) {
+  if (offset < 0 || offset + keyword.length > value.length) return false;
+  for (let index = 0; index < keyword.length; index += 1) {
+    let actual = value.charCodeAt(offset + index);
+    if (actual >= 97 && actual <= 122) actual -= 32;
+    if (actual !== keyword.charCodeAt(index)) return false;
+  }
+  return true;
+}
+function trimFlowQueryAsciiWhitespaceStart(value) {
+  let start = 0;
+  while (start < value.length && isFlowQueryAsciiWhitespaceCode(value.charCodeAt(start))) {
+    start += 1;
+  }
+  return start === 0 ? value : value.slice(start);
+}
+function trimFlowQueryAsciiWhitespace(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && isFlowQueryAsciiWhitespaceCode(value.charCodeAt(start))) start += 1;
+  while (end > start && isFlowQueryAsciiWhitespaceCode(value.charCodeAt(end - 1))) end -= 1;
+  return start === 0 && end === value.length ? value : value.slice(start, end);
+}
+function isFlowQueryAsciiWhitespaceCode(code) {
+  return code === 32 || code === 9 || code === 10 || code === 13;
 }
 function flowQueryParameterEntries(params) {
   if (typeof params !== "object" || params == null || Array.isArray(params)) {
@@ -1371,19 +1398,26 @@ function flowQueryParameterEntries(params) {
 function validateFlowQueryParameterName(name) {
   validateUnicodeScalarText(name, "FLOW.QUERY parameter name");
   const size = import_node_buffer3.Buffer.byteLength(name, "utf8");
-  if (size === 0 || size > FLOW_QUERY_MAX_PARAMETER_NAME_BYTES) {
+  if (size === 0 || size > FLOW_QUERY_MAX_PARAMETER_NAME_BYTES || !PARAMETER_NAME.test(name)) {
     throw new TypeError(
-      `FLOW.QUERY parameter names must be 1..${FLOW_QUERY_MAX_PARAMETER_NAME_BYTES} bytes`
+      `FLOW.QUERY parameter names must be 1..${FLOW_QUERY_MAX_PARAMETER_NAME_BYTES} ASCII letters, digits, '_', '.', or '-'`
     );
   }
 }
 function normalizeFlowQueryParameter(value, name) {
   if (typeof value === "string") {
     validateUnicodeScalarText(value, `FLOW.QUERY parameter ${JSON.stringify(name)}`);
+    validateParameterValueSize(import_node_buffer3.Buffer.byteLength(value, "utf8"), name);
+    return value;
+  }
+  if (import_node_buffer3.Buffer.isBuffer(value)) {
+    validateParameterValueSize(value.byteLength, name);
     return value;
   }
-  if (import_node_buffer3.Buffer.isBuffer(value)) return value;
-  if (value instanceof Uint8Array) return import_node_buffer3.Buffer.from(value);
+  if (value instanceof Uint8Array) {
+    validateParameterValueSize(value.byteLength, name);
+    return import_node_buffer3.Buffer.from(value);
+  }
   if (typeof value === "boolean") return value;
   if (typeof value === "bigint" && value >= MIN_I64 && value <= MAX_I64) return value;
   if (typeof value === "number" && Number.isFinite(value)) {
@@ -1393,6 +1427,13 @@ function normalizeFlowQueryParameter(value, name) {
     `FLOW.QUERY parameter ${JSON.stringify(name)} must be text, bytes, boolean, a finite float, or a signed 64-bit integer`
   );
 }
+function validateParameterValueSize(size, name) {
+  if (size > FLOW_QUERY_MAX_PARAMETER_VALUE_BYTES) {
+    throw new TypeError(
+      `FLOW.QUERY parameter ${JSON.stringify(name)} exceeds ${FLOW_QUERY_MAX_PARAMETER_VALUE_BYTES} bytes`
+    );
+  }
+}
 function commandText(value, context) {
   if (typeof value === "string") {
     validateUnicodeScalarText(value, context);
@@ -5864,7 +5905,10 @@ function isDecodedRecord(value) {
 // src/protocol-flow-query-result.ts
 var CONTRACT = "ferric.flow.query.result/v1";
 var MAX_RECORDS = 100;
+var MIN_CURSOR_BYTES = 16;
 var MAX_CURSOR_BYTES = 4096;
+var CURSOR_PREFIX = import_node_buffer24.Buffer.from("fqc1_");
+var MAX_SIGNED_64 = (1n << 63n) - 1n;
 var RECORD_FIELDS = [
   "id",
   "type",
@@ -5928,9 +5972,13 @@ function decodeCompactFlowQueryResult(data, budget) {
   const usage = {};
   for (const field3 of USAGE_FIELDS) {
     const read = readU64(data, offset);
+    if (BigInt(read.value) > MAX_SIGNED_64) {
+      throw new FerricStoreError("compact FLOW.QUERY usage exceeds signed 64-bit range");
+    }
     usage[field3] = read.value;
     offset = read.offset;
   }
+  validateCompactUsage(usage);
   let result;
   if (kind === 0) {
     const page = readPage(data, offset);
@@ -5939,6 +5987,7 @@ function decodeCompactFlowQueryResult(data, budget) {
     const count = data.readUInt32BE(offset);
     offset += 4;
     if (count > MAX_RECORDS) throw new FerricStoreError("compact FLOW.QUERY page exceeds 100 records");
+    validateCompactRecordUsage(usage, count);
     consumeDecodeItems(count, budget);
     const records = new Array(count);
     for (let index = 0; index < count; index += 1) {
@@ -5948,7 +5997,13 @@ function decodeCompactFlowQueryResult(data, budget) {
     }
     result = { version: import_node_buffer24.Buffer.from(CONTRACT), records, page: page.value, quality, usage };
   } else if (kind === 1) {
+    if (usageInteger(usage, "result_records") !== 1n) {
+      throw new FerricStoreError("compact FLOW.QUERY count usage is inconsistent");
+    }
     const count = readU64(data, offset);
+    if (BigInt(count.value) > MAX_SIGNED_64) {
+      throw new FerricStoreError("compact FLOW.QUERY count exceeds signed 64-bit range");
+    }
     offset = count.offset;
     result = {
       version: import_node_buffer24.Buffer.from(CONTRACT),
@@ -5973,18 +6028,37 @@ function readPage(data, offset) {
   if (hasMoreCode === 0 && size === NULL_U32) {
     return { value: { has_more: false, cursor: null }, offset };
   }
-  if (hasMoreCode !== 1 || size === 0 || size === NULL_U32 || size > MAX_CURSOR_BYTES) {
+  if (hasMoreCode !== 1 || size < MIN_CURSOR_BYTES || size === NULL_U32 || size > MAX_CURSOR_BYTES) {
     throw new FerricStoreError("invalid compact FLOW.QUERY page cursor");
   }
   requireAvailable(data, offset, size);
+  const cursor = data.subarray(offset, offset + size);
+  if (!cursor.subarray(0, CURSOR_PREFIX.byteLength).equals(CURSOR_PREFIX) || !(0, import_node_buffer24.isUtf8)(cursor)) {
+    throw new FerricStoreError("invalid compact FLOW.QUERY page cursor");
+  }
   return {
     value: {
       has_more: true,
-      cursor: detachDecodedBinary(data.subarray(offset, offset + size), data.byteLength)
+      cursor: detachDecodedBinary(cursor, data.byteLength)
     },
     offset: offset + size
   };
 }
+function validateCompactUsage(usage) {
+  const scanned = usageInteger(usage, "scanned_entries");
+  if (usageInteger(usage, "hydrated_records") > scanned || usageInteger(usage, "duplicate_entries") > scanned || usageInteger(usage, "range_pages") > scanned + usageInteger(usage, "range_seeks") || usageInteger(usage, "residual_checks") > scanned * 12n) {
+    throw new FerricStoreError("compact FLOW.QUERY usage counters are inconsistent");
+  }
+}
+function validateCompactRecordUsage(usage, count) {
+  const resultRecords = usageInteger(usage, "result_records");
+  if (resultRecords !== BigInt(count) || resultRecords > usageInteger(usage, "scanned_entries")) {
+    throw new FerricStoreError("compact FLOW.QUERY record usage is inconsistent");
+  }
+}
+function usageInteger(usage, field3) {
+  return BigInt(usage[field3]);
+}
 function readRecord(data, offset, budget) {
   requireAvailable(data, offset, 4);
   const bitmap = data.readUInt32BE(offset);
@@ -8010,6 +8084,63 @@ function nativeStartupPayload(clientName, events) {
   };
 }
 
+// src/flow-query-deadline.ts
+var import_node_buffer31 = require("buffer");
+function withFlowQueryDeadline(command, timeoutMs, nowMs2) {
+  if (timeoutMs == null) return command;
+  if (command.opcode === OPCODES.pipeline) {
+    return withPipelineQueryDeadlines(command, timeoutMs, nowMs2);
+  }
+  if (command.opcode !== OPCODES.flowQuery) return command;
+  const payload = command.payload;
+  if (payload instanceof Map) {
+    const nextPayload = new Map(payload);
+    nextPayload.set("deadline_ms", flowQueryDeadlineMs(timeoutMs, nowMs2));
+    return { ...command, payload: nextPayload };
+  }
+  if (typeof payload !== "object" || payload == null || Array.isArray(payload) || import_node_buffer31.Buffer.isBuffer(payload) || payload instanceof Uint8Array) {
+    return command;
+  }
+  return {
+    ...command,
+    payload: {
+      ...payload,
+      deadline_ms: flowQueryDeadlineMs(timeoutMs, nowMs2)
+    }
+  };
+}
+function withPipelineQueryDeadlines(command, timeoutMs, nowMs2) {
+  const payload = plainRecord(command.payload);
+  if (payload == null) return command;
+  const rawCommands = payload.commands;
+  if (!Array.isArray(rawCommands)) return command;
+  let commands;
+  let deadlineMs;
+  for (let index = 0; index < rawCommands.length; index += 1) {
+    const rawItem = rawCommands[index];
+    const item = plainRecord(rawItem);
+    if (item?.opcode !== OPCODES.flowQuery) continue;
+    const body = plainRecord(item.body);
+    if (body == null) continue;
+    commands ??= rawCommands.slice();
+    deadlineMs ??= flowQueryDeadlineMs(timeoutMs, nowMs2);
+    commands[index] = { ...item, body: { ...body, deadline_ms: deadlineMs } };
+  }
+  return commands == null ? command : { ...command, payload: { ...payload, commands } };
+}
+function flowQueryDeadlineMs(timeoutMs, nowMs2) {
+  return Math.min(
+    Number.MAX_SAFE_INTEGER,
+    (nowMs2 ?? Date.now()) + Math.max(1, Math.ceil(timeoutMs))
+  );
+}
+function plainRecord(value) {
+  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer31.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return void 0;
+  }
+  return value;
+}
+
 // src/native-adapter.ts
 var NativeAdapter = class _NativeAdapter {
   socket;
@@ -8215,7 +8346,11 @@ var NativeAdapter = class _NativeAdapter {
     let frame;
     try {
       requestId = this.requestScheduler.nextRequestId();
-      frame = encodeRequest(command, requestId, this.capabilities.requestFrameBytes);
+      frame = encodeRequest(
+        withFlowQueryDeadline(command, timeoutMs),
+        requestId,
+        this.capabilities.requestFrameBytes
+      );
     } catch (error) {
       if (hasFlowControlCredit) this.flowControl.release(laneId);
       return Promise.reject(error instanceof Error ? error : new FerricStoreError(String(error), { raw: error }));
@@ -8360,10 +8495,10 @@ function executeCommandArgs(executor, args) {
 }
 
 // src/reconnecting-executor.ts
-var import_node_buffer33 = require("buffer");
+var import_node_buffer34 = require("buffer");
 
 // src/command-retry-policy.ts
-var import_node_buffer32 = require("buffer");
+var import_node_buffer33 = require("buffer");
 function isCasMutation(args) {
   const offset = commandName2(args[0]) === "COMMAND_EXEC" ? 1 : 0;
   const name = commandName2(args[offset]);
@@ -8377,8 +8512,8 @@ function isCasMutation(args) {
 }
 function commandName2(value) {
   if (typeof value === "string") return value.toUpperCase();
-  if (import_node_buffer32.Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return import_node_buffer32.Buffer.from(value).toString("utf8").toUpperCase();
+  if (import_node_buffer33.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return import_node_buffer33.Buffer.from(value).toString("utf8").toUpperCase();
   }
   return void 0;
 }
@@ -8590,15 +8725,15 @@ function normalizeNonNegativeInteger2(value, fallback) {
 }
 
 // src/topology.ts
-var import_node_buffer36 = require("buffer");
+var import_node_buffer37 = require("buffer");
 
 // src/topology-routing.ts
-var import_node_buffer35 = require("buffer");
+var import_node_buffer36 = require("buffer");
 
 // src/flow-partition-route-cache.ts
-var import_node_buffer34 = require("buffer");
+var import_node_buffer35 = require("buffer");
 var import_node_crypto = require("crypto");
-var AUTO_PREFIX = import_node_buffer34.Buffer.from("__flow_auto__:", "ascii");
+var AUTO_PREFIX = import_node_buffer35.Buffer.from("__flow_auto__:", "ascii");
 var MAX_CACHEABLE_PARTITION_BYTES = 4 * 1024;
 var MAX_CACHE_BYTES = 1 * 1024 * 1024;
 var MAX_CACHE_ENTRIES = 1024;
@@ -8608,10 +8743,10 @@ var cacheBytes = 0;
 var cacheHits = 0;
 var cacheMisses = 0;
 function flowLogicalPartitionRoutingKey(value) {
-  if (typeof value !== "string" && !import_node_buffer34.Buffer.isBuffer(value)) return void 0;
+  if (typeof value !== "string" && !import_node_buffer35.Buffer.isBuffer(value)) return void 0;
   const autoBucket = flowAutoBucket(value);
   if (autoBucket != null) return `{fa:${autoBucket}}`;
-  const bytes2 = import_node_buffer34.Buffer.isBuffer(value) ? value : import_node_buffer34.Buffer.from(value);
+  const bytes2 = import_node_buffer35.Buffer.isBuffer(value) ? value : import_node_buffer35.Buffer.from(value);
   if (bytes2.byteLength > MAX_CACHEABLE_PARTITION_BYTES) return hashRoute(bytes2);
   const cacheKey = bytes2.toString("base64");
   const cached = routeCache.get(cacheKey);
@@ -8685,7 +8820,7 @@ function routingKeyFromProtocolPayload(name, command) {
       "scope"
     ]) {
       const value = getField(command.payload, field3);
-      if (typeof value === "string" || import_node_buffer35.Buffer.isBuffer(value)) {
+      if (typeof value === "string" || import_node_buffer36.Buffer.isBuffer(value)) {
         return value;
       }
     }
@@ -8733,7 +8868,7 @@ function flowRoutingData(name, args) {
     if (typeof partition === "string" && partition.toUpperCase() !== "AUTO" && partition.toUpperCase() !== "MIXED") {
       return flowRoutingResult(flowLogicalPartitionRoutingKey(partition));
     }
-    if (import_node_buffer35.Buffer.isBuffer(partition)) {
+    if (import_node_buffer36.Buffer.isBuffer(partition)) {
       const text3 = partition.toString("utf8").toUpperCase();
       if (text3 !== "AUTO" && text3 !== "MIXED") {
         return flowRoutingResult(flowLogicalPartitionRoutingKey(partition));
@@ -8824,17 +8959,17 @@ function flowPartitionRoutingKeyFromCommand(command, claim) {
   return { handled: false };
 }
 function isRoutingKey(value) {
-  return typeof value === "string" || import_node_buffer35.Buffer.isBuffer(value);
+  return typeof value === "string" || import_node_buffer36.Buffer.isBuffer(value);
 }
 function flowAutoIdRoutingKey(value) {
-  if (typeof value !== "string" && !import_node_buffer35.Buffer.isBuffer(value)) {
+  if (typeof value !== "string" && !import_node_buffer36.Buffer.isBuffer(value)) {
     return void 0;
   }
-  const bucket = (import_node_buffer35.Buffer.isBuffer(value) ? crc32(value) : crc32Utf8(value)) & 255;
+  const bucket = (import_node_buffer36.Buffer.isBuffer(value) ? crc32(value) : crc32Utf8(value)) & 255;
   return `{fa:${bucket}}`;
 }
 function flowClaimLogicalPartitionRoutingKey(value) {
-  if (typeof value !== "string" && !import_node_buffer35.Buffer.isBuffer(value)) return void 0;
+  if (typeof value !== "string" && !import_node_buffer36.Buffer.isBuffer(value)) return void 0;
   const selector = commandPart(value);
   if (selector === "AUTO" || selector === "ANY") return void 0;
   if (selector === "GLOBAL") return "{f}";
@@ -8849,7 +8984,7 @@ function singleShardFlowClaimPartitionKey(values) {
   return keys.some((key) => key == null) ? void 0 : singleShardKey(keys);
 }
 function singleShardKey(keys) {
-  if (keys.length === 0 || keys.some((key) => typeof key !== "string" && !import_node_buffer35.Buffer.isBuffer(key))) {
+  if (keys.length === 0 || keys.some((key) => typeof key !== "string" && !import_node_buffer36.Buffer.isBuffer(key))) {
     return void 0;
   }
   const usable = keys;
@@ -8882,7 +9017,7 @@ function routedKeyGroups(keys, routeKey) {
   const groups = /* @__PURE__ */ new Map();
   for (let index = 0; index < keys.length; index += 1) {
     const key = keys[index];
-    if (typeof key !== "string" && !import_node_buffer35.Buffer.isBuffer(key)) return void 0;
+    if (typeof key !== "string" && !import_node_buffer36.Buffer.isBuffer(key)) return void 0;
     const route = routeKey(key);
     const groupKey = `${route.endpointKey}\0${route.laneId}`;
     const group = groups.get(groupKey);
@@ -9971,7 +10106,7 @@ var TopologyNativeAdapterPool = class _TopologyNativeAdapterPool {
 };
 
 // src/response-map-preservation.ts
-var import_node_buffer37 = require("buffer");
+var import_node_buffer38 = require("buffer");
 function toStringKeyMapPreservingValues(value) {
   if (value == null) return void 0;
   const result = {};
@@ -9981,7 +10116,7 @@ function toStringKeyMapPreservingValues(value) {
     }
     return result;
   }
-  if (typeof value === "object" && !Array.isArray(value) && !import_node_buffer37.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value === "object" && !Array.isArray(value) && !import_node_buffer38.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
     for (const [key, item] of Object.entries(value)) {
       setOwnValue(result, text(key), normalizeMapStructurePreservingBytes(item));
     }
@@ -9990,7 +10125,7 @@ function toStringKeyMapPreservingValues(value) {
   return void 0;
 }
 function normalizeMapStructurePreservingBytes(value) {
-  if (import_node_buffer37.Buffer.isBuffer(value) || value instanceof Uint8Array) return value;
+  if (import_node_buffer38.Buffer.isBuffer(value) || value instanceof Uint8Array) return value;
   if (value instanceof Map) {
     const result = {};
     for (const [key, item] of value.entries()) {
@@ -10012,7 +10147,7 @@ function normalizeMapStructurePreservingBytes(value) {
 }
 
 // src/native-kv-responses.ts
-var import_node_buffer38 = require("buffer");
+var import_node_buffer39 = require("buffer");
 function rateLimitResultFromResp(value) {
   if (!Array.isArray(value) || value.length !== 4) {
     throw new TypeError("RATELIMIT.ADD returned an unexpected response");
@@ -10069,13 +10204,13 @@ function fetchOrComputeResultFromResp(value, codec) {
 }
 function decodePayload(codec, value) {
   if (value == null) return null;
-  if (import_node_buffer38.Buffer.isBuffer(value)) return codec.decode(value);
-  if (value instanceof Uint8Array) return codec.decode(import_node_buffer38.Buffer.from(value));
-  if (typeof value === "string") return codec.decode(import_node_buffer38.Buffer.from(value));
+  if (import_node_buffer39.Buffer.isBuffer(value)) return codec.decode(value);
+  if (value instanceof Uint8Array) return codec.decode(import_node_buffer39.Buffer.from(value));
+  if (typeof value === "string") return codec.decode(import_node_buffer39.Buffer.from(value));
   return normalizeRefMeta(value);
 }
 function requiredResponseString(value, context) {
-  if (typeof value !== "string" && !import_node_buffer38.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value !== "string" && !import_node_buffer39.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
     throw new TypeError(`${context} returned an unexpected response`);
   }
   const result = text(value);
@@ -10092,7 +10227,7 @@ function requiredNonNegativeInteger(value, context) {
   return result;
 }
 function responseBytes(value, context) {
-  if (typeof value !== "string" && !import_node_buffer38.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value !== "string" && !import_node_buffer39.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
     throw new TypeError(`${context} returned an unexpected response`);
   }
   return bytes(value);
@@ -10775,7 +10910,7 @@ function groupAutoPartitionItems(items) {
 }
 
 // src/client-values.ts
-var import_node_buffer39 = require("buffer");
+var import_node_buffer40 = require("buffer");
 async function valueMGetEntries(client, refs, options = {}) {
   const refCount = refs.length;
   if (refCount === 0) {
@@ -10810,12 +10945,12 @@ async function valueMGetEntries(client, refs, options = {}) {
     const item = response[index];
     if (item == null) {
       entries[index] = { found: false };
-    } else if (import_node_buffer39.Buffer.isBuffer(item)) {
+    } else if (import_node_buffer40.Buffer.isBuffer(item)) {
       entries[index] = { found: true, value: client.codec.decode(item) };
     } else if (item instanceof Uint8Array) {
-      entries[index] = { found: true, value: client.codec.decode(import_node_buffer39.Buffer.from(item)) };
+      entries[index] = { found: true, value: client.codec.decode(import_node_buffer40.Buffer.from(item)) };
     } else if (typeof item === "string") {
-      entries[index] = { found: true, value: client.codec.decode(import_node_buffer39.Buffer.from(item)) };
+      entries[index] = { found: true, value: client.codec.decode(import_node_buffer40.Buffer.from(item)) };
     } else {
       entries[index] = { found: true, value: item };
     }
@@ -10824,10 +10959,10 @@ async function valueMGetEntries(client, refs, options = {}) {
 }
 
 // src/auto-batch.ts
-var import_node_buffer41 = require("buffer");
+var import_node_buffer42 = require("buffer");
 
 // src/auto-batch-ordering.ts
-var import_node_buffer40 = require("buffer");
+var import_node_buffer41 = require("buffer");
 function autoBatchOrderingPlan(batch) {
   const accesses = /* @__PURE__ */ new Map();
   const fallbackDependencies = [];
@@ -10942,13 +11077,13 @@ function flowManyAutoBatchIds(command, name) {
     return fixedFlowItemIds(
       command,
       mixed ? 4 : 3,
-      (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && isFencingToken(command[itemIndex + (mixed ? 2 : 1)]) && import_node_buffer40.Buffer.isBuffer(command[itemIndex + (mixed ? 3 : 2)])
+      (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && isFencingToken(command[itemIndex + (mixed ? 2 : 1)]) && import_node_buffer41.Buffer.isBuffer(command[itemIndex + (mixed ? 3 : 2)])
     );
   }
   return fixedFlowItemIds(
     command,
     mixed ? 4 : 3,
-    (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer40.Buffer.isBuffer(command[itemIndex + (mixed ? 2 : 1)]) && isFencingToken(command[itemIndex + (mixed ? 3 : 2)])
+    (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer41.Buffer.isBuffer(command[itemIndex + (mixed ? 2 : 1)]) && isFencingToken(command[itemIndex + (mixed ? 3 : 2)])
   );
 }
 function createManyAutoBatchIds(command) {
@@ -10961,7 +11096,7 @@ function createManyAutoBatchIds(command) {
       const ids = fixedFlowItemIds(
         command,
         width,
-        (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer40.Buffer.isBuffer(command[itemIndex + width - 1]),
+        (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer41.Buffer.isBuffer(command[itemIndex + width - 1]),
         markerIndex
       );
       if (ids != null) return ids;
@@ -10979,7 +11114,7 @@ function extendedCreateManyAutoBatchIds(command, markerIndex) {
   let cursor = markerIndex + 2;
   for (let itemIndex = 0; itemIndex < itemCount; itemIndex += 1) {
     const id = command[cursor];
-    if (!isAutoBatchResourceValue(id) || !isAutoBatchResourceValue(command[cursor + 1]) || !import_node_buffer40.Buffer.isBuffer(command[cursor + 2])) return void 0;
+    if (!isAutoBatchResourceValue(id) || !isAutoBatchResourceValue(command[cursor + 1]) || !import_node_buffer41.Buffer.isBuffer(command[cursor + 2])) return void 0;
     ids.push(id);
     cursor += 3;
     const afterValues = skipExtendedNamedItems(command, cursor, true);
@@ -10998,7 +11133,7 @@ function skipExtendedNamedItems(command, countIndex, encodedValues) {
   for (let index = 0; index < count; index += 1) {
     const name = command[firstItem + index * 2];
     const value = command[firstItem + index * 2 + 1];
-    if (!isAutoBatchResourceValue(name) || (encodedValues ? !import_node_buffer40.Buffer.isBuffer(value) : !isAutoBatchResourceValue(value))) return void 0;
+    if (!isAutoBatchResourceValue(name) || (encodedValues ? !import_node_buffer41.Buffer.isBuffer(value) : !isAutoBatchResourceValue(value))) return void 0;
   }
   return firstItem + count * 2;
 }
@@ -11013,7 +11148,7 @@ function runStepsManyAutoBatchIds(command) {
         ids.push(item);
         continue;
       }
-      if (typeof item !== "object" || item == null || Array.isArray(item) || import_node_buffer40.Buffer.isBuffer(item)) return void 0;
+      if (typeof item !== "object" || item == null || Array.isArray(item) || import_node_buffer41.Buffer.isBuffer(item)) return void 0;
       const id = item.id;
       if (!isAutoBatchResourceValue(id)) return void 0;
       ids.push(id);
@@ -11054,7 +11189,7 @@ function flowValuePutOwner(command, start) {
 }
 var flowValuePutOptionTokens = /* @__PURE__ */ new Set(["NAME", "NOW", "OVERRIDE", "OWNER_FLOW_ID", "PARTITION", "TTL", "TTL_MS"]);
 function isAutoBatchResourceValue(value) {
-  return typeof value === "string" || import_node_buffer40.Buffer.isBuffer(value);
+  return typeof value === "string" || import_node_buffer41.Buffer.isBuffer(value);
 }
 function isFencingToken(value) {
   return typeof value === "number" && Number.isSafeInteger(value) || typeof value === "bigint";
@@ -11063,7 +11198,7 @@ function nonNegativeItemCount(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
 }
 function autoBatchResourceKey(namespace, value) {
-  return `${namespace}:${import_node_buffer40.Buffer.from(value).toString("base64")}`;
+  return `${namespace}:${import_node_buffer41.Buffer.from(value).toString("base64")}`;
 }
 function autoBatchCommandName(command) {
   return commandView(command).name ?? null;
@@ -11472,13 +11607,13 @@ function claimFailure(error) {
 }
 
 // src/client-flow-support.ts
-var import_node_buffer52 = require("buffer");
+var import_node_buffer55 = require("buffer");
 
 // src/flow-query-builder.ts
-var import_node_buffer43 = require("buffer");
+var import_node_buffer44 = require("buffer");
 
 // src/flow-query-metadata.ts
-var import_node_buffer42 = require("buffer");
+var import_node_buffer43 = require("buffer");
 var MAX_FLOW_QUERY_METADATA_KEY_BYTES = 64;
 function normalizeStateMeta(value, state) {
   if (value == null) return {};
@@ -11503,7 +11638,7 @@ function normalizeStateMeta(value, state) {
 function metadataEntries(value, context) {
   const entries = objectEntries(value ?? {}, context).map(([rawName, item]) => {
     const name = rawName.trim();
-    const size = import_node_buffer42.Buffer.byteLength(name, "utf8");
+    const size = import_node_buffer43.Buffer.byteLength(name, "utf8");
     if (size === 0 || size > MAX_FLOW_QUERY_METADATA_KEY_BYTES || name.startsWith("__")) {
       throw new TypeError(`${context} key is invalid or reserved`);
     }
@@ -11527,7 +11662,7 @@ function objectEntries(value, context) {
   return keys.map((key) => [key, value[key]]);
 }
 function isPlainRecord(value) {
-  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer42.Buffer.isBuffer(value)) {
+  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer43.Buffer.isBuffer(value)) {
     return false;
   }
   const prototype = Object.getPrototypeOf(value);
@@ -11597,7 +11732,7 @@ var FlowCollectionQuery = class {
     const states = /* @__PURE__ */ new Set();
     for (const [rawState, metadata] of objectEntries(values, "stateMeta")) {
       const state = requiredText(rawState, "stateMeta state").trim();
-      const stateBytes = import_node_buffer43.Buffer.byteLength(state, "utf8");
+      const stateBytes = import_node_buffer44.Buffer.byteLength(state, "utf8");
       if (stateBytes === 0 || stateBytes > MAX_FLOW_QUERY_STATE_BYTES) {
         throw new TypeError(
           `stateMeta state names must be 1..${MAX_FLOW_QUERY_STATE_BYTES} bytes`
@@ -11776,7 +11911,7 @@ function requiredPartition(value) {
       "FLOW.QUERY convenience methods require a partition key"
     );
   }
-  const size = import_node_buffer43.Buffer.byteLength(value, "utf8");
+  const size = import_node_buffer44.Buffer.byteLength(value, "utf8");
   if (size === 0 || size > MAX_FLOW_QUERY_PARTITION_BYTES) {
     throw new TypeError(
       `FLOW.QUERY partition key must be 1..${MAX_FLOW_QUERY_PARTITION_BYTES} bytes`
@@ -11824,20 +11959,23 @@ function requiredText(value, context) {
   return value;
 }
 function queryParameter(value, context) {
-  if (typeof value === "string" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "number" || import_node_buffer43.Buffer.isBuffer(value)) {
+  if (typeof value === "string" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "number" || import_node_buffer44.Buffer.isBuffer(value)) {
     return value;
   }
   throw new TypeError(`${context} must be a scalar FLOW.QUERY parameter`);
 }
 
 // src/flow-query-response.ts
-var import_node_buffer45 = require("buffer");
+var import_node_buffer48 = require("buffer");
+
+// src/flow-query-diagnostic-response.ts
+var import_node_buffer46 = require("buffer");
 
 // src/flow-query-response-validation.ts
-var import_node_buffer44 = require("buffer");
+var import_node_buffer45 = require("buffer");
 function requiredMap2(value, context) {
   if (value instanceof Map) return value;
-  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer44.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer45.Buffer.isBuffer(value) || value instanceof Uint8Array) {
     throw decodeError(`${context} must be a map`, value);
   }
   return value;
@@ -11894,7 +12032,7 @@ function normalizeMetadataValue(value, context, budget, ancestors, depth) {
     if (!value.isWellFormed()) throw decodeError(`${context} contains invalid text`, value);
     return value;
   }
-  if (import_node_buffer44.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+  if (import_node_buffer45.Buffer.isBuffer(value) || value instanceof Uint8Array) {
     const decoded = strictText2(value);
     if (decoded == null) throw decodeError(`${context} contains invalid UTF-8`, value);
     return decoded;
@@ -11973,7 +12111,7 @@ function optionalText2(mapping, name, context) {
 }
 function requiredBoundedText2(mapping, name, context, maximumBytes) {
   const value = requiredText2(mapping, name, context);
-  if (import_node_buffer44.Buffer.byteLength(value, "utf8") > maximumBytes) {
+  if (import_node_buffer45.Buffer.byteLength(value, "utf8") > maximumBytes) {
     throw decodeError(
       `${context} ${name} exceeds ${maximumBytes} bytes`,
       mapping
@@ -11986,7 +12124,7 @@ function boundedText(value, context, maximumBytes) {
   if (decoded == null || decoded.length === 0) {
     throw decodeError(`${context} must be non-empty text`, value);
   }
-  if (import_node_buffer44.Buffer.byteLength(decoded, "utf8") > maximumBytes) {
+  if (import_node_buffer45.Buffer.byteLength(decoded, "utf8") > maximumBytes) {
     throw decodeError(`${context} exceeds ${maximumBytes} bytes`, value);
   }
   return decoded;
@@ -12040,10 +12178,10 @@ function positiveBoundedInteger(value, maximum, context) {
 function hasKey(mapping, name) {
   if (!(mapping instanceof Map)) return Object.hasOwn(mapping, name);
   if (mapping.has(name)) return true;
-  const binaryName = import_node_buffer44.Buffer.from(name);
+  const binaryName = import_node_buffer45.Buffer.from(name);
   for (const key of mapping.keys()) {
-    if (import_node_buffer44.Buffer.isBuffer(key) && key.equals(binaryName)) return true;
-    if (key instanceof Uint8Array && import_node_buffer44.Buffer.from(key).equals(binaryName))
+    if (import_node_buffer45.Buffer.isBuffer(key) && key.equals(binaryName)) return true;
+    if (key instanceof Uint8Array && import_node_buffer45.Buffer.from(key).equals(binaryName))
       return true;
   }
   return false;
@@ -12054,7 +12192,7 @@ function decodeError(message, raw) {
 function strictText2(value) {
   if (typeof value === "string")
     return value.isWellFormed() ? value : void 0;
-  if (import_node_buffer44.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+  if (import_node_buffer45.Buffer.isBuffer(value) || value instanceof Uint8Array) {
     try {
       return new TextDecoder("utf-8", { fatal: true }).decode(value);
     } catch {
@@ -12087,189 +12225,35 @@ var FlowQueryError = class extends FerricStoreError {
   }
 };
 
-// src/flow-query-response.ts
-var FLOW_QUERY_RESULT_CONTRACT = "ferric.flow.query.result/v1";
-var FLOW_EXPLAIN_CONTRACT = "ferric.flow.explain/v1";
-var FLOW_QUERY_INDEXES_CONTRACT = "ferric.flow.query.indexes/v1";
-var USAGE_FIELDS2 = [
-  ["range_seeks", "rangeSeeks"],
-  ["range_pages", "rangePages"],
-  ["scanned_entries", "scannedEntries"],
-  ["scanned_bytes", "scannedBytes"],
-  ["hydrated_records", "hydratedRecords"],
-  ["residual_checks", "residualChecks"],
-  ["duplicate_entries", "duplicateEntries"],
-  ["result_records", "resultRecords"],
-  ["response_bytes", "responseBytes"],
-  ["memory_high_water_bytes", "memoryHighWaterBytes"],
-  ["wall_time_us", "wallTimeUs"]
-];
-var MAX_SIGNED_64 = (1n << 63n) - 1n;
-var MAX_UNSIGNED_64 = (1n << 64n) - 1n;
-function decodeFlowQueryResult(value) {
-  const result = decodeFlowQueryResponse(value, (mapping) => freezeMap(mapping));
-  if (result.kind === "records") {
-    return Object.freeze({
-      kind: "records",
-      version: FLOW_QUERY_RESULT_CONTRACT,
-      records: Object.freeze(result.records),
-      page: result.page,
-      quality: result.quality,
-      usage: result.usage,
-      raw: result.raw
-    });
-  }
-  return Object.freeze({
-    kind: "count",
-    version: FLOW_QUERY_RESULT_CONTRACT,
-    count: result.count,
-    quality: result.quality,
-    usage: result.usage,
-    raw: result.raw
-  });
-}
-function decodeFlowQueryRecords(value, decodeRecord) {
-  const result = decodeFlowQueryResponse(
-    value,
-    (mapping, index) => decodeRecord(mapping instanceof Map ? freezeMap(mapping) : mapping, index)
-  );
-  if (result.kind === "count") {
-    throw new FerricStoreError("Flow record convenience query returned a count result", {
-      raw: result.raw
-    });
-  }
-  return result.records;
-}
-function decodeFlowQueryResponse(value, decodeRecord) {
-  const mapping = requiredMap2(value, "FLOW.QUERY result");
-  requireContract(mapping, "version", FLOW_QUERY_RESULT_CONTRACT, "FLOW.QUERY result");
-  const quality = decodeQuality(field(mapping, "quality"));
-  const usage = decodeUsage(field(mapping, "usage"));
-  const hasRecords = hasKey(mapping, "records");
-  const hasCount = hasKey(mapping, "result");
-  if (hasRecords === hasCount) {
-    throw decodeError("FLOW.QUERY result must contain exactly one records or count shape", value);
-  }
-  const raw = freezeMap(mapping);
-  if (hasRecords) {
-    const rawRecords = field(mapping, "records");
-    if (!Array.isArray(rawRecords) || rawRecords.length > 100) {
-      throw decodeError("FLOW.QUERY records must be an array of at most 100 maps", value);
-    }
-    const records = new Array(rawRecords.length);
-    for (let index = 0; index < rawRecords.length; index += 1) {
-      if (!Object.hasOwn(rawRecords, index)) {
-        throw decodeError("FLOW.QUERY records must be a dense array", value);
-      }
-      records[index] = decodeRecord(
-        requiredMap2(rawRecords[index], `FLOW.QUERY record ${index}`),
-        index
-      );
-    }
-    if (usage.resultRecords !== records.length) {
-      throw decodeError("FLOW.QUERY usage result_records does not match records", value);
-    }
-    return {
-      kind: "records",
-      records,
-      page: decodePage(field(mapping, "page")),
-      quality,
-      usage,
-      raw
-    };
-  }
-  if (hasKey(mapping, "page")) {
-    throw decodeError("FLOW.QUERY count result contains an unexpected page", value);
-  }
-  const countResult = requiredMap2(field(mapping, "result"), "FLOW.QUERY count result");
-  if (requiredText2(countResult, "kind", "FLOW.QUERY count result") !== "count") {
-    throw decodeError("FLOW.QUERY count result kind must be count", value);
-  }
-  const count = boundedInteger(
-    field(countResult, "value"),
-    MAX_SIGNED_64,
-    "FLOW.QUERY count value"
-  );
-  if (usage.resultRecords !== 1) {
-    throw decodeError("FLOW.QUERY count usage result_records must be 1", value);
-  }
-  return {
-    kind: "count",
-    count,
-    quality,
-    usage,
-    raw
-  };
-}
-function decodeFlowExplainResult(value) {
-  const mapping = requiredMap2(value, "FLOW.QUERY explain");
-  requireContract(mapping, "version", FLOW_EXPLAIN_CONTRACT, "FLOW.QUERY explain");
-  const queryFingerprint = requiredText2(mapping, "query_fingerprint", "FLOW.QUERY explain");
-  if (!/^[0-9a-f]{64}$/iu.test(queryFingerprint)) {
-    throw decodeError("FLOW.QUERY explain query_fingerprint is invalid", value);
-  }
-  const status = requiredText2(mapping, "status", "FLOW.QUERY explain");
-  if (status !== "planned" && status !== "rejected" && status !== "executed") {
-    throw decodeError(`FLOW.QUERY explain status ${JSON.stringify(status)} is unsupported`, value);
-  }
-  const plan = freezeMetadataMap(
-    requiredMap2(field(mapping, "plan"), "FLOW.QUERY explain plan"),
-    "FLOW.QUERY explain plan"
-  );
-  const estimate = freezeMetadataMap(
-    requiredMap2(field(mapping, "estimate"), "FLOW.QUERY explain estimate"),
-    "FLOW.QUERY explain estimate"
-  );
-  const bounds = freezeMetadataMap(
-    requiredMap2(field(mapping, "bounds"), "FLOW.QUERY explain bounds"),
-    "FLOW.QUERY explain bounds"
-  );
-  const actualValue = field(mapping, "actual");
-  let actual;
-  if (status === "executed") {
-    if (actualValue == null) {
-      throw decodeError("FLOW.QUERY executed explain is missing actual usage", value);
-    }
-    actual = decodeUsage(actualValue);
-  } else if (actualValue != null) {
-    throw decodeError("FLOW.QUERY non-executed explain contains actual usage", value);
-  }
-  const diagnosticValue = field(mapping, "diagnostic");
-  let diagnostic;
-  if (status === "rejected") {
-    diagnostic = tryDecodeFlowQueryError(diagnosticValue);
-    if (diagnostic == null) {
-      throw decodeError("FLOW.QUERY rejected explain has an invalid diagnostic", value);
-    }
-  } else if (diagnosticValue != null) {
-    throw decodeError("FLOW.QUERY non-rejected explain contains a diagnostic", value);
-  }
-  return Object.freeze({
-    version: FLOW_EXPLAIN_CONTRACT,
-    queryFingerprint,
-    status,
-    plan,
-    estimate,
-    bounds,
-    actual,
-    diagnostic,
-    raw: freezeMap(mapping)
-  });
-}
+// src/flow-query-diagnostic-response.ts
+var MIN_SIGNED_64 = -(1n << 63n);
+var MAX_SIGNED_642 = (1n << 63n) - 1n;
+var DIAGNOSTIC_TEXT_BYTES = 1024;
+var DIAGNOSTIC_CONTEXT_ENTRIES = 16;
+var DIAGNOSTIC_CONTEXT_LIST_ITEMS = 32;
+var DIAGNOSTIC_CONTEXT_KEY_BYTES = 128;
+var DIAGNOSTIC_CONTEXT_DEPTH = 6;
+var DIAGNOSTIC_CONTEXT_NODES = 512;
 function tryDecodeFlowQueryError(value, cause) {
   try {
     const mapping = requiredMap2(value, "FLOW.QUERY diagnostic");
-    const contextValue = field(mapping, "context");
-    const context = contextValue == null ? void 0 : freezeMetadataMap(
-      requiredMap2(contextValue, "FLOW.QUERY diagnostic context"),
-      "FLOW.QUERY diagnostic context"
-    );
+    const context = decodeDiagnosticContext(field(mapping, "context"));
     const position = decodePosition(field(mapping, "position"));
     return new FlowQueryError({
-      code: requiredText2(mapping, "code", "FLOW.QUERY diagnostic"),
-      message: requiredText2(mapping, "message", "FLOW.QUERY diagnostic"),
-      detail: optionalText2(mapping, "detail", "FLOW.QUERY diagnostic"),
-      hint: optionalText2(mapping, "hint", "FLOW.QUERY diagnostic"),
+      code: requiredBoundedText2(
+        mapping,
+        "code",
+        "FLOW.QUERY diagnostic",
+        DIAGNOSTIC_TEXT_BYTES
+      ),
+      message: requiredBoundedText2(
+        mapping,
+        "message",
+        "FLOW.QUERY diagnostic",
+        DIAGNOSTIC_TEXT_BYTES
+      ),
+      detail: optionalDiagnosticText(mapping, "detail"),
+      hint: optionalDiagnosticText(mapping, "hint"),
       retryable: requiredBoolean(mapping, "retryable", "FLOW.QUERY diagnostic"),
       safeToRetry: requiredBoolean(mapping, "safe_to_retry", "FLOW.QUERY diagnostic"),
       retryAfterMs: nonNegativeInteger(
@@ -12286,49 +12270,724 @@ function tryDecodeFlowQueryError(value, cause) {
     throw error;
   }
 }
-function decodeFlowQueryIndexStatus(value) {
-  const mapping = requiredMap2(value, "FLOW.QUERY.INDEXES");
-  requireContract(
-    mapping,
-    "contract_version",
-    FLOW_QUERY_INDEXES_CONTRACT,
-    "FLOW.QUERY.INDEXES"
-  );
-  const registry = requiredMap2(field(mapping, "registry"), "FLOW.QUERY.INDEXES registry");
-  const services = freezeMetadataMap(
-    requiredMap2(field(mapping, "services"), "FLOW.QUERY.INDEXES services"),
-    "FLOW.QUERY.INDEXES services"
-  );
+function optionalDiagnosticText(mapping, name) {
+  const value = optionalText2(mapping, name, "FLOW.QUERY diagnostic");
+  if (value != null && import_node_buffer46.Buffer.byteLength(value, "utf8") > DIAGNOSTIC_TEXT_BYTES) {
+    throw decodeError(
+      `FLOW.QUERY diagnostic ${name} exceeds ${DIAGNOSTIC_TEXT_BYTES} bytes`,
+      mapping
+    );
+  }
+  return value;
+}
+function decodeDiagnosticContext(value) {
+  if (value == null) return void 0;
+  const mapping = requiredMap2(value, "FLOW.QUERY diagnostic context");
+  const size = mapping instanceof Map ? mapping.size : Object.keys(mapping).length;
+  if (size > DIAGNOSTIC_CONTEXT_ENTRIES) {
+    throw decodeError("FLOW.QUERY diagnostic context contains too many entries", value);
+  }
+  validateDiagnosticContextValue(
+    mapping,
+    DIAGNOSTIC_CONTEXT_DEPTH,
+    { remaining: DIAGNOSTIC_CONTEXT_NODES }
+  );
+  return freezeMetadataMap(mapping, "FLOW.QUERY diagnostic context");
+}
+function validateDiagnosticContextValue(value, depth, budget) {
+  consumeDiagnosticContextNode(value, budget);
+  if (value == null || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (Number.isSafeInteger(value)) return;
+    throw decodeError("FLOW.QUERY diagnostic context contains an invalid integer", value);
+  }
+  if (typeof value === "bigint") {
+    if (value >= MIN_SIGNED_64 && value <= MAX_SIGNED_642) return;
+    throw decodeError("FLOW.QUERY diagnostic context contains an invalid integer", value);
+  }
+  const text3 = diagnosticContextText(value);
+  if (text3 != null) {
+    if (import_node_buffer46.Buffer.byteLength(text3, "utf8") <= DIAGNOSTIC_TEXT_BYTES) return;
+    throw decodeError("FLOW.QUERY diagnostic context contains oversized text", value);
+  }
+  if (depth <= 0) {
+    throw decodeError("FLOW.QUERY diagnostic context exceeds its maximum depth", value);
+  }
+  if (Array.isArray(value)) {
+    if (value.length > DIAGNOSTIC_CONTEXT_LIST_ITEMS) {
+      throw decodeError("FLOW.QUERY diagnostic context list is too large", value);
+    }
+    for (let index = 0; index < value.length; index += 1) {
+      if (!Object.hasOwn(value, index)) {
+        throw decodeError("FLOW.QUERY diagnostic context list must be dense", value);
+      }
+      validateDiagnosticContextValue(value[index], depth - 1, budget);
+    }
+    return;
+  }
+  if (value instanceof Map || isDiagnosticContextRecord(value)) {
+    const entries = value instanceof Map ? value.entries() : Object.entries(value);
+    const size = value instanceof Map ? value.size : Object.keys(value).length;
+    if (size > DIAGNOSTIC_CONTEXT_ENTRIES) {
+      throw decodeError("FLOW.QUERY diagnostic context map is too large", value);
+    }
+    for (const [rawKey, item] of entries) {
+      const key = diagnosticContextText(rawKey);
+      if (key == null || key.length === 0 || import_node_buffer46.Buffer.byteLength(key, "utf8") > DIAGNOSTIC_CONTEXT_KEY_BYTES) {
+        throw decodeError("FLOW.QUERY diagnostic context contains an invalid key", value);
+      }
+      validateDiagnosticContextValue(item, depth - 1, budget);
+    }
+    return;
+  }
+  throw decodeError("FLOW.QUERY diagnostic context contains an unsupported value", value);
+}
+function consumeDiagnosticContextNode(value, budget) {
+  if (budget.remaining <= 0) {
+    throw decodeError("FLOW.QUERY diagnostic context exceeds its node limit", value);
+  }
+  budget.remaining -= 1;
+}
+function diagnosticContextText(value) {
+  if (typeof value === "string") return value.isWellFormed() ? value : void 0;
+  if (!import_node_buffer46.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) return void 0;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(value);
+  } catch {
+    return void 0;
+  }
+}
+function isDiagnosticContextRecord(value) {
+  if (typeof value !== "object" || value == null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function decodePosition(value) {
+  if (value == null) return void 0;
+  const mapping = requiredMap2(value, "FLOW.QUERY diagnostic position");
+  return Object.freeze({
+    byte: positiveInteger(field(mapping, "byte"), "FLOW.QUERY diagnostic position byte"),
+    line: positiveInteger(field(mapping, "line"), "FLOW.QUERY diagnostic position line"),
+    column: positiveInteger(
+      field(mapping, "column"),
+      "FLOW.QUERY diagnostic position column"
+    )
+  });
+}
+
+// src/flow-query-index-contract.ts
+var import_node_buffer47 = require("buffer");
+var FLOW_QUERY_BUILD_PHASES = ["pending", "snapshot", "backfill", "done"];
+var FLOW_QUERY_VALIDATION_PHASES = [
+  "pending",
+  "source",
+  "index",
+  "counter",
+  "cleanup",
+  "done"
+];
+var FLOW_QUERY_RETIREMENT_PHASES = [
+  "pending",
+  "fence",
+  "index",
+  "counter",
+  "reverse",
+  "cleanup",
+  "done"
+];
+var IDENTIFIER = /^[A-Za-z0-9_.:-]+$/u;
+var UNQUOTED_METADATA = /^[A-Za-z0-9_-]+$/u;
+var ATTRIBUTE_SELECTOR = /^attribute\['((?:[^']|'')*)'\]$/u;
+var STATE_META_SELECTOR = /^state_meta\['((?:[^']|'')*)'\]\['((?:[^']|'')*)'\]$/u;
+var INTEGER_FIELDS = /* @__PURE__ */ new Set([
+  "version",
+  "priority",
+  "created_at_ms",
+  "updated_at_ms",
+  "next_run_at_ms",
+  "lease_deadline_ms",
+  "attempts",
+  "max_active_ms"
+]);
+var BUILTIN_FIELDS = /* @__PURE__ */ new Set([
+  ...INTEGER_FIELDS,
+  "partition_key",
+  "run_id",
+  "event_id",
+  "type",
+  "state",
+  "run_state",
+  "parent_flow_id",
+  "root_flow_id",
+  "correlation_id"
+]);
+var RETIREMENT_PROGRESS_FIELDS = [
+  "phase_counts",
+  "current_phases",
+  "completed_shards",
+  "total_shards",
+  "deleted_entries",
+  "deleted_bytes",
+  "rewritten_reverse_rows"
+];
+function validateFlowQueryIndexContract(status, expectedId) {
+  let previousId;
+  let previousVersion;
+  for (const index of status.indexes) {
+    const version = BigInt(index.version);
+    if (previousId != null && (index.id < previousId || index.id === previousId && previousVersion != null && version <= previousVersion)) {
+      fail("indexes must be uniquely sorted by id and version", status.raw);
+    }
+    if (expectedId != null && index.id !== expectedId) {
+      fail("filtered indexes do not match the requested id", status.raw);
+    }
+    previousId = index.id;
+    previousVersion = version;
+    validateIndex(index, status);
+  }
+  if (expectedId != null && status.indexes.length === 0) {
+    fail("filtered indexes do not match the requested id", status.raw);
+  }
+  const hasUnavailableStatistics = status.indexes.some(
+    (index) => index.statistics.status === "unavailable"
+  );
+  if (status.services.statisticsStore === "unavailable") {
+    if (status.indexes.some((index) => index.statistics.status !== "unavailable")) {
+      fail("statistics must be unavailable when the service is unavailable", status.raw);
+    }
+  } else if (hasUnavailableStatistics) {
+    fail("statistics cannot be unavailable while the service is ready", status.raw);
+  }
+}
+function validateIndex(index, status) {
+  if (!IDENTIFIER.test(index.id) || index.workloads.some((workload) => !IDENTIFIER.test(workload))) {
+    fail("index identity contains invalid characters", index.raw);
+  }
+  const first = index.fields[0];
+  if (first?.name !== "partition_key" || first.direction !== "asc" || first.encoding !== "hashed") {
+    fail("index must begin with partition_key asc hashed", index.raw);
+  }
+  let attributeFields = 0;
+  for (const indexField of index.fields) {
+    if (indexField.encoding === "hashed" && indexField.direction !== "asc") {
+      fail("hashed index fields must be ascending", index.raw);
+    }
+    const kind = fieldKind(indexField.name);
+    if (kind == null) fail("index contains an unsupported field selector", index.raw);
+    if (indexField.encoding === "ordered" && kind !== "integer") {
+      fail("ordered index fields must be integers", index.raw);
+    }
+    if (kind === "attribute") attributeFields += 1;
+  }
+  if (attributeFields > 1) fail("index may contain at most one attribute field", index.raw);
+  for (const prefix of index.countPrefixes) {
+    if (index.fields.slice(0, prefix).some((field3) => field3.encoding !== "hashed")) {
+      fail("count prefixes may cover only hashed fields", index.raw);
+    }
+  }
+  if (index.coveringFields.length > 0) {
+    if (index.coveringFields.some((field3) => fieldKind(field3) == null)) {
+      fail("index contains an unsupported covering field selector", index.raw);
+    }
+    const required = /* @__PURE__ */ new Set(["run_id", "version", ...index.fields.map((field3) => field3.name)]);
+    if ([...required].some((field3) => !index.coveringFields.includes(field3))) {
+      fail("index covering fields omit an identity or index field", index.raw);
+    }
+  }
+  if (index.countPrefixes.length > 0 !== (index.format.counter != null)) {
+    fail("index counter format is inconsistent with count prefixes", index.raw);
+  }
+  validateProgress(index.build, FLOW_QUERY_BUILD_PHASES, "build");
+  validateProgress(index.validation, FLOW_QUERY_VALIDATION_PHASES, "validation");
+  if (index.retirement.status === "not_applicable") {
+    if (RETIREMENT_PROGRESS_FIELDS.some((name) => hasKey(index.retirement.raw, name))) {
+      fail("not_applicable retirement must not contain progress", index.retirement.raw);
+    }
+  } else {
+    const retirement = index.retirement;
+    if (retirement.phaseCounts == null || retirement.currentPhases == null || retirement.completedShards == null || retirement.totalShards == null) {
+      fail("retirement progress is incomplete", retirement.raw);
+    }
+    validateProgress(
+      {
+        phaseCounts: retirement.phaseCounts,
+        currentPhases: retirement.currentPhases,
+        completedShards: retirement.completedShards,
+        totalShards: retirement.totalShards,
+        raw: retirement.raw
+      },
+      FLOW_QUERY_RETIREMENT_PHASES,
+      "retirement"
+    );
+  }
+  const totals = new Set(
+    [
+      index.coverage.totalShards,
+      index.build.totalShards,
+      index.validation.totalShards,
+      ...index.retirement.totalShards == null ? [] : [index.retirement.totalShards]
+    ].map(indexInteger)
+  );
+  if (totals.size !== 1) fail("index shard totals are inconsistent", index.raw);
+  if (!sameIndexInteger(index.coverage.completeShards, index.build.completedShards)) {
+    fail("coverage and build completion are inconsistent", index.raw);
+  }
+  if (index.coverage.validation !== index.validation.status) {
+    fail("coverage and validation status are inconsistent", index.raw);
+  }
+  const queryable = index.state === "active" && sameIndexInteger(
+    index.coverage.completeShards,
+    index.coverage.totalShards
+  ) && index.coverage.validation === "passed";
+  if (index.queryable !== queryable) fail("index queryable flag is inconsistent", index.raw);
+  validateLifecycle(index);
+  validateValidation(index);
+  validateStatistics(index, status);
+}
+function validateProgress(progress, phases, section) {
+  const entries = Object.entries(progress.phaseCounts);
+  if (entries.length === 0 || entries.some(
+    ([phase, count]) => !phases.includes(phase) || indexInteger(count) <= 0n
+  ) || entries.reduce((sum, [, count]) => sum + indexInteger(count), 0n) !== indexInteger(progress.totalShards)) {
+    fail(`${section} phase_counts are invalid`, progress.raw);
+  }
+  const current = phases.filter((phase) => Object.hasOwn(progress.phaseCounts, phase));
+  if (current.length !== progress.currentPhases.length || current.some((phase, position) => phase !== progress.currentPhases[position])) {
+    fail(`${section} current_phases are inconsistent`, progress.raw);
+  }
+  if (!sameIndexInteger(
+    progress.completedShards,
+    progress.phaseCounts.done ?? 0
+  )) {
+    fail(`${section} completed_shards is inconsistent`, progress.raw);
+  }
+}
+function validateLifecycle(index) {
+  const built = sameIndexInteger(
+    index.build.completedShards,
+    index.build.totalShards
+  );
+  const validation = index.validation.status;
+  const retirement = index.retirement.status;
+  const valid = index.state === "building" && !built && validation === "pending" && retirement === "not_applicable" || index.state === "validating" && built && (validation === "pending" || validation === "passed") && retirement === "not_applicable" || index.state === "active" && built && validation === "passed" && retirement === "not_applicable" || index.state === "retiring" && built && validation !== "pending" && retirement !== "not_applicable" || index.state === "failed" && validation !== "pending" && retirement !== "not_applicable";
+  if (!valid) fail("index lifecycle fields are inconsistent", index.raw);
+}
+function validateValidation(index) {
+  const validation = index.validation;
+  const valid = validation.status === "pending" && indexInteger(validation.mismatches) === 0n && validation.failureReason == null && validation.validatedAtMs == null || validation.status === "passed" && indexInteger(validation.mismatches) === 0n && validation.failureReason == null && validation.validatedAtMs != null || validation.status === "failed" && indexInteger(validation.mismatches) > 0n && Boolean(validation.failureReason) && validation.validatedAtMs != null;
+  if (!valid) fail("validation status fields are inconsistent", validation.raw);
+}
+function validateStatistics(index, status) {
+  const statistics = index.statistics;
+  const times = [
+    statistics.oldestCollectedAtMs,
+    statistics.newestCollectedAtMs,
+    statistics.oldestAgeMs,
+    statistics.newestAgeMs
+  ];
+  if (indexInteger(statistics.samples) === 0n) {
+    if (statistics.status !== "missing" && statistics.status !== "unavailable" || times.some((value) => value != null)) {
+      fail("empty statistics fields are inconsistent", statistics.raw);
+    }
+    return;
+  }
+  if (times.some((value) => value == null)) {
+    fail("sampled statistics require timestamps and ages", statistics.raw);
+  }
+  const [oldest, newest, oldestAge, newestAge] = times;
+  if (indexInteger(oldest) > indexInteger(newest) || indexInteger(oldestAge) !== indexAge(status.observedAtMs, oldest) || indexInteger(newestAge) !== indexAge(status.observedAtMs, newest)) {
+    fail("statistics timestamps or ages are inconsistent", statistics.raw);
+  }
+  const expected = sameIndexInteger(statistics.freshSamples, statistics.samples) ? ["fresh"] : indexInteger(statistics.freshSamples) === 0n ? indexInteger(statistics.futureSamples) > 0n ? ["stale", "future"] : ["stale"] : ["mixed"];
+  if (!expected.includes(statistics.status)) {
+    fail("statistics status does not match sample counters", statistics.raw);
+  }
+}
+function fieldKind(name) {
+  if (BUILTIN_FIELDS.has(name)) return INTEGER_FIELDS.has(name) ? "integer" : "keyword";
+  const parts = name.split(".");
+  if (parts.length === 2 && parts[0] === "attribute" && validUnquoted(parts[1] ?? "")) return "attribute";
+  if (parts.length === 3 && parts[0] === "state_meta" && validUnquoted(parts[1] ?? "") && validUnquoted(parts[2] ?? "")) return "state_meta";
+  const attribute = ATTRIBUTE_SELECTOR.exec(name);
+  if (attribute != null) {
+    const metadata = (attribute[1] ?? "").replaceAll("''", "'");
+    if (validMetadata(metadata, true) && name === externalSelector("attribute", metadata)) return "attribute";
+  }
+  const stateMeta = STATE_META_SELECTOR.exec(name);
+  if (stateMeta != null) {
+    const state = (stateMeta[1] ?? "").replaceAll("''", "'");
+    const metadata = (stateMeta[2] ?? "").replaceAll("''", "'");
+    if (validMetadata(state, false) && validMetadata(metadata, true) && name === externalSelector("state_meta", state, metadata)) return "state_meta";
+  }
+  return void 0;
+}
+function validUnquoted(value) {
+  return !value.startsWith("__") && UNQUOTED_METADATA.test(value) && import_node_buffer47.Buffer.byteLength(value, "ascii") <= 64;
+}
+function validMetadata(value, rejectReserved) {
+  return value.length > 0 && import_node_buffer47.Buffer.byteLength(value, "utf8") <= 64 && (!rejectReserved || !value.startsWith("__"));
+}
+function externalSelector(root, ...segments) {
+  return segments.every(validUnquoted) ? [root, ...segments].join(".") : root + segments.map((segment) => `['${segment.replaceAll("'", "''")}']`).join("");
+}
+function sameIndexInteger(left, right) {
+  return indexInteger(left) === indexInteger(right);
+}
+function indexAge(observedAtMs, collectedAtMs) {
+  const age = indexInteger(observedAtMs) - indexInteger(collectedAtMs);
+  return age < 0n ? 0n : age;
+}
+function indexInteger(value) {
+  return BigInt(value);
+}
+function fail(message, raw) {
+  throw decodeError(`FLOW.QUERY.INDEXES ${message}`, raw);
+}
+
+// src/flow-query-index-decode.ts
+var MAX_UNSIGNED_64 = (1n << 64n) - 1n;
+function decodeUniqueTextArray(value, context, maximum, maximumBytes) {
+  if (!Array.isArray(value) || value.length > maximum) {
+    throw decodeError(`${context} must be a bounded array`, value);
+  }
+  const result = new Array(value.length);
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      throw decodeError(`${context} must be dense`, value);
+    }
+    const text3 = boundedText(
+      value[index],
+      `${context} entry ${index}`,
+      maximumBytes
+    );
+    if (seen.has(text3)) {
+      throw decodeError(`${context} contains duplicates`, value);
+    }
+    seen.add(text3);
+    result[index] = text3;
+  }
+  return Object.freeze(result);
+}
+function requiredChoice(mapping, name, context, choices) {
+  const value = requiredBoundedText2(mapping, name, context, 64);
+  if (!choices.includes(value)) {
+    throw decodeError(`${context} ${name} is unsupported`, mapping);
+  }
+  return value;
+}
+function optionalBoundedText(mapping, name, context, maximumBytes) {
+  const value = field(mapping, name);
+  if (value == null) return void 0;
+  return boundedText(value, `${context} ${name}`, maximumBytes);
+}
+function optionalIndexInteger(mapping, name, context) {
+  const value = field(mapping, name);
+  return value == null ? void 0 : unsignedIndexInteger(value, `${context} ${name}`);
+}
+function indexCounter(mapping, name, section) {
+  return unsignedIndexInteger(
+    field(mapping, name),
+    `FLOW.QUERY.INDEXES index ${section} ${name}`
+  );
+}
+function unsignedIndexInteger(value, context) {
+  return boundedInteger(value, MAX_UNSIGNED_64, context);
+}
+function positiveIndexInteger(value, context) {
+  return positiveBoundedInteger(value, MAX_UNSIGNED_64, context);
+}
+function indexInteger2(value) {
+  return BigInt(value);
+}
+
+// src/flow-query-index-lifecycle-response.ts
+function decodeIndexCoverage(value) {
+  const context = "FLOW.QUERY.INDEXES index coverage";
+  const mapping = requiredMap2(value, context);
+  const completeShards = unsignedIndexInteger(
+    field(mapping, "complete_shards"),
+    `${context} complete_shards`
+  );
+  const totalShards = positiveIndexInteger(
+    field(mapping, "total_shards"),
+    `${context} total_shards`
+  );
+  if (indexInteger2(completeShards) > indexInteger2(totalShards)) {
+    throw decodeError(`${context} complete_shards exceeds total_shards`, value);
+  }
+  return Object.freeze({
+    completeShards,
+    totalShards,
+    validation: requiredChoice(mapping, "validation", context, [
+      "pending",
+      "passed",
+      "failed"
+    ]),
+    raw: freezeMap(mapping)
+  });
+}
+function decodeIndexBuild(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY.INDEXES index build");
+  const progress = decodeIndexProgress(
+    mapping,
+    "build",
+    FLOW_QUERY_BUILD_PHASES
+  );
+  return Object.freeze({
+    ...progress,
+    scannedRecords: indexCounter(mapping, "scanned_records", "build"),
+    writtenEntries: indexCounter(mapping, "written_entries", "build"),
+    writtenBytes: indexCounter(mapping, "written_bytes", "build")
+  });
+}
+function decodeIndexValidation(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY.INDEXES index validation");
+  if (!hasKey(mapping, "failure_reason") || !hasKey(mapping, "validated_at_ms")) {
+    throw decodeError(
+      "FLOW.QUERY.INDEXES index validation is missing nullable fields",
+      value
+    );
+  }
+  const progress = decodeIndexProgress(
+    mapping,
+    "validation",
+    FLOW_QUERY_VALIDATION_PHASES
+  );
+  return Object.freeze({
+    ...progress,
+    status: requiredChoice(
+      mapping,
+      "status",
+      "FLOW.QUERY.INDEXES index validation",
+      ["pending", "passed", "failed"]
+    ),
+    checkedRecords: indexCounter(mapping, "checked_records", "validation"),
+    checkedEntries: indexCounter(mapping, "checked_entries", "validation"),
+    mismatches: indexCounter(mapping, "mismatches", "validation"),
+    failureReason: optionalBoundedText(
+      mapping,
+      "failure_reason",
+      "FLOW.QUERY.INDEXES index validation",
+      128
+    ),
+    validatedAtMs: optionalIndexInteger(
+      mapping,
+      "validated_at_ms",
+      "FLOW.QUERY.INDEXES index validation"
+    )
+  });
+}
+function decodeIndexRetirement(value) {
+  const context = "FLOW.QUERY.INDEXES index retirement";
+  const mapping = requiredMap2(value, context);
+  const status = requiredChoice(mapping, "status", context, [
+    "not_applicable",
+    "pending",
+    "complete"
+  ]);
+  if (status === "not_applicable") {
+    return Object.freeze({ status, raw: freezeMap(mapping) });
+  }
+  const completedShards = unsignedIndexInteger(
+    field(mapping, "completed_shards"),
+    `${context} completed_shards`
+  );
+  const totalShards = positiveIndexInteger(
+    field(mapping, "total_shards"),
+    `${context} total_shards`
+  );
+  if (indexInteger2(completedShards) > indexInteger2(totalShards)) {
+    throw decodeError(
+      `${context} completed_shards exceeds total_shards`,
+      mapping
+    );
+  }
+  return Object.freeze({
+    status,
+    phaseCounts: decodePhaseCounts(
+      field(mapping, "phase_counts"),
+      "retirement"
+    ),
+    currentPhases: decodeAllowedPhases(
+      field(mapping, "current_phases"),
+      "retirement",
+      FLOW_QUERY_RETIREMENT_PHASES
+    ),
+    completedShards,
+    totalShards,
+    deletedEntries: indexCounter(mapping, "deleted_entries", "retirement"),
+    deletedBytes: indexCounter(mapping, "deleted_bytes", "retirement"),
+    rewrittenReverseRows: indexCounter(
+      mapping,
+      "rewritten_reverse_rows",
+      "retirement"
+    ),
+    raw: freezeMap(mapping)
+  });
+}
+function decodeIndexStatistics(value) {
+  const context = "FLOW.QUERY.INDEXES index statistics";
+  const mapping = requiredMap2(value, context);
+  for (const name of [
+    "oldest_collected_at_ms",
+    "newest_collected_at_ms",
+    "oldest_age_ms",
+    "newest_age_ms"
+  ]) {
+    if (!hasKey(mapping, name)) {
+      throw decodeError(
+        `${context} is missing required nullable fields`,
+        value
+      );
+    }
+  }
+  const samples = indexCounter(mapping, "samples", "statistics");
+  const freshSamples = indexCounter(mapping, "fresh_samples", "statistics");
+  const staleSamples = indexCounter(mapping, "stale_samples", "statistics");
+  const futureSamples = indexCounter(mapping, "future_samples", "statistics");
+  if (indexInteger2(freshSamples) + indexInteger2(staleSamples) !== indexInteger2(samples) || indexInteger2(futureSamples) > indexInteger2(staleSamples)) {
+    throw decodeError(`${context} counters are inconsistent`, value);
+  }
+  return Object.freeze({
+    status: requiredChoice(mapping, "status", context, [
+      "fresh",
+      "stale",
+      "future",
+      "mixed",
+      "missing",
+      "unavailable"
+    ]),
+    samples,
+    freshSamples,
+    staleSamples,
+    futureSamples,
+    oldestCollectedAtMs: optionalIndexInteger(
+      mapping,
+      "oldest_collected_at_ms",
+      context
+    ),
+    newestCollectedAtMs: optionalIndexInteger(
+      mapping,
+      "newest_collected_at_ms",
+      context
+    ),
+    oldestAgeMs: optionalIndexInteger(mapping, "oldest_age_ms", context),
+    newestAgeMs: optionalIndexInteger(mapping, "newest_age_ms", context),
+    raw: freezeMap(mapping)
+  });
+}
+function decodeIndexProgress(mapping, section, allowedPhases) {
+  const context = `FLOW.QUERY.INDEXES index ${section}`;
+  const completedShards = unsignedIndexInteger(
+    field(mapping, "completed_shards"),
+    `${context} completed_shards`
+  );
+  const totalShards = positiveIndexInteger(
+    field(mapping, "total_shards"),
+    `${context} total_shards`
+  );
+  if (indexInteger2(completedShards) > indexInteger2(totalShards)) {
+    throw decodeError(
+      `${context} completed_shards exceeds total_shards`,
+      mapping
+    );
+  }
+  return Object.freeze({
+    scope: requiredChoice(mapping, "scope", context, ["catalog_build"]),
+    phaseCounts: decodePhaseCounts(field(mapping, "phase_counts"), section),
+    currentPhases: decodeAllowedPhases(
+      field(mapping, "current_phases"),
+      section,
+      allowedPhases
+    ),
+    completedShards,
+    totalShards,
+    raw: freezeMap(mapping)
+  });
+}
+function decodePhaseCounts(value, section) {
+  const context = `FLOW.QUERY.INDEXES index ${section} phase_counts`;
+  const mapping = requiredMap2(value, context);
+  const entries = mapping instanceof Map ? [...mapping.entries()] : Object.entries(mapping);
+  if (entries.length > 16) {
+    throw decodeError(`${context} contains too many entries`, value);
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const [rawPhase, rawCount] of entries) {
+    const phase = boundedText(rawPhase, `${context} phase`, 64);
+    if (Object.hasOwn(result, phase)) {
+      throw decodeError(`${context} contains duplicate phases`, value);
+    }
+    result[phase] = unsignedIndexInteger(rawCount, `${context} ${phase}`);
+  }
+  return Object.freeze(result);
+}
+function decodeAllowedPhases(value, section, allowed) {
+  const phases = decodeUniqueTextArray(
+    value,
+    `FLOW.QUERY.INDEXES index ${section} current_phases`,
+    allowed.length,
+    64
+  );
+  if (phases.some((phase) => !allowed.includes(phase))) {
+    throw decodeError(
+      `FLOW.QUERY.INDEXES index ${section} current_phases are invalid`,
+      value
+    );
+  }
+  return phases;
+}
+
+// src/flow-query-index-response.ts
+var FLOW_QUERY_INDEXES_CONTRACT = "ferric.flow.query.indexes/v1";
+function decodeFlowQueryIndexStatus(value, expectedId) {
+  const mapping = requiredMap2(value, "FLOW.QUERY.INDEXES");
+  requireContract(
+    mapping,
+    "contract_version",
+    FLOW_QUERY_INDEXES_CONTRACT,
+    "FLOW.QUERY.INDEXES"
+  );
+  const registry = requiredMap2(
+    field(mapping, "registry"),
+    "FLOW.QUERY.INDEXES registry"
+  );
+  const services = decodeIndexServices(field(mapping, "services"));
   const rawIndexes = field(mapping, "indexes");
   if (!Array.isArray(rawIndexes) || rawIndexes.length > 32) {
-    throw decodeError("FLOW.QUERY.INDEXES indexes must contain at most 32 entries", value);
+    throw decodeError(
+      "FLOW.QUERY.INDEXES indexes must contain at most 32 entries",
+      value
+    );
   }
   const indexes = new Array(rawIndexes.length);
   for (let index = 0; index < rawIndexes.length; index += 1) {
     if (!Object.hasOwn(rawIndexes, index)) {
-      throw decodeError("FLOW.QUERY.INDEXES indexes must be a dense array", value);
+      throw decodeError(
+        "FLOW.QUERY.INDEXES indexes must be a dense array",
+        value
+      );
     }
     indexes[index] = decodeIndex(rawIndexes[index], index);
   }
-  return Object.freeze({
+  const status = Object.freeze({
     contractVersion: FLOW_QUERY_INDEXES_CONTRACT,
-    observedAtMs: nonNegativeInteger(
+    observedAtMs: unsignedIndexInteger(
       field(mapping, "observed_at_ms"),
       "FLOW.QUERY.INDEXES observed_at_ms"
     ),
-    statisticsMaxAgeMs: nonNegativeInteger(
+    statisticsMaxAgeMs: unsignedIndexInteger(
       field(mapping, "statistics_max_age_ms"),
       "FLOW.QUERY.INDEXES statistics_max_age_ms"
     ),
     registry: Object.freeze({
-      epoch: boundedInteger(
+      epoch: unsignedIndexInteger(
         field(registry, "epoch"),
-        MAX_UNSIGNED_64,
         "FLOW.QUERY.INDEXES epoch"
       ),
-      catalogVersion: positiveBoundedInteger(
+      catalogVersion: positiveIndexInteger(
         field(registry, "catalog_version"),
-        MAX_UNSIGNED_64,
         "FLOW.QUERY.INDEXES catalog_version"
       )
     }),
@@ -12336,24 +12995,155 @@ function decodeFlowQueryIndexStatus(value) {
     indexes: Object.freeze(indexes),
     raw: freezeMap(mapping)
   });
+  validateFlowQueryIndexContract(status, expectedId);
+  return status;
 }
 function decodeIndex(value, index) {
   const mapping = requiredMap2(value, `FLOW.QUERY.INDEXES index ${index}`);
+  const fields = decodeIndexFields(field(mapping, "fields"));
   return Object.freeze({
-    id: requiredText2(mapping, "id", "FLOW.QUERY.INDEXES index"),
-    version: positiveBoundedInteger(
+    id: requiredBoundedText2(mapping, "id", "FLOW.QUERY.INDEXES index", 64),
+    version: positiveIndexInteger(
       field(mapping, "version"),
-      MAX_UNSIGNED_64,
       "FLOW.QUERY.INDEXES index version"
     ),
-    buildId: requiredText2(mapping, "build_id", "FLOW.QUERY.INDEXES index"),
-    state: requiredText2(mapping, "state", "FLOW.QUERY.INDEXES index"),
-    queryable: requiredBoolean(mapping, "queryable", "FLOW.QUERY.INDEXES index"),
+    buildId: requiredBoundedText2(
+      mapping,
+      "build_id",
+      "FLOW.QUERY.INDEXES index",
+      128
+    ),
+    source: requiredChoice(mapping, "source", "FLOW.QUERY.INDEXES index", [
+      "runs"
+    ]),
+    state: requiredChoice(mapping, "state", "FLOW.QUERY.INDEXES index", [
+      "building",
+      "validating",
+      "active",
+      "retiring",
+      "failed"
+    ]),
+    queryable: requiredBoolean(
+      mapping,
+      "queryable",
+      "FLOW.QUERY.INDEXES index"
+    ),
+    fields,
+    workloads: decodeUniqueTextArray(
+      field(mapping, "workloads"),
+      "FLOW.QUERY.INDEXES index workloads",
+      16,
+      64
+    ),
+    countPrefixes: decodeCountPrefixes(
+      field(mapping, "count_prefixes"),
+      fields.length
+    ),
     coveringFields: decodeCoveringFields(mapping),
     format: decodeIndexFormat(mapping),
+    coverage: decodeIndexCoverage(field(mapping, "coverage")),
+    build: decodeIndexBuild(field(mapping, "build")),
+    validation: decodeIndexValidation(field(mapping, "validation")),
+    retirement: decodeIndexRetirement(field(mapping, "retirement")),
+    statistics: decodeIndexStatistics(field(mapping, "statistics")),
     raw: freezeMap(mapping)
   });
 }
+function decodeIndexServices(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY.INDEXES services");
+  const choices = ["ready", "unavailable"];
+  return Object.freeze({
+    registry: requiredChoice(
+      mapping,
+      "registry",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    lifecycleWorker: requiredChoice(
+      mapping,
+      "lifecycle_worker",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    statisticsStore: requiredChoice(
+      mapping,
+      "statistics_store",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    statisticsWorker: requiredChoice(
+      mapping,
+      "statistics_worker",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    raw: freezeMap(mapping)
+  });
+}
+function decodeIndexFields(value) {
+  const context = "FLOW.QUERY.INDEXES index fields";
+  if (!Array.isArray(value) || value.length < 2 || value.length > 8) {
+    throw decodeError(`${context} must contain 2 to 8 entries`, value);
+  }
+  const fields = new Array(value.length);
+  const names = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      throw decodeError(`${context} must be dense`, value);
+    }
+    const mapping = requiredMap2(
+      value[index],
+      `FLOW.QUERY.INDEXES index field ${index}`
+    );
+    const name = requiredBoundedText2(
+      mapping,
+      "name",
+      "FLOW.QUERY.INDEXES index field",
+      512
+    );
+    if (names.has(name)) {
+      throw decodeError(`${context} contain duplicates`, value);
+    }
+    names.add(name);
+    fields[index] = Object.freeze({
+      name,
+      direction: requiredChoice(
+        mapping,
+        "direction",
+        "FLOW.QUERY.INDEXES index field",
+        ["asc", "desc"]
+      ),
+      encoding: requiredChoice(
+        mapping,
+        "encoding",
+        "FLOW.QUERY.INDEXES index field",
+        ["hashed", "ordered"]
+      ),
+      raw: freezeMap(mapping)
+    });
+  }
+  return Object.freeze(fields);
+}
+function decodeCountPrefixes(value, fieldCount) {
+  const context = "FLOW.QUERY.INDEXES index count_prefixes";
+  if (!Array.isArray(value) || value.length > fieldCount) {
+    throw decodeError(`${context} are invalid`, value);
+  }
+  const prefixes = new Array(value.length);
+  let previous = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      throw decodeError(`${context} must be dense`, value);
+    }
+    const prefix = positiveInteger(value[index], `${context} entry`);
+    if (prefix > fieldCount || prefix <= previous) {
+      throw decodeError(`${context} are invalid`, value);
+    }
+    prefixes[index] = prefix;
+    previous = prefix;
+  }
+  return Object.freeze(prefixes);
+}
 function decodeCoveringFields(mapping) {
   const raw = field(mapping, "covering_fields");
   if (!Array.isArray(raw) || raw.length > 32) {
@@ -12366,7 +13156,10 @@ function decodeCoveringFields(mapping) {
   const seen = /* @__PURE__ */ new Set();
   for (let index = 0; index < raw.length; index += 1) {
     if (!Object.hasOwn(raw, index)) {
-      throw decodeError("FLOW.QUERY.INDEXES index covering_fields must be dense", raw);
+      throw decodeError(
+        "FLOW.QUERY.INDEXES index covering_fields must be dense",
+        raw
+      );
     }
     const value = boundedText(
       raw[index],
@@ -12374,7 +13167,10 @@ function decodeCoveringFields(mapping) {
       512
     );
     if (seen.has(value)) {
-      throw decodeError("FLOW.QUERY.INDEXES index covering_fields contains duplicates", raw);
+      throw decodeError(
+        "FLOW.QUERY.INDEXES index covering_fields contains duplicates",
+        raw
+      );
     }
     seen.add(value);
     fields[index] = value;
@@ -12382,30 +13178,341 @@ function decodeCoveringFields(mapping) {
   return Object.freeze(fields);
 }
 function decodeIndexFormat(mapping) {
-  const raw = requiredMap2(field(mapping, "format"), "FLOW.QUERY.INDEXES index format");
+  const raw = requiredMap2(
+    field(mapping, "format"),
+    "FLOW.QUERY.INDEXES index format"
+  );
   if (!hasKey(raw, "counter")) {
-    throw decodeError("FLOW.QUERY.INDEXES index format counter is missing", raw);
+    throw decodeError(
+      "FLOW.QUERY.INDEXES index format counter is missing",
+      raw
+    );
   }
   const counterValue = field(raw, "counter");
-  const counter = counterValue === null ? void 0 : boundedText(counterValue, "FLOW.QUERY.INDEXES index format counter", 128);
+  const counter = counterValue === null ? void 0 : boundedText(
+    counterValue,
+    "FLOW.QUERY.INDEXES index format counter",
+    128
+  );
   return Object.freeze({
-    queryRow: requiredBoundedText2(raw, "query_row", "FLOW.QUERY.INDEXES index format", 128),
-    key: requiredBoundedText2(raw, "key", "FLOW.QUERY.INDEXES index format", 128),
-    entry: requiredBoundedText2(raw, "entry", "FLOW.QUERY.INDEXES index format", 128),
-    reverse: requiredBoundedText2(raw, "reverse", "FLOW.QUERY.INDEXES index format", 128),
+    queryRow: requiredBoundedText2(
+      raw,
+      "query_row",
+      "FLOW.QUERY.INDEXES index format",
+      128
+    ),
+    key: requiredBoundedText2(
+      raw,
+      "key",
+      "FLOW.QUERY.INDEXES index format",
+      128
+    ),
+    entry: requiredBoundedText2(
+      raw,
+      "entry",
+      "FLOW.QUERY.INDEXES index format",
+      128
+    ),
+    reverse: requiredBoundedText2(
+      raw,
+      "reverse",
+      "FLOW.QUERY.INDEXES index format",
+      128
+    ),
     counter,
     raw: freezeMap(raw)
   });
 }
+
+// src/flow-query-response.ts
+var FLOW_QUERY_RESULT_CONTRACT = "ferric.flow.query.result/v1";
+var FLOW_EXPLAIN_CONTRACT = "ferric.flow.explain/v1";
+var USAGE_FIELDS2 = [
+  ["range_seeks", "rangeSeeks"],
+  ["range_pages", "rangePages"],
+  ["scanned_entries", "scannedEntries"],
+  ["scanned_bytes", "scannedBytes"],
+  ["hydrated_records", "hydratedRecords"],
+  ["residual_checks", "residualChecks"],
+  ["duplicate_entries", "duplicateEntries"],
+  ["result_records", "resultRecords"],
+  ["response_bytes", "responseBytes"],
+  ["memory_high_water_bytes", "memoryHighWaterBytes"],
+  ["wall_time_us", "wallTimeUs"]
+];
+var MAX_SIGNED_643 = (1n << 63n) - 1n;
+var QUALITY_VALUES2 = {
+  exactness: ["authoritative", "projected_exact", "exact", "not_applicable"],
+  freshness: ["current", "projection_watermark", "not_applicable"],
+  coverage: ["complete", "unavailable"],
+  pagination: ["none", "complete", "authenticated_seek", "live_seek"]
+};
+function decodeFlowQueryResult(value) {
+  const result = decodeFlowQueryResponse(value, (mapping) => freezeMap(mapping));
+  if (result.kind === "records") {
+    return Object.freeze({
+      kind: "records",
+      version: FLOW_QUERY_RESULT_CONTRACT,
+      records: Object.freeze(result.records),
+      page: result.page,
+      quality: result.quality,
+      usage: result.usage,
+      raw: result.raw
+    });
+  }
+  return Object.freeze({
+    kind: "count",
+    version: FLOW_QUERY_RESULT_CONTRACT,
+    count: result.count,
+    quality: result.quality,
+    usage: result.usage,
+    raw: result.raw
+  });
+}
+function decodeFlowQueryRecords(value, decodeRecord) {
+  const result = decodeFlowQueryResponse(
+    value,
+    (mapping, index) => decodeRecord(mapping instanceof Map ? freezeMap(mapping) : mapping, index)
+  );
+  if (result.kind === "count") {
+    throw new FerricStoreError("Flow record convenience query returned a count result", {
+      raw: result.raw
+    });
+  }
+  return result.records;
+}
+function decodeFlowQueryResponse(value, decodeRecord) {
+  const mapping = requiredMap2(value, "FLOW.QUERY result");
+  requireContract(mapping, "version", FLOW_QUERY_RESULT_CONTRACT, "FLOW.QUERY result");
+  const quality = decodeQuality(field(mapping, "quality"));
+  const usage = decodeUsage(field(mapping, "usage"));
+  const hasRecords = hasKey(mapping, "records");
+  const hasCount = hasKey(mapping, "result");
+  if (hasRecords === hasCount) {
+    throw decodeError("FLOW.QUERY result must contain exactly one records or count shape", value);
+  }
+  const raw = freezeMap(mapping);
+  if (hasRecords) {
+    const rawRecords = field(mapping, "records");
+    if (!Array.isArray(rawRecords) || rawRecords.length > 100) {
+      throw decodeError("FLOW.QUERY records must be an array of at most 100 maps", value);
+    }
+    const records = new Array(rawRecords.length);
+    for (let index = 0; index < rawRecords.length; index += 1) {
+      if (!Object.hasOwn(rawRecords, index)) {
+        throw decodeError("FLOW.QUERY records must be a dense array", value);
+      }
+      records[index] = decodeRecord(
+        requiredMap2(rawRecords[index], `FLOW.QUERY record ${index}`),
+        index
+      );
+    }
+    if (usage.resultRecords !== records.length || usage.resultRecords > usage.scannedEntries) {
+      throw decodeError("FLOW.QUERY usage result_records is inconsistent with records", value);
+    }
+    return {
+      kind: "records",
+      records,
+      page: decodePage(field(mapping, "page")),
+      quality,
+      usage,
+      raw
+    };
+  }
+  if (hasKey(mapping, "page")) {
+    throw decodeError("FLOW.QUERY count result contains an unexpected page", value);
+  }
+  const countResult = requiredMap2(field(mapping, "result"), "FLOW.QUERY count result");
+  if (requiredText2(countResult, "kind", "FLOW.QUERY count result") !== "count") {
+    throw decodeError("FLOW.QUERY count result kind must be count", value);
+  }
+  const count = boundedInteger(
+    field(countResult, "value"),
+    MAX_SIGNED_643,
+    "FLOW.QUERY count value"
+  );
+  if (usage.resultRecords !== 1) {
+    throw decodeError("FLOW.QUERY count usage result_records must be 1", value);
+  }
+  return {
+    kind: "count",
+    count,
+    quality,
+    usage,
+    raw
+  };
+}
+function decodeFlowExplainResult(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY explain");
+  requireContract(mapping, "version", FLOW_EXPLAIN_CONTRACT, "FLOW.QUERY explain");
+  const queryFingerprint = requiredText2(mapping, "query_fingerprint", "FLOW.QUERY explain");
+  if (!/^[0-9a-f]{64}$/iu.test(queryFingerprint)) {
+    throw decodeError("FLOW.QUERY explain query_fingerprint is invalid", value);
+  }
+  const status = requiredText2(mapping, "status", "FLOW.QUERY explain");
+  if (status !== "planned" && status !== "rejected" && status !== "executed") {
+    throw decodeError(`FLOW.QUERY explain status ${JSON.stringify(status)} is unsupported`, value);
+  }
+  const plan = freezeMetadataMap(
+    requiredMap2(field(mapping, "plan"), "FLOW.QUERY explain plan"),
+    "FLOW.QUERY explain plan"
+  );
+  const estimate = freezeMetadataMap(
+    requiredMap2(field(mapping, "estimate"), "FLOW.QUERY explain estimate"),
+    "FLOW.QUERY explain estimate"
+  );
+  const bounds = freezeMetadataMap(
+    requiredMap2(field(mapping, "bounds"), "FLOW.QUERY explain bounds"),
+    "FLOW.QUERY explain bounds"
+  );
+  const capabilities = decodeExplainCapabilities(mapping);
+  const extendedFields = ["stats", "quality", "pressure", "decision", "alternatives"];
+  const extendedPresence = extendedFields.map((name) => hasKey(mapping, name));
+  const specialized = capabilities != null && !extendedPresence.some(Boolean);
+  let stats;
+  let quality;
+  let pressure;
+  let decision;
+  let alternatives;
+  if (specialized) {
+    if (status !== "planned") {
+      throw decodeError("FLOW.QUERY specialized explain must be planned", value);
+    }
+    if (hasKey(mapping, "actual") || hasKey(mapping, "diagnostic")) {
+      throw decodeError("FLOW.QUERY specialized explain has extended status fields", value);
+    }
+    alternatives = Object.freeze([]);
+  } else {
+    if (!extendedPresence.every(Boolean) || !hasKey(mapping, "actual") || !hasKey(mapping, "diagnostic")) {
+      throw decodeError("FLOW.QUERY explain is missing required v1 fields", value);
+    }
+    stats = freezeMetadataMap(
+      requiredMap2(field(mapping, "stats"), "FLOW.QUERY explain stats"),
+      "FLOW.QUERY explain stats"
+    );
+    quality = decodeQuality(field(mapping, "quality"));
+    pressure = freezeMetadataMap(
+      requiredMap2(field(mapping, "pressure"), "FLOW.QUERY explain pressure"),
+      "FLOW.QUERY explain pressure"
+    );
+    decision = freezeMetadataMap(
+      requiredMap2(field(mapping, "decision"), "FLOW.QUERY explain decision"),
+      "FLOW.QUERY explain decision"
+    );
+    alternatives = decodeExplainAlternatives(field(mapping, "alternatives"));
+  }
+  const actualValue = field(mapping, "actual");
+  let actual;
+  if (status === "executed") {
+    if (actualValue == null) {
+      throw decodeError("FLOW.QUERY executed explain is missing actual usage", value);
+    }
+    actual = decodeUsage(actualValue);
+  } else if (actualValue != null) {
+    throw decodeError("FLOW.QUERY non-executed explain contains actual usage", value);
+  }
+  const diagnosticValue = field(mapping, "diagnostic");
+  let diagnostic;
+  if (status === "rejected") {
+    diagnostic = tryDecodeFlowQueryError(diagnosticValue);
+    if (diagnostic == null) {
+      throw decodeError("FLOW.QUERY rejected explain has an invalid diagnostic", value);
+    }
+  } else if (diagnosticValue != null) {
+    throw decodeError("FLOW.QUERY non-rejected explain contains a diagnostic", value);
+  }
+  return Object.freeze({
+    version: FLOW_EXPLAIN_CONTRACT,
+    queryFingerprint,
+    status,
+    plan,
+    estimate,
+    stats,
+    quality,
+    bounds,
+    pressure,
+    decision,
+    alternatives,
+    capabilities,
+    actual,
+    diagnostic,
+    raw: freezeMap(mapping)
+  });
+}
+function decodeExplainCapabilities(mapping) {
+  if (!hasKey(mapping, "capabilities")) return void 0;
+  const value = requiredMap2(
+    field(mapping, "capabilities"),
+    "FLOW.QUERY explain capabilities"
+  );
+  return Object.freeze({
+    requested: decodeExplainCapabilityList(field(value, "requested"), "requested"),
+    available: decodeExplainCapabilityList(field(value, "available"), "available"),
+    missing: decodeExplainCapabilityList(field(value, "missing"), "missing"),
+    raw: freezeMetadataMap(value, "FLOW.QUERY explain capabilities")
+  });
+}
+function decodeExplainCapabilityList(value, name) {
+  if (!Array.isArray(value) || value.length > 64) {
+    throw decodeError(
+      `FLOW.QUERY explain capabilities ${name} must contain at most 64 entries`,
+      value
+    );
+  }
+  const result = new Array(value.length);
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      throw decodeError(`FLOW.QUERY explain capabilities ${name} must be dense`, value);
+    }
+    const capability = boundedText(
+      value[index],
+      `FLOW.QUERY explain capabilities ${name} entry ${index}`,
+      128
+    );
+    if (seen.has(capability)) {
+      throw decodeError(
+        `FLOW.QUERY explain capabilities ${name} contains duplicates`,
+        value
+      );
+    }
+    seen.add(capability);
+    result[index] = capability;
+  }
+  return Object.freeze(result);
+}
+function decodeExplainAlternatives(value) {
+  if (!Array.isArray(value) || value.length > 31) {
+    throw decodeError("FLOW.QUERY explain alternatives must be an array of at most 31 maps", value);
+  }
+  const alternatives = new Array(value.length);
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      throw decodeError("FLOW.QUERY explain alternatives must be dense", value);
+    }
+    alternatives[index] = freezeMetadataMap(
+      requiredMap2(value[index], `FLOW.QUERY explain alternative ${index}`),
+      `FLOW.QUERY explain alternative ${index}`
+    );
+  }
+  return Object.freeze(alternatives);
+}
 function decodeQuality(value) {
   const mapping = requiredMap2(value, "FLOW.QUERY quality");
   return Object.freeze({
-    exactness: requiredBoundedText2(mapping, "exactness", "FLOW.QUERY quality", 64),
-    freshness: requiredBoundedText2(mapping, "freshness", "FLOW.QUERY quality", 64),
-    coverage: requiredBoundedText2(mapping, "coverage", "FLOW.QUERY quality", 64),
-    pagination: requiredBoundedText2(mapping, "pagination", "FLOW.QUERY quality", 64)
+    exactness: decodeQualityValue(mapping, "exactness", QUALITY_VALUES2.exactness),
+    freshness: decodeQualityValue(mapping, "freshness", QUALITY_VALUES2.freshness),
+    coverage: decodeQualityValue(mapping, "coverage", QUALITY_VALUES2.coverage),
+    pagination: decodeQualityValue(mapping, "pagination", QUALITY_VALUES2.pagination)
   });
 }
+function decodeQualityValue(mapping, name, allowed) {
+  const value = requiredBoundedText2(mapping, name, "FLOW.QUERY quality", 64);
+  if (!allowed.includes(value)) {
+    throw decodeError(`FLOW.QUERY quality ${name} is unsupported`, mapping);
+  }
+  return value;
+}
 function decodeUsage(value) {
   const mapping = requiredMap2(value, "FLOW.QUERY usage");
   const usage = /* @__PURE__ */ Object.create(null);
@@ -12415,13 +13522,17 @@ function decodeUsage(value) {
       `FLOW.QUERY usage ${wireName}`
     );
   }
-  return Object.freeze(usage);
+  const decoded = usage;
+  if (decoded.hydratedRecords > decoded.scannedEntries || decoded.duplicateEntries > decoded.scannedEntries || decoded.rangePages > decoded.scannedEntries + decoded.rangeSeeks || decoded.residualChecks > decoded.scannedEntries * 12) {
+    throw decodeError("FLOW.QUERY usage counters are inconsistent", value);
+  }
+  return Object.freeze(decoded);
 }
 function decodePage(value) {
   const mapping = requiredMap2(value, "FLOW.QUERY page");
   const hasMore = requiredBoolean(mapping, "has_more", "FLOW.QUERY page");
   const cursor = optionalText2(mapping, "cursor", "FLOW.QUERY page");
-  if (cursor != null && (!cursor.startsWith("fqc1_") || import_node_buffer45.Buffer.byteLength(cursor) > 4096)) {
+  if (cursor != null && (!cursor.startsWith("fqc1_") || import_node_buffer48.Buffer.byteLength(cursor) < 16 || import_node_buffer48.Buffer.byteLength(cursor) > 4096)) {
     throw decodeError("FLOW.QUERY page cursor is invalid", value);
   }
   if (hasMore !== (cursor != null)) {
@@ -12429,26 +13540,14 @@ function decodePage(value) {
   }
   return Object.freeze({ hasMore, ...cursor == null ? {} : { cursor } });
 }
-function decodePosition(value) {
-  if (value == null) return void 0;
-  const mapping = requiredMap2(value, "FLOW.QUERY diagnostic position");
-  return Object.freeze({
-    byte: positiveInteger(field(mapping, "byte"), "FLOW.QUERY diagnostic position byte"),
-    line: positiveInteger(field(mapping, "line"), "FLOW.QUERY diagnostic position line"),
-    column: positiveInteger(
-      field(mapping, "column"),
-      "FLOW.QUERY diagnostic position column"
-    )
-  });
-}
 
 // src/client-core.ts
-var import_node_buffer50 = require("buffer");
+var import_node_buffer53 = require("buffer");
 
 // src/client-core-helpers.ts
-var import_node_buffer46 = require("buffer");
+var import_node_buffer49 = require("buffer");
 function bgsaveResponse(response) {
-  if ((typeof response === "string" || import_node_buffer46.Buffer.isBuffer(response) || response instanceof Uint8Array) && text(response) === "Background saving started") {
+  if ((typeof response === "string" || import_node_buffer49.Buffer.isBuffer(response) || response instanceof Uint8Array) && text(response) === "Background saving started") {
     return true;
   }
   return okResponse(response);
@@ -12462,7 +13561,7 @@ function fetchOrComputeCompletionToken(options) {
       "fetch-or-compute completion requires computeToken"
     );
   }
-  if (!import_node_buffer46.Buffer.isBuffer(options.computeToken)) {
+  if (!import_node_buffer49.Buffer.isBuffer(options.computeToken)) {
     throw new TypeError("fetch-or-compute computeToken must be a Buffer");
   }
   return options.computeToken;
@@ -12485,10 +13584,10 @@ function unsupportedClientCaching() {
 }
 
 // src/client-base.ts
-var import_node_buffer48 = require("buffer");
+var import_node_buffer51 = require("buffer");
 
 // src/client-executor.ts
-var import_node_buffer47 = require("buffer");
+var import_node_buffer50 = require("buffer");
 var ErrorMappingExecutor = class {
   constructor(executor) {
     this.executor = executor;
@@ -12822,14 +13921,14 @@ var FerricStoreAdministrationClient = class extends FerricStoreClientBase {
 };
 
 // src/store-utilities.ts
-var import_node_buffer49 = require("buffer");
+var import_node_buffer52 = require("buffer");
 function encode(codec, value) {
   return codec.encode(value);
 }
 function decode(codec, value) {
   if (value == null) return null;
-  if (import_node_buffer49.Buffer.isBuffer(value)) return codec.decode(value);
-  if (value instanceof Uint8Array) return codec.decode(import_node_buffer49.Buffer.from(value));
+  if (import_node_buffer52.Buffer.isBuffer(value)) return codec.decode(value);
+  if (value instanceof Uint8Array) return codec.decode(import_node_buffer52.Buffer.from(value));
   return value;
 }
 function number(value) {
@@ -15064,7 +16163,7 @@ var FerricStoreFlowQueryClient = class extends FerricStoreManagementClient {
       args.push(indexId);
     }
     try {
-      return decodeFlowQueryIndexStatus(await this.commandArgs(args));
+      return decodeFlowQueryIndexStatus(await this.commandArgs(args), indexId);
     } catch (error) {
       this.throwFlowQueryError(error);
     }
@@ -15126,7 +16225,7 @@ var FerricStoreFlowQueryClient = class extends FerricStoreManagementClient {
     if (hasFlowExplainPrefix(query)) {
       throw new TypeError("query already contains an EXPLAIN prefix");
     }
-    return decodeFlowExplainResult(await this.executeFlowQuery(prefix + query.trim(), params));
+    return decodeFlowExplainResult(await this.executeFlowQuery(prefix + query, params));
   }
   throwFlowQueryError(error) {
     if (error instanceof FerricStoreError) {
@@ -15159,7 +16258,7 @@ function throwIfClosed(signal) {
 }
 
 // src/flow-policy.ts
-var import_node_buffer51 = require("buffer");
+var import_node_buffer54 = require("buffer");
 var MAX_FLOW_POLICY_GENERATION = Number.MAX_SAFE_INTEGER;
 function assertFlowPolicyGeneration(value) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
@@ -15249,7 +16348,7 @@ function requiredRecord(value, context) {
     }
     return result;
   }
-  if (typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer51.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) return value;
+  if (typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer54.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) return value;
   throw new TypeError(`${context} returned an unexpected response`);
 }
 function optionalRecord(value, context) {
@@ -15270,8 +16369,8 @@ function stringArray(value, context) {
 }
 function requiredText3(value, context) {
   if (typeof value === "string") return value;
-  if (import_node_buffer51.Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return import_node_buffer51.Buffer.from(value).toString("utf8");
+  if (import_node_buffer54.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return import_node_buffer54.Buffer.from(value).toString("utf8");
   }
   throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
 }
@@ -15527,7 +16626,7 @@ var FerricStoreFlowSupportClient = class extends FerricStoreFlowQueryClient {
 };
 
 // src/flow-many-snapshot.ts
-var import_node_buffer53 = require("buffer");
+var import_node_buffer56 = require("buffer");
 var encodedOptionFields = ["error", "payload", "reason", "result"];
 function snapshotCreateItem(item, codec) {
   const snapshot = {
@@ -15567,7 +16666,7 @@ function snapshotFlowManyOptions(options, codec) {
 }
 function snapshotClaimedItem(item) {
   const wire = item[CLAIMED_ITEM_WIRE];
-  const leaseToken = import_node_buffer53.Buffer.from(wire?.leaseToken ?? item.leaseToken);
+  const leaseToken = import_node_buffer56.Buffer.from(wire?.leaseToken ?? item.leaseToken);
   const snapshot = {
     ...item,
     fencingToken: wire?.fencingToken ?? item.fencingToken,
@@ -15584,15 +16683,15 @@ function snapshotClaimedItem(item) {
 function snapshotFencedItem(item) {
   return Object.freeze({
     ...item,
-    ...item.leaseToken == null ? {} : { leaseToken: import_node_buffer53.Buffer.from(item.leaseToken) }
+    ...item.leaseToken == null ? {} : { leaseToken: import_node_buffer56.Buffer.from(item.leaseToken) }
   });
 }
 function snapshotClaimedItemWire(wire, leaseToken) {
   return Object.freeze({
     fencingToken: wire.fencingToken,
-    id: import_node_buffer53.Buffer.from(wire.id),
+    id: import_node_buffer56.Buffer.from(wire.id),
     leaseToken,
-    partitionKey: wire.partitionKey == null ? wire.partitionKey : import_node_buffer53.Buffer.from(wire.partitionKey)
+    partitionKey: wire.partitionKey == null ? wire.partitionKey : import_node_buffer56.Buffer.from(wire.partitionKey)
   });
 }
 function snapshotArray(values) {
@@ -15603,7 +16702,7 @@ function snapshotArray(values) {
   return Object.freeze(snapshot);
 }
 function snapshotStateMeta(stateMeta) {
-  return snapshotRecord(stateMeta, (value) => import_node_buffer53.Buffer.isBuffer(value) ? import_node_buffer53.Buffer.from(value) : value);
+  return snapshotRecord(stateMeta, (value) => import_node_buffer56.Buffer.isBuffer(value) ? import_node_buffer56.Buffer.from(value) : value);
 }
 function snapshotCommandRecord(values) {
   const seen = /* @__PURE__ */ new WeakMap();
@@ -15621,7 +16720,7 @@ function snapshotRecord(values, capture) {
 }
 function snapshotCommandArgument(value, seen) {
   if (typeof value !== "object" || value == null) return value;
-  if (import_node_buffer53.Buffer.isBuffer(value) || value instanceof Uint8Array) return import_node_buffer53.Buffer.from(value);
+  if (import_node_buffer56.Buffer.isBuffer(value) || value instanceof Uint8Array) return import_node_buffer56.Buffer.from(value);
   const objectValue = value;
   const existing = seen.get(objectValue);
   if (existing != null) return existing;
@@ -16609,7 +17708,7 @@ function nativeOptionsForBootstrap(options, signal) {
 }
 
 // src/flow-query-projection.ts
-var import_node_buffer54 = require("buffer");
+var import_node_buffer57 = require("buffer");
 var MAX_PROJECTION_FIELDS = 32;
 var MAX_DYNAMIC_NAME_BYTES = 64;
 var FIELD_BRAND = /* @__PURE__ */ Symbol("FerricStoreFlowProjectionField");
@@ -16677,20 +17776,38 @@ function projectFlowQuery(query, shape, ...fields) {
   if (containsReturnKeyword(query)) {
     throw new TypeError("Flow query already contains a RETURN clause");
   }
-  const trimmed = query.trim();
-  const base = trimmed.endsWith(";") ? trimmed.slice(0, -1).trimEnd() : trimmed;
+  const base = stripOptionalTerminator(query);
   const result = `${base} RETURN ${shape.toUpperCase()} (${selectors.join(", ")})`;
-  if (import_node_buffer54.Buffer.byteLength(result, "utf8") > FLOW_QUERY_MAX_BYTES) {
+  if (import_node_buffer57.Buffer.byteLength(result, "utf8") > FLOW_QUERY_MAX_BYTES) {
     throw new TypeError(`FLOW.QUERY query exceeds ${FLOW_QUERY_MAX_BYTES} bytes`);
   }
   return result;
 }
+function stripOptionalTerminator(query) {
+  const trimmed = trimFlowQueryAsciiWhitespace(query);
+  if (!trimmed.endsWith(";")) return trimmed;
+  const base = trimFlowQueryAsciiWhitespace(trimmed.slice(0, -1));
+  if (base.endsWith(";")) {
+    throw new TypeError("Flow query accepts at most one trailing semicolon");
+  }
+  return base;
+}
 function querySource(query) {
-  const match = /^\s*FROM\s+(runs|events)\b/iu.exec(query);
-  if (match?.[1] == null) {
+  const source = trimFlowQueryAsciiWhitespaceStart(query);
+  if (!matchesFlowQueryAsciiKeyword(source, 0, "FROM") || !isFlowQueryAsciiWhitespaceCode(source.charCodeAt(4))) {
     throw new TypeError("Projected Flow query must start with FROM runs or FROM events");
   }
-  return match[1].toLowerCase();
+  let offset = 4;
+  while (isFlowQueryAsciiWhitespaceCode(source.charCodeAt(offset))) offset += 1;
+  for (const candidate of ["runs", "events"]) {
+    if (matchesFlowQueryAsciiKeyword(source, offset, candidate.toUpperCase())) {
+      const boundary = source[offset + candidate.length];
+      if (boundary == null || isFlowQueryAsciiWhitespaceCode(boundary.charCodeAt(0))) {
+        return candidate;
+      }
+    }
+  }
+  throw new TypeError("Projected Flow query must start with FROM runs or FROM events");
 }
 function containsReturnKeyword(query) {
   let quoted = false;
@@ -16721,7 +17838,7 @@ function quoteName(value, allowPrivate) {
     throw new TypeError("Flow query projection metadata name must be text");
   }
   validateUnicodeScalarText2(value);
-  const size = import_node_buffer54.Buffer.byteLength(value, "utf8");
+  const size = import_node_buffer57.Buffer.byteLength(value, "utf8");
   if (size === 0 || size > MAX_DYNAMIC_NAME_BYTES || !allowPrivate && value.startsWith("__")) {
     throw new TypeError(
       `Flow query projection metadata names must be 1..${MAX_DYNAMIC_NAME_BYTES} UTF-8 bytes`
@@ -16755,7 +17872,7 @@ function complete(options = {}) {
 function retry(options = {}) {
   return brandOutcome({ ...options, kind: "retry" });
 }
-function fail(options = {}) {
+function fail2(options = {}) {
   return brandOutcome({ ...options, kind: "fail" });
 }
 function isOutcome(value) {
@@ -17552,7 +18669,7 @@ async function applyQueueException(queue, options, job, error) {
   const policy = normalizeExceptionPolicy(options.exceptionPolicy);
   if (policy === "raise") throw error;
   const payload = workerErrorPayload(error, options, queue.client.codec);
-  await applyQueueOutcome(queue, job, policy === "fail" ? fail({ error: payload }) : retry({ error: payload }));
+  await applyQueueOutcome(queue, job, policy === "fail" ? fail2({ error: payload }) : retry({ error: payload }));
 }
 
 // src/queue-pending-completions.ts
@@ -17799,7 +18916,7 @@ var QueueWorker = class {
         const policy = normalizeExceptionPolicy(this.options.exceptionPolicy);
         if (policy !== "raise") {
           const payload = workerErrorPayload(error, this.options, this.queue.client.codec);
-          outcome = policy === "fail" ? fail({ error: payload }) : retry({ error: payload });
+          outcome = policy === "fail" ? fail2({ error: payload }) : retry({ error: payload });
         }
       }
       const stopped = await stopQueueBatchGuards(guards.map((guard) => guard.job), guards);
@@ -18712,7 +19829,7 @@ var WorkflowWorker = class {
       await applyWorkflowOutcome(
         this.workflow.client,
         ctx,
-        fail({ error: workerErrorPayload(error, this.options, this.workflow.client.codec) }),
+        fail2({ error: workerErrorPayload(error, this.options, this.workflow.client.codec) }),
         registration.returnRecord
       );
       return;
@@ -18727,7 +19844,7 @@ var WorkflowWorker = class {
 };
 
 // src/version.ts
-var FERRICSTORE_SDK_VERSION = "0.5.0";
+var FERRICSTORE_SDK_VERSION = "0.5.2";
 var FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.0";
 var FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
 // Annotate the CommonJS export names for ESM import in node: