@datarails-ai/dr-cli 1.6.104 → 1.6.106

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.104",
+  version: "1.6.106",
   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.1",
+    "@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-07T12:03:26.799Z";
+var BUILD_TIME = "2026-10-07T14:49:41.993Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -1165,13 +1165,8 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
   inFlightExchanges.set(key, entry);
   return joinExchange(entry, opts.signal);
 }
-async function ensureJwt(store, serverKey, email, opts) {
-  const stored = await store.getSession(serverKey, email);
-  if (stored === void 0) {
-    throw new NotLoggedInError(`not logged in: ${serverKey}:${email}`);
-  }
-  const keyed = usesApiKey(stored);
-  const unsaved = keyed ? unsavedExchanges.get(`${serverKey}:${email}`) : void 0;
+async function exchangeKeyedSession(store, serverKey, email, stored, opts) {
+  const unsaved = unsavedExchanges.get(`${serverKey}:${email}`);
   const session = unsaved !== void 0 && unsaved.apiKey === stored.apiKey ? {
     ...stored,
     jwtAccess: unsaved.jwtAccess,
@@ -1184,16 +1179,40 @@ async function ensureJwt(store, serverKey, email, opts) {
     // The store still holds whatever the failed save meant to remove.
     jwtRefresh: void 0
   } : stored;
-  if (!opts.force && (!keyed || mintedByStoredApiKey(session)) && session.jwtAccess !== void 0 && session.jwtAccess !== "" && !jwtExpiringSoon(
-    session,
-    keyed ? apiKeyStaleBuffer(session, `${serverKey}:${email}`, opts.buffer) : opts.buffer
-  )) {
+  if (!opts.force && mintedByStoredApiKey(session) && session.jwtAccess !== void 0 && session.jwtAccess !== "" && !jwtExpiringSoon(session, apiKeyStaleBuffer(session, `${serverKey}:${email}`, opts.buffer))) {
     return session;
   }
   const host = opts.host ?? resolve(serverKey).host;
-  if (keyed) {
-    return exchangeForSession(store, serverKey, email, session, host, opts);
+  return exchangeForSession(store, serverKey, email, session, host, opts);
+}
+async function ensureApiKeyJwt(store, serverKey, email, options) {
+  const stored = options?.session ?? await store.getSession(serverKey, email);
+  if (stored === void 0) {
+    throw new NotLoggedInError(`not logged in: ${serverKey}:${email}`);
+  }
+  if (!usesApiKey(stored)) {
+    throw new Error(`${serverKey}:${email} is not an api-key identity`);
+  }
+  return exchangeKeyedSession(store, serverKey, email, stored, {
+    buffer: options?.buffer ?? 0,
+    force: false,
+    signal: options?.signal,
+    host: options?.host
+  });
+}
+async function ensureJwt(store, serverKey, email, opts) {
+  const stored = await store.getSession(serverKey, email);
+  if (stored === void 0) {
+    throw new NotLoggedInError(`not logged in: ${serverKey}:${email}`);
   }
+  if (usesApiKey(stored)) {
+    return exchangeKeyedSession(store, serverKey, email, stored, opts);
+  }
+  const session = stored;
+  if (!opts.force && session.jwtAccess !== void 0 && session.jwtAccess !== "" && !jwtExpiringSoon(session, opts.buffer)) {
+    return session;
+  }
+  const host = opts.host ?? resolve(serverKey).host;
   if (session.impersonatorEmail !== void 0 && session.impersonatorEmail !== "") {
     return recoverImpersonatedJwt(store, serverKey, email, session, host, opts);
   }
@@ -2101,7 +2120,8 @@ var AuthorizedClient = class _AuthorizedClient {
    * How this identity gets a usable JWT again. `dr login` is refused over an
    * api-key credential, and it re-authenticates the operator rather than the
    * impersonated user, so naming it for either sends the reader at a command
-   * that cannot help — the same loop `runWhoami`'s three-way split breaks.
+   * that cannot help — the same loop `runWhoami` avoids by never naming
+   * `dr login` for either.
    *
    * `cause` splits the keyed answer, which is the only one that differs: a
    * token that never arrived is not a token whose `organization_id` is wrong,
@@ -4807,7 +4827,7 @@ function declaredWithValueBelow(flag, cmd) {
 // src/commands/whoami.ts
 function registerWhoamiCommand(root) {
   const cmd = root.command("whoami").description(
-    "whoami decodes the locally-stored JWT for a server and prints the identity claims (user_id, username, email, expiration). Purely offline \u2014 no network."
+    "whoami decodes the locally-stored JWT for a server and prints the identity claims (user_id, username, email, expiration). Offline, except that an api-key identity holding no token its current key minted is exchanged once to obtain one."
   ).summary("Show the identity encoded in the stored JWT for a server").option("--json", "Output the full claims map as JSON", false).option("--verbose", "Print every claim in a table, sorted alphabetically", false).action(
     async (opts) => {
       const fileStore = await resolveFileStore(opts.server);
@@ -4845,19 +4865,34 @@ async function runWhoami(cfg) {
   }
   emitApiKeyExpiryWarning(session, `${cfg.serverKey}:${email}`);
   const foreignJwt = usesApiKey(session) && session.jwtAccess !== void 0 && session.jwtAccess !== "" && !mintedByStoredApiKey(session);
+  let active = session;
   if (session.jwtAccess === void 0 || session.jwtAccess === "" || foreignJwt) {
-    const missing = foreignJwt ? `the JWT stored for ${cfg.serverKey}:${email} was not minted by its API key` : `no JWT stored for ${cfg.serverKey}:${email}`;
-    throw new Error(
-      usesApiKey(session) ? `${missing}; run any authenticated command to exchange the API key` : isImpersonatedSession(session) ? `${missing}; re-run dr login-as` : `${missing}; run dr login --server ${cfg.serverKey} to refresh`
-    );
+    if (usesApiKey(session)) {
+      try {
+        active = await ensureApiKeyJwt(cfg.store, cfg.serverKey, email, { session });
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`cannot show identity for ${cfg.serverKey}:${email}: ${reason}`, {
+          cause: err
+        });
+      }
+    } else {
+      const missing = `no JWT stored for ${cfg.serverKey}:${email}`;
+      throw new Error(
+        isImpersonatedSession(session) ? `${missing}; re-run dr login-as` : `${missing}; run dr login --server ${cfg.serverKey} to refresh`
+      );
+    }
+  }
+  if (active.jwtAccess === void 0 || active.jwtAccess === "") {
+    throw new Error(`no JWT stored for ${cfg.serverKey}:${email}`);
   }
   try {
-    setTelemetryTarget(cfg.serverKey, deriveIdentity(session));
+    setTelemetryTarget(cfg.serverKey, deriveIdentity(active));
   } catch {
   }
   let claims;
   try {
-    claims = decodeJwtClaims(session.jwtAccess);
+    claims = decodeJwtClaims(active.jwtAccess);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(`decode JWT for ${cfg.serverKey}: ${msg}`);
@@ -4867,7 +4902,7 @@ async function runWhoami(cfg) {
     host = resolve(cfg.serverKey).host;
   } catch {
   }
-  const impersonatorEmail = session.impersonatorEmail !== void 0 && session.impersonatorEmail !== "" ? session.impersonatorEmail : void 0;
+  const impersonatorEmail = active.impersonatorEmail !== void 0 && active.impersonatorEmail !== "" ? active.impersonatorEmail : void 0;
   if (cfg.asJson) {
     writeWhoamiJSON(cfg.out, cfg.serverKey, host, claims, impersonatorEmail);
     return;
@@ -5360,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();
@@ -5495,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;
@@ -5504,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;
@@ -5657,6 +5692,10 @@ async function runApiKeyLogin(cfg) {
     apiKey: cfg.apiKey,
     jwtAccess: tok.access,
     jwtExpiresAt: tok.expiresAt,
+    // Records which key minted this token, as every exchange does. Without it
+    // `mintedByStoredApiKey` reads the token as unknown provenance, so `whoami`
+    // and the next command would exchange again instead of using it.
+    jwtApiKeyFingerprint: apiKeyFingerprint(cfg.apiKey),
     savedAt: /* @__PURE__ */ new Date(),
     cookieless: true
   };
@@ -12672,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;
       }
@@ -12723,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) {
@@ -15442,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 sleep4 = 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 sleep4(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 {
@@ -15485,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,
@@ -15495,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 };
@@ -15511,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) => ({
@@ -15519,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(
@@ -15538,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 sleep4 = 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 sleep4(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"];
@@ -15588,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;
@@ -15615,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
     });
@@ -15630,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,
@@ -15637,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 }
     );
@@ -15784,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 = [];
@@ -15859,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) => {
@@ -15893,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");
@@ -15905,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
@@ -15918,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;
@@ -15932,6 +16630,7 @@ function registerFunctionsCommand(root) {
           field,
           aggOriginal: opts.agg,
           template,
+          dateField: opts.dateField,
           asJson: opts.json === true,
           signal: setup.signal,
           out: process.stdout
@@ -15977,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",
@@ -16025,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,
@@ -16087,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,
     {
@@ -17420,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)}`
@@ -17448,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 : "";
@@ -18230,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)
 `);
@@ -18246,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(`
@@ -20337,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)
         ]
@@ -20445,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
@@ -21711,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) {
@@ -25264,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, {
@@ -25367,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,
@@ -25814,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
@@ -29967,16 +30696,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.`;
   }
@@ -34763,7 +35492,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;
@@ -34781,7 +35510,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 sleep4 = cfg.sleep ?? defaultSleep6;
   const now = cfg.now ?? Date.now;
   const start = now();
   const deadline = start + cfg.timeoutSec * 1e3;
@@ -38542,7 +39271,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;
@@ -38562,7 +39291,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 sleep4 = cfg.sleep ?? defaultSleep7;
   const resp = await resync(cfg.client, cfg.id, {
     signal: cfg.signal
   });
@@ -44235,7 +44964,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;
@@ -44247,8 +44976,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;
@@ -44275,10 +45004,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;
     },
@@ -44704,16 +45433,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})`
             );
           }
@@ -44730,8 +45459,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 () => {
@@ -44829,13 +45558,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`
             );
           }
@@ -44847,9 +45576,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 () => {
@@ -46051,9 +46780,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])
@@ -46080,11 +46809,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);
 }
@@ -46109,25 +46838,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 ?? "-")]
   ];
@@ -46151,12 +46880,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 () => {
@@ -46198,14 +46927,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 {
@@ -46216,12 +46945,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, {
@@ -46235,13 +46964,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,
@@ -46249,21 +46978,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;
@@ -46336,24 +47065,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}
@@ -49718,9 +50447,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 {
@@ -49739,8 +50468,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;
     },
@@ -52564,9 +53293,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 {
@@ -52585,8 +53314,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;
     },
@@ -54186,12 +54915,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();
@@ -58953,9 +59682,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}
@@ -58968,11 +59697,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)}
 `
     );
   }
@@ -60059,7 +60788,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);
@@ -60076,7 +60805,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 sleep4 = options.sleep ?? defaultSleep8;
   const now = options.now ?? Date.now;
   const resolved = /* @__PURE__ */ new Map();
   if (contractFileIds.length === 0) return { resolved, pending: [] };
@@ -62702,16 +63431,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;