@dforge-core/metadata 0.0.34 → 0.0.36

package/dist/index.js

@@ -420,6 +420,658 @@ var DEP_COLUMN_TYPES = [
   "bytea"
 ];
 
+// src/registers/types.ts
+var REGISTER_KINDS = ["balance", "turnover", "info", "accounting"];
+var isRegisterKind = (value) => typeof value === "string" && REGISTER_KINDS.includes(value);
+var REGISTER_CODE = /^[a-z][a-z0-9_]*$/;
+var REGISTER_COLUMN_NAME = /^[a-z_][a-z0-9_]*$/;
+var REGISTER_TOTALS_PERIODS = ["day", "month", "quarter", "year"];
+
+// src/registers/read.ts
+var isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+var safeTrim = (value) => typeof value === "string" && value.trim() ? value : void 0;
+var stringList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+var hasKey = (obj, key) => obj[key] !== void 0;
+var registerDimensions = (def) => stringList(def.dimensions);
+var registerResources = (def) => !isRecord(def.resources) ? [] : Object.entries(def.resources).map(([name, raw]) => ({ name, def: isRecord(raw) ? raw : {} }));
+function registerCarrier(def) {
+  switch (def.kind) {
+    case "balance":
+    case "info":
+      return safeTrim(def.entity);
+    case "turnover":
+    case "accounting":
+      return safeTrim(def.journal);
+    default:
+      return void 0;
+  }
+}
+var registerResourceShape = (resource) => "debitField" in resource || "creditField" in resource ? "split" : "field";
+var registerLineMode = (def) => def.lineMode === "compound" ? "compound" : "classic";
+var INFO_PROPERTIES = ["period", "recorder", "recordChangesOnly"];
+var ACCOUNTING_PROPERTIES = [
+  "chart",
+  "composition",
+  "analyticFields",
+  "lineMode",
+  "account",
+  "debitAccount",
+  "creditAccount",
+  "debitAnalyticFields",
+  "creditAnalyticFields",
+  "sideDimensions"
+];
+var BALANCE_PROPERTIES = ["allowNegative", "autoCreate"];
+var REFUSED = {
+  balance: [...INFO_PROPERTIES, ...ACCOUNTING_PROPERTIES],
+  turnover: ["entity", ...INFO_PROPERTIES, ...ACCOUNTING_PROPERTIES, ...BALANCE_PROPERTIES],
+  info: ["journal", "journalDirection", "journalDate", ...ACCOUNTING_PROPERTIES, "totals", ...BALANCE_PROPERTIES],
+  accounting: ["entity", ...INFO_PROPERTIES, "journalDirection", ...BALANCE_PROPERTIES]
+};
+var REQUIRED = {
+  balance: ["entity"],
+  turnover: ["journal", "journalDirection", "journalDate"],
+  info: ["entity"],
+  accounting: ["chart", "journal", "journalDate", "lineMode"]
+};
+var registerRefusedProps = (kind) => REFUSED[kind];
+var registerRequiredProps = (kind) => REQUIRED[kind];
+var KIND_LABEL = {
+  balance: { sentence: "A balance register", inline: "a balance register" },
+  turnover: { sentence: "A turnover register", inline: "a turnover register" },
+  info: { sentence: "An information register", inline: "an information register" },
+  accounting: { sentence: "An accounting register", inline: "an accounting register" }
+};
+
+// src/registers/entities.ts
+function createEntityChecks(lookup, error, warning) {
+  const resolved = /* @__PURE__ */ new Map();
+  const columnSets = /* @__PURE__ */ new WeakMap();
+  const entityAt = (path, code, what) => {
+    if (!code || !lookup) {
+      return null;
+    }
+    if (!resolved.has(code)) {
+      resolved.set(code, lookup(code));
+    }
+    const found = resolved.get(code);
+    if (found === void 0) {
+      error(path, "unknown-entity", `${what} '${code}' isn't an entity this module can see.`);
+    }
+    return found;
+  };
+  const columnsOf = (entity) => {
+    if (!entity) {
+      return null;
+    }
+    if (!columnSets.has(entity)) {
+      columnSets.set(entity, entity.columns ? new Set(entity.columns) : null);
+    }
+    return columnSets.get(entity) ?? null;
+  };
+  const columnAt = (path, entity, entityCode, column, what) => {
+    if (typeof column !== "string" || !column.trim()) {
+      return;
+    }
+    if (!REGISTER_COLUMN_NAME.test(column)) {
+      error(path, "column-name", `${what} '${column}' isn't a column name (lowercase letters, digits and '_').`);
+      return;
+    }
+    const columns = columnsOf(entity);
+    if (columns && !columns.has(column)) {
+      warning(path, "unknown-column", `${what} '${column}' isn't a stored column of ${entityCode}.`);
+    }
+  };
+  return { entityAt, columnAt };
+}
+
+// src/registers/issues.ts
+function createIssueReporter(issues, namespace, severity) {
+  return (path, code, message) => {
+    issues.push({ path, code: `${namespace}/${code}`, message, severity });
+  };
+}
+
+// src/registers/check-declaration.ts
+var MAX_DIMENSIONS = 8;
+var MAX_RESOURCES = 64;
+var MAX_ANALYTIC_SLOTS = 8;
+var MAX_REGISTERS = 100;
+function checkColumnPair(error, code, first, second, where) {
+  if (!first || !second) {
+    error(where.missing, code, where.missingMessage);
+  }
+  if (first && first === second) {
+    error(where.same, code, where.sameMessage);
+  }
+}
+function refuseKeys(def, keys, error, code, message) {
+  for (const key of keys) {
+    if (hasKey(def, key)) {
+      error([key], code, message(key));
+    }
+  }
+}
+function checkProperties({ def, kind, error }) {
+  for (const key of registerRequiredProps(kind)) {
+    if (safeTrim(def[key]) === void 0) {
+      error([key], "required", `${KIND_LABEL[kind].sentence} needs '${key}'.`);
+    }
+  }
+  refuseKeys(def, registerRefusedProps(kind), error, "refused", (key) => `'${key}' isn't allowed on ${KIND_LABEL[kind].inline}.`);
+  if ((safeTrim(def.journalDirection) || safeTrim(def.journalDate)) && !safeTrim(def.journal)) {
+    error(["journal"], "journal-stamps", "'journalDirection' and 'journalDate' are columns of the journal \u2014 name the journal entity.");
+  }
+  if (kind === "info" && def.recordChangesOnly === true && !safeTrim(def.recorder)) {
+    error(["recordChangesOnly"], "record-changes-only", "'recordChangesOnly' needs a 'recorder' \u2014 only a document's record can be compared with the slice in effect.");
+  }
+}
+function resolveEntities(def, kind, checks) {
+  const { entityAt, columnAt } = checks;
+  const entityCode = safeTrim(def.entity);
+  const journalCode = safeTrim(def.journal);
+  const carriedByEntity = kind === "balance" || kind === "info";
+  const entity = carriedByEntity ? entityAt(["entity"], entityCode, "Entity") : null;
+  const journal = kind !== "info" ? entityAt(["journal"], journalCode, "Journal") : null;
+  if (kind === "accounting") {
+    entityAt(["chart"], safeTrim(def.chart), "Chart");
+  }
+  columnAt(["journalDirection"], journal, journalCode, def.journalDirection, "Journal direction column");
+  columnAt(["journalDate"], journal, journalCode, def.journalDate, "Journal date column");
+  columnAt(["period"], entity, entityCode, def.period, "Period column");
+  columnAt(["recorder"], entity, entityCode, def.recorder, "Recorder column");
+  return { journalCode, journal, carrierCode: registerCarrier(def), carrier: carriedByEntity ? entity : journal };
+}
+function checkDimensions({ def, dimensions, sides, carrier, carrierCode, columnAt, error }) {
+  if (!Array.isArray(def.dimensions) || dimensions.length === 0) {
+    error(["dimensions"], "dimensions", "A register needs at least one dimension.");
+  }
+  if (dimensions.length > MAX_DIMENSIONS) {
+    error(["dimensions"], "dimensions", `At most ${MAX_DIMENSIONS} dimensions.`);
+  }
+  const twice = dimensions.filter((name, index) => dimensions.indexOf(name) !== index);
+  if (twice.length > 0) {
+    error(["dimensions"], "dimensions", `Dimension listed more than once: ${[...new Set(twice)].join(", ")}.`);
+  }
+  dimensions.forEach((name, i) => {
+    if (!(name in sides)) {
+      columnAt(["dimensions", i], carrier, carrierCode, name, "Dimension");
+    }
+  });
+}
+function checkResourceShape(ctx, name, resource, path) {
+  const { def, kind, error } = ctx;
+  const field = safeTrim(resource.field);
+  const debit = safeTrim(resource.debitField);
+  const credit = safeTrim(resource.creditField);
+  const split = registerResourceShape(resource) === "split";
+  const classic = kind === "accounting" && registerLineMode(def) === "classic";
+  if (split && hasKey(resource, "field")) {
+    error(path("field"), "resource-shape", `Resource '${name}': either 'field' or 'debitField' + 'creditField', not both.`);
+  }
+  if (classic && !split) {
+    error(path(), "resource-shape", `Resource '${name}': on a classic accounting register every resource is split \u2014 'debitField' and 'creditField'.`);
+  } else if (kind !== "accounting" && split) {
+    error(path(), "resource-shape", `Resource '${name}': 'debitField' / 'creditField' belong to an accounting register \u2014 name one 'field'.`);
+  } else if (split) {
+    checkColumnPair(error, "resource-shape", debit, credit, {
+      missing: path(),
+      missingMessage: `Resource '${name}' needs both 'debitField' and 'creditField'.`,
+      same: path("creditField"),
+      sameMessage: `Resource '${name}': the debit and credit columns must differ.`
+    });
+  } else if (!field) {
+    error(path(), "resource-shape", `Resource '${name}' needs its column ('field').`);
+  }
+}
+function checkResources(ctx) {
+  const { def, kind, resources, dimensions, carrier, carrierCode, columnAt, error } = ctx;
+  if (!isRecord(def.resources) || resources.length === 0) {
+    error(["resources"], "resources", "A register needs at least one resource.");
+  }
+  if (resources.length > MAX_RESOURCES) {
+    error(["resources"], "resources", `At most ${MAX_RESOURCES} resources.`);
+  }
+  const takesAbsentAs = kind === "info" && !!safeTrim(def.recorder) && def.recordChangesOnly === true;
+  const storage = /* @__PURE__ */ new Map();
+  for (const { name, def: resource } of resources) {
+    const path = (key) => key ? ["resources", name, key] : ["resources", name];
+    if (!REGISTER_COLUMN_NAME.test(name)) {
+      error(path(), "resource-name", `Resource '${name}' isn't a name (lowercase letters, digits and '_').`);
+    }
+    checkResourceShape(ctx, name, resource, path);
+    for (const key of ["field", "debitField", "creditField"]) {
+      const column = safeTrim(resource[key]);
+      if (!column) {
+        continue;
+      }
+      columnAt(path(key), carrier, carrierCode, column, `Resource '${name}' column`);
+      const other = storage.get(column);
+      if (other && other !== name) {
+        error(path(key), "resource-column-shared", `Resources '${other}' and '${name}' both store into '${column}' \u2014 posting would add both into one column.`);
+      }
+      storage.set(column, name);
+    }
+    const field = safeTrim(resource.field);
+    if (field && dimensions.includes(field)) {
+      error(path("field"), "resource-is-dimension", `'${field}' is both a dimension and resource '${name}'.`);
+    }
+    if (hasKey(resource, "absentAs") && !takesAbsentAs) {
+      error(path("absentAs"), "absent-as", `Resource '${name}': 'absentAs' needs 'recordChangesOnly' on a subordinate information register.`);
+    }
+  }
+}
+function checkAnalyticSlotColumns(ctx, key, columns) {
+  columns.forEach((column, i) => ctx.columnAt([key, i], ctx.journal, ctx.journalCode, column, "Analytic slot column"));
+}
+function checkSideDimensions(ctx) {
+  const { dimensions, sides, journal, journalCode, columnAt, error } = ctx;
+  for (const [name, side] of Object.entries(sides)) {
+    const base = ["sideDimensions", name];
+    if (!dimensions.includes(name)) {
+      error(base, "side-dimension", `Two-sided dimension '${name}' must also be listed in 'dimensions'.`);
+    }
+    const sideDef = isRecord(side) ? side : {};
+    const debitField = safeTrim(sideDef.debitField);
+    const creditField = safeTrim(sideDef.creditField);
+    checkColumnPair(error, "side-dimension", debitField, creditField, {
+      missing: base,
+      missingMessage: `Two-sided dimension '${name}' needs 'debitField' and 'creditField'.`,
+      same: [...base, "creditField"],
+      sameMessage: `Two-sided dimension '${name}': the two columns must differ.`
+    });
+    columnAt([...base, "debitField"], journal, journalCode, debitField, `Dimension '${name}' debit column`);
+    columnAt([...base, "creditField"], journal, journalCode, creditField, `Dimension '${name}' credit column`);
+  }
+}
+function checkCompoundAccounts(ctx) {
+  const { def, journal, journalCode, columnAt, error } = ctx;
+  refuseKeys(def, ["account", "analyticFields"], error, "line-mode", (key) => `'${key}' belongs to a classic register; a compound one names 'debitAccount' and 'creditAccount'.`);
+  const debit = safeTrim(def.debitAccount);
+  const credit = safeTrim(def.creditAccount);
+  checkColumnPair(error, "accounts", debit, credit, {
+    missing: ["debitAccount"],
+    missingMessage: "A compound register needs 'debitAccount' and 'creditAccount'.",
+    same: ["creditAccount"],
+    sameMessage: "'debitAccount' and 'creditAccount' must differ \u2014 one column would record no correspondence."
+  });
+  columnAt(["debitAccount"], journal, journalCode, debit, "Debit account column");
+  columnAt(["creditAccount"], journal, journalCode, credit, "Credit account column");
+  const debitSlots = stringList(def.debitAnalyticFields);
+  const creditSlots = stringList(def.creditAnalyticFields);
+  if (debitSlots.length > MAX_ANALYTIC_SLOTS || creditSlots.length > MAX_ANALYTIC_SLOTS) {
+    error(["debitAnalyticFields"], "analytic-slots", `At most ${MAX_ANALYTIC_SLOTS} analytic slots per side.`);
+  }
+  const shared = debitSlots.filter((column) => creditSlots.includes(column));
+  if (shared.length > 0) {
+    error(["creditAnalyticFields"], "analytic-slots", `Analytic slot column on both sides: ${shared.join(", ")}.`);
+  }
+  checkAnalyticSlotColumns(ctx, "debitAnalyticFields", debitSlots);
+  checkAnalyticSlotColumns(ctx, "creditAnalyticFields", creditSlots);
+  const needsComposition = debitSlots.length > 0 || creditSlots.length > 0;
+  checkSideDimensions(ctx);
+  return needsComposition;
+}
+function checkClassicAccounts(ctx) {
+  const { def, journal, journalCode, columnAt, error } = ctx;
+  refuseKeys(def, ["debitAccount", "creditAccount", "debitAnalyticFields", "creditAnalyticFields", "sideDimensions"], error, "line-mode", (key) => `'${key}' belongs to a compound register.`);
+  if (!safeTrim(def.account)) {
+    error(["account"], "accounts", "A classic register names the posting's account column ('account').");
+  }
+  columnAt(["account"], journal, journalCode, safeTrim(def.account), "Account column");
+  const slots = stringList(def.analyticFields);
+  if (slots.length > MAX_ANALYTIC_SLOTS) {
+    error(["analyticFields"], "analytic-slots", `At most ${MAX_ANALYTIC_SLOTS} analytic slots.`);
+  }
+  checkAnalyticSlotColumns(ctx, "analyticFields", slots);
+  return slots.length > 0;
+}
+function checkComposition(ctx, needsComposition) {
+  const { def, entityAt, columnAt, error } = ctx;
+  const composition = isRecord(def.composition) ? def.composition : void 0;
+  if (needsComposition && !composition) {
+    error(["composition"], "composition", "Analytic slots need a 'composition' \u2014 where the chart says which analytic each account takes in which slot.");
+  }
+  if (!needsComposition && composition) {
+    error(["composition"], "composition", "'composition' is for a register with analytic slots; this one declares none.");
+  }
+  if (!composition) {
+    return;
+  }
+  for (const key of ["entity", "account", "slot", "analytic"]) {
+    if (!safeTrim(composition[key])) {
+      error(["composition", key], "composition", `'composition' needs '${key}'.`);
+    }
+  }
+  const code = safeTrim(composition.entity);
+  const entity = entityAt(["composition", "entity"], code, "Composition entity");
+  for (const key of ["account", "slot", "analytic"]) {
+    columnAt(["composition", key], entity, code, composition[key], `Composition '${key}' column`);
+  }
+}
+function checkAccounting(ctx) {
+  const { def, kind, error } = ctx;
+  if (kind !== "accounting") {
+    return;
+  }
+  const mode = safeTrim(def.lineMode);
+  if (mode && mode !== "classic" && mode !== "compound") {
+    error(["lineMode"], "line-mode", "'lineMode' is 'classic' or 'compound'.");
+  }
+  checkComposition(ctx, mode === "compound" ? checkCompoundAccounts(ctx) : checkClassicAccounts(ctx));
+}
+function checkTotals(ctx) {
+  const { def, kind, dimensions, resources, entityAt, columnAt, error } = ctx;
+  const totals = isRecord(def.totals) ? def.totals : void 0;
+  if (!totals || kind === "info") {
+    return;
+  }
+  const totalsCode = safeTrim(totals.entity);
+  if (!totalsCode) {
+    error(["totals", "entity"], "totals", "The totals cache needs its entity.");
+  }
+  const totalsEntity = entityAt(["totals", "entity"], totalsCode, "Totals entity");
+  const period = safeTrim(totals.period);
+  if (!period || !REGISTER_TOTALS_PERIODS.includes(period)) {
+    error(["totals", "period"], "totals", "The totals cache needs a period: day, month, quarter or year.");
+  }
+  if (!safeTrim(totals.periodField)) {
+    error(["totals", "periodField"], "totals", "The totals cache needs 'periodField' \u2014 the column holding each period's first date.");
+  }
+  columnAt(["totals", "periodField"], totalsEntity, totalsCode, safeTrim(totals.periodField), "Totals period column");
+  if (kind === "accounting") {
+    if (!safeTrim(totals.accountField)) {
+      error(["totals", "accountField"], "totals", "An accounting register's cache needs 'accountField'.");
+    }
+    columnAt(["totals", "accountField"], totalsEntity, totalsCode, safeTrim(totals.accountField), "Totals account column");
+    stringList(totals.dimensions).forEach((name, i) => {
+      if (!dimensions.includes(name)) {
+        error(["totals", "dimensions", i], "totals", `Totals dimension '${name}' isn't a dimension of the register.`);
+      }
+    });
+  } else {
+    if (hasKey(totals, "accountField")) {
+      error(["totals", "accountField"], "totals", "'accountField' belongs to an accounting register's cache.");
+    }
+    if (hasKey(totals, "dimensions")) {
+      error(["totals", "dimensions"], "totals", "A cache grouped by fewer dimensions is for an accounting register only.");
+    }
+  }
+  const cached = isRecord(totals.resources) ? totals.resources : {};
+  const pair = kind === "accounting" ? ["debitField", "creditField"] : ["inField", "outField"];
+  for (const { name } of resources) {
+    const entry = cached[name];
+    if (!isRecord(entry)) {
+      error(["totals", "resources"], "totals", `The totals cache must cover every resource \u2014 '${name}' is missing.`);
+      continue;
+    }
+    for (const key of pair) {
+      if (!safeTrim(entry[key])) {
+        error(["totals", "resources", name], "totals", `Totals resource '${name}' needs '${key}'.`);
+      }
+      columnAt(["totals", "resources", name, key], totalsEntity, totalsCode, safeTrim(entry[key]), `Totals '${name}' ${key}`);
+    }
+  }
+  for (const name of Object.keys(cached)) {
+    if (!resources.some((resource) => resource.name === name)) {
+      error(["totals", "resources", name], "totals", `Totals cache names '${name}', which isn't a resource of the register.`);
+    }
+  }
+}
+function checkWarnings({ def, kind, journalCode, warning }) {
+  if (!safeTrim(def.label)) {
+    warning(["label"], "label", "No label \u2014 the query builder shows the code.");
+  }
+  if (kind === "balance") {
+    if (!journalCode) {
+      warning(["journal"], "no-journal", "No journal: unposting has to recompute from the document, and as-of-date reads are refused.");
+    } else if (!safeTrim(def.journalDirection) || !safeTrim(def.journalDate)) {
+      warning(["journal"], "journal-stamps", "Declare both journal stamps (direction and date) from the start \u2014 rows journalled without them can't be backfilled.");
+    }
+  }
+}
+function checkRegister(raw, lookup) {
+  const out = [];
+  const error = createIssueReporter(out, "registers", "error");
+  const warning = createIssueReporter(out, "registers", "warning");
+  if (!isRecord(raw)) {
+    error([], "shape", "A register declaration is a JSON object.");
+    return out;
+  }
+  const def = raw;
+  if (!isRegisterKind(def.kind)) {
+    error(["kind"], "kind", "Pick a kind: balance, turnover, info or accounting.");
+    return out;
+  }
+  const kind = def.kind;
+  checkProperties({ def, kind, error });
+  const checks = createEntityChecks(lookup, error, warning);
+  const ctx = {
+    def,
+    kind,
+    error,
+    warning,
+    ...checks,
+    ...resolveEntities(def, kind, checks),
+    dimensions: registerDimensions(def),
+    sides: isRecord(def.sideDimensions) ? def.sideDimensions : {},
+    resources: registerResources(def)
+  };
+  checkDimensions(ctx);
+  checkResources(ctx);
+  checkAccounting(ctx);
+  checkTotals(ctx);
+  checkWarnings(ctx);
+  return out;
+}
+function checkRegisters(file, lookup) {
+  const out = [];
+  const error = createIssueReporter(out, "registers", "error");
+  if (!isRecord(file)) {
+    error([], "shape", "registers.json is an object of register declarations.");
+    return out;
+  }
+  const codes = Object.keys(file).filter((code) => !code.startsWith("$"));
+  if (codes.length === 0) {
+    error([], "empty", "A module with no registers has no registers.json \u2014 the file needs at least one.");
+  }
+  if (codes.length > MAX_REGISTERS) {
+    error([], "limit", `A module declares at most ${MAX_REGISTERS} registers.`);
+  }
+  for (const code of codes) {
+    if (!REGISTER_CODE.test(code)) {
+      error([code], "code", `'${code}': lowercase letters, digits and '_', starting with a letter \u2014 a binding names it as module.code.`);
+    }
+    for (const issue of checkRegister(file[code], lookup)) {
+      out.push({ ...issue, path: [code, ...issue.path] });
+    }
+  }
+  return out;
+}
+
+// src/registers/check-binding.ts
+var isPlainColumnRef = (value) => !value.startsWith("=") && !value.startsWith("'") && !value.includes(".");
+function checkPosting(params, ledger, error) {
+  const lineEntity = safeTrim(params.lineEntity);
+  const locked = stringList(params.lockedFields);
+  const lockedLines = stringList(params.lockedLineFields);
+  if (!Array.isArray(params.lockedFields) || locked.length === 0) {
+    error(["lockedFields"], "register-locked-fields", `'lockedFields' is required: the document columns frozen while posted (or ["*"] for the whole row).`);
+  }
+  if (lineEntity) {
+    if (!safeTrim(params.lineField)) {
+      error(["lineField"], "register-line", "A line posting needs 'lineField' \u2014 the line's key to the document.");
+    }
+    if (!Array.isArray(params.lockedLineFields) || lockedLines.length === 0) {
+      error(["lockedLineFields"], "register-locked-fields", `A line posting needs 'lockedLineFields' (or ["*"]).`);
+    }
+  } else {
+    if (hasKey(params, "lineField")) {
+      error(["lineField"], "register-line", "'lineField' needs a 'lineEntity'.");
+    }
+    if (hasKey(params, "lockedLineFields")) {
+      error(["lockedLineFields"], "register-line", "'lockedLineFields' is for a line posting \u2014 name the 'lineEntity'.");
+    }
+    if (hasKey(params, "headerMap")) {
+      error(["headerMap"], "register-header-map", "'headerMap' is for a binding that posts from lines; a document posting reads every value from the document already.");
+    }
+    if (hasKey(params, "groupLinesBy")) {
+      error(["groupLinesBy"], "register-group-lines", "'groupLinesBy' needs lines to group \u2014 name the 'lineEntity'.");
+    }
+  }
+  if (ledger) {
+    if (!lineEntity) {
+      error(["lineEntity"], "register-line", "An L column posts lines: 'lineEntity' and 'lineField' are required.");
+    }
+    for (const key of ["headerMap", "skipPostingWhenEmpty", "dateTrunc", "groupLinesBy"]) {
+      if (hasKey(params, key)) {
+        error([key], "register-ledger-only", `'${key}' is read by A columns only.`);
+      }
+    }
+  }
+  const dateField = safeTrim(params.dateField);
+  if (hasKey(params, "dateTrunc") && !dateField) {
+    error(["dateTrunc"], "register-date", "'dateTrunc' needs a 'dateField'.");
+  }
+  if (dateField && !locked.includes("*") && isPlainColumnRef(dateField) && !locked.includes(dateField)) {
+    error(["dateField"], "register-date-unlocked", `'${dateField}' must be in 'lockedFields': a posted document re-dated would leave what it posted under the old date.`);
+  }
+}
+function checkInfoBinding({ params, register, qualified, error }) {
+  if (!safeTrim(register.recorder)) {
+    error(["register"], "register-info-independent", `"${qualified}" is an independent information register (no 'recorder'): its records are written by data operations, not by posting \u2014 unposting could never find them.`);
+  }
+  for (const key of ["direction", "sign"]) {
+    if (hasKey(params, key)) {
+      error([key], "register-info-direction", `'${key}' is refused on a binding to an information register, which records values rather than quantities.`);
+    }
+  }
+}
+function checkLedgerAccounts({ params, register, error }) {
+  if (register.lineMode === "compound") {
+    if (hasKey(params, "accountField")) {
+      error(["accountField"], "register-accounts", "A compound register takes 'debitAccountField' and 'creditAccountField', not 'accountField'.");
+    }
+    if (!safeTrim(params.debitAccountField) || !safeTrim(params.creditAccountField)) {
+      error(["register"], "register-accounts", "A binding to a compound register names 'debitAccountField' and 'creditAccountField'.");
+    }
+    return;
+  }
+  if (!safeTrim(params.accountField)) {
+    error(["register"], "register-accounts", "A binding to a classic register names the line's 'accountField'.");
+  }
+  for (const key of ["debitAccountField", "creditAccountField"]) {
+    if (hasKey(params, key)) {
+      error([key], "register-accounts", `'${key}' belongs to a compound register; a classic one takes 'accountField'.`);
+    }
+  }
+}
+function checkLedgerMapValue(ctx, key, value, resources) {
+  const { register, error } = ctx;
+  const resource = resources[key];
+  const split = key in resources ? isRecord(resource) && registerResourceShape(resource) === "split" : isRecord(register.sideDimensions) && key in register.sideDimensions;
+  if (split) {
+    if (!isRecord(value) || !safeTrim(value.debit) || !safeTrim(value.credit)) {
+      error(["map", key], "register-map-value", `"${key}" has a column per side; map both 'debit' and 'credit' to line columns.`);
+    }
+  } else if (!safeTrim(value)) {
+    error(["map", key], "register-map-value", `"${key}" is shared between the sides; map it to one line column.`);
+  }
+}
+function checkMaps(ctx, dimensions, resources) {
+  const { params, qualified, ledger, register, error } = ctx;
+  const known = /* @__PURE__ */ new Set([...dimensions, ...Object.keys(resources)]);
+  const mapped = /* @__PURE__ */ new Set();
+  for (const mapKey of ["map", "headerMap"]) {
+    const map = isRecord(params[mapKey]) ? params[mapKey] : null;
+    if (!map) {
+      continue;
+    }
+    for (const key of Object.keys(map)) {
+      if (mapped.has(key)) {
+        error([mapKey, key], "register-map-key", `"${key}" is in both 'map' and 'headerMap' \u2014 one value cannot come from two places.`);
+      }
+      mapped.add(key);
+      if (!known.has(key)) {
+        error([mapKey, key], "register-map-key", `"${key}" is neither a dimension nor a resource of ${qualified} (dimensions: ${dimensions.join(", ") || "none"}; resources: ${Object.keys(resources).join(", ") || "none"}).`);
+      } else if (ledger && mapKey === "map") {
+        checkLedgerMapValue(ctx, key, map[key], resources);
+      } else if (mapKey === "headerMap" && key in resources && register.kind !== "info") {
+        error([mapKey, key], "register-header-map", `A resource ("${key}") can't come from the document on a line posting \u2014 it would be added once per line. Only an information register's records take it.`);
+      }
+    }
+  }
+  return mapped;
+}
+function checkMapping(ctx) {
+  const { params, register, qualified, error } = ctx;
+  const dimensions = stringList(register.dimensions);
+  const resources = isRecord(register.resources) ? register.resources : {};
+  const mapped = checkMaps(ctx, dimensions, resources);
+  const unmapped = Object.entries(resources).filter(([resource, def]) => !mapped.has(resource) && !(isRecord(def) && def.required === false)).map(([resource]) => resource);
+  if (unmapped.length > 0) {
+    error(
+      [hasKey(params, "map") ? "map" : "register"],
+      "register-unmapped-resource",
+      `Every required resource of ${qualified} must be mapped \u2014 missing: ${unmapped.join(", ")}. A writer that omitted one would post a silent zero.`
+    );
+  }
+  stringList(params.skipPostingWhenEmpty).forEach((name, i) => {
+    if (!dimensions.includes(name)) {
+      error(["skipPostingWhenEmpty", i], "register-skip", `"${name}" isn't a dimension of ${qualified}; 'skipPostingWhenEmpty' names register dimensions.`);
+    }
+  });
+}
+function checkRegisterBinding(columnType, rawParams, register, options = {}) {
+  const out = [];
+  const error = createIssueReporter(out, "entity", "error");
+  if (!isRecord(rawParams)) {
+    return out;
+  }
+  const params = rawParams;
+  const qualified = safeTrim(params.register);
+  if (!qualified) {
+    return out;
+  }
+  const ledger = columnType === "L";
+  if (hasKey(params, "registries")) {
+    error(["registries"], "register-and-inline", "A column binds to a register OR restates one inline in 'registries' \u2014 keep one.");
+  }
+  if (!qualified.includes(".")) {
+    error(["register"], "register-unqualified", `A register is named as module.register, e.g. "${options.moduleCode ?? "module"}.${qualified}".`);
+    return out;
+  }
+  const dot = qualified.indexOf(".");
+  const moduleCode = qualified.slice(0, dot);
+  const registerCode = qualified.slice(dot + 1);
+  checkPosting(params, ledger, error);
+  if (register === null) {
+    return out;
+  }
+  if (!register) {
+    error(["register"], "unknown-register", `No register "${qualified}" \u2014 ${moduleCode}/registers.json doesn't declare "${registerCode}".`);
+    return out;
+  }
+  const kind = register.kind;
+  if (ledger && kind !== "accounting") {
+    error(["register"], "register-kind", `An L column posts to an accounting register; "${qualified}" is a ${kind || "?"} register \u2014 use an A column.`);
+    return out;
+  }
+  if (!ledger && kind === "accounting") {
+    error(["register"], "register-kind", `An A column posts to a balance, turnover or info register; "${qualified}" is an accounting register \u2014 use an L column.`);
+    return out;
+  }
+  const ctx = { params, register, qualified, ledger, error };
+  if (kind === "info") {
+    checkInfoBinding(ctx);
+  }
+  if (ledger) {
+    checkLedgerAccounts(ctx);
+  }
+  checkMapping(ctx);
+  return out;
+}
+
 // src/index.ts
 var flagDefs = [
   { value: "V", label: "Visible" },
@@ -434,9 +1086,16 @@ export {
   FILTER_GROUP_OPERATORS,
   FILTER_OPERATORS,
   NUMERIC_TOTAL,
+  REGISTER_CODE,
+  REGISTER_COLUMN_NAME,
+  REGISTER_KINDS,
+  REGISTER_TOTALS_PERIODS,
   baseDatatypes,
   baseToDbDatatype,
   chartTypes,
+  checkRegister,
+  checkRegisterBinding,
+  checkRegisters,
   columnTypes,
   dataViewKinds,
   defaultParams,
@@ -455,6 +1114,15 @@ export {
   getPrimaryKeys,
   getTrait,
   isFieldTypeCd,
+  isPlainColumnRef,
+  isRegisterKind,
+  registerCarrier,
+  registerDimensions,
+  registerLineMode,
+  registerRefusedProps,
+  registerRequiredProps,
+  registerResourceShape,
+  registerResources,
   traitFieldConflicts,
   traits,
   vizTypes