@iderouter/index-mcp 0.2.0-beta.1

package/src/background-embedding-profile.js

@@ -0,0 +1,64 @@
+export function backgroundEmbeddingProfileForSource({
+  source = "",
+  batchSize = 1,
+  concurrency = 1,
+  flushTarget = 1,
+  healthLatencyMs = 0,
+  observedRequestMs = 0,
+}) {
+  const resolved = {
+    batchSize: Math.max(1, Number(batchSize) || 1),
+    concurrency: Math.max(1, Number(concurrency) || 1),
+    flushTarget: Math.max(1, Number(flushTarget) || 1),
+  };
+  const sourceText = String(source || "");
+  const latencyMs = Math.max(0, Number(healthLatencyMs) || 0);
+  const observedMs = Math.max(0, Number(observedRequestMs) || 0);
+  const effectiveLatencyMs = observedMs > 0 ? observedMs : latencyMs;
+  if (sourceText.startsWith("previous_failure_fallback_deferred_resume")) {
+    return {
+      batchSize: Math.min(resolved.batchSize, 8),
+      concurrency: Math.min(resolved.concurrency, 1),
+      flushTarget: Math.min(resolved.flushTarget, 8),
+    };
+  }
+  if (
+    !sourceText.startsWith("background_fine_strategy") &&
+    !sourceText.startsWith("background_fine_post_priority_strategy")
+  ) {
+    return resolved;
+  }
+  const isPostPriority = sourceText.startsWith("background_fine_post_priority_strategy");
+  if (isPostPriority && effectiveLatencyMs <= 0) {
+    return {
+      batchSize: Math.min(resolved.batchSize, 24),
+      concurrency: Math.min(resolved.concurrency, 3),
+      flushTarget: Math.min(resolved.flushTarget, 32),
+    };
+  }
+  if (isPostPriority && effectiveLatencyMs > 0 && effectiveLatencyMs <= 2200) {
+    return resolved;
+  }
+  if (isPostPriority && effectiveLatencyMs > 0 && effectiveLatencyMs < 3000) {
+    return {
+      batchSize: Math.min(resolved.batchSize, 24),
+      concurrency: Math.min(resolved.concurrency, 3),
+      flushTarget: Math.min(resolved.flushTarget, 32),
+    };
+  }
+  if (effectiveLatencyMs >= 2400) {
+    return {
+      batchSize: Math.min(resolved.batchSize, 16),
+      concurrency: Math.min(resolved.concurrency, 2),
+      flushTarget: Math.min(resolved.flushTarget, 24),
+    };
+  }
+  if (effectiveLatencyMs < 3000) {
+    return resolved;
+  }
+  return {
+    batchSize: Math.min(resolved.batchSize, 16),
+    concurrency: Math.min(resolved.concurrency, 2),
+    flushTarget: Math.min(resolved.flushTarget, 24),
+  };
+}

package/src/background-fine-budget.js

@@ -0,0 +1,18 @@
+export function shouldDeferBackgroundBeforeFile({
+  priorityFineReady,
+  embeddedCount,
+  embeddedCountBaseline = 0,
+  pendingBatchCount = 0,
+  nextFileChunkEstimate,
+  incrementalBackgroundChunkBudget,
+}) {
+  if (!priorityFineReady) return false;
+  const budget = Math.max(1, Number(incrementalBackgroundChunkBudget) || 0);
+  const embedded = Math.max(0, (Number(embeddedCount) || 0) - Math.max(0, Number(embeddedCountBaseline) || 0));
+  const pending = Math.max(0, Number(pendingBatchCount) || 0);
+  const inFlightTotal = embedded + pending;
+  if (inFlightTotal >= budget) return true;
+  const nextCost = Math.max(0, Number(nextFileChunkEstimate) || 0);
+  if (nextCost <= 0) return false;
+  return inFlightTotal > 0 && inFlightTotal + nextCost > budget;
+}

package/src/background-fine-runtime.js

@@ -0,0 +1,179 @@
+export function shouldDeferBackgroundAfterPriorityFlushes({
+  priorityFineReady,
+  backgroundFlushCount = 0,
+  maxBackgroundFlushes = 0,
+}) {
+  if (!priorityFineReady) return false;
+  const limit = Math.max(0, Number(maxBackgroundFlushes) || 0);
+  if (limit <= 0) return false;
+  return Math.max(0, Number(backgroundFlushCount) || 0) >= limit;
+}
+
+export function shouldDeferBackgroundAfterPriorityFiles({
+  priorityFineReady,
+  completedBackgroundFileCount = 0,
+  completedBackgroundFileBaseline = 0,
+  maxBackgroundFilesAfterPriorityReady = 0,
+  minBackgroundFilesAfterPriorityReady = 0,
+}) {
+  if (!priorityFineReady) return false;
+  const limit = Math.max(
+    0,
+    Math.max(
+      Number(maxBackgroundFilesAfterPriorityReady) || 0,
+      Number(minBackgroundFilesAfterPriorityReady) || 0,
+    ),
+  );
+  if (limit <= 0) return false;
+  const completed = Math.max(
+    0,
+    (Number(completedBackgroundFileCount) || 0) - Math.max(0, Number(completedBackgroundFileBaseline) || 0),
+  );
+  return completed >= limit;
+}
+
+export function selectFineEmbeddingSource({
+  priorityFineReady,
+  initialSource = "",
+}) {
+  if (priorityFineReady) return "background_fine_post_priority_strategy";
+  return String(initialSource || "");
+}
+
+export function shouldDeferBackgroundAfterPriorityRuntime({
+  priorityFineReady,
+  nowMs = 0,
+  postPriorityReadyAtMs = 0,
+  maxPostPriorityRuntimeMs = 0,
+}) {
+  if (!priorityFineReady) return false;
+  const limit = Math.max(0, Number(maxPostPriorityRuntimeMs) || 0);
+  if (limit <= 0) return false;
+  const readyAt = Math.max(0, Number(postPriorityReadyAtMs) || 0);
+  if (readyAt <= 0) return false;
+  const elapsed = Math.max(0, Number(nowMs) || 0) - readyAt;
+  return elapsed >= limit;
+}
+
+export function initializePostPriorityBudgetState({
+  priorityFineReady = false,
+  nowMs = 0,
+  completedBackgroundFileCount = 0,
+}) {
+  return {
+    postPriorityReadyAtMs: priorityFineReady ? Math.max(0, Number(nowMs) || 0) : 0,
+    postPriorityCompletedBackgroundFilesBaseline: Math.max(0, Number(completedBackgroundFileCount) || 0),
+  };
+}
+
+export function shouldFlushAfterPriorityReadyFile({
+  isPriorityReadyFile = false,
+  pendingChunkCount = 0,
+  remainingPriorityReadyFileCount = 0,
+  eagerDeferredResume = false,
+}) {
+  if (!isPriorityReadyFile) return false;
+  if (Math.max(0, Number(pendingChunkCount) || 0) <= 0) return false;
+  if (eagerDeferredResume) return true;
+  return Math.max(0, Number(remainingPriorityReadyFileCount) || 0) <= 0;
+}
+
+export function shouldDeferFreshRunAfterPriorityReadyFile({
+  isResumePartialSeed = false,
+  isPriorityReadyFile = false,
+  remainingPriorityReadyFileCount = 0,
+  priorityFineReady = false,
+  hasRemainingFiles = false,
+}) {
+  void isResumePartialSeed;
+  void isPriorityReadyFile;
+  void remainingPriorityReadyFileCount;
+  void priorityFineReady;
+  void hasRemainingFiles;
+  return false;
+}
+
+export function shouldDeferFreshRunAfterPriorityReady({
+  isResumePartialSeed = false,
+  priorityFineReady = false,
+  hasRemainingQueuedFiles = false,
+}) {
+  void isResumePartialSeed;
+  void priorityFineReady;
+  void hasRemainingQueuedFiles;
+  return false;
+}
+
+export function postPriorityRuntimeBudgetMsForRun({
+  isResumePartialSeed = false,
+  freshBudgetMs = 0,
+  resumeBudgetMs = 0,
+  observedRequestMs = 0,
+  maxBackgroundFlushes = 0,
+}) {
+  const baseBudgetMs = Math.max(0, Number(isResumePartialSeed ? resumeBudgetMs : freshBudgetMs) || 0);
+  if (isResumePartialSeed) return baseBudgetMs;
+  const observedMs = Math.max(0, Number(observedRequestMs) || 0);
+  const flushes = Math.max(0, Number(maxBackgroundFlushes) || 0);
+  if (observedMs <= 0 || observedMs >= 3000 || flushes <= 0) return baseBudgetMs;
+  const estimatedBudgetMs = Math.round((observedMs * flushes) + 1000);
+  return Math.max(baseBudgetMs, Math.min(12000, estimatedBudgetMs));
+}
+
+export function backgroundIncrementalChunkBudgetForRun({
+  isResumePartialSeed = false,
+  freshBudget = 0,
+  resumeBudget = 0,
+}) {
+  return Math.max(1, Number(isResumePartialSeed ? resumeBudget : freshBudget) || 0);
+}
+
+export function maxBackgroundFilesAfterPriorityReadyForRun({
+  isResumePartialSeed = false,
+  configuredMaxFiles = 0,
+  observedRequestMs = 0,
+}) {
+  const configured = Math.max(0, Number(configuredMaxFiles) || 0);
+  if (isResumePartialSeed) return configured;
+  const observedMs = Math.max(0, Number(observedRequestMs) || 0);
+  if (observedMs <= 0 || observedMs >= 3000) return configured;
+  if (observedMs <= 2200) return Math.max(configured, 18);
+  return Math.max(configured, 16);
+}
+
+export function maxBackgroundFlushesAfterPriorityReadyForRun({
+  isResumePartialSeed = false,
+  configuredMaxFlushes = 0,
+  incrementalBackgroundChunkBudget = 0,
+  embeddingFlushChunkTarget = 0,
+}) {
+  const configured = Math.max(0, Number(configuredMaxFlushes) || 0);
+  const flushTarget = Math.max(1, Number(embeddingFlushChunkTarget) || 1);
+  const chunkBudget = Math.max(1, Number(incrementalBackgroundChunkBudget) || 1);
+  const budgetDrivenMinimum = Math.max(1, Math.floor(chunkBudget / flushTarget));
+  if (!isResumePartialSeed) {
+    return Math.max(configured, budgetDrivenMinimum);
+  }
+  return Math.max(configured, budgetDrivenMinimum);
+}
+
+export function shouldForceCheckpointAfterPriorityReadyFlush({
+  flushedAfterPriorityReadyFile = false,
+}) {
+  return Boolean(flushedAfterPriorityReadyFile);
+}
+
+export function shouldScheduleDeferredBackgroundContinuation({
+  backgroundCompletedFileCount = 0,
+  backgroundTargetFileCount = 0,
+  continuationPassCount = 0,
+  maxContinuationPasses = 0,
+}) {
+  const target = Math.max(0, Number(backgroundTargetFileCount) || 0);
+  const completed = Math.max(0, Number(backgroundCompletedFileCount) || 0);
+  if (target <= 0) return false;
+  if (completed >= target) return false;
+  const maxPasses = Math.max(0, Number(maxContinuationPasses) || 0);
+  if (maxPasses > 0 && Math.max(0, Number(continuationPassCount) || 0) >= maxPasses) return false;
+  return true;
+}

package/src/background-fine-selection.js

@@ -0,0 +1,332 @@
+import path from "node:path";
+
+const DEFAULT_BUCKET_ORDER = [
+  "relay",
+  "service",
+  "model",
+  "pkg",
+  "relay_channel",
+  "controller",
+  "router",
+  "middleware",
+  "other",
+];
+
+function parseProviderSet(value, fallback) {
+  const text = String(value || "").trim();
+  if (!text) return new Set(fallback);
+  return new Set(
+    text
+      .split(",")
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean),
+  );
+}
+
+const DEFAULT_HOT_RELAY_CHANNEL_PROVIDERS = parseProviderSet(
+  process.env.IDEROUTER_BACKGROUND_HOT_RELAY_CHANNEL_PROVIDERS,
+  [
+    "openai",
+    "claude",
+    "gemini",
+    "ali",
+    "aws",
+    "vertex",
+  ],
+);
+
+export function backgroundBucketKey(relativePathInput) {
+  const relativePath = String(relativePathInput || "").toLowerCase().split(path.sep).join("/");
+  if (relativePath.startsWith("relay/channel/")) {
+    const parts = relativePath.split("/");
+    return `relay_channel:${parts[2] || "misc"}`;
+  }
+  if (relativePath.startsWith("relay/")) return "relay";
+  if (relativePath.startsWith("service/")) return "service";
+  if (relativePath.startsWith("model/")) return "model";
+  if (relativePath.startsWith("pkg/")) return "pkg";
+  if (relativePath.startsWith("controller/")) return "controller";
+  if (relativePath.startsWith("router/")) return "router";
+  if (relativePath.startsWith("middleware/")) return "middleware";
+  return "other";
+}
+
+export function backgroundBucketPriority(bucketKey) {
+  if (bucketKey === "relay") return 0;
+  if (bucketKey === "service") return 1;
+  if (bucketKey === "model") return 2;
+  if (bucketKey === "pkg") return 3;
+  if (bucketKey.startsWith("relay_channel:")) return 4;
+  if (bucketKey === "controller") return 5;
+  if (bucketKey === "router") return 6;
+  if (bucketKey === "middleware") return 7;
+  return 8;
+}
+
+function bucketFamily(bucketKey) {
+  return String(bucketKey || "").startsWith("relay_channel:") ? "relay_channel" : String(bucketKey || "other");
+}
+
+function relayChannelSecondaryAllowed(relativePathInput) {
+  const relativePath = String(relativePathInput || "").toLowerCase().split(path.sep).join("/");
+  if (!relativePath.startsWith("relay/channel/")) return true;
+  const fileName = path.basename(relativePath);
+  return fileName === "adaptor.go" || fileName.startsWith("relay-") || fileName.includes("bridge");
+}
+
+function relayChannelPreferredProviderFile(relativePathInput) {
+  const relativePath = String(relativePathInput || "").toLowerCase().split(path.sep).join("/");
+  if (!relativePath.startsWith("relay/channel/")) return false;
+  return relayChannelSecondaryAllowed(relativePath);
+}
+
+function relayChannelProviderTier(providerKey, hotRelayChannelProviders = DEFAULT_HOT_RELAY_CHANNEL_PROVIDERS) {
+  return hotRelayChannelProviders.has(String(providerKey || "").toLowerCase()) ? "hot" : "warm";
+}
+
+function normalizedCursorIndex(bucketOrder, cursor) {
+  if (!cursor) return 0;
+  const family = bucketFamily(cursor);
+  const index = bucketOrder.indexOf(family);
+  return index >= 0 ? index : 0;
+}
+
+function rotateBucketFamilies(bucketFamilies, cursor) {
+  const orderedFamilies = [...bucketFamilies].sort((left, right) => {
+    const leftPriority = backgroundBucketPriority(left);
+    const rightPriority = backgroundBucketPriority(right);
+    if (leftPriority !== rightPriority) return leftPriority - rightPriority;
+    return left.localeCompare(right);
+  });
+  if (!cursor) return orderedFamilies;
+  const order = DEFAULT_BUCKET_ORDER.filter((entry) => orderedFamilies.includes(entry));
+  if (order.length === 0) return orderedFamilies;
+  const startIndex = normalizedCursorIndex(order, cursor);
+  return [
+    ...order.slice(startIndex),
+    ...order.slice(0, startIndex),
+  ];
+}
+
+function parseBucketCursor(cursor) {
+  const text = String(cursor || "").trim();
+  if (!text) return { family: "", lastRelativePath: "" };
+  if (!text.startsWith("{")) {
+    return { family: text, lastRelativePath: "" };
+  }
+  try {
+    const parsed = JSON.parse(text);
+    return {
+      family: String(parsed?.family || ""),
+      lastRelativePath: String(parsed?.last_relative_path || ""),
+    };
+  } catch {
+    return { family: text, lastRelativePath: "" };
+  }
+}
+
+function formatBucketCursor(family, lastRelativePath = "") {
+  const normalizedFamily = String(family || "").trim();
+  const normalizedPath = String(lastRelativePath || "").trim();
+  if (!normalizedFamily) return "";
+  if (!normalizedPath) return normalizedFamily;
+  return JSON.stringify({
+    family: normalizedFamily,
+    last_relative_path: normalizedPath,
+  });
+}
+
+function parsePreferredFamilies(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item || "").trim()).filter(Boolean);
+  }
+  return [];
+}
+
+export function buildBackgroundFineSelection(files, options = {}) {
+  const selected = [];
+  let estimatedChunks = 0;
+  let relayChannelCount = 0;
+  const relayChannelProviderCounts = new Map();
+  let relayChannelFallbackProviderCount = 0;
+  let controllerCount = 0;
+  let routerCount = 0;
+  let middlewareCount = 0;
+  let otherCount = 0;
+  const maxFiles = Math.max(1, Number(options.maxFiles) || 1);
+  const maxChunks = Math.max(1, Number(options.maxChunks) || 1);
+  const minScore = Number(options.minScore) || 0;
+  const relayChannelFileCap = Math.max(1, Number(options.relayChannelFileCap) || Number.MAX_SAFE_INTEGER);
+  const relayChannelProviderCap = Math.max(1, Number(options.relayChannelProviderCap) || Number.MAX_SAFE_INTEGER);
+  const relayChannelFallbackProviderCap = Math.max(0, Number(options.relayChannelFallbackProviderCap) || 0);
+  const relayChannelHotProviderSecondaryCap = Math.max(1, Number(options.relayChannelHotProviderSecondaryCap) || relayChannelProviderCap);
+  const relayChannelWarmProviderSecondaryCap = Math.max(1, Number(options.relayChannelWarmProviderSecondaryCap) || 1);
+  const hotRelayChannelProviders = options.hotRelayChannelProviders instanceof Set
+    ? options.hotRelayChannelProviders
+    : DEFAULT_HOT_RELAY_CHANNEL_PROVIDERS;
+  const controllerFileCap = Math.max(1, Number(options.controllerFileCap) || Number.MAX_SAFE_INTEGER);
+  const routerFileCap = Math.max(1, Number(options.routerFileCap) || Number.MAX_SAFE_INTEGER);
+  const middlewareFileCap = Math.max(1, Number(options.middlewareFileCap) || Number.MAX_SAFE_INTEGER);
+  const otherFileCap = Math.max(0, Number(options.otherFileCap) || 0);
+  const completedFineFiles = options.completedFineFiles || new Set();
+  const relayChannelResumeFamilyCompletedCap = Math.max(0, Number(options.relayChannelResumeFamilyCompletedCap) || 0);
+  const resumePreferredFamilies = parsePreferredFamilies(options.resumePreferredFamilies);
+  const resumePreferredFamilyFloor = Math.max(0, Number(options.resumePreferredFamilyFloor) || 0);
+  const parsedCursor = parseBucketCursor(options.bucketCursor);
+  const bucketQueues = new Map();
+  const relayChannelPreferredProviders = new Set();
+  const completedByFamily = new Map();
+
+  for (const relativePath of completedFineFiles.values ? completedFineFiles.values() : []) {
+    const family = bucketFamily(backgroundBucketKey(relativePath));
+    completedByFamily.set(family, (completedByFamily.get(family) || 0) + 1);
+  }
+
+  for (const file of [...files].sort((a, b) => {
+    const score = Number(b.score || 0) - Number(a.score || 0);
+    const chunkEstimateDelta = Number(a.chunkEstimate || 0) - Number(b.chunkEstimate || 0);
+    if (score === 0 && chunkEstimateDelta !== 0) return chunkEstimateDelta;
+    return score || String(a.relativePath || "").localeCompare(String(b.relativePath || ""));
+  })) {
+    const score = Number(file.score || 0);
+    if (score < minScore) continue;
+    const bucket = backgroundBucketKey(file.relativePath);
+    if (bucket.startsWith("relay_channel:") && relayChannelPreferredProviderFile(file.relativePath)) {
+      relayChannelPreferredProviders.add(bucket.split(":")[1] || "misc");
+    }
+    if (!bucketQueues.has(bucket)) bucketQueues.set(bucket, []);
+    bucketQueues.get(bucket).push(file);
+  }
+
+  let madeProgress = true;
+  while (madeProgress) {
+    if (selected.length >= maxFiles) break;
+    madeProgress = false;
+    const bucketFamilies = Array.from(new Set(Array.from(bucketQueues.keys()).map((bucket) => bucketFamily(bucket))));
+    const familyOrder = rotateBucketFamilies(bucketFamilies, parsedCursor.family);
+    const bucketOrder = Array.from(bucketQueues.keys()).sort((left, right) => {
+      const leftQueue = bucketQueues.get(left) || [];
+      const rightQueue = bucketQueues.get(right) || [];
+      const leftTotal = leftQueue.length;
+      const rightTotal = rightQueue.length;
+      const leftCompleted = leftQueue.filter((file) => completedFineFiles.has(file.relativePath)).length;
+      const rightCompleted = rightQueue.filter((file) => completedFineFiles.has(file.relativePath)).length;
+      const leftRatio = leftTotal > 0 ? leftCompleted / leftTotal : 1;
+      const rightRatio = rightTotal > 0 ? rightCompleted / rightTotal : 1;
+      if (leftRatio !== rightRatio) return leftRatio - rightRatio;
+      const leftFamily = bucketFamily(left);
+      const rightFamily = bucketFamily(right);
+      const leftFamilyCompleted = completedByFamily.get(leftFamily) || 0;
+      const rightFamilyCompleted = completedByFamily.get(rightFamily) || 0;
+      if (leftFamilyCompleted !== rightFamilyCompleted) return leftFamilyCompleted - rightFamilyCompleted;
+      const leftFamilyIndex = familyOrder.indexOf(bucketFamily(left));
+      const rightFamilyIndex = familyOrder.indexOf(bucketFamily(right));
+      if (leftFamilyIndex !== rightFamilyIndex) return leftFamilyIndex - rightFamilyIndex;
+      const leftPriority = backgroundBucketPriority(left);
+      const rightPriority = backgroundBucketPriority(right);
+      if (leftPriority !== rightPriority) return leftPriority - rightPriority;
+      return left.localeCompare(right);
+    });
+
+    if (parsedCursor.lastRelativePath) {
+      bucketOrder.sort((left, right) => {
+        const leftFamily = bucketFamily(left);
+        const rightFamily = bucketFamily(right);
+        if (leftFamily !== parsedCursor.family && rightFamily !== parsedCursor.family) return 0;
+        if (leftFamily === parsedCursor.family && rightFamily !== parsedCursor.family) return -1;
+        if (rightFamily === parsedCursor.family && leftFamily !== parsedCursor.family) return 1;
+        const leftQueue = bucketQueues.get(left) || [];
+        const rightQueue = bucketQueues.get(right) || [];
+        const leftHasCursorPath = leftQueue.some((file) => String(file.relativePath || "") === parsedCursor.lastRelativePath);
+        const rightHasCursorPath = rightQueue.some((file) => String(file.relativePath || "") === parsedCursor.lastRelativePath);
+        if (leftHasCursorPath && !rightHasCursorPath) return -1;
+        if (rightHasCursorPath && !leftHasCursorPath) return 1;
+        return 0;
+      });
+    }
+
+    for (const bucket of bucketOrder) {
+      const queue = bucketQueues.get(bucket);
+      if (!queue || queue.length === 0) continue;
+      if (parsedCursor.lastRelativePath && bucketFamily(bucket) === parsedCursor.family) {
+        const pivot = queue.findIndex((file) => String(file.relativePath || "") === parsedCursor.lastRelativePath);
+        if (pivot >= 0) {
+          queue.push(...queue.splice(0, pivot + 1));
+        }
+      }
+      while (queue.length > 0) {
+        const file = queue.shift();
+        const relativePath = String(file.relativePath || "").toLowerCase().split(path.sep).join("/");
+        const family = bucketFamily(bucket);
+        if (
+          family === "relay_channel" &&
+          resumePreferredFamilies.length > 0 &&
+          resumePreferredFamilyFloor > 0
+        ) {
+          const selectedFamilies = new Set(selected.map((item) => bucketFamily(backgroundBucketKey(item.relativePath))));
+          const preferredCovered = resumePreferredFamilies.filter((preferredFamily) => selectedFamilies.has(preferredFamily)).length;
+          if (preferredCovered < resumePreferredFamilyFloor) continue;
+        }
+        if (
+          family === "relay_channel" &&
+          relayChannelResumeFamilyCompletedCap > 0 &&
+          (completedByFamily.get("relay_channel") || 0) >= relayChannelResumeFamilyCompletedCap
+        ) {
+          const selectedNonRelayFamilies = new Set(selected.map((item) => bucketFamily(backgroundBucketKey(item.relativePath))));
+          selectedNonRelayFamilies.delete("relay_channel");
+          if (selectedNonRelayFamilies.size < 4) continue;
+        }
+        if (relativePath.startsWith("relay/channel/")) {
+          if (relayChannelCount >= relayChannelFileCap) continue;
+          const parts = relativePath.split("/");
+          const providerKey = parts.length >= 3 ? parts[2] : relativePath;
+          const providerCount = relayChannelProviderCounts.get(providerKey) || 0;
+          const providerHasPreferredFiles = relayChannelPreferredProviders.has(providerKey);
+          const providerTier = relayChannelProviderTier(providerKey, hotRelayChannelProviders);
+          const providerCap = providerTier === "hot" ? relayChannelHotProviderSecondaryCap : relayChannelWarmProviderSecondaryCap;
+          if (!providerHasPreferredFiles && providerCount === 0 && relayChannelFallbackProviderCount >= relayChannelFallbackProviderCap) continue;
+          if (providerCount === 0 && relayChannelPreferredProviders.has(providerKey) && !relayChannelPreferredProviderFile(relativePath)) continue;
+          if (providerCount >= Math.min(relayChannelProviderCap, providerCap)) continue;
+          if (providerCount >= 1 && !relayChannelSecondaryAllowed(relativePath)) continue;
+        }
+        if (relativePath.startsWith("controller/") && controllerCount >= controllerFileCap) continue;
+        if (relativePath.startsWith("router/") && routerCount >= routerFileCap) continue;
+        if (relativePath.startsWith("middleware/") && middlewareCount >= middlewareFileCap) continue;
+        if (family === "other" && otherCount >= otherFileCap) continue;
+        const chunkEstimate = Math.max(1, Number(file.chunkEstimate) || 1);
+        if (selected.length > 0 && estimatedChunks + chunkEstimate > maxChunks) {
+          queue.length = 0;
+          break;
+        }
+        selected.push(file);
+        estimatedChunks += chunkEstimate;
+        if (relativePath.startsWith("relay/channel/")) {
+          relayChannelCount += 1;
+          const parts = relativePath.split("/");
+          const providerKey = parts.length >= 3 ? parts[2] : relativePath;
+          if ((relayChannelProviderCounts.get(providerKey) || 0) === 0 && !relayChannelPreferredProviders.has(providerKey)) {
+            relayChannelFallbackProviderCount += 1;
+          }
+          relayChannelProviderCounts.set(providerKey, (relayChannelProviderCounts.get(providerKey) || 0) + 1);
+        }
+        if (relativePath.startsWith("controller/")) controllerCount += 1;
+        if (relativePath.startsWith("router/")) routerCount += 1;
+        if (relativePath.startsWith("middleware/")) middlewareCount += 1;
+        if (family === "other") otherCount += 1;
+        madeProgress = true;
+        break;
+      }
+      if (selected.length >= maxFiles) break;
+    }
+  }
+
+  return { selected, estimatedChunks };
+}
+
+export function advanceBackgroundBucketCursor(lastProcessedRelativePath, files) {
+  const lastBucketFamily = bucketFamily(backgroundBucketKey(lastProcessedRelativePath));
+  const presentFamilies = Array.from(new Set((files || []).map((file) => bucketFamily(backgroundBucketKey(file.relativePath)))));
+  const orderedFamilies = rotateBucketFamilies(presentFamilies, null);
+  if (orderedFamilies.length === 0) return "";
+  return formatBucketCursor(lastBucketFamily, lastProcessedRelativePath);
+}

package/src/checkpoint-policy.js

@@ -0,0 +1,16 @@
+export function shouldSaveCheckpoint({
+  force = false,
+  nowMs = 0,
+  lastSavedAtMs = 0,
+  fileDelta = 0,
+  chunkDelta = 0,
+  intervalMs = 0,
+  minFileDelta = 0,
+  minChunkDelta = 0,
+}) {
+  if (force) return true;
+  const dueToTime = Math.max(0, Number(nowMs) || 0) - Math.max(0, Number(lastSavedAtMs) || 0) >= Math.max(0, Number(intervalMs) || 0);
+  const dueToFiles = Math.max(0, Number(fileDelta) || 0) >= Math.max(0, Number(minFileDelta) || 0);
+  const dueToChunks = Math.max(0, Number(chunkDelta) || 0) >= Math.max(0, Number(minChunkDelta) || 0);
+  return dueToTime || dueToFiles || dueToChunks;
+}

package/src/conflict-policy.js

@@ -0,0 +1,17 @@
+export function shouldSuppressPartialChunkCountMismatch({ job = null, index = null }) {
+  if (!job || !index) return false;
+  if (index.complete === true) return false;
+  const stage = String(index.indexStage || "");
+  if (stage === "coarse_lexical") return true;
+  if (job.backgroundFineDeferred && job.semanticRetryDeferred) return true;
+  const chunks = Array.isArray(index.chunks) ? index.chunks : [];
+  const hasCoarseChunks = chunks.some((chunk) => chunk?.granularity === "coarse");
+  const hasFineChunks = chunks.some((chunk) => chunk?.granularity !== "coarse");
+  if (hasCoarseChunks && hasFineChunks) return true;
+  return false;
+}
+
+export function shouldSuppressExpectedResumeModelMismatch({ job = null }) {
+  const source = String(job?.embeddingModelSource || job?.diagnostics?.embeddingModelSource || "");
+  return source.startsWith("previous_failure_fallback_deferred_resume");
+}

package/src/deferred-retry-delay.js

@@ -0,0 +1,14 @@
+export function effectiveDeferredResumeDelayMs({
+  job = null,
+  failedDelayMs = 0,
+  semanticDeferredDelayMs = 0,
+}) {
+  if (job?.semanticRetryDeferred) {
+    const retryCount = Math.max(0, Number(job?.semanticRetryCount || 0));
+    if (retryCount <= 1) return 250;
+    if (retryCount === 2) return 500;
+    if (retryCount === 3) return 750;
+    return Math.max(0, Number(semanticDeferredDelayMs) || 0);
+  }
+  return Math.max(0, Number(failedDelayMs) || 0);
+}

package/src/deferred-retry-status.js

@@ -0,0 +1,10 @@
+export function remainingDeferredRetrySeconds({
+  deferredAt = "",
+  resumeDelayMs = 0,
+  nowMs = Date.now(),
+}) {
+  const startedMs = Date.parse(String(deferredAt || ""));
+  if (!Number.isFinite(startedMs) || startedMs <= 0) return 0;
+  const remainingMs = Math.max(0, Number(resumeDelayMs || 0) - (Number(nowMs || 0) - startedMs));
+  return Math.ceil(remainingMs / 1000);
+}

package/src/embedding-attempt-ordinal.js

@@ -0,0 +1,17 @@
+export function resolveEmbeddingAttemptOrdinal({
+  attemptPlan = [],
+  attemptIndex = -1,
+}) {
+  const attempts = Array.isArray(attemptPlan) ? attemptPlan : [];
+  const index = Number(attemptIndex);
+  if (index < 0 || index >= attempts.length) {
+    return {
+      current: 0,
+      total: attempts.length,
+    };
+  }
+  return {
+    current: index + 1,
+    total: attempts.length,
+  };
+}