@lunora/runtime 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/createQueryCoordinator-DbxC7iUz.mjs

@@ -0,0 +1,838 @@
+import { LunoraError } from './LunoraError-CL0aOtpo.mjs';
+import { resolveShard } from './resolveShard-DDkzWtrU.mjs';
+
+const createStaticShardRegistry = (table_to_keys) => {
+  return {
+    listShardKeys(table) {
+      return table_to_keys[table] ?? [];
+    }
+  };
+};
+const mergeStrategyForAggregate = (input) => {
+  if (input.kind === "count") {
+    return { kind: "sum" };
+  }
+  if (input.kind === "scalar") {
+    if (input.op === "count" || input.op === "sum") {
+      return { kind: "sum" };
+    }
+    if (input.op === "max") {
+      return { kind: "max" };
+    }
+    if (input.op === "min") {
+      return { kind: "min" };
+    }
+    throw new LunoraError('aggregate({ op: "avg" }) is not supported across shards in v1 — fan out sum + count separately', {
+      code: "BAD_REQUEST",
+      status: 400
+    });
+  }
+  const op = input.agg?.op ?? "count";
+  if (op === "count" || op === "sum") {
+    return { kind: "groupBy", op: "sum" };
+  }
+  if (op === "max") {
+    return { kind: "groupBy", op: "max" };
+  }
+  if (op === "min") {
+    return { kind: "groupBy", op: "min" };
+  }
+  throw new LunoraError('groupBy({ agg: { op: "avg" } }) is not supported across shards in v1 — fan out sum + count separately', {
+    code: "BAD_REQUEST",
+    status: 400
+  });
+};
+const DEFAULT_CONCURRENCY = 16;
+const DEFAULT_TIMEOUT_MS = 5e3;
+const unwrapResult = (value) => value !== null && typeof value === "object" && "result" in value ? value.result : value;
+const readRunCounts = (payload) => {
+  const run = payload ?? {};
+  return {
+    changed: typeof run.changed === "number" ? run.changed : 0,
+    processed: typeof run.processed === "number" ? run.processed : 0,
+    status: typeof run.status === "string" ? run.status : void 0
+  };
+};
+const rollUpStatus = (anyFailed, incomplete) => {
+  if (anyFailed) {
+    return "failed";
+  }
+  if (incomplete) {
+    return "in_progress";
+  }
+  return "completed";
+};
+const rollUpMigration = (results) => {
+  const shards = [];
+  let ok = 0;
+  let failed = 0;
+  let changed = 0;
+  let processed = 0;
+  let anyInProgress = false;
+  let anyFailed = false;
+  for (const result of results) {
+    if (result.kind === "err") {
+      failed += 1;
+      shards.push({ error: { message: result.message, timedOut: result.timedOut }, shardKey: result.shardKey });
+      continue;
+    }
+    ok += 1;
+    const payload = unwrapResult(result.value);
+    const counts = readRunCounts(payload);
+    changed += counts.changed;
+    processed += counts.processed;
+    anyInProgress ||= counts.status === "in_progress";
+    anyFailed ||= counts.status === "failed";
+    shards.push({ result: payload, shardKey: result.shardKey });
+  }
+  return { changed, failed, ok, processed, shards, status: rollUpStatus(anyFailed, anyInProgress || failed > 0) };
+};
+const readRankCounts = (payload) => {
+  const run = payload ?? {};
+  return {
+    before: typeof run.before === "number" && Number.isFinite(run.before) ? run.before : 0,
+    total: typeof run.total === "number" && Number.isFinite(run.total) ? run.total : 0
+  };
+};
+const rollUpRank = (results) => {
+  const shards = [];
+  let ok = 0;
+  let failed = 0;
+  let before = 0;
+  let total = 0;
+  for (const result of results) {
+    if (result.kind === "err") {
+      failed += 1;
+      shards.push({ error: { message: result.message, timedOut: result.timedOut }, shardKey: result.shardKey });
+      continue;
+    }
+    ok += 1;
+    const counts = readRankCounts(unwrapResult(result.value));
+    before += counts.before;
+    total += counts.total;
+    shards.push({ result: counts, shardKey: result.shardKey });
+  }
+  return { failed, ok, partial: failed > 0, position: before + 1, shards, total };
+};
+const RANK_CLASS_NULL = 0;
+const RANK_CLASS_NUMBER = 1;
+const RANK_CLASS_TEXT = 2;
+const rankValueClass = (value) => {
+  if (value === null || value === void 0) {
+    return RANK_CLASS_NULL;
+  }
+  if (typeof value === "number") {
+    return RANK_CLASS_NUMBER;
+  }
+  return RANK_CLASS_TEXT;
+};
+const compareRankValueAsc = (a, b) => {
+  const classA = rankValueClass(a);
+  const classB = rankValueClass(b);
+  if (classA !== classB) {
+    return classA < classB ? -1 : 1;
+  }
+  if (classA === RANK_CLASS_NULL) {
+    return 0;
+  }
+  if (classA === RANK_CLASS_NUMBER) {
+    const numberA = a;
+    const numberB = b;
+    if (numberA < numberB) {
+      return -1;
+    }
+    return numberA > numberB ? 1 : 0;
+  }
+  const textA = String(a);
+  const textB = String(b);
+  if (textA < textB) {
+    return -1;
+  }
+  return textA > textB ? 1 : 0;
+};
+const compareRankKeys = (a, b, directions) => {
+  const partitionCmp = compareRankValueAsc(a.partitionKey, b.partitionKey);
+  if (partitionCmp !== 0) {
+    return partitionCmp;
+  }
+  const length = Math.max(a.sortValues.length, b.sortValues.length);
+  for (let i = 0; i < length; i += 1) {
+    const valueCmp = compareRankValueAsc(a.sortValues[i], b.sortValues[i]);
+    if (valueCmp !== 0) {
+      return directions[i] === "desc" ? -valueCmp : valueCmp;
+    }
+  }
+  return compareRankValueAsc(a.rowId, b.rowId);
+};
+const encodeRankPageCursor = (state) => {
+  const json = JSON.stringify(state);
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCodePoint(byte);
+  }
+  return btoa(binary);
+};
+const decodeRankPageCursor = (cursor) => {
+  let json;
+  try {
+    const binary = atob(cursor);
+    const bytes = Uint8Array.from(binary, (character) => character.codePointAt(0) ?? 0);
+    json = new TextDecoder().decode(bytes);
+  } catch {
+    return { perShard: {} };
+  }
+  try {
+    const parsed = JSON.parse(json);
+    if (parsed !== null && typeof parsed === "object" && "perShard" in parsed) {
+      const { perShard } = parsed;
+      if (perShard !== null && typeof perShard === "object") {
+        return { perShard };
+      }
+    }
+  } catch {
+  }
+  return { perShard: {} };
+};
+const readRankPageResult = (payload) => {
+  const value = payload ?? {};
+  const rows = Array.isArray(value.rows) ? value.rows : [];
+  const directions = Array.isArray(value.directions) ? value.directions : [];
+  return { directions, hasMore: value.hasMore === true, rows };
+};
+const pickSmallestHead = (slices, directions) => {
+  let best;
+  let bestKey;
+  for (const slice of slices) {
+    const candidate = slice.rows[slice.head];
+    if (candidate === void 0) {
+      continue;
+    }
+    if (bestKey === void 0 || compareRankKeys(candidate.key, bestKey, directions) < 0) {
+      best = slice;
+      bestKey = candidate.key;
+    }
+  }
+  return best;
+};
+const buildNextRankPageCursor = (slices, lastConsumedKey) => {
+  let anyRemaining = false;
+  const sliceKeys = /* @__PURE__ */ new Set();
+  for (const slice of slices) {
+    sliceKeys.add(slice.shardKey);
+    if (slice.head < slice.rows.length || slice.hasMore) {
+      anyRemaining = true;
+    }
+  }
+  const perShard = { ...lastConsumedKey };
+  for (const shardKey of Object.keys(lastConsumedKey)) {
+    if (!sliceKeys.has(shardKey)) {
+      anyRemaining = true;
+    }
+  }
+  if (!anyRemaining) {
+    return null;
+  }
+  return encodeRankPageCursor({ perShard });
+};
+const kWayMergeRankPages = (slices, take, directions, priorPerShard) => {
+  const page = [];
+  const lastConsumedKey = { ...priorPerShard };
+  while (page.length < take) {
+    const best = pickSmallestHead(slices, directions);
+    if (best === void 0) {
+      break;
+    }
+    const row = best.rows[best.head];
+    if (row !== void 0) {
+      page.push(row.doc);
+      lastConsumedKey[best.shardKey] = row.key;
+    }
+    best.head += 1;
+  }
+  const nextCursor = buildNextRankPageCursor(slices, lastConsumedKey);
+  return { isDone: nextCursor === null, nextCursor, page };
+};
+const rollUpExport = (results) => {
+  const shards = [];
+  let ok = 0;
+  let failed = 0;
+  for (const result of results) {
+    if (result.kind === "err") {
+      failed += 1;
+      shards.push({ error: { message: result.message, timedOut: result.timedOut }, shardKey: result.shardKey });
+      continue;
+    }
+    ok += 1;
+    const payload = unwrapResult(result.value);
+    const rows = Array.isArray(payload?.rows) ? payload.rows : [];
+    shards.push({ rows, shardKey: result.shardKey });
+  }
+  return { failed, ok, shards };
+};
+const rollUpCdcSync = (results) => {
+  const shards = [];
+  let ok = 0;
+  let failed = 0;
+  for (const { outcome, sinceSeq } of results) {
+    if (outcome.kind === "err") {
+      failed += 1;
+      shards.push({ cursor: sinceSeq, error: { message: outcome.message, timedOut: outcome.timedOut }, shardKey: outcome.shardKey });
+      continue;
+    }
+    ok += 1;
+    const payload = unwrapResult(outcome.value);
+    const changes = Array.isArray(payload?.changes) ? payload.changes : [];
+    const cursor = typeof payload?.cursor === "number" ? payload.cursor : sinceSeq;
+    shards.push({ changes, cursor, shardKey: outcome.shardKey });
+  }
+  return { failed, ok, shards };
+};
+const rollUpApplyCdc = (results) => {
+  let ok = 0;
+  let failed = 0;
+  let applied = 0;
+  for (const outcome of results) {
+    if (outcome.kind === "err") {
+      failed += 1;
+      continue;
+    }
+    ok += 1;
+    const payload = unwrapResult(outcome.value);
+    applied += typeof payload?.applied === "number" ? payload.applied : 0;
+  }
+  return { applied, failed, ok };
+};
+const readShardRequests = (payload) => {
+  const snapshot = payload ?? {};
+  return typeof snapshot.requests === "number" && Number.isFinite(snapshot.requests) && snapshot.requests >= 0 ? snapshot.requests : 0;
+};
+const rollUpShardTraffic = (results) => {
+  const shards = [];
+  let ok = 0;
+  let failed = 0;
+  for (const result of results) {
+    if (result.kind === "err") {
+      failed += 1;
+      shards.push({ requests: 0, shardKey: result.shardKey });
+      continue;
+    }
+    ok += 1;
+    shards.push({ requests: readShardRequests(unwrapResult(result.value)), shardKey: result.shardKey });
+  }
+  return { failed, ok, shards };
+};
+const rollUpImport = (results) => {
+  const shards = [];
+  const inserted = {};
+  const errors = [];
+  let conflicts = 0;
+  let ok = 0;
+  let failed = 0;
+  for (const result of results) {
+    if (result.kind === "err") {
+      failed += 1;
+      shards.push({ error: { message: result.message, timedOut: result.timedOut }, shardKey: result.shardKey });
+      continue;
+    }
+    ok += 1;
+    const payload = unwrapResult(result.value);
+    const shardInserted = payload?.inserted ?? {};
+    for (const [table, count] of Object.entries(shardInserted)) {
+      inserted[table] = (inserted[table] ?? 0) + count;
+    }
+    const payloadErrors = payload?.errors;
+    if (Array.isArray(payloadErrors)) {
+      errors.push(...payloadErrors);
+    }
+    conflicts += payload?.conflicts ?? 0;
+    shards.push({
+      result: {
+        conflicts: payload?.conflicts ?? 0,
+        errors: payload?.errors ?? [],
+        inserted: shardInserted
+      },
+      shardKey: result.shardKey
+    });
+  }
+  return { conflicts, errors, failed, inserted, ok, shards };
+};
+const prepareShardRpc = (request) => {
+  return {
+    body: JSON.stringify({ args: request.args ?? {}, functionPath: request.functionPath }),
+    headers: { "content-type": "application/json", ...request.headers }
+  };
+};
+const callOneShard = async (namespace, shardKey, prepared, timeoutMs) => {
+  const stub = resolveShard(namespace, shardKey);
+  const controller = new AbortController();
+  const forwarded = new Request("https://shard.internal/rpc", {
+    body: prepared.body,
+    headers: prepared.headers,
+    method: "POST",
+    signal: controller.signal
+  });
+  let timeoutId;
+  const timeoutPromise = new Promise((resolve) => {
+    timeoutId = setTimeout(() => {
+      try {
+        controller.abort();
+      } catch {
+      }
+      resolve({ kind: "err", message: `shard "${shardKey}" timed out after ${String(timeoutMs)}ms`, shardKey, timedOut: true });
+    }, timeoutMs);
+  });
+  const fetchPromise = (async () => {
+    try {
+      const response = await stub.fetch(forwarded);
+      if (!response.ok) {
+        return { kind: "err", message: `shard "${shardKey}" returned ${String(response.status)}`, shardKey, timedOut: false };
+      }
+      const value = await response.json();
+      return { kind: "ok", shardKey, value };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { kind: "err", message: `shard "${shardKey}" threw: ${message}`, shardKey, timedOut: false };
+    }
+  })();
+  try {
+    return await Promise.race([fetchPromise, timeoutPromise]);
+  } finally {
+    if (timeoutId !== void 0) {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+const runBoundedFanOut = async (namespace, keys, request, maxConcurrency, timeoutMs) => {
+  if (keys.length === 0) {
+    return [];
+  }
+  const prepared = prepareShardRpc(request);
+  const outcomes = Array.from({ length: keys.length });
+  let cursor = 0;
+  const worker = async () => {
+    while (true) {
+      const index = cursor;
+      cursor += 1;
+      const shardKey = keys[index];
+      if (index >= keys.length || shardKey === void 0) {
+        return;
+      }
+      outcomes[index] = await callOneShard(namespace, shardKey, prepared, timeoutMs);
+    }
+  };
+  const concurrency = Math.min(maxConcurrency, keys.length);
+  await Promise.all(Array.from({ length: concurrency }, () => worker()));
+  return outcomes;
+};
+const compareCodeUnits = (a, b) => {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+};
+const canonicalJson = (record) => {
+  const ordered = {};
+  for (const key of Object.keys(record).toSorted(compareCodeUnits)) {
+    ordered[key] = record[key] ?? null;
+  }
+  return JSON.stringify(ordered);
+};
+const mergeConcat = (values) => {
+  const out = [];
+  for (const v of values) {
+    if (Array.isArray(v)) {
+      out.push(...v);
+    }
+  }
+  return out;
+};
+const combineGroupByValue = (current, incoming, op) => {
+  switch (op) {
+    case "max": {
+      return Math.max(current, incoming);
+    }
+    case "min": {
+      return Math.min(current, incoming);
+    }
+    case "sum": {
+      return current + incoming;
+    }
+    default: {
+      return current;
+    }
+  }
+};
+const accumulateGroupByEntry = (merged, entry, op) => {
+  if (entry === null || typeof entry !== "object") {
+    return;
+  }
+  const entryKey = entry.key ?? {};
+  const entryValue = entry.value ?? null;
+  const stableKey = canonicalJson(entryKey);
+  const existing = merged.get(stableKey);
+  if (!existing) {
+    merged.set(stableKey, { key: entryKey, value: entryValue });
+    return;
+  }
+  if (existing.value === null) {
+    existing.value = entryValue;
+    return;
+  }
+  if (entryValue === null) {
+    return;
+  }
+  existing.value = combineGroupByValue(existing.value, entryValue, op);
+};
+const mergeGroupBy = (values, op) => {
+  const merged = /* @__PURE__ */ new Map();
+  for (const v of values) {
+    if (!Array.isArray(v)) {
+      continue;
+    }
+    for (const entry of v) {
+      accumulateGroupByEntry(merged, entry, op);
+    }
+  }
+  return [...merged.values()];
+};
+const mergeNumeric = (values, pick) => {
+  let best = null;
+  for (const v of values) {
+    if (typeof v === "number" && Number.isFinite(v)) {
+      best = best === null ? v : pick(best, v);
+    }
+  }
+  return best;
+};
+const mergeSum = (values) => {
+  let total = 0;
+  for (const v of values) {
+    if (typeof v === "number" && Number.isFinite(v)) {
+      total += v;
+    }
+  }
+  return total;
+};
+const mergeRank = (values) => {
+  let before = 0;
+  let total = 0;
+  for (const v of values) {
+    if (v === null || typeof v !== "object") {
+      continue;
+    }
+    const payload = v;
+    if (typeof payload.before === "number" && Number.isFinite(payload.before)) {
+      before += payload.before;
+    }
+    if (typeof payload.total === "number" && Number.isFinite(payload.total)) {
+      total += payload.total;
+    }
+  }
+  return { position: before + 1, total };
+};
+const mergeTopK = (values, strategy) => {
+  const collected = [];
+  for (const v of values) {
+    if (!Array.isArray(v)) {
+      continue;
+    }
+    for (const row of v) {
+      if (row === null || typeof row !== "object") {
+        continue;
+      }
+      const raw = row[strategy.by];
+      const score = typeof raw === "number" && Number.isFinite(raw) ? raw : Number.NEGATIVE_INFINITY;
+      collected.push({ row, score });
+    }
+  }
+  const direction = strategy.direction ?? "desc";
+  collected.sort((a, b) => direction === "asc" ? a.score - b.score : b.score - a.score);
+  return collected.slice(0, strategy.k).map((entry) => entry.row);
+};
+const mergeShardResults = (values, strategy) => {
+  switch (strategy.kind) {
+    case "concat": {
+      return mergeConcat(values);
+    }
+    case "first": {
+      return values[0];
+    }
+    case "groupBy": {
+      return mergeGroupBy(values, strategy.op ?? "sum");
+    }
+    case "max": {
+      return mergeNumeric(values, (best, candidate) => Math.max(best, candidate));
+    }
+    case "min": {
+      return mergeNumeric(values, (best, candidate) => Math.min(best, candidate));
+    }
+    case "rank": {
+      return mergeRank(values);
+    }
+    case "sum": {
+      return mergeSum(values);
+    }
+    case "topK": {
+      return mergeTopK(values, strategy);
+    }
+    default: {
+      return values;
+    }
+  }
+};
+const createQueryCoordinator = (options) => {
+  const maxConcurrency = options.maxConcurrency ?? DEFAULT_CONCURRENCY;
+  const perShardTimeoutMs = options.perShardTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (maxConcurrency < 1) {
+    throw new LunoraError("maxConcurrency must be >= 1", { code: "BAD_REQUEST", status: 400 });
+  }
+  return {
+    async fanOut(namespace, request) {
+      const keys = await options.registry.listShardKeys(request.fanOut.table);
+      const results = await runBoundedFanOut(namespace, keys, request, maxConcurrency, perShardTimeoutMs);
+      const okValues = [];
+      const okShards = [];
+      const errors = [];
+      for (const result of results) {
+        if (result.kind === "ok") {
+          okValues.push(result.value);
+          okShards.push(result.shardKey);
+        } else {
+          errors.push({ message: result.message, shardKey: result.shardKey, timedOut: result.timedOut });
+        }
+      }
+      const merged = mergeShardResults(okValues, request.fanOut.merge);
+      return {
+        data: merged,
+        errors,
+        failed: errors.length,
+        ok: okShards.length
+      };
+    },
+    async orchestrateExport(namespace, request) {
+      const union = /* @__PURE__ */ new Set();
+      const perTableKeys = await Promise.all(request.tables.map(async (table) => options.registry.listShardKeys(table)));
+      for (const keys of perTableKeys) {
+        for (const key of keys) {
+          union.add(key);
+        }
+      }
+      const shardKeys = [...union];
+      const exportRequest = {
+        // Spread the caller's `args` (`batchSize`, future export knobs)
+        // before the `tables` field so they reach the shard RPC. The
+        // earlier `{ tables }` literal silently dropped them.
+        args: { ...request.args, tables: [...request.tables] },
+        functionPath: "__lunora_admin__:exportShard",
+        headers: request.headers
+      };
+      const results = await runBoundedFanOut(namespace, shardKeys, exportRequest, maxConcurrency, perShardTimeoutMs);
+      return rollUpExport(results);
+    },
+    async orchestrateCdcSync(namespace, request) {
+      const union = /* @__PURE__ */ new Set();
+      const perTableKeys = await Promise.all(request.tables.map(async (table) => options.registry.listShardKeys(table)));
+      for (const keys of perTableKeys) {
+        for (const key of keys) {
+          union.add(key);
+        }
+      }
+      const shardKeys = [...union];
+      const cursors = request.cursors ?? {};
+      const results = Array.from({ length: shardKeys.length });
+      let cursor = 0;
+      const concurrency = Math.min(maxConcurrency, shardKeys.length);
+      const worker = async () => {
+        while (true) {
+          const index = cursor;
+          cursor += 1;
+          const shardKey = shardKeys[index];
+          if (index >= shardKeys.length || shardKey === void 0) {
+            return;
+          }
+          const sinceSeq = cursors[shardKey] ?? 0;
+          const outcome = await callOneShard(
+            namespace,
+            shardKey,
+            prepareShardRpc({
+              args: { limit: request.limit, sinceSeq },
+              functionPath: "__lunora_admin__:cdcSync",
+              headers: request.headers
+            }),
+            perShardTimeoutMs
+          );
+          results[index] = { outcome, sinceSeq };
+        }
+      };
+      if (concurrency > 0) {
+        await Promise.all(Array.from({ length: concurrency }, () => worker()));
+      }
+      return rollUpCdcSync(results);
+    },
+    async orchestrateImport(namespace, request) {
+      const { batches } = request;
+      const outcomes = Array.from({ length: batches.length });
+      let cursor = 0;
+      const concurrency = Math.min(maxConcurrency, batches.length);
+      const worker = async () => {
+        while (true) {
+          const index = cursor;
+          cursor += 1;
+          const batch = batches[index];
+          if (index >= batches.length || batch === void 0) {
+            return;
+          }
+          outcomes[index] = await callOneShard(
+            namespace,
+            batch.shardKey,
+            prepareShardRpc({
+              args: { rows: [...batch.rows], startLine: batch.startLine ?? 1 },
+              functionPath: "__lunora_admin__:importShard",
+              headers: request.headers
+            }),
+            perShardTimeoutMs
+          );
+        }
+      };
+      if (concurrency > 0) {
+        await Promise.all(Array.from({ length: concurrency }, () => worker()));
+      }
+      return rollUpImport(outcomes);
+    },
+    async orchestrateApplyCdc(namespace, request) {
+      const { batches } = request;
+      const outcomes = Array.from({ length: batches.length });
+      let cursor = 0;
+      const concurrency = Math.min(maxConcurrency, batches.length);
+      const worker = async () => {
+        while (true) {
+          const index = cursor;
+          cursor += 1;
+          const batch = batches[index];
+          if (index >= batches.length || batch === void 0) {
+            return;
+          }
+          outcomes[index] = await callOneShard(
+            namespace,
+            batch.shardKey,
+            prepareShardRpc({
+              args: { changes: [...batch.changes] },
+              functionPath: "__lunora_admin__:applyCdc",
+              headers: request.headers
+            }),
+            perShardTimeoutMs
+          );
+        }
+      };
+      if (concurrency > 0) {
+        await Promise.all(Array.from({ length: concurrency }, () => worker()));
+      }
+      return rollUpApplyCdc(outcomes);
+    },
+    async orchestrateMigration(namespace, request) {
+      const keys = await options.registry.listShardKeys(request.table);
+      const results = await runBoundedFanOut(namespace, keys, request, maxConcurrency, perShardTimeoutMs);
+      return rollUpMigration(results);
+    },
+    async orchestrateRank(namespace, request) {
+      const keys = await options.registry.listShardKeys(request.table);
+      const rankRequest = {
+        args: {
+          index: request.index,
+          partitionKey: request.partitionKey,
+          rowId: request.rowId,
+          sortValues: [...request.sortValues],
+          table: request.table
+        },
+        functionPath: "__lunora_admin__:rankBefore",
+        headers: request.headers
+      };
+      const results = await runBoundedFanOut(namespace, keys, rankRequest, maxConcurrency, perShardTimeoutMs);
+      return rollUpRank(results);
+    },
+    async orchestrateRankPage(namespace, request) {
+      const keys = await options.registry.listShardKeys(request.table);
+      const take = Math.max(1, Math.min(1e3, Math.floor(request.take ?? 100)));
+      const requestedDirections = request.directions ?? [];
+      const cursorState = request.cursor ? decodeRankPageCursor(request.cursor) : { perShard: {} };
+      const outcomes = Array.from({ length: keys.length });
+      let cursor = 0;
+      const concurrency = Math.min(maxConcurrency, keys.length);
+      const worker = async () => {
+        while (true) {
+          const index = cursor;
+          cursor += 1;
+          const shardKey = keys[index];
+          if (index >= keys.length || shardKey === void 0) {
+            return;
+          }
+          const shardCursorKey = cursorState.perShard[shardKey];
+          const args = {
+            index: request.index,
+            table: request.table,
+            take
+          };
+          if (request.partitionKey !== void 0) {
+            args["partitionKey"] = request.partitionKey;
+          }
+          if (shardCursorKey !== void 0) {
+            args["after"] = shardCursorKey;
+          }
+          const outcome = await callOneShard(
+            namespace,
+            shardKey,
+            prepareShardRpc({ args, functionPath: "__lunora_admin__:rankPage", headers: request.headers }),
+            perShardTimeoutMs
+          );
+          if (outcome.kind === "err") {
+            outcomes[index] = { error: { message: outcome.message, timedOut: outcome.timedOut }, shardKey };
+            continue;
+          }
+          const payload = readRankPageResult(unwrapResult(outcome.value));
+          outcomes[index] = { directions: payload.directions, hasMore: payload.hasMore, rows: payload.rows, shardKey };
+        }
+      };
+      if (concurrency > 0) {
+        await Promise.all(Array.from({ length: concurrency }, () => worker()));
+      }
+      const slices = [];
+      let ok = 0;
+      let failed = 0;
+      let reportedDirections;
+      for (const outcome of outcomes) {
+        if (outcome.error) {
+          failed += 1;
+          continue;
+        }
+        ok += 1;
+        if (reportedDirections === void 0 && outcome.directions && outcome.directions.length > 0) {
+          reportedDirections = outcome.directions;
+        }
+        slices.push({ hasMore: outcome.hasMore ?? false, head: 0, rows: outcome.rows ?? [], shardKey: outcome.shardKey });
+      }
+      const merged = kWayMergeRankPages(slices, take, reportedDirections ?? requestedDirections, cursorState.perShard);
+      return {
+        continueCursor: merged.nextCursor,
+        failed,
+        isDone: merged.isDone,
+        ok,
+        page: merged.page,
+        partial: failed > 0,
+        shards: outcomes
+      };
+    },
+    async orchestrateShardTraffic(namespace, request) {
+      const keys = await options.registry.listShardKeys(request.table);
+      const trafficRequest = {
+        functionPath: "__lunora_admin__:getMetrics",
+        headers: request.headers
+      };
+      const results = await runBoundedFanOut(namespace, keys, trafficRequest, maxConcurrency, perShardTimeoutMs);
+      return rollUpShardTraffic(results);
+    },
+    registry: options.registry
+  };
+};
+
+export { createQueryCoordinator, createStaticShardRegistry, mergeStrategyForAggregate };