@ferricstore/ferricstore 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -45,6 +45,8 @@ __export(index_exports, {
   FlowAlreadyExistsError: () => FlowAlreadyExistsError,
   FlowBatchError: () => FlowBatchError,
   FlowNotFoundError: () => FlowNotFoundError,
+  FlowProjection: () => FlowProjection,
+  FlowQueryError: () => FlowQueryError,
   FlowWrongStateError: () => FlowWrongStateError,
   GeoStore: () => GeoStore,
   HashStore: () => HashStore,
@@ -87,6 +89,7 @@ __export(index_exports, {
   isOutcome: () => isOutcome,
   isReconnectableClosedConnectionError: () => isReconnectableClosedConnectionError,
   mapException: () => mapException,
+  projectFlowQuery: () => projectFlowQuery,
   retry: () => retry,
   transition: () => transition
 });
@@ -104,7 +107,7 @@ function assertSafeVariadicDispatch(argumentCount, arrayCapability) {
 // src/native-adapter.ts
 var import_node_net3 = require("net");
 var import_node_tls3 = require("tls");
-var import_node_buffer26 = require("buffer");
+var import_node_buffer31 = require("buffer");
 
 // src/errors.ts
 var FerricStoreError = class extends Error {
@@ -1276,10 +1279,151 @@ var NativeHeartbeat = class {
 };
 
 // src/protocol.ts
-var import_node_buffer22 = require("buffer");
+var import_node_buffer27 = require("buffer");
 
-// src/command-grammar.ts
+// src/flow-query-request.ts
 var import_node_buffer3 = require("buffer");
+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 MIN_I64 = -(1n << 63n);
+var MAX_I64 = (1n << 63n) - 1n;
+var INDEX_ID = /^[A-Za-z0-9_.:-]{1,64}$/u;
+function flowQueryArgs(query, params = {}) {
+  validateFlowQueryText(query);
+  const entries = flowQueryParameterEntries(params);
+  const args = ["FLOW.QUERY", FLOW_QUERY_LANGUAGE_VERSION, query];
+  for (const [name, value] of entries) args.push(name, value);
+  return args;
+}
+function flowQueryPayload(args) {
+  if (args.length < 2) throw new TypeError("FLOW.QUERY requires version and query");
+  if ((args.length - 2) % 2 !== 0) {
+    throw new TypeError("FLOW.QUERY parameters must be name/value pairs");
+  }
+  const version = commandText(args[0], "FLOW.QUERY version");
+  if (version !== FLOW_QUERY_LANGUAGE_VERSION) {
+    throw new TypeError(`FLOW.QUERY requires version ${FLOW_QUERY_LANGUAGE_VERSION}`);
+  }
+  const query = commandText(args[1], "FLOW.QUERY query");
+  validateFlowQueryText(query);
+  const parameterCount = (args.length - 2) / 2;
+  if (parameterCount > FLOW_QUERY_MAX_PARAMETERS) {
+    throw new TypeError(`FLOW.QUERY accepts at most ${FLOW_QUERY_MAX_PARAMETERS} named parameters`);
+  }
+  const params = /* @__PURE__ */ Object.create(null);
+  for (let index = 2; index < args.length; index += 2) {
+    const name = commandText(args[index], "FLOW.QUERY parameter name");
+    validateFlowQueryParameterName(name);
+    if (Object.hasOwn(params, name)) {
+      throw new TypeError(`FLOW.QUERY parameter ${JSON.stringify(name)} is duplicated`);
+    }
+    params[name] = normalizeFlowQueryParameter(args[index + 1], name);
+  }
+  return {
+    version,
+    query,
+    ...parameterCount === 0 ? {} : { params }
+  };
+}
+function validateFlowQueryText(query) {
+  if (typeof query !== "string") throw new TypeError("FLOW.QUERY query must be text");
+  if (query.trim().length === 0) throw new TypeError("FLOW.QUERY query must not be empty");
+  validateUnicodeScalarText(query, "FLOW.QUERY query");
+  if (import_node_buffer3.Buffer.byteLength(query, "utf8") > FLOW_QUERY_MAX_BYTES) {
+    throw new TypeError(`FLOW.QUERY query exceeds ${FLOW_QUERY_MAX_BYTES} bytes`);
+  }
+}
+function validateFlowQueryIndexId(indexId) {
+  if (typeof indexId !== "string" || !INDEX_ID.test(indexId)) {
+    throw new TypeError(
+      "query index id must be 1..64 ASCII letters, digits, '_', '-', ':', or '.'"
+    );
+  }
+}
+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] ?? ""));
+}
+function flowQueryParameterEntries(params) {
+  if (typeof params !== "object" || params == null || Array.isArray(params)) {
+    throw new TypeError("FLOW.QUERY params must be a plain object");
+  }
+  const prototype = Object.getPrototypeOf(params);
+  if (prototype !== null && prototype !== Object.prototype) {
+    throw new TypeError("FLOW.QUERY params must be a plain object");
+  }
+  const keys = Reflect.ownKeys(params);
+  if (keys.some((key) => typeof key !== "string")) {
+    throw new TypeError("FLOW.QUERY parameter names must be strings");
+  }
+  if (keys.length > FLOW_QUERY_MAX_PARAMETERS) {
+    throw new TypeError(`FLOW.QUERY accepts at most ${FLOW_QUERY_MAX_PARAMETERS} named parameters`);
+  }
+  const names = keys.sort();
+  return names.map((name) => {
+    validateFlowQueryParameterName(name);
+    return [name, normalizeFlowQueryParameter(params[name], name)];
+  });
+}
+function validateFlowQueryParameterName(name) {
+  validateUnicodeScalarText(name, "FLOW.QUERY parameter name");
+  const size = import_node_buffer3.Buffer.byteLength(name, "utf8");
+  if (size === 0 || size > FLOW_QUERY_MAX_PARAMETER_NAME_BYTES) {
+    throw new TypeError(
+      `FLOW.QUERY parameter names must be 1..${FLOW_QUERY_MAX_PARAMETER_NAME_BYTES} bytes`
+    );
+  }
+}
+function normalizeFlowQueryParameter(value, name) {
+  if (typeof value === "string") {
+    validateUnicodeScalarText(value, `FLOW.QUERY parameter ${JSON.stringify(name)}`);
+    return value;
+  }
+  if (import_node_buffer3.Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return import_node_buffer3.Buffer.from(value);
+  if (typeof value === "boolean") return value;
+  if (typeof value === "bigint" && value >= MIN_I64 && value <= MAX_I64) return value;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    if (!Number.isInteger(value) || Number.isSafeInteger(value)) return value;
+  }
+  throw new TypeError(
+    `FLOW.QUERY parameter ${JSON.stringify(name)} must be text, bytes, boolean, a finite float, or a signed 64-bit integer`
+  );
+}
+function commandText(value, context) {
+  if (typeof value === "string") {
+    validateUnicodeScalarText(value, context);
+    return value;
+  }
+  if (import_node_buffer3.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(value);
+    } catch (error) {
+      throw new TypeError(`${context} must be valid UTF-8`, { cause: error });
+    }
+  }
+  throw new TypeError(`${context} must be text`);
+}
+function validateUnicodeScalarText(value, context) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 55296 && code <= 56319) {
+      const low = value.charCodeAt(index + 1);
+      if (!(low >= 56320 && low <= 57343)) {
+        throw new TypeError(`${context} must be valid UTF-8`);
+      }
+      index += 1;
+    } else if (code >= 56320 && code <= 57343) {
+      throw new TypeError(`${context} must be valid UTF-8`);
+    }
+  }
+}
+
+// src/command-grammar.ts
+var import_node_buffer4 = require("buffer");
 
 // src/command-metadata-flow.ts
 var flowStateIdCommands = /* @__PURE__ */ new Set([
@@ -1670,20 +1814,15 @@ var typeScopedFlowCommands = /* @__PURE__ */ new Set([
   "FLOW.ATTRIBUTE_VALUES",
   "FLOW.ATTRIBUTES",
   "FLOW.BUDGET.LIST",
-  "FLOW.FAILURES",
   "FLOW.GOVERNANCE.OVERVIEW",
   "FLOW.INFO",
   "FLOW.LIMIT.LIST",
-  "FLOW.LIST",
   "FLOW.POLICY.GET",
   "FLOW.POLICY.SET",
   "FLOW.RETENTION_CLEANUP",
   "FLOW.SCHEDULE.FIRE_DUE",
   "FLOW.SCHEDULE.LIST",
-  "FLOW.SEARCH",
-  "FLOW.STATS",
-  "FLOW.STUCK",
-  "FLOW.TERMINALS"
+  "FLOW.STATS"
 ]);
 var flowScheduleCommands = /* @__PURE__ */ new Set([
   "FLOW.SCHEDULE.CREATE",
@@ -1726,8 +1865,8 @@ var secondKeySubcommands = /* @__PURE__ */ new Map([
 ]);
 function commandToken(value) {
   if (typeof value === "string") return value.toUpperCase();
-  if (import_node_buffer3.Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return import_node_buffer3.Buffer.from(value).toString("utf8").toUpperCase();
+  if (import_node_buffer4.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return import_node_buffer4.Buffer.from(value).toString("utf8").toUpperCase();
   }
   return void 0;
 }
@@ -1830,7 +1969,7 @@ function safeIntegerArgument(value) {
   if (typeof value === "bigint") {
     return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : void 0;
   }
-  const source = typeof value === "string" ? value : import_node_buffer3.Buffer.isBuffer(value) || value instanceof Uint8Array ? import_node_buffer3.Buffer.from(value).toString("utf8") : void 0;
+  const source = typeof value === "string" ? value : import_node_buffer4.Buffer.isBuffer(value) || value instanceof Uint8Array ? import_node_buffer4.Buffer.from(value).toString("utf8") : void 0;
   if (source == null || !/^[+-]?\d+$/u.test(source)) return void 0;
   const parsed = BigInt(source);
   return parsed >= BigInt(Number.MIN_SAFE_INTEGER) && parsed <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(parsed) : void 0;
@@ -1883,10 +2022,10 @@ function hasOwnCommandArgument(args, index, end, section) {
 }
 
 // src/protocol-core.ts
-var import_node_buffer7 = require("buffer");
+var import_node_buffer8 = require("buffer");
 
 // src/protocol-constants.ts
-var import_node_buffer4 = require("buffer");
+var import_node_buffer5 = require("buffer");
 
 // src/native-protocol-manifest.json
 var native_protocol_manifest_default = {
@@ -1981,7 +2120,6 @@ var COMMAND_OPCODES = {
   "FLOW.VALUE.PUT": 523,
   "FLOW.VALUE.MGET": 524,
   "FLOW.SIGNAL": 525,
-  "FLOW.LIST": 526,
   "FLOW.CREATE_MANY": 527,
   "FLOW.COMPLETE_MANY": 528,
   "FLOW.TRANSITION_MANY": 529,
@@ -1990,13 +2128,7 @@ var COMMAND_OPCODES = {
   "FLOW.CANCEL_MANY": 532,
   "FLOW.RECLAIM": 533,
   "FLOW.REWIND": 534,
-  "FLOW.TERMINALS": 535,
-  "FLOW.FAILURES": 536,
-  "FLOW.BY_PARENT": 537,
-  "FLOW.BY_ROOT": 538,
-  "FLOW.BY_CORRELATION": 539,
   "FLOW.INFO": 540,
-  "FLOW.STUCK": 541,
   "FLOW.POLICY.SET": 542,
   "FLOW.POLICY.GET": 543,
   "FLOW.SPAWN_CHILDREN": 544,
@@ -2015,7 +2147,7 @@ var COMMAND_OPCODES = {
   "FLOW.STATS": 557,
   "FLOW.ATTRIBUTES": 558,
   "FLOW.ATTRIBUTE_VALUES": 559,
-  "FLOW.SEARCH": 560,
+  "FLOW.QUERY": 561,
   "FLOW.EFFECT.RESERVE": 576,
   "FLOW.EFFECT.CONFIRM": 577,
   "FLOW.EFFECT.FAIL": 578,
@@ -2104,7 +2236,7 @@ var OPCODES = {
   flowStepContinue: COMMAND_OPCODES["FLOW.STEP_CONTINUE"],
   flowStartAndClaim: COMMAND_OPCODES["FLOW.START_AND_CLAIM"],
   flowRunStepsMany: COMMAND_OPCODES["FLOW.RUN_STEPS_MANY"],
-  flowSearch: COMMAND_OPCODES["FLOW.SEARCH"]
+  flowQuery: COMMAND_OPCODES["FLOW.QUERY"]
 };
 var COMPACT_FLOW_CLAIM_JOBS = 128;
 var COMPACT_OK_LIST = 129;
@@ -2131,11 +2263,12 @@ var COMPACT_FLOW_TRANSITION_MANY_REQUEST = 155;
 var COMPACT_FLOW_TRANSITION_MANY_OK_REQUEST = 156;
 var COMPACT_FLOW_VALUE_MGET_REQUEST = 157;
 var COMPACT_FLOW_CREATE_MANY_MIXED_REQUEST = 158;
-var COMPACT_FLOW_LIST_REQUEST = 159;
+var COMPACT_FLOW_QUERY_RESULT = 160;
 var COMPACT_PIPELINE_DECODED = /* @__PURE__ */ Symbol("ferricstore.compactPipelineDecoded");
 var NULL_U32 = 4294967295;
-var MIN_I64 = -9223372036854775808n;
-var MAX_I64 = 9223372036854775807n;
+var MIN_I642 = -9223372036854775808n;
+var MAX_I642 = 9223372036854775807n;
+var MAX_U64 = 18446744073709551615n;
 var MAX_SAFE_INTEGER_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
 var MIN_SAFE_INTEGER_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
 var FLOW_RECORD_FIELD_KEYS = [
@@ -2184,16 +2317,16 @@ var FLOW_RECORD_FIELD_KEYS = [
 ];
 
 // src/protocol-text.ts
-var import_node_buffer5 = require("buffer");
+var import_node_buffer6 = require("buffer");
 function toBuffer(value) {
-  if (import_node_buffer5.Buffer.isBuffer(value)) return value;
-  if (value instanceof Uint8Array) return import_node_buffer5.Buffer.from(value);
-  if (typeof value === "string") return import_node_buffer5.Buffer.from(value);
+  if (import_node_buffer6.Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return import_node_buffer6.Buffer.from(value);
+  if (typeof value === "string") return import_node_buffer6.Buffer.from(value);
   if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
-    return import_node_buffer5.Buffer.from(String(value));
+    return import_node_buffer6.Buffer.from(String(value));
   }
-  if (typeof value === "symbol") return import_node_buffer5.Buffer.from(value.description ?? value.toString());
-  if (value == null) return import_node_buffer5.Buffer.alloc(0);
+  if (typeof value === "symbol") return import_node_buffer6.Buffer.from(value.description ?? value.toString());
+  if (value == null) return import_node_buffer6.Buffer.alloc(0);
   throw new FerricStoreError(`unsupported binary command argument type: ${typeof value}`);
 }
 function asText(value) {
@@ -2201,14 +2334,14 @@ function asText(value) {
 }
 function optionalText(value) {
   if (value == null || value === "") return void 0;
-  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || import_node_buffer5.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || import_node_buffer6.Buffer.isBuffer(value) || value instanceof Uint8Array) {
     return asText(value);
   }
   return void 0;
 }
 function commandTokenIs(value, expected) {
   if (typeof value === "string") return value.toUpperCase() === expected;
-  if (import_node_buffer5.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+  if (import_node_buffer6.Buffer.isBuffer(value) || value instanceof Uint8Array) {
     return asText(value).toUpperCase() === expected;
   }
   return false;
@@ -2222,7 +2355,7 @@ function commandNameIs(value, expected) {
 }
 
 // src/request-context.ts
-var import_node_buffer6 = require("buffer");
+var import_node_buffer7 = require("buffer");
 var requestContextCommands = /* @__PURE__ */ new Set([
   "INVOCATION.CREATE",
   "INVOCATION.DEFINITION.GET",
@@ -2277,9 +2410,9 @@ function requestContextCommandToken(value) {
     const upper = value.toUpperCase();
     return isRequestContextCommand(upper) ? upper : void 0;
   }
-  if (import_node_buffer6.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+  if (import_node_buffer7.Buffer.isBuffer(value) || value instanceof Uint8Array) {
     if (value[0] !== 73 && value[0] !== 105) return void 0;
-    const command = import_node_buffer6.Buffer.from(value).toString("utf8").toUpperCase();
+    const command = import_node_buffer7.Buffer.from(value).toString("utf8").toUpperCase();
     return isRequestContextCommand(command) ? command : void 0;
   }
   return void 0;
@@ -2310,12 +2443,12 @@ function requestContextText(context, fieldName) {
   return value;
 }
 function isPlainObject(value) {
-  return typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer6.Buffer.isBuffer(value) && !(value instanceof Uint8Array);
+  return typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer7.Buffer.isBuffer(value) && !(value instanceof Uint8Array);
 }
 function commandToken2(value) {
   if (typeof value === "string") return value.toUpperCase();
-  if (import_node_buffer6.Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return import_node_buffer6.Buffer.from(value).toString("utf8").toUpperCase();
+  if (import_node_buffer7.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return import_node_buffer7.Buffer.from(value).toString("utf8").toUpperCase();
   }
   return "";
 }
@@ -2405,17 +2538,17 @@ function requestFrameTooLarge(maxBytes) {
   );
 }
 function binaryValueByteLength(value) {
-  if (import_node_buffer7.Buffer.isBuffer(value) || value instanceof Uint8Array) return value.byteLength;
-  if (typeof value === "string") return import_node_buffer7.Buffer.byteLength(value);
+  if (import_node_buffer8.Buffer.isBuffer(value) || value instanceof Uint8Array) return value.byteLength;
+  if (typeof value === "string") return import_node_buffer8.Buffer.byteLength(value);
   if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
-    return import_node_buffer7.Buffer.byteLength(String(value));
+    return import_node_buffer8.Buffer.byteLength(String(value));
   }
-  if (typeof value === "symbol") return import_node_buffer7.Buffer.byteLength(value.description ?? value.toString());
+  if (typeof value === "symbol") return import_node_buffer8.Buffer.byteLength(value.description ?? value.toString());
   if (value == null) return 0;
   return toBuffer(value).byteLength;
 }
 function writeCustomPayload(output, offset, value, knownByteLength) {
-  if (import_node_buffer7.Buffer.isBuffer(value)) {
+  if (import_node_buffer8.Buffer.isBuffer(value)) {
     value.copy(output, offset);
     return;
   }
@@ -2434,7 +2567,7 @@ function writeCustomPayload(output, offset, value, knownByteLength) {
   } else {
     throw new FerricStoreError(`unsupported binary command argument type: ${typeof value}`);
   }
-  output.write(text3, offset, knownByteLength ?? import_node_buffer7.Buffer.byteLength(text3), "utf8");
+  output.write(text3, offset, knownByteLength ?? import_node_buffer8.Buffer.byteLength(text3), "utf8");
 }
 function compactBinaryEncodedLength(value) {
   return 4 + compactBinaryByteLength(value);
@@ -2447,10 +2580,10 @@ function compactBinaryByteLength(value) {
   return byteLength;
 }
 function isCompactBinaryArgument(value) {
-  return typeof value === "string" || import_node_buffer7.Buffer.isBuffer(value) || value instanceof Uint8Array;
+  return typeof value === "string" || import_node_buffer8.Buffer.isBuffer(value) || value instanceof Uint8Array;
 }
 function isCompactBinaryScalar(value) {
-  return value == null || typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || typeof value === "symbol" || import_node_buffer7.Buffer.isBuffer(value) || value instanceof Uint8Array;
+  return value == null || typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || typeof value === "symbol" || import_node_buffer8.Buffer.isBuffer(value) || value instanceof Uint8Array;
 }
 function compactOptionalBinaryEncodedLength(value) {
   return value == null ? 4 : compactBinaryEncodedLength(value);
@@ -2516,7 +2649,7 @@ function integerArg(value) {
     throw new FerricStoreError("integer command argument must be an integer");
   }
   const integer2 = BigInt(source);
-  if (integer2 < MIN_I64 || integer2 > MAX_I64) {
+  if (integer2 < MIN_I642 || integer2 > MAX_I642) {
     throw new FerricStoreError("integer command argument exceeds the signed 64-bit range");
   }
   return integer2 >= MIN_SAFE_INTEGER_BIGINT && integer2 <= MAX_SAFE_INTEGER_BIGINT ? Number(integer2) : integer2;
@@ -2547,7 +2680,7 @@ function independentMode(value) {
   return 0;
 }
 function optionalI64(value) {
-  return typeof value === "number" ? BigInt(value) : MIN_I64;
+  return typeof value === "number" ? BigInt(value) : MIN_I642;
 }
 function compactClaimReturnMode(value) {
   const mode = value == null ? "" : asText(value).toUpperCase();
@@ -2581,18 +2714,18 @@ function setOwnValue2(target, key, value) {
 }
 
 // src/protocol-flow-options.ts
-var import_node_buffer8 = require("buffer");
+var import_node_buffer9 = require("buffer");
 
 // src/protocol-flow-option-value.ts
-function setFlowOptionValue(payload, field2, value, repeat) {
-  if (!repeat || !Object.hasOwn(payload, field2)) {
-    setOwnValue2(payload, field2, value);
+function setFlowOptionValue(payload, field3, value, repeat) {
+  if (!repeat || !Object.hasOwn(payload, field3)) {
+    setOwnValue2(payload, field3, value);
     return;
   }
-  const previous = payload[field2];
+  const previous = payload[field3];
   setOwnValue2(
     payload,
-    field2,
+    field3,
     Array.isArray(previous) ? [...previous, value] : [previous, value]
   );
 }
@@ -2635,44 +2768,30 @@ function optionMap(args) {
       index += 3;
       continue;
     }
-    const field2 = OPTION_FIELDS[token] ?? token.toLowerCase();
+    const field3 = OPTION_FIELDS[token] ?? token.toLowerCase();
     if (!hasOwnCommandArgument(args, index + 1, args.length, "Flow options")) {
       throw new FerricStoreError(`${token} requires a value`);
     }
     const value = args[index + 1];
-    if (BOOL_OPTION_FIELDS.has(field2) && !isBoolToken(value)) {
+    if (BOOL_OPTION_FIELDS.has(field3) && !isBoolToken(value)) {
       return void 0;
     }
-    setOwnValue2(payload, field2, BOOL_OPTION_FIELDS.has(field2) ? boolArg(value) : value);
+    setOwnValue2(payload, field3, BOOL_OPTION_FIELDS.has(field3) ? boolArg(value) : value);
     index += 2;
   }
   return payload;
 }
-function ensureObjectField(payload, field2) {
-  const value = payload[field2];
+function ensureObjectField(payload, field3) {
+  const value = payload[field3];
   if (isPlainObject2(value)) {
     return value;
   }
   const next = {};
-  setOwnValue2(payload, field2, next);
+  setOwnValue2(payload, field3, next);
   return next;
 }
-function normalizeFlowSearchStateMeta(payload) {
-  const stateMeta = payload.state_meta;
-  if (!isPlainObject2(stateMeta) || Object.keys(stateMeta).length === 0) {
-    return;
-  }
-  if (Object.values(stateMeta).every(isPlainObject2)) {
-    return;
-  }
-  const state = payload.state;
-  if (state == null) {
-    throw new FerricStoreError("FLOW.SEARCH STATE_META filters require STATE or nested state metadata");
-  }
-  payload.state_meta = { [asText(state)]: stateMeta };
-}
 function isPlainObject2(value) {
-  return typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer8.Buffer.isBuffer(value) && !(value instanceof Uint8Array);
+  return typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer9.Buffer.isBuffer(value) && !(value instanceof Uint8Array);
 }
 function parseFlowOptions(args, start, end, config) {
   const payload = {};
@@ -2766,9 +2885,9 @@ function parseFlowOptions(args, start, end, config) {
       case "TRANSITION_TO":
       case "TO_EVENT":
       case "EXPECT_STATE": {
-        const field2 = token === "IDEMPOTENCY" ? "idempotency_key" : token.toLowerCase();
+        const field3 = token === "IDEMPOTENCY" ? "idempotency_key" : token.toLowerCase();
         if (!hasOwnCommandArgument(args, index + 1, end, "Flow options")) return void 0;
-        setFlowOptionValue(payload, field2, args[index + 1], token === "IF_STATE");
+        setFlowOptionValue(payload, field3, args[index + 1], token === "IF_STATE");
         index += 2;
         break;
       }
@@ -2776,8 +2895,8 @@ function parseFlowOptions(args, start, end, config) {
       case "RESULT":
       case "ERROR":
       case "REASON": {
-        const field2 = token === "LEASE_TOKEN" ? "lease_token" : token.toLowerCase();
-        if (!putScalar(payload, field2, args, index + 1, end)) return void 0;
+        const field3 = token === "LEASE_TOKEN" ? "lease_token" : token.toLowerCase();
+        if (!putScalar(payload, field3, args, index + 1, end)) return void 0;
         index += 2;
         break;
       }
@@ -2799,8 +2918,8 @@ function parseFlowOptions(args, start, end, config) {
       case "VALUE_REF":
       case "STATE_META": {
         if (!hasOwnCommandArgument(args, index + 1, end, "Flow options") || !hasOwnCommandArgument(args, index + 2, end, "Flow options")) return void 0;
-        const field2 = token === "ATTRIBUTE" ? "attributes" : token === "ATTRIBUTE_MERGE" ? "attributes_merge" : token === "VALUE_REF" ? "value_refs" : "state_meta";
-        const values = ensureObjectField(payload, field2);
+        const field3 = token === "ATTRIBUTE" ? "attributes" : token === "ATTRIBUTE_MERGE" ? "attributes_merge" : token === "VALUE_REF" ? "value_refs" : "state_meta";
+        const values = ensureObjectField(payload, field3);
         setOwnValue2(values, asText(args[index + 1]), args[index + 2]);
         index += 3;
         break;
@@ -2809,8 +2928,8 @@ function parseFlowOptions(args, start, end, config) {
       case "OVERRIDE_VALUE":
       case "ATTRIBUTE_DELETE": {
         if (!hasOwnCommandArgument(args, index + 1, end, "Flow options")) return void 0;
-        const field2 = token === "DROP_VALUE" ? "drop_values" : token === "OVERRIDE_VALUE" ? "override_values" : "attributes_delete";
-        const values = ensureArrayField(payload, field2);
+        const field3 = token === "DROP_VALUE" ? "drop_values" : token === "OVERRIDE_VALUE" ? "override_values" : "attributes_delete";
+        const values = ensureArrayField(payload, field3);
         values.push(args[index + 1]);
         index += 2;
         break;
@@ -2927,13 +3046,13 @@ function putScalar(payload, key, args, index, end) {
   setOwnValue2(payload, key, args[index]);
   return true;
 }
-function ensureArrayField(payload, field2) {
-  const value = payload[field2];
+function ensureArrayField(payload, field3) {
+  const value = payload[field3];
   if (Array.isArray(value)) {
     return value;
   }
   const next = [];
-  setOwnValue2(payload, field2, next);
+  setOwnValue2(payload, field3, next);
   return next;
 }
 function putNumber(payload, key, args, index, end) {
@@ -3154,8 +3273,8 @@ function flowHistoryPayload(args) {
       case "CONSISTENT_PROJECTION":
       case "VALUES": {
         if (!isBoolToken(value)) return void 0;
-        const field2 = token === "REV" ? "rev" : token === "INCLUDE_COLD" ? "include_cold" : token === "CONSISTENT_PROJECTION" ? "consistent_projection" : "values";
-        payload[field2] = boolArg(value);
+        const field3 = token === "REV" ? "rev" : token === "INCLUDE_COLD" ? "include_cold" : token === "CONSISTENT_PROJECTION" ? "consistent_projection" : "values";
+        payload[field3] = boolArg(value);
         break;
       }
       default:
@@ -3167,9 +3286,9 @@ function flowHistoryPayload(args) {
 function flowAdminPayload(opcode, args, leadingFields = []) {
   if (args.length < leadingFields.length) return void 0;
   const payload = {};
-  for (const [index, field2] of leadingFields.entries()) {
+  for (const [index, field3] of leadingFields.entries()) {
     hasOwnCommandArgument(args, index, args.length, "Flow admin arguments");
-    setOwnValue2(payload, field2, args[index]);
+    setOwnValue2(payload, field3, args[index]);
   }
   for (let index = leadingFields.length; index < args.length; ) {
     hasOwnCommandArgument(args, index, args.length, "Flow admin arguments");
@@ -3177,15 +3296,15 @@ function flowAdminPayload(opcode, args, leadingFields = []) {
     if (token == null) return void 0;
     if (["ATTRIBUTE", "ATTRIBUTE_MERGE", "STATE_META", "VALUE", "VALUE_REF"].includes(token)) {
       if (!hasOwnCommandArgument(args, index + 1, args.length, "Flow admin arguments") || !hasOwnCommandArgument(args, index + 2, args.length, "Flow admin arguments")) return void 0;
-      const field3 = token === "ATTRIBUTE" ? "attributes" : token === "ATTRIBUTE_MERGE" ? "attributes_merge" : token === "STATE_META" ? "state_meta" : token === "VALUE" ? "values" : "value_refs";
-      setOwnValue2(ensureObjectField(payload, field3), asText(args[index + 1]), args[index + 2]);
+      const field4 = token === "ATTRIBUTE" ? "attributes" : token === "ATTRIBUTE_MERGE" ? "attributes_merge" : token === "STATE_META" ? "state_meta" : token === "VALUE" ? "values" : "value_refs";
+      setOwnValue2(ensureObjectField(payload, field4), asText(args[index + 1]), args[index + 2]);
       index += 3;
       continue;
     }
     if (token === "ATTRIBUTE_DELETE" || token === "DROP_VALUE" || token === "OVERRIDE_VALUE") {
       if (!hasOwnCommandArgument(args, index + 1, args.length, "Flow admin arguments")) return void 0;
-      const field3 = token === "ATTRIBUTE_DELETE" ? "attributes_delete" : token === "DROP_VALUE" ? "drop_values" : "override_values";
-      ensureArrayField(payload, field3).push(args[index + 1]);
+      const field4 = token === "ATTRIBUTE_DELETE" ? "attributes_delete" : token === "DROP_VALUE" ? "drop_values" : "override_values";
+      ensureArrayField(payload, field4).push(args[index + 1]);
       index += 2;
       continue;
     }
@@ -3204,13 +3323,13 @@ function flowAdminPayload(opcode, args, leadingFields = []) {
       index += 2 + count;
       continue;
     }
-    const field2 = FLOW_ADMIN_FIELDS[token];
-    if (field2 == null || !hasOwnCommandArgument(args, index + 1, args.length, "Flow admin arguments")) {
+    const field3 = FLOW_ADMIN_FIELDS[token];
+    if (field3 == null || !hasOwnCommandArgument(args, index + 1, args.length, "Flow admin arguments")) {
       return void 0;
     }
     const rawValue = args[index + 1];
-    if (FLOW_ADMIN_BOOLEAN_FIELDS.has(field2) && !isBoolToken(rawValue)) return void 0;
-    setOwnValue2(payload, field2, FLOW_ADMIN_BOOLEAN_FIELDS.has(field2) ? boolArg(rawValue) : rawValue);
+    if (FLOW_ADMIN_BOOLEAN_FIELDS.has(field3) && !isBoolToken(rawValue)) return void 0;
+    setOwnValue2(payload, field3, FLOW_ADMIN_BOOLEAN_FIELDS.has(field3) ? boolArg(rawValue) : rawValue);
     index += 2;
   }
   const serverBlockMs = opcode === COMMAND_OPCODES["FLOW.SCHEDULE.FIRE_DUE"] && payload.block_ms != null ? blockDurationMs(payload.block_ms, 1) : void 0;
@@ -3218,7 +3337,7 @@ function flowAdminPayload(opcode, args, leadingFields = []) {
 }
 
 // src/protocol-flow-compact.ts
-var import_node_buffer10 = require("buffer");
+var import_node_buffer11 = require("buffer");
 
 // src/protocol-flow-compact-common.ts
 function compactManyRequestTag(value, regularTag, okOnSuccessTag) {
@@ -3327,7 +3446,7 @@ function parseNamedCountMap(values, start) {
 }
 
 // src/protocol-flow-compact-transition.ts
-var import_node_buffer9 = require("buffer");
+var import_node_buffer10 = require("buffer");
 function compactFlowTransitionManyPayload(partition, fromState, toState, rawItems, mixed, options, maxBodyBytes) {
   if ("payload" in options || "priority" in options || "state_meta" in options || "values" in options || "value_refs" in options || "drop_values" in options || "override_values" in options || "attributes_merge" in options || "attributes_delete" in options || typeof options.now_ms !== "number" || !Number.isSafeInteger(options.now_ms) || options.now_ms < 0) {
     return void 0;
@@ -3379,7 +3498,7 @@ function compactFlowTransitionManyPayload(partition, fromState, toState, rawItem
     total += 4 + idLength + 4 + itemPartitionLength + 8 + 4 + leaseLength;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer9.Buffer.allocUnsafe(total);
+  const out = import_node_buffer10.Buffer.allocUnsafe(total);
   let offset = 0;
   out.writeUInt8(tag, offset);
   offset += 1;
@@ -3437,7 +3556,7 @@ function compactFlowCreateManyPayload(partition, rawItems, mixed, auto, options,
   }
   assertCompactPayloadFits(total, maxBodyBytes);
   const tag = mixed ? COMPACT_FLOW_CREATE_MANY_MIXED_REQUEST : auto ? COMPACT_FLOW_CREATE_MANY_REQUEST : COMPACT_FLOW_CREATE_MANY_PARTITION_REQUEST;
-  const out = import_node_buffer10.Buffer.allocUnsafe(total);
+  const out = import_node_buffer11.Buffer.allocUnsafe(total);
   let offset = 0;
   out.writeUInt8(tag, offset++);
   offset = writeBinary(out, offset, toBuffer(options.type));
@@ -3482,7 +3601,7 @@ function compactFlowClaimDuePayload(type, options, maxBodyBytes) {
     total += 1;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer10.Buffer.allocUnsafe(total);
+  const out = import_node_buffer11.Buffer.allocUnsafe(total);
   let offset = 0;
   out.writeUInt8(COMPACT_FLOW_CLAIM_DUE_REQUEST, offset++);
   offset = writeBinary(out, offset, toBuffer(type));
@@ -3536,7 +3655,7 @@ function compactFlowCompleteManyPayload(opcode, partition, rawItems, mixed, auto
     total += compactBinaryEncodedLength(rawItems[rawIndex]) + compactOptionalBinaryEncodedLength(mixed ? rawItems[rawIndex + 1] : null) + compactBinaryEncodedLength(rawItems[rawIndex + width - 2]) + 8;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer10.Buffer.allocUnsafe(total);
+  const out = import_node_buffer11.Buffer.allocUnsafe(total);
   let offset = 0;
   out.writeUInt8(
     returnMode === "OK_ON_SUCCESS" ? COMPACT_FLOW_COMPLETE_MANY_OK_REQUEST : COMPACT_FLOW_COMPLETE_MANY_REQUEST,
@@ -3583,7 +3702,7 @@ function compactFlowRetryManyPayload(partition, rawItems, mixed, auto, options,
     total += compactBinaryEncodedLength(rawItems[rawIndex]) + compactOptionalBinaryEncodedLength(mixed ? rawItems[rawIndex + 1] : null) + compactBinaryEncodedLength(rawItems[rawIndex + width - 2]) + 8;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer10.Buffer.allocUnsafe(total);
+  const out = import_node_buffer11.Buffer.allocUnsafe(total);
   let offset = 0;
   out.writeUInt8(
     returnMode === "OK_ON_SUCCESS" ? COMPACT_FLOW_RETRY_MANY_OK_REQUEST : COMPACT_FLOW_RETRY_MANY_REQUEST,
@@ -3671,7 +3790,7 @@ function compactFlowCancelManyPayload(args, maxBodyBytes) {
     total += 4 + idLength + 4 + itemPartitionLength + 8;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer10.Buffer.allocUnsafe(total);
+  const out = import_node_buffer11.Buffer.allocUnsafe(total);
   let offset = 0;
   out.writeUInt8(tag, offset);
   offset += 1;
@@ -3694,6 +3813,7 @@ function compactFlowCancelManyPayload(args, maxBodyBytes) {
     offset += 8;
   }
   return {
+    compactResponseItems: count,
     flags: FLAG_CUSTOM_PAYLOAD,
     opcode: COMMAND_OPCODES["FLOW.CANCEL_MANY"],
     payload: out
@@ -3707,7 +3827,7 @@ function isOptionalSafeIntegerNumber(value) {
 }
 
 // src/protocol-flow-compact-single.ts
-var import_node_buffer11 = require("buffer");
+var import_node_buffer12 = require("buffer");
 function compactFlowValueMGetPayload(refs, maxBytes, maxBodyBytes) {
   if (refs.length > 4294967295 || maxBytes != null && (typeof maxBytes !== "number" || !Number.isSafeInteger(maxBytes) || maxBytes < 0)) return void 0;
   const minimum = 13 + refs.length * 4;
@@ -3724,7 +3844,7 @@ function compactFlowValueMGetPayload(refs, maxBytes, maxBodyBytes) {
     total += 4 + byteLength;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer11.Buffer.allocUnsafe(total);
+  const out = import_node_buffer12.Buffer.allocUnsafe(total);
   let offset = 0;
   out.writeUInt8(COMPACT_FLOW_VALUE_MGET_REQUEST, offset);
   offset += 1;
@@ -3737,47 +3857,6 @@ function compactFlowValueMGetPayload(refs, maxBytes, maxBodyBytes) {
   }
   return { flags: FLAG_CUSTOM_PAYLOAD, opcode: OPCODES.flowValueMGet, payload: out };
 }
-function compactFlowListPayload(args, maxBodyBytes) {
-  const type = args[0];
-  if (!isCompactBinaryArgument(type)) return void 0;
-  let state;
-  let count = 100;
-  let returnMode = 0;
-  const seen = /* @__PURE__ */ new Set();
-  for (let index = 1; index < args.length; index += 2) {
-    if (index + 1 >= args.length) return void 0;
-    const token = asText(args[index]).toUpperCase();
-    if (seen.has(token)) return void 0;
-    seen.add(token);
-    if (token === "STATE") {
-      if (!isCompactBinaryArgument(args[index + 1])) return void 0;
-      state = args[index + 1];
-    } else if (token === "COUNT") {
-      const value = safeIntegerNumberArg(args[index + 1]);
-      if (value <= 0) return void 0;
-      count = value;
-    } else if (token === "RETURN") {
-      if (!commandTokenIs(args[index + 1], "META")) return void 0;
-      returnMode = 1;
-    } else {
-      return void 0;
-    }
-  }
-  const typeLength = compactBinaryByteLength(type);
-  const stateLength = state == null ? 0 : compactBinaryByteLength(state);
-  const total = 1 + 4 + typeLength + 4 + stateLength + 8 + 1;
-  assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer11.Buffer.allocUnsafe(total);
-  let offset = 0;
-  out.writeUInt8(COMPACT_FLOW_LIST_REQUEST, offset);
-  offset += 1;
-  offset = writeBinaryValue(out, offset, type, typeLength);
-  offset = writeOptionalBinaryValue(out, offset, state, stateLength);
-  out.writeBigInt64BE(BigInt(count), offset);
-  offset += 8;
-  out.writeUInt8(returnMode, offset);
-  return { flags: FLAG_CUSTOM_PAYLOAD, opcode: COMMAND_OPCODES["FLOW.LIST"], payload: out };
-}
 
 // src/protocol-flow-routing.ts
 function withFlowPartitionRouting(command, payload) {
@@ -3826,15 +3905,6 @@ function expandFlowClaimStates(args) {
 }
 
 // src/protocol-flow.ts
-function hasFlowCommandOnlyOption(command, args) {
-  if (command !== "FLOW.SEARCH") return false;
-  for (let index = 1; index < args.length; ) {
-    const token = asText(args[index]).toUpperCase();
-    if (token === "INDEXED_STATE_META") return true;
-    index += token === "ATTRIBUTE" || token === "STATE_META" ? 3 : 2;
-  }
-  return false;
-}
 function flowCreatePayload(args) {
   if (args.length < 7) return void 0;
   const id = args[0];
@@ -3891,9 +3961,9 @@ function flowValueMGetPayload(args, maxBodyBytes, allowCompact) {
   }
   if (allowCompact) {
     const compact = compactFlowValueMGetPayload(refs, payload.max_bytes, maxBodyBytes);
-    if (compact != null) return compact;
+    if (compact != null) return { ...compact, compactResponseItems: refs.length };
   }
-  return { opcode: OPCODES.flowValueMGet, payload };
+  return { compactResponseItems: refs.length, opcode: OPCODES.flowValueMGet, payload };
 }
 function flowCreateManyPayload(args, maxBodyBytes, allowCompact) {
   if (args.length < 2) return void 0;
@@ -3929,7 +3999,7 @@ function flowCreateManyPayload(args, maxBodyBytes, allowCompact) {
     if (items2 == null) return void 0;
     const payload2 = { ...options, items: items2 };
     if (!auto && !mixed) payload2.partition_key = partition;
-    return { opcode: OPCODES.flowCreateMany, payload: payload2 };
+    return { compactResponseItems: items2.length, opcode: OPCODES.flowCreateMany, payload: payload2 };
   }
   const rawItems = denseCommandArgumentTail(args, itemsIndex + 1, "ITEMS");
   const width = mixed ? 3 : 2;
@@ -3943,7 +4013,9 @@ function flowCreateManyPayload(args, maxBodyBytes, allowCompact) {
       options,
       maxBodyBytes
     );
-    if (compact != null) return compact;
+    if (compact != null) {
+      return { ...compact, compactResponseItems: rawItems.length / width };
+    }
   }
   const items = [];
   for (let index = 0; index < rawItems.length; index += width) {
@@ -3955,7 +4027,7 @@ function flowCreateManyPayload(args, maxBodyBytes, allowCompact) {
   }
   const payload = { ...options, items };
   if (!auto && !mixed) payload.partition_key = partition;
-  return { opcode: OPCODES.flowCreateMany, payload };
+  return { compactResponseItems: items.length, opcode: OPCODES.flowCreateMany, payload };
 }
 function flowClaimDuePayload(args, maxBodyBytes, allowCompact) {
   if (args.length < 1) return void 0;
@@ -4118,7 +4190,9 @@ function flowClaimedManyPayload(command, opcode, args, maxBodyBytes = Number.MAX
   if (rawItems.length === 0 || rawItems.length % width !== 0) return void 0;
   if (allowCompact) {
     const compact = command === "FLOW.RETRY_MANY" ? compactFlowRetryManyPayload(partition, rawItems, mixed, auto, options, maxBodyBytes) : compactFlowCompleteManyPayload(opcode, partition, rawItems, mixed, auto, options, maxBodyBytes);
-    if (compact != null) return compact;
+    if (compact != null) {
+      return { ...compact, compactResponseItems: rawItems.length / width };
+    }
   }
   const items = [];
   for (let index = 0; index < rawItems.length; index += width) {
@@ -4130,7 +4204,7 @@ function flowClaimedManyPayload(command, opcode, args, maxBodyBytes = Number.MAX
   }
   const payload = { ...options, items };
   if (!auto && !mixed) payload.partition_key = partition;
-  return { opcode, payload };
+  return { compactResponseItems: items.length, opcode, payload };
 }
 function flowTransitionManyPayload(args, maxBodyBytes, allowCompact) {
   if (args.length < 4) return void 0;
@@ -4170,7 +4244,9 @@ function flowTransitionManyPayload(args, maxBodyBytes, allowCompact) {
       options,
       maxBodyBytes
     ) : void 0;
-    if (compact != null) return compact;
+    if (compact != null) {
+      return { ...compact, compactResponseItems: rawItems.length / width };
+    }
   }
   const items = [];
   for (let index = 0; index < rawItems.length; index += width) {
@@ -4190,7 +4266,11 @@ function flowTransitionManyPayload(args, maxBodyBytes, allowCompact) {
     items
   };
   if (!mixed) payload.partition_key = args[0];
-  return { opcode: OPCODES.flowTransitionMany, payload };
+  return {
+    compactResponseItems: items.length,
+    opcode: OPCODES.flowTransitionMany,
+    payload
+  };
 }
 function flowSpawnChildrenPayload(args) {
   if (args.length < 2) return void 0;
@@ -4233,13 +4313,6 @@ function flowSpawnChildrenPayload(args) {
     payload: { id: args[0], ...options, children }
   };
 }
-function flowSearchPayload(args) {
-  if (args.length < 1) return void 0;
-  const payload = optionMap(args.slice(1));
-  if (payload == null) return void 0;
-  normalizeFlowSearchStateMeta(payload);
-  return { opcode: OPCODES.flowSearch, payload: { type: args[0], ...payload } };
-}
 
 // src/protocol-flow-signal.ts
 function flowSignalPayload(args) {
@@ -4265,7 +4338,7 @@ function flowSignalPayload(args) {
 }
 
 // src/protocol-flow-policy.ts
-var import_node_buffer12 = require("buffer");
+var import_node_buffer13 = require("buffer");
 var BACKOFF_FIELDS = {
   BASE_MS: "base_ms",
   MAX_MS: "max_ms",
@@ -4395,7 +4468,7 @@ function maxActiveOption(value) {
   return integerOption(value);
 }
 function isBinaryArgument(value) {
-  return typeof value === "string" || import_node_buffer12.Buffer.isBuffer(value) || value instanceof Uint8Array;
+  return typeof value === "string" || import_node_buffer13.Buffer.isBuffer(value) || value instanceof Uint8Array;
 }
 function objectField(target, name) {
   const existing = Object.hasOwn(target, name) ? target[name] : void 0;
@@ -4467,7 +4540,7 @@ function commandRequiresOrderedPipelineExecution(args) {
 }
 
 // src/protocol-compact-request.ts
-var import_node_buffer13 = require("buffer");
+var import_node_buffer14 = require("buffer");
 function compactMsetPayload(args, maxBodyBytes) {
   if (args.length % 2 !== 0) throw new FerricStoreError("MSET requires key/value pairs");
   const minimum = 6 + args.length * 4;
@@ -4486,7 +4559,7 @@ function compactMsetPayload(args, maxBodyBytes) {
     total += 4 + byteLength;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer13.Buffer.allocUnsafe(total);
+  const out = import_node_buffer14.Buffer.allocUnsafe(total);
   let offset = writeCompactPipelineHeader(out, 1, args.length / 2);
   for (let index = 0; index < args.length; index += 1) {
     offset = writeBinaryValue(out, offset, args[index], byteLengths[index] ?? 0);
@@ -4510,7 +4583,7 @@ function compactKeyPipelinePayload(opcode, args, mode, maxBodyBytes) {
     total += 4 + byteLength;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer13.Buffer.allocUnsafe(total);
+  const out = import_node_buffer14.Buffer.allocUnsafe(total);
   let offset = writeCompactPipelineHeader(out, mode, args.length);
   for (let index = 0; index < args.length; index += 1) {
     offset = writeBinaryValue(out, offset, args[index], byteLengths[index] ?? 0);
@@ -4520,7 +4593,7 @@ function compactKeyPipelinePayload(opcode, args, mode, maxBodyBytes) {
 function compactPipelinePayload(commands, maxBodyBytes) {
   if (commands.length === 0) {
     assertCompactPayloadFits(6, maxBodyBytes);
-    const out = import_node_buffer13.Buffer.allocUnsafe(6);
+    const out = import_node_buffer14.Buffer.allocUnsafe(6);
     writeCompactPipelineHeader(out, 128 | 2, 0);
     return out;
   }
@@ -4562,7 +4635,7 @@ function compactSetPipelinePayload(commands, maxBodyBytes) {
     total += 8 + keyByteLength + valueByteLength;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer13.Buffer.allocUnsafe(total);
+  const out = import_node_buffer14.Buffer.allocUnsafe(total);
   let offset = writeCompactPipelineHeader(out, 128 | 1, commands.length);
   for (let index = 0; index < commands.length; index += 1) {
     offset = writeBinaryValue(out, offset, argumentValues[index * 2], argumentByteLengths[index * 2] ?? 0);
@@ -4597,7 +4670,7 @@ function compactGetPipelinePayload(commands, maxBodyBytes) {
     total += 4 + keyByteLength;
   }
   assertCompactPayloadFits(total, maxBodyBytes);
-  const out = import_node_buffer13.Buffer.allocUnsafe(total);
+  const out = import_node_buffer14.Buffer.allocUnsafe(total);
   let offset = writeCompactPipelineHeader(out, 128 | 2, commands.length);
   for (let index = 0; index < commands.length; index += 1) {
     offset = writeBinaryValue(out, offset, keys[index], keyByteLengths[index] ?? 0);
@@ -4638,7 +4711,7 @@ function writeCompactPipelineHeader(out, mode, count) {
 }
 
 // src/protocol-kv.ts
-var import_node_buffer14 = require("buffer");
+var import_node_buffer15 = require("buffer");
 function collectionProtocolCommand(command, args) {
   switch (command) {
     case "CAS":
@@ -4709,8 +4782,8 @@ function stringSetPayload(args) {
       if (value == null || token === "EX" && value > Math.floor(Number.MAX_SAFE_INTEGER / 1e3)) {
         return void 0;
       }
-      const field2 = token === "EX" || token === "PX" ? "ttl" : token.toLowerCase();
-      setOwnValue2(payload, field2, token === "EX" ? value * 1e3 : value);
+      const field3 = token === "EX" || token === "PX" ? "ttl" : token.toLowerCase();
+      setOwnValue2(payload, field3, token === "EX" ? value * 1e3 : value);
       expirySeen = true;
       index += 2;
     } else if (token === "NX") {
@@ -4809,25 +4882,25 @@ function hashSetCommand(args) {
   if (!isBinaryCommandArgument(args[0]) || args.length < 3 || args.length % 2 !== 1) return void 0;
   const fields = /* @__PURE__ */ Object.create(null);
   for (let index = 1; index < args.length; index += 2) {
-    const field2 = args[index];
+    const field3 = args[index];
     const value = args[index + 1];
-    if (typeof field2 !== "string" || !isBinaryCommandArgument(value)) return void 0;
-    setOwnValue2(fields, field2, value);
+    if (typeof field3 !== "string" || !isBinaryCommandArgument(value)) return void 0;
+    setOwnValue2(fields, field3, value);
   }
   return { opcode: COMMAND_OPCODES.HSET, payload: { fields, key: args[0] } };
 }
 function keyOnlyCommand(opcode, args) {
   return args.length === 1 && isBinaryCommandArgument(args[0]) ? { opcode, payload: { key: args[0] } } : void 0;
 }
-function binaryFieldsCommand(opcode, args, field2, length) {
+function binaryFieldsCommand(opcode, args, field3, length) {
   if (args.length !== length || !isBinaryCommandArgument(args[0]) || !isBinaryCommandArgument(args[1])) return void 0;
-  return { opcode, payload: { [field2]: args[1], key: args[0] } };
+  return { opcode, payload: { [field3]: args[1], key: args[0] } };
 }
-function binaryListCommand(opcode, args, field2) {
+function binaryListCommand(opcode, args, field3) {
   if (!isBinaryCommandArgument(args[0]) || args.length < 2) return void 0;
   const values = args.slice(1);
   if (!values.every(isBinaryCommandArgument)) return void 0;
-  return { opcode, payload: { [field2]: values, key: args[0] } };
+  return { opcode, payload: { [field3]: values, key: args[0] } };
 }
 function listPopCommand(opcode, args) {
   if (!isBinaryCommandArgument(args[0]) || args.length !== 1 && args.length !== 2) return void 0;
@@ -4885,17 +4958,35 @@ function parsedNumber(value) {
   }
 }
 function isBinaryCommandArgument(value) {
-  return typeof value === "string" || import_node_buffer14.Buffer.isBuffer(value);
+  return typeof value === "string" || import_node_buffer15.Buffer.isBuffer(value);
 }
 function isDirectKvValueArgument(value) {
   return isBinaryCommandArgument(value) || typeof value === "object" && value != null;
 }
 function binaryToken(value) {
-  return typeof value === "string" ? value.toUpperCase() : import_node_buffer14.Buffer.isBuffer(value) ? value.toString("utf8").toUpperCase() : void 0;
+  return typeof value === "string" ? value.toUpperCase() : import_node_buffer15.Buffer.isBuffer(value) ? value.toString("utf8").toUpperCase() : void 0;
+}
+
+// src/protocol-value.ts
+var import_node_buffer17 = require("buffer");
+
+// src/protocol-map-key.ts
+var import_node_buffer16 = require("buffer");
+function setProtocolMapEntry(target, encodedKey, value) {
+  if (typeof encodedKey === "string" && !encodedKey.isWellFormed()) {
+    throw new FerricStoreError("native protocol map key must be valid UTF-8");
+  }
+  if (typeof encodedKey !== "string" && !(0, import_node_buffer16.isUtf8)(encodedKey)) {
+    throw new FerricStoreError("native protocol map key must be valid UTF-8");
+  }
+  const key = typeof encodedKey === "string" ? encodedKey : encodedKey.toString("utf8");
+  if (Object.hasOwn(target, key)) {
+    throw new FerricStoreError(`native protocol response contains duplicate map key ${JSON.stringify(key)}`);
+  }
+  setOwnValue2(target, key, value);
 }
 
 // src/protocol-value.ts
-var import_node_buffer15 = require("buffer");
 function planValueWithLimit(value, maxBytes) {
   const budget = {
     maxBytes,
@@ -4950,7 +5041,7 @@ function planContainerValue(value, budget, ancestors, depth) {
     let byteLength = 5;
     let index = 0;
     for (const [key, item] of entries) {
-      const keyByteLength = import_node_buffer15.Buffer.byteLength(key);
+      const keyByteLength = import_node_buffer17.Buffer.byteLength(key);
       consumeEncodeBytes(budget, 4 + keyByteLength);
       const valuePlan = planValueAt(item, budget, ancestors, depth + 1);
       entryPlans[index] = { key, keyByteLength, value: valuePlan };
@@ -4989,17 +5080,21 @@ function planScalarValue(value, budget) {
     return { byteLength: 9, tag: 3, value: BigInt(value) };
   }
   if (typeof value === "bigint") {
-    if (value < MIN_I64 || value > MAX_I64) {
-      throw new FerricStoreError("integer exceeds the signed 64-bit native range");
+    if (value >= MIN_I642 && value <= MAX_I642) {
+      consumeEncodeBytes(budget, 9);
+      return { byteLength: 9, tag: 3, value };
     }
-    consumeEncodeBytes(budget, 9);
-    return { byteLength: 9, tag: 3, value };
+    if (value > MAX_I642 && value <= MAX_U64) {
+      consumeEncodeBytes(budget, 9);
+      return { byteLength: 9, tag: 8, value };
+    }
+    throw new FerricStoreError("integer exceeds the signed or unsigned 64-bit native range");
   }
   if (typeof value === "number") {
     consumeEncodeBytes(budget, 9);
     return { byteLength: 9, tag: 7, value };
   }
-  if (typeof value === "string" || import_node_buffer15.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+  if (typeof value === "string" || import_node_buffer17.Buffer.isBuffer(value) || value instanceof Uint8Array) {
     const valueByteLength = binaryValueByteLength(value);
     const byteLength = 5 + valueByteLength;
     consumeEncodeBytes(budget, byteLength);
@@ -5023,7 +5118,7 @@ function writeValuePlan(output, start, plan) {
       offset += 4;
       if (typeof plan.value === "string") {
         output.write(plan.value, offset, plan.valueByteLength, "utf8");
-      } else if (import_node_buffer15.Buffer.isBuffer(plan.value)) {
+      } else if (import_node_buffer17.Buffer.isBuffer(plan.value)) {
         plan.value.copy(output, offset);
       } else {
         output.set(plan.value, offset);
@@ -5048,6 +5143,9 @@ function writeValuePlan(output, start, plan) {
     case 7:
       output.writeDoubleBE(plan.value, offset);
       return offset + 8;
+    case 8:
+      output.writeBigUInt64BE(plan.value, offset);
+      return offset + 8;
   }
 }
 function consumeEncodeBytes(budget, bytes2) {
@@ -5105,7 +5203,7 @@ function decodeValueAt(data, offset, limits, budget, depth) {
       const key = readBinary(data, offset);
       offset = key.offset;
       const item = decodeValueAt(data, offset, limits, budget, depth + 1);
-      setOwnValue2(value, key.value.toString("utf8"), item.value);
+      setProtocolMapEntry(value, key.value, item.value);
       offset = item.offset;
     }
     return { value, offset };
@@ -5114,6 +5212,14 @@ function decodeValueAt(data, offset, limits, budget, depth) {
     requireAvailable(data, offset, 8);
     return { value: data.readDoubleBE(offset), offset: offset + 8 };
   }
+  if (tag === 8) {
+    requireAvailable(data, offset, 8);
+    const integer2 = data.readBigUInt64BE(offset);
+    return {
+      value: integer2 <= MAX_SAFE_INTEGER_BIGINT ? Number(integer2) : integer2,
+      offset: offset + 8
+    };
+  }
   throw new FerricStoreError(`unknown protocol value tag ${tag}`);
 }
 function decodeValueWithBudget(data, offset, budget) {
@@ -5157,20 +5263,20 @@ function requireAvailable(data, offset, size) {
 }
 
 // src/key-slot-validation.ts
-var import_node_buffer17 = require("buffer");
+var import_node_buffer19 = require("buffer");
 
 // src/topology-utilities.ts
-var import_node_buffer16 = require("buffer");
+var import_node_buffer18 = require("buffer");
 function isPlainObject3(value) {
-  return typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer16.Buffer.isBuffer(value);
+  return typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer18.Buffer.isBuffer(value);
 }
 function getField(source, ...keys) {
   if (source instanceof Map) {
     for (const key of keys) {
       if (source.has(key)) return source.get(key);
-      const bufferKey = import_node_buffer16.Buffer.from(key);
+      const bufferKey = import_node_buffer18.Buffer.from(key);
       for (const [itemKey, value] of source.entries()) {
-        if (import_node_buffer16.Buffer.isBuffer(itemKey) && itemKey.equals(bufferKey)) return value;
+        if (import_node_buffer18.Buffer.isBuffer(itemKey) && itemKey.equals(bufferKey)) return value;
       }
     }
     return void 0;
@@ -5184,14 +5290,14 @@ function getField(source, ...keys) {
 }
 function textOrUndefined(value) {
   if (typeof value === "string") return value;
-  if (import_node_buffer16.Buffer.isBuffer(value)) return value.toString("utf8");
+  if (import_node_buffer18.Buffer.isBuffer(value)) return value.toString("utf8");
   return void 0;
 }
 function numberOrUndefined(value) {
   return typeof value === "number" && Number.isSafeInteger(value) ? value : void 0;
 }
-function nativeEventName(event) {
-  return textOrUndefined(getField(event.value, "event"))?.toUpperCase();
+function nativeEventName(event2) {
+  return textOrUndefined(getField(event2.value, "event"))?.toUpperCase();
 }
 function endpointFromRange(item) {
   const endpointValue = getField(item, "endpoint");
@@ -5359,7 +5465,7 @@ function stringHashRange(key) {
 var validatedCommands = /* @__PURE__ */ new WeakSet();
 function assertAtomicKeyValueCommandSharesSlot(args) {
   const value = args[0];
-  const command = (typeof value === "string" ? value : import_node_buffer17.Buffer.isBuffer(value) ? value.toString("utf8") : "").toUpperCase();
+  const command = (typeof value === "string" ? value : import_node_buffer19.Buffer.isBuffer(value) ? value.toString("utf8") : "").toUpperCase();
   if (command === "MSET" || command === "MSETNX") {
     assertKeyValueCommandSharesSlot(args, command);
   }
@@ -5369,7 +5475,7 @@ function assertKeyValueCommandSharesSlot(args, command) {
   let expectedSlot;
   for (let index = 1; index < args.length; index += 2) {
     const key = args[index];
-    if (typeof key !== "string" && !import_node_buffer17.Buffer.isBuffer(key)) return;
+    if (typeof key !== "string" && !import_node_buffer19.Buffer.isBuffer(key)) return;
     const slot = routingSlotForKey(key);
     expectedSlot ??= slot;
     if (slot !== expectedSlot) {
@@ -5380,62 +5486,202 @@ function assertKeyValueCommandSharesSlot(args, command) {
 }
 
 // src/protocol-response.ts
-var import_node_buffer21 = require("buffer");
+var import_node_buffer26 = require("buffer");
 
 // src/protocol-compact-response.ts
-var import_node_buffer20 = require("buffer");
+var import_node_buffer25 = require("buffer");
 
 // src/native-negotiation.ts
-var import_node_buffer18 = require("buffer");
+var import_node_buffer20 = require("buffer");
 var EMPTY_COMPACT_RESPONSE_OPCODES = /* @__PURE__ */ new Map();
 function nativeNegotiation(value) {
   const capabilities = field(value, "capabilities") ?? value;
   const limits = field(capabilities, "limits");
-  const responseCodecs = field(capabilities, "response_codecs");
+  const rawResponseCodecs = field(capabilities, "response_codecs");
+  const responseCodecs = rawResponseCodecs == null ? void 0 : requiredMap(rawResponseCodecs, "HELLO response_codecs");
+  const schemas = requiredMap(field(capabilities, "schemas"), "HELLO schemas");
   const maxResponseBytes = positiveSafeInteger3(field(limits, "max_response_bytes"));
   return {
     compactResponseOpcodes: parseCompactResponseOpcodes(
       field(responseCodecs, "compact_response_opcodes")
     ),
+    flowQuery: parseFlowQueryNegotiation(capabilities, schemas),
     ...maxResponseBytes == null ? {} : { maxResponseBytes }
   };
 }
+var REQUIRED_FLOW_QUERY_CAPABILITIES = /* @__PURE__ */ new Set([
+  "flow_query_v1",
+  "flow_query_result_projection_v1",
+  "flow_explain_v1",
+  "flow_explain_analyze_v1",
+  "flow_composite_index_v1",
+  "flow_query_index_status_v1"
+]);
+var REQUIRED_FLOW_QUERY_SHAPES = /* @__PURE__ */ new Set([
+  "runs_by_run_id_record",
+  "runs_by_partition_and_run_id_record",
+  "runs_by_partition_predicates_ordered_records",
+  "runs_by_partition_type_state_ordered_records",
+  "runs_by_partition_type_terminals_ordered_records",
+  "runs_by_partition_metadata_ordered_records",
+  "runs_by_partition_type_running_lease_deadline_ordered_records",
+  "runs_by_partition_parent_ordered_records",
+  "runs_by_partition_root_ordered_records",
+  "runs_by_partition_correlation_ordered_records",
+  "runs_by_partition_predicates_count",
+  "events_by_run_id_ordered_records"
+]);
+function parseFlowQueryNegotiation(capabilities, schemas) {
+  const manifest = requiredMap(field(capabilities, "flow_query"), "HELLO flow_query");
+  const requestContract = requiredBoundedText(manifest, "request_contract");
+  const resultContract = requiredBoundedText(manifest, "result_contract");
+  const explainContract = requiredBoundedText(manifest, "explain_contract");
+  const indexStatusContract = requiredBoundedText(manifest, "index_status_contract");
+  requireEqual(requestContract, "ferric.flow.query.request/v1", "flow_query request_contract");
+  requireEqual(resultContract, "ferric.flow.query.result/v1", "flow_query result_contract");
+  requireEqual(explainContract, "ferric.flow.explain/v1", "flow_query explain_contract");
+  requireEqual(
+    indexStatusContract,
+    "ferric.flow.query.indexes/v1",
+    "flow_query index_status_contract"
+  );
+  const queryCapabilities = boundedTextSet(manifest, "capabilities", 64);
+  const languageVersions = boundedTextSet(manifest, "language_versions", 16);
+  const shapes = boundedTextSet(manifest, "shapes", 128);
+  requireMembers(queryCapabilities, REQUIRED_FLOW_QUERY_CAPABILITIES, "flow_query capability");
+  requireMembers(languageVersions, /* @__PURE__ */ new Set(["FQL1"]), "flow_query language");
+  requireMembers(shapes, REQUIRED_FLOW_QUERY_SHAPES, "flow_query shape");
+  const schema = requiredMap(field(schemas, "FLOW.QUERY"), "HELLO FLOW.QUERY schema");
+  const fields = boundedTextSet(schema, "fields", 64);
+  requireMembers(
+    fields,
+    /* @__PURE__ */ new Set(["version", "query", "params", "deadline_ms"]),
+    "FLOW.QUERY schema field"
+  );
+  const required = boundedTextSet(schema, "required", 16);
+  if (required.size !== 2 || !required.has("version") || !required.has("query")) {
+    throw incompatibleServer("FLOW.QUERY schema must require exactly version and query");
+  }
+  return {
+    requestContract: "ferric.flow.query.request/v1",
+    resultContract: "ferric.flow.query.result/v1",
+    explainContract: "ferric.flow.explain/v1",
+    indexStatusContract: "ferric.flow.query.indexes/v1",
+    capabilities: queryCapabilities,
+    languageVersions,
+    shapes
+  };
+}
+function requiredMap(value, context) {
+  if (value instanceof Map) return value;
+  if (typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer20.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+    return value;
+  }
+  throw incompatibleServer(`${context} is missing or invalid`);
+}
+function requiredBoundedText(mapping, name) {
+  const value = strictText(field(mapping, name));
+  if (value == null || value.length === 0 || import_node_buffer20.Buffer.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);
+  if (!Array.isArray(raw) || raw.length < 1 || raw.length > maximum) {
+    throw incompatibleServer(`HELLO ${name} must contain 1..${maximum} entries`);
+  }
+  const result = /* @__PURE__ */ new Set();
+  for (let index = 0; index < raw.length; index += 1) {
+    if (!Object.hasOwn(raw, index)) throw incompatibleServer(`HELLO ${name} must be dense`);
+    const item = strictText(raw[index]);
+    if (item == null || item.length === 0 || import_node_buffer20.Buffer.byteLength(item) > 256) {
+      throw incompatibleServer(`HELLO ${name} contains invalid text`);
+    }
+    if (result.has(item)) throw incompatibleServer(`HELLO ${name} contains duplicate ${item}`);
+    result.add(item);
+  }
+  return result;
+}
+function requireMembers(actual, required, context) {
+  for (const item of required) {
+    if (!actual.has(item)) throw incompatibleServer(`missing ${context} ${JSON.stringify(item)}`);
+  }
+}
+function requireEqual(actual, expected, context) {
+  if (actual !== expected) throw incompatibleServer(`${context} must be ${JSON.stringify(expected)}`);
+}
+function strictText(value) {
+  if (typeof value === "string") return value;
+  if (import_node_buffer20.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(value);
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function incompatibleServer(message) {
+  return new FerricStoreError(`incompatible FerricStore server: ${message}`);
+}
 function compactResponseOpcodeSupports(capabilities, codec, opcode) {
   return capabilities?.get(codec)?.has(opcode) === true;
 }
 function parseCompactResponseOpcodes(value) {
+  if (value == null) return EMPTY_COMPACT_RESPONSE_OPCODES;
   const entries = mapEntries(value);
-  if (entries == null) return EMPTY_COMPACT_RESPONSE_OPCODES;
+  if (entries == null) {
+    throw incompatibleServer("HELLO compact_response_opcodes must be a map");
+  }
+  if (entries.length > 32) {
+    throw incompatibleServer("HELLO compact_response_opcodes supports at most 32 codecs");
+  }
   const result = /* @__PURE__ */ new Map();
+  let totalOpcodes = 0;
   for (const [rawName, rawOpcodes] of entries) {
-    const name = text2(rawName);
-    if (name == null || name.length === 0 || !Array.isArray(rawOpcodes)) continue;
+    const name = strictText(rawName);
+    if (name == null || name.length === 0 || import_node_buffer20.Buffer.byteLength(name) > 128) {
+      throw incompatibleServer("HELLO compact_response_opcodes contains an invalid codec name");
+    }
+    if (result.has(name)) {
+      throw incompatibleServer(`HELLO compact_response_opcodes contains duplicate codec ${name}`);
+    }
+    if (!Array.isArray(rawOpcodes)) {
+      throw incompatibleServer(`HELLO compact_response_opcodes codec ${name} must be an array`);
+    }
+    totalOpcodes += rawOpcodes.length;
+    if (totalOpcodes > 1024) {
+      throw incompatibleServer("HELLO compact_response_opcodes supports at most 1024 opcodes");
+    }
     const opcodes = /* @__PURE__ */ new Set();
-    let valid = true;
     for (let index = 0; index < rawOpcodes.length; index += 1) {
       if (!Object.hasOwn(rawOpcodes, index)) {
-        valid = false;
-        break;
+        throw incompatibleServer(`HELLO compact_response_opcodes codec ${name} must be dense`);
       }
-      const opcode = unsigned16(rawOpcodes[index]);
+      const opcode = strictUnsigned16(rawOpcodes[index]);
       if (opcode == null) {
-        valid = false;
-        break;
+        throw incompatibleServer(`HELLO compact_response_opcodes codec ${name} has invalid opcode`);
+      }
+      if (opcodes.has(opcode)) {
+        throw incompatibleServer(`HELLO compact_response_opcodes codec ${name} has duplicate opcode`);
       }
       opcodes.add(opcode);
     }
-    if (valid) result.set(name, opcodes);
+    result.set(name, opcodes);
   }
   return result;
 }
 function mapEntries(value) {
   if (value instanceof Map) return [...value.entries()];
-  if (typeof value !== "object" || value == null || Array.isArray(value)) return void 0;
+  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer20.Buffer.isBuffer(value) || value instanceof Uint8Array) return void 0;
   return Object.entries(value);
 }
-function unsigned16(value) {
-  const parsed = nonNegativeSafeInteger2(value);
-  return parsed != null && parsed <= 65535 ? parsed : void 0;
+function strictUnsigned16(value) {
+  if (typeof value === "bigint") {
+    return value >= 0n && value <= 0xffffn ? Number(value) : void 0;
+  }
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 65535 ? value : void 0;
 }
 function positiveSafeInteger3(value) {
   const parsed = nonNegativeSafeInteger2(value);
@@ -5454,14 +5700,14 @@ function nonNegativeSafeInteger2(value) {
 }
 function text2(value) {
   if (typeof value === "string") return value;
-  if (import_node_buffer18.Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return import_node_buffer18.Buffer.from(value).toString("utf8");
+  if (import_node_buffer20.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return import_node_buffer20.Buffer.from(value).toString("utf8");
   }
   return void 0;
 }
 
 // src/protocol-compact-collections.ts
-var import_node_buffer19 = require("buffer");
+var import_node_buffer21 = require("buffer");
 function decodeCompactIntegerList(data, budget) {
   requireAvailable(data, 0, 5);
   const count = data.readUInt32BE(1);
@@ -5526,7 +5772,7 @@ function readCompactBinaryMap(data, offset, budget) {
   for (let index = 0; index < count; index += 1) {
     const key = readBinary(data, offset);
     const value = readBinary(data, key.offset);
-    setOwnValue2(values, key.value.toString("utf8"), value.value);
+    setProtocolMapEntry(values, key.value, value.value);
     offset = value.offset;
   }
   return { value: values, offset };
@@ -5542,39 +5788,274 @@ function requireCompactContainer(count, budget) {
   consumeDecodeItems(count, budget);
 }
 
-// src/protocol-compact-response.ts
-function tryDecodeCompactResponse(opcode, body, hints) {
-  if (body.byteLength === 0) return { found: false, value: void 0 };
-  const budget = { remainingItems: DEFAULT_MAX_VALUE_ITEMS };
-  const tag = body.readUInt8(0);
-  const pipelineValues = opcode === OPCODES.pipeline && supports(hints, "pipeline_v1", opcode);
-  if (tag === COMPACT_OK_LIST && (supports(hints, "ok_list_v1", opcode) || pipelineValues)) {
-    const values = decodeCompactOkList(body, budget);
-    return {
-      found: true,
-      value: opcode === OPCODES.pipeline ? markCompactPipelineDecoded(values) : values.length === 1 ? "OK" : values
-    };
-  }
-  if (tag === COMPACT_KV_GET && supports(hints, "kv_get_v1", opcode)) {
-    return { found: true, value: decodeCompactKvGet(body) };
+// src/protocol-error-message.ts
+var import_node_buffer22 = require("buffer");
+var MAX_ERROR_MESSAGE_CHARS = 4096;
+var MAX_ERROR_TEXT_BYTES = MAX_ERROR_MESSAGE_CHARS * 4;
+function protocolErrorMessage(status, value) {
+  const direct = errorText(value);
+  if (direct != null) return truncate(direct);
+  return truncate(`ERR native request failed status=${status}: ${errorDescription(value)}`);
+}
+function errorText(value) {
+  if (typeof value === "string") return value;
+  if (import_node_buffer22.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return boundedBinaryText(value);
   }
-  if ((tag === COMPACT_KV_MGET || tag === COMPACT_KV_MGET_FIXED) && (supports(hints, "kv_mget_v1", opcode) || pipelineValues)) {
-    const values = tag === COMPACT_KV_MGET ? decodeCompactMget(body, budget) : decodeCompactMgetFixed(body, budget);
-    return {
-      found: true,
-      value: opcode === OPCODES.pipeline ? markCompactPipelineDecoded(values) : values
-    };
+  if (typeof value === "object" && value != null && Object.hasOwn(value, "message")) {
+    const message = value.message;
+    if (typeof message === "string") return message;
+    if (import_node_buffer22.Buffer.isBuffer(message) || message instanceof Uint8Array) {
+      return boundedBinaryText(message);
+    }
+    if (message == null || typeof message !== "object") return String(message);
   }
-  if (tag === COMPACT_INTEGER_LIST && pipelineValues) {
-    return { found: true, value: markCompactPipelineDecoded(decodeCompactIntegerList(body, budget)) };
+  return void 0;
+}
+function boundedBinaryText(value) {
+  const bytes2 = import_node_buffer22.Buffer.isBuffer(value) ? value : import_node_buffer22.Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  return bytes2.subarray(0, MAX_ERROR_TEXT_BYTES).toString("utf8");
+}
+function errorDescription(value) {
+  if (Array.isArray(value)) return `[array length=${value.length}]`;
+  if (value instanceof Map) return `[map size=${value.size}]`;
+  if (typeof value === "object" && value != null) return "[object]";
+  return String(value);
+}
+function truncate(value) {
+  return value.length <= MAX_ERROR_MESSAGE_CHARS ? value : `${value.slice(0, MAX_ERROR_MESSAGE_CHARS - 1)}\u2026`;
+}
+
+// src/protocol-flow-query-result.ts
+var import_node_buffer24 = require("buffer");
+
+// src/protocol-binary-detacher.ts
+var import_node_buffer23 = require("buffer");
+var MIN_PINNED_BACKING_BYTES = 64;
+function detachDecodedBinary(value, backingBytes) {
+  if (import_node_buffer23.Buffer.isBuffer(value)) return detachBuffer(value, backingBytes);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      value[index] = detachDecodedBinary(value[index], backingBytes);
+    }
+    return value;
   }
-  if (tag === COMPACT_BINARY_LIST_LIST && pipelineValues) {
-    return { found: true, value: markCompactPipelineDecoded(decodeCompactBinaryListList(body, budget)) };
+  if (!isDecodedRecord(value)) return value;
+  for (const key of Object.keys(value)) {
+    setOwnValue2(value, key, detachDecodedBinary(value[key], backingBytes));
   }
-  if (tag === COMPACT_BINARY_MAP_LIST && pipelineValues) {
-    return { found: true, value: markCompactPipelineDecoded(decodeCompactBinaryMapList(body, budget)) };
+  return value;
+}
+function detachBuffer(value, backingBytes) {
+  if (backingBytes <= Math.max(MIN_PINNED_BACKING_BYTES, value.byteLength * 2)) {
+    return value;
   }
-  if (tag === COMPACT_PIPELINE_RESPONSE && pipelineValues) {
+  if (value.byteLength === 0) return import_node_buffer23.Buffer.alloc(0);
+  const detached = import_node_buffer23.Buffer.allocUnsafeSlow(value.byteLength);
+  value.copy(detached);
+  return detached;
+}
+function isDecodedRecord(value) {
+  if (typeof value !== "object" || value == null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+// src/protocol-flow-query-result.ts
+var CONTRACT = "ferric.flow.query.result/v1";
+var MAX_RECORDS = 100;
+var MAX_CURSOR_BYTES = 4096;
+var RECORD_FIELDS = [
+  "id",
+  "type",
+  "state",
+  "version",
+  "priority",
+  "partition_key",
+  "created_at_ms",
+  "updated_at_ms",
+  "next_run_at_ms",
+  "lease_deadline_ms",
+  "attempts",
+  "run_state",
+  "max_active_ms",
+  "parent_flow_id",
+  "root_flow_id",
+  "correlation_id",
+  "attributes",
+  "state_meta",
+  "event_id",
+  "fields"
+];
+var RECORD_FIELD_MASK = (1 << RECORD_FIELDS.length) - 1;
+var QUALITY_VALUES = [
+  ["authoritative", "projected_exact", "exact", "not_applicable"],
+  ["current", "projection_watermark", "not_applicable"],
+  ["complete", "unavailable"],
+  ["none", "complete", "authenticated_seek", "live_seek"]
+];
+var QUALITY_FIELDS = ["exactness", "freshness", "coverage", "pagination"];
+var USAGE_FIELDS = [
+  "range_seeks",
+  "range_pages",
+  "scanned_entries",
+  "scanned_bytes",
+  "hydrated_records",
+  "residual_checks",
+  "duplicate_entries",
+  "result_records",
+  "response_bytes",
+  "memory_high_water_bytes",
+  "wall_time_us"
+];
+function decodeCompactFlowQueryResult(data, budget) {
+  requireAvailable(data, 0, 2 + QUALITY_FIELDS.length + USAGE_FIELDS.length * 8);
+  if (data.readUInt8(0) !== COMPACT_FLOW_QUERY_RESULT) {
+    throw new FerricStoreError("expected compact FLOW.QUERY result");
+  }
+  const kind = data.readUInt8(1);
+  let offset = 2;
+  const quality = {};
+  for (let index = 0; index < QUALITY_FIELDS.length; index += 1) {
+    const field3 = QUALITY_FIELDS[index];
+    const values = QUALITY_VALUES[index];
+    if (field3 == null || values == null) throw new FerricStoreError("invalid compact FLOW.QUERY quality schema");
+    const value = values[data.readUInt8(offset)];
+    if (value == null) throw new FerricStoreError("invalid compact FLOW.QUERY quality code");
+    quality[field3] = import_node_buffer24.Buffer.from(value);
+    offset += 1;
+  }
+  const usage = {};
+  for (const field3 of USAGE_FIELDS) {
+    const read = readU64(data, offset);
+    usage[field3] = read.value;
+    offset = read.offset;
+  }
+  let result;
+  if (kind === 0) {
+    const page = readPage(data, offset);
+    offset = page.offset;
+    requireAvailable(data, offset, 4);
+    const count = data.readUInt32BE(offset);
+    offset += 4;
+    if (count > MAX_RECORDS) throw new FerricStoreError("compact FLOW.QUERY page exceeds 100 records");
+    consumeDecodeItems(count, budget);
+    const records = new Array(count);
+    for (let index = 0; index < count; index += 1) {
+      const read = readRecord(data, offset, budget);
+      records[index] = read.value;
+      offset = read.offset;
+    }
+    result = { version: import_node_buffer24.Buffer.from(CONTRACT), records, page: page.value, quality, usage };
+  } else if (kind === 1) {
+    const count = readU64(data, offset);
+    offset = count.offset;
+    result = {
+      version: import_node_buffer24.Buffer.from(CONTRACT),
+      result: { kind: import_node_buffer24.Buffer.from("count"), value: count.value },
+      quality,
+      usage
+    };
+  } else {
+    throw new FerricStoreError(`unsupported compact FLOW.QUERY result kind ${kind}`);
+  }
+  if (offset !== data.byteLength) throw new FerricStoreError("trailing compact FLOW.QUERY result bytes");
+  if (BigInt(usage.response_bytes) !== BigInt(data.byteLength)) {
+    throw new FerricStoreError("compact FLOW.QUERY response_bytes does not match its payload");
+  }
+  return result;
+}
+function readPage(data, offset) {
+  requireAvailable(data, offset, 5);
+  const hasMoreCode = data.readUInt8(offset);
+  const size = data.readUInt32BE(offset + 1);
+  offset += 5;
+  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) {
+    throw new FerricStoreError("invalid compact FLOW.QUERY page cursor");
+  }
+  requireAvailable(data, offset, size);
+  return {
+    value: {
+      has_more: true,
+      cursor: detachDecodedBinary(data.subarray(offset, offset + size), data.byteLength)
+    },
+    offset: offset + size
+  };
+}
+function readRecord(data, offset, budget) {
+  requireAvailable(data, offset, 4);
+  const bitmap = data.readUInt32BE(offset);
+  offset += 4;
+  if ((bitmap & ~RECORD_FIELD_MASK) !== 0) {
+    throw new FerricStoreError("compact FLOW.QUERY record contains reserved fields");
+  }
+  consumeDecodeItems(populationCount(bitmap), budget);
+  const record = {};
+  for (let index = 0; index < RECORD_FIELDS.length; index += 1) {
+    if ((bitmap & 1 << index) === 0) continue;
+    const field3 = RECORD_FIELDS[index];
+    if (field3 == null) throw new FerricStoreError("invalid compact FLOW.QUERY record schema");
+    const read = decodeValueWithBudget(data, offset, budget);
+    setOwnValue2(record, field3, detachDecodedBinary(read.value, data.byteLength));
+    offset = read.offset;
+  }
+  return { value: record, offset };
+}
+function readU64(data, offset) {
+  requireAvailable(data, offset, 8);
+  const value = data.readBigUInt64BE(offset);
+  return {
+    value: value <= MAX_SAFE_INTEGER_BIGINT ? Number(value) : value,
+    offset: offset + 8
+  };
+}
+function populationCount(value) {
+  let remaining = value >>> 0;
+  let count = 0;
+  while (remaining !== 0) {
+    remaining &= remaining - 1;
+    count += 1;
+  }
+  return count;
+}
+
+// src/protocol-compact-response.ts
+function tryDecodeCompactResponse(opcode, body, hints) {
+  if (body.byteLength === 0) return { found: false, value: void 0 };
+  const budget = { remainingItems: DEFAULT_MAX_VALUE_ITEMS };
+  const tag = body.readUInt8(0);
+  validateCompactResponseItems(tag, opcode, body, hints);
+  const pipelineValues = opcode === OPCODES.pipeline && supports(hints, "pipeline_v1", opcode);
+  if (tag === COMPACT_OK_LIST && (supports(hints, "ok_list_v1", opcode) || pipelineValues)) {
+    const values = decodeCompactOkList(body, budget);
+    return {
+      found: true,
+      value: opcode === OPCODES.pipeline ? markCompactPipelineDecoded(values) : values.length === 1 ? "OK" : values
+    };
+  }
+  if (tag === COMPACT_KV_GET && supports(hints, "kv_get_v1", opcode)) {
+    return { found: true, value: decodeCompactKvGet(body) };
+  }
+  if ((tag === COMPACT_KV_MGET || tag === COMPACT_KV_MGET_FIXED) && (supports(hints, "kv_mget_v1", opcode) || pipelineValues)) {
+    const values = tag === COMPACT_KV_MGET ? decodeCompactMget(body, budget) : decodeCompactMgetFixed(body, budget);
+    return {
+      found: true,
+      value: opcode === OPCODES.pipeline ? markCompactPipelineDecoded(values) : values
+    };
+  }
+  if (tag === COMPACT_INTEGER_LIST && pipelineValues) {
+    return { found: true, value: markCompactPipelineDecoded(decodeCompactIntegerList(body, budget)) };
+  }
+  if (tag === COMPACT_BINARY_LIST_LIST && pipelineValues) {
+    return { found: true, value: markCompactPipelineDecoded(decodeCompactBinaryListList(body, budget)) };
+  }
+  if (tag === COMPACT_BINARY_MAP_LIST && pipelineValues) {
+    return { found: true, value: markCompactPipelineDecoded(decodeCompactBinaryMapList(body, budget)) };
+  }
+  if (tag === COMPACT_PIPELINE_RESPONSE && pipelineValues) {
     return { found: true, value: decodeCompactPipeline(body, budget, hints.pipelineClaimModes) };
   }
   if (tag === COMPACT_FLOW_CLAIM_JOBS && (supports(hints, "flow_claim_jobs_v1", opcode) || pipelineValues)) {
@@ -5597,6 +6078,9 @@ function tryDecodeCompactResponse(opcode, body, hints) {
       value: opcode === OPCODES.pipeline ? markCompactPipelineDecoded(read.value) : read.value
     };
   }
+  if (tag === COMPACT_FLOW_QUERY_RESULT && supports(hints, "flow_query_result_v1", opcode)) {
+    return { found: true, value: decodeCompactFlowQueryResult(body, budget) };
+  }
   return { found: false, value: void 0 };
 }
 function supports(hints, codec, opcode) {
@@ -5607,7 +6091,7 @@ function decodeCompactOkList(data, budget) {
   const count = data.readUInt32BE(1);
   requireCompactContainer2(count, budget);
   if (data.byteLength !== 5) throw new FerricStoreError("invalid compact OK list response");
-  return Array.from({ length: count }, () => import_node_buffer20.Buffer.from("OK"));
+  return Array.from({ length: count }, () => import_node_buffer25.Buffer.from("OK"));
 }
 function decodeCompactKvGet(data) {
   requireAvailable(data, 0, 2);
@@ -5653,7 +6137,7 @@ function decodeCompactMgetFixed(data, budget) {
   if (size === NULL_U32 || data.byteLength !== expected) {
     throw new FerricStoreError("invalid compact fixed MGET response");
   }
-  if (size === 0) return new Array(count).fill(import_node_buffer20.Buffer.alloc(0));
+  if (size === 0) return new Array(count).fill(import_node_buffer25.Buffer.alloc(0));
   const values = new Array(count);
   for (let index = 0, offset = 9; index < count; index += 1, offset += size) {
     values[index] = data.subarray(offset, offset + size);
@@ -5714,7 +6198,7 @@ function decodeCompactPipeline(data, budget, claimModes) {
       const read = readBinary(data, offset);
       const errorStatus = status === 1 ? "busy" : "error";
       values[index] = classifyServerError(
-        errorMessage(status === 1 ? 4 : 1, read.value),
+        protocolErrorMessage(status === 1 ? 4 : 1, read.value),
         read.value,
         void 0,
         errorStatus
@@ -5824,13 +6308,13 @@ function readCompactFlowRecord(data, offset, budget = { remainingItems: DEFAULT_
     let key;
     if (keyId === 0) {
       const read2 = readBinary(data, offset);
-      key = read2.value.toString("utf8");
+      key = read2.value;
       offset = read2.offset;
     } else {
       key = FLOW_RECORD_FIELD_KEYS[keyId] ?? `field_${keyId}`;
     }
     const read = decodeValueWithBudget(data, offset, budget);
-    setOwnValue2(record, key, read.value);
+    setProtocolMapEntry(record, key, read.value);
     offset = read.offset;
   }
   return { value: record, offset };
@@ -5866,15 +6350,29 @@ function requireCompactContainer2(count, budget) {
   }
   consumeDecodeItems(count, budget);
 }
-function errorMessage(status, value) {
-  if (typeof value === "string") return value;
-  if (import_node_buffer20.Buffer.isBuffer(value)) return value.toString("utf8");
-  if (typeof value === "object" && value != null && Object.hasOwn(value, "message")) {
-    const message = value.message;
-    return typeof message === "string" ? message : String(message);
+function validateCompactResponseItems(tag, opcode, data, hints) {
+  const scalarItems = opcode === OPCODES.set || opcode === OPCODES.mset ? 1 : void 0;
+  const expected = scalarItems ?? hints.compactResponseItems;
+  if (expected == null || !COUNTED_COMPACT_TAGS.has(tag)) return;
+  requireAvailable(data, 0, 5);
+  const actual = data.readUInt32BE(1);
+  if (actual !== expected) {
+    throw new FerricStoreError(
+      `compact response returned ${actual} items; expected ${expected} items`
+    );
   }
-  return `ERR native request failed status=${status}: ${String(value)}`;
 }
+var COUNTED_COMPACT_TAGS = /* @__PURE__ */ new Set([
+  COMPACT_FLOW_CLAIM_JOBS,
+  COMPACT_OK_LIST,
+  COMPACT_KV_MGET,
+  COMPACT_FLOW_RECORD_LIST,
+  COMPACT_BINARY_LIST_LIST,
+  COMPACT_BINARY_MAP_LIST,
+  COMPACT_INTEGER_LIST,
+  COMPACT_KV_MGET_FIXED,
+  COMPACT_PIPELINE_RESPONSE
+]);
 
 // src/protocol-response.ts
 function decodeResponse(frame, expectedOpcode, hints = {}) {
@@ -5892,9 +6390,16 @@ function decodeResponse(frame, expectedOpcode, hints = {}) {
   }
   const status = frame.body.readUInt16BE(0);
   const body = frame.body.subarray(2);
-  const value = decodeResponseValue(frame.opcode, body, hints);
+  const customPayload = (frame.flags & FLAG_CUSTOM_PAYLOAD) !== 0;
+  const value = decodeResponseValue(
+    frame.opcode,
+    body,
+    hints,
+    status === STATUS_OK,
+    customPayload
+  );
   if (status === STATUS_OK) return value;
-  const message = errorMessage2(status, value);
+  const message = protocolErrorMessage(status, value);
   throw classifyServerError(message, value, void 0, status);
 }
 function unwrapPipelineResponse(value, options = {}, expectedItems) {
@@ -5933,7 +6438,7 @@ function unwrapPipelineResponse(value, options = {}, expectedItems) {
           continue;
         }
         const error = classifyServerError(
-          errorMessage2(status === "busy" ? 4 : 1, payload),
+          protocolErrorMessage(status === "busy" ? 4 : 1, payload),
           payload,
           void 0,
           status
@@ -5948,28 +6453,24 @@ function unwrapPipelineResponse(value, options = {}, expectedItems) {
   return out;
 }
 function pipelineStatus(value) {
-  if (typeof value !== "string" && !import_node_buffer21.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) return null;
+  if (typeof value !== "string" && !import_node_buffer26.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) return null;
   const status = asText(value).toLowerCase();
   return status === "ok" || status === "busy" || status === "error" ? status : null;
 }
-function decodeResponseValue(opcode, body, hints) {
-  const compact = tryDecodeCompactResponse(opcode, body, hints);
-  if (compact.found) return compact.value;
+function decodeResponseValue(opcode, body, hints, allowCompact, customPayload) {
+  if (customPayload && allowCompact) {
+    const compact = tryDecodeCompactResponse(opcode, body, hints);
+    if (compact.found) return compact.value;
+  }
+  if (customPayload) {
+    throw new FerricStoreError("unsupported or malformed custom protocol response", { raw: body });
+  }
   const decoded = decodeValue(body);
   if (decoded.offset !== body.byteLength) {
     throw new FerricStoreError("native protocol response has trailing bytes", { raw: body });
   }
   return decoded.value;
 }
-function errorMessage2(status, value) {
-  if (typeof value === "string") return value;
-  if (import_node_buffer21.Buffer.isBuffer(value)) return value.toString("utf8");
-  if (typeof value === "object" && value != null && Object.hasOwn(value, "message")) {
-    const message = value.message;
-    return typeof message === "string" ? message : String(message);
-  }
-  return `ERR native request failed status=${status}: ${String(value)}`;
-}
 
 // src/protocol.ts
 function encodeRequest(command, requestId, maxBodyBytes = Number.MAX_SAFE_INTEGER) {
@@ -5979,7 +6480,7 @@ function encodeRequest(command, requestId, maxBodyBytes = Number.MAX_SAFE_INTEGE
   const bodyLength = customPayload ? binaryValueByteLength(command.payload) : plan?.byteLength ?? 0;
   if (bodyLength > bodyLimit) throw requestFrameTooLarge(bodyLimit);
   const flags = command.flags ?? 0;
-  const frame = import_node_buffer22.Buffer.allocUnsafe(HEADER_SIZE + bodyLength);
+  const frame = import_node_buffer27.Buffer.allocUnsafe(HEADER_SIZE + bodyLength);
   frame.write(MAGIC, 0, "ascii");
   frame.writeUInt8(REQUEST_VERSION, 4);
   frame.writeUInt8(flags, 5);
@@ -6080,18 +6581,18 @@ function buildProtocolCommand(args, maxBodyBytes = Number.MAX_SAFE_INTEGER, allo
   }
   if (command === "SET" && commandArgs2.length >= 2) {
     const payload = stringSetPayload(commandArgs2);
-    return payload == null ? commandExec(args) : { opcode: OPCODES.set, payload };
+    return payload == null ? commandExec(args) : { compactResponseItems: 1, opcode: OPCODES.set, payload };
   }
   if (command === "MGET" && commandArgs2.length > 0) {
     const compact = allowCustomPayload ? compactKeyPipelinePayload(OPCODES.mget, commandArgs2, 2, maxBodyBytes) : void 0;
-    if (compact != null) return compact;
-    return commandArgs2.every(isBinaryCommandArgument) ? { opcode: OPCODES.mget, payload: { keys: commandArgs2 } } : commandExec(args);
+    if (compact != null) return { ...compact, compactResponseItems: commandArgs2.length };
+    return commandArgs2.every(isBinaryCommandArgument) ? { compactResponseItems: commandArgs2.length, opcode: OPCODES.mget, payload: { keys: commandArgs2 } } : commandExec(args);
   }
   if (command === "MSET" && commandArgs2.length >= 2 && commandArgs2.length % 2 === 0) {
     const compact = allowCustomPayload ? compactMsetPayload(commandArgs2, maxBodyBytes) : void 0;
-    if (compact != null) return compact;
+    if (compact != null) return { ...compact, compactResponseItems: 1 };
     const pairs = typedKeyValuePairs(commandArgs2);
-    return pairs == null ? commandExec(args) : { opcode: OPCODES.mset, payload: { pairs } };
+    return pairs == null ? commandExec(args) : { compactResponseItems: 1, opcode: OPCODES.mset, payload: { pairs } };
   }
   if (command === "DEL" && commandArgs2.length > 0) {
     return commandArgs2.every(isBinaryCommandArgument) ? { opcode: OPCODES.del, payload: { keys: commandArgs2 } } : commandExec(args);
@@ -6101,8 +6602,8 @@ function buildProtocolCommand(args, maxBodyBytes = Number.MAX_SAFE_INTEGER, allo
   if (command === "FLOW.HISTORY") {
     return flowHistoryPayload(commandArgs2) ?? commandExec(args);
   }
-  if (command === "FLOW.LIST") {
-    return (allowCustomPayload ? compactFlowListPayload(commandArgs2, maxBodyBytes) : void 0) ?? commandExec(args);
+  if (command === "FLOW.QUERY") {
+    return { opcode: OPCODES.flowQuery, payload: flowQueryPayload(commandArgs2) };
   }
   if (command === "FLOW.POLICY.SET") {
     return flowPolicySetPayload(commandArgs2) ?? commandExec(args);
@@ -6261,24 +6762,17 @@ function buildProtocolCommand(args, maxBodyBytes = Number.MAX_SAFE_INTEGER, allo
   if (command === "FLOW.RUN_STEPS_MANY") {
     return flowAdminPayload(OPCODES.flowRunStepsMany, commandArgs2) ?? commandExec(args);
   }
-  if (command === "FLOW.SEARCH") {
-    if (hasFlowCommandOnlyOption(command, commandArgs2)) {
-      const fallback = commandExec(args);
-      try {
-        const parsed = flowSearchPayload(commandArgs2);
-        return parsed == null ? fallback : withFlowPartitionRouting(fallback, parsed.payload);
-      } catch {
-        return fallback;
-      }
-    }
-    return flowSearchPayload(commandArgs2) ?? commandExec(args);
-  }
   return commandExec(args);
 }
 function tryPipelineCommand(commands, maxBodyBytes = Number.MAX_SAFE_INTEGER) {
   const compact = compactPipelinePayload(commands, maxBodyBytes);
   if (compact != null) {
-    return { flags: FLAG_CUSTOM_PAYLOAD, opcode: OPCODES.pipeline, payload: compact };
+    return {
+      compactResponseItems: commands.length,
+      flags: FLAG_CUSTOM_PAYLOAD,
+      opcode: OPCODES.pipeline,
+      payload: compact
+    };
   }
   const protocols = new Array(commands.length);
   for (let index = 0; index < commands.length; index += 1) {
@@ -6317,6 +6811,7 @@ function tryPipelineCommand(commands, maxBodyBytes = Number.MAX_SAFE_INTEGER) {
   const pipelineClaimModes = pipelineProtocols.map((protocol) => protocol.compactClaimMode);
   const hasPipelineClaimMode = pipelineClaimModes.some((mode) => mode != null);
   return {
+    compactResponseItems: commands.length,
     opcode: OPCODES.pipeline,
     payload: {
       atomicity: "none",
@@ -6365,7 +6860,7 @@ var import_node_net2 = require("net");
 var import_node_tls2 = require("tls");
 
 // src/client-native-options.ts
-var import_node_buffer23 = require("buffer");
+var import_node_buffer28 = require("buffer");
 
 // src/string-array-snapshot.ts
 function snapshotOwnStringArray(values, name) {
@@ -6448,7 +6943,7 @@ function snapshotTlsOptions(options) {
   return Object.freeze(snapshot);
 }
 function snapshotTlsValue(value, name) {
-  if (import_node_buffer23.Buffer.isBuffer(value)) return import_node_buffer23.Buffer.from(value);
+  if (import_node_buffer28.Buffer.isBuffer(value)) return import_node_buffer28.Buffer.from(value);
   if (value instanceof Uint8Array) return value.slice();
   if (Array.isArray(value)) {
     const snapshot = new Array(value.length);
@@ -7003,7 +7498,7 @@ var NativeChunkAssembler = class {
 };
 
 // src/native-response-handler.ts
-var import_node_buffer24 = require("buffer");
+var import_node_buffer29 = require("buffer");
 
 // src/native-receive-buffer.ts
 var FRAME_ASSEMBLY_PAGE_BYTES = 64 * 1024;
@@ -7303,7 +7798,7 @@ var NativeResponseHandler = class {
       compactResponseOpcodes: this.options.compactResponseOpcodes?.() ?? EMPTY_COMPACT_RESPONSE_OPCODES
     });
     if (frame.opcode === OPCODES.windowUpdate) this.options.applyFlowControlLimits(value);
-    const event = {
+    const event2 = {
       flags: frame.flags,
       laneId: frame.laneId,
       opcode: frame.opcode,
@@ -7311,7 +7806,7 @@ var NativeResponseHandler = class {
     };
     if (frame.opcode === OPCODES.goaway) this.options.beginDraining();
     try {
-      const callback = this.options.onEvent?.(event);
+      const callback = this.options.onEvent?.(event2);
       if (callback != null) void Promise.resolve(callback).catch(() => void 0);
     } catch {
     }
@@ -7338,7 +7833,7 @@ var NativeRequestScheduler = class {
 };
 
 // src/native-write-queue.ts
-var import_node_buffer25 = require("buffer");
+var import_node_buffer30 = require("buffer");
 var NativeWriteQueue = class {
   constructor(socket, maxQueuedWriteBytes, isClosed, hasPending, rejectPending) {
     this.socket = socket;
@@ -7475,12 +7970,14 @@ var NativeConnectionCapabilities = class {
   }
   configuredRequestFrameBytes;
   compactResponseOpcodes = EMPTY_COMPACT_RESPONSE_OPCODES;
+  flowQuery;
   requestFrameBytes;
   negotiatedRequestFrameBytes;
   apply(value) {
     const limits = startupLimits(value);
     const negotiation = nativeNegotiation(value);
     this.compactResponseOpcodes = negotiation.compactResponseOpcodes;
+    this.flowQuery = negotiation.flowQuery;
     if (limits.frameBytes != null) {
       this.negotiatedRequestFrameBytes = Math.min(
         this.configuredRequestFrameBytes,
@@ -7500,6 +7997,19 @@ var NativeConnectionCapabilities = class {
   }
 };
 
+// src/native-startup-payload.ts
+function nativeStartupPayload(clientName, events) {
+  const name = clientName ?? "ferricstore-typescript";
+  return {
+    client_name: name,
+    compact_flow_responses: true,
+    compact_response_codecs: ["flow_query_result_v1"],
+    compression: "none",
+    driver_name: name,
+    ...events == null || events.length === 0 ? {} : { events: [...events] }
+  };
+}
+
 // src/native-adapter.ts
 var NativeAdapter = class _NativeAdapter {
   socket;
@@ -7658,13 +8168,7 @@ var NativeAdapter = class _NativeAdapter {
     const response = await this.request({
       laneId: 0,
       opcode: OPCODES.startup,
-      payload: {
-        client_name: clientName ?? "ferricstore-typescript",
-        compact_flow_responses: true,
-        compression: "none",
-        driver_name: clientName ?? "ferricstore-typescript",
-        ...events == null || events.length === 0 ? {} : { events: [...events] }
-      }
+      payload: nativeStartupPayload(clientName, events)
     });
     this.applyStartupLimits(response);
     const authRequired = field(response, "auth_required");
@@ -7724,6 +8228,7 @@ var NativeAdapter = class _NativeAdapter {
       if (!hasFlowControlCredit) this.pendingControlRequests += 1;
       this.pending.set(requestId, {
         ...command.compactClaimMode == null ? {} : { compactClaimMode: command.compactClaimMode },
+        ...command.compactResponseItems == null ? {} : { compactResponseItems: command.compactResponseItems },
         hasFlowControlCredit,
         indefinite: timeoutMs == null,
         laneId,
@@ -7855,10 +8360,10 @@ function executeCommandArgs(executor, args) {
 }
 
 // src/reconnecting-executor.ts
-var import_node_buffer28 = require("buffer");
+var import_node_buffer33 = require("buffer");
 
 // src/command-retry-policy.ts
-var import_node_buffer27 = require("buffer");
+var import_node_buffer32 = require("buffer");
 function isCasMutation(args) {
   const offset = commandName2(args[0]) === "COMMAND_EXEC" ? 1 : 0;
   const name = commandName2(args[offset]);
@@ -7872,8 +8377,8 @@ function isCasMutation(args) {
 }
 function commandName2(value) {
   if (typeof value === "string") return value.toUpperCase();
-  if (import_node_buffer27.Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return import_node_buffer27.Buffer.from(value).toString("utf8").toUpperCase();
+  if (import_node_buffer32.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return import_node_buffer32.Buffer.from(value).toString("utf8").toUpperCase();
   }
   return void 0;
 }
@@ -8085,19 +8590,91 @@ function normalizeNonNegativeInteger2(value, fallback) {
 }
 
 // src/topology.ts
-var import_node_buffer30 = require("buffer");
+var import_node_buffer36 = require("buffer");
 
 // src/topology-routing.ts
-var import_node_buffer29 = require("buffer");
+var import_node_buffer35 = require("buffer");
+
+// src/flow-partition-route-cache.ts
+var import_node_buffer34 = require("buffer");
 var import_node_crypto = require("crypto");
-var FLOW_PARTITION_ROUTE_CACHE_MAX = 1024;
-var flowPartitionRouteCache = /* @__PURE__ */ new Map();
+var AUTO_PREFIX = import_node_buffer34.Buffer.from("__flow_auto__:", "ascii");
+var MAX_CACHEABLE_PARTITION_BYTES = 4 * 1024;
+var MAX_CACHE_BYTES = 1 * 1024 * 1024;
+var MAX_CACHE_ENTRIES = 1024;
+var CACHE_ENTRY_OVERHEAD_BYTES = 96;
+var routeCache = /* @__PURE__ */ new Map();
+var cacheBytes = 0;
+var cacheHits = 0;
+var cacheMisses = 0;
+function flowLogicalPartitionRoutingKey(value) {
+  if (typeof value !== "string" && !import_node_buffer34.Buffer.isBuffer(value)) return void 0;
+  const autoBucket = flowAutoBucket(value);
+  if (autoBucket != null) return `{fa:${autoBucket}}`;
+  const bytes2 = import_node_buffer34.Buffer.isBuffer(value) ? value : import_node_buffer34.Buffer.from(value);
+  if (bytes2.byteLength > MAX_CACHEABLE_PARTITION_BYTES) return hashRoute(bytes2);
+  const cacheKey = bytes2.toString("base64");
+  const cached = routeCache.get(cacheKey);
+  if (cached != null) {
+    cacheHits += 1;
+    routeCache.delete(cacheKey);
+    routeCache.set(cacheKey, cached);
+    return cached.routeKey;
+  }
+  cacheMisses += 1;
+  const routeKey = hashRoute(bytes2);
+  const entryBytes = estimatedEntryBytes(cacheKey, routeKey);
+  while (routeCache.size >= MAX_CACHE_ENTRIES || routeCache.size > 0 && cacheBytes + entryBytes > MAX_CACHE_BYTES) {
+    evictOldest();
+  }
+  if (entryBytes <= MAX_CACHE_BYTES) {
+    routeCache.set(cacheKey, { bytes: entryBytes, routeKey });
+    cacheBytes += entryBytes;
+  }
+  return routeKey;
+}
+function flowAutoBucket(value) {
+  if (typeof value === "string") {
+    const match = /^__flow_auto__:(0|[1-9]\d{0,2})$/u.exec(value);
+    if (match?.[1] == null) return void 0;
+    const bucket2 = Number(match[1]);
+    return bucket2 < 256 ? bucket2 : void 0;
+  }
+  const digitCount = value.byteLength - AUTO_PREFIX.byteLength;
+  if (digitCount < 1 || digitCount > 3) return void 0;
+  for (let index = 0; index < AUTO_PREFIX.byteLength; index += 1) {
+    if (value[index] !== AUTO_PREFIX[index]) return void 0;
+  }
+  if (digitCount > 1 && value[AUTO_PREFIX.byteLength] === 48) return void 0;
+  let bucket = 0;
+  for (let index = AUTO_PREFIX.byteLength; index < value.byteLength; index += 1) {
+    const digit = value[index];
+    if (digit == null || digit < 48 || digit > 57) return void 0;
+    bucket = bucket * 10 + digit - 48;
+  }
+  return bucket < 256 ? bucket : void 0;
+}
+function hashRoute(value) {
+  const digest = (0, import_node_crypto.createHash)("sha256").update(value).digest("base64url");
+  return `{f:${digest}}`;
+}
+function estimatedEntryBytes(cacheKey, routeKey) {
+  return CACHE_ENTRY_OVERHEAD_BYTES + 2 * (cacheKey.length + routeKey.length);
+}
+function evictOldest() {
+  const oldest = routeCache.entries().next().value;
+  if (oldest == null) return;
+  routeCache.delete(oldest[0]);
+  cacheBytes -= oldest[1].bytes;
+}
+
+// src/topology-routing.ts
 function routingKeyFromProtocolPayload(name, command) {
   if (command.opcode < 256 || name === "CLUSTER.KEYSLOT" || name === "SHARDS" || name === "ROUTE") {
     return void 0;
   }
   if (isPlainObject3(command.payload)) {
-    for (const field2 of [
+    for (const field3 of [
       "key",
       "partition_key",
       "id",
@@ -8107,8 +8684,8 @@ function routingKeyFromProtocolPayload(name, command) {
       "correlation_id",
       "scope"
     ]) {
-      const value = getField(command.payload, field2);
-      if (typeof value === "string" || import_node_buffer29.Buffer.isBuffer(value)) {
+      const value = getField(command.payload, field3);
+      if (typeof value === "string" || import_node_buffer35.Buffer.isBuffer(value)) {
         return value;
       }
     }
@@ -8142,6 +8719,7 @@ function flowRoutingData(name, args) {
   if (flowScheduleCommands.has(name)) {
     return void 0;
   }
+  if (name === "FLOW.QUERY") return void 0;
   if (flowApprovalIdCommands.has(name)) {
     const id = flowArgs[0];
     return flowRoutingResult(flowLogicalPartitionRoutingKey(id));
@@ -8155,7 +8733,7 @@ function flowRoutingData(name, args) {
     if (typeof partition === "string" && partition.toUpperCase() !== "AUTO" && partition.toUpperCase() !== "MIXED") {
       return flowRoutingResult(flowLogicalPartitionRoutingKey(partition));
     }
-    if (import_node_buffer29.Buffer.isBuffer(partition)) {
+    if (import_node_buffer35.Buffer.isBuffer(partition)) {
       const text3 = partition.toString("utf8").toUpperCase();
       if (text3 !== "AUTO" && text3 !== "MIXED") {
         return flowRoutingResult(flowLogicalPartitionRoutingKey(partition));
@@ -8246,46 +8824,17 @@ function flowPartitionRoutingKeyFromCommand(command, claim) {
   return { handled: false };
 }
 function isRoutingKey(value) {
-  return typeof value === "string" || import_node_buffer29.Buffer.isBuffer(value);
-}
-function flowLogicalPartitionRoutingKey(value) {
-  if (typeof value !== "string" && !import_node_buffer29.Buffer.isBuffer(value)) {
-    return void 0;
-  }
-  const bytes2 = import_node_buffer29.Buffer.isBuffer(value) ? value : import_node_buffer29.Buffer.from(value);
-  const text3 = bytes2.toString("utf8");
-  const autoMatch = /^__flow_auto__:(0|[1-9]\d{0,2})$/u.exec(text3);
-  if (autoMatch != null) {
-    const bucket = Number(autoMatch[1]);
-    if (bucket < 256) {
-      return `{fa:${bucket}}`;
-    }
-  }
-  const cacheKey = `${import_node_buffer29.Buffer.isBuffer(value) ? "b" : "s"}:${bytes2.toString("base64")}`;
-  const cached = flowPartitionRouteCache.get(cacheKey);
-  if (cached != null) {
-    flowPartitionRouteCache.delete(cacheKey);
-    flowPartitionRouteCache.set(cacheKey, cached);
-    return cached;
-  }
-  const digest = (0, import_node_crypto.createHash)("sha256").update(bytes2).digest("base64url");
-  const routeKey = `{f:${digest}}`;
-  if (flowPartitionRouteCache.size >= FLOW_PARTITION_ROUTE_CACHE_MAX) {
-    const oldest = flowPartitionRouteCache.keys().next().value;
-    if (oldest != null) flowPartitionRouteCache.delete(oldest);
-  }
-  flowPartitionRouteCache.set(cacheKey, routeKey);
-  return routeKey;
+  return typeof value === "string" || import_node_buffer35.Buffer.isBuffer(value);
 }
 function flowAutoIdRoutingKey(value) {
-  if (typeof value !== "string" && !import_node_buffer29.Buffer.isBuffer(value)) {
+  if (typeof value !== "string" && !import_node_buffer35.Buffer.isBuffer(value)) {
     return void 0;
   }
-  const bucket = (import_node_buffer29.Buffer.isBuffer(value) ? crc32(value) : crc32Utf8(value)) & 255;
+  const bucket = (import_node_buffer35.Buffer.isBuffer(value) ? crc32(value) : crc32Utf8(value)) & 255;
   return `{fa:${bucket}}`;
 }
 function flowClaimLogicalPartitionRoutingKey(value) {
-  if (typeof value !== "string" && !import_node_buffer29.Buffer.isBuffer(value)) return void 0;
+  if (typeof value !== "string" && !import_node_buffer35.Buffer.isBuffer(value)) return void 0;
   const selector = commandPart(value);
   if (selector === "AUTO" || selector === "ANY") return void 0;
   if (selector === "GLOBAL") return "{f}";
@@ -8300,7 +8849,7 @@ function singleShardFlowClaimPartitionKey(values) {
   return keys.some((key) => key == null) ? void 0 : singleShardKey(keys);
 }
 function singleShardKey(keys) {
-  if (keys.length === 0 || keys.some((key) => typeof key !== "string" && !import_node_buffer29.Buffer.isBuffer(key))) {
+  if (keys.length === 0 || keys.some((key) => typeof key !== "string" && !import_node_buffer35.Buffer.isBuffer(key))) {
     return void 0;
   }
   const usable = keys;
@@ -8333,7 +8882,7 @@ function routedKeyGroups(keys, routeKey) {
   const groups = /* @__PURE__ */ new Map();
   for (let index = 0; index < keys.length; index += 1) {
     const key = keys[index];
-    if (typeof key !== "string" && !import_node_buffer29.Buffer.isBuffer(key)) return void 0;
+    if (typeof key !== "string" && !import_node_buffer35.Buffer.isBuffer(key)) return void 0;
     const route = routeKey(key);
     const groupKey = `${route.endpointKey}\0${route.laneId}`;
     const group = groups.get(groupKey);
@@ -9105,15 +9654,15 @@ var TopologyNativeAdapterPool = class _TopologyNativeAdapterPool {
     this.adapterOptions = {
       ...adapterOptions,
       events: [.../* @__PURE__ */ new Set([...adapterOptions.events ?? [], "TOPOLOGY_CHANGED"])],
-      onEvent: (event) => {
+      onEvent: (event2) => {
         try {
-          const callback = userOnEvent?.(event);
+          const callback = userOnEvent?.(event2);
           if (callback != null) {
             void Promise.resolve(callback).catch(() => void 0);
           }
         } catch {
         }
-        if (!this.closed && nativeEventName(event) === "TOPOLOGY_CHANGED") {
+        if (!this.closed && nativeEventName(event2) === "TOPOLOGY_CHANGED") {
           this.requestTopologyRefresh();
         }
       }
@@ -9422,7 +9971,7 @@ var TopologyNativeAdapterPool = class _TopologyNativeAdapterPool {
 };
 
 // src/response-map-preservation.ts
-var import_node_buffer31 = require("buffer");
+var import_node_buffer37 = require("buffer");
 function toStringKeyMapPreservingValues(value) {
   if (value == null) return void 0;
   const result = {};
@@ -9432,7 +9981,7 @@ function toStringKeyMapPreservingValues(value) {
     }
     return result;
   }
-  if (typeof value === "object" && !Array.isArray(value) && !import_node_buffer31.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value === "object" && !Array.isArray(value) && !import_node_buffer37.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
     for (const [key, item] of Object.entries(value)) {
       setOwnValue(result, text(key), normalizeMapStructurePreservingBytes(item));
     }
@@ -9441,7 +9990,7 @@ function toStringKeyMapPreservingValues(value) {
   return void 0;
 }
 function normalizeMapStructurePreservingBytes(value) {
-  if (import_node_buffer31.Buffer.isBuffer(value) || value instanceof Uint8Array) return value;
+  if (import_node_buffer37.Buffer.isBuffer(value) || value instanceof Uint8Array) return value;
   if (value instanceof Map) {
     const result = {};
     for (const [key, item] of value.entries()) {
@@ -9463,7 +10012,7 @@ function normalizeMapStructurePreservingBytes(value) {
 }
 
 // src/native-kv-responses.ts
-var import_node_buffer32 = require("buffer");
+var import_node_buffer38 = require("buffer");
 function rateLimitResultFromResp(value) {
   if (!Array.isArray(value) || value.length !== 4) {
     throw new TypeError("RATELIMIT.ADD returned an unexpected response");
@@ -9520,13 +10069,13 @@ function fetchOrComputeResultFromResp(value, codec) {
 }
 function decodePayload(codec, value) {
   if (value == null) return null;
-  if (import_node_buffer32.Buffer.isBuffer(value)) return codec.decode(value);
-  if (value instanceof Uint8Array) return codec.decode(import_node_buffer32.Buffer.from(value));
-  if (typeof value === "string") return codec.decode(import_node_buffer32.Buffer.from(value));
+  if (import_node_buffer38.Buffer.isBuffer(value)) return codec.decode(value);
+  if (value instanceof Uint8Array) return codec.decode(import_node_buffer38.Buffer.from(value));
+  if (typeof value === "string") return codec.decode(import_node_buffer38.Buffer.from(value));
   return normalizeRefMeta(value);
 }
 function requiredResponseString(value, context) {
-  if (typeof value !== "string" && !import_node_buffer32.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value !== "string" && !import_node_buffer38.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
     throw new TypeError(`${context} returned an unexpected response`);
   }
   const result = text(value);
@@ -9543,7 +10092,7 @@ function requiredNonNegativeInteger(value, context) {
   return result;
 }
 function responseBytes(value, context) {
-  if (typeof value !== "string" && !import_node_buffer32.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+  if (typeof value !== "string" && !import_node_buffer38.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
     throw new TypeError(`${context} returned an unexpected response`);
   }
   return bytes(value);
@@ -9866,17 +10415,6 @@ function finiteNonNegativeInteger(value, fallback) {
 function finiteNonNegativeNumber(value, fallback) {
   return value == null || !Number.isFinite(value) ? fallback : Math.max(0, value);
 }
-function appendReadOptions(args, options) {
-  append(args, "COUNT", options.count);
-  append(args, "PARTITION", options.partitionKey);
-  append(args, "FROM_MS", options.fromMs);
-  append(args, "TO_MS", options.toMs);
-  appendBool(args, "REV", options.rev);
-  append(args, "STATE", options.state);
-  appendBool(args, "TERMINAL_ONLY", options.terminalOnly);
-  appendBool(args, "INCLUDE_COLD", options.includeCold);
-  appendBool(args, "CONSISTENT_PROJECTION", options.consistentProjection);
-}
 function appendAttributeQueryOptions(args, options) {
   append(args, "STATE", options.state);
   append(args, "PARTITION", options.partitionKey);
@@ -9930,22 +10468,6 @@ function appendAttributes(args, attributes) {
     args.push("ATTRIBUTE", name, value);
   }
 }
-function appendSearchStateMeta(args, state, stateMeta) {
-  const entries = Object.entries(stateMeta ?? {});
-  if (entries.length === 0) {
-    return;
-  }
-  if (entries.every(([, value]) => isPlainObject5(value))) {
-    for (const [metaState, values] of entries) {
-      args.push("STATE_META", metaState, values);
-    }
-    return;
-  }
-  if (state == null) {
-    throw new Error("search stateMeta filters require state or nested state metadata");
-  }
-  args.push("STATE_META", state, stateMeta);
-}
 function normalizeAdminResponse(value) {
   return normalizeRefMeta(value);
 }
@@ -10253,7 +10775,7 @@ function groupAutoPartitionItems(items) {
 }
 
 // src/client-values.ts
-var import_node_buffer33 = require("buffer");
+var import_node_buffer39 = require("buffer");
 async function valueMGetEntries(client, refs, options = {}) {
   const refCount = refs.length;
   if (refCount === 0) {
@@ -10288,12 +10810,12 @@ async function valueMGetEntries(client, refs, options = {}) {
     const item = response[index];
     if (item == null) {
       entries[index] = { found: false };
-    } else if (import_node_buffer33.Buffer.isBuffer(item)) {
+    } else if (import_node_buffer39.Buffer.isBuffer(item)) {
       entries[index] = { found: true, value: client.codec.decode(item) };
     } else if (item instanceof Uint8Array) {
-      entries[index] = { found: true, value: client.codec.decode(import_node_buffer33.Buffer.from(item)) };
+      entries[index] = { found: true, value: client.codec.decode(import_node_buffer39.Buffer.from(item)) };
     } else if (typeof item === "string") {
-      entries[index] = { found: true, value: client.codec.decode(import_node_buffer33.Buffer.from(item)) };
+      entries[index] = { found: true, value: client.codec.decode(import_node_buffer39.Buffer.from(item)) };
     } else {
       entries[index] = { found: true, value: item };
     }
@@ -10302,10 +10824,10 @@ async function valueMGetEntries(client, refs, options = {}) {
 }
 
 // src/auto-batch.ts
-var import_node_buffer35 = require("buffer");
+var import_node_buffer41 = require("buffer");
 
 // src/auto-batch-ordering.ts
-var import_node_buffer34 = require("buffer");
+var import_node_buffer40 = require("buffer");
 function autoBatchOrderingPlan(batch) {
   const accesses = /* @__PURE__ */ new Map();
   const fallbackDependencies = [];
@@ -10420,13 +10942,13 @@ function flowManyAutoBatchIds(command, name) {
     return fixedFlowItemIds(
       command,
       mixed ? 4 : 3,
-      (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && isFencingToken(command[itemIndex + (mixed ? 2 : 1)]) && import_node_buffer34.Buffer.isBuffer(command[itemIndex + (mixed ? 3 : 2)])
+      (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && isFencingToken(command[itemIndex + (mixed ? 2 : 1)]) && import_node_buffer40.Buffer.isBuffer(command[itemIndex + (mixed ? 3 : 2)])
     );
   }
   return fixedFlowItemIds(
     command,
     mixed ? 4 : 3,
-    (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer34.Buffer.isBuffer(command[itemIndex + (mixed ? 2 : 1)]) && isFencingToken(command[itemIndex + (mixed ? 3 : 2)])
+    (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer40.Buffer.isBuffer(command[itemIndex + (mixed ? 2 : 1)]) && isFencingToken(command[itemIndex + (mixed ? 3 : 2)])
   );
 }
 function createManyAutoBatchIds(command) {
@@ -10439,7 +10961,7 @@ function createManyAutoBatchIds(command) {
       const ids = fixedFlowItemIds(
         command,
         width,
-        (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer34.Buffer.isBuffer(command[itemIndex + width - 1]),
+        (itemIndex) => isAutoBatchResourceValue(command[itemIndex]) && (!mixed || isAutoBatchResourceValue(command[itemIndex + 1])) && import_node_buffer40.Buffer.isBuffer(command[itemIndex + width - 1]),
         markerIndex
       );
       if (ids != null) return ids;
@@ -10457,7 +10979,7 @@ function extendedCreateManyAutoBatchIds(command, markerIndex) {
   let cursor = markerIndex + 2;
   for (let itemIndex = 0; itemIndex < itemCount; itemIndex += 1) {
     const id = command[cursor];
-    if (!isAutoBatchResourceValue(id) || !isAutoBatchResourceValue(command[cursor + 1]) || !import_node_buffer34.Buffer.isBuffer(command[cursor + 2])) return void 0;
+    if (!isAutoBatchResourceValue(id) || !isAutoBatchResourceValue(command[cursor + 1]) || !import_node_buffer40.Buffer.isBuffer(command[cursor + 2])) return void 0;
     ids.push(id);
     cursor += 3;
     const afterValues = skipExtendedNamedItems(command, cursor, true);
@@ -10476,7 +10998,7 @@ function skipExtendedNamedItems(command, countIndex, encodedValues) {
   for (let index = 0; index < count; index += 1) {
     const name = command[firstItem + index * 2];
     const value = command[firstItem + index * 2 + 1];
-    if (!isAutoBatchResourceValue(name) || (encodedValues ? !import_node_buffer34.Buffer.isBuffer(value) : !isAutoBatchResourceValue(value))) return void 0;
+    if (!isAutoBatchResourceValue(name) || (encodedValues ? !import_node_buffer40.Buffer.isBuffer(value) : !isAutoBatchResourceValue(value))) return void 0;
   }
   return firstItem + count * 2;
 }
@@ -10491,7 +11013,7 @@ function runStepsManyAutoBatchIds(command) {
         ids.push(item);
         continue;
       }
-      if (typeof item !== "object" || item == null || Array.isArray(item) || import_node_buffer34.Buffer.isBuffer(item)) return void 0;
+      if (typeof item !== "object" || item == null || Array.isArray(item) || import_node_buffer40.Buffer.isBuffer(item)) return void 0;
       const id = item.id;
       if (!isAutoBatchResourceValue(id)) return void 0;
       ids.push(id);
@@ -10532,7 +11054,7 @@ function flowValuePutOwner(command, start) {
 }
 var flowValuePutOptionTokens = /* @__PURE__ */ new Set(["NAME", "NOW", "OVERRIDE", "OWNER_FLOW_ID", "PARTITION", "TTL", "TTL_MS"]);
 function isAutoBatchResourceValue(value) {
-  return typeof value === "string" || import_node_buffer34.Buffer.isBuffer(value);
+  return typeof value === "string" || import_node_buffer40.Buffer.isBuffer(value);
 }
 function isFencingToken(value) {
   return typeof value === "number" && Number.isSafeInteger(value) || typeof value === "bigint";
@@ -10541,7 +11063,7 @@ function nonNegativeItemCount(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
 }
 function autoBatchResourceKey(namespace, value) {
-  return `${namespace}:${import_node_buffer34.Buffer.from(value).toString("base64")}`;
+  return `${namespace}:${import_node_buffer40.Buffer.from(value).toString("base64")}`;
 }
 function autoBatchCommandName(command) {
   return commandView(command).name ?? null;
@@ -10917,7 +11439,7 @@ async function hydrateClaimedRecords(claimed, concurrency, hydrate) {
   const results = new Array(claimed.length);
   let cursor = 0;
   let failure;
-  const run = async () => {
+  const run2 = async () => {
     while (failure == null) {
       const index = cursor;
       cursor += 1;
@@ -10930,7 +11452,7 @@ async function hydrateClaimedRecords(claimed, concurrency, hydrate) {
       }
     }
   };
-  await Promise.all(Array.from({ length: Math.min(concurrency, claimed.length) }, run));
+  await Promise.all(Array.from({ length: Math.min(concurrency, claimed.length) }, run2));
   if (failure != null) {
     const hydratedItems = [];
     for (let index = 0; index < results.length; index += 1) {
@@ -10950,71 +11472,1039 @@ function claimFailure(error) {
 }
 
 // src/client-flow-support.ts
-var import_node_buffer42 = require("buffer");
+var import_node_buffer52 = require("buffer");
 
-// src/client-core.ts
-var import_node_buffer40 = require("buffer");
+// src/flow-query-builder.ts
+var import_node_buffer43 = require("buffer");
 
-// src/client-core-helpers.ts
-var import_node_buffer36 = require("buffer");
-function bgsaveResponse(response) {
-  if ((typeof response === "string" || import_node_buffer36.Buffer.isBuffer(response) || response instanceof Uint8Array) && text(response) === "Background saving started") {
-    return true;
+// src/flow-query-metadata.ts
+var import_node_buffer42 = require("buffer");
+var MAX_FLOW_QUERY_METADATA_KEY_BYTES = 64;
+function normalizeStateMeta(value, state) {
+  if (value == null) return {};
+  const entries = objectEntries(value, "stateMeta");
+  if (entries.length === 0) return {};
+  const nested = entries.map(([, item]) => isPlainRecord(item));
+  if (nested.every(Boolean)) {
+    return value;
   }
-  return okResponse(response);
-}
-function clientNameResponse(response) {
-  return response == null ? null : textResponse(response, "CLIENT GETNAME");
-}
-function fetchOrComputeCompletionToken(options) {
-  if (options == null || !Object.hasOwn(options, "computeToken") || options.computeToken === void 0) {
+  if (nested.some(Boolean)) {
     throw new TypeError(
-      "fetch-or-compute completion requires computeToken"
+      "stateMeta must be entirely flat or entirely nested by state"
     );
   }
-  if (!import_node_buffer36.Buffer.isBuffer(options.computeToken)) {
-    throw new TypeError("fetch-or-compute computeToken must be a Buffer");
+  if (state == null || state === "" || state === "any") {
+    throw new TypeError(
+      "FLOW.QUERY stateMeta filters require state; a concrete state is required"
+    );
   }
-  return options.computeToken;
+  return { [state]: value };
 }
-function concatCommandArgs(prefix, suffix) {
-  const args = new Array(prefix.length + suffix.length);
-  for (let index = 0; index < prefix.length; index += 1) args[index] = prefix[index];
-  for (let index = 0; index < suffix.length; index += 1) {
-    args[prefix.length + index] = suffix[index];
+function metadataEntries(value, context) {
+  const entries = objectEntries(value ?? {}, context).map(([rawName, item]) => {
+    const name = rawName.trim();
+    const size = import_node_buffer42.Buffer.byteLength(name, "utf8");
+    if (size === 0 || size > MAX_FLOW_QUERY_METADATA_KEY_BYTES || name.startsWith("__")) {
+      throw new TypeError(`${context} key is invalid or reserved`);
+    }
+    return [name, item];
+  });
+  entries.sort(([left], [right]) => compareUnicodeScalars(left, right));
+  for (let index = 1; index < entries.length; index += 1) {
+    if (entries[index - 1]?.[0] === entries[index]?.[0]) {
+      throw new TypeError(`${context} key is duplicated after normalization`);
+    }
   }
-  return args;
+  return entries;
 }
-function unsupportedClientTracking() {
-  throw new InvalidCommandError(
-    "CLIENT TRACKING is not supported by the FerricStore native protocol; use native event subscriptions"
-  );
+function objectEntries(value, context) {
+  if (!isPlainRecord(value))
+    throw new TypeError(`${context} must be a plain object`);
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== "string")) {
+    throw new TypeError(`${context} keys must be strings`);
+  }
+  return keys.map((key) => [key, value[key]]);
 }
-function unsupportedClientCaching() {
-  throw new InvalidCommandError("CLIENT CACHING is not supported by the FerricStore native protocol");
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer42.Buffer.isBuffer(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype;
 }
-
-// src/client-base.ts
-var import_node_buffer38 = require("buffer");
-
-// src/client-executor.ts
-var import_node_buffer37 = require("buffer");
-var ErrorMappingExecutor = class {
-  constructor(executor) {
-    this.executor = executor;
+function metadataSelector(root, ...names) {
+  return root + names.map((name) => `['${name.replaceAll("'", "''")}']`).join("");
+}
+function compareUnicodeScalars(left, right) {
+  let leftOffset = 0;
+  let rightOffset = 0;
+  while (leftOffset < left.length && rightOffset < right.length) {
+    const leftCodePoint = left.codePointAt(leftOffset);
+    const rightCodePoint = right.codePointAt(rightOffset);
+    if (leftCodePoint == null || rightCodePoint == null) break;
+    if (leftCodePoint !== rightCodePoint)
+      return leftCodePoint < rightCodePoint ? -1 : 1;
+    leftOffset += leftCodePoint > 65535 ? 2 : 1;
+    rightOffset += rightCodePoint > 65535 ? 2 : 1;
   }
-  executor;
-  async executeCommand(...args) {
-    return await this.executeCommandArgs(args);
+  return left.length === right.length ? 0 : leftOffset === left.length ? -1 : 1;
+}
+
+// src/flow-query-builder.ts
+var MAX_FLOW_QUERY_RESULTS = 100;
+var MAX_FLOW_QUERY_PARTITION_BYTES = 65535;
+var MAX_FLOW_QUERY_TIME = Number.MAX_SAFE_INTEGER;
+var MAX_FLOW_QUERY_STATE_BYTES = 64;
+var FlowCollectionQuery = class {
+  constructor(partitionKey, limit, reverse) {
+    this.limit = limit;
+    this.reverse = reverse;
+    this.params.partition_key = partitionKey;
   }
-  async executeCommandArgs(args) {
-    try {
-      return await executeCommandArgs(this.executor, args);
-    } catch (error) {
-      throwMapped(error);
+  limit;
+  reverse;
+  params = /* @__PURE__ */ Object.create(null);
+  predicates = ["partition_key = @partition_key"];
+  orderField = "updated_at_ms";
+  equality(selector, parameter, value) {
+    this.params[parameter] = queryParameter(value, parameter);
+    this.predicates.push(`${selector} = @${parameter}`);
+  }
+  window(fromMs, toMs) {
+    if (fromMs == null && toMs == null) return;
+    const lower = fromMs == null ? 0 : boundedTime(fromMs, "fromMs");
+    const upper = toMs == null ? MAX_FLOW_QUERY_TIME : boundedTime(toMs, "toMs");
+    if (lower > upper) throw new TypeError("fromMs must not exceed toMs");
+    this.predicates.push("updated_at_ms BETWEEN @from_ms AND @to_ms");
+    this.params.from_ms = lower;
+    this.params.to_ms = upper;
+  }
+  metadata(root, values) {
+    const entries = metadataEntries(values, root);
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index];
+      if (entry == null) throw new TypeError("metadata entries must be dense");
+      this.equality(
+        metadataSelector(root, entry[0]),
+        `${root}_${index}`,
+        entry[1]
+      );
     }
   }
-  async executePipeline(commands, options) {
+  stateMetadata(values) {
+    const entries = [];
+    const states = /* @__PURE__ */ new Set();
+    for (const [rawState, metadata] of objectEntries(values, "stateMeta")) {
+      const state = requiredText(rawState, "stateMeta state").trim();
+      const stateBytes = import_node_buffer43.Buffer.byteLength(state, "utf8");
+      if (stateBytes === 0 || stateBytes > MAX_FLOW_QUERY_STATE_BYTES) {
+        throw new TypeError(
+          `stateMeta state names must be 1..${MAX_FLOW_QUERY_STATE_BYTES} bytes`
+        );
+      }
+      if (states.has(state)) {
+        throw new TypeError(
+          "stateMeta state is duplicated after normalization"
+        );
+      }
+      states.add(state);
+      if (!isPlainRecord(metadata))
+        throw new TypeError("stateMeta values must be metadata maps");
+      for (const [name, value] of metadataEntries(metadata, "stateMeta")) {
+        entries.push([state, name, value]);
+      }
+    }
+    entries.sort(
+      ([leftState, leftName], [rightState, rightName]) => compareUnicodeScalars(leftState, rightState) || compareUnicodeScalars(leftName, rightName)
+    );
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index];
+      if (entry == null) throw new TypeError("stateMeta entries must be dense");
+      this.equality(
+        metadataSelector("state_meta", entry[0], entry[1]),
+        `state_meta_${index}`,
+        entry[2]
+      );
+    }
+  }
+  build() {
+    if (this.predicates.length > 12) {
+      throw new TypeError("FLOW.QUERY accepts at most 12 predicates");
+    }
+    const direction = this.reverse ? "DESC" : "ASC";
+    const query = `FROM runs WHERE ${this.predicates.join(" AND ")} ORDER BY ${this.orderField} ${direction} LIMIT ${this.limit} RETURN RECORDS`;
+    validateFlowQueryText(query);
+    return { query, params: this.params };
+  }
+};
+function buildFlowListQuery(type, options) {
+  const attributeCount = Object.keys(options.attributes ?? {}).length;
+  if (type === "any" && attributeCount === 0) {
+    throw new TypeError(
+      "FLOW.QUERY list requires a concrete flow type or an attribute predicate"
+    );
+  }
+  if (options.terminalOnly !== true && options.state === "any" && attributeCount === 0) {
+    throw new TypeError(
+      "FLOW.QUERY list state any requires an attribute predicate"
+    );
+  }
+  const builder = queryBuilder(options);
+  addType(builder, type);
+  if (options.terminalOnly === true) {
+    addTerminalState(builder, options.state);
+  } else if (options.state == null || options.state === "") {
+    builder.equality("state", "state", "queued");
+  } else if (options.state !== "any") {
+    builder.equality("state", "state", requiredText(options.state, "state"));
+  }
+  builder.metadata("attribute", options.attributes);
+  builder.window(options.fromMs, options.toMs);
+  return builder.build();
+}
+function buildFlowSearchQuery(type, options) {
+  const stateMeta = normalizeStateMeta(options.stateMeta, options.state);
+  if (Object.keys(options.attributes ?? {}).length === 0 && Object.keys(stateMeta).length === 0) {
+    throw new TypeError(
+      "FLOW.QUERY search requires an attribute or stateMeta predicate"
+    );
+  }
+  if ((type === "" || type === "any") && Object.keys(stateMeta).length > 0) {
+    throw new TypeError(
+      "FLOW.QUERY stateMeta predicates require a concrete flow type"
+    );
+  }
+  const builder = queryBuilder(options);
+  if (type !== "" && type !== "any")
+    builder.equality("type", "type", requiredText(type, "type"));
+  if (options.terminalOnly === true) {
+    addTerminalState(builder, options.state);
+  } else if (options.state != null && options.state !== "" && options.state !== "any") {
+    builder.equality("state", "state", requiredText(options.state, "state"));
+  }
+  builder.metadata("attribute", options.attributes);
+  builder.stateMetadata(stateMeta);
+  builder.window(options.fromMs, options.toMs);
+  return builder.build();
+}
+function buildFlowTerminalQuery(type, options) {
+  if (requiredText(type, "type") === "any") {
+    throw new TypeError("FLOW.QUERY terminals require a concrete flow type");
+  }
+  if (metadataEntries(options.attributes, "attribute").length > 0) {
+    throw new TypeError(
+      "FLOW.QUERY terminals do not support attribute predicates"
+    );
+  }
+  const builder = queryBuilder(options);
+  addType(builder, type);
+  addTerminalState(builder, options.state);
+  builder.window(options.fromMs, options.toMs);
+  return builder.build();
+}
+function buildFlowFailureQuery(type, options) {
+  if (options.state != null && options.state !== "" && options.state !== "any" && options.state !== "failed") {
+    throw new TypeError("FLOW failures state must be failed or any");
+  }
+  return buildFlowListQuery(type, {
+    ...options,
+    state: "failed",
+    terminalOnly: false
+  });
+}
+function buildFlowLineageQuery(selector, id, options) {
+  if (options.terminalOnly === true) {
+    throw new TypeError("terminalOnly cannot be combined with a lineage query");
+  }
+  if (metadataEntries(options.attributes, "attribute").length > 0) {
+    throw new TypeError(
+      "FLOW.QUERY lineage does not support attribute predicates"
+    );
+  }
+  const builder = queryBuilder(options);
+  builder.equality(selector, "lineage_id", requiredText(id, "lineage id"));
+  if (options.state != null && options.state !== "" && options.state !== "any") {
+    builder.equality("state", "state", requiredText(options.state, "state"));
+  }
+  builder.metadata("attribute", options.attributes);
+  builder.window(options.fromMs, options.toMs);
+  return builder.build();
+}
+function buildFlowStuckQuery(type, options) {
+  const concreteType = requiredText(type, "type");
+  if (concreteType === "any") {
+    throw new TypeError("FLOW.QUERY stuck requires a concrete flow type");
+  }
+  const now = options.nowMs == null ? Date.now() : boundedTime(options.nowMs, "nowMs");
+  const older = options.olderThanMs == null ? 0 : boundedTime(options.olderThanMs, "olderThanMs");
+  const cutoff = now - older;
+  if (cutoff < 0) throw new TypeError("olderThanMs must not exceed nowMs");
+  const builder = new FlowCollectionQuery(
+    requiredPartition(options.partitionKey),
+    boundedCount(options.count),
+    false
+  );
+  builder.orderField = "lease_deadline_ms";
+  builder.equality("type", "type", concreteType);
+  builder.equality("state", "state", "running");
+  builder.predicates.push(
+    "lease_deadline_ms BETWEEN @lease_from_ms AND @lease_to_ms"
+  );
+  builder.params.lease_from_ms = 0;
+  builder.params.lease_to_ms = cutoff;
+  return builder.build();
+}
+function queryBuilder(options) {
+  if (options.includeCold === true)
+    throw new TypeError("FLOW.QUERY does not expose includeCold");
+  if (options.consistentProjection === true) {
+    throw new TypeError("FLOW.QUERY does not expose consistentProjection");
+  }
+  if (options.rev != null && typeof options.rev !== "boolean") {
+    throw new TypeError("rev must be boolean");
+  }
+  return new FlowCollectionQuery(
+    requiredPartition(options.partitionKey),
+    boundedCount(options.count),
+    options.rev !== false
+  );
+}
+function requiredPartition(value) {
+  if (typeof value !== "string") {
+    throw new TypeError(
+      "FLOW.QUERY convenience methods require a partition key"
+    );
+  }
+  const size = import_node_buffer43.Buffer.byteLength(value, "utf8");
+  if (size === 0 || size > MAX_FLOW_QUERY_PARTITION_BYTES) {
+    throw new TypeError(
+      `FLOW.QUERY partition key must be 1..${MAX_FLOW_QUERY_PARTITION_BYTES} bytes`
+    );
+  }
+  return value;
+}
+function boundedCount(value) {
+  if (value == null) return MAX_FLOW_QUERY_RESULTS;
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_FLOW_QUERY_RESULTS) {
+    throw new TypeError(
+      `FLOW.QUERY limit must be between 1 and ${MAX_FLOW_QUERY_RESULTS}`
+    );
+  }
+  return value;
+}
+function boundedTime(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > MAX_FLOW_QUERY_TIME) {
+    throw new TypeError(`${name} must be a non-negative safe integer`);
+  }
+  return value;
+}
+function addType(builder, type) {
+  const normalized = requiredText(type, "type");
+  if (normalized !== "any") builder.equality("type", "type", normalized);
+}
+function addTerminalState(builder, state) {
+  if (state == null || state === "" || state === "any") {
+    builder.predicates.push("state IN (@terminal_0, @terminal_1, @terminal_2)");
+    builder.params.terminal_0 = "completed";
+    builder.params.terminal_1 = "failed";
+    builder.params.terminal_2 = "cancelled";
+  } else if (state === "completed" || state === "failed" || state === "cancelled") {
+    builder.equality("state", "state", state);
+  } else {
+    throw new TypeError(
+      "terminal state must be completed, failed, cancelled, or any"
+    );
+  }
+}
+function requiredText(value, context) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${context} must be non-empty text`);
+  }
+  return value;
+}
+function queryParameter(value, context) {
+  if (typeof value === "string" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "number" || import_node_buffer43.Buffer.isBuffer(value)) {
+    return value;
+  }
+  throw new TypeError(`${context} must be a scalar FLOW.QUERY parameter`);
+}
+
+// src/flow-query-response.ts
+var import_node_buffer45 = require("buffer");
+
+// src/flow-query-response-validation.ts
+var import_node_buffer44 = require("buffer");
+function requiredMap2(value, context) {
+  if (value instanceof Map) return value;
+  if (typeof value !== "object" || value == null || Array.isArray(value) || import_node_buffer44.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    throw decodeError(`${context} must be a map`, value);
+  }
+  return value;
+}
+function freezeMap(value) {
+  const output = /* @__PURE__ */ Object.create(null);
+  const entries = value instanceof Map ? value.entries() : Object.entries(value);
+  for (const [rawKey, item] of entries) {
+    const key = strictText2(rawKey);
+    if (key == null || Object.hasOwn(output, key)) {
+      throw decodeError(
+        "server response map contains an invalid or duplicate key",
+        value
+      );
+    }
+    output[key] = item;
+  }
+  return Object.freeze(output);
+}
+function freezeMetadataMap(value, context) {
+  return normalizeMetadataMap(
+    value,
+    context,
+    { remaining: DEFAULT_MAX_VALUE_ITEMS },
+    /* @__PURE__ */ new Set(),
+    0
+  );
+}
+function normalizeMetadataMap(value, context, budget, ancestors, depth) {
+  enterMetadataContainer(value, context, budget, ancestors, depth);
+  try {
+    const output = /* @__PURE__ */ Object.create(null);
+    const entries = value instanceof Map ? value.entries() : Object.entries(value);
+    for (const [rawKey, item] of entries) {
+      const key = strictText2(rawKey);
+      if (key == null || Object.hasOwn(output, key)) {
+        throw decodeError(`${context} contains an invalid or duplicate key`, value);
+      }
+      output[key] = normalizeMetadataValue(
+        item,
+        `${context}.${key}`,
+        budget,
+        ancestors,
+        depth + 1
+      );
+    }
+    return Object.freeze(output);
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function normalizeMetadataValue(value, context, budget, ancestors, depth) {
+  if (typeof value === "string") {
+    if (!value.isWellFormed()) throw decodeError(`${context} contains invalid text`, value);
+    return value;
+  }
+  if (import_node_buffer44.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    const decoded = strictText2(value);
+    if (decoded == null) throw decodeError(`${context} contains invalid UTF-8`, value);
+    return decoded;
+  }
+  if (value == null || typeof value === "boolean" || typeof value === "number" || typeof value === "bigint") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    enterMetadataContainer(value, context, budget, ancestors, depth);
+    try {
+      const output = new Array(value.length);
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) {
+          throw decodeError(`${context} must be a dense array`, value);
+        }
+        output[index] = normalizeMetadataValue(
+          value[index],
+          `${context}[${index}]`,
+          budget,
+          ancestors,
+          depth + 1
+        );
+      }
+      return Object.freeze(output);
+    } finally {
+      ancestors.delete(value);
+    }
+  }
+  if (value instanceof Map) {
+    return normalizeMetadataMap(value, context, budget, ancestors, depth);
+  }
+  if (isPlainObject6(value)) {
+    return normalizeMetadataMap(value, context, budget, ancestors, depth);
+  }
+  throw decodeError(`${context} contains an unsupported value`, value);
+}
+function enterMetadataContainer(value, context, budget, ancestors, depth) {
+  if (depth >= DEFAULT_MAX_VALUE_DEPTH) {
+    throw decodeError(`${context} exceeds the maximum metadata depth`, value);
+  }
+  if (ancestors.has(value)) throw decodeError(`${context} contains a cycle`, value);
+  const size = Array.isArray(value) ? value.length : value instanceof Map ? value.size : Object.keys(value).length;
+  if (size > budget.remaining) {
+    throw decodeError(`${context} exceeds the maximum metadata items`, value);
+  }
+  budget.remaining -= size;
+  ancestors.add(value);
+}
+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);
+  if (actual !== expected) {
+    throw decodeError(
+      `${context} has unsupported contract ${JSON.stringify(actual)}`,
+      mapping
+    );
+  }
+}
+function requiredText2(mapping, name, context) {
+  const value = strictText2(field(mapping, name));
+  if (value == null || value.length === 0) {
+    throw decodeError(`${context} ${name} must be non-empty text`, mapping);
+  }
+  return value;
+}
+function optionalText2(mapping, name, context) {
+  const raw = field(mapping, name);
+  if (raw == null) return void 0;
+  const value = strictText2(raw);
+  if (value == null)
+    throw decodeError(`${context} ${name} must be text`, mapping);
+  return value;
+}
+function requiredBoundedText2(mapping, name, context, maximumBytes) {
+  const value = requiredText2(mapping, name, context);
+  if (import_node_buffer44.Buffer.byteLength(value, "utf8") > maximumBytes) {
+    throw decodeError(
+      `${context} ${name} exceeds ${maximumBytes} bytes`,
+      mapping
+    );
+  }
+  return value;
+}
+function boundedText(value, context, maximumBytes) {
+  const decoded = strictText2(value);
+  if (decoded == null || decoded.length === 0) {
+    throw decodeError(`${context} must be non-empty text`, value);
+  }
+  if (import_node_buffer44.Buffer.byteLength(decoded, "utf8") > maximumBytes) {
+    throw decodeError(`${context} exceeds ${maximumBytes} bytes`, value);
+  }
+  return decoded;
+}
+function requiredBoolean(mapping, name, context) {
+  const value = field(mapping, name);
+  if (typeof value !== "boolean") {
+    throw decodeError(`${context} ${name} must be boolean`, mapping);
+  }
+  return value;
+}
+function nonNegativeInteger(value, context) {
+  if (typeof value === "bigint") {
+    if (value >= 0n && value <= BigInt(Number.MAX_SAFE_INTEGER))
+      return Number(value);
+  } else if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+    return value;
+  }
+  throw decodeError(`${context} must be a non-negative safe integer`, value);
+}
+function positiveInteger(value, context) {
+  const parsed = nonNegativeInteger(value, context);
+  if (parsed === 0) throw decodeError(`${context} must be positive`, value);
+  return parsed;
+}
+function boundedInteger(value, maximum, context) {
+  let parsed;
+  if (typeof value === "bigint") {
+    parsed = value;
+  } else if (typeof value === "number" && Number.isSafeInteger(value)) {
+    parsed = BigInt(value);
+  } else {
+    throw decodeError(
+      `${context} must be a lossless non-negative integer`,
+      value
+    );
+  }
+  if (parsed < 0n || parsed > maximum) {
+    throw decodeError(
+      `${context} is outside its supported integer range`,
+      value
+    );
+  }
+  return parsed <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(parsed) : parsed;
+}
+function positiveBoundedInteger(value, maximum, context) {
+  const parsed = boundedInteger(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 = import_node_buffer44.Buffer.from(name);
+  for (const key of mapping.keys()) {
+    if (import_node_buffer44.Buffer.isBuffer(key) && key.equals(binaryName)) return true;
+    if (key instanceof Uint8Array && import_node_buffer44.Buffer.from(key).equals(binaryName))
+      return true;
+  }
+  return false;
+}
+function decodeError(message, raw) {
+  return new FerricStoreError(`invalid server response: ${message}`, { raw });
+}
+function strictText2(value) {
+  if (typeof value === "string")
+    return value.isWellFormed() ? value : void 0;
+  if (import_node_buffer44.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(value);
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+
+// src/flow-query-types.ts
+var FlowQueryError = class extends FerricStoreError {
+  code;
+  detail;
+  hint;
+  position;
+  context;
+  constructor(options) {
+    super(options.message, {
+      cause: options.cause,
+      raw: options.raw,
+      retryable: options.retryable,
+      safeToRetry: options.safeToRetry,
+      retryAfterMs: options.retryAfterMs
+    });
+    this.code = options.code;
+    this.detail = options.detail;
+    this.hint = options.hint;
+    this.position = options.position;
+    this.context = options.context;
+  }
+};
+
+// src/flow-query-response.ts
+var FLOW_QUERY_RESULT_CONTRACT = "ferric.flow.query.result/v1";
+var FLOW_EXPLAIN_CONTRACT = "ferric.flow.explain/v1";
+var FLOW_QUERY_INDEXES_CONTRACT = "ferric.flow.query.indexes/v1";
+var USAGE_FIELDS2 = [
+  ["range_seeks", "rangeSeeks"],
+  ["range_pages", "rangePages"],
+  ["scanned_entries", "scannedEntries"],
+  ["scanned_bytes", "scannedBytes"],
+  ["hydrated_records", "hydratedRecords"],
+  ["residual_checks", "residualChecks"],
+  ["duplicate_entries", "duplicateEntries"],
+  ["result_records", "resultRecords"],
+  ["response_bytes", "responseBytes"],
+  ["memory_high_water_bytes", "memoryHighWaterBytes"],
+  ["wall_time_us", "wallTimeUs"]
+];
+var MAX_SIGNED_64 = (1n << 63n) - 1n;
+var MAX_UNSIGNED_64 = (1n << 64n) - 1n;
+function decodeFlowQueryResult(value) {
+  const result = decodeFlowQueryResponse(value, (mapping) => freezeMap(mapping));
+  if (result.kind === "records") {
+    return Object.freeze({
+      kind: "records",
+      version: FLOW_QUERY_RESULT_CONTRACT,
+      records: Object.freeze(result.records),
+      page: result.page,
+      quality: result.quality,
+      usage: result.usage,
+      raw: result.raw
+    });
+  }
+  return Object.freeze({
+    kind: "count",
+    version: FLOW_QUERY_RESULT_CONTRACT,
+    count: result.count,
+    quality: result.quality,
+    usage: result.usage,
+    raw: result.raw
+  });
+}
+function decodeFlowQueryRecords(value, decodeRecord) {
+  const result = decodeFlowQueryResponse(
+    value,
+    (mapping, index) => decodeRecord(mapping instanceof Map ? freezeMap(mapping) : mapping, index)
+  );
+  if (result.kind === "count") {
+    throw new FerricStoreError("Flow record convenience query returned a count result", {
+      raw: result.raw
+    });
+  }
+  return result.records;
+}
+function decodeFlowQueryResponse(value, decodeRecord) {
+  const mapping = requiredMap2(value, "FLOW.QUERY result");
+  requireContract(mapping, "version", FLOW_QUERY_RESULT_CONTRACT, "FLOW.QUERY result");
+  const quality = decodeQuality(field(mapping, "quality"));
+  const usage = decodeUsage(field(mapping, "usage"));
+  const hasRecords = hasKey(mapping, "records");
+  const hasCount = hasKey(mapping, "result");
+  if (hasRecords === hasCount) {
+    throw decodeError("FLOW.QUERY result must contain exactly one records or count shape", value);
+  }
+  const raw = freezeMap(mapping);
+  if (hasRecords) {
+    const rawRecords = field(mapping, "records");
+    if (!Array.isArray(rawRecords) || rawRecords.length > 100) {
+      throw decodeError("FLOW.QUERY records must be an array of at most 100 maps", value);
+    }
+    const records = new Array(rawRecords.length);
+    for (let index = 0; index < rawRecords.length; index += 1) {
+      if (!Object.hasOwn(rawRecords, index)) {
+        throw decodeError("FLOW.QUERY records must be a dense array", value);
+      }
+      records[index] = decodeRecord(
+        requiredMap2(rawRecords[index], `FLOW.QUERY record ${index}`),
+        index
+      );
+    }
+    if (usage.resultRecords !== records.length) {
+      throw decodeError("FLOW.QUERY usage result_records does not match records", value);
+    }
+    return {
+      kind: "records",
+      records,
+      page: decodePage(field(mapping, "page")),
+      quality,
+      usage,
+      raw
+    };
+  }
+  if (hasKey(mapping, "page")) {
+    throw decodeError("FLOW.QUERY count result contains an unexpected page", value);
+  }
+  const countResult = requiredMap2(field(mapping, "result"), "FLOW.QUERY count result");
+  if (requiredText2(countResult, "kind", "FLOW.QUERY count result") !== "count") {
+    throw decodeError("FLOW.QUERY count result kind must be count", value);
+  }
+  const count = boundedInteger(
+    field(countResult, "value"),
+    MAX_SIGNED_64,
+    "FLOW.QUERY count value"
+  );
+  if (usage.resultRecords !== 1) {
+    throw decodeError("FLOW.QUERY count usage result_records must be 1", value);
+  }
+  return {
+    kind: "count",
+    count,
+    quality,
+    usage,
+    raw
+  };
+}
+function decodeFlowExplainResult(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY explain");
+  requireContract(mapping, "version", FLOW_EXPLAIN_CONTRACT, "FLOW.QUERY explain");
+  const queryFingerprint = requiredText2(mapping, "query_fingerprint", "FLOW.QUERY explain");
+  if (!/^[0-9a-f]{64}$/iu.test(queryFingerprint)) {
+    throw decodeError("FLOW.QUERY explain query_fingerprint is invalid", value);
+  }
+  const status = requiredText2(mapping, "status", "FLOW.QUERY explain");
+  if (status !== "planned" && status !== "rejected" && status !== "executed") {
+    throw decodeError(`FLOW.QUERY explain status ${JSON.stringify(status)} is unsupported`, value);
+  }
+  const plan = freezeMetadataMap(
+    requiredMap2(field(mapping, "plan"), "FLOW.QUERY explain plan"),
+    "FLOW.QUERY explain plan"
+  );
+  const estimate = freezeMetadataMap(
+    requiredMap2(field(mapping, "estimate"), "FLOW.QUERY explain estimate"),
+    "FLOW.QUERY explain estimate"
+  );
+  const bounds = freezeMetadataMap(
+    requiredMap2(field(mapping, "bounds"), "FLOW.QUERY explain bounds"),
+    "FLOW.QUERY explain bounds"
+  );
+  const actualValue = field(mapping, "actual");
+  let actual;
+  if (status === "executed") {
+    if (actualValue == null) {
+      throw decodeError("FLOW.QUERY executed explain is missing actual usage", value);
+    }
+    actual = decodeUsage(actualValue);
+  } else if (actualValue != null) {
+    throw decodeError("FLOW.QUERY non-executed explain contains actual usage", value);
+  }
+  const diagnosticValue = field(mapping, "diagnostic");
+  let diagnostic;
+  if (status === "rejected") {
+    diagnostic = tryDecodeFlowQueryError(diagnosticValue);
+    if (diagnostic == null) {
+      throw decodeError("FLOW.QUERY rejected explain has an invalid diagnostic", value);
+    }
+  } else if (diagnosticValue != null) {
+    throw decodeError("FLOW.QUERY non-rejected explain contains a diagnostic", value);
+  }
+  return Object.freeze({
+    version: FLOW_EXPLAIN_CONTRACT,
+    queryFingerprint,
+    status,
+    plan,
+    estimate,
+    bounds,
+    actual,
+    diagnostic,
+    raw: freezeMap(mapping)
+  });
+}
+function tryDecodeFlowQueryError(value, cause) {
+  try {
+    const mapping = requiredMap2(value, "FLOW.QUERY diagnostic");
+    const contextValue = field(mapping, "context");
+    const context = contextValue == null ? void 0 : freezeMetadataMap(
+      requiredMap2(contextValue, "FLOW.QUERY diagnostic context"),
+      "FLOW.QUERY diagnostic context"
+    );
+    const 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;
+  }
+}
+function decodeFlowQueryIndexStatus(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY.INDEXES");
+  requireContract(
+    mapping,
+    "contract_version",
+    FLOW_QUERY_INDEXES_CONTRACT,
+    "FLOW.QUERY.INDEXES"
+  );
+  const registry = requiredMap2(field(mapping, "registry"), "FLOW.QUERY.INDEXES registry");
+  const services = freezeMetadataMap(
+    requiredMap2(field(mapping, "services"), "FLOW.QUERY.INDEXES services"),
+    "FLOW.QUERY.INDEXES services"
+  );
+  const rawIndexes = field(mapping, "indexes");
+  if (!Array.isArray(rawIndexes) || rawIndexes.length > 32) {
+    throw decodeError("FLOW.QUERY.INDEXES indexes must contain at most 32 entries", value);
+  }
+  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);
+    }
+    indexes[index] = decodeIndex(rawIndexes[index], index);
+  }
+  return Object.freeze({
+    contractVersion: FLOW_QUERY_INDEXES_CONTRACT,
+    observedAtMs: nonNegativeInteger(
+      field(mapping, "observed_at_ms"),
+      "FLOW.QUERY.INDEXES observed_at_ms"
+    ),
+    statisticsMaxAgeMs: nonNegativeInteger(
+      field(mapping, "statistics_max_age_ms"),
+      "FLOW.QUERY.INDEXES statistics_max_age_ms"
+    ),
+    registry: Object.freeze({
+      epoch: boundedInteger(
+        field(registry, "epoch"),
+        MAX_UNSIGNED_64,
+        "FLOW.QUERY.INDEXES epoch"
+      ),
+      catalogVersion: positiveBoundedInteger(
+        field(registry, "catalog_version"),
+        MAX_UNSIGNED_64,
+        "FLOW.QUERY.INDEXES catalog_version"
+      )
+    }),
+    services,
+    indexes: Object.freeze(indexes),
+    raw: freezeMap(mapping)
+  });
+}
+function decodeIndex(value, index) {
+  const mapping = requiredMap2(value, `FLOW.QUERY.INDEXES index ${index}`);
+  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)
+  });
+}
+function decodeCoveringFields(mapping) {
+  const raw = field(mapping, "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(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);
+  }
+  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)
+  });
+}
+function decodeQuality(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY quality");
+  return Object.freeze({
+    exactness: requiredBoundedText2(mapping, "exactness", "FLOW.QUERY quality", 64),
+    freshness: requiredBoundedText2(mapping, "freshness", "FLOW.QUERY quality", 64),
+    coverage: requiredBoundedText2(mapping, "coverage", "FLOW.QUERY quality", 64),
+    pagination: requiredBoundedText2(mapping, "pagination", "FLOW.QUERY quality", 64)
+  });
+}
+function decodeUsage(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY usage");
+  const usage = /* @__PURE__ */ Object.create(null);
+  for (const [wireName, property] of USAGE_FIELDS2) {
+    usage[property] = nonNegativeInteger(
+      field(mapping, wireName),
+      `FLOW.QUERY usage ${wireName}`
+    );
+  }
+  return Object.freeze(usage);
+}
+function decodePage(value) {
+  const mapping = requiredMap2(value, "FLOW.QUERY page");
+  const hasMore = requiredBoolean(mapping, "has_more", "FLOW.QUERY page");
+  const cursor = optionalText2(mapping, "cursor", "FLOW.QUERY page");
+  if (cursor != null && (!cursor.startsWith("fqc1_") || import_node_buffer45.Buffer.byteLength(cursor) > 4096)) {
+    throw decodeError("FLOW.QUERY page cursor is invalid", value);
+  }
+  if (hasMore !== (cursor != null)) {
+    throw decodeError("FLOW.QUERY page has_more and cursor are inconsistent", value);
+  }
+  return Object.freeze({ hasMore, ...cursor == null ? {} : { cursor } });
+}
+function decodePosition(value) {
+  if (value == null) return void 0;
+  const mapping = requiredMap2(value, "FLOW.QUERY diagnostic position");
+  return Object.freeze({
+    byte: positiveInteger(field(mapping, "byte"), "FLOW.QUERY diagnostic position byte"),
+    line: positiveInteger(field(mapping, "line"), "FLOW.QUERY diagnostic position line"),
+    column: positiveInteger(
+      field(mapping, "column"),
+      "FLOW.QUERY diagnostic position column"
+    )
+  });
+}
+
+// src/client-core.ts
+var import_node_buffer50 = require("buffer");
+
+// src/client-core-helpers.ts
+var import_node_buffer46 = require("buffer");
+function bgsaveResponse(response) {
+  if ((typeof response === "string" || import_node_buffer46.Buffer.isBuffer(response) || response instanceof Uint8Array) && text(response) === "Background saving started") {
+    return true;
+  }
+  return okResponse(response);
+}
+function clientNameResponse(response) {
+  return response == null ? null : textResponse(response, "CLIENT GETNAME");
+}
+function fetchOrComputeCompletionToken(options) {
+  if (options == null || !Object.hasOwn(options, "computeToken") || options.computeToken === void 0) {
+    throw new TypeError(
+      "fetch-or-compute completion requires computeToken"
+    );
+  }
+  if (!import_node_buffer46.Buffer.isBuffer(options.computeToken)) {
+    throw new TypeError("fetch-or-compute computeToken must be a Buffer");
+  }
+  return options.computeToken;
+}
+function concatCommandArgs(prefix, suffix) {
+  const args = new Array(prefix.length + suffix.length);
+  for (let index = 0; index < prefix.length; index += 1) args[index] = prefix[index];
+  for (let index = 0; index < suffix.length; index += 1) {
+    args[prefix.length + index] = suffix[index];
+  }
+  return args;
+}
+function unsupportedClientTracking() {
+  throw new InvalidCommandError(
+    "CLIENT TRACKING is not supported by the FerricStore native protocol; use native event subscriptions"
+  );
+}
+function unsupportedClientCaching() {
+  throw new InvalidCommandError("CLIENT CACHING is not supported by the FerricStore native protocol");
+}
+
+// src/client-base.ts
+var import_node_buffer48 = require("buffer");
+
+// src/client-executor.ts
+var import_node_buffer47 = require("buffer");
+var ErrorMappingExecutor = class {
+  constructor(executor) {
+    this.executor = executor;
+  }
+  executor;
+  async executeCommand(...args) {
+    return await this.executeCommandArgs(args);
+  }
+  async executeCommandArgs(args) {
+    try {
+      return await executeCommandArgs(this.executor, args);
+    } catch (error) {
+      throwMapped(error);
+    }
+  }
+  async executePipeline(commands, options) {
     let results;
     try {
       if (this.executor.executePipeline != null) {
@@ -11332,14 +12822,14 @@ var FerricStoreAdministrationClient = class extends FerricStoreClientBase {
 };
 
 // src/store-utilities.ts
-var import_node_buffer39 = require("buffer");
+var import_node_buffer49 = require("buffer");
 function encode(codec, value) {
   return codec.encode(value);
 }
 function decode(codec, value) {
   if (value == null) return null;
-  if (import_node_buffer39.Buffer.isBuffer(value)) return codec.decode(value);
-  if (value instanceof Uint8Array) return codec.decode(import_node_buffer39.Buffer.from(value));
+  if (import_node_buffer49.Buffer.isBuffer(value)) return codec.decode(value);
+  if (value instanceof Uint8Array) return codec.decode(import_node_buffer49.Buffer.from(value));
   return value;
 }
 function number(value) {
@@ -11929,15 +13419,15 @@ function compressionOptions(options) {
 // src/store-decoders.ts
 function decodeHashRecord(codec, value) {
   const result = {};
-  for (const [field2, item] of hashPairs(value)) {
-    setOwnValue(result, textToken(field2), decode(codec, item));
+  for (const [field3, item] of hashPairs(value)) {
+    setOwnValue(result, textToken(field3), decode(codec, item));
   }
   return result;
 }
 function decodeHashFlatPairs(codec, value) {
   const result = [];
-  for (const [field2, item] of hashPairs(value)) {
-    result.push(textToken(field2), decode(codec, item));
+  for (const [field3, item] of hashPairs(value)) {
+    result.push(textToken(field3), decode(codec, item));
   }
   return result;
 }
@@ -12057,7 +13547,7 @@ function requiredPair(value, message) {
 }
 function decodeStreamFieldValues(codec, value) {
   const result = [];
-  for (const [field2, item] of hashPairs(value)) result.push(textToken(field2), decode(codec, item));
+  for (const [field3, item] of hashPairs(value)) result.push(textToken(field3), decode(codec, item));
   return result;
 }
 var geoSearchMetadataTokens = /* @__PURE__ */ new Set(["WITHCOORD", "WITHDIST", "WITHHASH"]);
@@ -12871,8 +14361,8 @@ var HashStore = class {
   async hset(key, entries) {
     return number(await commandArgs(this.client, keyValueArgs(["HSET", key], this.client.codec, entries)));
   }
-  async hget(key, field2) {
-    return decode(this.client.codec, await this.client.command("HGET", key, field2));
+  async hget(key, field3) {
+    return decode(this.client.codec, await this.client.command("HGET", key, field3));
   }
   async hdel(key, ...fieldsOrArray) {
     const fields = requireNonEmpty(arrayOrRest(fieldsOrArray), "HDEL", "field");
@@ -12891,8 +14381,8 @@ var HashStore = class {
   async hgetall(key) {
     return decodeHashRecord(this.client.codec, await this.client.command("HGETALL", key));
   }
-  async hexists(key, field2) {
-    return binaryBooleanResponse(await this.client.command("HEXISTS", key, field2));
+  async hexists(key, field3) {
+    return binaryBooleanResponse(await this.client.command("HEXISTS", key, field3));
   }
   async hkeys(key) {
     return mapArray(await this.client.command("HKEYS", key), "HKEYS", textToken);
@@ -12907,17 +14397,17 @@ var HashStore = class {
   async hlen(key) {
     return number(await this.client.command("HLEN", key));
   }
-  async hincrby(key, field2, increment) {
-    return integerReply(await this.client.command("HINCRBY", key, field2, increment));
+  async hincrby(key, field3, increment) {
+    return integerReply(await this.client.command("HINCRBY", key, field3, increment));
   }
-  async hincrbyfloat(key, field2, increment) {
-    return string(await this.client.command("HINCRBYFLOAT", key, field2, increment));
+  async hincrbyfloat(key, field3, increment) {
+    return string(await this.client.command("HINCRBYFLOAT", key, field3, increment));
   }
-  async hsetnx(key, field2, value) {
-    return binaryBooleanResponse(await this.client.command("HSETNX", key, field2, encode(this.client.codec, value)));
+  async hsetnx(key, field3, value) {
+    return binaryBooleanResponse(await this.client.command("HSETNX", key, field3, encode(this.client.codec, value)));
   }
-  async hstrlen(key, field2) {
-    return number(await this.client.command("HSTRLEN", key, field2));
+  async hstrlen(key, field3) {
+    return number(await this.client.command("HSTRLEN", key, field3));
   }
   async hrandfield(key, count, withValues = false) {
     if (withValues && count == null) {
@@ -13553,6 +15043,100 @@ var FerricStoreManagementClient = class extends FerricStoreClientCore {
   }
 };
 
+// src/client-flow-query.ts
+var FerricStoreFlowQueryClient = class extends FerricStoreManagementClient {
+  async query(query, params = {}) {
+    if (hasFlowExplainPrefix(query)) {
+      throw new TypeError("query does not accept EXPLAIN; use explain or explainAnalyze");
+    }
+    return decodeFlowQueryResult(await this.executeFlowQuery(query, params));
+  }
+  async explain(query, params = {}) {
+    return await this.executeExplain("EXPLAIN ", query, params);
+  }
+  async explainAnalyze(query, params = {}) {
+    return await this.executeExplain("EXPLAIN ANALYZE ", query, params);
+  }
+  async queryIndexes(indexId) {
+    const args = ["FLOW.QUERY.INDEXES"];
+    if (indexId != null) {
+      validateFlowQueryIndexId(indexId);
+      args.push(indexId);
+    }
+    try {
+      return decodeFlowQueryIndexStatus(await this.commandArgs(args));
+    } catch (error) {
+      this.throwFlowQueryError(error);
+    }
+  }
+  async list(type, options) {
+    return await this.executeFlowRecordQuery(buildFlowListQuery(type, options));
+  }
+  async search(type, options) {
+    return await this.executeFlowRecordQuery(buildFlowSearchQuery(type, options));
+  }
+  async terminals(type, options) {
+    return await this.executeFlowRecordQuery(buildFlowTerminalQuery(type, options));
+  }
+  async failures(type, options) {
+    return await this.executeFlowRecordQuery(buildFlowFailureQuery(type, options));
+  }
+  async byParent(parentFlowId, options) {
+    return await this.executeFlowRecordQuery(
+      buildFlowLineageQuery("parent_flow_id", parentFlowId, options)
+    );
+  }
+  async byRoot(rootFlowId, options) {
+    return await this.executeFlowRecordQuery(
+      buildFlowLineageQuery("root_flow_id", rootFlowId, options)
+    );
+  }
+  async byCorrelation(correlationId, options) {
+    return await this.executeFlowRecordQuery(
+      buildFlowLineageQuery("correlation_id", correlationId, options)
+    );
+  }
+  async stuck(type, options) {
+    return await this.executeFlowRecordQuery(buildFlowStuckQuery(type, options));
+  }
+  records(values) {
+    const records = new Array(values.length);
+    for (let index = 0; index < values.length; index += 1) {
+      if (!Object.hasOwn(values, index)) {
+        throw new TypeError(`Flow record response item ${index} is missing`);
+      }
+      records[index] = flowRecordFromResp(values[index], this.codec);
+    }
+    return records;
+  }
+  async executeFlowQuery(query, params) {
+    const args = flowQueryArgs(query, params);
+    try {
+      return await this.commandArgs(args);
+    } catch (error) {
+      this.throwFlowQueryError(error);
+    }
+  }
+  async executeFlowRecordQuery(request) {
+    const response = await this.executeFlowQuery(request.query, request.params);
+    return decodeFlowQueryRecords(response, (value) => flowRecordFromResp(value, this.codec));
+  }
+  async executeExplain(prefix, query, params) {
+    validateFlowQueryText(query);
+    if (hasFlowExplainPrefix(query)) {
+      throw new TypeError("query already contains an EXPLAIN prefix");
+    }
+    return decodeFlowExplainResult(await this.executeFlowQuery(prefix + query.trim(), params));
+  }
+  throwFlowQueryError(error) {
+    if (error instanceof FerricStoreError) {
+      const diagnostic = tryDecodeFlowQueryError(error.raw, error);
+      if (diagnostic != null) throw diagnostic;
+    }
+    throw error;
+  }
+};
+
 // src/producer-backpressure.ts
 async function executeProducerWriteWithBackpressure(execute, policy, signal) {
   for (let attempt = 0; ; attempt += 1) {
@@ -13575,7 +15159,7 @@ function throwIfClosed(signal) {
 }
 
 // src/flow-policy.ts
-var import_node_buffer41 = require("buffer");
+var import_node_buffer51 = require("buffer");
 var MAX_FLOW_POLICY_GENERATION = Number.MAX_SAFE_INTEGER;
 function assertFlowPolicyGeneration(value) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
@@ -13585,15 +15169,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 = optionalText2(field(policy, "state"), "state");
+  const state = optionalText3(field(policy, "state"), "state");
   const mode = optionalMode(field(policy, "mode"), "mode");
   const version = optionalVersion(field(policy, "version"));
-  const indexedStateMeta = optionalText2(field(policy, "indexed_state_meta"), "indexed_state_meta");
+  const indexedStateMeta = optionalText3(field(policy, "indexed_state_meta"), "indexed_state_meta");
   const governance = optionalRecord(field(policy, "governance"), "governance");
   const states = optionalStates(field(policy, "states"));
   return {
-    type: requiredText(field(policy, "type"), "type"),
-    generation: nonNegativeInteger(field(policy, "generation"), "generation"),
+    type: requiredText3(field(policy, "type"), "type"),
+    generation: nonNegativeInteger2(field(policy, "generation"), "generation"),
     ...state == null ? {} : { state },
     ...version == null ? {} : { version },
     ...mode == null ? {} : { mode },
@@ -13611,21 +15195,21 @@ function retrySnapshot(value, context) {
   const retry2 = requiredRecord(value, `FLOW policy ${context}`);
   const backoff = requiredRecord(field(retry2, "backoff"), `FLOW policy ${context}.backoff`);
   return {
-    maxRetries: nonNegativeInteger(field(retry2, "max_retries"), `${context}.max_retries`),
+    maxRetries: nonNegativeInteger2(field(retry2, "max_retries"), `${context}.max_retries`),
     backoff: {
       kind: backoffKind(field(backoff, "kind"), `${context}.backoff.kind`),
-      baseMs: nonNegativeInteger(field(backoff, "base_ms"), `${context}.backoff.base_ms`),
-      maxMs: nonNegativeInteger(field(backoff, "max_ms"), `${context}.backoff.max_ms`),
-      jitterPct: nonNegativeInteger(field(backoff, "jitter_pct"), `${context}.backoff.jitter_pct`)
+      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`)
     },
-    exhaustedTo: requiredText(field(retry2, "exhausted_to"), `${context}.exhausted_to`)
+    exhaustedTo: requiredText3(field(retry2, "exhausted_to"), `${context}.exhausted_to`)
   };
 }
 function retentionSnapshot(value, context) {
   const retention = requiredRecord(value, `FLOW policy ${context}`);
   return {
-    ttlMs: nonNegativeInteger(field(retention, "ttl_ms"), `${context}.ttl_ms`),
-    historyMaxEvents: nonNegativeInteger(
+    ttlMs: nonNegativeInteger2(field(retention, "ttl_ms"), `${context}.ttl_ms`),
+    historyMaxEvents: nonNegativeInteger2(
       field(retention, "history_max_events"),
       `${context}.history_max_events`
     )
@@ -13661,11 +15245,11 @@ function requiredRecord(value, context) {
   if (value instanceof Map) {
     const result = {};
     for (const [key, item] of value.entries()) {
-      setOwnValue(result, requiredText(key, `${context} key`), item);
+      setOwnValue(result, requiredText3(key, `${context} key`), item);
     }
     return result;
   }
-  if (typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer41.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) return value;
+  if (typeof value === "object" && value != null && !Array.isArray(value) && !import_node_buffer51.Buffer.isBuffer(value) && !(value instanceof Uint8Array)) return value;
   throw new TypeError(`${context} returned an unexpected response`);
 }
 function optionalRecord(value, context) {
@@ -13680,21 +15264,21 @@ function stringArray(value, context) {
     if (!Object.hasOwn(value, index)) {
       throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
     }
-    result[index] = requiredText(value[index], `${context}[${index}]`);
+    result[index] = requiredText3(value[index], `${context}[${index}]`);
   }
   return result;
 }
-function requiredText(value, context) {
+function requiredText3(value, context) {
   if (typeof value === "string") return value;
-  if (import_node_buffer41.Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return import_node_buffer41.Buffer.from(value).toString("utf8");
+  if (import_node_buffer51.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return import_node_buffer51.Buffer.from(value).toString("utf8");
   }
   throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
 }
-function optionalText2(value, context) {
-  return value == null ? void 0 : requiredText(value, context);
+function optionalText3(value, context) {
+  return value == null ? void 0 : requiredText3(value, context);
 }
-function nonNegativeInteger(value, context) {
+function nonNegativeInteger2(value, context) {
   let parsed;
   try {
     parsed = integer(value);
@@ -13706,26 +15290,26 @@ function nonNegativeInteger(value, context) {
 }
 function optionalPositiveInteger(value, context) {
   if (value == null) return void 0;
-  const parsed = nonNegativeInteger(value, context);
+  const parsed = nonNegativeInteger2(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 nonNegativeInteger(value, "version");
+    return nonNegativeInteger2(value, "version");
   }
-  return requiredText(value, "version");
+  return requiredText3(value, "version");
 }
 function backoffKind(value, context) {
-  const kind = requiredText(value, context).toLowerCase();
+  const kind = requiredText3(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 = requiredText(value, context).toLowerCase();
+  const mode = requiredText3(value, context).toLowerCase();
   if (mode === "fifo" || mode === "parallel") return mode;
   throw new TypeError(`FLOW policy ${context} returned an unexpected response`);
 }
@@ -13734,7 +15318,7 @@ function optionalMode(value, context) {
 }
 
 // src/client-flow-support.ts
-var FerricStoreFlowSupportClient = class extends FerricStoreManagementClient {
+var FerricStoreFlowSupportClient = class extends FerricStoreFlowQueryClient {
   async rewind(id, options = {}) {
     const partitionKey = options.partitionKey;
     const returnRecord = options.returnRecord === true;
@@ -13760,43 +15344,9 @@ var FerricStoreFlowSupportClient = class extends FerricStoreManagementClient {
     }
     return flowRecordFromResp(response, this.codec);
   }
-  async list(type, options = {}) {
-    return await this.indexQuery("FLOW.LIST", type, options);
-  }
-  async search(type, options = {}) {
-    const args = ["FLOW.SEARCH", type];
-    appendReadOptions(args, options);
-    appendAttributes(args, options.attributes);
-    appendSearchStateMeta(args, options.state, options.stateMeta);
-    const response = await this.commandArgs(args);
-    return this.records(requiredArrayResponse(response, "FLOW.SEARCH"));
-  }
-  async terminals(type, options = {}) {
-    return await this.indexQuery("FLOW.TERMINALS", type, options);
-  }
-  async failures(type, options = {}) {
-    return await this.indexQuery("FLOW.FAILURES", type, options);
-  }
-  async byParent(parentFlowId, options = {}) {
-    return await this.indexQuery("FLOW.BY_PARENT", parentFlowId, options);
-  }
-  async byRoot(rootFlowId, options = {}) {
-    return await this.indexQuery("FLOW.BY_ROOT", rootFlowId, options);
-  }
-  async byCorrelation(correlationId, options = {}) {
-    return await this.indexQuery("FLOW.BY_CORRELATION", correlationId, options);
-  }
   async info(type) {
     return parseKvResponse(await this.command("FLOW.INFO", type));
   }
-  async stuck(type, options = {}) {
-    const args = ["FLOW.STUCK", type];
-    append(args, "PARTITION", options.partitionKey);
-    append(args, "COUNT", options.count);
-    append(args, "OLDER_THAN", options.olderThanMs);
-    append(args, "NOW", options.nowMs);
-    return this.records(arrayResponse(await this.commandArgs(args)));
-  }
   async history(id, options = {}) {
     const args = ["FLOW.HISTORY", id];
     append(args, "PARTITION", options.partitionKey);
@@ -13926,16 +15476,6 @@ var FerricStoreFlowSupportClient = class extends FerricStoreManagementClient {
     }
     return record;
   }
-  records(values) {
-    const records = new Array(values.length);
-    for (let index = 0; index < values.length; index += 1) {
-      if (!Object.hasOwn(values, index)) {
-        throw new TypeError(`Flow record response item ${index} is missing`);
-      }
-      records[index] = flowRecordFromResp(values[index], this.codec);
-    }
-    return records;
-  }
   recordsOrResponse(value) {
     if (Array.isArray(value) && value.every(isRecordLike)) {
       return this.records(value);
@@ -13965,12 +15505,6 @@ var FerricStoreFlowSupportClient = class extends FerricStoreManagementClient {
     }
     return results;
   }
-  async indexQuery(command, key, options) {
-    const args = [command, key];
-    appendReadOptions(args, options);
-    const response = await this.commandArgs(args);
-    return this.records(requiredArrayResponse(response, command));
-  }
   appendPartitionOptions(args, options) {
     if (options.partitionKey != null && options.partitionKeys != null) {
       throw new Error("partitionKey and partitionKeys are mutually exclusive");
@@ -13993,7 +15527,7 @@ var FerricStoreFlowSupportClient = class extends FerricStoreManagementClient {
 };
 
 // src/flow-many-snapshot.ts
-var import_node_buffer43 = require("buffer");
+var import_node_buffer53 = require("buffer");
 var encodedOptionFields = ["error", "payload", "reason", "result"];
 function snapshotCreateItem(item, codec) {
   const snapshot = {
@@ -14011,9 +15545,9 @@ function snapshotCreateItem(item, codec) {
 function snapshotFlowManyOptions(options, codec) {
   const snapshot = { ...options };
   const mutable = snapshot;
-  for (const field2 of encodedOptionFields) {
-    const value = options[field2];
-    if (value != null) mutable[field2] = snapshotFlowValue(codec, value);
+  for (const field3 of encodedOptionFields) {
+    const value = options[field3];
+    if (value != null) mutable[field3] = snapshotFlowValue(codec, value);
   }
   if (options.attributes != null) mutable.attributes = snapshotCommandRecord(options.attributes);
   if (options.attributesMerge != null) {
@@ -14033,7 +15567,7 @@ function snapshotFlowManyOptions(options, codec) {
 }
 function snapshotClaimedItem(item) {
   const wire = item[CLAIMED_ITEM_WIRE];
-  const leaseToken = import_node_buffer43.Buffer.from(wire?.leaseToken ?? item.leaseToken);
+  const leaseToken = import_node_buffer53.Buffer.from(wire?.leaseToken ?? item.leaseToken);
   const snapshot = {
     ...item,
     fencingToken: wire?.fencingToken ?? item.fencingToken,
@@ -14050,15 +15584,15 @@ function snapshotClaimedItem(item) {
 function snapshotFencedItem(item) {
   return Object.freeze({
     ...item,
-    ...item.leaseToken == null ? {} : { leaseToken: import_node_buffer43.Buffer.from(item.leaseToken) }
+    ...item.leaseToken == null ? {} : { leaseToken: import_node_buffer53.Buffer.from(item.leaseToken) }
   });
 }
 function snapshotClaimedItemWire(wire, leaseToken) {
   return Object.freeze({
     fencingToken: wire.fencingToken,
-    id: import_node_buffer43.Buffer.from(wire.id),
+    id: import_node_buffer53.Buffer.from(wire.id),
     leaseToken,
-    partitionKey: wire.partitionKey == null ? wire.partitionKey : import_node_buffer43.Buffer.from(wire.partitionKey)
+    partitionKey: wire.partitionKey == null ? wire.partitionKey : import_node_buffer53.Buffer.from(wire.partitionKey)
   });
 }
 function snapshotArray(values) {
@@ -14069,7 +15603,7 @@ function snapshotArray(values) {
   return Object.freeze(snapshot);
 }
 function snapshotStateMeta(stateMeta) {
-  return snapshotRecord(stateMeta, (value) => import_node_buffer43.Buffer.isBuffer(value) ? import_node_buffer43.Buffer.from(value) : value);
+  return snapshotRecord(stateMeta, (value) => import_node_buffer53.Buffer.isBuffer(value) ? import_node_buffer53.Buffer.from(value) : value);
 }
 function snapshotCommandRecord(values) {
   const seen = /* @__PURE__ */ new WeakMap();
@@ -14087,7 +15621,7 @@ function snapshotRecord(values, capture) {
 }
 function snapshotCommandArgument(value, seen) {
   if (typeof value !== "object" || value == null) return value;
-  if (import_node_buffer43.Buffer.isBuffer(value) || value instanceof Uint8Array) return import_node_buffer43.Buffer.from(value);
+  if (import_node_buffer53.Buffer.isBuffer(value) || value instanceof Uint8Array) return import_node_buffer53.Buffer.from(value);
   const objectValue = value;
   const existing = seen.get(objectValue);
   if (existing != null) return existing;
@@ -15074,6 +16608,142 @@ function nativeOptionsForBootstrap(options, signal) {
   };
 }
 
+// src/flow-query-projection.ts
+var import_node_buffer54 = require("buffer");
+var MAX_PROJECTION_FIELDS = 32;
+var MAX_DYNAMIC_NAME_BYTES = 64;
+var FIELD_BRAND = /* @__PURE__ */ Symbol("FerricStoreFlowProjectionField");
+function field2(source, selector) {
+  return Object.freeze({ source, selector, [FIELD_BRAND]: true });
+}
+var run = Object.freeze({
+  id: field2("runs", "run_id"),
+  type: field2("runs", "type"),
+  state: field2("runs", "state"),
+  version: field2("runs", "version"),
+  priority: field2("runs", "priority"),
+  partitionKey: field2("runs", "partition_key"),
+  createdAtMs: field2("runs", "created_at_ms"),
+  updatedAtMs: field2("runs", "updated_at_ms"),
+  nextRunAtMs: field2("runs", "next_run_at_ms"),
+  leaseDeadlineMs: field2("runs", "lease_deadline_ms"),
+  attempts: field2("runs", "attempts"),
+  runState: field2("runs", "run_state"),
+  maxActiveMs: field2("runs", "max_active_ms"),
+  parentFlowId: field2("runs", "parent_flow_id"),
+  rootFlowId: field2("runs", "root_flow_id"),
+  correlationId: field2("runs", "correlation_id"),
+  attributes: field2("runs", "attributes"),
+  stateMetadata: field2("runs", "state_meta"),
+  attribute(name) {
+    return field2("runs", `attribute[${quoteName(name, false)}]`);
+  },
+  stateMeta(state, name) {
+    return field2(
+      "runs",
+      `state_meta[${quoteName(state, true)}][${quoteName(name, false)}]`
+    );
+  }
+});
+var event = Object.freeze({
+  id: field2("events", "event_id"),
+  fields: field2("events", "fields"),
+  field(name) {
+    return field2("events", `fields[${quoteName(name, false)}]`);
+  }
+});
+var FlowProjection = Object.freeze({ run, event });
+function projectFlowQuery(query, shape, ...fields) {
+  validateFlowQueryText(query);
+  if (shape !== "record" && shape !== "records") {
+    throw new TypeError("Flow query projection shape must be record or records");
+  }
+  if (fields.length === 0 || fields.length > MAX_PROJECTION_FIELDS) {
+    throw new TypeError(
+      `Flow query projection must contain 1..${MAX_PROJECTION_FIELDS} fields`
+    );
+  }
+  if (!fields.every((item) => item?.[FIELD_BRAND])) {
+    throw new TypeError("Flow query projection accepts only FlowProjection fields");
+  }
+  const source = querySource(query);
+  if (fields.some((item) => item.source !== source)) {
+    throw new TypeError(`Flow query projection fields must belong to ${source}`);
+  }
+  const selectors = fields.map((item) => item.selector);
+  if (new Set(selectors).size !== selectors.length) {
+    throw new TypeError("Flow query projection contains a duplicate field");
+  }
+  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 result = `${base} RETURN ${shape.toUpperCase()} (${selectors.join(", ")})`;
+  if (import_node_buffer54.Buffer.byteLength(result, "utf8") > FLOW_QUERY_MAX_BYTES) {
+    throw new TypeError(`FLOW.QUERY query exceeds ${FLOW_QUERY_MAX_BYTES} bytes`);
+  }
+  return result;
+}
+function querySource(query) {
+  const match = /^\s*FROM\s+(runs|events)\b/iu.exec(query);
+  if (match?.[1] == null) {
+    throw new TypeError("Projected Flow query must start with FROM runs or FROM events");
+  }
+  return match[1].toLowerCase();
+}
+function containsReturnKeyword(query) {
+  let quoted = false;
+  for (let index = 0; index < query.length; ) {
+    const character = query.charAt(index);
+    if (character === "'") {
+      if (quoted && query[index + 1] === "'") {
+        index += 2;
+        continue;
+      }
+      quoted = !quoted;
+      index += 1;
+      continue;
+    }
+    if (!quoted && /[A-Za-z_]/u.test(character)) {
+      let end = index + 1;
+      while (end < query.length && /[A-Za-z0-9_]/u.test(query.charAt(end))) end += 1;
+      if (query.slice(index, end).toUpperCase() === "RETURN") return true;
+      index = end;
+      continue;
+    }
+    index += 1;
+  }
+  return false;
+}
+function quoteName(value, allowPrivate) {
+  if (typeof value !== "string") {
+    throw new TypeError("Flow query projection metadata name must be text");
+  }
+  validateUnicodeScalarText2(value);
+  const size = import_node_buffer54.Buffer.byteLength(value, "utf8");
+  if (size === 0 || size > MAX_DYNAMIC_NAME_BYTES || !allowPrivate && value.startsWith("__")) {
+    throw new TypeError(
+      `Flow query projection metadata names must be 1..${MAX_DYNAMIC_NAME_BYTES} UTF-8 bytes`
+    );
+  }
+  return `'${value.replaceAll("'", "''")}'`;
+}
+function validateUnicodeScalarText2(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 55296 && code <= 56319) {
+      const low = value.charCodeAt(index + 1);
+      if (!(low >= 56320 && low <= 57343)) {
+        throw new TypeError("Flow query projection metadata name must be valid UTF-8");
+      }
+      index += 1;
+    } else if (code >= 56320 && code <= 57343) {
+      throw new TypeError("Flow query projection metadata name must be valid UTF-8");
+    }
+  }
+}
+
 // src/outcomes.ts
 var OUTCOME_BRAND = /* @__PURE__ */ Symbol("ferricstore.outcome");
 function transition(toState, options = {}) {
@@ -15153,7 +16823,7 @@ var LeaseRenewalGuard = class {
     if (options.leaseRenewal === false) {
       return;
     }
-    const intervalMs = positiveInteger(options.leaseRenewIntervalMs, Math.max(1, Math.trunc(leaseMs / 2)));
+    const intervalMs = positiveInteger2(options.leaseRenewIntervalMs, Math.max(1, Math.trunc(leaseMs / 2)));
     this.timer = setLongInterval(() => this.renew(), intervalMs);
     this.timer.unref();
   }
@@ -15225,7 +16895,7 @@ function snapshotLeasedJob(job) {
   return snapshot;
 }
 function workerConcurrency(options) {
-  return positiveInteger(options.concurrency ?? options.workers, 1);
+  return positiveInteger2(options.concurrency ?? options.workers, 1);
 }
 function workerRefillStrategy(options) {
   return options.refillStrategy === "wave" ? "wave" : "continuous";
@@ -15268,18 +16938,18 @@ function workerErrorPayload(error, options, codec) {
 }
 function workerBatchSize(options, flowManyBatchLimit = DEFAULT_FLOW_MANY_BATCH_LIMIT2) {
   return Math.min(
-    positiveInteger(options.batchSize, 10),
-    positiveInteger(flowManyBatchLimit, DEFAULT_FLOW_MANY_BATCH_LIMIT2)
+    positiveInteger2(options.batchSize, 10),
+    positiveInteger2(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 positiveInteger(options.claimDrainBatches, 1);
+  return positiveInteger2(options.claimDrainBatches, 1);
 }
 function workerLeaseMs(options, fallback = 3e4) {
-  return positiveInteger(options.leaseMs, positiveInteger(fallback, 3e4));
+  return positiveInteger2(options.leaseMs, positiveInteger2(fallback, 3e4));
 }
 function workerIdleSleepMs(options) {
   return nonNegativeDuration(options.idleSleepMs, 250);
@@ -15291,7 +16961,7 @@ function workerClaimBlockMs(options, useBlocking) {
   if (options.signal == null || !Number.isFinite(options.blockMs) || options.blockMs < 0) {
     return options.blockMs;
   }
-  const abortPollMs = positiveInteger(options.abortPollMs, 1e3);
+  const abortPollMs = positiveInteger2(options.abortPollMs, 1e3);
   return options.blockMs === 0 ? abortPollMs : Math.min(Math.trunc(options.blockMs), abortPollMs);
 }
 function workerMaxIdleSleepMs(options, idleSleepMs = workerIdleSleepMs(options)) {
@@ -15302,14 +16972,14 @@ function nextWorkerIdleSleepMs(currentIdleSleepMs, maxIdleSleepMs) {
   return Math.min(maxIdleSleepMs, Math.max(1, currentIdleSleepMs * 2));
 }
 async function runContinuousWorkerPool(options) {
-  const concurrency = positiveInteger(options.concurrency, 1);
-  const maxClaimSize = positiveInteger(options.maxClaimSize, concurrency);
+  const concurrency = positiveInteger2(options.concurrency, 1);
+  const maxClaimSize = positiveInteger2(options.maxClaimSize, concurrency);
   const initialIdleSleepMs = nonNegativeDuration(options.idleSleepMs, 250);
   const maxIdleSleepMs = Math.max(
     initialIdleSleepMs,
     nonNegativeDuration(options.maxIdleSleepMs, 5e3)
   );
-  const refillDelayMs = nonNegativeInteger2(options.refillDelayMs, 0);
+  const refillDelayMs = nonNegativeInteger3(options.refillDelayMs, 0);
   const active = /* @__PURE__ */ new Set();
   const pending = [];
   let pendingIndex = 0;
@@ -15425,10 +17095,10 @@ function normalizeWorkflowWorkerConfig(options) {
     ...captured
   });
 }
-function positiveInteger(value, fallback) {
+function positiveInteger2(value, fallback) {
   return value == null || !Number.isFinite(value) ? fallback : Math.max(1, Math.trunc(value));
 }
-function nonNegativeInteger2(value, fallback) {
+function nonNegativeInteger3(value, fallback) {
   return value == null || !Number.isFinite(value) ? fallback : Math.max(0, Math.trunc(value));
 }
 function nonNegativeDuration(value, fallback) {
@@ -17057,8 +18727,8 @@ var WorkflowWorker = class {
 };
 
 // src/version.ts
-var FERRICSTORE_SDK_VERSION = "0.3.0";
-var FERRICSTORE_MINIMUM_SERVER_VERSION = "0.9.1";
+var FERRICSTORE_SDK_VERSION = "0.5.0";
+var FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.0";
 var FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -17077,6 +18747,8 @@ var FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
   FlowAlreadyExistsError,
   FlowBatchError,
   FlowNotFoundError,
+  FlowProjection,
+  FlowQueryError,
   FlowWrongStateError,
   GeoStore,
   HashStore,
@@ -17119,6 +18791,7 @@ var FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
   isOutcome,
   isReconnectableClosedConnectionError,
   mapException,
+  projectFlowQuery,
   retry,
   transition
 });