gangtise-openapi-cli 0.30.1 → 0.32.0

package/dist/src/core/indicatorMatrix.js

@@ -1,4 +1,5 @@
-import { ApiError } from "./errors.js";
+import { screenerExpressionFields, screenerExpressionIsEvaluable } from "./args.js";
+import { ApiError, attachEnvelopeTraceId, ENVELOPE_TRACE_ID } from "./errors.js";
 // The EDE endpoints double-wrap on success: the shared client strips the outer
 // envelope but leaves an inner { code, status, data } around the real payload.
 // Peel that inner envelope so the list (search) / matrix (cross-section,
@@ -22,8 +23,12 @@ export function unwrapIndicatorData(raw) {
                 // 999999 / 130001 that most need reporting — reach the user trace-less.
                 throw new ApiError(typeof record.msg === "string" && record.msg ? record.msg : "Indicator API request failed", code, undefined, record);
             }
+            // Carry the envelope's traceId onto the inner payload. `unwrapEnvelope`
+            // attached it to THIS object, but everything downstream (the flatteners'
+            // shape guards) only ever sees `record.data` — without this hand-off those
+            // failures, exactly the ones support needs to trace, arrive trace-less.
             if (ok && "data" in record)
-                return record.data;
+                return attachEnvelopeTraceId(record.data, record[ENVELOPE_TRACE_ID] ?? record.traceId);
         }
     }
     return raw;
@@ -31,10 +36,33 @@ export function unwrapIndicatorData(raw) {
 function asStringArray(value) {
     return Array.isArray(value) ? value.map((item) => String(item)) : undefined;
 }
-function asIndicatorMetaList(value) {
+/** An IDENTITY axis — the security codes a row belongs to, the dates a column
+ * belongs to. `String(item)` would turn a `null` into the literal `"null"` and
+ * render it as a perfectly plausible label (probed 2026-08-02: `dates: [null]`
+ * produced `date: "null"`, `securityCodeList: [null]` produced
+ * `security: "null"`), so a fabricated identity would reach the output at exit
+ * 0. Nothing here may be coerced: every entry must already be a non-empty string. */
+function asIdentityArray(data, value, key) {
     if (!Array.isArray(value))
         return undefined;
-    return value.map((item) => (item && typeof item === "object" && !Array.isArray(item) ? item : {}));
+    const bad = value.findIndex((item) => typeof item !== "string" || item.trim() === "");
+    if (bad !== -1) {
+        throw new ApiError(`Indicator matrix shape mismatch: ${key}[${bad}] is not a usable identifier (${JSON.stringify(value[bad])}) — rows would be labelled with a value that identifies nothing`, undefined, undefined, data);
+    }
+    return value;
+}
+/** Indicator metadata is an identity axis too: `--key-by code` addresses columns
+ * by `code`, so an entry without one cannot be mapped back to what was asked
+ * for. A non-object entry used to collapse into `{}` and surface as `col0`. */
+function asIndicatorMetaList(data, value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const bad = value.findIndex((item) => !item || typeof item !== "object" || Array.isArray(item)
+        || typeof item.code !== "string" || String(item.code).trim() === "");
+    if (bad !== -1) {
+        throw new ApiError(`Indicator matrix shape mismatch: indicatorList[${bad}] carries no usable \`code\` (${JSON.stringify(value[bad])}) — the column could not be mapped back to a requested indicator`, undefined, undefined, data);
+    }
+    return value;
 }
 function optionalString(value) {
     return value === undefined || value === null ? undefined : String(value);
@@ -87,16 +115,116 @@ function indicatorHeaders(indicators, keyBy, reserved) {
     return buildHeaders(bases.map((base, i) => (base !== undefined && repeated.has(base) ? `${base} (${fields[i] ?? i})` : base)), fields, reserved);
 }
 const CROSS_SECTION_COLUMNS = ["security", "name"];
-/** What the caller asked for that the response does not contain. The server
- * does NOT pad missing data with `null`: an indicator that is empty for every
- * security disappears from `indicatorList`, and a security that is empty for
- * every indicator disappears from `securityCodeList` (probed 2026-08-02 — three
- * indicators over 09992.HK came back with one, two securities over
- * `qte_mkt_cptl` came back with one). Only partial gaps become `null`.
+/** A response carrying neither securities nor indicators: the query as a whole
+ * resolved to nothing. This is NOT a dropped axis, so it must not be reported as
+ * partial — calling every requested code "omitted" would be false metadata, the
+ * diff against the request is total by construction.
+ *
+ * What it MEANS changed on 2026-08-07: a genuine no-data answer (non-trading
+ * date, uncovered market, future date) now comes back as a null cell with its
+ * row and column intact, so an all-empty matrix no longer means "no data". It
+ * now means nothing in the request RESOLVED — every security code or every
+ * indicator code was unrecognised — or a parameter name is wrong. The caller's
+ * stderr note says exactly that.
+ *
+ * The check covers every STRUCTURAL array, not just the two axis lists, because
+ * accepting anything looser would let a malformed payload — `values: null`, a
+ * missing `values`, or dates with no matrix — pass as "legitimately empty" and
+ * exit 0, which is precisely the protocol regression this release's shape guards
+ * exist to catch. Required empty: `securityCodeList`, `indicatorList`, `values`;
+ * plus `dates` when present. Probed 2026-08-02 (back when this shape still meant
+ * "no data"): a time-series all-empty answer is five empty arrays, a
+ * cross-section one is four (it carries no `dates` key at all), hence "absent or
+ * empty" rather than a flat count. The STRUCTURE is unchanged; only its meaning
+ * moved — since 2026-08-07 it signals an unresolved axis, not missing data.
+ *
+ * `securityNameList` is deliberately NOT checked: it holds display labels, not
+ * structure, so a `null` there cannot misalign anything — and rejecting it would
+ * re-introduce the false-partial this function exists to prevent. */
+export function isEmptyMatrix(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const d = data;
+    if (asStringArray(d.securityCodeList)?.length !== 0)
+        return false;
+    if (!Array.isArray(d.indicatorList) || d.indicatorList.length !== 0)
+        return false;
+    if (!Array.isArray(d.values) || d.values.length !== 0)
+        return false;
+    // `dates` is time-series only; when present it must be empty too.
+    return d.dates === undefined || (Array.isArray(d.dates) && d.dates.length === 0);
+}
+/** Validate the variable bindings a screener answered with, returning the bound
+ * variables that are merely missing (see below).
+ *
+ * The screener answers with the variable each column was requested under, and
+ * that binding is the ONLY thing tying a column back to the filter it came from
+ * — nothing else in the payload can catch it going wrong. A swapped or unknown
+ * `field` renders as a perfectly ordinary result (probed 2026-08-02: a response
+ * labelling a requested `F1` as `F9` printed a normal table at exit 0), which
+ * would make every screening decision downstream unfounded.
  *
- * That is the dangerous shape: `--key-by code` batch mapping finds no key at
- * all rather than a null, and a cross-market pull quietly returns fewer rows
- * than requested with exit code 0.
+ * Every returned entry must therefore name a REQUESTED variable and carry that
+ * variable's code, and no variable may appear twice. A wholly empty result binds
+ * nothing and is left alone. */
+export function checkScreenerBindings(data, requested, expression) {
+    if (!data || typeof data !== "object")
+        return [];
+    const d = data;
+    // A result with no securities matched nothing and binds nothing — the
+    // canonical empty answer, left alone.
+    if (!Array.isArray(d.securityCodeList) || d.securityCodeList.length === 0)
+        return [];
+    const indicators = Array.isArray(d.indicatorList) ? d.indicatorList : [];
+    const wanted = new Map(requested.map((binding) => [binding.field, binding.indicatorCode]));
+    const seen = new Set();
+    for (const [i, meta] of indicators.entries()) {
+        const field = optionalString(meta?.field);
+        const code = optionalString(meta?.code);
+        if (!field || !wanted.has(field)) {
+            throw new ApiError(`Screener binding mismatch: indicatorList[${i}] is bound to ${field ? `"${field}"` : "no variable"}, which --indicator never requested — the column cannot be traced to a filter`, undefined, undefined, data);
+        }
+        if (wanted.get(field) !== code) {
+            throw new ApiError(`Screener binding mismatch: variable ${field} came back as "${code}" but was requested as "${wanted.get(field)}" — the filter and the column disagree`, undefined, undefined, data);
+        }
+        if (seen.has(field)) {
+            throw new ApiError(`Screener binding mismatch: variable ${field} appears twice in the response — the mapping back to a filter is ambiguous`, undefined, undefined, data);
+        }
+        seen.add(field);
+    }
+    // Securities came back, so the filter ran. A column vanishing is never "it got
+    // filtered out" — filtering removes securities (rows), never indicators
+    // (columns). Since 2026-08-07 a covered-but-empty indicator keeps a null
+    // column, so an absent column means the server did not resolve that indicator
+    // code at all. What that implies depends on how the expression combines terms:
+    //
+    // The answer follows the expression's BOOLEAN STRUCTURE, not the mere presence
+    // of a `||` — see screenerExpressionIsEvaluable. If no branch survives the
+    // missing columns, the rows cannot be shown to satisfy anything and the result
+    // is fatal; if some branch still could have matched, the absence proves nothing
+    // wrong and it degrades to partial.
+    const missing = [...wanted.keys()].filter((field) => !seen.has(field));
+    if (!screenerExpressionIsEvaluable(expression, seen)) {
+        const absent = [...new Set(screenerExpressionFields(expression))].filter((field) => !seen.has(field));
+        throw new ApiError(`Screener binding mismatch: the expression cannot be evaluated from what came back — ${absent.join(", ")} ${absent.length > 1 ? "have" : "has"} no column, and no branch of the expression survives without ${absent.length > 1 ? "them" : "it"}, so the rows cannot be shown to satisfy it`, undefined, undefined, data);
+    }
+    // Whatever survives is an output column that went missing: information lost,
+    // correctness intact.
+    return missing;
+}
+/** What the caller asked for that the response does not contain.
+ *
+ * The server used to drop any axis it had no DATA for, which made this a
+ * coverage check. Re-probed 2026-08-08: a coverage gap is now padded with `null`
+ * and keeps its row and column, down to the 1×1 case (`finc_pb_mrq` × 09992.HK,
+ * `mgn_bal` × 00700.HK — null, present, alone in the request). What still
+ * disappears is a code the server cannot RESOLVE: an unknown indicator code, or
+ * a security code with the wrong market suffix (`AAPL.US` vanishes, `AAPL.O`
+ * returns).
+ *
+ * So the remaining shape is the dangerous one: a misspelled code is invisible
+ * otherwise — `--key-by code` batch mapping finds no key at all rather than a
+ * null, and the pull quietly returns fewer rows than requested with exit code 0.
  *
  * Universe entries with no `.` are skipped — those are sector IDs, which the
  * server expands into constituents, so their absence from the response is
@@ -107,20 +235,108 @@ export function droppedFromMatrix(data, requestedSecurities, requestedIndicators
         return empty;
     const d = data;
     const returnedSecurities = new Set(asStringArray(d.securityCodeList) ?? []);
-    const returnedIndicators = new Set((asIndicatorMetaList(d.indicatorList) ?? []).map((meta) => optionalString(meta.code)));
+    const returnedIndicators = new Set((Array.isArray(d.indicatorList) ? d.indicatorList : []).map((meta) => optionalString(meta?.code)));
     return {
         securities: requestedSecurities.filter((code) => code.includes(".") && !returnedSecurities.has(code)),
         indicators: requestedIndicators.filter((code) => !returnedIndicators.has(code)),
     };
 }
-/** The matrix and its axis labels must agree, or every cell is off by a row.
- * The 2026-08-01 revision transposed cross-section without a version marker, so
- * a future re-transpose has to fail loudly instead of silently relabelling
- * columns. Rows are compared, not cells: the server legitimately returns short
- * rows when a trailing indicator has no data anywhere. */
-function assertRowCount(rows, expected, axis) {
-    if (rows.length !== expected) {
-        throw new ApiError(`Indicator matrix shape mismatch: got ${rows.length} value rows for ${expected} ${axis} — the response layout may have changed`, undefined);
+/** True only when the payload carries NONE of the EDE matrix keys — a foreign
+ * shape. Nothing legitimately reaches the flatteners in that state — `indicator
+ * search` prints its unwrapped list directly and `raw call` bypasses them — so
+ * this is a protocol failure, not a payload to hand back: returning it would
+ * print the raw envelope and exit 0, indistinguishable from success. */
+function assertMatrixPayload(data, d) {
+    const bare = d.securityCodeList === undefined && d.securityNameList === undefined
+        && d.indicatorList === undefined && d.dates === undefined && d.values === undefined;
+    if (bare) {
+        throw new ApiError("Indicator matrix shape mismatch: the response carries none of the matrix fields — the response layout may have changed", undefined, undefined, data);
+    }
+}
+function assertAxis(data, axis, key) {
+    if (axis === undefined) {
+        throw new ApiError(`Indicator matrix shape mismatch: the response is missing \`${key}\` or it is not an array — the response layout may have changed`, undefined, undefined, data);
+    }
+}
+/** Resolve the display names for a security axis, degrading instead of failing.
+ *
+ * Names are consumed POSITIONALLY, so a list that does not line up cannot be
+ * trusted at all: `["泡泡玛特"]` against `["600519.SH","09992.HK"]` labels 茅台's
+ * series 泡泡玛特, and a `[null]` element used to render a column literally
+ * headed `"null"` (both probed 2026-08-02). Neither may reach the output.
+ *
+ * But a name is a LABEL, not structure — `securityCodeList` already carries
+ * identity, and every header falls back to the code. So an anomaly here drops
+ * the names and keeps the values, rather than killing an EDE command whose
+ * numbers are all correct. That is a deliberate asymmetry with the other guards
+ * in this module: they protect against MISATTRIBUTED VALUES and must be fatal;
+ * this one protects a caption. */
+function resolveSecurityNames(names, codes) {
+    if (names === undefined || names === null)
+        return undefined;
+    if (!Array.isArray(names) || names.length !== codes.length) {
+        process.stderr.write(`[gangtise] warning: securityNameList carries ${Array.isArray(names) ? `${names.length} entries` : "no array"} for ${codes.length} securities — names are positional, so all of them were dropped; columns fall back to the security code.\n`);
+        return undefined;
+    }
+    let warned = false;
+    return names.map((name, i) => {
+        if (typeof name === "string" && name.trim() !== "")
+            return name;
+        // A blank or null name is a plausible gap for one security — fall back
+        // quietly. A non-string (an object, a number) means the field changed type,
+        // which is worth saying once.
+        if (typeof name !== "string" && name !== null && name !== undefined && !warned) {
+            warned = true;
+            process.stderr.write(`[gangtise] warning: securityNameList holds non-string entries; those columns fall back to the security code.\n`);
+        }
+        return codes[i];
+    });
+}
+/** The matrix endpoints cannot legitimately answer with a non-object payload:
+ * `indicator search` never reaches the flatteners (it prints the unwrapped list
+ * directly) and `raw call` bypasses them entirely, so there is no caller for
+ * which `null`, an array, or a foreign object is a valid cross-section /
+ * time-series / screener body. Checked here, BEFORE the envelope is discarded,
+ * because a `data: null` cannot carry the non-enumerable traceId — passing the
+ * envelope as details is the only way such a failure stays traceable. */
+export function requireIndicatorMatrix(raw) {
+    const data = unwrapIndicatorData(raw);
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, raw);
+    }
+    return data;
+}
+function assertValuesPresent(data, values) {
+    if (!Array.isArray(values)) {
+        throw new ApiError(`Indicator matrix shape mismatch: the response carries axis lists but no \`values\` array — the response layout may have changed`, undefined, undefined, data);
+    }
+}
+/** The matrix and its axis labels must agree on BOTH dimensions, or cells are
+ * dropped or misread. The 2026-08-01 revision transposed cross-section without a
+ * version marker, so a re-transpose has to fail loudly rather than silently
+ * relabel columns — with the caveat that this only catches a NON-SQUARE change.
+ * A 2×2 or 1×1 matrix keeps its dimensions when transposed and would still be
+ * read with the axes swapped; nothing in the payload distinguishes the two.
+ *
+ * Row length is checked exactly, not leniently: the server pads a row with
+ * `null` rather than truncating it — probed 2026-08-02 across A/HK/US, where a
+ * US security missing 3 of 4 indicators still came back with a full-length row,
+ * and a cross-market time series padded every security to the union of trading
+ * days (each market's own holidays land as `null`). A short or long row is
+ * therefore a structural change, not missing data.
+ *
+ * `data` rides along as ApiError details so the failure keeps the response's
+ * traceId — a shape mismatch is precisely the kind of thing support needs to
+ * trace, and without it the error reaches the user trace-less. */
+function assertMatrixShape(data, values, rows, rowAxis, cols, colAxis) {
+    if (values.length !== rows) {
+        throw new ApiError(`Indicator matrix shape mismatch: got ${values.length} value rows for ${rows} ${rowAxis} — the response layout may have changed`, undefined, undefined, data);
+    }
+    for (const [i, row] of values.entries()) {
+        const width = Array.isArray(row) ? row.length : -1;
+        if (width !== cols) {
+            throw new ApiError(`Indicator matrix shape mismatch: value row ${i} has ${width < 0 ? "no array of" : String(width)} cells for ${cols} ${colAxis} — the response layout may have changed`, undefined, undefined, data);
+        }
     }
 }
 // Cross-section (and the screener, whose payload is the same shape plus a
@@ -129,18 +345,25 @@ function assertRowCount(rows, expected, axis) {
 // values[i][j]. There is no row-level date any more — the query date now lives
 // in each indicator's own parameters and may legitimately differ per column.
 export function flattenCrossSection(data, keyBy = "name") {
-    if (!data || typeof data !== "object")
-        return data;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, data);
+    }
     const d = data;
-    const securityCode = asStringArray(d.securityCodeList);
-    const indicators = asIndicatorMetaList(d.indicatorList);
-    if (!Array.isArray(d.values) || !securityCode || !indicators)
-        return data;
-    assertRowCount(d.values, securityCode.length, "securities");
-    const securityName = asStringArray(d.securityNameList);
+    assertMatrixPayload(data, d);
+    // Past this point the payload claims to be a matrix, so every axis it needs
+    // must actually be there. A `null` or absent axis is a broken response.
+    const securityCode = asIdentityArray(data, d.securityCodeList, "securityCodeList");
+    const indicators = asIndicatorMetaList(data, d.indicatorList);
+    assertAxis(data, securityCode, "securityCodeList");
+    assertAxis(data, indicators, "indicatorList");
+    assertValuesPresent(data, d.values);
+    assertMatrixShape(data, d.values, securityCode.length, "securities", indicators.length, "indicators");
+    const securityName = resolveSecurityNames(d.securityNameList, securityCode);
     const headers = indicatorHeaders(indicators, keyBy, CROSS_SECTION_COLUMNS);
     const list = securityCode.map((code, i) => {
-        const row = { security: code, name: securityName?.[i] };
+        // Only create `name` when there IS one: an always-present `name: undefined`
+        // is invisible in JSON but renders as a real empty column in CSV/table.
+        const row = securityName ? { security: code, name: securityName[i] } : { security: code };
         const cells = rowOf(d.values, i);
         for (let j = 0; j < headers.length; j++) {
             row[headers[j]] = cells?.[j];
@@ -153,24 +376,65 @@ export function flattenCrossSection(data, keyBy = "name") {
 // case) or the securities (single-indicator case) — exactly one dimension
 // varies, per the API contract. `values` stays a 2D [series][date] matrix.
 //
-// `requestedSecurities` decides the axis. Deriving it from the RESPONSE is
-// wrong: the server drops securities that have no data at all, so a
-// single-indicator × two-security query where one security is uncovered comes
-// back with one security and silently relabels the column as the indicator —
-// the caller then cannot tell whose series they are holding (probed 2026-08-02:
-// `finc_pe_ttm` over 600519.SH + 09992.HK renders a bare 市盈率(TTM) column).
-export function flattenTimeSeries(data, keyBy = "name", requestedSecurities) {
-    if (!data || typeof data !== "object")
-        return data;
+// Axis rule, in priority order:
+//  1. More than one indicator came back → multi-indicator × single-security.
+//  2. More than one security came back → single-indicator × multi-security.
+//     This is what a sector ID produces: the request carries ONE universe entry
+//     and the server expands it into N constituents, so the request count says
+//     nothing about the axis.
+//  3. Both are 1 → genuinely ambiguous, so fall back to what was REQUESTED:
+//     - a universe holding a sector ID always takes the security axis. The
+//       sector may expand to one constituent, or the rest may have been dropped
+//       for lack of data; either way the caller asked "which securities", and an
+//       indicator-named column would erase whose series this is.
+//     - otherwise the entry count decides. The server drops securities with no
+//       data at all, so a two-security request that comes back with one must
+//       still be labelled by security (probed 2026-08-02: `finc_pe_ttm` over
+//       600519.SH + 09992.HK).
+export function flattenTimeSeries(data, keyBy = "name", requestedUniverse) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, data);
+    }
     const d = data;
-    const dates = asStringArray(d.dates);
-    const securityCode = asStringArray(d.securityCodeList);
-    const indicators = asIndicatorMetaList(d.indicatorList);
-    if (!Array.isArray(d.values) || !dates || !securityCode || !indicators)
-        return data;
-    const securityName = asStringArray(d.securityNameList);
-    const seriesAreIndicators = (requestedSecurities ?? securityCode.length) <= 1;
-    assertRowCount(d.values, seriesAreIndicators ? indicators.length : securityCode.length, seriesAreIndicators ? "indicators" : "securities");
+    assertMatrixPayload(data, d);
+    const dates = asIdentityArray(data, d.dates, "dates");
+    const securityCode = asIdentityArray(data, d.securityCodeList, "securityCodeList");
+    const indicators = asIndicatorMetaList(data, d.indicatorList);
+    assertAxis(data, dates, "dates");
+    assertAxis(data, securityCode, "securityCodeList");
+    assertAxis(data, indicators, "indicatorList");
+    assertValuesPresent(data, d.values);
+    const securityName = resolveSecurityNames(d.securityNameList, securityCode);
+    // The API permits multi-indicator × single-security OR single-indicator ×
+    // multi-security, never both — the server rejects such a REQUEST with 100003.
+    // A RESPONSE carrying both axes plural is therefore unattributable: whichever
+    // axis becomes the columns, the other one's identity is silently discarded
+    // (probed 2026-08-02: 2×2 rendered as 收盘价/成交量 with both securities gone,
+    // and droppedFromMatrix sees nothing missing so it would not even flag).
+    // Data with only one identity axis is unattributable in the other direction:
+    // `securityCodeList: []` alongside a populated matrix leaves every row
+    // belonging to no security at all, and the row/column counts still line up so
+    // no other guard notices.
+    // Without this, dates-with-no-series still passes the later shape check (0 rows
+    // for 0 series) and emits one row per date carrying nothing but the date. A
+    // response that resolved to nothing empties `dates` too (probed 2026-08-02), so dates
+    // alongside a missing axis is always a broken response.
+    if (dates.length > 0 && (securityCode.length === 0 || indicators.length === 0)) {
+        throw new ApiError(`Indicator matrix shape mismatch: the time-series response carries ${dates.length} dates but ${securityCode.length} securities and ${indicators.length} indicators — the data could not be attributed`, undefined, undefined, data);
+    }
+    if (securityCode.length > 1 && indicators.length > 1) {
+        throw new ApiError(`Indicator matrix shape mismatch: the time-series response carries ${securityCode.length} securities AND ${indicators.length} indicators, which the endpoint does not support — one of the two identities would be lost`, undefined, undefined, data);
+    }
+    // A universe entry without a `.` is a sector ID — the server expands it, so
+    // neither its presence nor the entry count says anything about the axis.
+    const requested = requestedUniverse === undefined ? undefined : [...new Set(requestedUniverse)];
+    const hasSector = requested?.some((entry) => !entry.includes(".")) ?? false;
+    const seriesAreIndicators = indicators.length > 1 ? true
+        : securityCode.length > 1 ? false
+            : hasSector ? false
+                : (requested?.length ?? securityCode.length) <= 1;
+    const seriesCount = seriesAreIndicators ? indicators.length : securityCode.length;
+    assertMatrixShape(data, d.values, seriesCount, seriesAreIndicators ? "indicators" : "securities", dates.length, "dates");
     // Map over securityCode rather than securityNameList directly: a response that
     // omits the names must still yield one header per security (falling back to
     // the code), not zero columns.

package/dist/src/core/printer.js

@@ -28,9 +28,11 @@ export async function printData(data, format, output, cache) {
             const listLen = Array.isArray(meta.list) ? meta.list.length : 0;
             process.stderr.write(`Total: ${meta.total}, showing: ${listLen}\n`);
         }
-        // Partial results (failed pages/shards) exit with code 3: the table/csv/jsonl
-        // renderers only emit the rows, so without a distinct exit code a script or AI
-        // consumer cannot tell a partial export from a complete one.
+        // Incomplete results exit with code 3: the table/csv/jsonl renderers only
+        // emit the rows, so without a distinct exit code a script or AI consumer
+        // cannot tell such an export from a clean one. `partial` means rows are
+        // missing — failed pages/shards, a row cap, or an EDE response that dropped
+        // whole securities/indicators because it did not recognise those codes.
         if (meta.partial === true) {
             process.exitCode = 3;
         }

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated — DO NOT EDIT
-export const CLI_VERSION = "0.30.1";
+export const CLI_VERSION = "0.32.0";