@datarails-ai/dr-cli 1.6.105 → 1.6.107

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.105",
+  version: "1.6.107",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -40,7 +40,7 @@ var package_default = {
     postinstall: "node scripts/postinstall.mjs"
   },
   dependencies: {
-    "@datarails-ai/dr-appspace-cli": "0.11.2",
+    "@datarails-ai/dr-appspace-cli": "0.11.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     commander: "^12.1.0",
@@ -69,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-07T13:28:02.898Z";
+var BUILD_TIME = "2026-10-07T16:21:03.565Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -5338,7 +5338,7 @@ async function poll(host, path11, deviceCode, options, terminalHints, onSuccess)
   const interval = options.interval ?? 2e3;
   const maxWait = options.maxWait ?? 6e5;
   const now = options.now ?? Date.now;
-  const sleep4 = options.sleep ?? defaultSleep;
+  const sleep3 = options.sleep ?? defaultSleep;
   const signal = options.signal;
   const base = host.replace(/\/+$/, "");
   const deadline = now() + maxWait;
@@ -5366,7 +5366,7 @@ async function poll(host, path11, deviceCode, options, terminalHints, onSuccess)
     }
     const errCode = tryParseErrorCode(text2);
     if (errCode === "authorization_pending" || errCode === "slow_down") {
-      await sleep4(interval, signal);
+      await sleep3(interval, signal);
       continue;
     }
     if (errCode) {
@@ -5395,18 +5395,18 @@ async function openBrowser(url) {
 // src/commands/_serverPicker.ts
 async function readLine(stdin) {
   return new Promise((resolve3, reject) => {
-    let data3 = "";
+    let data4 = "";
     const onData = (chunk) => {
-      data3 += chunk.toString();
-      const i = data3.indexOf("\n");
+      data4 += chunk.toString();
+      const i = data4.indexOf("\n");
       if (i >= 0) {
         cleanup();
-        resolve3(data3.slice(0, i + 1));
+        resolve3(data4.slice(0, i + 1));
       }
     };
     const onEnd = () => {
       cleanup();
-      resolve3(data3);
+      resolve3(data4);
     };
     const onError = (err) => {
       cleanup();
@@ -5530,7 +5530,7 @@ async function readFirstLineFromPipe(stdin) {
   stdin.setEncoding?.("utf8");
   stdin.resume?.();
   return new Promise((resolve3, reject) => {
-    let data3 = "";
+    let data4 = "";
     let done = false;
     const finish = (line) => {
       if (done) return;
@@ -5539,11 +5539,11 @@ async function readFirstLineFromPipe(stdin) {
       resolve3(line.endsWith("\r") ? line.slice(0, -1) : line);
     };
     const onData = (chunk) => {
-      data3 += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-      const i = data3.indexOf("\n");
-      if (i >= 0) finish(data3.slice(0, i));
+      data4 += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      const i = data4.indexOf("\n");
+      if (i >= 0) finish(data4.slice(0, i));
     };
-    const onEnd = () => finish(data3);
+    const onEnd = () => finish(data4);
     const onError = (err) => {
       if (done) return;
       done = true;
@@ -12284,7 +12284,7 @@ var defaultSleep2 = (ms, signal) => new Promise((resolve3, reject) => {
 async function pollTask(client, label, path11, options = {}) {
   const interval = options.pollIntervalMs ?? AGGREGATE_POLL_INTERVAL_MS;
   const timeout = options.timeoutMs ?? AGGREGATE_POLL_TIMEOUT_MS;
-  const sleep4 = options.sleep ?? defaultSleep2;
+  const sleep3 = options.sleep ?? defaultSleep2;
   const now = options.now ?? Date.now;
   const inner = new AbortController();
   const onOuterAbort = () => inner.abort(options.signal?.reason);
@@ -12326,7 +12326,7 @@ async function pollTask(client, label, path11, options = {}) {
         return result.env;
       }
       try {
-        await sleep4(interval, inner.signal);
+        await sleep3(interval, inner.signal);
       } catch {
         const reason = inner.signal.reason instanceof Error ? inner.signal.reason.message : String(inner.signal.reason ?? "aborted");
         throw new Error(`${label} polling timed out: ${reason}`);
@@ -12711,25 +12711,25 @@ function buildAggregateBody(dimensions, metrics, filters) {
   }
   return body;
 }
-function groupRows(data3) {
-  if (!Array.isArray(data3)) return data3;
-  return data3.filter((r) => !(isPlainObject(r) && ("col_keys" in r || "row_keys" in r)));
+function groupRows(data4) {
+  if (!Array.isArray(data4)) return data4;
+  return data4.filter((r) => !(isPlainObject(r) && ("col_keys" in r || "row_keys" in r)));
 }
 function readTotals(metadata) {
   if (!isPlainObject(metadata)) return null;
   const totals = metadata["totals"];
   return isPlainObject(totals) && Object.keys(totals).length > 0 ? totals : null;
 }
-function asRowList(data3) {
-  if (Array.isArray(data3)) {
-    if (data3.every((x) => isPlainObject(x))) {
-      return data3;
+function asRowList(data4) {
+  if (Array.isArray(data4)) {
+    if (data4.every((x) => isPlainObject(x))) {
+      return data4;
     }
     return null;
   }
-  if (isPlainObject(data3)) {
+  if (isPlainObject(data4)) {
     for (const key of ["rows", "data", "results", "items"]) {
-      const v = data3[key];
+      const v = data4[key];
       if (Array.isArray(v) && v.every((x) => isPlainObject(x))) {
         return v;
       }
@@ -12762,10 +12762,10 @@ function writeTable5(out, rows) {
     out.write(parts.join("") + "\n");
   }
 }
-function renderAggregateResult(out, data3) {
-  const rows = asRowList(data3);
+function renderAggregateResult(out, data4) {
+  const rows = asRowList(data4);
   if (rows === null) {
-    out.write(JSON.stringify(data3, null, 2) + "\n");
+    out.write(JSON.stringify(data4, null, 2) + "\n");
     return;
   }
   if (rows.length === 0) {
@@ -15481,6 +15481,108 @@ function registerDynamicRangesCommand(root) {
 // src/commands/functions.ts
 import { promises as fs11 } from "fs";
 
+// src/api/_cacheKeyPolling.ts
+var CacheKeyHttpError = class extends Error {
+  status;
+  path;
+  bodyText;
+  constructor(method, path11, status2, bodyText) {
+    super(`${method} ${path11}: HTTP ${status2}: ${truncate5(bodyText, 200)}`);
+    this.name = "CacheKeyHttpError";
+    this.status = status2;
+    this.path = path11;
+    this.bodyText = bodyText;
+  }
+};
+async function putOnce(client, path11, body, options) {
+  const res = await client.do("PUT", path11, body, options);
+  const text2 = await res.text();
+  if (res.status !== 409 && (res.status < 200 || res.status >= 300)) {
+    throw new CacheKeyHttpError("PUT", path11, res.status, text2);
+  }
+  if (text2 === "" || text2 === '""') {
+    return { status: res.status, parsed: null };
+  }
+  try {
+    return { status: res.status, parsed: JSON.parse(text2) };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`PUT ${path11}: decode: ${msg}`);
+  }
+}
+function extractCacheKey(body) {
+  if (body === null || typeof body !== "object") return "";
+  const top = body["cache_key"];
+  if (typeof top === "string" && top !== "") return top;
+  const detail = body["detail"];
+  if (detail !== null && typeof detail === "object") {
+    const nested = detail["cache_key"];
+    if (typeof nested === "string" && nested !== "") return nested;
+  }
+  return "";
+}
+function withCacheKey(path11, key) {
+  return `${path11}?cache_key=${encodeURIComponent(key)}`;
+}
+var CACHE_KEY_POLL_INTERVAL_MS = 500;
+var abortableSleep = (ms, signal) => new Promise((resolve3, reject) => {
+  if (signal?.aborted) {
+    reject(signal.reason ?? new Error("aborted"));
+    return;
+  }
+  const onAbort = () => {
+    clearTimeout(t);
+    reject(signal?.reason ?? new Error("aborted"));
+  };
+  const t = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve3();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+async function putWithCacheKeyPolling(client, path11, payload, options = {}) {
+  const interval = options.pollIntervalMs ?? CACHE_KEY_POLL_INTERVAL_MS;
+  const sleep3 = options.sleep ?? abortableSleep;
+  const label = options.label ?? "data";
+  const body = JSON.stringify(payload);
+  const first = await putOnce(client, path11, body, options);
+  if (first.status !== 409) {
+    return first.parsed;
+  }
+  const cacheKey = extractCacheKey(first.parsed);
+  if (cacheKey === "") {
+    throw new Error(
+      `PUT ${path11}: 409 without cache_key: ${truncate5(JSON.stringify(first.parsed ?? ""), 200)}`
+    );
+  }
+  const pollPath = withCacheKey(path11, cacheKey);
+  for (; ; ) {
+    try {
+      await sleep3(interval, options.signal);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new Error(`${label} polling timed out: ${reason}`);
+    }
+    let result;
+    try {
+      result = await putOnce(client, pollPath, body, options);
+    } catch (err) {
+      if (options.signal?.aborted) {
+        const reason = options.signal.reason instanceof Error ? options.signal.reason.message : String(options.signal.reason ?? "aborted");
+        throw new Error(`${label} polling timed out: ${reason}`);
+      }
+      throw err;
+    }
+    if (result.status !== 409) {
+      return result.parsed;
+    }
+  }
+}
+function truncate5(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n) + "\u2026";
+}
+
 // src/api/functions.ts
 function normalize(raw) {
   return {
@@ -15524,6 +15626,16 @@ async function getDetail(client, id, options) {
     default_agg_config: out.default_agg_config ?? null
   };
 }
+var DEFAULT_AGG_CONFIG = {
+  YTD: { aggregate_by: "month", fnc: "sum", is_end_of_period: true },
+  QTD: { aggregate_by: "month", fnc: "sum", is_end_of_period: true },
+  RM: { rolling_month_before: 0, is_end_of_period: true },
+  SA: { aggregate_by: "month", fnc: "sum", is_end_of_period: true },
+  YTG: { aggregate_by: "month", fnc: "sum", is_end_of_period: true },
+  QTG: { aggregate_by: "month", fnc: "sum", is_end_of_period: true },
+  MTD: { aggregate_by: "month", fnc: "sum", is_end_of_period: true },
+  MTG: { aggregate_by: "month", fnc: "sum", is_end_of_period: true }
+};
 async function create6(client, args, options) {
   const body = {
     id: -1,
@@ -15534,6 +15646,10 @@ async function create6(client, args, options) {
     calculated_values: [],
     template: args.template
   };
+  if (args.dateField !== void 0) {
+    body.default_agg_datefield = args.dateField;
+    body.default_agg_config = DEFAULT_AGG_CONFIG;
+  }
   const out = await client.postJSON("/api/functions/", body, options);
   if (out === null) {
     return { id: 0, name: "", aggfun: "", value_field: 0, template: 0 };
@@ -15550,7 +15666,9 @@ async function getFull(client, id, options) {
       value_field: 0,
       template: 0,
       calculated_values: [],
-      is_fx_aware: false
+      is_fx_aware: false,
+      default_agg_datefield: null,
+      default_agg_config: null
     };
   }
   const links = (out.calculated_values ?? []).map((cv) => ({
@@ -15558,7 +15676,13 @@ async function getFull(client, id, options) {
     field: cv.field ?? null,
     side: cv.side ?? null
   }));
-  return { ...normalize(out), calculated_values: links, is_fx_aware: out.is_fx_aware === true };
+  return {
+    ...normalize(out),
+    calculated_values: links,
+    is_fx_aware: out.is_fx_aware === true,
+    default_agg_datefield: out.default_agg_datefield ?? null,
+    default_agg_config: out.default_agg_config ?? null
+  };
 }
 async function update2(client, id, body, options) {
   const out = await client.putJSON(
@@ -15577,6 +15701,140 @@ async function rename2(client, id, name, options) {
 async function deleteById3(client, id, options) {
   await client.deleteJSON(`/api/functions/${id}`, options);
 }
+async function data2(client, id, body, options = {}) {
+  const out = await putWithCacheKeyPolling(client, `/api/functions/${id}/data/v2`, body, {
+    label: "function data",
+    ...options
+  });
+  return out ?? { query_results: [] };
+}
+async function drilldown(client, id, body, options = {}) {
+  return putWithCacheKeyPolling(client, `/api/functions/${id}/drilldown/v4`, body, {
+    label: "function drilldown",
+    ...options
+  });
+}
+function parseDrilldown(body) {
+  if (!Array.isArray(body)) {
+    throw new Error(`unexpected drill-down response (not an array): ${preview(body)}`);
+  }
+  const first = body[0];
+  if (first !== null && typeof first === "object" && "error" in first) {
+    const e = first;
+    if (e["error"] === "too_large_data") {
+      return {
+        kind: "too_large",
+        rows_count: Number(e["rows_count"] ?? 0),
+        cols_count: Number(e["cols_count"] ?? 0)
+      };
+    }
+    throw new Error(`drill-down error: ${preview(first)}`);
+  }
+  if (body.length === 0) {
+    return { kind: "rows", rows: [], schema: { fields: [], empty_fields: [] } };
+  }
+  const last = body[body.length - 1];
+  const isSchema = last !== null && typeof last === "object" && Array.isArray(last["fields"]);
+  if (!isSchema) {
+    throw new Error("unexpected drill-down response: no trailing {fields, empty_fields} schema");
+  }
+  const raw = last;
+  const schema = {
+    fields: raw["fields"],
+    empty_fields: Array.isArray(raw["empty_fields"]) ? raw["empty_fields"] : []
+  };
+  return { kind: "rows", rows: body.slice(0, -1), schema };
+}
+async function exportDrilldownCsv(client, id, body, options = {}) {
+  const interval = options.pollIntervalMs ?? CACHE_KEY_POLL_INTERVAL_MS;
+  const sleep3 = options.sleep ?? abortableSleep;
+  const path11 = `/api/functions/${id}/drilldown/export_to_csv`;
+  const payload = JSON.stringify(body);
+  let res = await putOnce(client, path11, payload, options);
+  while (res.status === 409) {
+    const key = extractCacheKey(res.parsed);
+    if (key === "") {
+      throw new Error(`PUT ${path11}: 409 without cache_key: ${preview(res.parsed)}`);
+    }
+    for (; ; ) {
+      try {
+        await sleep3(interval, options.signal);
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`drill-down CSV export polling timed out: ${reason}`);
+      }
+      const status2 = await client.postJSON(
+        "/api/cache/cache_keys_status",
+        { cache_keys: [key] },
+        options
+      );
+      const entry = status2?.[key];
+      if (entry !== null && typeof entry === "object") {
+        const e = entry;
+        const status3 = typeof e["status"] === "string" ? e["status"].toUpperCase() : "";
+        const hasError = e["error"] !== void 0 && e["error"] !== null && e["error"] !== false;
+        if (status3 === "FAILURE" || hasError) {
+          throw new Error(
+            `drill-down CSV export failed on the server (cache key ${key}, status ${status3 === "" ? "-" : status3}${hasError ? `, error ${preview(e["error"])}` : ""}); retry, or narrow the drill-down with more --filter flags`
+          );
+        }
+        if (e["is_ready"] === true) break;
+      }
+    }
+    res = await putOnce(client, withCacheKey(path11, key), payload, options);
+  }
+  const parsed2 = res.parsed;
+  const reportId = parsed2 !== null && typeof parsed2 === "object" ? parsed2["drill_down_report_id"] : void 0;
+  if (typeof reportId !== "number") {
+    throw new Error(`PUT ${path11}: no drill_down_report_id in ${preview(parsed2)}`);
+  }
+  const reportPath = `/api/dashboards/report/${reportId}?report_type=drill_down_report`;
+  const report = await client.do("GET", reportPath, void 0, options);
+  if (report.status < 200 || report.status >= 300) {
+    const text2 = await report.text();
+    throw new Error(`GET ${reportPath}: HTTP ${report.status}: ${text2.slice(0, 200)}`);
+  }
+  return { reportId, bytes: new Uint8Array(await report.arrayBuffer()) };
+}
+function preview(v) {
+  const s = JSON.stringify(v ?? null);
+  return s.length > 200 ? s.slice(0, 200) + "\u2026" : s;
+}
+
+// src/commands/_excelSerial.ts
+var EXCEL_UNIX_EPOCH_OFFSET_DAYS = 25569;
+var EXCEL_MAX_SERIAL = 2958465;
+var MIN_EPOCH_SECONDS = 1e8;
+var MAX_EPOCH_SECONDS = 1e11;
+var SERIAL_DATE_FORMS = "a full date (YYYY-MM-DD, M/D/YYYY or an ISO datetime \u2014 a month alone is ambiguous), an Excel serial (e.g. 45688), or Unix epoch seconds";
+function toExcelSerial(raw) {
+  const s = raw.trim();
+  if (/^\d+(\.\d+)?$/.test(s)) {
+    const n = Number(s);
+    if (n <= EXCEL_MAX_SERIAL) return n;
+    if (Number.isInteger(n) && n >= MIN_EPOCH_SECONDS && n < MAX_EPOCH_SECONDS) {
+      return epochSecondsToSerial(n);
+    }
+    return null;
+  }
+  if (/^\d{4}[-/]\d{1,2}$/.test(s)) return null;
+  const epoch = toEpochSeconds(s);
+  if (epoch === null) return null;
+  return epochSecondsToSerial(Number(epoch));
+}
+function epochSecondsToSerial(sec) {
+  return Math.floor(sec / 86400) + EXCEL_UNIX_EPOCH_OFFSET_DAYS;
+}
+function excelSerialToIso(n) {
+  if (!Number.isFinite(n)) return String(n);
+  const ms = (Math.floor(n) - EXCEL_UNIX_EPOCH_OFFSET_DAYS) * 864e5;
+  return new Date(ms).toISOString().slice(0, 10);
+}
+function epochSecondsToIso(sec) {
+  if (!Number.isFinite(sec)) return String(sec);
+  const iso = new Date(sec * 1e3).toISOString();
+  return sec % 86400 === 0 ? iso.slice(0, 10) : iso.replace(/\.\d{3}Z$/, "Z");
+}
 
 // src/commands/functions.ts
 var VALID_AGGS2 = ["SUM", "COUNT", "AVG", "MIN", "MAX"];
@@ -15627,19 +15885,37 @@ async function runFunctionsGet(cfg) {
   renderFunctionTable(cfg.out, [fn]);
   renderFunctionFilters(cfg.out, fn);
 }
+async function resolveDateField(client, templateId, token, signal) {
+  const index = await loadTemplateFields(client, templateId, { signal });
+  const field = resolveField(index, token, "--date-field");
+  if (!isDateField(field)) {
+    throw new Error(
+      `--date-field "${token}": "${field.name}" is a ${field.type} field; the default aggregation date field must be a Date field`
+    );
+  }
+  return field;
+}
 async function runFunctionsCreate(cfg) {
   validateName(cfg.name);
   const aggUpper = validateAgg(cfg.aggOriginal);
+  const dateField = cfg.dateField === void 0 ? void 0 : await resolveDateField(cfg.client, cfg.template, cfg.dateField, cfg.signal);
   const created = await create6(
     cfg.client,
     {
       name: cfg.name,
       template: cfg.template,
       valueField: cfg.valueField,
-      aggfun: aggUpper
+      aggfun: aggUpper,
+      ...dateField !== void 0 ? { dateField: dateField.id } : {}
     },
     { signal: cfg.signal }
   );
+  if (dateField === void 0) {
+    (cfg.err ?? process.stderr).write(
+      `warning: no --date-field given \u2014 period aggregations (DR.YTD/QTD/MTD/\u2026, functions data --agg YTD) will not work for function ${created.id}; set one with: dr functions update ${created.id} --date-field <Date field>
+`
+    );
+  }
   if (cfg.asJson) {
     writeJSONIndented(cfg.out, toJsonShape(created));
     return;
@@ -15654,13 +15930,14 @@ async function runFunctionsUpdate(cfg) {
   const hasField = cfg.field !== void 0;
   const hasAgg = cfg.aggOriginal !== void 0;
   const hasTemplate = cfg.template !== void 0;
-  if (!hasName && !hasField && !hasAgg && !hasTemplate) {
-    throw new Error("nothing to update (pass --name/--field/--agg/--template)");
+  const hasDateField = cfg.dateField !== void 0;
+  if (!hasName && !hasField && !hasAgg && !hasTemplate && !hasDateField) {
+    throw new Error("nothing to update (pass --name/--field/--agg/--template/--date-field)");
   }
   if (hasName) validateName(cfg.name);
   const aggUpper = hasAgg ? validateAgg(cfg.aggOriginal) : void 0;
   let result;
-  if (!hasField && !hasAgg && !hasTemplate) {
+  if (!hasField && !hasAgg && !hasTemplate && !hasDateField) {
     await rename2(cfg.client, cfg.id, cfg.name, {
       signal: cfg.signal
     });
@@ -15669,6 +15946,13 @@ async function runFunctionsUpdate(cfg) {
     const current = await getFull(cfg.client, cfg.id, {
       signal: cfg.signal
     });
+    const template = hasTemplate ? cfg.template : current.template;
+    if (template !== current.template && current.default_agg_datefield !== null && !hasDateField) {
+      throw new Error(
+        `function ${cfg.id} has default date field ${current.default_agg_datefield}, which belongs to the old template ${current.template}; pass --date-field <Date field of template ${template}> together with --template`
+      );
+    }
+    const dateField = hasDateField ? await resolveDateField(cfg.client, template, cfg.dateField, cfg.signal) : void 0;
     result = await update2(
       cfg.client,
       cfg.id,
@@ -15676,11 +15960,16 @@ async function runFunctionsUpdate(cfg) {
         name: hasName ? cfg.name : current.name,
         value_field: hasField ? cfg.field : current.value_field,
         aggfun: hasAgg ? aggUpper : current.aggfun,
-        template: hasTemplate ? cfg.template : current.template,
+        template,
         calculated_values: current.calculated_values,
         // Re-sent so the full PUT can't silently reset the currency-conversion
         // flag (same class of trap as calculated_values above).
-        is_fx_aware: current.is_fx_aware
+        is_fx_aware: current.is_fx_aware,
+        ...dateField !== void 0 ? {
+          default_agg_datefield: dateField.id,
+          // Keep a config the function already has; otherwise the platform default.
+          default_agg_config: current.default_agg_config ?? DEFAULT_AGG_CONFIG
+        } : {}
       },
       { signal: cfg.signal }
     );
@@ -15823,6 +16112,365 @@ async function runFunctionsDelete(cfg) {
     }
   });
 }
+var PERIOD_AGGS = [
+  "DEFAULT",
+  "YTD",
+  "YTG",
+  "QTD",
+  "QTG",
+  "MTD",
+  "MTG"
+];
+function validatePeriodAgg(orig) {
+  const upper = orig.trim().toUpperCase();
+  if (!PERIOD_AGGS.includes(upper)) {
+    throw new Error(`invalid --agg "${orig}" (valid: ${PERIOD_AGGS.join(", ")})`);
+  }
+  return upper;
+}
+function parseEvalFilterFlags(raw, flag) {
+  return raw.map((r) => {
+    const idx = r.indexOf("=");
+    const name = idx > 0 ? r.slice(0, idx).trim() : "";
+    const values = idx > 0 ? r.slice(idx + 1).split(",").map((v) => v.trim()).filter((v) => v !== "") : [];
+    if (name === "" || values.length === 0) {
+      throw new Error(`invalid ${flag} "${r}": expected NAME=V1[,V2\u2026]`);
+    }
+    return { flag, name, values };
+  });
+}
+var NUMERIC_FIELD_TYPES = /* @__PURE__ */ new Set(["integer", "float", "number", "numeric", "monetary"]);
+function resolveEvalFilters(index, specs) {
+  const seen = /* @__PURE__ */ new Set();
+  return specs.map((s) => {
+    const field = resolveField(index, s.name, s.flag);
+    if (seen.has(field.id)) {
+      throw new Error(
+        `field "${field.name}" is given more than once; put all its values in one ${s.flag} "${field.name}=V1,V2"`
+      );
+    }
+    seen.add(field.id);
+    const isDate = isDateField(field);
+    if (s.flag === "--date" && !isDate) {
+      throw new Error(
+        `--date "${s.name}=\u2026": "${field.name}" is a ${field.type} field, not Date; use --filter`
+      );
+    }
+    let values;
+    if (isDate) {
+      values = s.values.map((v) => {
+        const serial = toExcelSerial(v);
+        if (serial === null) {
+          throw new Error(
+            `invalid date "${v}" for Date field "${field.name}" (${s.flag}): expected ${SERIAL_DATE_FORMS}`
+          );
+        }
+        return serial;
+      });
+    } else if (NUMERIC_FIELD_TYPES.has(field.type.trim().toLowerCase())) {
+      values = s.values.map((v) => /^-?\d+(\.\d+)?$/.test(v) ? Number(v) : v);
+    } else {
+      values = [...s.values];
+    }
+    return { field, isDate, values, isExcluded: s.flag === "--exclude" };
+  });
+}
+function readableQueryError(msg) {
+  const decoded = String(decodeHtmlEntitiesDeep(msg));
+  const inner = [...decoded.matchAll(/\[\s*'((?:[^'\\]|\\.)*)'\s*\]/g)].map((m) => m[1]);
+  return inner.length > 0 ? inner.join("; ") : decoded;
+}
+function rethrowEvaluatorError(err, id, what) {
+  if (err instanceof CacheKeyHttpError) {
+    let msg = `function ${id} ${what}: HTTP ${err.status}: ${err.bodyText}`;
+    if (err.status === 400 && err.bodyText.includes("DateAgg")) {
+      msg += `
+hint: period aggregations need a default date field \u2014 dr functions update ${id} --date-field <Date field>`;
+    }
+    throw new Error(msg);
+  }
+  throw err;
+}
+function formatEvalNumber(v) {
+  if (v === null || v === void 0) return "-";
+  if (typeof v !== "number") return typeof v === "string" ? v : JSON.stringify(v);
+  if (!Number.isFinite(v) || Number.isInteger(v)) return String(v);
+  if (Math.abs(v) < 1) return String(Number(v.toPrecision(10)));
+  if (Math.abs(v) >= 1e15) return String(v);
+  return String(Math.round(v * 1e4) / 1e4);
+}
+async function runFunctionsData(cfg) {
+  if (cfg.id <= 0) throw new Error("function id must be positive");
+  const agg = validatePeriodAgg(cfg.aggOriginal);
+  const specs = [
+    ...parseEvalFilterFlags(cfg.filters, "--filter"),
+    ...parseEvalFilterFlags(cfg.dates, "--date")
+  ];
+  const fn = await getDetail(cfg.client, cfg.id, { signal: cfg.signal });
+  const resolved = specs.length === 0 ? [] : resolveEvalFilters(
+    await loadTemplateFields(cfg.client, fn.template, { signal: cfg.signal }),
+    specs
+  );
+  const body = {
+    queries: [
+      {
+        client_key: "q1",
+        agg_type: agg,
+        fields: resolved.map((r) => ({ name: r.field.name, values: r.values }))
+      }
+    ],
+    global_filters: [],
+    function_filters: []
+  };
+  let res;
+  try {
+    res = await data2(cfg.client, cfg.id, body, {
+      signal: cfg.signal,
+      pollIntervalMs: cfg.pollIntervalMs,
+      sleep: cfg.sleep
+    });
+  } catch (err) {
+    rethrowEvaluatorError(err, cfg.id, "data");
+  }
+  if (cfg.asJson) writeJSONIndented(cfg.out, res);
+  const results = Array.isArray(res.query_results) ? res.query_results : [];
+  const errors = results.filter((q) => q.error !== void 0 && q.error !== null);
+  if (errors.length > 0) {
+    throw new Error(
+      `function ${cfg.id} data: ` + errors.map((q) => readableQueryError(String(q.error?.msg ?? ""))).join("; ")
+    );
+  }
+  if (cfg.asJson) return;
+  const values = results.flatMap((q) => Array.isArray(q.res) ? q.res : []);
+  if (values.length === 0) {
+    cfg.out.write("(no data: nothing matches these filters)\n");
+    return;
+  }
+  const rows = [{ cells: [...resolved.map((r) => r.field.name), "VALUE"] }];
+  for (const r of values) {
+    const k = Array.isArray(r.k) ? r.k : [];
+    const keyCells = k.length === resolved.length ? k.map(
+      (kv, i) => resolved[i]?.isDate === true && typeof kv === "number" ? excelSerialToIso(kv) : formatEvalNumber(kv)
+    ) : resolved.map((_, i) => i === 0 ? JSON.stringify(k) : "");
+    rows.push({ cells: [...keyCells, formatEvalNumber(r.v)] });
+  }
+  writeTable11(cfg.out, rows);
+}
+function aggregateColumn(aggfun, values) {
+  const present = values.filter((v) => v !== null && v !== void 0 && v !== "");
+  const nums = present.map((v) => Number(v)).filter((n) => Number.isFinite(n));
+  switch (aggfun.trim().toUpperCase()) {
+    case "COUNT":
+      return present.length;
+    case "AVG":
+      return nums.length === 0 ? null : nums.reduce((a, b) => a + b, 0) / nums.length;
+    case "MIN":
+      return nums.length === 0 ? null : Math.min(...nums);
+    case "MAX":
+      return nums.length === 0 ? null : Math.max(...nums);
+    default:
+      return nums.reduce((a, b) => a + b, 0);
+  }
+}
+function drilldownCell(v, isDate) {
+  if (v === null || v === void 0) return "";
+  if (isDate && typeof v === "number") return epochSecondsToIso(v);
+  if (typeof v === "number") return formatEvalNumber(v);
+  if (typeof v === "string") return v;
+  return JSON.stringify(v);
+}
+function drilldownRowsToCsv(rows, schema) {
+  const cols = schema.fields.length > 0 ? schema.fields : Object.keys(rows[0] ?? {}).map((name) => ({ name }));
+  const dateCols = new Set(
+    schema.fields.filter((f) => (f.type ?? "").toLowerCase() === "date").map((f) => f.name)
+  );
+  const cell = (v) => {
+    if (v === null || v === void 0) return "";
+    if (typeof v === "string") return v;
+    return typeof v === "object" ? JSON.stringify(v) : String(v);
+  };
+  const lines = [formatCsvRow(cols.map((c) => c.name))];
+  for (const r of rows) {
+    lines.push(
+      formatCsvRow(
+        cols.map((c) => {
+          const v = r[c.name];
+          return dateCols.has(c.name) && typeof v === "number" ? epochSecondsToIso(v) : cell(v);
+        })
+      )
+    );
+  }
+  return lines.join("\n") + "\n";
+}
+async function runFunctionsDrilldown(cfg) {
+  if (cfg.id <= 0) throw new Error("function id must be positive");
+  if (cfg.forceCsv && cfg.outPath === void 0) {
+    throw new Error("--csv needs --out <file.csv>");
+  }
+  if (!Number.isInteger(cfg.limit) || cfg.limit < 0) {
+    throw new Error("--limit must be a non-negative integer (0 = all rows)");
+  }
+  const agg = validatePeriodAgg(cfg.aggOriginal);
+  const specs = [
+    ...parseEvalFilterFlags(cfg.filters, "--filter"),
+    ...parseEvalFilterFlags(cfg.excludes, "--exclude"),
+    ...parseEvalFilterFlags(cfg.dates, "--date")
+  ];
+  const fn = await getDetail(cfg.client, cfg.id, { signal: cfg.signal });
+  const index = await loadTemplateFields(cfg.client, fn.template, { signal: cfg.signal });
+  const resolved = resolveEvalFilters(index, specs);
+  const valueFieldName = index.fields.find((f) => f.id === fn.value_field)?.name ?? `field ${fn.value_field}`;
+  const aggLabel = `${fn.aggfun === "" ? "SUM" : fn.aggfun.toUpperCase()}(${valueFieldName})`;
+  const body = {
+    agg_type: [agg],
+    global_filters: [],
+    function_filters: [
+      resolved.map((r) => ({
+        values: r.values,
+        name: r.field.name,
+        type: r.field.type,
+        field: r.field.id,
+        function_id: cfg.id,
+        is_excluded: r.isExcluded,
+        show_in_graph: false
+      }))
+    ],
+    table_filters: []
+  };
+  const writeFile6 = cfg.writeFile ?? ((p, d) => fs11.writeFile(p, d));
+  const seams = { signal: cfg.signal, pollIntervalMs: cfg.pollIntervalMs, sleep: cfg.sleep };
+  const exportCsv2 = async (reason) => {
+    const outPath = cfg.outPath;
+    let exp;
+    try {
+      exp = await exportDrilldownCsv(cfg.client, cfg.id, body, seams);
+    } catch (err) {
+      rethrowEvaluatorError(err, cfg.id, "drilldown export");
+    }
+    await writeFile6(outPath, exp.bytes);
+    const table2 = parseCsvRows(new TextDecoder().decode(exp.bytes).replace(/^/, ""));
+    const header = table2[0] ?? [];
+    const col = header.findIndex((h) => h.trim() === valueFieldName);
+    const dataRows = table2.slice(1);
+    const aggValue2 = col < 0 ? null : aggregateColumn(
+      fn.aggfun,
+      dataRows.map((r) => r[col])
+    );
+    if (cfg.asJson) {
+      writeJSONIndented(cfg.out, {
+        function_id: cfg.id,
+        out: outPath,
+        source: "export_to_csv",
+        report_id: exp.reportId,
+        bytes: exp.bytes.length,
+        rows: dataRows.length,
+        columns: header.length,
+        aggregate: { label: aggLabel, value: aggValue2 }
+      });
+      return;
+    }
+    cfg.out.write(
+      `Wrote ${dataRows.length} rows \xD7 ${header.length} columns to ${outPath} (server CSV export${reason}, report ${exp.reportId}, ${exp.bytes.length} bytes).
+`
+    );
+    cfg.out.write(
+      col < 0 ? `(value field "${valueFieldName}" not found in the CSV header; no aggregate)
+` : `${aggLabel} over these rows: ${formatEvalNumber(aggValue2)}
+`
+    );
+  };
+  if (cfg.forceCsv) {
+    await exportCsv2("");
+    return;
+  }
+  let raw;
+  try {
+    raw = await drilldown(cfg.client, cfg.id, body, seams);
+  } catch (err) {
+    rethrowEvaluatorError(err, cfg.id, "drilldown");
+  }
+  const parsed2 = parseDrilldown(raw);
+  if (parsed2.kind === "too_large") {
+    if (cfg.outPath !== void 0) {
+      await exportCsv2(`; inline answer too large: ${parsed2.rows_count} rows`);
+      return;
+    }
+    if (cfg.asJson) writeJSONIndented(cfg.out, raw);
+    throw new Error(
+      `drill-down for function ${cfg.id} is too large to return inline (${parsed2.rows_count} rows \xD7 ${parsed2.cols_count} columns); re-run with --out <file.csv> to export it as CSV, or narrow it with more --filter flags`
+    );
+  }
+  const { rows, schema } = parsed2;
+  const aggValue = aggregateColumn(
+    fn.aggfun,
+    rows.map((r) => r[valueFieldName])
+  );
+  if (cfg.outPath !== void 0) {
+    await writeFile6(cfg.outPath, drilldownRowsToCsv(rows, schema));
+    if (cfg.asJson) {
+      writeJSONIndented(cfg.out, {
+        function_id: cfg.id,
+        out: cfg.outPath,
+        source: "inline",
+        rows: rows.length,
+        columns: schema.fields.length,
+        aggregate: { label: aggLabel, value: aggValue }
+      });
+      return;
+    }
+    cfg.out.write(
+      `Wrote ${rows.length} rows \xD7 ${schema.fields.length} columns to ${cfg.outPath} (inline drill-down).
+`
+    );
+    cfg.out.write(`${aggLabel} over these rows: ${formatEvalNumber(aggValue)}
+`);
+    return;
+  }
+  if (cfg.asJson) {
+    writeJSONIndented(cfg.out, raw);
+    return;
+  }
+  cfg.out.write(
+    `${rows.length} rows \xD7 ${schema.fields.length} columns (${schema.empty_fields.length} empty)
+`
+  );
+  cfg.out.write(`${aggLabel} over these rows: ${formatEvalNumber(aggValue)}
+`);
+  if (rows.length === 0) return;
+  const byName = new Map(schema.fields.map((f) => [f.name, f]));
+  let cols;
+  if (cfg.columns !== void 0 && cfg.columns.length > 0) {
+    cols = cfg.columns.map((c) => {
+      if (byName.has(c)) return c;
+      const loose = schema.fields.filter((f) => f.name.toLowerCase() === c.toLowerCase());
+      if (loose.length === 1) return loose[0].name;
+      throw new Error(
+        `unknown --columns entry "${c}"; drill-down columns: ${schema.fields.map((f) => f.name).join(", ")}`
+      );
+    });
+  } else {
+    cols = [.../* @__PURE__ */ new Set([...resolved.map((r) => r.field.name), valueFieldName])].filter(
+      (c) => byName.has(c)
+    );
+  }
+  const shown = cfg.limit === 0 ? rows : rows.slice(0, cfg.limit);
+  cfg.out.write("\n");
+  const table = [{ cells: cols }];
+  for (const r of shown) {
+    table.push({
+      cells: cols.map(
+        (c) => drilldownCell(r[c], (byName.get(c)?.type ?? "").toLowerCase() === "date")
+      )
+    });
+  }
+  writeTable11(cfg.out, table);
+  if (shown.length < rows.length) {
+    cfg.out.write(
+      `(showing ${shown.length} of ${rows.length} rows \u2014 --limit 0 for all, --columns to pick columns, --out <file.csv> for every column)
+`
+    );
+  }
+}
 function writeTable11(out, rows) {
   if (rows.length === 0) return;
   const widths = [];
@@ -15898,6 +16546,10 @@ function parseIntFlag(raw, flagName) {
   }
   return n;
 }
+function collectFlag(value, previous) {
+  return [...previous, value];
+}
+var DRILLDOWN_EXPORT_TIMEOUT_MS = 3e5;
 function registerFunctionsCommand(root) {
   const fn = root.command("functions").description("Operations on Datarails template functions");
   const listCmd = fn.command("list").description("List functions on this tenant").option("--json", "Output raw JSON instead of a table", false).action(async (opts) => {
@@ -15932,7 +16584,10 @@ function registerFunctionsCommand(root) {
   });
   addServerFlag(getCmd);
   addAccountFlag(getCmd);
-  const createCmd = fn.command("create").description("Create a new function").requiredOption("--name <name>", "Function name (no whitespace; required)").requiredOption("--template <id>", "Template ID (required)").requiredOption("--field <id>", "Value field ID (required)").option("--agg <kind>", "Aggregation: SUM, COUNT, AVG, MIN, MAX (default: SUM)", "SUM").option("--json", "Output raw JSON instead of a table", false).action(
+  const createCmd = fn.command("create").description("Create a new function").requiredOption("--name <name>", "Function name (no whitespace; required)").requiredOption("--template <id>", "Template ID (required)").requiredOption("--field <id>", "Value field ID (required)").option("--agg <kind>", "Aggregation: SUM, COUNT, AVG, MIN, MAX (default: SUM)", "SUM").option(
+    "--date-field <id|name>",
+    "Default aggregation date field (a Date field of the template). Needed for DR.YTD/QTD/MTD/\u2026 and `functions data --agg YTD`; without it a warning is printed"
+  ).option("--json", "Output raw JSON instead of a table", false).action(
     async (opts) => {
       const template = parseIntFlag(opts.template, "--template");
       const valueField = parseIntFlag(opts.field, "--field");
@@ -15944,6 +16599,7 @@ function registerFunctionsCommand(root) {
           template,
           valueField,
           aggOriginal: opts.agg ?? "SUM",
+          dateField: opts.dateField,
           asJson: opts.json === true,
           signal: setup.signal,
           out: process.stdout
@@ -15957,7 +16613,10 @@ function registerFunctionsCommand(root) {
   addAccountFlag(createCmd);
   const updateCmd = fn.command("update").description(
     "Update a function (name-only routes to the rename endpoint; structural changes read-modify-write a full PUT)"
-  ).argument("<id>", "function id").option("--name <name>", "New function name (no whitespace)").option("--field <id>", "New value field ID").option("--agg <kind>", "New aggregation: SUM, COUNT, AVG, MIN, MAX").option("--template <id>", "New template ID").option("--json", "Output raw JSON instead of a table", false).action(
+  ).argument("<id>", "function id").option("--name <name>", "New function name (no whitespace)").option("--field <id>", "New value field ID").option("--agg <kind>", "New aggregation: SUM, COUNT, AVG, MIN, MAX").option("--template <id>", "New template ID").option(
+    "--date-field <id|name>",
+    "Set the default aggregation date field (a Date field) used by DR.YTD/QTD/MTD/\u2026"
+  ).option("--json", "Output raw JSON instead of a table", false).action(
     async (idStr, opts) => {
       const id = parseFunctionIdArg(idStr);
       const field = opts.field !== void 0 ? parseIntFlag(opts.field, "--field") : void 0;
@@ -15971,6 +16630,7 @@ function registerFunctionsCommand(root) {
           field,
           aggOriginal: opts.agg,
           template,
+          dateField: opts.dateField,
           asJson: opts.json === true,
           signal: setup.signal,
           out: process.stdout
@@ -16016,6 +16676,106 @@ function registerFunctionsCommand(root) {
   );
   addServerFlag(setFiltersCmd);
   addAccountFlag(setFiltersCmd);
+  const dataCmd = fn.command("data").description(
+    "Evaluate a function the way the Excel add-in does (PUT /api/functions/<id>/data/v2): one value per filter-value combination; dates are sent as Excel serials"
+  ).argument("<id>", "function id").option(
+    "--filter <NAME=V1,V2>",
+    "Dimension filter by field name (or id); repeatable. Several values return one result per value. A value on a Date field is converted like --date",
+    collectFlag,
+    []
+  ).option(
+    "--date <NAME=DATE[,DATE]>",
+    'Date filter, e.g. "Reporting Date=2025-01-31" (YYYY-MM-DD, M/D/YYYY, an ISO datetime, an Excel serial, or epoch seconds; a bare month is refused); repeatable',
+    collectFlag,
+    []
+  ).option(
+    "--agg <period>",
+    "Period aggregation: DEFAULT, YTD, YTG, QTD, QTG, MTD, MTG",
+    "DEFAULT"
+  ).option("--timeout <seconds>", "Whole-command budget in seconds (default 30)").option("--json", "Print the server body verbatim", false).action(
+    async (idStr, opts) => {
+      const id = parseFunctionIdArg(idStr);
+      validatePeriodAgg(opts.agg ?? "DEFAULT");
+      const setup = await setupCall(opts.server, opts.account, batchSetupOptions(opts.timeout));
+      try {
+        await runFunctionsData({
+          client: setup.client,
+          id,
+          filters: opts.filter,
+          dates: opts.date,
+          aggOriginal: opts.agg ?? "DEFAULT",
+          asJson: opts.json === true,
+          signal: setup.signal,
+          out: process.stdout
+        });
+      } finally {
+        setup.cleanup();
+      }
+    }
+  );
+  addServerFlag(dataCmd);
+  addAccountFlag(dataCmd);
+  const drilldownCmd = fn.command("drilldown").description(
+    "The rows behind a function value (PUT /api/functions/<id>/drilldown/v4); with --out, a result too large to return inline is exported as CSV automatically"
+  ).argument("<id>", "function id").option(
+    "--filter <NAME=V1,V2>",
+    "Dimension filter by field name (or id); repeatable",
+    collectFlag,
+    []
+  ).option(
+    "--exclude <NAME=V1,V2>",
+    "Exclude these values of a field; repeatable",
+    collectFlag,
+    []
+  ).option(
+    "--date <NAME=DATE[,DATE]>",
+    'Date filter, e.g. "Reporting Date=2025-01-31"; repeatable',
+    collectFlag,
+    []
+  ).option(
+    "--agg <period>",
+    "Period aggregation: DEFAULT, YTD, YTG, QTD, QTG, MTD, MTG",
+    "DEFAULT"
+  ).option(
+    "--columns <names>",
+    "Comma-separated columns to print (default: the filtered fields and the value field)"
+  ).option("--limit <n>", "Rows to print; 0 = all", "20").option(
+    "--out <file.csv>",
+    "Write every row and column to a CSV file; a result over the inline cap is fetched through the server CSV export"
+  ).option("--csv", "Always use the server CSV export (needs --out)", false).option(
+    "--timeout <seconds>",
+    "Whole-command budget in seconds (default 30, or 300 with --out)"
+  ).option("--json", "Print the server body verbatim (with --out: a JSON summary)", false).action(
+    async (idStr, opts) => {
+      const id = parseFunctionIdArg(idStr);
+      validatePeriodAgg(opts.agg ?? "DEFAULT");
+      const limit = parseIntFlag(opts.limit ?? "20", "--limit");
+      const columns = opts.columns === void 0 ? void 0 : opts.columns.split(",").map((c) => c.trim()).filter((c) => c !== "");
+      const setupOpts = opts.timeout !== void 0 ? batchSetupOptions(opts.timeout) : opts.out !== void 0 ? { timeoutMs: DRILLDOWN_EXPORT_TIMEOUT_MS } : {};
+      const setup = await setupCall(opts.server, opts.account, setupOpts);
+      try {
+        await runFunctionsDrilldown({
+          client: setup.client,
+          id,
+          filters: opts.filter,
+          excludes: opts.exclude,
+          dates: opts.date,
+          aggOriginal: opts.agg ?? "DEFAULT",
+          columns,
+          limit,
+          outPath: opts.out,
+          forceCsv: opts.csv === true,
+          asJson: opts.json === true,
+          signal: setup.signal,
+          out: process.stdout
+        });
+      } finally {
+        setup.cleanup();
+      }
+    }
+  );
+  addServerFlag(drilldownCmd);
+  addAccountFlag(drilldownCmd);
   const deleteCmd = fn.command("delete").description("Delete a function by ID (two-step confirm)").argument("<id>", "function id (positive integer)").option(
     "--confirm-token <token>",
     "Token from a prior plan run \u2014 required to actually delete",
@@ -16064,7 +16824,7 @@ async function get7(client, alias, options) {
   }
   return out;
 }
-async function data2(client, alias, params, options) {
+async function data3(client, alias, params, options) {
   const path11 = `/finance-os/api/semantictables/v1/${rawPathSegmentEscape(alias)}/data`;
   const body = {
     limit: params.rows,
@@ -16126,7 +16886,7 @@ async function runSemanticTablesData(cfg) {
   }
   const parsedFilters = parseAggregateFilters(cfg.filters, cfg.excludes);
   const select = parseSelectFields(cfg.fields);
-  const env = await data2(
+  const env = await data3(
     cfg.client,
     cfg.alias,
     {
@@ -17450,7 +18210,7 @@ var LUT_SAVE_POLL_TIMEOUT_MS = 3e5;
 async function saveMappings(client, documentId, body, options = {}) {
   const interval = options.pollIntervalMs ?? LUT_SAVE_POLL_INTERVAL_MS;
   const timeout = options.timeoutMs ?? LUT_SAVE_POLL_TIMEOUT_MS;
-  const sleep4 = options.sleep ?? defaultPollSleep;
+  const sleep3 = options.sleep ?? defaultPollSleep;
   const now = options.now ?? Date.now;
   const deadline = now() + timeout;
   const path11 = `/api/documents/${documentId}/web_update_lut`;
@@ -17459,7 +18219,7 @@ async function saveMappings(client, documentId, body, options = {}) {
   if (first.status === 200) {
     return toResult(first.text);
   }
-  const cacheKey = extractCacheKey(first.text);
+  const cacheKey = extractCacheKey2(first.text);
   if (cacheKey === "") {
     throw new Error(
       `POST ${path11}: HTTP ${first.status} without a cache_key to join: ${truncateBody(first.text)}`
@@ -17472,7 +18232,7 @@ async function saveMappings(client, documentId, body, options = {}) {
         `lut save-mappings: the server is still writing after ${Math.round(timeout / 1e3)}s (task ${cacheKey}). The write is still running server-side \u2014 re-run the same command to rejoin it, or raise --timeout.`
       );
     }
-    await sleep4(interval, options.signal);
+    await sleep3(interval, options.signal);
     const tick = await postOnce(client, pollPath, payload, options.signal);
     if (tick.status === 200) {
       return toResult(tick.text);
@@ -17487,7 +18247,7 @@ async function postOnce(client, path11, payload, signal) {
   }
   throw new Error(`POST ${path11}: HTTP ${res.status}: ${truncateBody(text2)}`);
 }
-function extractCacheKey(text2) {
+function extractCacheKey2(text2) {
   try {
     const parsed2 = JSON.parse(text2);
     return typeof parsed2.cache_key === "string" ? parsed2.cache_key : "";
@@ -17770,7 +18530,7 @@ async function exportDocument(client, id, destinationOrgIds, override, reqOption
 async function pollDocumentJob(client, basePath, label, requestId, options = {}) {
   const interval = options.pollIntervalMs ?? AUTO_CALC_POLL_INTERVAL_MS;
   const timeout = options.timeoutMs ?? AUTO_CALC_POLL_TIMEOUT_MS;
-  const sleep4 = options.sleep ?? defaultSleep3;
+  const sleep3 = options.sleep ?? defaultSleep3;
   const now = options.now ?? Date.now;
   const deadline = now() + timeout;
   for (; ; ) {
@@ -17798,7 +18558,7 @@ async function pollDocumentJob(client, basePath, label, requestId, options = {})
         `${label} polling timed out after ${timeout}ms (request ${requestId} still processing)`
       );
     }
-    await sleep4(interval, options.signal);
+    await sleep3(interval, options.signal);
   }
 }
 
@@ -18269,14 +19029,14 @@ async function runLutData(cfg) {
   if (cfg.lutId <= 0) {
     throw new Error("lut id must be positive");
   }
-  const data3 = await getMappedData(cfg.client, cfg.documentId, cfg.lutId, {
+  const data4 = await getMappedData(cfg.client, cfg.documentId, cfg.lutId, {
     signal: cfg.signal
   });
   if (cfg.asJson) {
-    writeJSONIndented(cfg.out, data3);
+    writeJSONIndented(cfg.out, data4);
     return;
   }
-  const keys2 = Object.keys(data3);
+  const keys2 = Object.keys(data4);
   if (keys2.length === 0) {
     cfg.out.write(`(LUT ${cfg.lutId} on document ${cfg.documentId} is empty or unmapped)
 `);
@@ -18285,7 +19045,7 @@ async function runLutData(cfg) {
   const sortedKeys = [...keys2].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
   const rows = [{ cells: ["KEY", "VALUE"] }];
   for (const k of sortedKeys) {
-    rows.push({ cells: [k, renderLutValue(data3[k])] });
+    rows.push({ cells: [k, renderLutValue(data4[k])] });
   }
   writeTable15(cfg.out, rows);
   cfg.out.write(`
@@ -20376,14 +21136,14 @@ function renderDataflow(out, items) {
     ];
     const group = groups[col] ?? [];
     for (const it of group) {
-      const data3 = extractData(it.data);
+      const data4 = extractData(it.data);
       rows.push({
         cells: [
           String(it.order),
           it.type,
-          String(data3.entityId ?? 0),
-          data3.name ?? "",
-          data3.statusType ?? "",
+          String(data4.entityId ?? 0),
+          data4.name ?? "",
+          data4.statusType ?? "",
           String(it.connections.length),
           String(it.children.length)
         ]
@@ -20484,7 +21244,7 @@ async function getData2(client, params, options) {
   }
   return out;
 }
-async function drilldown(client, params, options) {
+async function drilldown2(client, params, options) {
   const path11 = "/finance-os/api/metrics/v1/drill_down";
   const body = {
     metric_ids: params.metric_ids
@@ -21023,7 +21783,7 @@ async function waitForReAggregation(cfg) {
   let interval = cfg.pollIntervalMs ?? REAGG_POLL_INTERVAL_MS;
   const maxInterval = cfg.maxPollIntervalMs ?? REAGG_POLL_MAX_INTERVAL_MS;
   const timeout = cfg.timeoutMs ?? REAGG_POLL_TIMEOUT_MS;
-  const sleep4 = cfg.sleep ?? defaultSleep4;
+  const sleep3 = cfg.sleep ?? defaultSleep4;
   const now = cfg.now ?? Date.now;
   const accepted = [...cfg.accepted];
   const observedProcessing = /* @__PURE__ */ new Set();
@@ -21058,7 +21818,7 @@ async function waitForReAggregation(cfg) {
       break;
     }
     try {
-      await sleep4(interval, cfg.signal);
+      await sleep3(interval, cfg.signal);
     } catch {
       aborted = true;
       break;
@@ -21750,8 +22510,8 @@ function detectApiTruncation(env) {
   }
   return false;
 }
-function readCountUniqueRows(data3, field) {
-  const rows = Array.isArray(data3) ? data3 : null;
+function readCountUniqueRows(data4, field) {
+  const rows = Array.isArray(data4) ? data4 : null;
   if (rows === null) return null;
   let best = null;
   for (const row of rows) {
@@ -23665,7 +24425,7 @@ async function waitForSuggestionRun(r, cfg, runId) {
   let interval = cfg.pollIntervalMs ?? SUGGESTIONS_POLL_INTERVAL_MS;
   const maxInterval = cfg.maxPollIntervalMs ?? SUGGESTIONS_POLL_MAX_INTERVAL_MS;
   const timeout = cfg.timeoutMs ?? SUGGESTIONS_POLL_TIMEOUT_MS;
-  const sleep4 = cfg.sleep ?? defaultSleep5;
+  const sleep3 = cfg.sleep ?? defaultSleep5;
   const now = cfg.now ?? Date.now;
   const errOut = cfg.errOut ?? process.stderr;
   const start = now();
@@ -23695,7 +24455,7 @@ async function waitForSuggestionRun(r, cfg, runId) {
       break;
     }
     try {
-      await sleep4(interval, cfg.signal);
+      await sleep3(interval, cfg.signal);
     } catch {
       aborted = true;
       break;
@@ -25303,12 +26063,12 @@ async function runMetricsList(cfg) {
   if (cfg.raw) {
     const env2 = await listRaw2(cfg.client, { signal: cfg.signal });
     envelopeErr(env2.success, env2.error);
-    const data3 = decodeHtmlEntitiesDeep(env2.data);
+    const data4 = decodeHtmlEntitiesDeep(env2.data);
     if (cfg.asJson) {
-      writeJSONIndented(cfg.out, data3);
+      writeJSONIndented(cfg.out, data4);
       return;
     }
-    renderMetricsRawTable(cfg.out, data3);
+    renderMetricsRawTable(cfg.out, data4);
     return;
   }
   const env = await listSemantic(cfg.client, {
@@ -25406,7 +26166,7 @@ async function runMetricsDrilldown(cfg) {
     throw new Error(`--id list capped at 50 (got ${cfg.ids.length})`);
   }
   const dimFilters = parseDimensionFilters(cfg.filters);
-  const env = await drilldown(
+  const env = await drilldown2(
     cfg.client,
     {
       metric_ids: cfg.ids,
@@ -25853,83 +26613,13 @@ async function getTemplateFields(client, templateId, options) {
   }
   return result;
 }
-async function putDataOnce(client, path11, body, options) {
-  const res = await client.do("PUT", path11, body, options);
-  const text2 = await res.text();
-  if (res.status === 401 || res.status === 403) {
-    throw new Error(`PUT ${path11}: HTTP ${res.status}: ${truncate5(text2, 200)}`);
-  }
-  if (res.status !== 200 && res.status !== 409 && (res.status < 200 || res.status >= 300)) {
-    throw new Error(`PUT ${path11}: HTTP ${res.status}: ${truncate5(text2, 200)}`);
-  }
-  if (text2 === "" || text2 === '""') {
-    return { status: res.status, parsed: null };
-  }
-  try {
-    return { status: res.status, parsed: JSON.parse(text2) };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`PUT ${path11}: decode: ${msg}`);
-  }
-}
-var WIDGET_DATA_POLL_INTERVAL_MS = 500;
-var defaultSleep6 = (ms, signal) => new Promise((resolve3, reject) => {
-  if (signal?.aborted) {
-    reject(signal.reason ?? new Error("aborted"));
-    return;
-  }
-  const onAbort = () => {
-    clearTimeout(t);
-    reject(signal?.reason ?? new Error("aborted"));
-  };
-  const t = setTimeout(() => {
-    signal?.removeEventListener("abort", onAbort);
-    resolve3();
-  }, ms);
-  signal?.addEventListener("abort", onAbort, { once: true });
-});
 async function putDataWithPolling(client, dashboardId, id, payload, options = {}) {
-  const interval = options.pollIntervalMs ?? WIDGET_DATA_POLL_INTERVAL_MS;
-  const sleep4 = options.sleep ?? defaultSleep6;
-  const path11 = `/api/dashboards/${dashboardId}/widgets/${id}/data`;
-  const body = JSON.stringify(payload);
-  const first = await putDataOnce(client, path11, body, options);
-  if (first.status === 200) {
-    return first.parsed;
-  }
-  const task = first.parsed !== null && typeof first.parsed === "object" ? first.parsed : {};
-  const cacheKey = typeof task["cache_key"] === "string" ? task["cache_key"] : "";
-  if (cacheKey === "") {
-    throw new Error(
-      `PUT ${path11}: 409 without cache_key: ${truncate5(JSON.stringify(first.parsed ?? ""), 200)}`
-    );
-  }
-  const pollPath = `${path11}?cache_key=${encodeURIComponent(cacheKey)}`;
-  for (; ; ) {
-    try {
-      await sleep4(interval, options.signal);
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      throw new Error(`widget data polling timed out: ${reason}`);
-    }
-    let result;
-    try {
-      result = await putDataOnce(client, pollPath, body, options);
-    } catch (err) {
-      if (options.signal?.aborted) {
-        const reason = options.signal.reason instanceof Error ? options.signal.reason.message : String(options.signal.reason ?? "aborted");
-        throw new Error(`widget data polling timed out: ${reason}`);
-      }
-      throw err;
-    }
-    if (result.status === 200) {
-      return result.parsed;
-    }
-  }
-}
-function truncate5(s, n) {
-  if (s.length <= n) return s;
-  return s.slice(0, n) + "\u2026";
+  return putWithCacheKeyPolling(
+    client,
+    `/api/dashboards/${dashboardId}/widgets/${id}/data`,
+    payload,
+    { ...options, label: "widget data" }
+  );
 }
 
 // src/commands/_shellQuote.ts
@@ -29761,9 +30451,6 @@ function registerSkillCommand(root) {
   });
 }
 
-// src/commands/datamappers.ts
-import { setTimeout as sleep3 } from "timers/promises";
-
 // src/api/datamappers.ts
 async function list20(client, tableId, options) {
   const out = await client.getJSON(`/api/templates/${tableId}/mappers`, options);
@@ -29797,14 +30484,6 @@ async function create12(client, tableId, body, options) {
   }
   return out;
 }
-async function update8(client, id, body, options) {
-  const path11 = `/api/templates/mappers/${id}`;
-  const out = await client.putJSON(path11, body, options);
-  if (out === null) {
-    throw new Error(`PUT ${path11}: empty response from datamapper update`);
-  }
-  return out;
-}
 async function deleteById12(client, tableId, id, options) {
   await client.deleteJSON(`/api/templates/${tableId}/mappers/${id}`, options);
 }
@@ -30006,16 +30685,16 @@ function validateCalcFields(entries) {
     if (isLikelyValidCalcFormula(entry.formula)) continue;
     const name = entry.name === "" ? "(unnamed)" : entry.name;
     const trimmed = entry.formula.trim();
-    const preview = trimmed.slice(0, 80);
-    throw new Error(formatCalcFieldError(name, preview, trimmed));
+    const preview2 = trimmed.slice(0, 80);
+    throw new Error(formatCalcFieldError(name, preview2, trimmed));
   }
   const arityViolations = findArityViolations(entries);
   if (arityViolations.length > 0) {
     throw new Error(formatArityViolation(arityViolations[0]));
   }
 }
-function formatCalcFieldError(name, preview, full) {
-  const head = `calculated_fields["${name}"]: formula "${preview}"`;
+function formatCalcFieldError(name, preview2, full) {
+  const head = `calculated_fields["${name}"]: formula "${preview2}"`;
   if (full === "") {
     return `${head} is empty \u2014 every calc field needs a formula.`;
   }
@@ -30528,34 +31207,69 @@ async function runDatamappersUpdate(cfg) {
       "merge"
     );
   }
+  const err = cfg.err ?? process.stderr;
   const { decoded: decodedBody, changeCount } = decodeBodyEntitiesDeep(body);
   if (changeCount > 0) {
-    process.stderr.write(
-      `note: decoded ${changeCount} HTML entit${changeCount === 1 ? "y" : "ies"} (&quot; \u2192 ", &amp; \u2192 &, &lt; \u2192 <, &gt; \u2192 >) in the request body \u2014 mirrors the legacy webclient's ajaxService.success post-processing; the server's GET response carries the entities and the PUT-side parser doesn't decode them.
+    err.write(
+      `note: decoded ${changeCount} HTML entit${changeCount === 1 ? "y" : "ies"} (&quot; \u2192 ", &amp; \u2192 &, &lt; \u2192 <, &gt; \u2192 >) in the request body \u2014 mirrors the legacy webclient's ajaxService.success post-processing; the server's GET response carries the entities and the mapper compiler doesn't decode them.
 `
     );
     body = decodedBody;
   }
   validateCalcFields(extractCalcFields(body));
-  const err = cfg.err ?? process.stderr;
-  const scanBaseline = rescanValue === "latest" && cfg.verifyScanDispatch !== void 0 ? await captureScanBaseline(cfg.client, cfg.id, cfg.signal, err) : void 0;
-  let updated;
+  const details = await getDetails2(cfg.client, cfg.id, { signal: cfg.signal });
+  const templateId = details.template.id;
+  const payloadVersion = body["document_version_id"];
+  if (payloadVersion != null && !(Number.isInteger(payloadVersion) && payloadVersion > 0)) {
+    throw new Error(
+      `payload document_version_id must be a positive integer, got ${JSON.stringify(payloadVersion)}`
+    );
+  }
+  const versionId = payloadVersion ?? details.from_version;
+  if (typeof versionId !== "number") {
+    throw new Error(
+      `mapper ${cfg.id} has no source document version (typical after an org import or template push). Add "document_version_id" to the payload: an ACTIVE version of one of its documents (\`dr filebox versions <filebox_id>\`), with a sheet_name that exists in it`
+    );
+  }
+  const current = await get14(cfg.client, templateId, cfg.id, { signal: cfg.signal });
+  for (const key of ["id", "mapped_documents_ids", "previous_version", "mapping_date"]) {
+    delete body[key];
+  }
+  const boundDocs = current.mapped_documents_ids ?? [];
+  const payloadDocs = body["selected_document_ids"];
+  const hasPayloadDocs = Array.isArray(payloadDocs) && payloadDocs.length > 0;
+  if (boundDocs.length === 0 && !hasPayloadDocs) {
+    throw new Error(
+      `mapper ${cfg.id} is bound to no documents, so it is most likely an older version that an update or a UI publish replaced. Find the current one with \`dr datamappers list --table ${templateId}\`, or name the documents in the payload with "selected_document_ids"`
+    );
+  }
+  body = {
+    // GET returns the name HTML-escaped; sent back as is, it would be stored escaped twice.
+    name: decodeHtmlEntitiesDeep(details.name),
+    ordinal: current.ordinal,
+    ...body,
+    // Pinned after the spread: a null version or an empty doc list in the
+    // payload would otherwise publish a version bound to nothing.
+    document_version_id: versionId,
+    selected_document_ids: hasPayloadDocs ? payloadDocs : boundDocs,
+    datamapper_id: cfg.id
+  };
+  const publishPath = `/api/templates/${templateId}/mappers`;
+  let published;
   try {
-    updated = await update8(cfg.client, cfg.id, body, {
-      signal: cfg.signal
-    });
+    published = await create12(cfg.client, templateId, body, { signal: cfg.signal });
   } catch (err2) {
     const msg = err2 instanceof Error ? err2.message : String(err2);
     if (/HTTP 500/.test(msg)) {
-      const hint = "hint: the server logs an `ETLError: Custom Columns: The creation of '<field>' field has failed due to incorrect formula syntax.` line for this case but the response body is a bare 500 HTML page. Common causes the client-side guard cannot detect: (1) a [field] reference in a calc formula that does not resolve to any header `map_to`, calc-field `name`, or system field (`[FileBox_ID]`, `[System_Year]`, `[Posting Date]`, \u2026), (2) an unsupported function name (try copying the function spelling from another working calc field via `dr datamappers get`), (3) a string literal that's a plain-English placeholder (e.g. `\"Customer or Client name\"`) which parses but the ETL refuses. Iterate on calc-field formulas one at a time. If every formula looks correct and PUT still 500s, fall back to the workaround: `dr datamappers create from-file <table> --file <new.json>` then `dr datamappers delete <old_id> --table <table>` (note: this orphans references \u2014 LUTs/dashboards/functions pointing at the old mapper id break).";
+      const hint = "hint: the server logs an `ETLError: Custom Columns: The creation of '<field>' field has failed due to incorrect formula syntax.` line for this case but the response body is a bare 500 HTML page. Common causes the client-side guard cannot detect: (1) a [field] reference in a calc formula that does not resolve to any header `map_to`, calc-field `name`, or system field (`[FileBox_ID]`, `[System_Year]`, `[Posting Date]`, \u2026), (2) an unsupported function name (try copying the function spelling from another working calc field via `dr datamappers get`), (3) a string literal that's a plain-English placeholder (e.g. `\"Customer or Client name\"`) which parses but the ETL refuses. Iterate on calc-field formulas one at a time.";
       const responseBody = extractResponseBodyFromError(msg);
       let logPath;
       try {
         logPath = await writeErrorLog({
           command: `dr datamappers update ${cfg.id} --payload-file ${payloadFile}`,
           server: cfg.serverFlag ?? "",
-          method: "PUT",
-          url: `/api/templates/mappers/${cfg.id}`,
+          method: "POST",
+          url: publishPath,
           status: 500,
           requestBody: body,
           responseBody,
@@ -30574,103 +31288,26 @@ ${hint}${logSuffix}`);
     throw err2;
   }
   if (cfg.asJson) {
-    writeJSONIndented(cfg.out, updated);
+    writeJSONIndented(cfg.out, published);
   } else {
-    renderMappersTable(cfg.out, [updated]);
-  }
-  if (scanBaseline !== void 0) {
-    const opts = cfg.verifyScanDispatch ?? {};
-    const started2 = await waitForNewScan(cfg.client, scanBaseline, cfg.signal, opts);
-    if (!started2) {
-      const docIds = await mappedDocumentIds(
-        cfg.client,
-        scanBaseline.templateId,
-        cfg.id,
-        cfg.signal
-      );
-      err.write(
-        formatNoScanWarning({
-          mapperId: cfg.id,
-          templateId: scanBaseline.templateId,
-          timeoutMs: opts.timeoutMs ?? DEFAULT_SCAN_DISPATCH_TIMEOUT_MS,
-          docIds
-        })
-      );
-    }
-  }
-}
-var DEFAULT_SCAN_DISPATCH_TIMEOUT_MS = 3e4;
-var DEFAULT_SCAN_DISPATCH_POLL_MS = 2e3;
-function scanFingerprint(report) {
-  let maxScanId = 0;
-  for (const doc of report.documents ?? []) {
-    for (const v of doc.versions ?? []) {
-      if (typeof v.scan_id === "number" && v.scan_id > maxScanId) maxScanId = v.scan_id;
-    }
-  }
-  return `${report.scans_status?.last_updated ?? ""}|${maxScanId}`;
-}
-async function captureScanBaseline(client, mapperId, signal, err) {
-  try {
-    const details = await getDetails2(client, mapperId, { signal });
-    const templateId = details.template.id;
-    const report = await getStatus(client, templateId, { signal });
-    return { templateId, fingerprint: scanFingerprint(report) };
-  } catch (e) {
-    if (signal.aborted) throw e;
-    err.write(
-      "note: could not read the scan status before the update, so dr cannot confirm a rescan starts. Check with `dr scans status <template_id>` afterwards.\n"
-    );
-    return void 0;
-  }
-}
-async function waitForNewScan(client, baseline, signal, opts) {
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_SCAN_DISPATCH_TIMEOUT_MS;
-  const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_SCAN_DISPATCH_POLL_MS;
-  const deadline = Date.now() + timeoutMs;
-  for (; ; ) {
-    try {
-      const report = await getStatus(client, baseline.templateId, { signal });
-      if (scanFingerprint(report) !== baseline.fingerprint) return true;
-    } catch (e) {
-      if (signal.aborted) throw e;
-    }
-    const remaining = deadline - Date.now();
-    if (remaining <= 0) return false;
-    await sleep3(Math.min(pollIntervalMs, remaining), void 0, { signal });
-  }
-}
-async function mappedDocumentIds(client, templateId, mapperId, signal) {
-  try {
-    const mapper = await get14(client, templateId, mapperId, { signal });
-    return Array.isArray(mapper.mapped_documents_ids) ? mapper.mapped_documents_ids : void 0;
-  } catch (e) {
-    if (signal.aborted) throw e;
-    return void 0;
+    renderMappersTable(cfg.out, [published]);
   }
-}
-function formatNoScanWarning(p) {
-  const secs = Math.round(p.timeoutMs / 1e3);
-  const lines = [
-    `warning: mapper ${p.mapperId} was saved, but no new scan showed up on template ${p.templateId} within ${secs}s.`,
-    '  Either the scan is still queued, or this server predates the DR-54200 fix and ignored rescan="latest", so existing data still has the old config.',
-    `  Check first: dr scans status ${p.templateId}`
-  ];
-  if (p.docIds !== void 0 && p.docIds.length === 0) {
-    lines.push("  The mapper has no bound documents, so there is nothing to scan.");
-  } else {
-    const docFlags = p.docIds !== void 0 ? p.docIds.map((d) => `--doc ${d}`).join(" ") : "--doc <doc_id> [--doc <doc_id> ...]";
-    lines.push(
-      "  If no new scan appears there, re-bind the mapper to its current documents with a rescan:"
+  err.write(
+    `note: mapper ${cfg.id} was published as new version ${published.id} on template ${templateId}; use ${published.id} for later updates.
+`
+  );
+  const declaredCalcNames = extractCalcFields(body).map((c) => c.name).filter((n) => n !== "");
+  if (declaredCalcNames.length > 0 && rescanValue !== "") {
+    const result = await verifyCalcFieldsMaterialise(
+      cfg.client,
+      templateId,
+      declaredCalcNames,
+      cfg.signal,
+      cfg.verifyCalcFieldsOpts
     );
-    if (p.docIds === void 0) {
-      lines.push(
-        `    dr datamappers get ${p.mapperId} --table ${p.templateId} --json   # read mapped_documents_ids`
-      );
-    }
-    lines.push(`    dr datamappers bind ${p.mapperId} ${docFlags} --rescan latest`);
+    const timeoutMs = cfg.verifyCalcFieldsOpts?.timeoutMs ?? 3e4;
+    err.write(formatVerifyResult(templateId, result, timeoutMs));
   }
-  return lines.join("\n") + "\n";
 }
 async function buildConveniencePayload(client, tableId, name, versionId, sheet, flags, signal) {
   const fieldTypes = parseFieldOverrides(flags.fieldOverrides);
@@ -31283,8 +31920,12 @@ function registerDatamappersCommand(root) {
   addServerFlag(fromFileCmd);
   addAccountFlag(fromFileCmd);
   const updateCmd = dm.command("update").description(
-    "Update a datamapper in place (payload-file only \u2014 server accepts config+sheet_name+rescan). `--rescan latest` (the default) re-extracts the LATEST version of each document bound to the mapper. Servers without the DR-54200 fix save the config and start no scan, so after the update dr watches the template for a new scan and, when none shows up, prints how to check `dr scans status` and the `dr datamappers bind` fallback. For a full historical rescan (every calculated field re-executed against every document version ever uploaded), use `dr rescan table <template_id>` instead \u2014 that is far more expensive and higher-blast."
-  ).argument("<mapper_id>", "mapper id (positive integer)").option("--payload-file <path>", "Path to a JSON file with the PUT body (required)", "").option(
+    'Update a datamapper (payload-file only: config + sheet_name, optionally name). Publishes the payload as a new version of the mapper, the way the UI "Publish and scan" does: new columns are added to the table, the new version takes over the documents of the old one, and the old version is unbound. The new version has a NEW mapper id, which dr prints. `--rescan latest` (the default) re-extracts the LATEST version of each bound document, then dr checks that any calculated fields in the payload appear on the table. For a full historical rescan (every calculated field re-executed against every document version ever uploaded), use `dr rescan table <template_id>` instead \u2014 that is far more expensive and higher-blast.'
+  ).argument("<mapper_id>", "mapper id (positive integer)").option(
+    "--payload-file <path>",
+    "Path to a JSON file with the mapper body: config, sheet_name, optional name (required)",
+    ""
+  ).option(
     "--field <NAME:TYPE>",
     'Set a column type via fields_to_change (Text|Float|Date|Integer). Repeatable. Mirrors the UI "Publish and scan" so a calc column referencing a LUT-injected column materialises instead of 500ing on inferred types. Note: the server blocks a type change (HTTP 400) when the template has more than one mapper.',
     collectArrayOpt,
@@ -31306,8 +31947,7 @@ function registerDatamappersCommand(root) {
           serverFlag: opts.server ?? "",
           asJson: opts.json === true,
           signal: setup.signal,
-          out: process.stdout,
-          verifyScanDispatch: {}
+          out: process.stdout
         });
       } finally {
         setup.cleanup();
@@ -33042,7 +33682,7 @@ async function create15(client, body, reqOptions) {
   }
   return out;
 }
-async function update9(client, id, body, reqOptions) {
+async function update8(client, id, body, reqOptions) {
   const path11 = `/api/v3/data_integrations/${id}/`;
   const out = await client.putJSON(path11, body, reqOptions);
   if (out === null) {
@@ -34802,7 +35442,7 @@ async function captureDataQuerySyncBaseline(client, fileboxId, periods, signal)
     );
   }
 }
-var defaultSleep7 = (ms, signal) => new Promise((resolve3, reject) => {
+var defaultSleep6 = (ms, signal) => new Promise((resolve3, reject) => {
   if (signal?.aborted) {
     reject(signal.reason ?? new Error("aborted"));
     return;
@@ -34820,7 +35460,7 @@ var defaultSleep7 = (ms, signal) => new Promise((resolve3, reject) => {
 async function waitForDataQuerySync(cfg) {
   let interval = cfg.pollIntervalMs ?? DQ_WAIT_POLL_INTERVAL_MS;
   const maxInterval = cfg.maxPollIntervalMs ?? DQ_WAIT_POLL_MAX_INTERVAL_MS;
-  const sleep4 = cfg.sleep ?? defaultSleep7;
+  const sleep3 = cfg.sleep ?? defaultSleep6;
   const now = cfg.now ?? Date.now;
   const start = now();
   const deadline = start + cfg.timeoutSec * 1e3;
@@ -34862,7 +35502,7 @@ async function waitForDataQuerySync(cfg) {
       break;
     }
     try {
-      await sleep4(interval, cfg.signal);
+      await sleep3(interval, cfg.signal);
     } catch {
       outcome = "cancelled";
       break;
@@ -36173,7 +36813,7 @@ async function runFileboxSetVersionFileStatus(cfg) {
     throw new Error("version id must be positive");
   }
   const err = cfg.err ?? process.stderr;
-  const sleep4 = cfg.sleep ?? defaultCycleTagSleep;
+  const sleep3 = cfg.sleep ?? defaultCycleTagSleep;
   const settleMs = cfg.tagSettleDelayMs ?? CYCLE_TAG_SETTLE_DELAY_MS;
   const details = await getDetails(cfg.client, cfg.docId, { signal: cfg.signal });
   const tag = (details.tags_config ?? []).find(isFileStatusTag);
@@ -36266,7 +36906,7 @@ async function runFileboxSetVersionFileStatus(cfg) {
     }
   };
   const readBack = async () => {
-    await sleep4(settleMs, cfg.signal);
+    await sleep3(settleMs, cfg.signal);
     return readVersionForConfirm(cfg.client, cfg.versionId, cfg.docId, cfg.signal);
   };
   await write();
@@ -38581,7 +39221,7 @@ function syncCallTimeoutMs(waitMs) {
   if (waitMs <= 0) return void 0;
   return waitMs + SYNC_SETUP_OVERHEAD_MS;
 }
-var defaultSleep8 = (ms, signal) => new Promise((resolve3, reject) => {
+var defaultSleep7 = (ms, signal) => new Promise((resolve3, reject) => {
   if (signal?.aborted) {
     reject(signal.reason ?? new Error("aborted"));
     return;
@@ -38601,7 +39241,7 @@ async function runIntegrationsSync(cfg) {
     throw new Error("integration id must be positive");
   }
   const interval = cfg.pollIntervalMs ?? INTEGRATIONS_SYNC_POLL_INTERVAL_MS;
-  const sleep4 = cfg.sleep ?? defaultSleep8;
+  const sleep3 = cfg.sleep ?? defaultSleep7;
   const resp = await resync(cfg.client, cfg.id, {
     signal: cfg.signal
   });
@@ -38650,7 +39290,7 @@ async function runIntegrationsSync(cfg) {
         return;
       }
       try {
-        await sleep4(interval, inner.signal);
+        await sleep3(interval, inner.signal);
       } catch {
         cfg.out.write(
           `Timed out waiting for sync to finish \u2014 last status was ${orDash2(lastStatus)}
@@ -38740,7 +39380,7 @@ async function runIntegrationsUpdate(cfg) {
     throw new Error("--payload-file is required");
   }
   const body = await readJsonPayload(pf);
-  const updated = await update9(cfg.client, cfg.id, body, {
+  const updated = await update8(cfg.client, cfg.id, body, {
     signal: cfg.signal
   });
   if (cfg.asJson) {
@@ -44274,7 +44914,7 @@ async function runReconciliationAccountsUpdateSettings(cfg) {
   const current = await getAccountSettings(cfg.client, {}, { signal: cfg.signal });
   const currentByKey = new Map(current.map((s) => [settingsKey(s), s]));
   const changed = [];
-  const preview = [];
+  const preview2 = [];
   for (const want of cfg.settings) {
     const have = currentByKey.get(settingsKey(want));
     let what;
@@ -44286,8 +44926,8 @@ async function runReconciliationAccountsUpdateSettings(cfg) {
       what = diffs.join(", ");
     }
     changed.push(want);
-    if (preview.length < 5) {
-      preview.push(`  ${want.entity ?? ""} / ${want.account_group ?? ""} / ${want.name}: ${what}`);
+    if (preview2.length < 5) {
+      preview2.push(`  ${want.entity ?? ""} / ${want.account_group ?? ""} / ${want.name}: ${what}`);
     }
   }
   const unchanged = n - changed.length;
@@ -44314,10 +44954,10 @@ async function runReconciliationAccountsUpdateSettings(cfg) {
         `unchanged: ${unchanged} (already match the tenant \u2014 skipped)`,
         `by frequency: ${[...byFrequency].map(([f, c]) => `${f} ${c}`).join(", ")}`,
         "changes:",
-        ...preview
+        ...preview2
       ];
-      if (changed.length > preview.length) {
-        lines.push(`  \u2026 (+${changed.length - preview.length} more)`);
+      if (changed.length > preview2.length) {
+        lines.push(`  \u2026 (+${changed.length - preview2.length} more)`);
       }
       return lines;
     },
@@ -44743,16 +45383,16 @@ verify the date matches the accounts' reporting period (try \`dr reconciliation
     describe: async () => {
       let signOffsReset = 0;
       let bootstraps = 0;
-      const preview = [];
+      const preview2 = [];
       for (const id of accountIds) {
         const account = byId.get(id);
         if (account.members.length === 0) bootstraps += 1;
         for (const r of changesByAccount.get(id)) {
           const current = account.members.find((m) => m.type === r.row.type);
           if (current?.is_sign_off === true) signOffsReset += 1;
-          if (preview.length < 5) {
+          if (preview2.length < 5) {
             const from = current === void 0 ? "(no slot)" : `${current.name} (user ${current.user_id})`;
-            preview.push(
+            preview2.push(
               `  ${account.account_name} (${id}) ${r.row.type}: ${from} \u2192 ${r.name} (user ${r.row.userId})`
             );
           }
@@ -44769,8 +45409,8 @@ verify the date matches the accounts' reporting period (try \`dr reconciliation
           `no member slots yet: ${bootstraps} account${plural(bootstraps)} \u2014 both slots are initialized, the unlisted role as Unassigned`
         );
       }
-      lines.push("changes:", ...preview);
-      if (changeCount > preview.length) lines.push(`  \u2026 (+${changeCount - preview.length} more)`);
+      lines.push("changes:", ...preview2);
+      if (changeCount > preview2.length) lines.push(`  \u2026 (+${changeCount - preview2.length} more)`);
       return lines;
     },
     execute: async () => {
@@ -44868,13 +45508,13 @@ verify the date matches the accounts' reporting period (try \`dr reconciliation
     confirmCmd: cfg.confirmCmd,
     describe: async () => {
       let signOffsReset = 0;
-      const preview = [];
+      const preview2 = [];
       for (const id of accountIds) {
         const account = byId.get(id);
         for (const { row, current } of clearsByAccount.get(id)) {
           if (current.is_sign_off) signOffsReset += 1;
-          if (preview.length < 5) {
-            preview.push(
+          if (preview2.length < 5) {
+            preview2.push(
               `  ${account.account_name} (${id}) ${row.type}: ${current.name} (user ${current.user_id}) \u2192 Unassigned`
             );
           }
@@ -44886,9 +45526,9 @@ verify the date matches the accounts' reporting period (try \`dr reconciliation
         `unchanged: ${unchanged.length} (slot already Unassigned, or the account has no member slots \u2014 skipped)`,
         `sign-offs reset: ${signOffsReset}`,
         "changes:",
-        ...preview
+        ...preview2
       ];
-      if (clearCount > preview.length) lines.push(`  \u2026 (+${clearCount - preview.length} more)`);
+      if (clearCount > preview2.length) lines.push(`  \u2026 (+${clearCount - preview2.length} more)`);
       return lines;
     },
     execute: async () => {
@@ -46090,9 +46730,9 @@ function sanitizeProse(input, maxLen) {
   }
   return s;
 }
-function applyProse(data3, overlay, warn2 = () => {
+function applyProse(data4, overlay, warn2 = () => {
 }) {
-  const out = JSON.parse(JSON.stringify(data3));
+  const out = JSON.parse(JSON.stringify(data4));
   const rowProse = overlay.rowProse ?? {};
   const byId = new Map(
     out.rows.filter((r) => "id" in r).map((r) => [r.id, r])
@@ -46119,11 +46759,11 @@ function applyProse(data3, overlay, warn2 = () => {
 import { readFile as readFile6 } from "fs/promises";
 import { join as join12 } from "path";
 var MARKER = "<!--__DATA_BLOCK__-->";
-function renderReportHtml(data3, templateHtml) {
+function renderReportHtml(data4, templateHtml) {
   if (!templateHtml.includes(MARKER)) {
     throw new Error(`report template is missing the ${MARKER} marker`);
   }
-  const json = JSON.stringify(data3).replace(/</g, "\\u003c");
+  const json = JSON.stringify(data4).replace(/</g, "\\u003c");
   const block = `<script>window.__DATA__ = ${json};</script>`;
   return templateHtml.replace(MARKER, block);
 }
@@ -46148,25 +46788,25 @@ function validateReportType(raw) {
   throw new Error("--report-type must be 'P&L' or 'BS'");
 }
 async function runSessionCreate(cfg) {
-  const data3 = await createSession(cfg.client, cfg.baseUrl, { signal: cfg.signal });
-  cfg.out.write(`${data3.session_id ?? ""}
+  const data4 = await createSession(cfg.client, cfg.baseUrl, { signal: cfg.signal });
+  cfg.out.write(`${data4.session_id ?? ""}
 `);
 }
 async function runSessionGet(cfg) {
-  const data3 = await getSession(cfg.client, cfg.baseUrl, cfg.sessionId, {
+  const data4 = await getSession(cfg.client, cfg.baseUrl, cfg.sessionId, {
     signal: cfg.signal
   });
   if (cfg.asJson) {
-    writeJSONIndented(cfg.out, data3);
+    writeJSONIndented(cfg.out, data4);
     return;
   }
-  const config = data3.config ?? {};
+  const config = data4.config ?? {};
   const rows = [
-    ["session_id", String(data3.session_id ?? "-")],
-    ["created_at", String(data3.created_at ?? "-")],
-    ["reconcile_status", String(data3.reconcile_status ?? "-")],
-    ["investigation_status", String(data3.investigation_status ?? "-")],
-    ["reconcile_error", String(data3.reconcile_error ?? "-")],
+    ["session_id", String(data4.session_id ?? "-")],
+    ["created_at", String(data4.created_at ?? "-")],
+    ["reconcile_status", String(data4.reconcile_status ?? "-")],
+    ["investigation_status", String(data4.investigation_status ?? "-")],
+    ["reconcile_error", String(data4.reconcile_error ?? "-")],
     ["report_type", String(config.report_type ?? "-")],
     ["period", String(config.period ?? "-")]
   ];
@@ -46190,12 +46830,12 @@ async function runSessionDelete(cfg) {
     server: cfg.serverFlag,
     confirmCmd: `dr validate onboarding session delete ${cfg.sessionId} --server ${cfg.serverFlag}`,
     describe: async () => {
-      const data3 = await getSession(cfg.client, cfg.baseUrl, cfg.sessionId, {
+      const data4 = await getSession(cfg.client, cfg.baseUrl, cfg.sessionId, {
         signal: cfg.signal
       });
       return [
-        `created_at:       ${String(data3.created_at ?? "-")}`,
-        `reconcile_status: ${String(data3.reconcile_status ?? "-")}`
+        `created_at:       ${String(data4.created_at ?? "-")}`,
+        `reconcile_status: ${String(data4.reconcile_status ?? "-")}`
       ];
     },
     execute: async () => {
@@ -46237,14 +46877,14 @@ async function runUpload(cfg) {
   }
 }
 async function runReconcile(cfg) {
-  const data3 = await startReconcile(
+  const data4 = await startReconcile(
     cfg.client,
     cfg.baseUrl,
     cfg.sessionId,
     { report_type: cfg.reportType, period: cfg.period, csm_notes: cfg.csmNotes },
     { signal: cfg.signal }
   );
-  if (data3.status === "already_running") {
+  if (data4.status === "already_running") {
     cfg.out.write(`reconcile already running for session ${cfg.sessionId}
 `);
   } else {
@@ -46255,12 +46895,12 @@ async function runReconcile(cfg) {
 `);
 }
 async function runStatus(cfg) {
-  const data3 = await getSession(cfg.client, cfg.baseUrl, cfg.sessionId, {
+  const data4 = await getSession(cfg.client, cfg.baseUrl, cfg.sessionId, {
     signal: cfg.signal
   });
-  const recon = data3.reconcile_status ?? "pending";
-  const invest = data3.investigation_status ?? "pending";
-  const err = data3.reconcile_error ?? null;
+  const recon = data4.reconcile_status ?? "pending";
+  const invest = data4.investigation_status ?? "pending";
+  const err = data4.reconcile_error ?? null;
   const summary = summaryStatus(recon, invest);
   if (cfg.asJson) {
     writeJSONIndented(cfg.out, {
@@ -46274,13 +46914,13 @@ async function runStatus(cfg) {
   cfg.out.write(`reconcile: ${recon} | investigation: ${invest}
 `);
   if (err !== null && err !== "") {
-    const preview = err.length <= ERROR_PREVIEW_MAX ? err : `${err.slice(0, ERROR_PREVIEW_MAX)}...`;
-    cfg.out.write(`error: ${preview}
+    const preview2 = err.length <= ERROR_PREVIEW_MAX ? err : `${err.slice(0, ERROR_PREVIEW_MAX)}...`;
+    cfg.out.write(`error: ${preview2}
 `);
   }
 }
 async function runResult(cfg) {
-  const data3 = await getResult(
+  const data4 = await getResult(
     cfg.client,
     cfg.baseUrl,
     cfg.sessionId,
@@ -46288,21 +46928,21 @@ async function runResult(cfg) {
     { signal: cfg.signal }
   );
   if (cfg.asJson) {
-    writeJSONIndented(cfg.out, data3);
+    writeJSONIndented(cfg.out, data4);
     return;
   }
   if (cfg.reconcile) {
-    writeJSONIndented(cfg.out, data3);
+    writeJSONIndented(cfg.out, data4);
     return;
   }
-  const report = data3.report;
+  const report = data4.report;
   const markdown = report !== null && report !== void 0 && typeof report === "object" ? report.markdown : void 0;
   if (typeof markdown === "string" && markdown !== "") {
     cfg.out.write(`${markdown}
 `);
     return;
   }
-  writeJSONIndented(cfg.out, data3);
+  writeJSONIndented(cfg.out, data4);
 }
 async function runReport(cfg) {
   let result;
@@ -46375,24 +47015,24 @@ async function runReport(cfg) {
     tenant: cfg.org || null,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  let data3 = buildReportData(result, meta, balanceCheck);
+  let data4 = buildReportData(result, meta, balanceCheck);
   if (cfg.emitData) {
     if (cfg.outPath) {
-      await fs19.writeFile(cfg.outPath, JSON.stringify(data3, null, 2), "utf8");
+      await fs19.writeFile(cfg.outPath, JSON.stringify(data4, null, 2), "utf8");
       cfg.out.write(`wrote data block to ${cfg.outPath}
 `);
     } else {
-      writeJSONIndented(cfg.out, data3);
+      writeJSONIndented(cfg.out, data4);
     }
     return;
   }
   if (cfg.prosePath) {
     const overlay = JSON.parse(await fs19.readFile(cfg.prosePath, "utf8"));
-    data3 = applyProse(data3, overlay, (m) => process.stderr.write(`${m}
+    data4 = applyProse(data4, overlay, (m) => process.stderr.write(`${m}
 `));
   }
   const template = await readReportTemplate();
-  const html = renderReportHtml(data3, template);
+  const html = renderReportHtml(data4, template);
   const outPath = cfg.outPath || `./${cfg.sessionId}-report.html`;
   await fs19.writeFile(outPath, html, "utf8");
   cfg.out.write(`${outPath}
@@ -49757,9 +50397,9 @@ async function runMecMemberGrantBulk(cfg) {
     signal: cfg.signal
   });
   const wirePayload = { ...cfg.payload, role: role.id };
-  let preview = null;
+  let preview2 = null;
   try {
-    preview = await withMec(
+    preview2 = await withMec(
       () => grantUsersBulkCheck(cfg.client, wirePayload, { signal: cfg.signal })
     );
   } catch {
@@ -49778,8 +50418,8 @@ async function runMecMemberGrantBulk(cfg) {
         "",
         "WARNING: this cascades table permissions for linked LUT templates."
       ];
-      if (preview !== null) {
-        lines.push(`pre-check response: ${JSON.stringify(preview).slice(0, 200)}`);
+      if (preview2 !== null) {
+        lines.push(`pre-check response: ${JSON.stringify(preview2).slice(0, 200)}`);
       }
       return lines;
     },
@@ -52603,9 +53243,9 @@ async function runMemberGrantBulk(cfg) {
     signal: cfg.signal
   });
   const wirePayload = { ...cfg.payload, role: role.id };
-  let preview = null;
+  let preview2 = null;
   try {
-    preview = await withWorkflowV2(
+    preview2 = await withWorkflowV2(
       () => grantUsersBulkCheck(cfg.client, wirePayload, { signal: cfg.signal })
     );
   } catch {
@@ -52624,8 +53264,8 @@ async function runMemberGrantBulk(cfg) {
         "",
         "WARNING: this cascades table permissions for linked LUT templates."
       ];
-      if (preview !== null) {
-        lines.push(`pre-check response: ${JSON.stringify(preview).slice(0, 200)}`);
+      if (preview2 !== null) {
+        lines.push(`pre-check response: ${JSON.stringify(preview2).slice(0, 200)}`);
       }
       return lines;
     },
@@ -54225,12 +54865,12 @@ function parseCsvImportText(text2) {
       `--file: unexpected CSV header \u2014 expected "${EXPECTED_HEADER5.join(",")}", got "${header.slice(0, 3).join(",")}"`
     );
   }
-  const data3 = rows.slice(1).filter((r) => r.some((c) => c.trim() !== ""));
-  if (data3.length === 0) {
+  const data4 = rows.slice(1).filter((r) => r.some((c) => c.trim() !== ""));
+  if (data4.length === 0) {
     throw new Error("--file: CSV has no data rows (header only)");
   }
   const out = [];
-  data3.forEach((row, idx) => {
+  data4.forEach((row, idx) => {
     const lineNo = idx + 2;
     const detailedRule = (row[0] ?? "").trim();
     const category = (row[2] ?? "").trim();
@@ -56527,7 +57167,7 @@ async function create16(client, body, options) {
   }
   return out;
 }
-async function update10(client, id, body, options) {
+async function update9(client, id, body, options) {
   const out = await client.putJSON(`/api/templates/${id}/calcmodels`, body, options);
   if (out === null) {
     throw new Error(
@@ -56624,7 +57264,7 @@ async function runCalcmodelsUpdate(cfg) {
     );
   }
   validateCalcmodelBody(body);
-  const updated = await update10(cfg.client, cfg.id, body, {
+  const updated = await update9(cfg.client, cfg.id, body, {
     signal: cfg.signal
   });
   if (cfg.asJson) {
@@ -56671,7 +57311,7 @@ async function runCalcmodelsSetFlow(cfg) {
       `new update_flow:     ${flow}`
     ]),
     execute: async () => {
-      const updated = await update10(
+      const updated = await update9(
         cfg.client,
         cfg.id,
         { ...model, update_flow: flow },
@@ -56701,7 +57341,7 @@ async function runCalcmodelsRecalculate(cfg) {
       `type: ${model.type}`
     ]),
     execute: async () => {
-      await update10(cfg.client, cfg.id, model, { signal: cfg.signal });
+      await update9(cfg.client, cfg.id, model, { signal: cfg.signal });
       cfg.out.write(`recalculation queued \u2014 check status via dr calcmodels get ${cfg.id}
 `);
     }
@@ -56967,7 +57607,7 @@ async function create17(client, templateId, body, options) {
   }
   return out;
 }
-async function update11(client, templateId, calcId, body, options) {
+async function update10(client, templateId, calcId, body, options) {
   const out = await client.putJSON(
     `/api/templates/${templateId}/calc_vals/${calcId}`,
     body,
@@ -57094,7 +57734,7 @@ async function runCalcValsUpdate(cfg) {
         `--file body.id (${String(bodyId)}) does not match URL id (${cfg.id}) \u2014 refusing to overwrite calc value #${cfg.id} with another value's body. Either fix the body's id field or point --file at the right file.`
       );
     }
-    updated = await update11(cfg.client, cfg.templateId, cfg.id, body, {
+    updated = await update10(cfg.client, cfg.templateId, cfg.id, body, {
       signal: cfg.signal
     });
   } else {
@@ -57109,7 +57749,7 @@ async function runCalcValsUpdate(cfg) {
       // `--format ""` clears the mask (→ null); otherwise keep existing.
       format: cfg.format !== void 0 ? cfg.format === "" ? null : cfg.format : existing.format
     };
-    updated = await update11(cfg.client, cfg.templateId, cfg.id, body, {
+    updated = await update10(cfg.client, cfg.templateId, cfg.id, body, {
       signal: cfg.signal
     });
   }
@@ -58992,9 +59632,9 @@ async function runCpList(cfg) {
 }
 async function runCpGet(cfg) {
   const bucket = await getBucket(cfg.client, cfg.id, { signal: cfg.signal });
-  const data3 = cfg.noCpData ? void 0 : await getCpData(cfg.client, cfg.id, { signal: cfg.signal });
+  const data4 = cfg.noCpData ? void 0 : await getCpData(cfg.client, cfg.id, { signal: cfg.signal });
   if (cfg.asJson) {
-    writeJSONIndented(cfg.out, { bucket, cp_data: data3 ?? null });
+    writeJSONIndented(cfg.out, { bucket, cp_data: data4 ?? null });
     return;
   }
   cfg.out.write(`id:       ${bucket.id}
@@ -59007,11 +59647,11 @@ async function runCpGet(cfg) {
 `);
   cfg.out.write(`is_demo:  ${bucket.is_demo}
 `);
-  if (data3 !== void 0) {
-    cfg.out.write(`cp_data.owner_user_id:           ${data3.owner_user_id}
+  if (data4 !== void 0) {
+    cfg.out.write(`cp_data.owner_user_id:           ${data4.owner_user_id}
 `);
     cfg.out.write(
-      `cp_data.level_dimension_tags:    ${JSON.stringify(data3.level_dimension_tags)}
+      `cp_data.level_dimension_tags:    ${JSON.stringify(data4.level_dimension_tags)}
 `
     );
   }
@@ -60098,7 +60738,7 @@ var EXTRACT_POLL_TIMEOUT_MS = 10 * 60 * 1e3;
 function isTerminalAiStatus(status2) {
   return status2 === "PROCESSED" || status2 === "FAILED";
 }
-async function defaultSleep9(ms, signal) {
+async function defaultSleep8(ms, signal) {
   if (signal?.aborted === true) return;
   await new Promise((resolve3) => {
     const timer = setTimeout(resolve3, ms);
@@ -60115,7 +60755,7 @@ async function defaultSleep9(ms, signal) {
 async function pollExtractionStatus(client, contractFileIds, options = {}) {
   const interval = options.pollIntervalMs ?? EXTRACT_POLL_INTERVAL_MS;
   const timeout = options.timeoutMs ?? EXTRACT_POLL_TIMEOUT_MS;
-  const sleep4 = options.sleep ?? defaultSleep9;
+  const sleep3 = options.sleep ?? defaultSleep8;
   const now = options.now ?? Date.now;
   const resolved = /* @__PURE__ */ new Map();
   if (contractFileIds.length === 0) return { resolved, pending: [] };
@@ -60165,7 +60805,7 @@ async function pollExtractionStatus(client, contractFileIds, options = {}) {
       options.onTick?.(resolved.size, contractFileIds.length);
       if (resolved.size >= contractFileIds.length) break;
       if (now() > deadline || inner.signal.aborted) break;
-      await sleep4(interval, inner.signal);
+      await sleep3(interval, inner.signal);
     }
   } finally {
     clearTimeout(deadlineTimer);
@@ -62741,16 +63381,16 @@ function describeBulkCreate(draft, contracts, batchCount, serverKey) {
     }
     if (d.category !== void 0) out.push(`default category: ${d.category}`);
   }
-  const preview = contracts.slice(0, DESCRIBE_PREVIEW_ROWS3);
-  if (preview.length > 0) {
+  const preview2 = contracts.slice(0, DESCRIBE_PREVIEW_ROWS3);
+  if (preview2.length > 0) {
     out.push("preview:");
-    for (let i = 0; i < preview.length; i++) {
-      const c = preview[i];
+    for (let i = 0; i < preview2.length; i++) {
+      const c = preview2[i];
       const vendor = c.vendor_name !== void 0 && c.vendor_name !== null && c.vendor_name !== "" ? c.vendor_name : c.vendor_id !== void 0 && c.vendor_id !== null ? c.vendor_id : "?";
       out.push(`  [${i}] ${vendor} \u2014 ${c.value} ${c.currency}`);
     }
-    if (contracts.length > preview.length) {
-      out.push(`  \u2026 (${contracts.length - preview.length} more)`);
+    if (contracts.length > preview2.length) {
+      out.push(`  \u2026 (${contracts.length - preview2.length} more)`);
     }
   }
   return out;
@@ -63022,7 +63662,7 @@ function registerSpendControlCommand(root) {
   );
   addServerFlag(bulkCreate);
   addAccountFlag(bulkCreate);
-  const update12 = contracts.command("update").description("Partially update a contract by id (PATCH /contracts/{id})").argument("<contract_id>", "Contract UUID").requiredOption("--from <path>", "Path to JSON body matching ContractPartialUpdateSchema").option("--json", "Output raw JSON of the updated contract", false).action(async (contractId, opts) => {
+  const update11 = contracts.command("update").description("Partially update a contract by id (PATCH /contracts/{id})").argument("<contract_id>", "Contract UUID").requiredOption("--from <path>", "Path to JSON body matching ContractPartialUpdateSchema").option("--json", "Output raw JSON of the updated contract", false).action(async (contractId, opts) => {
     const setup = await setupCall(opts.server, opts.account);
     try {
       await runContractUpdate({
@@ -63037,8 +63677,8 @@ function registerSpendControlCommand(root) {
       setup.cleanup();
     }
   });
-  addServerFlag(update12);
-  addAccountFlag(update12);
+  addServerFlag(update11);
+  addAccountFlag(update11);
   for (const spec of [
     {
       name: "archive",