@datarails-ai/dr-cli 0.0.1-locked → 1.6.71

package/dist/skills/fx-conversion-matrix/scripts/_args.mjs

@@ -0,0 +1,52 @@
+/**
+ * Argument handling shared by this skill's scripts.
+ *
+ * Same reasoning as `_xlsx.mjs`: one copy, because a fix to the parser has to
+ * reach every script rather than the one someone happened to edit. These scripts
+ * can only import from this directory — the skill folder is copied verbatim into
+ * the CLI binary and runs under bare `node`, so nothing in `src/` or
+ * `node_modules/` is reachable from here.
+ */
+
+/**
+ * Parse `--flag value` / `--flag` pairs.
+ *
+ * A flag with no value (or followed by another flag) yields `true`, so every
+ * caller must check the type before using a value — {@link str} does that.
+ */
+export function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+/** A parsed flag's value, or undefined when absent or given without one. */
+export function str(args, key) {
+  const v = args[key];
+  return typeof v === 'string' && v !== '' ? v : undefined;
+}
+
+/** Fail with a one-line reason, the way every script here reports bad input. */
+export function die(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+/** A comma-separated currency list, upper-cased and emptied of blanks. */
+export function splitCodes(s) {
+  return String(s ?? '')
+    .split(',')
+    .map((c) => c.trim().toUpperCase())
+    .filter((c) => c !== '');
+}

package/dist/skills/fx-conversion-matrix/scripts/_xlsx.mjs

@@ -0,0 +1,241 @@
+/**
+ * Minimal .xlsx writer, shared by this skill's scripts.
+ *
+ * Dependency-free on purpose: exceljs and openpyxl are both routinely missing
+ * on Windows dev boxes, and a global npm install inside a sandboxed app lands
+ * somewhere the operator's own shell cannot see. The output is a stored-entry
+ * ZIP (no compression, so no zlib dance) wrapping the smallest OOXML package
+ * Excel and the Datarails backend will both accept -- verified by round-tripping
+ * a generated file through `dr documents add-functions` and a real filebox
+ * calculate.
+ *
+ * Kept as one module rather than copied per script: a fix to the ZIP or the
+ * package layout has to reach every producer, and two copies is how that stops
+ * being true. Nothing outside this directory is importable -- the skill folder is
+ * copied verbatim into the CLI binary and the scripts run under bare `node` --
+ * so the CLI's own `jszip` dependency is genuinely out of reach, not merely
+ * unused.
+ */
+
+// ---------------------------------------------------------------------------
+// ZIP
+// ---------------------------------------------------------------------------
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let c = 0 ^ -1;
+  for (let i = 0; i < buf.length; i += 1) c = (c >>> 8) ^ CRC_TABLE[(c ^ buf[i]) & 0xff];
+  return (c ^ -1) >>> 0;
+}
+
+/**
+ * Pack entries into a ZIP with stored (uncompressed) members.
+ *
+ * Timestamps are pinned to 1980-01-01 so the same inputs give the same bytes --
+ * which is what lets a regression test diff a generated workbook against a
+ * known-good one.
+ *
+ * @param {{name: string, data: Buffer}[]} entries
+ * @returns {Buffer}
+ */
+function zip(entries) {
+  const locals = [];
+  const central = [];
+  let offset = 0;
+
+  for (const { name, data } of entries) {
+    const nameBuf = Buffer.from(name, 'utf8');
+    const crc = crc32(data);
+
+    const local = Buffer.alloc(30 + nameBuf.length);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0, 6); // flags
+    local.writeUInt16LE(0, 8); // method: stored
+    local.writeUInt16LE(0, 10); // mod time
+    local.writeUInt16LE(0x21, 12); // mod date (1980-01-01, deterministic)
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    nameBuf.copy(local, 30);
+    locals.push(local, data);
+
+    const cd = Buffer.alloc(46 + nameBuf.length);
+    cd.writeUInt32LE(0x02014b50, 0);
+    cd.writeUInt16LE(20, 4); // version made by
+    cd.writeUInt16LE(20, 6); // version needed
+    cd.writeUInt16LE(0, 8);
+    cd.writeUInt16LE(0, 10);
+    cd.writeUInt16LE(0, 12);
+    cd.writeUInt16LE(0x21, 14);
+    cd.writeUInt32LE(crc, 16);
+    cd.writeUInt32LE(data.length, 20);
+    cd.writeUInt32LE(data.length, 24);
+    cd.writeUInt16LE(nameBuf.length, 28);
+    cd.writeUInt16LE(0, 30); // extra len
+    cd.writeUInt16LE(0, 32); // comment len
+    cd.writeUInt16LE(0, 34); // disk number
+    cd.writeUInt16LE(0, 36); // internal attrs
+    cd.writeUInt32LE(0, 38); // external attrs
+    cd.writeUInt32LE(offset, 42);
+    nameBuf.copy(cd, 46);
+    central.push(cd);
+
+    offset += local.length + data.length;
+  }
+
+  const cdBuf = Buffer.concat(central);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(cdBuf.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...locals, cdBuf, eocd]);
+}
+
+// ---------------------------------------------------------------------------
+// Cells and sheets
+// ---------------------------------------------------------------------------
+
+const xmlEscape = (s) =>
+  String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+
+/** 1-based column index -> spreadsheet letters (1 -> A, 27 -> AA). */
+export function colName(n) {
+  let s = '';
+  let i = n;
+  while (i > 0) {
+    const rem = (i - 1) % 26;
+    s = String.fromCharCode(65 + rem) + s;
+    i = Math.floor((i - 1) / 26);
+  }
+  return s;
+}
+
+/** A cell holding literal text. Inline, so no sharedStrings part is needed. */
+export const textCell = (ref, value) =>
+  `<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${xmlEscape(value)}</t></is></c>`;
+
+/**
+ * A cell holding a formula and NO cached value. Datarails recalculates
+ * server-side, and omitting `<v>` keeps a stale number from being mistaken for
+ * a real one before the first calculate.
+ */
+export const formulaCell = (ref, f) => `<c r="${ref}"><f>${xmlEscape(f)}</f></c>`;
+
+/** A cell holding a literal number. */
+export const numberCell = (ref, value) => `<c r="${ref}"><v>${value}</v></c>`;
+
+/**
+ * Serialise one worksheet.
+ *
+ * @param {Map<number, string[]>} rows row number -> cell XML, in column order
+ */
+export function sheetXml(rows) {
+  const body = [...rows.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([r, cells]) => `<row r="${r}">${cells.join('')}</row>`)
+    .join('');
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+    `<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">` +
+    `<sheetData>${body}</sheetData></worksheet>`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Package
+// ---------------------------------------------------------------------------
+
+/**
+ * Assemble a complete .xlsx from named sheets.
+ *
+ * @param {{name: string, xml: string}[]} sheets in tab order
+ * @param {{fullCalcOnLoad?: boolean}} [opts] `fullCalcOnLoad` forces a full
+ *   recalculation when the file is opened, so no cached zero survives a round
+ *   trip. Set it for workbooks carrying formulas; pointless for literal data.
+ * @returns {Buffer}
+ */
+export function buildWorkbook(sheets, opts = {}) {
+  const entries = sheets.map((s, i) => ({
+    ...s,
+    file: `sheet${i + 1}.xml`,
+    rid: `rId${i + 1}`,
+  }));
+
+  const contentTypes =
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+    `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">` +
+    `<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>` +
+    `<Default Extension="xml" ContentType="application/xml"/>` +
+    `<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>` +
+    entries
+      .map(
+        (s) =>
+          `<Override PartName="/xl/worksheets/${s.file}" ` +
+          `ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>`,
+      )
+      .join('') +
+    `</Types>`;
+
+  const rootRels =
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+    `<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>` +
+    `</Relationships>`;
+
+  const workbook =
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+    `<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" ` +
+    `xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets>` +
+    entries
+      .map((s, i) => `<sheet name="${xmlEscape(s.name)}" sheetId="${i + 1}" r:id="${s.rid}"/>`)
+      .join('') +
+    `</sheets>` +
+    (opts.fullCalcOnLoad === true ? `<calcPr calcId="0" fullCalcOnLoad="1"/>` : '') +
+    `</workbook>`;
+
+  const workbookRels =
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+    entries
+      .map(
+        (s) =>
+          `<Relationship Id="${s.rid}" ` +
+          `Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" ` +
+          `Target="worksheets/${s.file}"/>`,
+      )
+      .join('') +
+    `</Relationships>`;
+
+  return zip([
+    { name: '[Content_Types].xml', data: Buffer.from(contentTypes, 'utf8') },
+    { name: '_rels/.rels', data: Buffer.from(rootRels, 'utf8') },
+    { name: 'xl/workbook.xml', data: Buffer.from(workbook, 'utf8') },
+    { name: 'xl/_rels/workbook.xml.rels', data: Buffer.from(workbookRels, 'utf8') },
+    ...entries.map((s) => ({
+      name: `xl/worksheets/${s.file}`,
+      data: Buffer.from(s.xml, 'utf8'),
+    })),
+  ]);
+}

package/dist/skills/fx-conversion-matrix/scripts/build-matrix.mjs

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+/**
+ * Build the FX cross-currency conversion workbook.
+ *
+ * One sheet per target currency, named `To <CCY>`. Handles both source shapes
+ * and any number of rate types.
+ *
+ * SHAPES
+ *
+ *   --shape single-base   (default)
+ *       The source quotes everything against one currency. A cross-rate is then
+ *       a plain ratio -- rate(source->target) = rate(target)/rate(source) --
+ *       so there is ONE DR.GET per row per rate type and no lookup per pair.
+ *       It degenerates correctly when the base is itself a row (its rate is 1).
+ *
+ *   --shape pairs
+ *       The source already holds directed pairs (a from-currency AND a
+ *       to-currency dimension). Nothing is derived: each cell is a direct
+ *       lookup of the supplied pair. A pair the customer did not supply
+ *       returns 0, silently -- verify coverage BEFORE building (see the skill's
+ *       Step 0), because this layout cannot tell a missing pair from a zero.
+ *
+ * RATE TYPES
+ *
+ *   --rate-types "AVG=FX_Avg_Rate,EOP=FX_EOP_Rate"
+ *       name=function pairs. Each type gets its own column per target currency,
+ *       because a Datarails function binds exactly one value field. The legacy
+ *       `--function <NAME>` form is one unnamed type and is still accepted.
+ *
+ *       UDM names the two source rates `Currency AVG rate` (period average, for
+ *       P&L) and `Currency EOP rate` (end of period, for balance sheet), so
+ *       `--rate-types "AVG=...,EOP=..." --column-pattern "Currency {type} rate"`
+ *       reproduces the standard pair. Note EOP, not EOM: every tenant and the
+ *       MEC playbook spell it end-of-PERIOD.
+ *
+ * LAYOUTS
+ *
+ *   --layout matrix  (wiring A) headers on row 4, read by per-currency
+ *       datamappers picking cells by coordinate.
+ *   --layout lut     (wiring B) headers on row 1, key columns FIRST: a
+ *       filebox-sourced LUT resolves keys POSITIONALLY from the header row and
+ *       silently ignores the payload's keys/fields arrays. The period becomes a
+ *       real column rather than being implied by the filebox date tag, and the
+ *       DR.GET helpers move to a `_rates` sheet so each mapped sheet is exactly
+ *       key | key | value...
+ *
+ * Alongside the .xlsx this writes `<out>.layout.json` describing every mapped
+ * cell. `gen-mappers.mjs --layout-file` consumes it, so the two scripts cannot
+ * disagree about a coordinate.
+ *
+ * Usage:
+ *   node build-matrix.mjs --out matrix.xlsx --base USD \
+ *     --rate-types "Avg=FX_Avg_Rate,EOP=FX_EOP_Rate" \
+ *     --currencies USD,EUR,GBP,ILS [--targets EUR,GBP,ILS] \
+ *     [--shape single-base|pairs] [--layout matrix|lut] \
+ *     [--period-field "Reporting Month"] [--currency-field "Posting Currency"] \
+ *     [--to-currency-field "Reporting Currency"]   (pairs only) \
+ *     [--column-pattern "{type} {ccy} Rate"] [--scenario Actuals]
+ *
+ * No dependencies -- see `_xlsx.mjs` for why and how.
+ */
+import { writeFile } from 'node:fs/promises';
+
+import { die, parseArgs, splitCodes, str } from './_args.mjs';
+import {
+  buildWorkbook,
+  colName,
+  formulaCell as formula,
+  sheetXml,
+  textCell as text,
+} from './_xlsx.mjs';
+
+// ---------------------------------------------------------------------------
+// Arguments
+// ---------------------------------------------------------------------------
+
+const args = parseArgs(process.argv.slice(2));
+const out = args.out ?? 'matrix.xlsx';
+const base = (args.base ?? 'USD').toUpperCase();
+const periodField = str(args, 'period-field') ?? 'Reporting Month';
+const currencyField = str(args, 'currency-field') ?? 'Posting Currency';
+const toCurrencyField = str(args, 'to-currency-field') ?? 'Reporting Currency';
+const scenario = str(args, 'scenario') ?? 'Actuals';
+const layout = args.layout ?? 'matrix';
+const shape = args.shape ?? 'single-base';
+
+if (layout !== 'matrix' && layout !== 'lut')
+  die(`--layout must be "matrix" or "lut", got "${layout}"`);
+if (shape !== 'single-base' && shape !== 'pairs') {
+  die(`--shape must be "single-base" or "pairs", got "${shape}"`);
+}
+
+/**
+ * Rate types, as {name, fn}. `name` is '' for the legacy single-type form,
+ * which keeps its original column naming so existing files round-trip.
+ */
+let rateTypes;
+if (str(args, 'rate-types') !== undefined) {
+  rateTypes = str(args, 'rate-types')
+    .split(',')
+    .map((spec) => spec.trim())
+    .filter((spec) => spec !== '')
+    .map((spec) => {
+      const eq = spec.indexOf('=');
+      if (eq <= 0 || eq === spec.length - 1) {
+        die(`--rate-types entry "${spec}" must be NAME=FUNCTION (e.g. Avg=FX_Avg_Rate)`);
+      }
+      return { name: spec.slice(0, eq).trim(), fn: spec.slice(eq + 1).trim() };
+    });
+} else if (str(args, 'function') !== undefined) {
+  rateTypes = [{ name: '', fn: str(args, 'function') }];
+} else {
+  die('pass --rate-types "Avg=FX_Avg_Rate[,EOP=FX_EOP_Rate]" (or the legacy --function <NAME>)');
+}
+
+const seenNames = new Set();
+for (const t of rateTypes) {
+  if (seenNames.has(t.name)) die(`duplicate rate type name "${t.name}"`);
+  seenNames.add(t.name);
+  if (/\s/.test(t.fn)) die(`function name "${t.fn}" contains whitespace; dr functions reject that`);
+}
+
+/** Every currency that gets a ROW (the conversion sources). */
+const currencies = splitCodes(args.currencies);
+/** Every currency that gets a TAB (the conversion targets). Defaults to all. */
+const targets = args.targets === undefined ? currencies : splitCodes(args.targets);
+
+if (currencies.length === 0) die('--currencies USD,EUR,GBP is required');
+for (const t of targets) {
+  if (!currencies.includes(t)) {
+    die(`target ${t} is not in --currencies, so it has no row to convert from`);
+  }
+}
+if (shape === 'single-base' && !currencies.includes(base)) {
+  die(`base ${base} must appear in --currencies (its own rate is the 1.0 anchor)`);
+}
+
+/**
+ * Column name for one rate type on one target.
+ *
+ * The currency goes in the name only WHEN NEEDED -- a table with one reporting
+ * currency does not need it, and leaving it out keeps the plain UDM name that MEC
+ * and reconciliation expect. Defaults climb that ladder automatically:
+ *
+ *   1 target            `Currency AVG rate`              plain UDM
+ *   2+ targets          `EUR Currency AVG rate`          UDM stem, target prefixed
+ *   explicit pairing    `Currency USD to EUR AVG rate`   via --column-pattern
+ *
+ * All three forms exist in the reference org, so none of this is invented. The
+ * legacy single-unnamed-type form keeps `Rate to <CCY>` unchanged, because files
+ * already built that way must keep round-tripping.
+ *
+ * Tokens: {type} the rate type, {ccy} the target, {base} the base currency
+ * (single-base only -- in pairs mode the source varies per row, so there is no
+ * one base to name).
+ */
+function defaultColumnPattern() {
+  // The legacy single-unnamed-type form is pinned: files already built that way
+  // must keep round-tripping byte for byte.
+  if (rateTypes.length === 1 && rateTypes[0].name === '') return 'Rate to {ccy}';
+  return targets.length > 1 ? '{ccy} Currency {type} rate' : 'Currency {type} rate';
+}
+const columnPattern = str(args, 'column-pattern') ?? defaultColumnPattern();
+
+if (columnPattern.includes('{base}') && shape !== 'single-base') {
+  die(
+    '--column-pattern {base} needs --shape single-base; in pairs mode the source currency varies per row',
+  );
+}
+
+const columnName = (type, ccy) =>
+  columnPattern
+    .replaceAll('{type}', type.name)
+    .replaceAll('{ccy}', ccy)
+    .replaceAll('{base}', base)
+    // An unnamed rate type leaves a double space behind; collapse it.
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/**
+ * The lookup for one currency under one rate type.
+ *
+ * The period pair MUST come first, immediately after the function name. Any
+ * other order returns 0 with no error, no #NAME?, and nothing else to signal
+ * it. DR.MONTH() makes the match period-based rather than exact-timestamp,
+ * which is what a Date-typed period field needs.
+ */
+function rateFormula(type, code, toCode) {
+  const filters =
+    toCode === undefined
+      ? `"[${currencyField}]","${code}"`
+      : `"[${currencyField}]","${code}","[${toCurrencyField}]","${toCode}"`;
+  return (
+    `_xll.DR.GET(${type.fn},"[${periodField}]",_xll.DR.MONTH(DR_TAG_DATE),` +
+    `${filters},"[Scenario]","${scenario}")`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Sheets
+// ---------------------------------------------------------------------------
+
+/** @type {{name: string, xml: string}[]} */
+const sheets = [];
+/** Layout sidecar: what gen-mappers.mjs needs, so it never guesses a cell. */
+const layoutDoc = {
+  layout,
+  shape,
+  base: shape === 'single-base' ? base : null,
+  header_row: layout === 'lut' ? 1 : 4,
+  currency_field: currencyField,
+  period_field: periodField,
+  rate_types: rateTypes.map((t) => t.name),
+  sheets: [],
+};
+
+const headerRow = layout === 'lut' ? 1 : 4;
+const firstDataRow = headerRow + 1;
+
+/**
+ * Per-type helper columns holding the base-quoted rate. Only single-base needs
+ * them -- pairs mode reads its answer directly.
+ */
+const needsHelpers = shape === 'single-base';
+
+/**
+ * Row of `code` in whichever block holds the helper rates. The `_rates` sheet
+ * and a matrix tab both start their data at `firstDataRow`, so one expression
+ * covers both layouts.
+ */
+const helperRow = (code) => currencies.indexOf(code) + firstDataRow;
+
+/**
+ * Where each rate type's columns sit, resolved ONCE so the header row and the
+ * data rows cannot disagree about a coordinate.
+ *
+ *  - `helper` is the base-quoted rate. In `matrix` it interleaves with the
+ *    output columns (B,D,F...), in `lut` it lives on the `_rates` sheet
+ *    (B,C,D...), and in pairs mode there is none -- the lookup IS the answer.
+ *  - `out` is the mapped cross-rate column, the one gen-mappers reads.
+ */
+const columnPlan = rateTypes.map((type, ti) => ({
+  type,
+  helper: needsHelpers ? (layout === 'lut' ? colName(2 + ti) : colName(2 + 2 * ti)) : null,
+  out: layout === 'lut' ? colName(3 + ti) : needsHelpers ? colName(3 + 2 * ti) : colName(2 + ti),
+}));
+
+if (layout === 'lut' && needsHelpers) {
+  // Helpers live off the mapped sheets so each `To <CCY>` tab is exactly
+  // key | key | value... and positional key resolution cannot pick up a rate
+  // column by mistake.
+  const rows = new Map();
+  const head = [text(`A${headerRow}`, 'Currency')];
+  for (const { type, helper } of columnPlan) {
+    head.push(text(`${helper}${headerRow}`, `${base}-based ${type.name || 'rate'}`.trim()));
+  }
+  rows.set(headerRow, head);
+  currencies.forEach((code, i) => {
+    const r = firstDataRow + i;
+    const cells = [text(`A${r}`, code)];
+    for (const { type, helper } of columnPlan) {
+      cells.push(formula(`${helper}${r}`, rateFormula(type, code)));
+    }
+    rows.set(r, cells);
+  });
+  sheets.push({ name: '_rates', xml: sheetXml(rows) });
+}
+
+for (const target of targets) {
+  const rows = new Map();
+  // Every mapped column, in the order the header row lists them.
+  const plan = columnPlan.map((p) => ({ ...p, name: columnName(p.type, target) }));
+  const mappedColumns = plan.map((p) => ({ name: p.name, coordinate: `${p.out}${headerRow}` }));
+  // The anchor is the TARGET currency's own row, and it is the same for every
+  // source row on this tab.
+  const targetRow = helperRow(target);
+
+  if (layout === 'matrix') {
+    rows.set(1, [text('A1', `FX Conversion Matrix — convert to ${target}`)]);
+    // TEXT() wraps DR_TAG_DATE directly -- NOT DR.MONTH(), which returns a
+    // range-like pseudo-value and yields #NAME? when wrapped.
+    rows.set(2, [text('A2', 'Month:'), formula('B2', 'TEXT(DR_TAG_DATE,"mmmm yyyy")')]);
+
+    const head = [text(`A${headerRow}`, 'Currency')];
+    for (const { type, helper, out, name } of plan) {
+      if (helper !== null) {
+        head.push(text(`${helper}${headerRow}`, `${base}-based ${type.name || 'rate'}`.trim()));
+      }
+      head.push(text(`${out}${headerRow}`, name));
+    }
+    rows.set(headerRow, head);
+
+    currencies.forEach((code, i) => {
+      const r = firstDataRow + i;
+      const cells = [text(`A${r}`, code)];
+      for (const { type, helper, out } of plan) {
+        if (helper !== null) {
+          cells.push(formula(`${helper}${r}`, rateFormula(type, code)));
+          // rate(target)/rate(source), anchored on the target's own row.
+          cells.push(formula(`${out}${r}`, `$${helper}$${targetRow}/${helper}${r}`));
+        } else {
+          // Pairs: nothing is derived, the supplied pair IS the answer.
+          cells.push(formula(`${out}${r}`, rateFormula(type, code, target)));
+        }
+      }
+      rows.set(r, cells);
+    });
+  } else {
+    // Keys leftmost: the LUT engine takes the first key_len columns as keys.
+    const head = [text(`A${headerRow}`, 'Currency'), text(`B${headerRow}`, periodField)];
+    for (const { out, name } of plan) head.push(text(`${out}${headerRow}`, name));
+    rows.set(headerRow, head);
+
+    currencies.forEach((code, i) => {
+      const r = firstDataRow + i;
+      const cells = [
+        text(`A${r}`, code),
+        // The period must be a real, matchable column here -- a filebox-sourced
+        // LUT keys on cell values, not on the version's date tag.
+        formula(`B${r}`, 'TEXT(DR_TAG_DATE,"yyyy-mm")'),
+      ];
+      for (const { type, helper, out } of plan) {
+        cells.push(
+          helper !== null
+            ? formula(`${out}${r}`, `_rates!$${helper}$${targetRow}/_rates!$${helper}$${r}`)
+            : formula(`${out}${r}`, rateFormula(type, code, target)),
+        );
+      }
+      rows.set(r, cells);
+    });
+  }
+
+  sheets.push({ name: `To ${target}`, xml: sheetXml(rows) });
+  layoutDoc.sheets.push({
+    sheet: `To ${target}`,
+    target,
+    currency_coordinate: `A${headerRow}`,
+    columns: mappedColumns,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Package
+// ---------------------------------------------------------------------------
+
+// fullCalcOnLoad: every rate cell is a formula, so a cached value from a
+// previous period must never be what the reader sees.
+await writeFile(out, buildWorkbook(sheets, { fullCalcOnLoad: true }));
+
+const layoutFile = `${out}.layout.json`;
+await writeFile(layoutFile, `${JSON.stringify(layoutDoc, null, 2)}\n`, 'utf8');
+
+console.log(
+  `wrote ${out} — shape=${shape}, layout=${layout}` +
+    (shape === 'single-base' ? `, base=${base}` : '') +
+    `, ${rateTypes.length} rate type(s): ${rateTypes.map((t) => t.name || '(unnamed)').join(', ')}` +
+    `, ${targets.length} tab(s): ${targets.map((t) => `To ${t}`).join(', ')}`,
+);
+console.log(`wrote ${layoutFile} — pass it to gen-mappers.mjs --layout-file`);
+if (shape === 'pairs') {
+  console.log(
+    'note: pairs mode derives nothing. A pair the source does not carry reads 0 with\n' +
+      '      no error -- confirm coverage before trusting this file.',
+  );
+}
+console.log('next: dr documents add-functions (Step 4) BEFORE uploading, or every cell reads 0');