@ferricstore/ferricstore 0.1.4 → 0.1.5

package/dist/index.js

@@ -110,24 +110,171 @@ var FLAG_CUSTOM_PAYLOAD = 2;
 var FLAG_COMPRESSED = 8;
 var FLAG_MORE_CHUNKS = 32;
 var STATUS_OK = 0;
+var COMMAND_OPCODES = {
+  "HELLO": 1,
+  "AUTH": 2,
+  "PING": 3,
+  "CLIENT.SETNAME": 4,
+  "CLIENT.INFO": 5,
+  "ROUTE": 6,
+  "SHARDS": 7,
+  "BACKPRESSURE": 8,
+  "QUIT": 9,
+  "GOAWAY": 10,
+  "OPTIONS": 11,
+  "STARTUP": 12,
+  "WINDOW_UPDATE": 13,
+  "PIPELINE": 14,
+  "ROUTE_BATCH": 15,
+  "EVENT": 16,
+  "SUBSCRIBE_EVENTS": 17,
+  "UNSUBSCRIBE_EVENTS": 18,
+  "COMMAND_EXEC": 256,
+  "GET": 257,
+  "SET": 258,
+  "DEL": 259,
+  "MGET": 260,
+  "MSET": 261,
+  "CAS": 262,
+  "LOCK": 263,
+  "UNLOCK": 264,
+  "EXTEND": 265,
+  "RATELIMIT.ADD": 266,
+  "FETCH_OR_COMPUTE": 267,
+  "FETCH_OR_COMPUTE_RESULT": 268,
+  "FETCH_OR_COMPUTE_ERROR": 269,
+  "HSET": 272,
+  "HGET": 273,
+  "HMGET": 274,
+  "HGETALL": 275,
+  "LPUSH": 288,
+  "RPUSH": 289,
+  "LPOP": 290,
+  "RPOP": 291,
+  "LRANGE": 292,
+  "SADD": 304,
+  "SREM": 305,
+  "SMEMBERS": 306,
+  "SISMEMBER": 307,
+  "ZADD": 320,
+  "ZREM": 321,
+  "ZRANGE": 322,
+  "ZSCORE": 323,
+  "FLOW.CREATE": 513,
+  "FLOW.GET": 514,
+  "FLOW.CLAIM_DUE": 515,
+  "FLOW.COMPLETE": 516,
+  "FLOW.TRANSITION": 517,
+  "FLOW.RETRY": 518,
+  "FLOW.FAIL": 519,
+  "FLOW.CANCEL": 520,
+  "FLOW.EXTEND_LEASE": 521,
+  "FLOW.HISTORY": 522,
+  "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,
+  "FLOW.RETRY_MANY": 530,
+  "FLOW.FAIL_MANY": 531,
+  "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,
+  "FLOW.RETENTION_CLEANUP": 545,
+  "FLOW.STEP_CONTINUE": 546,
+  "FLOW.START_AND_CLAIM": 547,
+  "FLOW.RUN_STEPS_MANY": 548,
+  "FLOW.SCHEDULE.CREATE": 549,
+  "FLOW.SCHEDULE.GET": 550,
+  "FLOW.SCHEDULE.DELETE": 551,
+  "FLOW.SCHEDULE.FIRE_DUE": 552,
+  "FLOW.SCHEDULE.LIST": 553,
+  "FLOW.SCHEDULE.FIRE": 554,
+  "FLOW.SCHEDULE.PAUSE": 555,
+  "FLOW.SCHEDULE.RESUME": 556,
+  "FLOW.STATS": 557,
+  "FLOW.ATTRIBUTES": 558,
+  "FLOW.ATTRIBUTE_VALUES": 559,
+  "FLOW.SEARCH": 560,
+  "FLOW.EFFECT.RESERVE": 576,
+  "FLOW.EFFECT.CONFIRM": 577,
+  "FLOW.EFFECT.FAIL": 578,
+  "FLOW.EFFECT.COMPENSATE": 579,
+  "FLOW.EFFECT.GET": 580,
+  "FLOW.GOVERNANCE.LEDGER": 581,
+  "FLOW.APPROVAL.REQUEST": 582,
+  "FLOW.APPROVAL.APPROVE": 583,
+  "FLOW.APPROVAL.REJECT": 584,
+  "FLOW.APPROVAL.GET": 585,
+  "FLOW.CIRCUIT.OPEN": 586,
+  "FLOW.CIRCUIT.CLOSE": 587,
+  "FLOW.CIRCUIT.GET": 588,
+  "FLOW.BUDGET.RESERVE": 589,
+  "FLOW.BUDGET.GET": 590,
+  "FLOW.LIMIT.LEASE": 591,
+  "FLOW.LIMIT.SPEND": 592,
+  "FLOW.LIMIT.RELEASE": 593,
+  "FLOW.LIMIT.GET": 594,
+  "FLOW.APPROVAL.LIST": 595,
+  "FLOW.GOVERNANCE.OVERVIEW": 596,
+  "FLOW.BUDGET.LIST": 597,
+  "FLOW.LIMIT.LIST": 598,
+  "FLOW.BUDGET.COMMIT": 599,
+  "FLOW.BUDGET.RELEASE": 600,
+  "CLUSTER.HEALTH": 769,
+  "CLUSTER.STATS": 770,
+  "CLUSTER.KEYSLOT": 771,
+  "CLUSTER.SLOTS": 772,
+  "CLUSTER.STATUS": 773,
+  "CLUSTER.JOIN": 774,
+  "CLUSTER.LEAVE": 775,
+  "CLUSTER.FAILOVER": 776,
+  "CLUSTER.PROMOTE": 777,
+  "CLUSTER.DEMOTE": 778,
+  "CLUSTER.ROLE": 779,
+  "FERRICSTORE.KEY_INFO": 780,
+  "FERRICSTORE.CONFIG": 781,
+  "FERRICSTORE.HOTNESS": 782,
+  "FERRICSTORE.METRICS": 783,
+  "FERRICSTORE.BLOBGC": 784
+};
 var OPCODES = {
-  startup: 12,
-  auth: 2,
-  ping: 3,
-  clientSetName: 4,
-  clientInfo: 5,
-  commandExec: 256,
-  get: 257,
-  set: 258,
-  del: 259,
-  mget: 260,
-  mset: 261,
-  pipeline: 14,
-  flowCreate: 513,
-  flowClaimDue: 515,
-  flowComplete: 516,
-  flowCreateMany: 527,
-  flowCompleteMany: 528
+  startup: COMMAND_OPCODES.STARTUP,
+  auth: COMMAND_OPCODES.AUTH,
+  ping: COMMAND_OPCODES.PING,
+  clientSetName: COMMAND_OPCODES["CLIENT.SETNAME"],
+  clientInfo: COMMAND_OPCODES["CLIENT.INFO"],
+  route: COMMAND_OPCODES.ROUTE,
+  routeBatch: COMMAND_OPCODES.ROUTE_BATCH,
+  shards: COMMAND_OPCODES.SHARDS,
+  backpressure: COMMAND_OPCODES.BACKPRESSURE,
+  options: COMMAND_OPCODES.OPTIONS,
+  quit: COMMAND_OPCODES.QUIT,
+  commandExec: COMMAND_OPCODES.COMMAND_EXEC,
+  get: COMMAND_OPCODES.GET,
+  set: COMMAND_OPCODES.SET,
+  del: COMMAND_OPCODES.DEL,
+  mget: COMMAND_OPCODES.MGET,
+  mset: COMMAND_OPCODES.MSET,
+  pipeline: COMMAND_OPCODES.PIPELINE,
+  flowCreate: COMMAND_OPCODES["FLOW.CREATE"],
+  flowClaimDue: COMMAND_OPCODES["FLOW.CLAIM_DUE"],
+  flowComplete: COMMAND_OPCODES["FLOW.COMPLETE"],
+  flowCreateMany: COMMAND_OPCODES["FLOW.CREATE_MANY"],
+  flowCompleteMany: COMMAND_OPCODES["FLOW.COMPLETE_MANY"],
+  flowSearch: COMMAND_OPCODES["FLOW.SEARCH"]
 };
 var COMPACT_FLOW_CLAIM_JOBS = 128;
 var COMPACT_OK_LIST = 129;
@@ -260,12 +407,46 @@ function buildProtocolCommand(args) {
   }
   const command = asText(args[0]).toUpperCase();
   const commandArgs = args.slice(1);
+  if (command === "COMMAND_EXEC" && commandArgs.length >= 1) {
+    return commandExec(commandArgs);
+  }
+  if (command === "HELLO" || command === "STARTUP" || command === "WINDOW_UPDATE") {
+    return { laneId: 0, opcode: COMMAND_OPCODES[command], payload: optionMap(commandArgs) };
+  }
+  if (command === "AUTH") {
+    const payload = commandArgs.length === 1 ? { password: commandArgs[0], username: "default" } : { password: commandArgs[1], username: commandArgs[0] };
+    return { laneId: 0, opcode: OPCODES.auth, payload };
+  }
   if (command === "PING") {
     return { laneId: 0, opcode: OPCODES.ping, payload: commandArgs.length === 0 ? {} : { message: commandArgs[0] } };
   }
+  if (command === "OPTIONS") {
+    return { laneId: 0, opcode: OPCODES.options, payload: {} };
+  }
+  if (command === "BACKPRESSURE") {
+    return { laneId: 0, opcode: OPCODES.backpressure, payload: {} };
+  }
+  if (command === "QUIT") {
+    return { laneId: 0, opcode: OPCODES.quit, payload: {} };
+  }
+  if (command === "ROUTE" && commandArgs.length >= 1) {
+    return { laneId: 0, opcode: OPCODES.route, payload: { key: commandArgs[0] } };
+  }
+  if (command === "ROUTE_BATCH") {
+    return { laneId: 0, opcode: OPCODES.routeBatch, payload: { keys: commandArgs } };
+  }
+  if (command === "SHARDS") {
+    return { laneId: 0, opcode: OPCODES.shards, payload: {} };
+  }
   if (command === "CLIENT" && asText(commandArgs[0]).toUpperCase() === "SETNAME" && commandArgs.length === 2) {
     return { laneId: 0, opcode: OPCODES.clientSetName, payload: { name: commandArgs[1] } };
   }
+  if (command === "CLIENT.SETNAME" && commandArgs.length === 1) {
+    return { laneId: 0, opcode: OPCODES.clientSetName, payload: { name: commandArgs[0] } };
+  }
+  if (command === "CLIENT" && asText(commandArgs[0]).toUpperCase() === "INFO" && commandArgs.length === 1 || command === "CLIENT.INFO" && commandArgs.length === 0) {
+    return { laneId: 0, opcode: OPCODES.clientInfo, payload: {} };
+  }
   if (command === "GET" && commandArgs.length >= 1) {
     return { opcode: OPCODES.get, payload: { key: commandArgs[0] } };
   }
@@ -284,7 +465,7 @@ function buildProtocolCommand(args) {
   if (command === "DEL") {
     return { opcode: OPCODES.del, payload: { keys: commandArgs } };
   }
-  if (command.startsWith("FLOW.") && hasFlowCommandOnlyOption(commandArgs)) {
+  if (command.startsWith("FLOW.") && hasFlowCommandOnlyOption(command, commandArgs)) {
     return commandExec(args);
   }
   if (command === "FLOW.CREATE") {
@@ -302,6 +483,9 @@ function buildProtocolCommand(args) {
   if (command === "FLOW.COMPLETE_MANY") {
     return flowCompleteManyPayload(commandArgs) ?? commandExec(args);
   }
+  if (command === "FLOW.SEARCH") {
+    return flowSearchPayload(commandArgs) ?? commandExec(args);
+  }
   return commandExec(args);
 }
 function commandExec(args) {
@@ -646,13 +830,13 @@ function writeOptionalBinary(out, offset, value) {
   }
   return writeBinary(out, offset, value);
 }
-function hasFlowCommandOnlyOption(args) {
+function hasFlowCommandOnlyOption(command, args) {
   return args.some((arg) => {
     if (typeof arg !== "string" && !Buffer2.isBuffer(arg)) {
       return false;
     }
     const token = asText(arg).toUpperCase();
-    return token === "STATE_META" || token === "INDEXED_STATE_META";
+    return token === "INDEXED_STATE_META" || command !== "FLOW.SEARCH" && token === "STATE_META";
   });
 }
 function flowCreatePayload(args) {
@@ -770,6 +954,12 @@ function flowCompleteManyPayload(args) {
   if (!auto && !mixed) payload.partition_key = partition;
   return { opcode: OPCODES.flowCompleteMany, payload };
 }
+function flowSearchPayload(args) {
+  if (args.length < 1) return void 0;
+  const payload = optionMap(args.slice(1));
+  normalizeFlowSearchStateMeta(payload);
+  return { opcode: OPCODES.flowSearch, payload: { type: args[0], ...payload } };
+}
 function compactFlowCreateManyPayload(partition, rawItems, mixed, auto, options) {
   if ("priority" in options || "idempotent" in options || "retention_ttl_ms" in options || typeof options.type === "undefined" || typeof options.state === "undefined" || typeof options.now_ms !== "number") {
     return void 0;
@@ -872,6 +1062,78 @@ function compactFlowCompleteManyPayload(partition, rawItems, mixed, auto, option
   }
   return { flags: FLAG_CUSTOM_PAYLOAD, opcode: OPCODES.flowCompleteMany, payload: out };
 }
+var OPTION_FIELDS = {
+  CONSISTENT_PROJECTION: "consistent_projection",
+  COUNT: "count",
+  FROM_MS: "from_ms",
+  INCLUDE_COLD: "include_cold",
+  PARTITION: "partition_key",
+  REV: "rev",
+  STATE: "state",
+  TERMINAL_ONLY: "terminal_only",
+  TO_MS: "to_ms"
+};
+var BOOL_OPTION_FIELDS = /* @__PURE__ */ new Set(["consistent_projection", "include_cold", "rev", "terminal_only"]);
+function optionMap(args) {
+  const payload = {};
+  for (let index = 0; index < args.length; ) {
+    const token = asText(args[index]).toUpperCase();
+    if (token === "ATTRIBUTE") {
+      if (index + 2 >= args.length) {
+        throw new FerricStoreError("ATTRIBUTE requires name and value");
+      }
+      const name = asText(args[index + 1]);
+      const attributes = ensureObjectField(payload, "attributes");
+      attributes[name] = args[index + 2];
+      index += 3;
+      continue;
+    }
+    if (token === "STATE_META") {
+      if (index + 2 >= args.length) {
+        throw new FerricStoreError("STATE_META requires name and value");
+      }
+      const name = asText(args[index + 1]);
+      const stateMeta = ensureObjectField(payload, "state_meta");
+      stateMeta[name] = args[index + 2];
+      index += 3;
+      continue;
+    }
+    const field2 = OPTION_FIELDS[token] ?? token.toLowerCase();
+    if (index + 1 >= args.length) {
+      throw new FerricStoreError(`${token} requires a value`);
+    }
+    const value = args[index + 1];
+    payload[field2] = BOOL_OPTION_FIELDS.has(field2) ? boolArg(value) : value;
+    index += 2;
+  }
+  return payload;
+}
+function ensureObjectField(payload, field2) {
+  const value = payload[field2];
+  if (isPlainObject(value)) {
+    return value;
+  }
+  const next = {};
+  payload[field2] = next;
+  return next;
+}
+function normalizeFlowSearchStateMeta(payload) {
+  const stateMeta = payload.state_meta;
+  if (!isPlainObject(stateMeta) || Object.keys(stateMeta).length === 0) {
+    return;
+  }
+  if (Object.values(stateMeta).every(isPlainObject)) {
+    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 isPlainObject(value) {
+  return typeof value === "object" && value != null && !Array.isArray(value) && !Buffer2.isBuffer(value) && !(value instanceof Uint8Array);
+}
 function parseFlowOptions(args, start, end, config) {
   const payload = {};
   const seen = /* @__PURE__ */ new Set();
@@ -1430,6 +1692,9 @@ var NativeAdapter = class _NativeAdapter {
     const command = buildProtocolCommand(args);
     return await this.request(command);
   }
+  async executeProtocolCommand(command, laneId) {
+    return await this.request(laneId == null ? command : { ...command, laneId });
+  }
   async executePipeline(commands, options = {}) {
     if (commands.length === 0) {
       return [];
@@ -1641,6 +1906,20 @@ var ReconnectingExecutor = class {
       return await Promise.all(commands.map((command) => executor.executeCommand(...command)));
     });
   }
+  async refreshTopology() {
+    const executor = await this.executorPromise;
+    if (executor.refreshTopology == null) {
+      throw new FerricStoreError("topology refresh requires a topology-aware native executor");
+    }
+    return await executor.refreshTopology();
+  }
+  async route(key) {
+    const executor = await this.executorPromise;
+    if (executor.route == null) {
+      throw new FerricStoreError("route lookup requires a topology-aware native executor");
+    }
+    return await executor.route(key);
+  }
   async close() {
     if (this.closed) {
       return;
@@ -1731,6 +2010,653 @@ function normalizeKeepAliveInitialDelay(value) {
   return Math.max(0, Math.trunc(value ?? 3e4));
 }
 
+// src/topology.ts
+import { Buffer as Buffer4 } from "buffer";
+var ROUTE_SLOT_COUNT = 1024;
+var ROUTE_SLOT_MASK = ROUTE_SLOT_COUNT - 1;
+var RoutingTopology = class _RoutingTopology {
+  routeEpoch;
+  shardCount;
+  slots;
+  endpoints;
+  constructor(routeEpoch, shardCount, slots, endpoints) {
+    this.routeEpoch = routeEpoch;
+    this.shardCount = shardCount;
+    this.slots = slots;
+    this.endpoints = endpoints;
+  }
+  static empty() {
+    return new _RoutingTopology(0, 0, Array.from({ length: ROUTE_SLOT_COUNT }), /* @__PURE__ */ new Map());
+  }
+  static build(payload) {
+    const ranges = getField(payload, "ranges");
+    if (!Array.isArray(ranges)) {
+      throw new FerricStoreError("invalid SHARDS topology payload", { raw: payload });
+    }
+    const slots = Array.from({ length: ROUTE_SLOT_COUNT });
+    const endpoints = /* @__PURE__ */ new Map();
+    for (const item of ranges) {
+      if (textOrUndefined(getField(item, "hint")) === "leader_unknown") {
+        throw new FerricStoreError("SHARDS range has no leader", { raw: item });
+      }
+      const first = numberOrUndefined(getField(item, "first_slot"));
+      const last = numberOrUndefined(getField(item, "last_slot"));
+      const shard = numberOrUndefined(getField(item, "shard"));
+      const laneId = numberOrUndefined(getField(item, "lane_id"));
+      const endpoint = endpointFromRange(item);
+      if (first == null || last == null || shard == null || laneId == null || first < 0 || last < first || last >= ROUTE_SLOT_COUNT) {
+        throw new FerricStoreError("invalid SHARDS range", { raw: item });
+      }
+      const endpointKey = endpointKeyFor(endpoint);
+      const route = {
+        endpoint,
+        endpointKey,
+        laneId,
+        leaderNode: endpoint.node,
+        shard
+      };
+      for (let slot = first; slot <= last; slot += 1) {
+        slots[slot] = route;
+      }
+      endpoints.set(endpointKey, endpoint);
+    }
+    return new _RoutingTopology(
+      numberOrUndefined(getField(payload, "route_epoch")) ?? 0,
+      numberOrUndefined(getField(payload, "shard_count")) ?? 0,
+      slots,
+      endpoints
+    );
+  }
+  static slotForKey(key) {
+    const textKey = Buffer4.isBuffer(key) ? key.toString("utf8") : key;
+    let hashInput;
+    if (textKey.startsWith("f:{")) {
+      hashInput = flowHashTag(textKey.slice(3), textKey);
+    } else if (textKey.startsWith("X:f:{")) {
+      hashInput = flowHashTag(textKey.slice(5), textKey);
+    } else {
+      hashInput = hashTagOrKey(textKey);
+    }
+    return crc32(Buffer4.from(hashInput)) & ROUTE_SLOT_MASK;
+  }
+  routeKey(key) {
+    const slot = _RoutingTopology.slotForKey(key);
+    const route = this.slots[slot];
+    if (route == null) {
+      throw new FerricStoreError(`no route for slot ${slot}`);
+    }
+    return { ...route, slot };
+  }
+};
+var TopologyNativeAdapterPool = class _TopologyNativeAdapterPool {
+  adapterOptions;
+  adapters = /* @__PURE__ */ new Map();
+  endpointPolicy;
+  endpointValidator;
+  seedEndpointKeys;
+  seedUrls;
+  tls;
+  trustedHosts;
+  warmConnections;
+  topologyValue = RoutingTopology.empty();
+  constructor(urls, options = {}) {
+    if (urls.length === 0) {
+      throw new FerricStoreError("TopologyNativeAdapterPool requires at least one seed URL");
+    }
+    this.seedUrls = [...urls];
+    this.endpointPolicy = options.endpointPolicy ?? "seed_hosts";
+    this.endpointValidator = options.endpointValidator;
+    this.warmConnections = options.warmConnections ?? false;
+    this.tls = options.tlsOptions != null || urls.some((url) => parseFerricUrl2(url).tls);
+    this.adapterOptions = nativeOnlyOptions(withSeedAuthDefaults(urls, options));
+    this.seedEndpointKeys = new Set(urls.map((url) => endpointKeyFor(endpointFromUrl(url))));
+    this.trustedHosts = normalizedHostSet(options.trustedHosts ?? []);
+  }
+  static async fromUrls(urls, options = {}) {
+    const pool = new _TopologyNativeAdapterPool(urls, options);
+    await pool.refreshTopology();
+    return pool;
+  }
+  get topology() {
+    return this.topologyValue;
+  }
+  async refreshTopology() {
+    let lastError;
+    for (const url of this.refreshCandidateUrls()) {
+      try {
+        const adapter = await this.adapterForUrl(url);
+        const topology = RoutingTopology.build(await adapter.executeCommand("SHARDS"));
+        this.topologyValue = topology;
+        if (this.warmConnections) {
+          await Promise.allSettled([...topology.endpoints.values()].map(async (endpoint) => await this.adapterForEndpoint(endpoint)));
+        }
+        return topology;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw new FerricStoreError("no FerricStore topology endpoint reachable", { raw: lastError });
+  }
+  route(key) {
+    const route = this.topologyValue.routeKey(key);
+    this.validateEndpoint(route.endpoint);
+    return route;
+  }
+  async executeCommand(...args) {
+    const routed = this.routeData(args);
+    if (routed == null) {
+      return await (await this.controlAdapter()).executeCommand(...args);
+    }
+    const adapter = await this.adapterForEndpoint(routed.route.endpoint);
+    try {
+      return await adapter.executeProtocolCommand(routed.command, routed.route.laneId);
+    } catch (error) {
+      if (isRetryableRouteError(error)) {
+        await this.refreshTopology().catch(() => void 0);
+      }
+      throw error;
+    }
+  }
+  async executePipeline(commands, options = {}) {
+    if (commands.length === 0) {
+      return [];
+    }
+    const route = this.singleRouteForCommands(commands);
+    if (route == null) {
+      return await (await this.controlAdapter()).executePipeline(commands, options);
+    }
+    const adapter = await this.adapterForEndpoint(route.endpoint);
+    try {
+      const response = await adapter.executeProtocolCommand(pipelineCommand(commands), route.laneId);
+      return unwrapPipelineResponse(response, options);
+    } catch (error) {
+      if (isRetryableRouteError(error)) {
+        await this.refreshTopology().catch(() => void 0);
+      }
+      throw error;
+    }
+  }
+  async close() {
+    await Promise.allSettled([...this.adapters.values()].map(async (adapter) => await adapter.close()));
+    this.adapters.clear();
+  }
+  routeData(args) {
+    if (args.length === 0) {
+      return void 0;
+    }
+    let command;
+    try {
+      command = buildProtocolCommand(args);
+    } catch {
+      return void 0;
+    }
+    const key = routingKey(args, command);
+    if (key == null) {
+      return void 0;
+    }
+    return { command, route: this.route(key) };
+  }
+  singleRouteForCommands(commands) {
+    let route;
+    for (const command of commands) {
+      const routed = this.routeData(command);
+      if (routed == null) {
+        return void 0;
+      }
+      const current = routed.route;
+      if (route == null) {
+        route = current;
+      } else if (route.endpointKey !== current.endpointKey || route.laneId !== current.laneId) {
+        return void 0;
+      }
+    }
+    return route;
+  }
+  async controlAdapter() {
+    for (const url of this.refreshCandidateUrls()) {
+      try {
+        return await this.adapterForUrl(url);
+      } catch {
+      }
+    }
+    return await this.adapterForUrl(this.seedUrls[0] ?? "ferric://127.0.0.1:6388");
+  }
+  async adapterForUrl(url) {
+    const endpoint = endpointFromUrl(url);
+    const key = endpointKeyFor(endpoint);
+    const existing = this.adapters.get(key);
+    if (existing != null) {
+      return existing;
+    }
+    const adapter = await NativeAdapter.fromUrl(url, this.adapterOptions);
+    this.adapters.set(key, adapter);
+    return adapter;
+  }
+  async adapterForEndpoint(endpoint) {
+    this.validateEndpoint(endpoint);
+    const key = endpointKeyFor(endpoint);
+    const existing = this.adapters.get(key);
+    if (existing != null) {
+      return existing;
+    }
+    const adapter = await NativeAdapter.fromUrl(urlFromEndpoint(endpoint, this.tls), this.adapterOptions);
+    this.adapters.set(key, adapter);
+    return adapter;
+  }
+  validateEndpoint(endpoint) {
+    let allowed;
+    if (this.endpointPolicy === "any" || this.endpointPolicy === "none") {
+      allowed = true;
+    } else if (this.endpointPolicy === "seed_hosts") {
+      allowed = this.seedEndpointKeys.has(endpointKeyFor(endpoint)) || this.trustedHosts.has(endpoint.host.toLowerCase());
+    } else if ("allowHosts" in this.endpointPolicy) {
+      allowed = normalizedHostSet(this.endpointPolicy.allowHosts).has(endpoint.host.toLowerCase());
+    } else {
+      throw new FerricStoreError("invalid endpoint policy", { raw: this.endpointPolicy });
+    }
+    if (!allowed) {
+      throw new FerricStoreError("unsafe learned endpoint", { raw: endpoint });
+    }
+    if (this.endpointValidator != null && !this.endpointValidator(endpoint)) {
+      throw new FerricStoreError("unsafe learned endpoint", { raw: endpoint });
+    }
+  }
+  refreshCandidateUrls() {
+    const urls = [
+      ...this.seedUrls,
+      ...[...this.topologyValue.endpoints.values()].map((endpoint) => urlFromEndpoint(endpoint, this.tls))
+    ];
+    return [...new Set(urls)];
+  }
+};
+function routingKey(args, command) {
+  const name = commandName(args);
+  if (command.opcode < 256 || name === "CLUSTER.KEYSLOT" || name === "SHARDS" || name === "ROUTE") {
+    return void 0;
+  }
+  const keyFromArgs = routingKeyFromArgs(name, args);
+  if (keyFromArgs != null) {
+    return keyFromArgs;
+  }
+  if (!isPlainObject2(command.payload)) {
+    return void 0;
+  }
+  for (const field2 of ["key", "partition_key", "id", "owner_flow_id", "parent_id", "root_id", "correlation_id", "scope"]) {
+    const value = getField(command.payload, field2);
+    if (typeof value === "string" || Buffer4.isBuffer(value)) {
+      return value;
+    }
+  }
+  const keys = getField(command.payload, "keys");
+  if (Array.isArray(keys)) {
+    return singleShardKey(keys);
+  }
+  const pairsValue = getField(command.payload, "pairs");
+  if (Array.isArray(pairsValue)) {
+    return singleShardKey(
+      pairsValue.filter((pair) => Array.isArray(pair) && pair.length > 0).map((pair) => pair[0])
+    );
+  }
+  return void 0;
+}
+function routingKeyFromArgs(name, args) {
+  if (name == null) {
+    return void 0;
+  }
+  if (name === "MGET" || name === "DEL") {
+    return singleShardKey(args.slice(1));
+  }
+  if (name === "MSET") {
+    const keys = [];
+    for (let index = 1; index < args.length; index += 2) {
+      keys.push(args[index]);
+    }
+    return singleShardKey(keys);
+  }
+  if (name === "BITOP") {
+    return bitopRoutingKey(args);
+  }
+  if (name === "RENAME" || name === "RENAMENX") {
+    return singleShardKey(args.slice(1, 3));
+  }
+  if (name === "XREAD" || name === "XREADGROUP") {
+    return streamReadRoutingKey(args);
+  }
+  if (name.startsWith("FLOW.")) {
+    return flowRoutingKey(name, args);
+  }
+  if (firstKeyCommands.has(name)) {
+    const key = args[1];
+    return typeof key === "string" || Buffer4.isBuffer(key) ? key : void 0;
+  }
+  return void 0;
+}
+function flowRoutingKey(name, args) {
+  const flowArgs = args.slice(1);
+  if (flowArgs.length === 0) {
+    return void 0;
+  }
+  if (name === "FLOW.CLAIM_DUE" || name === "FLOW.RECLAIM") {
+    return flowPartitionRoutingKey(flowArgs, 1);
+  }
+  if (name === "FLOW.CREATE_MANY" || name === "FLOW.COMPLETE_MANY" || name === "FLOW.TRANSITION_MANY" || name === "FLOW.RETRY_MANY" || name === "FLOW.FAIL_MANY" || name === "FLOW.CANCEL_MANY") {
+    const partition2 = flowArgs[0];
+    if (typeof partition2 === "string" && partition2.toUpperCase() !== "AUTO" && partition2.toUpperCase() !== "MIXED") {
+      return partition2;
+    }
+    if (Buffer4.isBuffer(partition2)) {
+      const text2 = partition2.toString("utf8").toUpperCase();
+      if (text2 !== "AUTO" && text2 !== "MIXED") {
+        return partition2;
+      }
+    }
+    return void 0;
+  }
+  const partition = flowPartitionRoutingKey(flowArgs, 1);
+  if (partition != null) {
+    return partition;
+  }
+  if (typeScopedFlowCommands.has(name)) {
+    return void 0;
+  }
+  const id = flowArgs[0];
+  return typeof id === "string" || Buffer4.isBuffer(id) ? id : void 0;
+}
+function bitopRoutingKey(args) {
+  if (args.length < 4) {
+    return void 0;
+  }
+  return singleShardKey(args.slice(2));
+}
+function streamReadRoutingKey(args) {
+  const streamsIndex = args.findIndex((arg) => commandPart(arg) === "STREAMS");
+  if (streamsIndex < 0) {
+    return void 0;
+  }
+  const streamArgs = args.slice(streamsIndex + 1);
+  if (streamArgs.length === 0 || streamArgs.length % 2 !== 0) {
+    return void 0;
+  }
+  return singleShardKey(streamArgs.slice(0, streamArgs.length / 2));
+}
+function flowPartitionRoutingKey(args, start) {
+  for (let index = start; index < args.length; index += 1) {
+    const token = commandPart(args[index]);
+    if (token === "PARTITION") {
+      const key = args[index + 1];
+      return typeof key === "string" || Buffer4.isBuffer(key) ? key : void 0;
+    }
+    if (token === "PARTITIONS") {
+      const count = Number(args[index + 1]);
+      if (!Number.isInteger(count) || count < 0) {
+        return void 0;
+      }
+      return singleShardKey(args.slice(index + 2, index + 2 + count));
+    }
+  }
+  return void 0;
+}
+function singleShardKey(keys) {
+  const usable = keys.filter((key) => typeof key === "string" || Buffer4.isBuffer(key));
+  if (usable.length === 0) {
+    return void 0;
+  }
+  const first = usable[0];
+  if (first == null) {
+    return void 0;
+  }
+  const firstSlot = RoutingTopology.slotForKey(first);
+  return usable.every((key) => RoutingTopology.slotForKey(key) === firstSlot) ? first : void 0;
+}
+function commandName(args) {
+  const first = commandPart(args[0]);
+  if (first == null) {
+    return void 0;
+  }
+  if (first === "FLOW" && args.length > 1) {
+    const second = commandPart(args[1]);
+    return second == null ? first : `${first}.${second}`;
+  }
+  if (first === "CLIENT" && args.length > 1) {
+    const second = commandPart(args[1]);
+    return second == null ? first : `${first}.${second}`;
+  }
+  if (first === "CLUSTER" && args.length > 1) {
+    const second = commandPart(args[1]);
+    return second == null ? first : `${first}.${second}`;
+  }
+  return first;
+}
+function commandPart(value) {
+  if (typeof value === "string") {
+    return value.toUpperCase();
+  }
+  if (Buffer4.isBuffer(value)) {
+    return value.toString("utf8").toUpperCase();
+  }
+  return void 0;
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value != null && !Array.isArray(value) && !Buffer4.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 = Buffer4.from(key);
+      for (const [itemKey, value] of source.entries()) {
+        if (Buffer4.isBuffer(itemKey) && itemKey.equals(bufferKey)) {
+          return value;
+        }
+      }
+    }
+    return void 0;
+  }
+  if (isPlainObject2(source)) {
+    for (const key of keys) {
+      if (key in source) return source[key];
+    }
+  }
+  return void 0;
+}
+function textOrUndefined(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (Buffer4.isBuffer(value)) {
+    return value.toString("utf8");
+  }
+  return void 0;
+}
+function numberOrUndefined(value) {
+  return typeof value === "number" && Number.isInteger(value) ? value : void 0;
+}
+function endpointFromRange(item) {
+  const endpointValue = getField(item, "endpoint");
+  const raw = isPlainObject2(endpointValue) || endpointValue instanceof Map ? endpointValue : item;
+  const host = textOrUndefined(getField(raw, "host", "native_host"));
+  const nativePort = numberOrUndefined(getField(raw, "native_port"));
+  if (host == null || nativePort == null) {
+    throw new FerricStoreError("invalid SHARDS endpoint", { raw: item });
+  }
+  const nativeTlsPort = numberOrUndefined(getField(raw, "native_tls_port"));
+  return {
+    host,
+    nativePort,
+    node: textOrUndefined(getField(raw, "node", "leader_node", "owner_node")) ?? host,
+    ...nativeTlsPort == null ? {} : { nativeTlsPort }
+  };
+}
+function endpointFromUrl(url) {
+  const parsed = parseFerricUrl2(url);
+  return {
+    host: parsed.host,
+    nativePort: parsed.port,
+    node: parsed.host,
+    ...parsed.tls ? { nativeTlsPort: parsed.port } : {}
+  };
+}
+function parseFerricUrl2(value) {
+  const url = new URL(value);
+  if (url.protocol !== "ferric:" && url.protocol !== "ferrics:") {
+    throw new FerricStoreError(`unsupported FerricStore URL scheme: ${url.protocol}`);
+  }
+  return {
+    host: url.hostname || "127.0.0.1",
+    ...url.password === "" ? {} : { password: decodeURIComponent(url.password) },
+    port: Number(url.port || (url.protocol === "ferrics:" ? 6389 : 6388)),
+    tls: url.protocol === "ferrics:",
+    ...url.username === "" ? {} : { username: decodeURIComponent(url.username) }
+  };
+}
+function endpointKeyFor(endpoint) {
+  return `${endpoint.host.toLowerCase()}:${endpoint.nativePort}`;
+}
+function urlFromEndpoint(endpoint, useTls) {
+  const port = useTls && endpoint.nativeTlsPort != null ? endpoint.nativeTlsPort : endpoint.nativePort;
+  const host = endpoint.host.includes(":") && !endpoint.host.startsWith("[") ? `[${endpoint.host}]` : endpoint.host;
+  return `${useTls ? "ferrics" : "ferric"}://${host}:${port}`;
+}
+function nativeOnlyOptions(options) {
+  const nativeOptions = { ...options };
+  delete nativeOptions.endpointPolicy;
+  delete nativeOptions.endpointValidator;
+  delete nativeOptions.haRouting;
+  delete nativeOptions.seeds;
+  delete nativeOptions.trustedHosts;
+  delete nativeOptions.warmConnections;
+  return nativeOptions;
+}
+function withSeedAuthDefaults(urls, options) {
+  const next = { ...options };
+  for (const url of urls) {
+    const parsed = parseFerricUrl2(url);
+    if (next.username == null && parsed.username != null) {
+      next.username = parsed.username;
+    }
+    if (next.password == null && parsed.password != null) {
+      next.password = parsed.password;
+    }
+    if (next.username != null && next.password != null) {
+      break;
+    }
+  }
+  return next;
+}
+function isRetryableRouteError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  return message.includes("connection closed") || message.includes("connection is closed") || message.includes("shard not available") || message.includes("leader") || message.includes("route");
+}
+function normalizedHostSet(hosts) {
+  return new Set(hosts.filter((host) => host != null && host !== "").map((host) => host.toLowerCase()));
+}
+function hashTagOrKey(key) {
+  const start = key.indexOf("{");
+  if (start < 0) {
+    return key;
+  }
+  const end = key.indexOf("}", start + 1);
+  return end > start + 1 ? key.slice(start + 1, end) : key;
+}
+function flowHashTag(rest, fallbackKey) {
+  const end = rest.indexOf("}");
+  return end > 0 ? rest.slice(0, end) : hashTagOrKey(fallbackKey);
+}
+var crc32Table = new Uint32Array(256);
+for (let index = 0; index < 256; index += 1) {
+  let value = index;
+  for (let bit = 0; bit < 8; bit += 1) {
+    value = (value & 1) !== 0 ? 3988292384 ^ value >>> 1 : value >>> 1;
+  }
+  crc32Table[index] = value >>> 0;
+}
+function crc32(buffer) {
+  let value = 4294967295;
+  for (const byte of buffer) {
+    value = value >>> 8 ^ (crc32Table[(value ^ byte) & 255] ?? 0);
+  }
+  return (value ^ 4294967295) >>> 0;
+}
+var firstKeyCommands = /* @__PURE__ */ new Set([
+  "BITCOUNT",
+  "BITFIELD",
+  "BITPOS",
+  "CAS",
+  "EXISTS",
+  "EXPIRE",
+  "EXPIREAT",
+  "FETCH_OR_COMPUTE",
+  "FETCH_OR_COMPUTE_ERROR",
+  "FETCH_OR_COMPUTE_RESULT",
+  "FERRICSTORE.KEY_INFO",
+  "GET",
+  "GETBIT",
+  "GETDEL",
+  "GETEX",
+  "HDEL",
+  "HEXISTS",
+  "HGET",
+  "HGETALL",
+  "HINCRBY",
+  "HKEYS",
+  "HLEN",
+  "HMGET",
+  "HMSET",
+  "HSET",
+  "HVALS",
+  "LOCK",
+  "LPOP",
+  "LPUSH",
+  "LRANGE",
+  "LREM",
+  "RATELIMIT.ADD",
+  "RPOP",
+  "RPUSH",
+  "SADD",
+  "SCARD",
+  "SISMEMBER",
+  "SMEMBERS",
+  "SREM",
+  "SET",
+  "SETBIT",
+  "STRLEN",
+  "TTL",
+  "TYPE",
+  "UNLINK",
+  "UNLOCK",
+  "XADD",
+  "XLEN",
+  "XRANGE",
+  "ZADD",
+  "ZCARD",
+  "ZRANGE",
+  "ZREM",
+  "ZSCORE"
+]);
+var typeScopedFlowCommands = /* @__PURE__ */ new Set([
+  "FLOW.APPROVAL.LIST",
+  "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"
+]);
+
 // src/codecs.ts
 var RawCodec = class {
   encode(value) {
@@ -1944,7 +2870,7 @@ function parseKvResponse(value) {
   return { value };
 }
 function autoPartitionKeyForId(id) {
-  return `${AUTO_PARTITION_PREFIX}${crc32(Buffer.from(id)) % AUTO_PARTITION_BUCKETS}`;
+  return `${AUTO_PARTITION_PREFIX}${crc322(Buffer.from(id)) % AUTO_PARTITION_BUCKETS}`;
 }
 function expandManyResponse(value, count) {
   if (Array.isArray(value) && value.length === count) {
@@ -2014,7 +2940,7 @@ function coerceDiagnosticValue(value) {
   }
   return value;
 }
-function crc32(buffer) {
+function crc322(buffer) {
   let crc = 4294967295;
   for (const byte of buffer) {
     crc ^= byte;
@@ -2940,14 +3866,14 @@ function claimedItemFromResp(value, codec) {
     const partition = tuple[1] == null ? null : bytes(tuple[1]);
     const leaseToken = bytes(tuple[2]);
     const fencingToken = integer(tuple[3]);
-    const attrs = tuple[5] ?? (isPlainObject(tuple[4]) ? tuple[4] : void 0);
+    const attrs = tuple[5] ?? (isPlainObject3(tuple[4]) ? tuple[4] : void 0);
     const item = {
       id: text(id),
       partitionKey: optionalString(partition),
       leaseToken,
       fencingToken,
       runState: optionalString(tuple[4]),
-      attributes: isPlainObject(attrs) ? attrs : void 0,
+      attributes: isPlainObject3(attrs) ? attrs : void 0,
       type: "",
       state: "running"
     };
@@ -3067,9 +3993,9 @@ function decodeValues(value, codec) {
 }
 function plainObjectField(value, key) {
   const item = field(value, key);
-  return isPlainObject(item) ? item : void 0;
+  return isPlainObject3(item) ? item : void 0;
 }
-function isPlainObject(value) {
+function isPlainObject3(value) {
   return typeof value === "object" && value != null && !Buffer.isBuffer(value) && !(value instanceof Uint8Array) && !Array.isArray(value);
 }
 
@@ -3121,7 +4047,18 @@ var FerricStoreClient = class _FerricStoreClient {
   }
   static async fromUrl(url, options = {}) {
     const reconnectOptions = options.reconnect ?? options.nativeOptions?.autoReconnect ?? true;
-    const createExecutor = async () => await NativeAdapter.fromUrl(url, options.nativeOptions);
+    const nativeOptions = options.nativeOptions ?? {};
+    const seeds = nativeOptions.seeds ?? [];
+    const createExecutor = async () => nativeOptions.haRouting === true || seeds.length > 0 ? await TopologyNativeAdapterPool.fromUrls([url, ...seeds], nativeOptions) : await NativeAdapter.fromUrl(url, nativeOptions);
+    const executor = reconnectOptions === false ? await createExecutor() : new ReconnectingExecutor(createExecutor, reconnectOptions === true ? {} : reconnectOptions);
+    return new _FerricStoreClient(executor, options);
+  }
+  static async fromUrls(urls, options = {}) {
+    if (urls.length === 0) {
+      throw new Error("FerricStoreClient.fromUrls requires at least one URL");
+    }
+    const reconnectOptions = options.reconnect ?? options.nativeOptions?.autoReconnect ?? true;
+    const createExecutor = async () => await TopologyNativeAdapterPool.fromUrls(urls, options.nativeOptions);
     const executor = reconnectOptions === false ? await createExecutor() : new ReconnectingExecutor(createExecutor, reconnectOptions === true ? {} : reconnectOptions);
     return new _FerricStoreClient(executor, options);
   }
@@ -3137,6 +4074,18 @@ var FerricStoreClient = class _FerricStoreClient {
   async close() {
     await this.executor.close?.();
   }
+  async refreshTopology() {
+    if (this.executor.refreshTopology == null) {
+      throw new Error("topology refresh requires a topology-aware native executor");
+    }
+    return await this.executor.refreshTopology();
+  }
+  async route(key) {
+    if (this.executor.route == null) {
+      throw new Error("route lookup requires a topology-aware native executor");
+    }
+    return await this.executor.route(key);
+  }
   async ping(message) {
     return await this.command("PING", ...message == null ? [] : [message]);
   }
@@ -3199,7 +4148,7 @@ var FerricStoreClient = class _FerricStoreClient {
     return response == null ? null : text(response);
   }
   async clientInfo() {
-    return text(await this.command("CLIENT", "INFO"));
+    return infoText(await this.command("CLIENT", "INFO"));
   }
   async clientList(options = {}) {
     return text(await this.command("CLIENT", "LIST", ...options.type == null ? [] : ["TYPE", options.type]));
@@ -3254,7 +4203,7 @@ var FerricStoreClient = class _FerricStoreClient {
     return Number(await this.command("PUBSUB", "NUMPAT"));
   }
   async aclSetUser(username, rules) {
-    return okResponse(await this.command("ACL", "SETUSER", username, ...rules));
+    return okResponse(await this.command("ACL", "SETUSER", username, ...ruleArgs(rules)));
   }
   async aclDelUser(...usernames) {
     return Number(await this.command("ACL", "DELUSER", ...usernames));
@@ -3265,6 +4214,9 @@ var FerricStoreClient = class _FerricStoreClient {
   async aclList() {
     return arrayResponse(await this.command("ACL", "LIST"));
   }
+  async aclListUsers() {
+    return await this.aclList();
+  }
   async aclWhoami() {
     return text(await this.command("ACL", "WHOAMI"));
   }
@@ -3360,6 +4312,54 @@ var FerricStoreClient = class _FerricStoreClient {
   async ferricstoreDoctor(...args) {
     return await this.command("FERRICSTORE.DOCTOR", ...args);
   }
+  async capabilities() {
+    return normalizeAdminResponse(await this.command("FERRICSTORE.CAPABILITIES"));
+  }
+  async ensureNamespace(prefix, attrs = {}) {
+    return normalizeAdminResponse(
+      await this.command("FERRICSTORE.NAMESPACE", "ENSURE", prefix, ...managementPairArgs(attrs))
+    );
+  }
+  async getNamespace(prefix) {
+    return normalizeAdminResponse(await this.command("FERRICSTORE.NAMESPACE", "GET", prefix));
+  }
+  async listNamespaces() {
+    return normalizeAdminResponse(await this.command("FERRICSTORE.NAMESPACE", "LIST"));
+  }
+  async deleteNamespace(prefix) {
+    return normalizeAdminResponse(await this.command("FERRICSTORE.NAMESPACE", "DELETE", prefix));
+  }
+  async setQuota(namespace, quotaSpec = {}) {
+    return normalizeAdminResponse(
+      await this.command("FERRICSTORE.QUOTA", "SET", namespace, ...managementPairArgs(quotaSpec))
+    );
+  }
+  async getQuota(namespace) {
+    return normalizeAdminResponse(await this.command("FERRICSTORE.QUOTA", "GET", namespace));
+  }
+  async quotaUsage(namespace) {
+    return normalizeAdminResponse(await this.command("FERRICSTORE.QUOTA", "USAGE", namespace));
+  }
+  async clusterInfo() {
+    return normalizeAdminResponse(await this.command("FERRICSTORE.TELEMETRY", "CLUSTER_INFO"));
+  }
+  async namespaceUsage(prefix) {
+    return normalizeAdminResponse(
+      await this.command("FERRICSTORE.TELEMETRY", "NAMESPACE_USAGE", prefix)
+    );
+  }
+  async flowQuery(attrs = {}) {
+    const response = normalizeAdminResponse(
+      await this.command("FERRICSTORE.TELEMETRY", "FLOW_QUERY", ...managementPairArgs(attrs))
+    );
+    return Array.isArray(response) ? [...response] : [];
+  }
+  async flowHistory(id, attrs = {}) {
+    const response = normalizeAdminResponse(
+      await this.command("FERRICSTORE.TELEMETRY", "FLOW_HISTORY", id, ...managementPairArgs(attrs))
+    );
+    return Array.isArray(response) ? [...response] : [];
+  }
   async create(id, options) {
     const currentNowMs = options.nowMs ?? nowMs();
     const args = [
@@ -3840,6 +4840,14 @@ var FerricStoreClient = class _FerricStoreClient {
   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.command(...args);
+    return Array.isArray(response) ? this.records(response) : [];
+  }
   async terminals(type, options = {}) {
     return await this.indexQuery("FLOW.TERMINALS", type, options);
   }
@@ -4009,6 +5017,18 @@ var ErrorMappingExecutor = class {
       throwMapped(error);
     }
   }
+  async refreshTopology() {
+    if (this.executor.refreshTopology == null) {
+      throw new Error("topology refresh requires a topology-aware native executor");
+    }
+    return await this.executor.refreshTopology();
+  }
+  async route(key) {
+    if (this.executor.route == null) {
+      throw new Error("route lookup requires a topology-aware native executor");
+    }
+    return await this.executor.route(key);
+  }
   async close() {
     await this.executor.close?.();
   }
@@ -4044,6 +5064,18 @@ var AutoBatchExecutor = class {
     }
     return await Promise.all(commands.map((command) => this.executor.executeCommand(...command)));
   }
+  async refreshTopology() {
+    if (this.executor.refreshTopology == null) {
+      throw new Error("topology refresh requires a topology-aware native executor");
+    }
+    return await this.executor.refreshTopology();
+  }
+  async route(key) {
+    if (this.executor.route == null) {
+      throw new Error("route lookup requires a topology-aware native executor");
+    }
+    return await this.executor.route(key);
+  }
   async close() {
     this.scheduled = false;
     if (this.timer != null) {
@@ -4204,7 +5236,7 @@ var neverAutoBatchCommandPrefixes = /* @__PURE__ */ new Set([
 ]);
 var neverAutoBatchCommands = /* @__PURE__ */ new Set(["FLOW.CLAIM_DUE", "FLOW.RECLAIM"]);
 function autoBatchCommandAllowed(command, mode) {
-  const name = commandName(command);
+  const name = commandName2(command);
   if (name == null || neverAutoBatchCommands.has(name)) {
     return false;
   }
@@ -4214,18 +5246,18 @@ function autoBatchCommandAllowed(command, mode) {
   }
   return mode === "all" || safeAutoBatchCommands.has(name);
 }
-function commandName(command) {
-  const first = commandPart(command[0]);
+function commandName2(command) {
+  const first = commandPart2(command[0]);
   if (first == null) {
     return null;
   }
   if (first === "FLOW" && command.length > 1) {
-    const second = commandPart(command[1]);
+    const second = commandPart2(command[1]);
     return second == null ? first : `${first}.${second}`;
   }
   return first;
 }
-function commandPart(value) {
+function commandPart2(value) {
   if (typeof value === "string") {
     return value.toUpperCase();
   }
@@ -4250,6 +5282,67 @@ function appendStateMeta(args, stateMeta) {
     args.push("STATE_META", name, value);
   }
 }
+function appendAttributes(args, attributes) {
+  for (const [name, value] of Object.entries(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]) => isPlainObject4(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);
+}
+function infoText(value) {
+  if (typeof value === "string" || Buffer.isBuffer(value)) {
+    return text(value);
+  }
+  const normalized = normalizeRefMeta(value);
+  if (isPlainObject4(normalized)) {
+    return Object.entries(normalized).map(([key, item]) => `${key}=${diagnosticValueText(item)}`).join(" ");
+  }
+  return diagnosticValueText(normalized);
+}
+function diagnosticValueText(value) {
+  if (value == null) {
+    return "";
+  }
+  if (Buffer.isBuffer(value)) {
+    return value.toString("utf8");
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+function managementPairArgs(pairs2) {
+  const args = [];
+  for (const [key, value] of Object.entries(pairs2)) {
+    if (value != null) {
+      args.push(key.toUpperCase(), value);
+    }
+  }
+  return args;
+}
+function ruleArgs(rules) {
+  return typeof rules === "string" ? [rules] : [...rules];
+}
+function isPlainObject4(value) {
+  return typeof value === "object" && value != null && !Array.isArray(value) && !Buffer.isBuffer(value);
+}
 function sharedCreateManyStateMeta(items, stateMeta) {
   const itemMetas = items.map((item) => item.stateMeta).filter((meta) => meta != null);
   if (itemMetas.length === 0) {
@@ -5222,6 +6315,7 @@ function valueRefToString(value) {
 export {
   BitmapStore,
   BloomFilterStore,
+  COMMAND_OPCODES,
   CountMinSketchStore,
   CuckooFilterStore,
   FerricStoreClient,
@@ -5246,12 +6340,14 @@ export {
   QueueWorker,
   RawCodec,
   ReconnectingExecutor,
+  RoutingTopology,
   SetStore,
   SortedSetStore,
   StaleLeaseError,
   StreamStore,
   TDigestStore,
   TopKStore,
+  TopologyNativeAdapterPool,
   Workflow,
   WorkflowClient,
   WorkflowContext,