@headband/cli 0.6.0 → 0.7.0

package/dist/index.js

@@ -35,14 +35,15 @@ __export(index_exports, {
   main: () => main,
   parseArgv: () => parseArgv,
   parseExpires: () => parseExpires,
+  parseIndexList: () => parseIndexList,
   parsePermissions: () => parsePermissions,
   run: () => run,
   stdinIsInteractive: () => stdinIsInteractive,
   syncClientFromFlags: () => syncClientFromFlags
 });
 module.exports = __toCommonJS(index_exports);
-var import_fs11 = require("fs");
 var import_fs12 = require("fs");
+var import_fs13 = require("fs");
 var import_path11 = require("path");
 var import_prompts2 = __toESM(require("prompts"));
 var import_picocolors3 = __toESM(require("picocolors"));
@@ -527,7 +528,7 @@ function errorMessageOf(status, errorBody) {
   }
   return message;
 }
-var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
 async function readJson(response) {
   const text = await response.text();
   if (!text) return {};
@@ -547,7 +548,7 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
     headers.set("authorization", `Bearer ${init2.apiKey}`);
   }
   const base = normalizeUrl(baseUrl);
-  const { rateLimitRetries = 0, sleep = defaultSleep, apiKey: _apiKey, ...fetchInit } = init2;
+  const { rateLimitRetries = 0, sleep: sleep2 = defaultSleep, apiKey: _apiKey, ...fetchInit } = init2;
   void _apiKey;
   let response;
   try {
@@ -560,7 +561,7 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
       const wait = response.status === 429 ? retryAfterSeconds(response) : null;
       if (wait === null || attempt >= rateLimitRetries) break;
       await response.body?.cancel().catch(() => void 0);
-      await sleep(wait * 1e3);
+      await sleep2(wait * 1e3);
     }
   } catch (error) {
     const cause = error?.cause;
@@ -599,7 +600,7 @@ function createApiClient(url, profile) {
 }
 
 // src/auth.ts
-var defaultSleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var defaultSleep2 = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
 function openBrowser(url) {
   try {
     if (process.platform === "darwin") {
@@ -614,7 +615,7 @@ function openBrowser(url) {
 }
 async function runDeviceFlow(url, io, options = {}) {
   const baseUrl = normalizeUrl(url);
-  const sleep = options.sleep || defaultSleep2;
+  const sleep2 = options.sleep || defaultSleep2;
   const now = options.now || Date.now;
   const device = await apiRequest(baseUrl, "/api/cli/device", {
     method: "POST",
@@ -629,7 +630,7 @@ async function runDeviceFlow(url, io, options = {}) {
   let interval = device.data.interval;
   const deadline = now() + device.data.expiresIn * 1e3;
   while (now() < deadline) {
-    await sleep(interval * 1e3);
+    await sleep2(interval * 1e3);
     try {
       const token = await apiRequest(baseUrl, "/api/cli/token", {
         method: "POST",
@@ -684,6 +685,7 @@ async function login(url, io, options = {}) {
 }
 
 // src/branch.ts
+var import_fs4 = require("fs");
 var import_path5 = require("path");
 
 // src/output.ts
@@ -893,14 +895,22 @@ var PART_2 = /* @__PURE__ */ new Set(["reset", "rollback", "restore", "set-prima
 var BRANCH_USAGE = [
   "Usage:",
   "  headband branch list [--project <id>] [--json]",
-  "  headband branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]",
+  "  headband branch create <name> [--empty] [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]",
+  "  headband branch ensure <name> [--from <parent>] [--expires-in <7d>] [--env-out <file>] [--project <id>] [--json]",
   "  headband branch delete <name> [--project <id>] [--yes] [--json]",
   "  headband branch protect <name> [--project <id>] [--json]",
   "  headband branch unprotect <name> [--project <id>] [--json]",
   "  headband branch expire <name> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]",
   "  headband branch checkout <name> [--project <id>] [--json]",
-  "  headband branch create <name> (without --empty, a fork)   coming with bucket storage",
-  "  headband branch reset|rollback|restore|set-primary <name>  coming with bucket storage",
+  "  headband branch reset|rollback|restore|set-primary <name>  not available yet",
+  "",
+  "create without --empty forks the parent (default: main): its indexes, documents and settings,",
+  "copy-on-write. --empty makes a branch with no indexes.",
+  "",
+  "ensure is for preview deploys: it forks the branch unless it exists, pushes its expiry out",
+  "(--expires-in, default 7d), mints a search key and an admin key for it, and writes HEADBAND_*",
+  "variables to --env-out (or prints them). The name is made branch-safe first: feature/Foo_Bar",
+  "becomes feature/foo_bar. It refuses the primary branch.",
   "",
   "The project comes from --project, else the directory's checkout (.headband/project.json).",
   "Durations take s, m, h, d or w: 30m, 2h, 7d.",
@@ -999,10 +1009,7 @@ async function runBranch(args, flags, deps) {
   const action = args[0];
   const json = flags["--json"] === true;
   if (action && PART_2.has(action)) {
-    throw new UsageError(
-      `headband branch ${action} is coming with bucket storage.`,
-      "not_available"
-    );
+    throw new UsageError(`headband branch ${action} is not available yet.`, "not_available");
   }
   const client = createApiClient(auth.url, { apiKey: auth.apiKey });
   const checkout = () => checkoutFor(cwd, auth.profile?.orgId);
@@ -1031,18 +1038,35 @@ async function runBranch(args, flags, deps) {
       if (error instanceof ApiError && error.code === "branches_not_open") {
         throw restate(error, "Branches other than main are not open yet.");
       }
-      if (error instanceof ApiError && error.code === "fork_not_available") {
-        throw restate(
-          error,
-          "Forking arrives with bucket storage. Pass --empty for an empty branch."
-        );
-      }
-      throw error;
+      throw restateCreate(error);
     }
     if (json) printJson(io, response);
     else printTable(io, [response.data], COLUMNS);
     return;
   }
+  if (action === "ensure") {
+    const result = await ensureBranch(client, {
+      name: branchNameFrom(requiredName(args[1])),
+      project: projectFor(flags, checkout),
+      from: stringFlag2(flags, "--from"),
+      expiresInMs: parseDuration(stringFlag2(flags, "--expires-in") ?? "7d"),
+      url: auth.url
+    });
+    const envOut = stringFlag2(flags, "--env-out");
+    if (envOut && envOut !== "-") writeEnvFile((0, import_path5.resolve)(cwd, envOut), result.env);
+    if (json) {
+      printJson(io, { branch: result.branch, created: result.created, env: result.env });
+    } else if (envOut && envOut !== "-") {
+      const engines = result.branch.instances?.length ?? 0;
+      io.stdout(
+        `${result.created ? "Forked" : "Reused"} branch ${result.branch.name} (${engines} engine${engines === 1 ? "" : "s"}), expires ${result.branch.expiresAt}.`
+      );
+      io.stdout(`Wrote ${Object.keys(result.env).length} HEADBAND_* variables to ${envOut}.`);
+    } else {
+      io.stdout(dotenv(result.env));
+    }
+    return;
+  }
   if (action === "delete") {
     const name = requiredName(args[1]);
     const project = projectFor(flags, checkout);
@@ -1114,9 +1138,109 @@ async function runBranch(args, flags, deps) {
   io.stdout(BRANCH_USAGE);
   throw new UsageError("Unknown branch command");
 }
+function restateCreate(error) {
+  if (error instanceof ApiError && error.code === "branches_not_open") {
+    return restate(error, "Branches other than main are not open yet.");
+  }
+  if (error instanceof ApiError && error.code === "fork_not_available") {
+    return restate(error, "Forking is not open yet. Pass --empty for an empty branch.");
+  }
+  return error;
+}
+function branchNameFrom(ref) {
+  const name = ref.trim().toLowerCase().replace(/[^a-z0-9._/-]+/g, "-").slice(0, 63).replace(/^[^a-z0-9]+/, "").replace(/[^a-z0-9]+$/, "");
+  if (!name) throw new UsageError(`"${ref}" has no letters or digits to make a branch name from.`);
+  return name;
+}
+var ENSURE_WAIT_MS = 6e4;
+var ENSURE_POLL_MS = 2e3;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var engineVar = (engine) => `HEADBAND_${engine.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_URL`;
+async function ensureBranch(client, o, now = Date.now) {
+  var _a;
+  const path2 = `/v1/branches/${encodeURIComponent(o.name)}?project=${encodeURIComponent(o.project)}`;
+  const read = async () => {
+    try {
+      return (await client.get(path2)).data;
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404 && error.code === "branch_not_found") {
+        return null;
+      }
+      throw error;
+    }
+  };
+  const expiresAt = () => new Date(now() + o.expiresInMs).toISOString();
+  let branch = await read();
+  let created = false;
+  if (!branch) {
+    const body = {
+      name: o.name,
+      projectId: o.project,
+      expiresAt: expiresAt()
+    };
+    if (o.from) body.parent = o.from;
+    try {
+      branch = (await client.post("/v1/branches", body)).data;
+      created = true;
+    } catch (error) {
+      if (!(error instanceof ApiError && error.code === "branch_exists"))
+        throw restateCreate(error);
+      branch = await read();
+      if (!branch) throw error;
+    }
+  }
+  if (branch.primary) {
+    throw new UsageError(
+      `${branch.name} is the primary branch. ensure is for preview branches; run it only on preview builds.`
+    );
+  }
+  for (const until = now() + ENSURE_WAIT_MS; branch.state === "creating" && now() < until; ) {
+    await sleep(ENSURE_POLL_MS);
+    branch = await read() ?? branch;
+  }
+  if (branch.state !== "ready") {
+    throw new CliError(`Branch ${branch.name} is ${branch.state}, not ready. Try again shortly.`, {
+      exitCode: EXIT_CODES.conflict,
+      code: "branch_not_ready"
+    });
+  }
+  if (!created && !branch.protected) {
+    branch = {
+      ...branch,
+      ...(await client.patch(path2, { expiresAt: expiresAt() })).data
+    };
+  }
+  if (!branch.instances)
+    branch = { ...branch, ...(await client.get(path2)).data };
+  const mint = async (type) => (await client.post("/v1/keys", {
+    name: `preview ${branch.name} ${type}`,
+    type,
+    projectId: o.project,
+    branch: branch.id
+  })).data.apiKey;
+  const env = {
+    HEADBAND_URL: o.url,
+    HEADBAND_PROJECT_ID: o.project,
+    HEADBAND_BRANCH: branch.name,
+    HEADBAND_BRANCH_ID: branch.id,
+    HEADBAND_SEARCH_KEY: await mint("search"),
+    HEADBAND_ADMIN_KEY: await mint("admin")
+  };
+  for (const i of branch.instances ?? []) env[_a = engineVar(i.engine)] ?? (env[_a] = i.endpoint);
+  return { branch, created, env };
+}
+var quote = (v) => /^[A-Za-z0-9_./:@+-]*$/.test(v) ? v : JSON.stringify(v);
+function dotenv(env) {
+  return Object.entries(env).map(([k, v]) => `${k}=${quote(v)}`).join("\n");
+}
+function writeEnvFile(file, env) {
+  const kept = (0, import_fs4.existsSync)(file) ? (0, import_fs4.readFileSync)(file, "utf8").split("\n").filter((line) => line.trim() !== "" && !/^\s*(export\s+)?HEADBAND_[A-Z0-9_]*=/.test(line)) : [];
+  (0, import_fs4.writeFileSync)(file, [...kept, dotenv(env)].join("\n") + "\n", { mode: 384 });
+  (0, import_fs4.chmodSync)(file, 384);
+}
 
 // src/config-load.ts
-var import_fs4 = require("fs");
+var import_fs5 = require("fs");
 var import_path6 = require("path");
 var import_url = require("url");
 var import_jiti = require("jiti");
@@ -1202,7 +1326,7 @@ function validateConfig(config, ormSchema) {
         continue;
       }
       const hasPath = model.relations.some(
-        (r) => r.fromModel === spec.model && r.toModel === index.source && r.kind === "many"
+        (r) => r.fromModel === index.source && r.toModel === spec.model && r.kind === "many"
       );
       if (!hasPath) {
         errors.push({
@@ -1252,7 +1376,7 @@ var SYNC_CONFIG_SHAPE = 'a headband.config.ts whose default export is defineConf
 function findConfigFile(cwd) {
   for (const name of CONFIG_FILENAMES) {
     const path2 = (0, import_path6.join)(cwd, name);
-    if ((0, import_fs4.existsSync)(path2)) return path2;
+    if ((0, import_fs5.existsSync)(path2)) return path2;
   }
   return void 0;
 }
@@ -1372,10 +1496,10 @@ function missingAdapterError(command, why) {
 
 // src/docs.ts
 var import_path7 = require("path");
-var import_fs5 = require("fs");
+var import_fs6 = require("fs");
 var DOCS_BATCH_SIZE = 1e3;
 function parseDocumentsFile(path2) {
-  const content = (0, import_fs5.readFileSync)(path2, "utf-8");
+  const content = (0, import_fs6.readFileSync)(path2, "utf-8");
   const ext = (0, import_path7.extname)(path2).toLowerCase();
   if (ext === ".jsonl") {
     return content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
@@ -1488,6 +1612,67 @@ var ExportInterruptedError = class extends Error {
     this.name = "ExportInterruptedError";
   }
 };
+function refusedWalk(error) {
+  if (!(error instanceof ApiError) || error.code !== "feature_not_supported") return null;
+  if (!/primary key/i.test(error.message)) return null;
+  const pk = /add `([^`]+)`/.exec(error.message)?.[1] ?? null;
+  const named = ["filterableAttributes", "sortableAttributes", "displayedAttributes"].filter(
+    (name) => error.message.includes(name)
+  );
+  return { pk, lists: named.length ? named : ["filterableAttributes", "sortableAttributes"] };
+}
+var DECLARE_WAIT_MS = 15 * 6e4;
+var DECLARE_POLL_MS = 3e3;
+async function declareExportKey(client, index, io, opts = {}) {
+  const sleep2 = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now ?? Date.now;
+  const probe = () => client.get(`/v1/documents?index=${encodeURIComponent(index)}&limit=1&cursor=`);
+  let refused;
+  try {
+    await probe();
+    return false;
+  } catch (error) {
+    refused = refusedWalk(error);
+    if (!refused) throw error;
+    if (!refused.pk) throw error;
+  }
+  const { pk, lists } = refused;
+  const path2 = `/v1/indexes/${encodeURIComponent(index)}/settings`;
+  const current = await client.get(path2);
+  const patch = {};
+  for (const name of lists) {
+    const list = Array.isArray(current?.[name]) ? current[name] : [];
+    if (list.includes("*") || list.includes(pk)) continue;
+    patch[name] = [...list, pk];
+  }
+  io.stderr(
+    `Declaring \`${pk}\` in ${Object.keys(patch).join(" and ") || lists.join(" and ")} on ${index}, so the export can read past 1000 documents. Visor rebuilds the index for this change, which can take minutes on a large one.`
+  );
+  if (Object.keys(patch).length > 0) {
+    try {
+      await client.patch(path2, patch);
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.status < 500) throw error;
+    }
+  }
+  const deadline = now() + (opts.waitMs ?? DECLARE_WAIT_MS);
+  for (; ; ) {
+    try {
+      await probe();
+      io.stderr(`\`${pk}\` is declared. Exporting.`);
+      return true;
+    } catch (error) {
+      const waiting = refusedWalk(error) || error instanceof ApiError && error.status >= 500;
+      if (!waiting) throw error;
+    }
+    if (now() >= deadline) {
+      throw new CliError(
+        `\`${pk}\` is still not declared on ${index} after ${Math.round((opts.waitMs ?? DECLARE_WAIT_MS) / 6e4)} minutes. Visor may still be rebuilding it: run headband docs export again later.`
+      );
+    }
+    await sleep2(DECLARE_POLL_MS);
+  }
+}
 function exportRefusalAdvice(error, index) {
   if (!(error instanceof ApiError) || error.code !== "feature_not_supported") return null;
   if (!/primary key/i.test(error.message)) return null;
@@ -1498,7 +1683,8 @@ function exportRefusalAdvice(error, index) {
   );
   const lists = missing.length ? missing.join(" and ") : "filterableAttributes and sortableAttributes";
   return [
-    `To export the whole index, declare ${key} on it once:`,
+    `To export the whole index, run it again with --declare-key: it declares ${key} on the index`,
+    `once (Visor rebuilds the index for it), waits for it, and exports. Or declare it yourself:`,
     `  1. headband indexes settings get ${index} > settings.json`,
     `  2. Add ${key} to ${lists} in settings.json.`,
     `  3. headband indexes settings set ${index} --file settings.json`,
@@ -1514,6 +1700,41 @@ function exportFailure(error, index) {
 ${advice}`);
 }
 
+// src/content-drift.ts
+async function readRemoteDocuments(client, index, primaryKey) {
+  const batchSize = await defaultExportBatchSize(client, index);
+  const docs = /* @__PURE__ */ new Map();
+  for await (const { results } of walkDocuments(client, { index, batchSize })) {
+    for (const doc of results) {
+      const id = doc?.[primaryKey];
+      if (id !== void 0 && id !== null) docs.set(String(id), doc);
+    }
+  }
+  return docs;
+}
+function wire(value) {
+  return value === void 0 ? null : JSON.parse(JSON.stringify(value));
+}
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+function documentsMatch(expected, remote, primaryKey) {
+  if (!remote) return false;
+  for (const [key, raw] of Object.entries(expected)) {
+    if (key === primaryKey) {
+      if (String(raw) !== String(remote[key])) return false;
+      continue;
+    }
+    if (canonical(wire(raw)) !== canonical(wire(remote[key]))) return false;
+  }
+  return true;
+}
+
 // ../../src/lib/density/catalog-constants.ts
 function formatMemory(mb) {
   return mb >= 1024 ? `${mb / 1024} GB` : `${mb} MB`;
@@ -2069,7 +2290,7 @@ async function runSwitchEngine(client, opts, io, chatter) {
     );
     return;
   }
-  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep2 = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   let lastPhase = "";
   for (; ; ) {
     if (view.phase !== lastPhase) {
@@ -2077,7 +2298,7 @@ async function runSwitchEngine(client, opts, io, chatter) {
       chatter.stdout(`${opts.uid}: ${PHASES[view.phase] ?? view.phase}`);
     }
     if (view.status === "succeeded" || view.status === "failed") break;
-    await sleep(opts.pollMs ?? 3e3);
+    await sleep2(opts.pollMs ?? 3e3);
     const status = await client.get(path2);
     if (!status.switch || status.switch.switchId !== view.switchId) {
       throw new CliError("The switch is no longer listed for this index.", {
@@ -2214,11 +2435,11 @@ function planMigration(config, applied, opts) {
 }
 
 // src/schema.ts
-var import_fs7 = require("fs");
+var import_fs8 = require("fs");
 var import_path9 = require("path");
 
 // ../sync/src/migrations.ts
-var import_fs6 = require("fs");
+var import_fs7 = require("fs");
 var import_path8 = require("path");
 var FILE_NAME_RE = /^(\d{4})_(.+)\.json$/;
 function sanitizeSlug(slug) {
@@ -2226,7 +2447,7 @@ function sanitizeSlug(slug) {
   return sanitized || "migration";
 }
 function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new Date()) {
-  (0, import_fs6.mkdirSync)(dir, { recursive: true });
+  (0, import_fs7.mkdirSync)(dir, { recursive: true });
   const existing = readMigrations(dir);
   const nextVersion = existing.length === 0 ? 1 : existing[existing.length - 1].version + 1;
   const safeSlug = sanitizeSlug(meta.slug);
@@ -2239,13 +2460,13 @@ function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new D
     ...meta.targetHashes ? { targetHashes: meta.targetHashes } : {},
     ops
   };
-  (0, import_fs6.writeFileSync)(path2, JSON.stringify(file, null, 2));
+  (0, import_fs7.writeFileSync)(path2, JSON.stringify(file, null, 2));
   return path2;
 }
 function readMigrations(dir) {
   let entries;
   try {
-    entries = (0, import_fs6.readdirSync)(dir);
+    entries = (0, import_fs7.readdirSync)(dir);
   } catch {
     return [];
   }
@@ -2254,7 +2475,7 @@ function readMigrations(dir) {
     const match = FILE_NAME_RE.exec(entry);
     if (!match) continue;
     const path2 = (0, import_path8.join)(dir, entry);
-    const raw = (0, import_fs6.readFileSync)(path2, "utf-8");
+    const raw = (0, import_fs7.readFileSync)(path2, "utf-8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -2284,7 +2505,7 @@ function pendingMigrations(files, appliedVersion) {
 var BASE_BACKOFF_MS = 500;
 var DEFAULT_MAX_RETRIES = 5;
 function defaultSleep3(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 var SchemaCasError = class extends Error {
   constructor(message) {
@@ -2357,6 +2578,14 @@ var HeadbandClient = class {
     if (opts?.projectId !== void 0) body.projectId = opts.projectId;
     await this.request("POST", "/v1/indexes", body);
   }
+  /** The index (GET /v1/indexes/{uid}): its engine among the rest. */
+  async getIndex(uid) {
+    return this.request("GET", `/v1/indexes/${encodeURIComponent(uid)}`);
+  }
+  /** Deletes an index (DELETE /v1/indexes/{uid}): `schema apply` removes a reindex it could not set up. */
+  async deleteIndex(uid) {
+    await this.request("DELETE", `/v1/indexes/${encodeURIComponent(uid)}`);
+  }
   async patchSettings(uid, settings) {
     await this.request("PATCH", `/v1/indexes/${uid}/settings`, settings);
   }
@@ -2443,17 +2672,17 @@ function printOpsTable(io, ops) {
 }
 function readAppliedMarker(dir) {
   const path2 = (0, import_path9.join)(dir, APPLIED_MARKER_FILE);
-  if (!(0, import_fs7.existsSync)(path2)) return 0;
+  if (!(0, import_fs8.existsSync)(path2)) return 0;
   try {
-    const parsed = JSON.parse((0, import_fs7.readFileSync)(path2, "utf-8"));
+    const parsed = JSON.parse((0, import_fs8.readFileSync)(path2, "utf-8"));
     return typeof parsed.version === "number" ? parsed.version : 0;
   } catch {
     return 0;
   }
 }
 function writeAppliedMarker(dir, version) {
-  (0, import_fs7.mkdirSync)(dir, { recursive: true });
-  (0, import_fs7.writeFileSync)((0, import_path9.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
+  (0, import_fs8.mkdirSync)(dir, { recursive: true });
+  (0, import_fs8.writeFileSync)((0, import_path9.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
 }
 function configHashes(config, index) {
   const def = config.indexes.find((d) => d.name === index);
@@ -2512,7 +2741,36 @@ async function createIndexIdempotent(ctx, uid, opts) {
     ctx.io.stdout(`Index "${uid}" already exists. Continuing.`);
   }
 }
+var ES_EVERY_FIELD = [
+  "searchableAttributes",
+  "filterableAttributes",
+  "sortableAttributes"
+];
+async function indexEngine(ctx, uid) {
+  try {
+    return (await ctx.client.getIndex(uid)).engine ?? null;
+  } catch {
+    return null;
+  }
+}
+function settingsForEngine(ctx, uid, engine, settings) {
+  if (engine !== "elasticsearch") return settings;
+  const out = { ...settings };
+  const left = [];
+  for (const key of ES_EVERY_FIELD) {
+    if (out[key] === void 0) continue;
+    delete out[key];
+    left.push(key);
+  }
+  if (left.length > 0) {
+    ctx.io.stdout(
+      `"${uid}" is on Elasticsearch, which searches, filters and sorts every field without these lists, so they are not sent: ${left.join(", ")}.`
+    );
+  }
+  return out;
+}
 async function patchSettingsBeforeBackfill(ctx, uid, settings) {
+  if (Object.keys(settings).length === 0) return false;
   try {
     await ctx.client.patchSettings(uid, settings);
     return false;
@@ -2536,13 +2794,14 @@ async function patchSettingsAfterBackfill(ctx, uid, settings) {
 function settingsRefused(uid, err) {
   const message = err instanceof Error ? err.message : String(err);
   const { status, code } = err ?? {};
-  return new CliError(
+  const refused = new CliError(
     `Index "${uid}" exists, but its settings were refused: ${message.replace(/\.?$/, ".")} Change the index's settings in headband.config.ts, then re-run "headband schema apply": it picks up the existing index.`,
     {
       ...typeof status === "number" ? { exitCode: exitCodeForStatus(status) } : {},
       ...typeof code === "string" ? { code } : {}
     }
   );
+  return Object.assign(refused, { refusal: message });
 }
 function postState(client, state) {
   return client.postSchemaState(state);
@@ -2590,13 +2849,83 @@ async function backfill(ctx, def, targetUid, abortPoint, onPage) {
   );
   return { pushed, excluded };
 }
+async function catchUp(ctx, def, targetUid, when) {
+  if (!ctx.readRemoteDocuments) return;
+  const remote = await ctx.readRemoteDocuments(targetUid, def.primaryKey);
+  const keep = /* @__PURE__ */ new Set();
+  let pushed = 0;
+  let cursor = null;
+  for (; ; ) {
+    const page = await ctx.adapter.listIds(def.source, cursor, ctx.backfillBatchSize);
+    if (page.ids.length === 0) break;
+    const docs = await ctx.adapter.resolveDocs(def.name, page.ids);
+    const toPush = [];
+    for (const doc of docs) {
+      const sourceRow = doc.__source ?? doc;
+      delete doc.__source;
+      if (def.shouldIndex && !def.shouldIndex(sourceRow)) continue;
+      const key = String(doc[def.primaryKey]);
+      keep.add(key);
+      if (!documentsMatch(doc, remote.get(key), def.primaryKey)) toPush.push(doc);
+    }
+    if (toPush.length > 0) {
+      const result = await ctx.client.bulkPush(targetUid, toPush, def.primaryKey);
+      if (result?.partialFailure) {
+        throw new CliError(
+          `Catching up "${def.name}" ${when} stopped: ${partialFailureSummary(result.partialFailure)}. Re-run "headband schema apply" once resolved.`
+        );
+      }
+      pushed += toPush.length;
+    }
+    cursor = page.nextCursor;
+    if (cursor === null || page.ids.length < ctx.backfillBatchSize) break;
+  }
+  const extra = [...remote.keys()].filter((key) => !keep.has(key));
+  for (let offset = 0; offset < extra.length; offset += ctx.backfillBatchSize) {
+    const result = await ctx.client.deleteDocs(
+      targetUid,
+      extra.slice(offset, offset + ctx.backfillBatchSize)
+    );
+    if (result?.partialFailure) {
+      throw new CliError(
+        `Catching up "${def.name}" ${when} stopped: ${partialFailureSummary(result.partialFailure)}. Re-run "headband schema apply" once resolved.`
+      );
+    }
+  }
+  ctx.io.stdout(
+    `Caught up "${def.name}" ${when}: ${pushed} changed or new document(s) written, ${extra.length} removed.`
+  );
+}
+async function abandonReindex(ctx, index, physical, err) {
+  let removed;
+  try {
+    await ctx.client.deleteIndex(physical);
+    removed = `The new index "${physical}" was removed`;
+  } catch (deleteErr) {
+    const why = deleteErr instanceof Error ? deleteErr.message : String(deleteErr);
+    removed = `The new index "${physical}" could not be removed (${why}): remove it with "headband indexes delete ${physical}"`;
+  }
+  const reason = err?.refusal ?? (err instanceof Error ? err.message : String(err));
+  return new CliError(
+    `The reindex of "${index}" stopped: the new index's settings were refused: ${String(reason).replace(/\.?$/, ".")} ${removed}, and "${index}" is unchanged. Change the index's settings in headband.config.ts, then re-run "headband schema apply".`,
+    {
+      ...err instanceof CliError ? { exitCode: err.exitCode, code: err.code } : {}
+    }
+  );
+}
 async function applyReindex(op, ctx, existing, expectedParentHash) {
   const def = ctx.config.indexes.find((d) => d.name === op.index);
   if (!def) {
     throw new CliError(`Cannot reindex "${op.index}": no matching index in the loaded config.`);
   }
+  const settings = settingsForEngine(ctx, op.index, await indexEngine(ctx, op.index), op.settings);
   await createIndexIdempotent(ctx, op.toPhysicalUid, { primaryKey: def.primaryKey });
-  const settingsAfter = await patchSettingsBeforeBackfill(ctx, op.toPhysicalUid, op.settings);
+  let settingsAfter;
+  try {
+    settingsAfter = await patchSettingsBeforeBackfill(ctx, op.toPhysicalUid, settings);
+  } catch (err) {
+    throw await abandonReindex(ctx, op.index, op.toPhysicalUid, err);
+  }
   const version = (existing?.version ?? 0) + 1;
   const schemaHashValue = docShapeHash(def);
   const settingsHashValue = settingsHash(def);
@@ -2625,8 +2954,10 @@ async function applyReindex(op, ctx, existing, expectedParentHash) {
     "before the alias flip",
     (cursor) => writeState("migrating", cursor)
   );
-  if (settingsAfter) await patchSettingsAfterBackfill(ctx, op.toPhysicalUid, op.settings);
+  if (settingsAfter) await patchSettingsAfterBackfill(ctx, op.toPhysicalUid, settings);
+  await catchUp(ctx, def, op.toPhysicalUid, "before the alias flip");
   await ctx.client.patchAlias(op.index, op.toPhysicalUid);
+  await catchUp(ctx, def, op.index, "after the alias flip");
   await writeState("applied", null);
   return {
     indexUid: op.index,
@@ -2646,9 +2977,15 @@ async function applyOp(op, ctx, existing, expectedParentHash) {
       );
     }
     await createIndexIdempotent(ctx, op.index, { primaryKey: def.primaryKey });
-    const settingsAfter = await patchSettingsBeforeBackfill(ctx, op.index, op.settings);
+    const settings = settingsForEngine(
+      ctx,
+      op.index,
+      await indexEngine(ctx, op.index),
+      op.settings
+    );
+    const settingsAfter = await patchSettingsBeforeBackfill(ctx, op.index, settings);
     await backfill(ctx, def, op.index, "before recording the index as applied");
-    if (settingsAfter) await patchSettingsAfterBackfill(ctx, op.index, op.settings);
+    if (settingsAfter) await patchSettingsAfterBackfill(ctx, op.index, settings);
     const next = {
       indexUid: op.index,
       version: 1,
@@ -2664,7 +3001,13 @@ async function applyOp(op, ctx, existing, expectedParentHash) {
     if (!existing) {
       throw new CliError(`Cannot patch settings for "${op.index}": no applied schema state found.`);
     }
-    await ctx.client.patchSettings(op.index, op.settings);
+    const settings = settingsForEngine(
+      ctx,
+      op.index,
+      await indexEngine(ctx, op.index),
+      op.settings
+    );
+    if (Object.keys(settings).length > 0) await ctx.client.patchSettings(op.index, settings);
     const def = ctx.config.indexes.find((d) => d.name === op.index);
     const next = {
       ...existing,
@@ -2720,7 +3063,8 @@ async function runSchemaApply(deps) {
     client: deps.client,
     backfillBatchSize: deps.backfillBatchSize ?? DEFAULT_BACKFILL_BATCH_SIZE,
     io: deps.io,
-    projectId: deps.projectId
+    projectId: deps.projectId,
+    readRemoteDocuments: deps.readRemoteDocuments
   };
   let appliedOps = 0;
   let appliedFiles = 0;
@@ -2847,7 +3191,7 @@ async function runSchemaForget(deps) {
 }
 
 // src/sync.ts
-var import_fs8 = require("fs");
+var import_fs9 = require("fs");
 var import_path10 = require("path");
 var import_crypto = require("crypto");
 var import_pg = require("pg");
@@ -2917,6 +3261,12 @@ function pgOutboxDriver(exec, opts) {
       );
       return rows?.[0]?.status === "dead_letter" ? "dead_letter" : "pending";
     },
+    async release(ids, error) {
+      await exec(
+        `UPDATE ${table} SET last_error = $2, claimed_at = NULL WHERE id = ANY($1) AND status = 'pending'`,
+        [ids, error]
+      );
+    },
     async deadLetters(limit) {
       const { rows } = await exec(
         `SELECT * FROM ${table} WHERE status = 'dead_letter' ORDER BY id LIMIT $1`,
@@ -3132,7 +3482,7 @@ function rowOutcomes(rows, resolved, failures) {
   return { done, retry, deadLetter };
 }
 function defaultSleep4(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function errorMessage(err) {
   if (!(err instanceof Error)) return String(err);
@@ -3154,6 +3504,7 @@ function describeRow(row) {
 var emptyOutcome = () => ({
   done: [],
   retry: [],
+  release: [],
   deadLetter: [],
   pushed: 0,
   deleted: 0
@@ -3171,7 +3522,7 @@ async function runSyncWorker(opts) {
     batchSize = DEFAULT_BATCH_SIZE,
     stopSignal,
     now = Date.now,
-    sleep = defaultSleep4,
+    sleep: sleep2 = defaultSleep4,
     onHeartbeat,
     log = (message) => console.warn(message)
   } = opts;
@@ -3198,7 +3549,7 @@ async function runSyncWorker(opts) {
       log(`[headband] could not record this worker run: ${errorMessage(err)}`);
     }
   };
-  const backoff = (attempt) => sleep(Math.min(failureDelayMs * 2 ** (attempt - 1), MAX_FAILURE_DELAY_MS));
+  const backoff = (attempt) => sleep2(Math.min(failureDelayMs * 2 ** (attempt - 1), MAX_FAILURE_DELAY_MS));
   const processBatch = async (batch) => {
     const changes = batch.map((row) => ({
       model: row.model,
@@ -3213,7 +3564,7 @@ async function runSyncWorker(opts) {
       primaryKeyByIndex,
       backoff
     );
-    return { ...rowOutcomes(batch, resolved, failures), pushed, deleted };
+    return { ...rowOutcomes(batch, resolved, failures), release: [], pushed, deleted };
   };
   const processIsolated = async (batch) => {
     const outcome = emptyOutcome();
@@ -3226,7 +3577,10 @@ async function runSyncWorker(opts) {
         outcome.pushed += one.pushed;
         outcome.deleted += one.deleted;
       } catch (err) {
-        outcome.retry.push([row, errorMessage(err)]);
+        (isTransientBatchError(err) ? outcome.release : outcome.retry).push([
+          row,
+          errorMessage(err)
+        ]);
       }
     }
     return outcome;
@@ -3237,7 +3591,7 @@ async function runSyncWorker(opts) {
     const rows = await outbox.claim(batchSize);
     if (rows.length === 0) {
       if (!loop) break;
-      await sleep(idleDelayMs);
+      await sleep2(idleDelayMs);
       continue;
     }
     let outcome;
@@ -3245,12 +3599,14 @@ async function runSyncWorker(opts) {
     try {
       outcome = await processBatch(rows);
     } catch (err) {
-      if (rows.length > 1 && !isTransientBatchError(err)) {
+      const transient = isTransientBatchError(err);
+      if (rows.length > 1 && !transient) {
         outcome = await processIsolated(rows);
       } else {
         wholeBatchFailed = true;
         const message = errorMessage(err);
-        outcome = { ...emptyOutcome(), retry: rows.map((row) => [row, message]) };
+        const failed = rows.map((row) => [row, message]);
+        outcome = transient ? { ...emptyOutcome(), release: failed } : { ...emptyOutcome(), retry: failed };
         log(
           `[headband] a batch of ${rows.length} outbox row(s) failed and will be retried: ${message}`
         );
@@ -3272,6 +3628,17 @@ async function runSyncWorker(opts) {
         log(`[headband] ${describeRow(row)} failed: ${message}`);
       }
     }
+    if (outcome.release.length > 0) {
+      if (outbox.release) {
+        await outbox.release(
+          outcome.release.map(([row]) => row.id),
+          outcome.release[0][1]
+        );
+        report.retried += outcome.release.length;
+      } else {
+        outcome.retry.push(...outcome.release);
+      }
+    }
     for (const [row, message] of outcome.retry) {
       const status = await outbox.markFailed(row.id, message);
       if (status === "dead_letter") {
@@ -3288,7 +3655,7 @@ async function runSyncWorker(opts) {
         }
       }
     }
-    if (outcome.retry.length > 0) {
+    if (outcome.retry.length > 0 || outcome.release.length > 0) {
       consecutiveFailures += 1;
       await backoff(consecutiveFailures);
     } else {
@@ -3383,8 +3750,8 @@ async function runSyncInit(deps) {
   deps.io.stdout(ddl);
   if (deps.write) {
     const path2 = (0, import_path10.join)(deps.cwd ?? process.cwd(), OUTBOX_SQL_RELATIVE_PATH);
-    (0, import_fs8.mkdirSync)((0, import_path10.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
-    (0, import_fs8.writeFileSync)(path2, `${ddl}
+    (0, import_fs9.mkdirSync)((0, import_path10.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
+    (0, import_fs9.writeFileSync)(path2, `${ddl}
 `);
     deps.io.stdout(`Wrote ${path2}`);
   }
@@ -3512,6 +3879,66 @@ async function runSyncWorkerCmd(deps) {
     }
   }
 }
+async function reconcileContent(deps, def, pageSize) {
+  const remote = await deps.readRemoteDocuments(def.name, def.primaryKey);
+  const keep = /* @__PURE__ */ new Set();
+  let missing = 0;
+  let stale = 0;
+  let cursor = null;
+  for (; ; ) {
+    const page = await deps.adapter.listIds(def.source, cursor, pageSize);
+    if (page.ids.length === 0) break;
+    const docs = await deps.adapter.resolveDocs(def.name, page.ids);
+    const toPush = [];
+    for (const doc of docs) {
+      const sourceRow = doc.__source ?? doc;
+      delete doc.__source;
+      if (def.shouldIndex && !def.shouldIndex(sourceRow)) continue;
+      const key = String(doc[def.primaryKey]);
+      keep.add(key);
+      const indexed = remote.get(key);
+      if (!indexed) missing += 1;
+      else if (!documentsMatch(doc, indexed, def.primaryKey)) stale += 1;
+      else continue;
+      toPush.push(doc);
+    }
+    if (deps.fix && toPush.length > 0) {
+      const result = await deps.client.bulkPush(def.name, toPush, def.primaryKey);
+      if (result?.partialFailure) {
+        throw new CliError(
+          `Repair push for "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+        );
+      }
+    }
+    if (page.nextCursor === null) break;
+    cursor = page.nextCursor;
+  }
+  const extraIds = [...remote.keys()].filter((key) => !keep.has(key));
+  if (deps.fix) {
+    for (let offset = 0; offset < extraIds.length; offset += pageSize) {
+      const result = await deps.client.deleteDocs(
+        def.name,
+        extraIds.slice(offset, offset + pageSize)
+      );
+      if (result?.partialFailure) {
+        throw new CliError(
+          `Removing extra documents from "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+        );
+      }
+    }
+  }
+  const drift = missing + extraIds.length + stale;
+  return {
+    index: def.name,
+    sourceCount: keep.size,
+    remoteCount: remote.size,
+    missing,
+    extra: extraIds.length,
+    stale,
+    drift,
+    fixed: Boolean(deps.fix) && drift !== 0
+  };
+}
 async function indexableSourceIds(adapter, def, pageSize) {
   const ids = /* @__PURE__ */ new Map();
   let cursor = null;
@@ -3556,6 +3983,17 @@ async function runSyncReconcile(deps) {
   const pageSize = deps.pageSize ?? RECONCILE_PAGE_SIZE;
   const rows = [];
   for (const def of deps.config.indexes) {
+    if (deps.content && deps.readRemoteDocuments) {
+      try {
+        rows.push(await reconcileContent(deps, def, pageSize));
+        continue;
+      } catch (err) {
+        if (err instanceof CliError) throw err;
+        deps.io.stderr(
+          `Could not read the documents of "${def.name}", comparing ids only: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
     const source = await indexableSourceIds(deps.adapter, def, pageSize);
     let remoteKeys = null;
     let remoteCount = -1;
@@ -3619,6 +4057,7 @@ async function runSyncReconcile(deps) {
     }
     rows.push(row);
   }
+  const contentCompared = rows.some((r) => r.stale !== void 0 && r.stale !== null);
   printTable(
     deps.io,
     rows.map((r) => ({
@@ -3626,9 +4065,10 @@ async function runSyncReconcile(deps) {
       remoteCount: r.remoteCount === -1 ? "unknown" : r.remoteCount,
       missing: r.missing ?? "",
       extra: r.extra ?? "",
+      stale: r.stale ?? "",
       fixed: r.fixed ? "yes" : ""
     })),
-    ["index", "sourceCount", "remoteCount", "missing", "extra", "drift", "fixed"]
+    contentCompared ? ["index", "sourceCount", "remoteCount", "missing", "extra", "stale", "drift", "fixed"] : ["index", "sourceCount", "remoteCount", "missing", "extra", "drift", "fixed"]
   );
   const unfixed = rows.filter((r) => r.drift !== 0 && !r.fixed);
   if (unfixed.length > 0 && !deps.fix) {
@@ -3697,10 +4137,10 @@ async function runSelfHostedSyncStatus(deps) {
 }
 function runSyncScaffoldDocker(deps) {
   const path2 = (0, import_path10.join)(deps.cwd, DOCKERFILE_NAME);
-  if ((0, import_fs8.existsSync)(path2) && !deps.force) {
+  if ((0, import_fs9.existsSync)(path2) && !deps.force) {
     throw new CliError(`${DOCKERFILE_NAME} already exists at ${path2}. Pass --force to overwrite.`);
   }
-  (0, import_fs8.writeFileSync)(path2, dockerfileContent(deps.cliVersion));
+  (0, import_fs9.writeFileSync)(path2, dockerfileContent(deps.cliVersion));
   deps.io.stdout(`Wrote ${path2}`);
   deps.io.stdout("Add this service to your docker-compose.yml:");
   deps.io.stdout(COMPOSE_SNIPPET);
@@ -3798,13 +4238,14 @@ var syncWorker = [
   "package name, and prints a docker-compose service."
 ].join("\n");
 var syncReconcile = [
-  "Usage: headband sync reconcile [--fix] [--json]",
+  "Usage: headband sync reconcile [--content] [--fix] [--json]",
   "",
   "Per index, compares the source rows that belong in it (every row shouldIndex keeps) with",
   "the documents in it, and prints how many documents are missing and how many are extra",
   "(counts, not ids; --json gives the same counts). --fix pushes the missing ones and deletes",
-  "the extra ones. Exits 1 when drift is left. Documents whose content went",
-  "stale are not detected: a reindex (schema apply) rewrites every document.",
+  "the extra ones. Exits 1 when drift is left. --content also compares every document with its",
+  "freshly resolved source row and counts the stale ones; with --fix it rewrites them. It reads",
+  "the whole index, so it takes about as long as a backfill.",
   "Needs the adapter export and DATABASE_URL."
 ].join("\n");
 var syncRetry = [
@@ -3839,7 +4280,7 @@ var SUBCOMMAND_HELP = {
     "  headband sync init [--table <name>] [--write] [--apply] [--json]",
     "  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--project <id>] [--json]",
     "  headband sync worker --scaffold docker [--force] [--json]",
-    "  headband sync reconcile [--fix] [--json]",
+    "  headband sync reconcile [--content] [--fix] [--json]",
     "  headband sync retry-dead-letters [--json]",
     "  headband sync status [--json]",
     "",
@@ -3876,10 +4317,10 @@ ${CONFIG_NOTE}`,
 };
 
 // src/sync-indexes.ts
-var import_fs10 = require("fs");
+var import_fs11 = require("fs");
 
 // src/sync-sources.ts
-var import_fs9 = require("fs");
+var import_fs10 = require("fs");
 var import_pg2 = require("pg");
 
 // ../../src/lib/sync/copy.ts
@@ -3946,7 +4387,7 @@ var SOURCE_USAGE = [
 function readCaFile(deps, file) {
   let text;
   try {
-    text = (deps.readFile ?? ((p) => (0, import_fs9.readFileSync)(p, "utf8")))(file);
+    text = (deps.readFile ?? ((p) => (0, import_fs10.readFileSync)(p, "utf8")))(file);
   } catch {
     throw new CliError("Cannot read the --ca-file.");
   }
@@ -4587,7 +5028,7 @@ var PREVIEW_MAX_IDS = 20;
 var ATTENTION_INDEX = /* @__PURE__ */ new Set(["error", "needs_rebuild", "awaiting_setup", "degraded"]);
 var ATTENTION_SOURCE = /* @__PURE__ */ new Set(["error", "awaiting_setup"]);
 var path = (id, suffix = "") => `/v1/sync/indexes/${encodeURIComponent(id)}${suffix}`;
-function readDefinition(file, readFile = (p) => (0, import_fs10.readFileSync)(p, "utf8")) {
+function readDefinition(file, readFile = (p) => (0, import_fs11.readFileSync)(p, "utf8")) {
   let text;
   try {
     text = readFile(file);
@@ -4984,6 +5425,7 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--client",
   "--instance",
   "--instances",
+  "--indexes",
   "--db-url",
   "--owner-url",
   "--tls-mode",
@@ -5005,6 +5447,8 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--branch",
   "--parent",
   "--expires-in",
+  "--env-out",
+  "--from",
   "--in",
   "--at",
   "--level",
@@ -5020,6 +5464,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--write",
   "--force",
   "--fix",
+  "--content",
   "--loop",
   "--accept-broad-role",
   "--rebuild",
@@ -5176,14 +5621,15 @@ Commands:
   projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]
   projects delete <id> [--yes] [--json]
   branch list [--project <id>] [--json]
-  branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+  branch create <name> [--empty] [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+  branch ensure <name> [--from <parent>] [--expires-in <7d>] [--env-out <file>] [--project <id>] [--json]
   branch delete <name> [--project <id>] [--yes] [--json]
   branch protect|unprotect <name> [--project <id>] [--json]
   branch expire <name> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]
   branch checkout <name> [--project <id>] [--json]
-  branch reset|rollback|restore|set-primary (coming with bucket storage)
+  branch reset|rollback|restore|set-primary (not available yet)
   keys list [--json]
-  keys create <name> --type <admin|search> [--project <id>] [--branch <name>] [--instances <id,id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]
+  keys create <name> --type <admin|search> [--project <id>] [--branch <name>] [--instances <id,id>] [--indexes <uid,uid>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]
   keys revoke <id> [--yes] [--json]
   indexes list [--json]                      (index works in place of indexes)
   indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]
@@ -5201,7 +5647,7 @@ Commands:
   instances connect <id> [--client <node|curl>] [--json]
   warm <index>... | --project <id> [--branch <name>] [--level auto|stage|start] [--json]
   docs push <file> --index <uid> [--json]
-  docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>]
+  docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--declare-key]
   docs delete <docId>... --index <uid> [--json]
   search <index> [<query>] [--limit N] [--filter <expr>] [--mode <instant|retrieval>] [--json]
   tasks list [--index <uid>] [--limit <n>] [--json]
@@ -5216,7 +5662,7 @@ Commands:
   sync init [--table <name>] [--write] [--apply] [--json]
   sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--project <id>] [--json]
   sync worker --scaffold docker [--force] [--json]
-  sync reconcile [--fix] [--json]
+  sync reconcile [--content] [--fix] [--json]
   sync retry-dead-letters [--json]
   sync status [--json]
 
@@ -5252,13 +5698,14 @@ function printCommandHelp(command, io) {
     keys: [
       "Usage:",
       "  headband keys list [--json]",
-      "  headband keys create <name> --type <admin|search> [--project <id>] [--branch <name>] [--instances <id,id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]",
+      "  headband keys create <name> --type <admin|search> [--project <id>] [--branch <name>] [--instances <id,id>] [--indexes <uid,uid>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]",
       "  headband keys revoke <id> [--yes] [--json]",
       "",
       "keys create mints a key for one branch: --branch (with --project, else the checkout's project),",
       "else the checked-out branch, else the --project's primary branch. With none of these,",
       "--type admin mints an org key, and --type search is refused: a search key needs a branch.",
-      "--instances <id,id> limits the key to those dedicated engines (on a branch: its engines among them)."
+      "--instances <id,id> limits the key to those dedicated engines (on a branch: its engines among them).",
+      "--indexes <uid,uid> limits a search key to those indexes; any other index answers 404."
     ].join("\n"),
     indexes: [
       "Usage:",
@@ -5290,7 +5737,7 @@ function printCommandHelp(command, io) {
     docs: [
       "Usage:",
       "  headband docs push <file> --index <uid> [--json]",
-      "  headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--json]",
+      "  headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--declare-key] [--json]",
       "  headband docs delete <docId>... --index <uid> [--json]",
       "",
       "docs push sends the documents in a .json (an array) or .jsonl file, 1000 at a time.",
@@ -5300,6 +5747,9 @@ function printCommandHelp(command, io) {
       "  --out <file>     to a file. The format follows the extension (.json is one array,",
       "                   anything else JSONL) unless --format says otherwise.",
       "  --batch <n>      documents per request. Default 1000, or 250 on Typesense.",
+      "  --declare-key    a Visor index past 1000 documents whose primary key is not",
+      "                   filterable and sortable (made before 2026-10-21): declare the",
+      "                   key on it first (Visor rebuilds the index), wait, then export.",
       "  If the export stops on an error, the documents written so far are kept in",
       "  <file>.partial, and <file> is not written.",
       "",
@@ -5510,7 +5960,12 @@ function parsePermissions(raw) {
 }
 function keyRow(key) {
   const branch = key.branch;
-  return { ...key, branch: branch?.name ?? "", engines: enginesColumn(key.instanceIds) };
+  return {
+    ...key,
+    branch: branch?.name ?? "",
+    engines: enginesColumn(key.instanceIds),
+    indexes: enginesColumn(key.indexUids)
+  };
 }
 function enginesColumn(instanceIds) {
   if (instanceIds === null) return "all";
@@ -5521,6 +5976,21 @@ function enginesColumn(instanceIds) {
   }
   return "none";
 }
+function parseIndexList(raw) {
+  const uids = [
+    ...new Set(
+      raw.split(",").map((x) => x.trim()).filter(Boolean)
+    )
+  ];
+  if (uids.length === 0) throw new CliError("--indexes needs at least one index uid.");
+  const bad = uids.find((uid) => !/^[A-Za-z0-9_-]{1,64}$/.test(uid));
+  if (bad) {
+    throw new CliError(
+      `Not an index uid: ${bad}. Index uids are letters, numbers, hyphens and underscores.`
+    );
+  }
+  return uids;
+}
 function parseInstanceList(raw) {
   const ids = [
     ...new Set(
@@ -5553,6 +6023,7 @@ async function runKeys(args, flags, io, confirm, cwd) {
         "projectId",
         "branch",
         "engines",
+        "indexes",
         "environment",
         "lastUsedAt",
         "expiresAt"
@@ -5574,6 +6045,11 @@ async function runKeys(args, flags, io, confirm, cwd) {
     }
     const instances = stringFlag3(flags, "--instances");
     if (instances !== void 0) body.instanceIds = parseInstanceList(instances);
+    if (stringFlag3(flags, "--index") !== void 0) {
+      throw new CliError("Unknown option --index for keys create. Did you mean --indexes?");
+    }
+    const indexes = stringFlag3(flags, "--indexes");
+    if (indexes !== void 0) body.indexUids = parseIndexList(indexes);
     const permissions = stringFlag3(flags, "--permissions");
     if (permissions) body.permissions = parsePermissions(permissions);
     const expires = stringFlag3(flags, "--expires");
@@ -5593,6 +6069,12 @@ async function runKeys(args, flags, io, confirm, cwd) {
         typeof keyId === "string" && keyId ? `This API did not limit the new key to the chosen engines, so key ${keyId} reaches wider than asked. Revoke it now: headband keys revoke ${keyId}` : "This API did not limit the new key to the chosen engines, so it reaches wider than asked. Find it with `headband keys list` and revoke it with `headband keys revoke <id>`."
       );
     }
+    if (indexes !== void 0 && !Array.isArray(response.data.key.indexUids)) {
+      const keyId = response.data.key.id;
+      throw new CliError(
+        typeof keyId === "string" && keyId ? `This API did not limit the new key to the chosen indexes, so key ${keyId} reaches every index of its branch. Revoke it now: headband keys revoke ${keyId}` : "This API did not limit the new key to the chosen indexes, so it reaches every index of its branch. Find it with `headband keys list` and revoke it with `headband keys revoke <id>`."
+      );
+    }
     if (boolFlag(flags, "--json")) {
       printJson(io, response);
       return;
@@ -5602,7 +6084,17 @@ async function runKeys(args, flags, io, confirm, cwd) {
     printTable(
       io,
       [keyRow(response.data.key)],
-      ["id", "name", "type", "environment", "branch", "engines", "keyPrefix", "expiresAt"]
+      [
+        "id",
+        "name",
+        "type",
+        "environment",
+        "branch",
+        "engines",
+        "indexes",
+        "keyPrefix",
+        "expiresAt"
+      ]
     );
     return;
   }
@@ -5688,7 +6180,7 @@ async function runIndexes(args, flags, io, confirm, cwd) {
     }
     if (settingsAction === "set") {
       const file = requiredFlag(flags, "--file");
-      const settings = JSON.parse((0, import_fs12.readFileSync)(file, "utf-8"));
+      const settings = JSON.parse((0, import_fs13.readFileSync)(file, "utf-8"));
       const response = await client.patch(`/v1/indexes/${encode(uid)}/settings`, settings);
       printJson(io, response);
       return;
@@ -5738,6 +6230,7 @@ async function runDocsExport(flags, context, cwd) {
   const format = exportFormat(flags, out);
   const client = clientFromFlags(flags, cwd);
   const batchSize = parseIntFlag(flags, "--batch") ?? await defaultExportBatchSize(client, index);
+  if (boolFlag(flags, "--declare-key")) await declareExportKey(client, index, io);
   if (!out) {
     const writeLine = context.writeLine ?? ((line) => io.stdout(line));
     try {
@@ -5748,7 +6241,7 @@ async function runDocsExport(flags, context, cwd) {
     return;
   }
   const partial = `${out}.partial`;
-  const fd = (0, import_fs11.openSync)(partial, "w", 384);
+  const fd = (0, import_fs12.openSync)(partial, "w", 384);
   let exported;
   try {
     exported = await exportDocuments(client, {
@@ -5756,26 +6249,26 @@ async function runDocsExport(flags, context, cwd) {
       format,
       batchSize,
       write: (line) => {
-        (0, import_fs11.writeSync)(fd, `${line}
+        (0, import_fs12.writeSync)(fd, `${line}
 `);
       },
       onPage: (count, total) => io.stderr(`Exported ${count}${total === null ? "" : `/${total}`} documents`),
       finishOnError: true
     });
-    (0, import_fs11.closeSync)(fd);
+    (0, import_fs12.closeSync)(fd);
   } catch (error) {
-    (0, import_fs11.closeSync)(fd);
+    (0, import_fs12.closeSync)(fd);
     const kept = error instanceof ExportInterruptedError ? error.exported : 0;
     if (kept > 0) {
       io.stderr(
         `Kept the ${kept} ${kept === 1 ? "document" : "documents"} exported before the error in ${partial}. ${out} was not written.`
       );
     } else {
-      (0, import_fs11.rmSync)(partial, { force: true });
+      (0, import_fs12.rmSync)(partial, { force: true });
     }
     throw exportFailure(error instanceof ExportInterruptedError ? error.cause : error, index);
   }
-  (0, import_fs11.renameSync)(partial, out);
+  (0, import_fs12.renameSync)(partial, out);
   if (boolFlag(flags, "--json")) printJson(io, { index, out, format, exported });
   else io.stdout(`Exported ${exported} documents to ${out}.`);
 }
@@ -5940,7 +6433,8 @@ async function runSchema(args, flags, io, confirm, cwd) {
       dir,
       allowDestructive,
       io: chatter,
-      projectId
+      projectId,
+      readRemoteDocuments: (uid, primaryKey) => readRemoteDocuments(apiClient, uid, primaryKey)
     });
     if (json) printJson(io, { ...result, projectId: projectId ?? null });
     else {
@@ -6120,8 +6614,10 @@ async function runSync(args, flags, io, confirm, cwd) {
       client,
       io: chatter,
       fix: boolFlag(flags, "--fix"),
+      content: boolFlag(flags, "--content"),
       getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`),
-      listRemoteIds: (uid, primaryKey) => listRemoteIds(apiClient, uid, primaryKey)
+      listRemoteIds: (uid, primaryKey) => listRemoteIds(apiClient, uid, primaryKey),
+      readRemoteDocuments: (uid, primaryKey) => readRemoteDocuments(apiClient, uid, primaryKey)
     });
     if (json) printJson(io, { indexes: rows, drift: reconcileHasDrift(rows) });
     if (reconcileHasDrift(rows)) process.exitCode = 1;
@@ -6143,7 +6639,7 @@ async function runSync(args, flags, io, confirm, cwd) {
   printCommandHelp("sync", io);
   throw new UsageError("Unknown sync command");
 }
-var CLI_VERSION = true ? "0.6.0" : "dev";
+var CLI_VERSION = true ? "0.7.0" : "dev";
 async function run(argv, context = { io: defaultIO }) {
   if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version")) {
     context.io.stdout(CLI_VERSION);
@@ -6245,7 +6741,7 @@ async function main(argv, context = { io: defaultIO }) {
 function stdoutLineWriter(line) {
   if (process.stdout.write(`${line}
 `)) return;
-  return new Promise((resolve2) => process.stdout.once("drain", () => resolve2()));
+  return new Promise((resolve3) => process.stdout.once("drain", () => resolve3()));
 }
 function isDirectRun() {
   return typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
@@ -6277,6 +6773,7 @@ function exitAfterFlush(code) {
   main,
   parseArgv,
   parseExpires,
+  parseIndexList,
   parsePermissions,
   run,
   stdinIsInteractive,