@ferricstore/ferricstore 0.5.1 → 0.11.4

package/dist/index.js

@@ -1140,10 +1140,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;
@@ -1190,9 +1190,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);
@@ -1246,9 +1248,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)) {
@@ -1274,19 +1301,26 @@ function flowQueryParameterEntries(params) {
 function validateFlowQueryParameterName(name) {
   validateUnicodeScalarText(name, "FLOW.QUERY parameter name");
   const size = Buffer4.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(Buffer4.byteLength(value, "utf8"), name);
+    return value;
+  }
+  if (Buffer4.isBuffer(value)) {
+    validateParameterValueSize(value.byteLength, name);
     return value;
   }
-  if (Buffer4.isBuffer(value)) return value;
-  if (value instanceof Uint8Array) return Buffer4.from(value);
+  if (value instanceof Uint8Array) {
+    validateParameterValueSize(value.byteLength, name);
+    return Buffer4.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)) {
@@ -1296,6 +1330,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);
@@ -3049,6 +3090,7 @@ var FLOW_ADMIN_FIELDS = {
   AT_MS: "at_ms",
   BLOCK: "block_ms",
   BLOCK_MS: "block_ms",
+  CATCHUP_POLICY: "catchup_policy",
   CONSISTENT_PROJECTION: "consistent_projection",
   CORRELATION_ID: "correlation_id",
   COUNT: "count",
@@ -5482,15 +5524,15 @@ function requiredMap(value, context) {
   }
   throw incompatibleServer(`${context} is missing or invalid`);
 }
-function requiredBoundedText(mapping, name) {
-  const value = strictText(field(mapping, name));
+function requiredBoundedText(mapping2, name) {
+  const value = strictText(field(mapping2, name));
   if (value == null || value.length === 0 || Buffer20.byteLength(value) > 256) {
     throw incompatibleServer(`HELLO flow_query ${name} must be bounded non-empty text`);
   }
   return value;
 }
-function boundedTextSet(mapping, name, maximum) {
-  const raw = field(mapping, name);
+function boundedTextSet(mapping2, name, maximum) {
+  const raw = field(mapping2, name);
   if (!Array.isArray(raw) || raw.length < 1 || raw.length > maximum) {
     throw incompatibleServer(`HELLO ${name} must contain 1..${maximum} entries`);
   }
@@ -5730,7 +5772,7 @@ function truncate(value) {
 }
 
 // src/protocol-flow-query-result.ts
-import { Buffer as Buffer24 } from "buffer";
+import { Buffer as Buffer24, isUtf8 as isUtf82 } from "buffer";
 
 // src/protocol-binary-detacher.ts
 import { Buffer as Buffer23 } from "buffer";
@@ -5767,7 +5809,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 = Buffer24.from("fqc1_");
+var MAX_SIGNED_64 = (1n << 63n) - 1n;
 var RECORD_FIELDS = [
   "id",
   "type",
@@ -5831,9 +5876,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);
@@ -5842,6 +5891,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) {
@@ -5851,7 +5901,13 @@ function decodeCompactFlowQueryResult(data, budget) {
     }
     result = { version: Buffer24.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: Buffer24.from(CONTRACT),
@@ -5876,18 +5932,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) || !isUtf82(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);
@@ -6780,15 +6855,15 @@ function snapshotOwnStringArray(values, name) {
 
 // src/client-native-options.ts
 function snapshotNativeClientOptions(options) {
-  const own = { ...options };
+  const own2 = { ...options };
   const snapshot = {
-    ...own,
-    ...typeof own.autoReconnect === "object" && own.autoReconnect != null ? { autoReconnect: Object.freeze({ ...own.autoReconnect }) } : {},
-    ...own.endpointPolicy == null ? {} : { endpointPolicy: snapshotEndpointPolicy(own.endpointPolicy) },
-    ...own.events == null ? {} : { events: snapshotOwnStringArray(own.events, "events") },
-    ...own.seeds == null ? {} : { seeds: snapshotOwnStringArray(own.seeds, "seeds") },
-    ...own.tlsOptions == null ? {} : { tlsOptions: snapshotTlsOptions(own.tlsOptions) },
-    ...own.trustedHosts == null ? {} : { trustedHosts: snapshotOwnStringArray(own.trustedHosts, "trustedHosts") }
+    ...own2,
+    ...typeof own2.autoReconnect === "object" && own2.autoReconnect != null ? { autoReconnect: Object.freeze({ ...own2.autoReconnect }) } : {},
+    ...own2.endpointPolicy == null ? {} : { endpointPolicy: snapshotEndpointPolicy(own2.endpointPolicy) },
+    ...own2.events == null ? {} : { events: snapshotOwnStringArray(own2.events, "events") },
+    ...own2.seeds == null ? {} : { seeds: snapshotOwnStringArray(own2.seeds, "seeds") },
+    ...own2.tlsOptions == null ? {} : { tlsOptions: snapshotTlsOptions(own2.tlsOptions) },
+    ...own2.trustedHosts == null ? {} : { trustedHosts: snapshotOwnStringArray(own2.trustedHosts, "trustedHosts") }
   };
   return Object.freeze(snapshot);
 }
@@ -6829,12 +6904,12 @@ function topologyNativeOptions(options) {
 }
 function snapshotEndpointPolicy(policy) {
   if (typeof policy !== "object") return policy;
-  const own = { ...policy };
-  if (!Object.hasOwn(own, "allowHosts") || !Array.isArray(own.allowHosts)) {
+  const own2 = { ...policy };
+  if (!Object.hasOwn(own2, "allowHosts") || !Array.isArray(own2.allowHosts)) {
     throw new TypeError("endpointPolicy.allowHosts must be an own array of strings");
   }
   return Object.freeze({
-    allowHosts: snapshotOwnStringArray(own.allowHosts, "endpointPolicy.allowHosts")
+    allowHosts: snapshotOwnStringArray(own2.allowHosts, "endpointPolicy.allowHosts")
   });
 }
 function snapshotTlsOptions(options) {
@@ -7913,6 +7988,63 @@ function nativeStartupPayload(clientName, events) {
   };
 }
 
+// src/flow-query-deadline.ts
+import { Buffer as Buffer31 } from "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) || Buffer31.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) || Buffer31.isBuffer(value) || value instanceof Uint8Array) {
+    return void 0;
+  }
+  return value;
+}
+
 // src/native-adapter.ts
 var NativeAdapter = class _NativeAdapter {
   socket;
@@ -8118,7 +8250,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 }));
@@ -8266,7 +8402,7 @@ function executeCommandArgs(executor, args) {
 import "buffer";
 
 // src/command-retry-policy.ts
-import { Buffer as Buffer32 } from "buffer";
+import { Buffer as Buffer33 } from "buffer";
 function isCasMutation(args) {
   const offset = commandName2(args[0]) === "COMMAND_EXEC" ? 1 : 0;
   const name = commandName2(args[offset]);
@@ -8280,8 +8416,8 @@ function isCasMutation(args) {
 }
 function commandName2(value) {
   if (typeof value === "string") return value.toUpperCase();
-  if (Buffer32.isBuffer(value) || value instanceof Uint8Array) {
-    return Buffer32.from(value).toString("utf8").toUpperCase();
+  if (Buffer33.isBuffer(value) || value instanceof Uint8Array) {
+    return Buffer33.from(value).toString("utf8").toUpperCase();
   }
   return void 0;
 }
@@ -8496,12 +8632,12 @@ function normalizeNonNegativeInteger2(value, fallback) {
 import "buffer";
 
 // src/topology-routing.ts
-import { Buffer as Buffer35 } from "buffer";
+import { Buffer as Buffer36 } from "buffer";
 
 // src/flow-partition-route-cache.ts
-import { Buffer as Buffer34 } from "buffer";
+import { Buffer as Buffer35 } from "buffer";
 import { createHash } from "crypto";
-var AUTO_PREFIX = Buffer34.from("__flow_auto__:", "ascii");
+var AUTO_PREFIX = Buffer35.from("__flow_auto__:", "ascii");
 var MAX_CACHEABLE_PARTITION_BYTES = 4 * 1024;
 var MAX_CACHE_BYTES = 1 * 1024 * 1024;
 var MAX_CACHE_ENTRIES = 1024;
@@ -8511,10 +8647,10 @@ var cacheBytes = 0;
 var cacheHits = 0;
 var cacheMisses = 0;
 function flowLogicalPartitionRoutingKey(value) {
-  if (typeof value !== "string" && !Buffer34.isBuffer(value)) return void 0;
+  if (typeof value !== "string" && !Buffer35.isBuffer(value)) return void 0;
   const autoBucket = flowAutoBucket(value);
   if (autoBucket != null) return `{fa:${autoBucket}}`;
-  const bytes2 = Buffer34.isBuffer(value) ? value : Buffer34.from(value);
+  const bytes2 = Buffer35.isBuffer(value) ? value : Buffer35.from(value);
   if (bytes2.byteLength > MAX_CACHEABLE_PARTITION_BYTES) return hashRoute(bytes2);
   const cacheKey = bytes2.toString("base64");
   const cached = routeCache.get(cacheKey);
@@ -8588,7 +8724,7 @@ function routingKeyFromProtocolPayload(name, command) {
       "scope"
     ]) {
       const value = getField(command.payload, field3);
-      if (typeof value === "string" || Buffer35.isBuffer(value)) {
+      if (typeof value === "string" || Buffer36.isBuffer(value)) {
         return value;
       }
     }
@@ -8636,7 +8772,7 @@ function flowRoutingData(name, args) {
     if (typeof partition === "string" && partition.toUpperCase() !== "AUTO" && partition.toUpperCase() !== "MIXED") {
       return flowRoutingResult(flowLogicalPartitionRoutingKey(partition));
     }
-    if (Buffer35.isBuffer(partition)) {
+    if (Buffer36.isBuffer(partition)) {
       const text3 = partition.toString("utf8").toUpperCase();
       if (text3 !== "AUTO" && text3 !== "MIXED") {
         return flowRoutingResult(flowLogicalPartitionRoutingKey(partition));
@@ -8727,17 +8863,17 @@ function flowPartitionRoutingKeyFromCommand(command, claim) {
   return { handled: false };
 }
 function isRoutingKey(value) {
-  return typeof value === "string" || Buffer35.isBuffer(value);
+  return typeof value === "string" || Buffer36.isBuffer(value);
 }
 function flowAutoIdRoutingKey(value) {
-  if (typeof value !== "string" && !Buffer35.isBuffer(value)) {
+  if (typeof value !== "string" && !Buffer36.isBuffer(value)) {
     return void 0;
   }
-  const bucket = (Buffer35.isBuffer(value) ? crc32(value) : crc32Utf8(value)) & 255;
+  const bucket = (Buffer36.isBuffer(value) ? crc32(value) : crc32Utf8(value)) & 255;
   return `{fa:${bucket}}`;
 }
 function flowClaimLogicalPartitionRoutingKey(value) {
-  if (typeof value !== "string" && !Buffer35.isBuffer(value)) return void 0;
+  if (typeof value !== "string" && !Buffer36.isBuffer(value)) return void 0;
   const selector = commandPart(value);
   if (selector === "AUTO" || selector === "ANY") return void 0;
   if (selector === "GLOBAL") return "{f}";
@@ -8752,7 +8888,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" && !Buffer35.isBuffer(key))) {
+  if (keys.length === 0 || keys.some((key) => typeof key !== "string" && !Buffer36.isBuffer(key))) {
     return void 0;
   }
   const usable = keys;
@@ -8785,7 +8921,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" && !Buffer35.isBuffer(key)) return void 0;
+    if (typeof key !== "string" && !Buffer36.isBuffer(key)) return void 0;
     const route = routeKey(key);
     const groupKey = `${route.endpointKey}\0${route.laneId}`;
     const group = groups.get(groupKey);
@@ -9874,7 +10010,7 @@ var TopologyNativeAdapterPool = class _TopologyNativeAdapterPool {
 };
 
 // src/response-map-preservation.ts
-import { Buffer as Buffer37 } from "buffer";
+import { Buffer as Buffer38 } from "buffer";
 function toStringKeyMapPreservingValues(value) {
   if (value == null) return void 0;
   const result = {};
@@ -9884,7 +10020,7 @@ function toStringKeyMapPreservingValues(value) {
     }
     return result;
   }
-  if (typeof value === "object" && !Array.isArray(value) && !Buffer37.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value === "object" && !Array.isArray(value) && !Buffer38.isBuffer(value) && !(value instanceof Uint8Array)) {
     for (const [key, item] of Object.entries(value)) {
       setOwnValue(result, text(key), normalizeMapStructurePreservingBytes(item));
     }
@@ -9893,7 +10029,7 @@ function toStringKeyMapPreservingValues(value) {
   return void 0;
 }
 function normalizeMapStructurePreservingBytes(value) {
-  if (Buffer37.isBuffer(value) || value instanceof Uint8Array) return value;
+  if (Buffer38.isBuffer(value) || value instanceof Uint8Array) return value;
   if (value instanceof Map) {
     const result = {};
     for (const [key, item] of value.entries()) {
@@ -9915,7 +10051,7 @@ function normalizeMapStructurePreservingBytes(value) {
 }
 
 // src/native-kv-responses.ts
-import { Buffer as Buffer38 } from "buffer";
+import { Buffer as Buffer39 } from "buffer";
 function rateLimitResultFromResp(value) {
   if (!Array.isArray(value) || value.length !== 4) {
     throw new TypeError("RATELIMIT.ADD returned an unexpected response");
@@ -9972,13 +10108,13 @@ function fetchOrComputeResultFromResp(value, codec) {
 }
 function decodePayload(codec, value) {
   if (value == null) return null;
-  if (Buffer38.isBuffer(value)) return codec.decode(value);
-  if (value instanceof Uint8Array) return codec.decode(Buffer38.from(value));
-  if (typeof value === "string") return codec.decode(Buffer38.from(value));
+  if (Buffer39.isBuffer(value)) return codec.decode(value);
+  if (value instanceof Uint8Array) return codec.decode(Buffer39.from(value));
+  if (typeof value === "string") return codec.decode(Buffer39.from(value));
   return normalizeRefMeta(value);
 }
 function requiredResponseString(value, context) {
-  if (typeof value !== "string" && !Buffer38.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value !== "string" && !Buffer39.isBuffer(value) && !(value instanceof Uint8Array)) {
     throw new TypeError(`${context} returned an unexpected response`);
   }
   const result = text(value);
@@ -9995,7 +10131,7 @@ function requiredNonNegativeInteger(value, context) {
   return result;
 }
 function responseBytes(value, context) {
-  if (typeof value !== "string" && !Buffer38.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value !== "string" && !Buffer39.isBuffer(value) && !(value instanceof Uint8Array)) {
     throw new TypeError(`${context} returned an unexpected response`);
   }
   return bytes(value);
@@ -10678,7 +10814,7 @@ function groupAutoPartitionItems(items) {
 }
 
 // src/client-values.ts
-import { Buffer as Buffer39 } from "buffer";
+import { Buffer as Buffer40 } from "buffer";
 async function valueMGetEntries(client, refs, options = {}) {
   const refCount = refs.length;
   if (refCount === 0) {
@@ -10713,12 +10849,12 @@ async function valueMGetEntries(client, refs, options = {}) {
     const item = response[index];
     if (item == null) {
       entries[index] = { found: false };
-    } else if (Buffer39.isBuffer(item)) {
+    } else if (Buffer40.isBuffer(item)) {
       entries[index] = { found: true, value: client.codec.decode(item) };
     } else if (item instanceof Uint8Array) {
-      entries[index] = { found: true, value: client.codec.decode(Buffer39.from(item)) };
+      entries[index] = { found: true, value: client.codec.decode(Buffer40.from(item)) };
     } else if (typeof item === "string") {
-      entries[index] = { found: true, value: client.codec.decode(Buffer39.from(item)) };
+      entries[index] = { found: true, value: client.codec.decode(Buffer40.from(item)) };
     } else {
       entries[index] = { found: true, value: item };
     }
@@ -10730,7 +10866,7 @@ async function valueMGetEntries(client, refs, options = {}) {
 import "buffer";
 
 // src/auto-batch-ordering.ts
-import { Buffer as Buffer40 } from "buffer";
+import { Buffer as Buffer41 } from "buffer";
 function autoBatchOrderingPlan(batch) {
   const accesses = /* @__PURE__ */ new Map();
   const fallbackDependencies = [];
@@ -10845,13 +10981,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)]) && Buffer40.isBuffer(command[itemIndex + (mixed ? 3 : 2)])
+      (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && isFencingToken(command[itemIndex + (mixed ? 2 : 1)]) && Buffer41.isBuffer(command[itemIndex + (mixed ? 3 : 2)])
     );
   }
   return fixedFlowItemIds(
     command,
     mixed ? 4 : 3,
-    (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && Buffer40.isBuffer(command[itemIndex + (mixed ? 2 : 1)]) && isFencingToken(command[itemIndex + (mixed ? 3 : 2)])
+    (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && Buffer41.isBuffer(command[itemIndex + (mixed ? 2 : 1)]) && isFencingToken(command[itemIndex + (mixed ? 3 : 2)])
   );
 }
 function createManyAutoBatchIds(command) {
@@ -10864,7 +11000,7 @@ function createManyAutoBatchIds(command) {
       const ids = fixedFlowItemIds(
         command,
         width,
-        (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && Buffer40.isBuffer(command[itemIndex + width - 1]),
+        (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && Buffer41.isBuffer(command[itemIndex + width - 1]),
         markerIndex
       );
       if (ids != null) return ids;
@@ -10882,7 +11018,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]) || !Buffer40.isBuffer(command[cursor + 2])) return void 0;
+    if (!isAutoBatchResourceValue(id) || !isAutoBatchResourceValue(command[cursor + 1]) || !Buffer41.isBuffer(command[cursor + 2])) return void 0;
     ids.push(id);
     cursor += 3;
     const afterValues = skipExtendedNamedItems(command, cursor, true);
@@ -10901,7 +11037,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 ? !Buffer40.isBuffer(value) : !isAutoBatchResourceValue(value))) return void 0;
+    if (!isAutoBatchResourceValue(name) || (encodedValues ? !Buffer41.isBuffer(value) : !isAutoBatchResourceValue(value))) return void 0;
   }
   return firstItem + count * 2;
 }
@@ -10916,7 +11052,7 @@ function runStepsManyAutoBatchIds(command) {
         ids.push(item);
         continue;
       }
-      if (typeof item !== "object" || item == null || Array.isArray(item) || Buffer40.isBuffer(item)) return void 0;
+      if (typeof item !== "object" || item == null || Array.isArray(item) || Buffer41.isBuffer(item)) return void 0;
       const id = item.id;
       if (!isAutoBatchResourceValue(id)) return void 0;
       ids.push(id);
@@ -10957,7 +11093,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" || Buffer40.isBuffer(value);
+  return typeof value === "string" || Buffer41.isBuffer(value);
 }
 function isFencingToken(value) {
   return typeof value === "number" && Number.isSafeInteger(value) || typeof value === "bigint";
@@ -10966,7 +11102,7 @@ function nonNegativeItemCount(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
 }
 function autoBatchResourceKey(namespace, value) {
-  return `${namespace}:${Buffer40.from(value).toString("base64")}`;
+  return `${namespace}:${Buffer41.from(value).toString("base64")}`;
 }
 function autoBatchCommandName(command) {
   return commandView(command).name ?? null;
@@ -11378,10 +11514,10 @@ function claimFailure(error) {
 import "buffer";
 
 // src/flow-query-builder.ts
-import { Buffer as Buffer43 } from "buffer";
+import { Buffer as Buffer44 } from "buffer";
 
 // src/flow-query-metadata.ts
-import { Buffer as Buffer42 } from "buffer";
+import { Buffer as Buffer43 } from "buffer";
 var MAX_FLOW_QUERY_METADATA_KEY_BYTES = 64;
 function normalizeStateMeta(value, state) {
   if (value == null) return {};
@@ -11406,7 +11542,7 @@ function normalizeStateMeta(value, state) {
 function metadataEntries(value, context) {
   const entries = objectEntries(value ?? {}, context).map(([rawName, item]) => {
     const name = rawName.trim();
-    const size = Buffer42.byteLength(name, "utf8");
+    const size = Buffer43.byteLength(name, "utf8");
     if (size === 0 || size > MAX_FLOW_QUERY_METADATA_KEY_BYTES || name.startsWith("__")) {
       throw new TypeError(`${context} key is invalid or reserved`);
     }
@@ -11430,7 +11566,7 @@ function objectEntries(value, context) {
   return keys.map((key) => [key, value[key]]);
 }
 function isPlainRecord(value) {
-  if (typeof value !== "object" || value == null || Array.isArray(value) || Buffer42.isBuffer(value)) {
+  if (typeof value !== "object" || value == null || Array.isArray(value) || Buffer43.isBuffer(value)) {
     return false;
   }
   const prototype = Object.getPrototypeOf(value);
@@ -11500,7 +11636,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 = Buffer43.byteLength(state, "utf8");
+      const stateBytes = Buffer44.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`
@@ -11679,7 +11815,7 @@ function requiredPartition(value) {
       "FLOW.QUERY convenience methods require a partition key"
     );
   }
-  const size = Buffer43.byteLength(value, "utf8");
+  const size = Buffer44.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`
@@ -11727,20 +11863,23 @@ function requiredText(value, context) {
   return value;
 }
 function queryParameter(value, context) {
-  if (typeof value === "string" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "number" || Buffer43.isBuffer(value)) {
+  if (typeof value === "string" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "number" || Buffer44.isBuffer(value)) {
     return value;
   }
   throw new TypeError(`${context} must be a scalar FLOW.QUERY parameter`);
 }
 
 // src/flow-query-response.ts
-import { Buffer as Buffer45 } from "buffer";
+import { Buffer as Buffer48 } from "buffer";
+
+// src/flow-query-diagnostic-response.ts
+import { Buffer as Buffer46 } from "buffer";
 
 // src/flow-query-response-validation.ts
-import { Buffer as Buffer44 } from "buffer";
+import { Buffer as Buffer45 } from "buffer";
 function requiredMap2(value, context) {
   if (value instanceof Map) return value;
-  if (typeof value !== "object" || value == null || Array.isArray(value) || Buffer44.isBuffer(value) || value instanceof Uint8Array) {
+  if (typeof value !== "object" || value == null || Array.isArray(value) || Buffer45.isBuffer(value) || value instanceof Uint8Array) {
     throw decodeError(`${context} must be a map`, value);
   }
   return value;
@@ -11797,7 +11936,7 @@ function normalizeMetadataValue(value, context, budget, ancestors, depth) {
     if (!value.isWellFormed()) throw decodeError(`${context} contains invalid text`, value);
     return value;
   }
-  if (Buffer44.isBuffer(value) || value instanceof Uint8Array) {
+  if (Buffer45.isBuffer(value) || value instanceof Uint8Array) {
     const decoded = strictText2(value);
     if (decoded == null) throw decodeError(`${context} contains invalid UTF-8`, value);
     return decoded;
@@ -11850,36 +11989,36 @@ function isPlainObject6(value) {
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
-function requireContract(mapping, name, expected, context) {
-  const actual = requiredText2(mapping, name, context);
+function requireContract(mapping2, name, expected, context) {
+  const actual = requiredText2(mapping2, name, context);
   if (actual !== expected) {
     throw decodeError(
       `${context} has unsupported contract ${JSON.stringify(actual)}`,
-      mapping
+      mapping2
     );
   }
 }
-function requiredText2(mapping, name, context) {
-  const value = strictText2(field(mapping, name));
+function requiredText2(mapping2, name, context) {
+  const value = strictText2(field(mapping2, name));
   if (value == null || value.length === 0) {
-    throw decodeError(`${context} ${name} must be non-empty text`, mapping);
+    throw decodeError(`${context} ${name} must be non-empty text`, mapping2);
   }
   return value;
 }
-function optionalText2(mapping, name, context) {
-  const raw = field(mapping, name);
+function optionalText2(mapping2, name, context) {
+  const raw = field(mapping2, name);
   if (raw == null) return void 0;
   const value = strictText2(raw);
   if (value == null)
-    throw decodeError(`${context} ${name} must be text`, mapping);
+    throw decodeError(`${context} ${name} must be text`, mapping2);
   return value;
 }
-function requiredBoundedText2(mapping, name, context, maximumBytes) {
-  const value = requiredText2(mapping, name, context);
-  if (Buffer44.byteLength(value, "utf8") > maximumBytes) {
+function requiredBoundedText2(mapping2, name, context, maximumBytes) {
+  const value = requiredText2(mapping2, name, context);
+  if (Buffer45.byteLength(value, "utf8") > maximumBytes) {
     throw decodeError(
       `${context} ${name} exceeds ${maximumBytes} bytes`,
-      mapping
+      mapping2
     );
   }
   return value;
@@ -11889,15 +12028,15 @@ function boundedText(value, context, maximumBytes) {
   if (decoded == null || decoded.length === 0) {
     throw decodeError(`${context} must be non-empty text`, value);
   }
-  if (Buffer44.byteLength(decoded, "utf8") > maximumBytes) {
+  if (Buffer45.byteLength(decoded, "utf8") > maximumBytes) {
     throw decodeError(`${context} exceeds ${maximumBytes} bytes`, value);
   }
   return decoded;
 }
-function requiredBoolean(mapping, name, context) {
-  const value = field(mapping, name);
+function requiredBoolean(mapping2, name, context) {
+  const value = field(mapping2, name);
   if (typeof value !== "boolean") {
-    throw decodeError(`${context} ${name} must be boolean`, mapping);
+    throw decodeError(`${context} ${name} must be boolean`, mapping2);
   }
   return value;
 }
@@ -11940,13 +12079,13 @@ function positiveBoundedInteger(value, maximum, context) {
   if (parsed === 0) throw decodeError(`${context} must be positive`, value);
   return parsed;
 }
-function hasKey(mapping, name) {
-  if (!(mapping instanceof Map)) return Object.hasOwn(mapping, name);
-  if (mapping.has(name)) return true;
-  const binaryName = Buffer44.from(name);
-  for (const key of mapping.keys()) {
-    if (Buffer44.isBuffer(key) && key.equals(binaryName)) return true;
-    if (key instanceof Uint8Array && Buffer44.from(key).equals(binaryName))
+function hasKey(mapping2, name) {
+  if (!(mapping2 instanceof Map)) return Object.hasOwn(mapping2, name);
+  if (mapping2.has(name)) return true;
+  const binaryName = Buffer45.from(name);
+  for (const key of mapping2.keys()) {
+    if (Buffer45.isBuffer(key) && key.equals(binaryName)) return true;
+    if (key instanceof Uint8Array && Buffer45.from(key).equals(binaryName))
       return true;
   }
   return false;
@@ -11957,7 +12096,7 @@ function decodeError(message, raw) {
 function strictText2(value) {
   if (typeof value === "string")
     return value.isWellFormed() ? value : void 0;
-  if (Buffer44.isBuffer(value) || value instanceof Uint8Array) {
+  if (Buffer45.isBuffer(value) || value instanceof Uint8Array) {
     try {
       return new TextDecoder("utf-8", { fatal: true }).decode(value);
     } catch {
@@ -11990,341 +12129,1314 @@ 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
+// 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 mapping2 = requiredMap2(value, "FLOW.QUERY diagnostic");
+    const context = decodeDiagnosticContext(field(mapping2, "context"));
+    const position = decodePosition(field(mapping2, "position"));
+    return new FlowQueryError({
+      code: requiredBoundedText2(
+        mapping2,
+        "code",
+        "FLOW.QUERY diagnostic",
+        DIAGNOSTIC_TEXT_BYTES
+      ),
+      message: requiredBoundedText2(
+        mapping2,
+        "message",
+        "FLOW.QUERY diagnostic",
+        DIAGNOSTIC_TEXT_BYTES
+      ),
+      detail: optionalDiagnosticText(mapping2, "detail"),
+      hint: optionalDiagnosticText(mapping2, "hint"),
+      retryable: requiredBoolean(mapping2, "retryable", "FLOW.QUERY diagnostic"),
+      safeToRetry: requiredBoolean(mapping2, "safe_to_retry", "FLOW.QUERY diagnostic"),
+      retryAfterMs: nonNegativeInteger(
+        field(mapping2, "retry_after_ms"),
+        "FLOW.QUERY diagnostic retry_after_ms"
+      ),
+      position,
+      context,
+      raw: value,
+      cause
     });
+  } catch (error) {
+    if (error instanceof FerricStoreError) return void 0;
+    throw error;
   }
-  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
-    });
+function optionalDiagnosticText(mapping2, name) {
+  const value = optionalText2(mapping2, name, "FLOW.QUERY diagnostic");
+  if (value != null && Buffer46.byteLength(value, "utf8") > DIAGNOSTIC_TEXT_BYTES) {
+    throw decodeError(
+      `FLOW.QUERY diagnostic ${name} exceeds ${DIAGNOSTIC_TEXT_BYTES} bytes`,
+      mapping2
+    );
   }
-  return result.records;
+  return value;
 }
-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);
+function decodeDiagnosticContext(value) {
+  if (value == null) return void 0;
+  const mapping2 = requiredMap2(value, "FLOW.QUERY diagnostic context");
+  const size = mapping2 instanceof Map ? mapping2.size : Object.keys(mapping2).length;
+  if (size > DIAGNOSTIC_CONTEXT_ENTRIES) {
+    throw decodeError("FLOW.QUERY diagnostic context contains too many entries", value);
+  }
+  validateDiagnosticContextValue(
+    mapping2,
+    DIAGNOSTIC_CONTEXT_DEPTH,
+    { remaining: DIAGNOSTIC_CONTEXT_NODES }
+  );
+  return freezeMetadataMap(mapping2, "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);
   }
-  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);
+  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 (Buffer46.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);
     }
-    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);
+    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);
       }
-      records[index] = decodeRecord(
-        requiredMap2(rawRecords[index], `FLOW.QUERY record ${index}`),
-        index
-      );
+      validateDiagnosticContextValue(value[index], depth - 1, budget);
     }
-    if (usage.resultRecords !== records.length) {
-      throw decodeError("FLOW.QUERY usage result_records does not match records", value);
+    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);
     }
-    return {
-      kind: "records",
-      records,
-      page: decodePage(field(mapping, "page")),
-      quality,
-      usage,
-      raw
-    };
+    for (const [rawKey, item] of entries) {
+      const key = diagnosticContextText(rawKey);
+      if (key == null || key.length === 0 || Buffer46.byteLength(key, "utf8") > DIAGNOSTIC_CONTEXT_KEY_BYTES) {
+        throw decodeError("FLOW.QUERY diagnostic context contains an invalid key", value);
+      }
+      validateDiagnosticContextValue(item, depth - 1, budget);
+    }
+    return;
   }
-  if (hasKey(mapping, "page")) {
-    throw decodeError("FLOW.QUERY count result contains an unexpected page", value);
+  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);
   }
-  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);
+  budget.remaining -= 1;
+}
+function diagnosticContextText(value) {
+  if (typeof value === "string") return value.isWellFormed() ? value : void 0;
+  if (!Buffer46.isBuffer(value) && !(value instanceof Uint8Array)) return void 0;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(value);
+  } catch {
+    return void 0;
   }
-  const count = boundedInteger(
-    field(countResult, "value"),
-    MAX_SIGNED_64,
-    "FLOW.QUERY count value"
+}
+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 mapping2 = requiredMap2(value, "FLOW.QUERY diagnostic position");
+  return Object.freeze({
+    byte: positiveInteger(field(mapping2, "byte"), "FLOW.QUERY diagnostic position byte"),
+    line: positiveInteger(field(mapping2, "line"), "FLOW.QUERY diagnostic position line"),
+    column: positiveInteger(
+      field(mapping2, "column"),
+      "FLOW.QUERY diagnostic position column"
+    )
+  });
+}
+
+// src/flow-query-index-contract.ts
+import { Buffer as Buffer47 } from "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 (usage.resultRecords !== 1) {
-    throw decodeError("FLOW.QUERY count usage result_records must be 1", value);
+  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);
   }
-  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);
+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 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 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);
   }
-  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);
+  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);
     }
-    actual = decodeUsage(actualValue);
-  } else if (actualValue != null) {
-    throw decodeError("FLOW.QUERY non-executed explain contains actual usage", value);
+    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;
   }
-  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);
+  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);
     }
-  } 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)
-  });
-}
-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"
+  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 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"),
-      retryable: requiredBoolean(mapping, "retryable", "FLOW.QUERY diagnostic"),
-      safeToRetry: requiredBoolean(mapping, "safe_to_retry", "FLOW.QUERY diagnostic"),
-      retryAfterMs: nonNegativeInteger(
-        field(mapping, "retry_after_ms"),
-        "FLOW.QUERY diagnostic retry_after_ms"
-      ),
-      position,
-      context,
-      raw: value,
-      cause
-    });
-  } catch (error) {
-    if (error instanceof FerricStoreError) return void 0;
-    throw error;
   }
+  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) && Buffer47.byteLength(value, "ascii") <= 64;
+}
+function validMetadata(value, rejectReserved) {
+  return value.length > 0 && Buffer47.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(mapping2, name, context, choices) {
+  const value = requiredBoundedText2(mapping2, name, context, 64);
+  if (!choices.includes(value)) {
+    throw decodeError(`${context} ${name} is unsupported`, mapping2);
+  }
+  return value;
+}
+function optionalBoundedText(mapping2, name, context, maximumBytes) {
+  const value = field(mapping2, name);
+  if (value == null) return void 0;
+  return boundedText(value, `${context} ${name}`, maximumBytes);
 }
-function decodeFlowQueryIndexStatus(value) {
-  const mapping = requiredMap2(value, "FLOW.QUERY.INDEXES");
+function optionalIndexInteger(mapping2, name, context) {
+  const value = field(mapping2, name);
+  return value == null ? void 0 : unsignedIndexInteger(value, `${context} ${name}`);
+}
+function indexCounter(mapping2, name, section) {
+  return unsignedIndexInteger(
+    field(mapping2, 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 mapping2 = requiredMap2(value, context);
+  const completeShards = unsignedIndexInteger(
+    field(mapping2, "complete_shards"),
+    `${context} complete_shards`
+  );
+  const totalShards = positiveIndexInteger(
+    field(mapping2, "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(mapping2, "validation", context, [
+      "pending",
+      "passed",
+      "failed"
+    ]),
+    raw: freezeMap(mapping2)
+  });
+}
+function decodeIndexBuild(value) {
+  const mapping2 = requiredMap2(value, "FLOW.QUERY.INDEXES index build");
+  const progress = decodeIndexProgress(
+    mapping2,
+    "build",
+    FLOW_QUERY_BUILD_PHASES
+  );
+  return Object.freeze({
+    ...progress,
+    scannedRecords: indexCounter(mapping2, "scanned_records", "build"),
+    writtenEntries: indexCounter(mapping2, "written_entries", "build"),
+    writtenBytes: indexCounter(mapping2, "written_bytes", "build")
+  });
+}
+function decodeIndexValidation(value) {
+  const mapping2 = requiredMap2(value, "FLOW.QUERY.INDEXES index validation");
+  if (!hasKey(mapping2, "failure_reason") || !hasKey(mapping2, "validated_at_ms")) {
+    throw decodeError(
+      "FLOW.QUERY.INDEXES index validation is missing nullable fields",
+      value
+    );
+  }
+  const progress = decodeIndexProgress(
+    mapping2,
+    "validation",
+    FLOW_QUERY_VALIDATION_PHASES
+  );
+  return Object.freeze({
+    ...progress,
+    status: requiredChoice(
+      mapping2,
+      "status",
+      "FLOW.QUERY.INDEXES index validation",
+      ["pending", "passed", "failed"]
+    ),
+    checkedRecords: indexCounter(mapping2, "checked_records", "validation"),
+    checkedEntries: indexCounter(mapping2, "checked_entries", "validation"),
+    mismatches: indexCounter(mapping2, "mismatches", "validation"),
+    failureReason: optionalBoundedText(
+      mapping2,
+      "failure_reason",
+      "FLOW.QUERY.INDEXES index validation",
+      128
+    ),
+    validatedAtMs: optionalIndexInteger(
+      mapping2,
+      "validated_at_ms",
+      "FLOW.QUERY.INDEXES index validation"
+    )
+  });
+}
+function decodeIndexRetirement(value) {
+  const context = "FLOW.QUERY.INDEXES index retirement";
+  const mapping2 = requiredMap2(value, context);
+  const status = requiredChoice(mapping2, "status", context, [
+    "not_applicable",
+    "pending",
+    "complete"
+  ]);
+  if (status === "not_applicable") {
+    return Object.freeze({ status, raw: freezeMap(mapping2) });
+  }
+  const completedShards = unsignedIndexInteger(
+    field(mapping2, "completed_shards"),
+    `${context} completed_shards`
+  );
+  const totalShards = positiveIndexInteger(
+    field(mapping2, "total_shards"),
+    `${context} total_shards`
+  );
+  if (indexInteger2(completedShards) > indexInteger2(totalShards)) {
+    throw decodeError(
+      `${context} completed_shards exceeds total_shards`,
+      mapping2
+    );
+  }
+  return Object.freeze({
+    status,
+    phaseCounts: decodePhaseCounts(
+      field(mapping2, "phase_counts"),
+      "retirement"
+    ),
+    currentPhases: decodeAllowedPhases(
+      field(mapping2, "current_phases"),
+      "retirement",
+      FLOW_QUERY_RETIREMENT_PHASES
+    ),
+    completedShards,
+    totalShards,
+    deletedEntries: indexCounter(mapping2, "deleted_entries", "retirement"),
+    deletedBytes: indexCounter(mapping2, "deleted_bytes", "retirement"),
+    rewrittenReverseRows: indexCounter(
+      mapping2,
+      "rewritten_reverse_rows",
+      "retirement"
+    ),
+    raw: freezeMap(mapping2)
+  });
+}
+function decodeIndexStatistics(value) {
+  const context = "FLOW.QUERY.INDEXES index statistics";
+  const mapping2 = requiredMap2(value, context);
+  for (const name of [
+    "oldest_collected_at_ms",
+    "newest_collected_at_ms",
+    "oldest_age_ms",
+    "newest_age_ms"
+  ]) {
+    if (!hasKey(mapping2, name)) {
+      throw decodeError(
+        `${context} is missing required nullable fields`,
+        value
+      );
+    }
+  }
+  const samples = indexCounter(mapping2, "samples", "statistics");
+  const freshSamples = indexCounter(mapping2, "fresh_samples", "statistics");
+  const staleSamples = indexCounter(mapping2, "stale_samples", "statistics");
+  const futureSamples = indexCounter(mapping2, "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(mapping2, "status", context, [
+      "fresh",
+      "stale",
+      "future",
+      "mixed",
+      "missing",
+      "unavailable"
+    ]),
+    samples,
+    freshSamples,
+    staleSamples,
+    futureSamples,
+    oldestCollectedAtMs: optionalIndexInteger(
+      mapping2,
+      "oldest_collected_at_ms",
+      context
+    ),
+    newestCollectedAtMs: optionalIndexInteger(
+      mapping2,
+      "newest_collected_at_ms",
+      context
+    ),
+    oldestAgeMs: optionalIndexInteger(mapping2, "oldest_age_ms", context),
+    newestAgeMs: optionalIndexInteger(mapping2, "newest_age_ms", context),
+    raw: freezeMap(mapping2)
+  });
+}
+function decodeIndexProgress(mapping2, section, allowedPhases) {
+  const context = `FLOW.QUERY.INDEXES index ${section}`;
+  const completedShards = unsignedIndexInteger(
+    field(mapping2, "completed_shards"),
+    `${context} completed_shards`
+  );
+  const totalShards = positiveIndexInteger(
+    field(mapping2, "total_shards"),
+    `${context} total_shards`
+  );
+  if (indexInteger2(completedShards) > indexInteger2(totalShards)) {
+    throw decodeError(
+      `${context} completed_shards exceeds total_shards`,
+      mapping2
+    );
+  }
+  return Object.freeze({
+    scope: requiredChoice(mapping2, "scope", context, ["catalog_build"]),
+    phaseCounts: decodePhaseCounts(field(mapping2, "phase_counts"), section),
+    currentPhases: decodeAllowedPhases(
+      field(mapping2, "current_phases"),
+      section,
+      allowedPhases
+    ),
+    completedShards,
+    totalShards,
+    raw: freezeMap(mapping2)
+  });
+}
+function decodePhaseCounts(value, section) {
+  const context = `FLOW.QUERY.INDEXES index ${section} phase_counts`;
+  const mapping2 = requiredMap2(value, context);
+  const entries = mapping2 instanceof Map ? [...mapping2.entries()] : Object.entries(mapping2);
+  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 mapping2 = requiredMap2(value, "FLOW.QUERY.INDEXES");
   requireContract(
-    mapping,
+    mapping2,
     "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"
+  const registry = requiredMap2(
+    field(mapping2, "registry"),
+    "FLOW.QUERY.INDEXES registry"
   );
-  const rawIndexes = field(mapping, "indexes");
+  const services = decodeIndexServices(field(mapping2, "services"));
+  const rawIndexes = field(mapping2, "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(
-      field(mapping, "observed_at_ms"),
+    observedAtMs: unsignedIndexInteger(
+      field(mapping2, "observed_at_ms"),
       "FLOW.QUERY.INDEXES observed_at_ms"
     ),
-    statisticsMaxAgeMs: nonNegativeInteger(
-      field(mapping, "statistics_max_age_ms"),
+    statisticsMaxAgeMs: unsignedIndexInteger(
+      field(mapping2, "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"
       )
     }),
     services,
     indexes: Object.freeze(indexes),
-    raw: freezeMap(mapping)
+    raw: freezeMap(mapping2)
+  });
+  validateFlowQueryIndexContract(status, expectedId);
+  return status;
+}
+function decodeIndex(value, index) {
+  const mapping2 = requiredMap2(value, `FLOW.QUERY.INDEXES index ${index}`);
+  const fields = decodeIndexFields(field(mapping2, "fields"));
+  return Object.freeze({
+    id: requiredBoundedText2(mapping2, "id", "FLOW.QUERY.INDEXES index", 64),
+    version: positiveIndexInteger(
+      field(mapping2, "version"),
+      "FLOW.QUERY.INDEXES index version"
+    ),
+    buildId: requiredBoundedText2(
+      mapping2,
+      "build_id",
+      "FLOW.QUERY.INDEXES index",
+      128
+    ),
+    source: requiredChoice(mapping2, "source", "FLOW.QUERY.INDEXES index", [
+      "runs"
+    ]),
+    state: requiredChoice(mapping2, "state", "FLOW.QUERY.INDEXES index", [
+      "building",
+      "validating",
+      "active",
+      "retiring",
+      "failed"
+    ]),
+    queryable: requiredBoolean(
+      mapping2,
+      "queryable",
+      "FLOW.QUERY.INDEXES index"
+    ),
+    fields,
+    workloads: decodeUniqueTextArray(
+      field(mapping2, "workloads"),
+      "FLOW.QUERY.INDEXES index workloads",
+      16,
+      64
+    ),
+    countPrefixes: decodeCountPrefixes(
+      field(mapping2, "count_prefixes"),
+      fields.length
+    ),
+    coveringFields: decodeCoveringFields(mapping2),
+    format: decodeIndexFormat(mapping2),
+    coverage: decodeIndexCoverage(field(mapping2, "coverage")),
+    build: decodeIndexBuild(field(mapping2, "build")),
+    validation: decodeIndexValidation(field(mapping2, "validation")),
+    retirement: decodeIndexRetirement(field(mapping2, "retirement")),
+    statistics: decodeIndexStatistics(field(mapping2, "statistics")),
+    raw: freezeMap(mapping2)
+  });
+}
+function decodeIndexServices(value) {
+  const mapping2 = requiredMap2(value, "FLOW.QUERY.INDEXES services");
+  const choices = ["ready", "unavailable"];
+  return Object.freeze({
+    registry: requiredChoice(
+      mapping2,
+      "registry",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    lifecycleWorker: requiredChoice(
+      mapping2,
+      "lifecycle_worker",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    statisticsStore: requiredChoice(
+      mapping2,
+      "statistics_store",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    statisticsWorker: requiredChoice(
+      mapping2,
+      "statistics_worker",
+      "FLOW.QUERY.INDEXES services",
+      choices
+    ),
+    raw: freezeMap(mapping2)
+  });
+}
+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 mapping2 = requiredMap2(
+      value[index],
+      `FLOW.QUERY.INDEXES index field ${index}`
+    );
+    const name = requiredBoundedText2(
+      mapping2,
+      "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(
+        mapping2,
+        "direction",
+        "FLOW.QUERY.INDEXES index field",
+        ["asc", "desc"]
+      ),
+      encoding: requiredChoice(
+        mapping2,
+        "encoding",
+        "FLOW.QUERY.INDEXES index field",
+        ["hashed", "ordered"]
+      ),
+      raw: freezeMap(mapping2)
+    });
+  }
+  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(mapping2) {
+  const raw = field(mapping2, "covering_fields");
+  if (!Array.isArray(raw) || raw.length > 32) {
+    throw decodeError(
+      "FLOW.QUERY.INDEXES index covering_fields must contain at most 32 entries",
+      raw
+    );
+  }
+  const fields = new Array(raw.length);
+  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
+      );
+    }
+    const value = boundedText(
+      raw[index],
+      `FLOW.QUERY.INDEXES index covering_fields entry ${index}`,
+      512
+    );
+    if (seen.has(value)) {
+      throw decodeError(
+        "FLOW.QUERY.INDEXES index covering_fields contains duplicates",
+        raw
+      );
+    }
+    seen.add(value);
+    fields[index] = value;
+  }
+  return Object.freeze(fields);
+}
+function decodeIndexFormat(mapping2) {
+  const raw = requiredMap2(
+    field(mapping2, "format"),
+    "FLOW.QUERY.INDEXES index format"
+  );
+  if (!hasKey(raw, "counter")) {
+    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
+  );
+  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
+    ),
+    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, (mapping2) => freezeMap(mapping2));
+  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,
+    (mapping2, index) => decodeRecord(mapping2 instanceof Map ? freezeMap(mapping2) : mapping2, 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 mapping2 = requiredMap2(value, "FLOW.QUERY result");
+  requireContract(mapping2, "version", FLOW_QUERY_RESULT_CONTRACT, "FLOW.QUERY result");
+  const quality = decodeQuality(field(mapping2, "quality"));
+  const usage = decodeUsage(field(mapping2, "usage"));
+  const hasRecords = hasKey(mapping2, "records");
+  const hasCount = hasKey(mapping2, "result");
+  if (hasRecords === hasCount) {
+    throw decodeError("FLOW.QUERY result must contain exactly one records or count shape", value);
+  }
+  const raw = freezeMap(mapping2);
+  if (hasRecords) {
+    const rawRecords = field(mapping2, "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(mapping2, "page")),
+      quality,
+      usage,
+      raw
+    };
+  }
+  if (hasKey(mapping2, "page")) {
+    throw decodeError("FLOW.QUERY count result contains an unexpected page", value);
+  }
+  const countResult = requiredMap2(field(mapping2, "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 mapping2 = requiredMap2(value, "FLOW.QUERY explain");
+  requireContract(mapping2, "version", FLOW_EXPLAIN_CONTRACT, "FLOW.QUERY explain");
+  const queryFingerprint = requiredText2(mapping2, "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(mapping2, "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(mapping2, "plan"), "FLOW.QUERY explain plan"),
+    "FLOW.QUERY explain plan"
+  );
+  const estimate = freezeMetadataMap(
+    requiredMap2(field(mapping2, "estimate"), "FLOW.QUERY explain estimate"),
+    "FLOW.QUERY explain estimate"
+  );
+  const bounds = freezeMetadataMap(
+    requiredMap2(field(mapping2, "bounds"), "FLOW.QUERY explain bounds"),
+    "FLOW.QUERY explain bounds"
+  );
+  const capabilities = decodeExplainCapabilities(mapping2);
+  const extendedFields = ["stats", "quality", "pressure", "decision", "alternatives"];
+  const extendedPresence = extendedFields.map((name) => hasKey(mapping2, 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(mapping2, "actual") || hasKey(mapping2, "diagnostic")) {
+      throw decodeError("FLOW.QUERY specialized explain has extended status fields", value);
+    }
+    alternatives = Object.freeze([]);
+  } else {
+    if (!extendedPresence.every(Boolean) || !hasKey(mapping2, "actual") || !hasKey(mapping2, "diagnostic")) {
+      throw decodeError("FLOW.QUERY explain is missing required v1 fields", value);
+    }
+    stats = freezeMetadataMap(
+      requiredMap2(field(mapping2, "stats"), "FLOW.QUERY explain stats"),
+      "FLOW.QUERY explain stats"
+    );
+    quality = decodeQuality(field(mapping2, "quality"));
+    pressure = freezeMetadataMap(
+      requiredMap2(field(mapping2, "pressure"), "FLOW.QUERY explain pressure"),
+      "FLOW.QUERY explain pressure"
+    );
+    decision = freezeMetadataMap(
+      requiredMap2(field(mapping2, "decision"), "FLOW.QUERY explain decision"),
+      "FLOW.QUERY explain decision"
+    );
+    alternatives = decodeExplainAlternatives(field(mapping2, "alternatives"));
+  }
+  const actualValue = field(mapping2, "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(mapping2, "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(mapping2)
   });
 }
-function decodeIndex(value, index) {
-  const mapping = requiredMap2(value, `FLOW.QUERY.INDEXES index ${index}`);
+function decodeExplainCapabilities(mapping2) {
+  if (!hasKey(mapping2, "capabilities")) return void 0;
+  const value = requiredMap2(
+    field(mapping2, "capabilities"),
+    "FLOW.QUERY explain capabilities"
+  );
   return Object.freeze({
-    id: requiredText2(mapping, "id", "FLOW.QUERY.INDEXES index"),
-    version: positiveBoundedInteger(
-      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"),
-    coveringFields: decodeCoveringFields(mapping),
-    format: decodeIndexFormat(mapping),
-    raw: freezeMap(mapping)
+    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 decodeCoveringFields(mapping) {
-  const raw = field(mapping, "covering_fields");
-  if (!Array.isArray(raw) || raw.length > 32) {
+function decodeExplainCapabilityList(value, name) {
+  if (!Array.isArray(value) || value.length > 64) {
     throw decodeError(
-      "FLOW.QUERY.INDEXES index covering_fields must contain at most 32 entries",
-      raw
+      `FLOW.QUERY explain capabilities ${name} must contain at most 64 entries`,
+      value
     );
   }
-  const fields = new Array(raw.length);
+  const result = new Array(value.length);
   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);
+  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 value = boundedText(
-      raw[index],
-      `FLOW.QUERY.INDEXES index covering_fields entry ${index}`,
-      512
+    const capability = boundedText(
+      value[index],
+      `FLOW.QUERY explain capabilities ${name} entry ${index}`,
+      128
     );
-    if (seen.has(value)) {
-      throw decodeError("FLOW.QUERY.INDEXES index covering_fields contains duplicates", raw);
+    if (seen.has(capability)) {
+      throw decodeError(
+        `FLOW.QUERY explain capabilities ${name} contains duplicates`,
+        value
+      );
     }
-    seen.add(value);
-    fields[index] = value;
+    seen.add(capability);
+    result[index] = capability;
   }
-  return Object.freeze(fields);
+  return Object.freeze(result);
 }
-function decodeIndexFormat(mapping) {
-  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);
+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 counterValue = field(raw, "counter");
-  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),
-    counter,
-    raw: freezeMap(raw)
-  });
+  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");
+  const mapping2 = 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(mapping2, "exactness", QUALITY_VALUES2.exactness),
+    freshness: decodeQualityValue(mapping2, "freshness", QUALITY_VALUES2.freshness),
+    coverage: decodeQualityValue(mapping2, "coverage", QUALITY_VALUES2.coverage),
+    pagination: decodeQualityValue(mapping2, "pagination", QUALITY_VALUES2.pagination)
   });
 }
+function decodeQualityValue(mapping2, name, allowed) {
+  const value = requiredBoundedText2(mapping2, name, "FLOW.QUERY quality", 64);
+  if (!allowed.includes(value)) {
+    throw decodeError(`FLOW.QUERY quality ${name} is unsupported`, mapping2);
+  }
+  return value;
+}
 function decodeUsage(value) {
-  const mapping = requiredMap2(value, "FLOW.QUERY usage");
+  const mapping2 = requiredMap2(value, "FLOW.QUERY usage");
   const usage = /* @__PURE__ */ Object.create(null);
   for (const [wireName, property] of USAGE_FIELDS2) {
     usage[property] = nonNegativeInteger(
-      field(mapping, wireName),
+      field(mapping2, wireName),
       `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_") || Buffer45.byteLength(cursor) > 4096)) {
+  const mapping2 = requiredMap2(value, "FLOW.QUERY page");
+  const hasMore = requiredBoolean(mapping2, "has_more", "FLOW.QUERY page");
+  const cursor = optionalText2(mapping2, "cursor", "FLOW.QUERY page");
+  if (cursor != null && (!cursor.startsWith("fqc1_") || Buffer48.byteLength(cursor) < 16 || Buffer48.byteLength(cursor) > 4096)) {
     throw decodeError("FLOW.QUERY page cursor is invalid", value);
   }
   if (hasMore !== (cursor != null)) {
@@ -12332,26 +13444,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
 import "buffer";
 
 // src/client-core-helpers.ts
-import { Buffer as Buffer46 } from "buffer";
+import { Buffer as Buffer49 } from "buffer";
 function bgsaveResponse(response) {
-  if ((typeof response === "string" || Buffer46.isBuffer(response) || response instanceof Uint8Array) && text(response) === "Background saving started") {
+  if ((typeof response === "string" || Buffer49.isBuffer(response) || response instanceof Uint8Array) && text(response) === "Background saving started") {
     return true;
   }
   return okResponse(response);
@@ -12365,7 +13465,7 @@ function fetchOrComputeCompletionToken(options) {
       "fetch-or-compute completion requires computeToken"
     );
   }
-  if (!Buffer46.isBuffer(options.computeToken)) {
+  if (!Buffer49.isBuffer(options.computeToken)) {
     throw new TypeError("fetch-or-compute computeToken must be a Buffer");
   }
   return options.computeToken;
@@ -12451,12 +13551,12 @@ var ErrorMappingExecutor = class {
 
 // src/client-config.ts
 function snapshotClientOptions(options) {
-  const own = { ...options };
+  const own2 = { ...options };
   const snapshot = {
-    ...own,
-    ...typeof own.autoBatch === "object" && own.autoBatch != null ? { autoBatch: Object.freeze({ ...own.autoBatch }) } : {},
-    ...own.backpressure == null ? {} : { backpressure: Object.freeze({ ...own.backpressure }) },
-    ...typeof own.reconnect === "object" && own.reconnect != null ? { reconnect: Object.freeze({ ...own.reconnect }) } : {}
+    ...own2,
+    ...typeof own2.autoBatch === "object" && own2.autoBatch != null ? { autoBatch: Object.freeze({ ...own2.autoBatch }) } : {},
+    ...own2.backpressure == null ? {} : { backpressure: Object.freeze({ ...own2.backpressure }) },
+    ...typeof own2.reconnect === "object" && own2.reconnect != null ? { reconnect: Object.freeze({ ...own2.reconnect }) } : {}
   };
   return Object.freeze(snapshot);
 }
@@ -12725,14 +13825,14 @@ var FerricStoreAdministrationClient = class extends FerricStoreClientBase {
 };
 
 // src/store-utilities.ts
-import { Buffer as Buffer49 } from "buffer";
+import { Buffer as Buffer52 } from "buffer";
 function encode(codec, value) {
   return codec.encode(value);
 }
 function decode(codec, value) {
   if (value == null) return null;
-  if (Buffer49.isBuffer(value)) return codec.decode(value);
-  if (value instanceof Uint8Array) return codec.decode(Buffer49.from(value));
+  if (Buffer52.isBuffer(value)) return codec.decode(value);
+  if (value instanceof Uint8Array) return codec.decode(Buffer52.from(value));
   return value;
 }
 function number(value) {
@@ -14645,33 +15745,511 @@ var FerricStoreClientCore = class extends FerricStoreAdministrationClient {
   }
 };
 
-// src/client-management.ts
-var FerricStoreManagementClient = class extends FerricStoreClientCore {
-  async stats(type, options = {}) {
-    const args = ["FLOW.STATS", type];
-    append(args, "STATE", options.state);
-    append(args, "COUNT", options.count);
-    append(args, "PARTITION", options.partitionKey);
-    appendAttributes(args, options.attributes);
-    appendBool(args, "CONSISTENT_PROJECTION", options.consistentProjection);
-    return adminRecordResponse(await this.commandArgs(args), "FLOW.STATS");
+// src/schedule-request.ts
+var MAX_EXACT_INTEGER = Number.MAX_SAFE_INTEGER;
+var SCHEDULE_KINDS = /* @__PURE__ */ new Set(["one_shot", "delay", "interval", "cron"]);
+var RECURRING_KINDS = /* @__PURE__ */ new Set(["interval", "cron"]);
+var OVERLAP_POLICIES = /* @__PURE__ */ new Set([
+  "allow",
+  "skip",
+  "queue_after_previous",
+  "fail_schedule"
+]);
+var SCHEDULE_STATES = /* @__PURE__ */ new Set([
+  "active",
+  "paused",
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+  "all"
+]);
+var TARGET_FIELDS = /* @__PURE__ */ new Set([
+  "correlation_id",
+  "id",
+  "id_prefix",
+  "parent_flow_id",
+  "partition_key",
+  "payload",
+  "payload_ref",
+  "priority",
+  "root_flow_id",
+  "run_at_ms",
+  "state",
+  "type",
+  "value_refs",
+  "values"
+]);
+var TARGET_TEXT_FIELDS = [
+  "state",
+  "id",
+  "id_prefix",
+  "partition_key",
+  "correlation_id",
+  "parent_flow_id",
+  "root_flow_id",
+  "payload_ref"
+];
+var INTERNAL_SCHEDULE_TYPE = "__ferricstore_schedule";
+var INTERNAL_SCHEDULE_ID_PREFIX = "__ferricstore_schedule__:";
+function validateScheduleCreate(id, options) {
+  requiredText3(id, "id");
+  if (!mapping(options)) throw new TypeError("schedule options must be a mapping");
+  const kind = effectiveKind(options);
+  validateTiming(kind, options);
+  const recurring = RECURRING_KINDS.has(kind);
+  validateTarget(options.target, recurring);
+  nonNegativeInteger2(options.atMs, "at_ms");
+  nonNegativeInteger2(options.delayMs, "delay_ms");
+  nonNegativeInteger2(options.startAtMs, "start_at_ms");
+  positiveInteger2(options.everyMs, "every_ms");
+  positiveInteger2(options.overlapRetryMs, "overlap_retry_ms");
+  positiveInteger2(options.maxFires, "max_fires");
+  nonNegativeInteger2(options.endAtMs, "end_at_ms");
+  nonNegativeInteger2(options.nowMs, "now_ms");
+  optionalBoolean(options.overwrite, "overwrite");
+  if (kind === "delay") {
+    if (options.delayMs == null) throw new TypeError("delay_ms is required for delay schedules");
+    if (options.nowMs != null && options.nowMs > MAX_EXACT_INTEGER - options.delayMs) {
+      throw new TypeError("now_ms plus delay_ms exceeds the exact integer range");
+    }
+  }
+  if (kind === "interval" && options.everyMs == null) {
+    throw new TypeError("every_ms is required for interval schedules");
+  }
+  if (kind === "cron") {
+    requiredText3(options.cron, "cron");
+    optionalText3(options.timezone, "timezone");
+  } else if (options.timezone != null) {
+    throw new TypeError("timezone is only supported for cron schedules");
+  }
+  if (kind === "interval") {
+    if (options.catchupPolicy != null && options.catchupPolicy !== "fire_once") {
+      throw new TypeError("catchup_policy must be fire_once");
+    }
+  } else if (options.catchupPolicy != null) {
+    throw new TypeError("catchup_policy is only supported for interval schedules");
+  }
+  if (recurring) {
+    if (options.overlapPolicy != null && !OVERLAP_POLICIES.has(options.overlapPolicy)) {
+      throw new TypeError(
+        "overlap_policy must be allow, skip, queue_after_previous, or fail_schedule"
+      );
+    }
+    if (options.overlapRetryMs != null && options.overlapPolicy !== "queue_after_previous") {
+      throw new TypeError("overlap_retry_ms requires overlap_policy queue_after_previous");
+    }
+    const firstRun = knownFirstRun(kind, options);
+    if (options.endAtMs != null && firstRun != null && options.endAtMs < firstRun) {
+      throw new TypeError("end_at_ms must be at or after first run");
+    }
+  } else {
+    if (options.overlapPolicy != null) {
+      throw new TypeError("overlap_policy is only supported for recurring schedules");
+    }
+    if (options.overlapRetryMs != null) {
+      throw new TypeError("overlap_retry_ms requires overlap_policy queue_after_previous");
+    }
+    if (options.maxFires != null) {
+      throw new TypeError("max_fires is only supported for recurring schedules");
+    }
+    if (options.endAtMs != null) {
+      throw new TypeError("end_at_ms is only supported for recurring schedules");
+    }
   }
-  async countByState(type, state, options = {}) {
-    const stats = await this.stats(type, { ...options, state });
-    if (!("count" in stats)) throw new TypeError("FLOW.STATS response missing count");
-    return integer(stats.count);
+}
+function validateScheduleID(id) {
+  requiredText3(id, "id");
+}
+function validateScheduleFire(id, options) {
+  validateScheduleID(id);
+  nonNegativeInteger2(options.fireAtMs, "fire_at_ms");
+  nonNegativeInteger2(options.nowMs, "now_ms");
+}
+function validateScheduleStatus(id, nowMs2) {
+  validateScheduleID(id);
+  nonNegativeInteger2(nowMs2, "now_ms");
+}
+function validateScheduleFireDue(options) {
+  if (!mapping(options)) throw new TypeError("schedule fire-due options must be a mapping");
+  nonNegativeInteger2(options.nowMs, "now_ms");
+  optionalText3(options.worker, "worker");
+  positiveInteger2(options.leaseMs, "lease_ms");
+  nonNegativeInteger2(options.blockMs, "block_ms");
+  positiveInteger2(options.limit, "limit");
+  const leaseMs = options.leaseMs ?? 3e4;
+  if (options.nowMs != null && options.nowMs > MAX_EXACT_INTEGER - leaseMs) {
+    throw new TypeError("now_ms plus lease_ms exceeds the exact integer range");
   }
-  async attributes(type, options = {}) {
-    const args = ["FLOW.ATTRIBUTES", type];
-    appendAttributeQueryOptions(args, options);
-    return adminRecordList(await this.commandArgs(args), "FLOW.ATTRIBUTES");
+}
+function validateScheduleList(options) {
+  if (!mapping(options)) throw new TypeError("schedule list options must be a mapping");
+  if (options.kind != null && !SCHEDULE_KINDS.has(options.kind)) {
+    throw new TypeError("kind must be one_shot, delay, interval, or cron");
   }
-  async attributeValues(type, attribute, options = {}) {
-    const args = ["FLOW.ATTRIBUTE_VALUES", type, attribute];
-    appendAttributeQueryOptions(args, options);
-    return adminRecordList(await this.commandArgs(args), "FLOW.ATTRIBUTE_VALUES");
+  if (options.state != null && !SCHEDULE_STATES.has(options.state)) {
+    throw new TypeError("state is invalid");
+  }
+  optionalText3(options.timezone, "timezone");
+  optionalText3(options.targetType, "target_type");
+  nonNegativeInteger2(options.fromMs, "from_ms");
+  nonNegativeInteger2(options.toMs, "to_ms");
+  if (options.fromMs != null && options.toMs != null && options.fromMs > options.toMs) {
+    throw new TypeError("from_ms must not exceed to_ms");
+  }
+  positiveInteger2(options.count, "count");
+  optionalBoolean(options.rev, "rev");
+}
+function effectiveKind(options) {
+  if (options.kind != null) {
+    if (!SCHEDULE_KINDS.has(options.kind)) {
+      throw new TypeError("kind must be one_shot, delay, interval, or cron");
+    }
+    return options.kind;
+  }
+  if (options.cron != null) return "cron";
+  if (options.everyMs != null) return "interval";
+  if (options.delayMs != null) return "delay";
+  return "one_shot";
+}
+function validateTiming(kind, options) {
+  if (options.atMs != null && options.startAtMs != null) {
+    throw new TypeError("cannot set both at_ms and start_at_ms");
+  }
+  if (options.delayMs != null && kind !== "delay") {
+    throw new TypeError("delay_ms is only supported for delay schedules");
+  }
+  if (options.everyMs != null && kind !== "interval") {
+    throw new TypeError("every_ms is only supported for interval schedules");
+  }
+  if (options.cron != null && kind !== "cron") {
+    throw new TypeError("cron is only supported for cron schedules");
+  }
+  if (kind === "delay" && (options.atMs != null || options.startAtMs != null)) {
+    throw new TypeError("at_ms and start_at_ms are not supported for delay schedules");
   }
+}
+function validateTarget(value, recurring) {
+  if (!mapping(value)) throw new TypeError("target must be a mapping with a non-empty type");
+  const target = value;
+  for (const key of Object.keys(target)) {
+    if (!TARGET_FIELDS.has(key)) throw new TypeError(`target contains unknown field ${key}`);
+  }
+  const type = own(target, "type");
+  requiredText3(type, "target type");
+  if (type === INTERNAL_SCHEDULE_TYPE) {
+    throw new TypeError("target type is reserved for internal use");
+  }
+  for (const key of TARGET_TEXT_FIELDS) optionalText3(own(target, key), `target ${key}`);
+  const id = own(target, "id");
+  const idPrefix = own(target, "id_prefix");
+  if (id != null && idPrefix != null) {
+    throw new TypeError("target cannot set both id and id_prefix");
+  }
+  if (recurring && id != null) {
+    throw new TypeError("target id is not supported for recurring schedules; use id_prefix");
+  }
+  if (typeof id === "string" && id.startsWith(INTERNAL_SCHEDULE_ID_PREFIX)) {
+    throw new TypeError("target id is reserved for internal use");
+  }
+  if (typeof idPrefix === "string" && idPrefix.startsWith(INTERNAL_SCHEDULE_ID_PREFIX)) {
+    throw new TypeError("target id_prefix is reserved for internal use");
+  }
+  nonNegativeInteger2(own(target, "run_at_ms"), "target run_at_ms");
+  const priority = own(target, "priority");
+  if (priority != null && (typeof priority !== "number" || !Number.isSafeInteger(priority) || priority < 0 || priority > 2)) {
+    throw new TypeError("target priority must be an integer between 0 and 2");
+  }
+}
+function knownFirstRun(kind, options) {
+  if (kind === "delay") {
+    if (options.nowMs == null || options.delayMs == null) return void 0;
+    return options.nowMs + options.delayMs;
+  }
+  if (kind === "cron") return options.startAtMs ?? options.atMs ?? options.nowMs;
+  return options.atMs ?? options.startAtMs ?? options.nowMs;
+}
+function requiredText3(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+}
+function optionalText3(value, name) {
+  if (value != null) requiredText3(value, name);
+}
+function nonNegativeInteger2(value, name) {
+  if (value != null && (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) {
+    throw new TypeError(`${name} must be a non-negative exact integer`);
+  }
+}
+function positiveInteger2(value, name) {
+  if (value != null && (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)) {
+    throw new TypeError(`${name} must be a positive exact integer`);
+  }
+}
+function optionalBoolean(value, name) {
+  if (value != null && typeof value !== "boolean") {
+    throw new TypeError(`${name} must be a boolean`);
+  }
+}
+function mapping(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function own(mapping2, key) {
+  return Object.prototype.hasOwnProperty.call(mapping2, key) ? mapping2[key] : void 0;
+}
+
+// src/schedule-response.ts
+var SCHEDULE_INTEGER_FIELDS = [
+  "end_at_ms",
+  "last_catchup_at_ms",
+  "last_fire_at_ms",
+  "last_overlap_at_ms",
+  "last_skipped_at_ms",
+  "max_fires",
+  "next_run_at_ms",
+  "overlap_queued_due_at_ms"
+];
+var REQUIRED_SCHEDULE_INTEGER_FIELDS = [
+  "attempts",
+  "coalesced_count",
+  "fire_count",
+  "last_coalesced_count",
+  "skipped_count"
+];
+var OPTIONAL_SCHEDULE_TEXT_FIELDS = [
+  "cron",
+  "end_reason",
+  "flow_id",
+  "last_overlap_reason",
+  "last_overlap_target_id",
+  "last_planning_error",
+  "last_target_id",
+  "timezone"
+];
+var SCHEDULE_KINDS2 = /* @__PURE__ */ new Set(["one_shot", "delay", "interval", "cron"]);
+var SCHEDULE_STATES2 = /* @__PURE__ */ new Set([
+  "active",
+  "paused",
+  "running",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+var SCHEDULE_OVERLAP_POLICIES = /* @__PURE__ */ new Set([
+  "allow",
+  "skip",
+  "queue_after_previous",
+  "fail_schedule"
+]);
+function scheduleRecordResponse(value, context) {
+  const record = adminRecordResponse(value, context);
+  if (typeof record.id !== "string" || record.id.length === 0) {
+    throw new TypeError(`${context} response missing id`);
+  }
+  if (typeof record.kind !== "string" || !SCHEDULE_KINDS2.has(record.kind)) {
+    throw new TypeError(`${context} response missing or invalid kind`);
+  }
+  if (typeof record.state !== "string" || !SCHEDULE_STATES2.has(record.state)) {
+    throw new TypeError(`${context} response missing or invalid state`);
+  }
+  if (typeof record.target !== "object" || record.target == null || Array.isArray(record.target)) {
+    throw new TypeError(`${context} response missing or invalid target`);
+  }
+  const target = record.target;
+  if (typeof target.type !== "string" || target.type.length === 0) {
+    throw new TypeError(`${context} response missing or invalid target type`);
+  }
+  if (!("catchup_policy" in record) || record.kind === "interval" && record.catchup_policy !== "fire_once" || record.kind !== "interval" && record.catchup_policy != null) {
+    throw new TypeError(`${context} returned an invalid catchup_policy`);
+  }
+  if (typeof record.overlap_policy !== "string" || !SCHEDULE_OVERLAP_POLICIES.has(record.overlap_policy)) {
+    throw new TypeError(`${context} response missing or invalid overlap_policy`);
+  }
+  safeNonNegativeInteger(record, "created_at_ms", context, true);
+  const everyMs = requiredNullableNonNegativeInteger(record, "every_ms", context);
+  const cron = requiredNullableResponseText(record, "cron", context);
+  const timezone = requiredNullableResponseText(record, "timezone", context);
+  const overlapRetryMs = requiredNullableNonNegativeInteger(
+    record,
+    "overlap_retry_ms",
+    context
+  );
+  validateRecurrence(record, context, everyMs, cron, timezone, overlapRetryMs);
+  let coalescedCount = 0;
+  let lastCoalescedCount = 0;
+  for (const field3 of REQUIRED_SCHEDULE_INTEGER_FIELDS) {
+    const value2 = safeNonNegativeInteger(record, field3, context, true);
+    if (field3 === "coalesced_count") coalescedCount = value2;
+    if (field3 === "last_coalesced_count") lastCoalescedCount = value2;
+  }
+  for (const field3 of SCHEDULE_INTEGER_FIELDS) {
+    if (record[field3] != null) safeNonNegativeInteger(record, field3, context);
+  }
+  for (const field3 of OPTIONAL_SCHEDULE_TEXT_FIELDS) {
+    optionalResponseText(record, field3, context);
+  }
+  validateCatchupState(record, context, coalescedCount, lastCoalescedCount);
+  return record;
+}
+function validateRecurrence(record, context, everyMs, cron, timezone, overlapRetryMs) {
+  if (record.kind === "interval") {
+    if (everyMs == null || everyMs <= 0) {
+      throw new TypeError(`${context} interval every_ms must be positive`);
+    }
+  } else if (everyMs != null) {
+    throw new TypeError(`${context} every_ms is only valid for interval schedules`);
+  }
+  if (record.kind === "cron") {
+    if (cron == null) throw new TypeError(`${context} cron schedule is missing cron`);
+    if (timezone == null) throw new TypeError(`${context} cron schedule is missing timezone`);
+  } else if (cron != null) {
+    throw new TypeError(`${context} cron is only valid for cron schedules`);
+  } else if (timezone != null) {
+    throw new TypeError(`${context} timezone is only valid for cron schedules`);
+  }
+  if (record.kind !== "interval" && record.kind !== "cron" && record.overlap_policy !== "allow") {
+    throw new TypeError(`${context} overlap_policy is only valid for recurring schedules`);
+  }
+  if (overlapRetryMs != null) {
+    if (overlapRetryMs <= 0) {
+      throw new TypeError(`${context} overlap_retry_ms must be positive`);
+    }
+    if (record.overlap_policy !== "queue_after_previous") {
+      throw new TypeError(`${context} overlap_retry_ms requires queue_after_previous`);
+    }
+  }
+}
+function validateCatchupState(record, context, coalescedCount, lastCoalescedCount) {
+  const lastCatchupAt = record.last_catchup_at_ms;
+  if (record.kind !== "interval") {
+    if (coalescedCount !== 0) {
+      throw new TypeError(`${context} non-interval coalesced_count must be zero`);
+    }
+    if (lastCoalescedCount !== 0) {
+      throw new TypeError(`${context} non-interval last_coalesced_count must be zero`);
+    }
+    if (lastCatchupAt != null) {
+      throw new TypeError(`${context} non-interval last_catchup_at_ms must be null`);
+    }
+    return;
+  }
+  if (lastCoalescedCount > coalescedCount) {
+    throw new TypeError(`${context} last_coalesced_count exceeds coalesced_count`);
+  }
+  if (lastCoalescedCount > 0 && lastCatchupAt == null) {
+    throw new TypeError(`${context} response missing last_catchup_at_ms after catch-up`);
+  }
+  if (lastCoalescedCount === 0 && lastCatchupAt != null) {
+    throw new TypeError(`${context} last_catchup_at_ms requires a catch-up`);
+  }
+}
+function optionalScheduleRecord(value, context) {
+  return value == null ? null : scheduleRecordResponse(value, context);
+}
+function scheduleRecordList(value, context) {
+  return arrayResponse(value).map((item) => scheduleRecordResponse(item, context));
+}
+function scheduleFireDueResponse(value) {
+  const context = "FLOW.SCHEDULE.FIRE_DUE";
+  const record = adminRecordResponse(value, context);
+  const claimed = safeNonNegativeInteger(record, "claimed", context, true);
+  const fired = safeNonNegativeInteger(record, "fired", context, true);
+  const skipped = safeNonNegativeInteger(record, "skipped", context, true);
+  const coalesced = safeNonNegativeInteger(record, "coalesced", context, true);
+  if (!Array.isArray(record.errors)) {
+    throw new TypeError(`${context} response missing errors`);
+  }
+  for (const error of record.errors) {
+    if (!Array.isArray(error) || error.length !== 2 || typeof error[0] !== "string" || error[0].length === 0 || typeof error[1] !== "string" || error[1].length === 0) {
+      throw new TypeError(`${context} returned an invalid error entry`);
+    }
+  }
+  if (fired + skipped + record.errors.length !== claimed) {
+    throw new TypeError(`${context} outcomes do not equal claimed`);
+  }
+  optionalResponseText(record, "claim_error", context);
+  const lastTargetId = optionalResponseText(record, "last_target_id", context);
+  const lastSkipReason = optionalResponseText(record, "last_skip_reason", context);
+  if (fired > 0 && lastTargetId == null) {
+    throw new TypeError(`${context} response missing last_target_id`);
+  }
+  if (fired === 0 && lastTargetId != null) {
+    throw new TypeError(`${context} last_target_id requires a fired outcome`);
+  }
+  if (skipped > 0 && lastSkipReason == null) {
+    throw new TypeError(`${context} response missing last_skip_reason`);
+  }
+  if (skipped === 0 && lastSkipReason != null) {
+    throw new TypeError(`${context} last_skip_reason requires a skipped outcome`);
+  }
+  if (coalesced > 0 && fired + skipped === 0) {
+    throw new TypeError(`${context} coalesced count requires a fired or skipped outcome`);
+  }
+  return record;
+}
+function scheduleFireResponse(value) {
+  const context = "FLOW.SCHEDULE.FIRE";
+  const record = adminRecordResponse(value, context);
+  const schedule = scheduleRecordResponse(record.schedule, `${context} schedule`);
+  const fired = safeNonNegativeInteger(record, "fired", context, true);
+  const skipped = record.skipped == null ? 0 : safeNonNegativeInteger(record, "skipped", context);
+  if (fired > 1 || skipped > 1 || fired + skipped !== 1) {
+    throw new TypeError(`${context} outcomes must equal one`);
+  }
+  if (fired === 1 && (typeof record.target_id !== "string" || record.target_id.length === 0)) {
+    throw new TypeError(`${context} response missing target_id`);
+  }
+  if (skipped === 1 && (typeof record.reason !== "string" || record.reason.length === 0)) {
+    throw new TypeError(`${context} response missing reason`);
+  }
+  if (fired === 0 && record.target_id != null) {
+    throw new TypeError(`${context} target_id requires a fired outcome`);
+  }
+  if (skipped === 0 && record.reason != null) {
+    throw new TypeError(`${context} reason requires a skipped outcome`);
+  }
+  return { ...record, fired, skipped, schedule };
+}
+function optionalResponseText(record, field3, context) {
+  const value = record[field3];
+  if (value == null) return void 0;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${context} ${field3} must be non-empty text`);
+  }
+  return value;
+}
+function requiredNullableResponseText(record, field3, context) {
+  if (!(field3 in record)) throw new TypeError(`${context} response missing ${field3}`);
+  if (record[field3] === void 0) {
+    throw new TypeError(`${context} response missing ${field3}`);
+  }
+  return optionalResponseText(record, field3, context) ?? null;
+}
+function requiredNullableNonNegativeInteger(record, field3, context) {
+  if (!(field3 in record)) throw new TypeError(`${context} response missing ${field3}`);
+  if (record[field3] === void 0) {
+    throw new TypeError(`${context} response missing ${field3}`);
+  }
+  if (record[field3] === null) return null;
+  return safeNonNegativeInteger(record, field3, context);
+}
+function safeNonNegativeInteger(record, field3, context, required = false) {
+  if (!(field3 in record) || record[field3] == null) {
+    if (required) throw new TypeError(`${context} response missing ${field3}`);
+    return 0;
+  }
+  const value = record[field3];
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`${context} ${field3} must be a safe non-negative integer`);
+  }
+  return value;
+}
+
+// src/client-schedules.ts
+var FerricStoreScheduleClient = class extends FerricStoreClientCore {
   async scheduleCreate(id, options) {
+    validateScheduleCreate(id, options);
     const args = ["FLOW.SCHEDULE.CREATE", id];
     append(args, "KIND", options.kind);
     append(args, "AT_MS", options.atMs);
@@ -14681,6 +16259,7 @@ var FerricStoreManagementClient = class extends FerricStoreClientCore {
     append(args, "CRON", options.cron);
     append(args, "TIMEZONE", options.timezone);
     append(args, "TARGET", options.target);
+    append(args, "CATCHUP_POLICY", options.catchupPolicy);
     append(args, "OVERLAP_POLICY", options.overlapPolicy);
     append(args, "OVERLAP_RETRY_MS", options.overlapRetryMs);
     append(args, "MAX_FIRES", options.maxFires);
@@ -14690,34 +16269,55 @@ var FerricStoreManagementClient = class extends FerricStoreClientCore {
     for (const [name, value] of Object.entries(options.extraOptions ?? {})) {
       args.push(name.toUpperCase(), value);
     }
-    return adminRecordResponse(await this.commandArgs(args), "FLOW.SCHEDULE.CREATE");
+    return scheduleRecordResponse(await this.commandArgs(args), "FLOW.SCHEDULE.CREATE");
   }
-  async scheduleGet(id, options = {}) {
-    const args = ["FLOW.SCHEDULE.GET", id];
-    append(args, "NOW", options.nowMs);
-    return optionalAdminRecord(await this.commandArgs(args), "FLOW.SCHEDULE.GET");
+  async scheduleGet(id) {
+    validateScheduleID(id);
+    return optionalScheduleRecord(
+      await this.commandArgs(["FLOW.SCHEDULE.GET", id]),
+      "FLOW.SCHEDULE.GET"
+    );
   }
   async scheduleFire(id, options = {}) {
-    return await this.scheduleStatus("FLOW.SCHEDULE.FIRE", id, options.nowMs);
+    validateScheduleFire(id, options);
+    const args = ["FLOW.SCHEDULE.FIRE", id];
+    append(args, "FIRE_AT_MS", options.fireAtMs);
+    append(args, "NOW", options.nowMs);
+    return scheduleFireResponse(await this.commandArgs(args));
   }
   async schedulePause(id, options = {}) {
-    return await this.scheduleStatus("FLOW.SCHEDULE.PAUSE", id, options.nowMs);
+    validateScheduleStatus(id, options.nowMs);
+    return scheduleRecordResponse(
+      await this.scheduleStatusResponse("FLOW.SCHEDULE.PAUSE", id, options.nowMs),
+      "FLOW.SCHEDULE.PAUSE"
+    );
   }
   async scheduleResume(id, options = {}) {
-    return await this.scheduleStatus("FLOW.SCHEDULE.RESUME", id, options.nowMs);
+    validateScheduleStatus(id, options.nowMs);
+    return scheduleRecordResponse(
+      await this.scheduleStatusResponse("FLOW.SCHEDULE.RESUME", id, options.nowMs),
+      "FLOW.SCHEDULE.RESUME"
+    );
   }
   async scheduleDelete(id, options = {}) {
-    return await this.scheduleStatus("FLOW.SCHEDULE.DELETE", id, options.nowMs);
+    validateScheduleStatus(id, options.nowMs);
+    const response = await this.scheduleStatusResponse("FLOW.SCHEDULE.DELETE", id, options.nowMs);
+    if (!okLike(response)) {
+      throw new TypeError("FLOW.SCHEDULE.DELETE response must be OK");
+    }
   }
   async scheduleFireDue(options = {}) {
+    validateScheduleFireDue(options);
     const args = ["FLOW.SCHEDULE.FIRE_DUE"];
     append(args, "NOW", options.nowMs);
     append(args, "WORKER", options.worker);
+    append(args, "LEASE_MS", options.leaseMs);
     append(args, "BLOCK", options.blockMs);
     append(args, "LIMIT", options.limit);
-    return adminRecordResponse(await this.commandArgs(args), "FLOW.SCHEDULE.FIRE_DUE");
+    return scheduleFireDueResponse(await this.commandArgs(args));
   }
   async scheduleList(options = {}) {
+    validateScheduleList(options);
     const args = ["FLOW.SCHEDULE.LIST"];
     append(args, "KIND", options.kind);
     append(args, "STATE", options.state);
@@ -14727,14 +16327,40 @@ var FerricStoreManagementClient = class extends FerricStoreClientCore {
     append(args, "TO_MS", options.toMs);
     append(args, "COUNT", options.count);
     appendBool(args, "REV", options.rev);
-    return adminRecordList(await this.commandArgs(args), "FLOW.SCHEDULE.LIST");
+    return scheduleRecordList(await this.commandArgs(args), "FLOW.SCHEDULE.LIST");
   }
-  async scheduleStatus(command, id, now) {
+  async scheduleStatusResponse(command, id, now) {
     const args = [command, id];
     append(args, "NOW", now);
-    const response = await this.commandArgs(args);
-    if (okLike(response)) return { id, status: "deleted" };
-    return adminRecordResponse(response, command);
+    return await this.commandArgs(args);
+  }
+};
+
+// src/client-management.ts
+var FerricStoreManagementClient = class extends FerricStoreScheduleClient {
+  async stats(type, options = {}) {
+    const args = ["FLOW.STATS", type];
+    append(args, "STATE", options.state);
+    append(args, "COUNT", options.count);
+    append(args, "PARTITION", options.partitionKey);
+    appendAttributes(args, options.attributes);
+    appendBool(args, "CONSISTENT_PROJECTION", options.consistentProjection);
+    return adminRecordResponse(await this.commandArgs(args), "FLOW.STATS");
+  }
+  async countByState(type, state, options = {}) {
+    const stats = await this.stats(type, { ...options, state });
+    if (!("count" in stats)) throw new TypeError("FLOW.STATS response missing count");
+    return integer(stats.count);
+  }
+  async attributes(type, options = {}) {
+    const args = ["FLOW.ATTRIBUTES", type];
+    appendAttributeQueryOptions(args, options);
+    return adminRecordList(await this.commandArgs(args), "FLOW.ATTRIBUTES");
+  }
+  async attributeValues(type, attribute, options = {}) {
+    const args = ["FLOW.ATTRIBUTE_VALUES", type, attribute];
+    appendAttributeQueryOptions(args, options);
+    return adminRecordList(await this.commandArgs(args), "FLOW.ATTRIBUTE_VALUES");
   }
   async effectReserve(id, effectKey, effectType, options) {
     const args = [
@@ -14967,7 +16593,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);
     }
@@ -15029,7 +16655,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) {
@@ -15062,7 +16688,7 @@ function throwIfClosed(signal) {
 }
 
 // src/flow-policy.ts
-import { Buffer as Buffer51 } from "buffer";
+import { Buffer as Buffer54 } from "buffer";
 var MAX_FLOW_POLICY_GENERATION = Number.MAX_SAFE_INTEGER;
 function assertFlowPolicyGeneration(value) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
@@ -15072,15 +16698,15 @@ function assertFlowPolicyGeneration(value) {
 function flowPolicySnapshotFromResp(value) {
   const policy = requiredRecord(value, "FLOW policy snapshot");
   const maxActiveMs = optionalPositiveInteger(field(policy, "max_active_ms"), "max_active_ms");
-  const state = optionalText3(field(policy, "state"), "state");
+  const state = optionalText4(field(policy, "state"), "state");
   const mode = optionalMode(field(policy, "mode"), "mode");
   const version = optionalVersion(field(policy, "version"));
-  const indexedStateMeta = optionalText3(field(policy, "indexed_state_meta"), "indexed_state_meta");
+  const indexedStateMeta = optionalText4(field(policy, "indexed_state_meta"), "indexed_state_meta");
   const governance = optionalRecord(field(policy, "governance"), "governance");
   const states = optionalStates(field(policy, "states"));
   return {
-    type: requiredText3(field(policy, "type"), "type"),
-    generation: nonNegativeInteger2(field(policy, "generation"), "generation"),
+    type: requiredText4(field(policy, "type"), "type"),
+    generation: nonNegativeInteger3(field(policy, "generation"), "generation"),
     ...state == null ? {} : { state },
     ...version == null ? {} : { version },
     ...mode == null ? {} : { mode },
@@ -15098,21 +16724,21 @@ function retrySnapshot(value, context) {
   const retry2 = requiredRecord(value, `FLOW policy ${context}`);
   const backoff = requiredRecord(field(retry2, "backoff"), `FLOW policy ${context}.backoff`);
   return {
-    maxRetries: nonNegativeInteger2(field(retry2, "max_retries"), `${context}.max_retries`),
+    maxRetries: nonNegativeInteger3(field(retry2, "max_retries"), `${context}.max_retries`),
     backoff: {
       kind: backoffKind(field(backoff, "kind"), `${context}.backoff.kind`),
-      baseMs: nonNegativeInteger2(field(backoff, "base_ms"), `${context}.backoff.base_ms`),
-      maxMs: nonNegativeInteger2(field(backoff, "max_ms"), `${context}.backoff.max_ms`),
-      jitterPct: nonNegativeInteger2(field(backoff, "jitter_pct"), `${context}.backoff.jitter_pct`)
+      baseMs: nonNegativeInteger3(field(backoff, "base_ms"), `${context}.backoff.base_ms`),
+      maxMs: nonNegativeInteger3(field(backoff, "max_ms"), `${context}.backoff.max_ms`),
+      jitterPct: nonNegativeInteger3(field(backoff, "jitter_pct"), `${context}.backoff.jitter_pct`)
     },
-    exhaustedTo: requiredText3(field(retry2, "exhausted_to"), `${context}.exhausted_to`)
+    exhaustedTo: requiredText4(field(retry2, "exhausted_to"), `${context}.exhausted_to`)
   };
 }
 function retentionSnapshot(value, context) {
   const retention = requiredRecord(value, `FLOW policy ${context}`);
   return {
-    ttlMs: nonNegativeInteger2(field(retention, "ttl_ms"), `${context}.ttl_ms`),
-    historyMaxEvents: nonNegativeInteger2(
+    ttlMs: nonNegativeInteger3(field(retention, "ttl_ms"), `${context}.ttl_ms`),
+    historyMaxEvents: nonNegativeInteger3(
       field(retention, "history_max_events"),
       `${context}.history_max_events`
     )
@@ -15148,11 +16774,11 @@ function requiredRecord(value, context) {
   if (value instanceof Map) {
     const result = {};
     for (const [key, item] of value.entries()) {
-      setOwnValue(result, requiredText3(key, `${context} key`), item);
+      setOwnValue(result, requiredText4(key, `${context} key`), item);
     }
     return result;
   }
-  if (typeof value === "object" && value != null && !Array.isArray(value) && !Buffer51.isBuffer(value) && !(value instanceof Uint8Array)) return value;
+  if (typeof value === "object" && value != null && !Array.isArray(value) && !Buffer54.isBuffer(value) && !(value instanceof Uint8Array)) return value;
   throw new TypeError(`${context} returned an unexpected response`);
 }
 function optionalRecord(value, context) {
@@ -15167,21 +16793,21 @@ function stringArray(value, context) {
     if (!Object.hasOwn(value, index)) {
       throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
     }
-    result[index] = requiredText3(value[index], `${context}[${index}]`);
+    result[index] = requiredText4(value[index], `${context}[${index}]`);
   }
   return result;
 }
-function requiredText3(value, context) {
+function requiredText4(value, context) {
   if (typeof value === "string") return value;
-  if (Buffer51.isBuffer(value) || value instanceof Uint8Array) {
-    return Buffer51.from(value).toString("utf8");
+  if (Buffer54.isBuffer(value) || value instanceof Uint8Array) {
+    return Buffer54.from(value).toString("utf8");
   }
   throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
 }
-function optionalText3(value, context) {
-  return value == null ? void 0 : requiredText3(value, context);
+function optionalText4(value, context) {
+  return value == null ? void 0 : requiredText4(value, context);
 }
-function nonNegativeInteger2(value, context) {
+function nonNegativeInteger3(value, context) {
   let parsed;
   try {
     parsed = integer(value);
@@ -15193,26 +16819,26 @@ function nonNegativeInteger2(value, context) {
 }
 function optionalPositiveInteger(value, context) {
   if (value == null) return void 0;
-  const parsed = nonNegativeInteger2(value, context);
+  const parsed = nonNegativeInteger3(value, context);
   if (parsed === 0) throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
   return parsed;
 }
 function optionalVersion(value) {
   if (value == null) return void 0;
   if (typeof value === "number" || typeof value === "bigint") {
-    return nonNegativeInteger2(value, "version");
+    return nonNegativeInteger3(value, "version");
   }
-  return requiredText3(value, "version");
+  return requiredText4(value, "version");
 }
 function backoffKind(value, context) {
-  const kind = requiredText3(value, context).toLowerCase();
+  const kind = requiredText4(value, context).toLowerCase();
   if (kind === "none" || kind === "fixed" || kind === "linear" || kind === "exponential") {
     return kind;
   }
   throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
 }
 function requiredMode(value, context) {
-  const mode = requiredText3(value, context).toLowerCase();
+  const mode = requiredText4(value, context).toLowerCase();
   if (mode === "fifo" || mode === "parallel") return mode;
   throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
 }
@@ -15430,7 +17056,7 @@ var FerricStoreFlowSupportClient = class extends FerricStoreFlowQueryClient {
 };
 
 // src/flow-many-snapshot.ts
-import { Buffer as Buffer53 } from "buffer";
+import { Buffer as Buffer56 } from "buffer";
 var encodedOptionFields = ["error", "payload", "reason", "result"];
 function snapshotCreateItem(item, codec) {
   const snapshot = {
@@ -15470,7 +17096,7 @@ function snapshotFlowManyOptions(options, codec) {
 }
 function snapshotClaimedItem(item) {
   const wire = item[CLAIMED_ITEM_WIRE];
-  const leaseToken = Buffer53.from(wire?.leaseToken ?? item.leaseToken);
+  const leaseToken = Buffer56.from(wire?.leaseToken ?? item.leaseToken);
   const snapshot = {
     ...item,
     fencingToken: wire?.fencingToken ?? item.fencingToken,
@@ -15487,15 +17113,15 @@ function snapshotClaimedItem(item) {
 function snapshotFencedItem(item) {
   return Object.freeze({
     ...item,
-    ...item.leaseToken == null ? {} : { leaseToken: Buffer53.from(item.leaseToken) }
+    ...item.leaseToken == null ? {} : { leaseToken: Buffer56.from(item.leaseToken) }
   });
 }
 function snapshotClaimedItemWire(wire, leaseToken) {
   return Object.freeze({
     fencingToken: wire.fencingToken,
-    id: Buffer53.from(wire.id),
+    id: Buffer56.from(wire.id),
     leaseToken,
-    partitionKey: wire.partitionKey == null ? wire.partitionKey : Buffer53.from(wire.partitionKey)
+    partitionKey: wire.partitionKey == null ? wire.partitionKey : Buffer56.from(wire.partitionKey)
   });
 }
 function snapshotArray(values) {
@@ -15506,7 +17132,7 @@ function snapshotArray(values) {
   return Object.freeze(snapshot);
 }
 function snapshotStateMeta(stateMeta) {
-  return snapshotRecord(stateMeta, (value) => Buffer53.isBuffer(value) ? Buffer53.from(value) : value);
+  return snapshotRecord(stateMeta, (value) => Buffer56.isBuffer(value) ? Buffer56.from(value) : value);
 }
 function snapshotCommandRecord(values) {
   const seen = /* @__PURE__ */ new WeakMap();
@@ -15524,7 +17150,7 @@ function snapshotRecord(values, capture) {
 }
 function snapshotCommandArgument(value, seen) {
   if (typeof value !== "object" || value == null) return value;
-  if (Buffer53.isBuffer(value) || value instanceof Uint8Array) return Buffer53.from(value);
+  if (Buffer56.isBuffer(value) || value instanceof Uint8Array) return Buffer56.from(value);
   const objectValue = value;
   const existing = seen.get(objectValue);
   if (existing != null) return existing;
@@ -16512,7 +18138,7 @@ function nativeOptionsForBootstrap(options, signal) {
 }
 
 // src/flow-query-projection.ts
-import { Buffer as Buffer54 } from "buffer";
+import { Buffer as Buffer57 } from "buffer";
 var MAX_PROJECTION_FIELDS = 32;
 var MAX_DYNAMIC_NAME_BYTES = 64;
 var FIELD_BRAND = /* @__PURE__ */ Symbol("FerricStoreFlowProjectionField");
@@ -16580,20 +18206,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 (Buffer54.byteLength(result, "utf8") > FLOW_QUERY_MAX_BYTES) {
+  if (Buffer57.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;
@@ -16624,7 +18268,7 @@ function quoteName(value, allowPrivate) {
     throw new TypeError("Flow query projection metadata name must be text");
   }
   validateUnicodeScalarText2(value);
-  const size = Buffer54.byteLength(value, "utf8");
+  const size = Buffer57.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`
@@ -16658,7 +18302,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) {
@@ -16726,7 +18370,7 @@ var LeaseRenewalGuard = class {
     if (options.leaseRenewal === false) {
       return;
     }
-    const intervalMs = positiveInteger2(options.leaseRenewIntervalMs, Math.max(1, Math.trunc(leaseMs / 2)));
+    const intervalMs = positiveInteger3(options.leaseRenewIntervalMs, Math.max(1, Math.trunc(leaseMs / 2)));
     this.timer = setLongInterval(() => this.renew(), intervalMs);
     this.timer.unref();
   }
@@ -16798,7 +18442,7 @@ function snapshotLeasedJob(job) {
   return snapshot;
 }
 function workerConcurrency(options) {
-  return positiveInteger2(options.concurrency ?? options.workers, 1);
+  return positiveInteger3(options.concurrency ?? options.workers, 1);
 }
 function workerRefillStrategy(options) {
   return options.refillStrategy === "wave" ? "wave" : "continuous";
@@ -16841,18 +18485,18 @@ function workerErrorPayload(error, options, codec) {
 }
 function workerBatchSize(options, flowManyBatchLimit = DEFAULT_FLOW_MANY_BATCH_LIMIT2) {
   return Math.min(
-    positiveInteger2(options.batchSize, 10),
-    positiveInteger2(flowManyBatchLimit, DEFAULT_FLOW_MANY_BATCH_LIMIT2)
+    positiveInteger3(options.batchSize, 10),
+    positiveInteger3(flowManyBatchLimit, DEFAULT_FLOW_MANY_BATCH_LIMIT2)
   );
 }
 function workerClaimLimit(options, flowManyBatchLimit = DEFAULT_FLOW_MANY_BATCH_LIMIT2) {
   return Math.min(workerBatchSize(options, flowManyBatchLimit), workerConcurrency(options));
 }
 function workerDrainBatches(options) {
-  return positiveInteger2(options.claimDrainBatches, 1);
+  return positiveInteger3(options.claimDrainBatches, 1);
 }
 function workerLeaseMs(options, fallback = 3e4) {
-  return positiveInteger2(options.leaseMs, positiveInteger2(fallback, 3e4));
+  return positiveInteger3(options.leaseMs, positiveInteger3(fallback, 3e4));
 }
 function workerIdleSleepMs(options) {
   return nonNegativeDuration(options.idleSleepMs, 250);
@@ -16864,7 +18508,7 @@ function workerClaimBlockMs(options, useBlocking) {
   if (options.signal == null || !Number.isFinite(options.blockMs) || options.blockMs < 0) {
     return options.blockMs;
   }
-  const abortPollMs = positiveInteger2(options.abortPollMs, 1e3);
+  const abortPollMs = positiveInteger3(options.abortPollMs, 1e3);
   return options.blockMs === 0 ? abortPollMs : Math.min(Math.trunc(options.blockMs), abortPollMs);
 }
 function workerMaxIdleSleepMs(options, idleSleepMs = workerIdleSleepMs(options)) {
@@ -16875,14 +18519,14 @@ function nextWorkerIdleSleepMs(currentIdleSleepMs, maxIdleSleepMs) {
   return Math.min(maxIdleSleepMs, Math.max(1, currentIdleSleepMs * 2));
 }
 async function runContinuousWorkerPool(options) {
-  const concurrency = positiveInteger2(options.concurrency, 1);
-  const maxClaimSize = positiveInteger2(options.maxClaimSize, concurrency);
+  const concurrency = positiveInteger3(options.concurrency, 1);
+  const maxClaimSize = positiveInteger3(options.maxClaimSize, concurrency);
   const initialIdleSleepMs = nonNegativeDuration(options.idleSleepMs, 250);
   const maxIdleSleepMs = Math.max(
     initialIdleSleepMs,
     nonNegativeDuration(options.maxIdleSleepMs, 5e3)
   );
-  const refillDelayMs = nonNegativeInteger3(options.refillDelayMs, 0);
+  const refillDelayMs = nonNegativeInteger4(options.refillDelayMs, 0);
   const active = /* @__PURE__ */ new Set();
   const pending = [];
   let pendingIndex = 0;
@@ -16998,10 +18642,10 @@ function normalizeWorkflowWorkerConfig(options) {
     ...captured
   });
 }
-function positiveInteger2(value, fallback) {
+function positiveInteger3(value, fallback) {
   return value == null || !Number.isFinite(value) ? fallback : Math.max(1, Math.trunc(value));
 }
-function nonNegativeInteger3(value, fallback) {
+function nonNegativeInteger4(value, fallback) {
   return value == null || !Number.isFinite(value) ? fallback : Math.max(0, Math.trunc(value));
 }
 function nonNegativeDuration(value, fallback) {
@@ -17455,7 +19099,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
@@ -17702,7 +19346,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);
@@ -17885,13 +19529,13 @@ var QueueWorker = class {
 
 // src/flow-client-options.ts
 function snapshotFlowClientOptions(options, context) {
-  const own = { ...options };
-  if (typeof own.type !== "string" || own.type.length === 0) {
+  const own2 = { ...options };
+  if (typeof own2.type !== "string" || own2.type.length === 0) {
     throw new TypeError(`${context} type must be an own non-empty string`);
   }
-  const valueConfig = own.valueConfig;
+  const valueConfig = own2.valueConfig;
   return Object.freeze({
-    ...own,
+    ...own2,
     ...valueConfig == null ? {} : { valueConfig: Object.freeze({ ...valueConfig }) }
   });
 }
@@ -18314,19 +19958,19 @@ async function applyFail(client, ctx, outcome, returnRecord) {
 
 // src/workflow-registration.ts
 function createWorkflowStateRegistration(name, handler, options, defaultValueMaxBytes) {
-  const own = { ...options };
-  const claimValues = own.claimValues == null ? void 0 : snapshotOwnStringArray(own.claimValues, "claimValues");
-  const retryPolicy = own.retryPolicy == null ? void 0 : Object.freeze({ ...own.retryPolicy });
+  const own2 = { ...options };
+  const claimValues = own2.claimValues == null ? void 0 : snapshotOwnStringArray(own2.claimValues, "claimValues");
+  const retryPolicy = own2.retryPolicy == null ? void 0 : Object.freeze({ ...own2.retryPolicy });
   return Object.freeze({
-    claimPayload: own.claimPayload ?? true,
-    claimRecord: own.claimRecord ?? true,
-    exceptionPolicy: normalizeExceptionPolicy(own.exceptionPolicy),
+    claimPayload: own2.claimPayload ?? true,
+    claimRecord: own2.claimRecord ?? true,
+    exceptionPolicy: normalizeExceptionPolicy(own2.exceptionPolicy),
     handler,
-    leaseMs: own.leaseMs ?? 3e4,
-    ...own.mode == null ? {} : { mode: normalizeStateMode(own.mode) },
+    leaseMs: own2.leaseMs ?? 3e4,
+    ...own2.mode == null ? {} : { mode: normalizeStateMode(own2.mode) },
     name,
-    returnRecord: own.returnRecord ?? false,
-    valueMaxBytes: own.valueMaxBytes ?? defaultValueMaxBytes,
+    returnRecord: own2.returnRecord ?? false,
+    valueMaxBytes: own2.valueMaxBytes ?? defaultValueMaxBytes,
     ...claimValues == null ? {} : { claimValues },
     ...retryPolicy == null ? {} : { retryPolicy }
   });
@@ -18615,7 +20259,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;
@@ -18630,8 +20274,8 @@ var WorkflowWorker = class {
 };
 
 // src/version.ts
-var FERRICSTORE_SDK_VERSION = "0.5.1";
-var FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.0";
+var FERRICSTORE_SDK_VERSION = "0.11.4";
+var FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.4";
 var FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
 export {
   BitmapStore,
@@ -18689,7 +20333,7 @@ export {
   WorkflowWorker,
   classifyServerError,
   complete,
-  fail,
+  fail2 as fail,
   isOutcome,
   isReconnectableClosedConnectionError,
   mapException,