@firedrill-tools/netsuite 0.1.2

package/firedrill/tools/netsuite/lib/suiteql-run.mjs

@@ -0,0 +1,270 @@
+// SuiteQL evaluation: resolve the parsed plan against the analytics tables and render every scalar as a string.
+import { quote } from "./errors.mjs";
+import { parseSql, SqlError, sqlBad } from "./suiteql-parse.mjs";
+import { buildTables, COLUMNS, displayIndex, DF_SOURCE, TABLES } from "./suiteql-tables.mjs";
+
+const canonicalTable = (name) => {
+  const canonical = TABLES.get(name.toLowerCase());
+  if (canonical === undefined) sqlBad(`unknown table ${quote(name)}`);
+  return canonical;
+};
+
+class Scope {
+  constructor() {
+    this.sources = [];
+  }
+
+  add(canonical, alias) {
+    const key = (alias ?? canonical).toLowerCase();
+    if (this.sources.some((source) => source.key === key)) sqlBad(`duplicate table alias ${quote(alias ?? canonical)}`);
+    this.sources.push({ key, canonical, columns: new Set(COLUMNS[canonical]) });
+  }
+
+  /** Resolve a column reference to the flat row key `<alias>.<column>`. */
+  resolve(reference) {
+    const column = reference.name.toLowerCase();
+    if (reference.qualifier !== null) {
+      const source = this.sources.find((entry) => entry.key === reference.qualifier.toLowerCase());
+      if (source === undefined) sqlBad(`unknown table qualifier ${quote(reference.qualifier)}`);
+      if (!source.columns.has(column)) sqlBad(`unknown column ${quote(`${reference.qualifier}.${reference.name}`)}`);
+      return { key: `${source.key}.${column}`, column, canonical: source.canonical };
+    }
+    const matches = this.sources.filter((entry) => entry.columns.has(column));
+    if (matches.length === 0) sqlBad(`unknown column ${quote(reference.name)}`);
+    if (matches.length > 1) sqlBad(`column ${quote(reference.name)} is ambiguous; qualify it with its table`);
+    return { key: `${matches[0].key}.${column}`, column, canonical: matches[0].canonical };
+  }
+
+  star(qualifier) {
+    if (qualifier === null) {
+      if (this.sources.length > 1) sqlBad("SELECT * needs a table qualifier when the statement joins tables");
+      return this.sources.flatMap((source) => [...source.columns].map((column) => ({ key: `${source.key}.${column}`, name: column })));
+    }
+    const source = this.sources.find((entry) => entry.key === qualifier.toLowerCase());
+    if (source === undefined) sqlBad(`unknown table qualifier ${quote(qualifier)}`);
+    return [...source.columns].map((column) => ({ key: `${source.key}.${column}`, name: column }));
+  }
+}
+
+const flatten = (source, key, row) => {
+  const flat = {};
+  for (const column of COLUMNS[source]) flat[`${key}.${column}`] = row[column] ?? null;
+  return flat;
+};
+
+/** Both sides of a join must be plain column equalities so the right table can be indexed once. */
+function joinKeys(node, scope, rightKey, keys = []) {
+  if (node.kind === "and") {
+    joinKeys(node.left, scope, rightKey, keys);
+    joinKeys(node.right, scope, rightKey, keys);
+    return keys;
+  }
+  if (node.kind !== "compare" || node.operator !== "=") {
+    sqlBad("a JOIN condition must be one or more column equalities");
+  }
+  if (node.left.kind !== "column" || node.right.kind !== "column") {
+    sqlBad("a JOIN condition must compare two columns");
+  }
+  const left = scope.resolve(node.left);
+  const right = scope.resolve(node.right);
+  const leftIsRightTable = left.key.startsWith(`${rightKey}.`);
+  const rightIsRightTable = right.key.startsWith(`${rightKey}.`);
+  if (leftIsRightTable === rightIsRightTable) sqlBad("a JOIN condition must relate the joined table to an earlier one");
+  keys.push(leftIsRightTable ? { outer: right.key, inner: left.key } : { outer: left.key, inner: right.key });
+  return keys;
+}
+
+const text = (value) => (value === null || value === undefined ? "" : String(value));
+
+/** One aggregate over a group bucket's already-evaluated argument values. */
+export function aggregate(name, values, distinct) {
+  const present = values.filter((entry) => entry !== null && entry !== undefined);
+  if (name === "COUNT") {
+    return distinct === true ? new Set(present.map((entry) => String(entry))).size : present.length;
+  }
+  if (present.length === 0) return null;
+  const numbers = present.map((entry) => {
+    const parsed = typeof entry === "number" ? entry : Number(entry);
+    if (!Number.isFinite(parsed)) sqlBad(`${name} needs numeric values`);
+    return parsed;
+  });
+  const total = numbers.reduce((sum, entry) => sum + entry, 0);
+  if (name === "SUM") return Math.round(total * 1e6) / 1e6;
+  if (name === "AVG") return Math.round((total / numbers.length) * 1e6) / 1e6;
+  if (name === "MIN") return Math.min(...numbers);
+  return Math.max(...numbers);
+}
+
+function likeMatch(value, pattern) {
+  const subject = text(value).toLowerCase();
+  const source = text(pattern).toLowerCase();
+  let index = 0;
+  let anchored = true;
+  let cursor = 0;
+  while (index < source.length) {
+    if (source[index] === "%") {
+      anchored = false;
+      index += 1;
+      continue;
+    }
+    let segment = "";
+    let singles = 0;
+    while (index < source.length && source[index] !== "%") {
+      if (source[index] === "_") singles += 1;
+      else segment += source[index];
+      index += 1;
+    }
+    if (singles > 0) {
+      // `_` is matched positionally: consume one character per underscore around the literal segment.
+      if (anchored) {
+        if (cursor + singles + segment.length > subject.length) return false;
+        if (!subject.startsWith(segment, cursor + singles)) return false;
+        cursor += singles + segment.length;
+      } else {
+        const found = subject.indexOf(segment, cursor + singles);
+        if (found < 0) return false;
+        cursor = found + segment.length;
+      }
+    } else if (anchored) {
+      if (!subject.startsWith(segment, cursor)) return false;
+      cursor += segment.length;
+    } else {
+      const found = subject.indexOf(segment, cursor);
+      if (found < 0) return false;
+      cursor = found + segment.length;
+    }
+    anchored = true;
+  }
+  return anchored ? cursor === subject.length : true;
+}
+
+function compareValues(left, right) {
+  if (left === null || right === null) return null;
+  const leftNumber = typeof left === "number" ? left : Number(left);
+  const rightNumber = typeof right === "number" ? right : Number(right);
+  if (Number.isFinite(leftNumber) && Number.isFinite(rightNumber) && text(left).trim() !== "" && text(right).trim() !== "") {
+    return leftNumber < rightNumber ? -1 : leftNumber > rightNumber ? 1 : 0;
+  }
+  const leftText = text(left);
+  const rightText = text(right);
+  return leftText < rightText ? -1 : leftText > rightText ? 1 : 0;
+}
+
+export function runSql(session, statement, params) {
+  const plan = parseSql(statement);
+  const scope = new Scope();
+  const tables = buildTables(session);
+  const fromCanonical = canonicalTable(plan.from.name);
+  scope.add(fromCanonical, plan.from.alias);
+  const fromKey = scope.sources[0].key;
+  let rows = tables.rows(fromCanonical).map((row) => flatten(fromCanonical, fromKey, row));
+
+  for (const join of plan.joins) {
+    const canonical = canonicalTable(join.table.name);
+    scope.add(canonical, join.table.alias);
+    const key = scope.sources[scope.sources.length - 1].key;
+    const keys = joinKeys(join.on, scope, key, []);
+    const index = new Map();
+    const rightRows = tables.rows(canonical).map((row) => flatten(canonical, key, row));
+    for (const row of rightRows) {
+      const composite = keys.map((entry) => text(row[entry.inner])).join("\u0000");
+      const bucket = index.get(composite);
+      if (bucket === undefined) index.set(composite, [row]);
+      else bucket.push(row);
+    }
+    const joined = [];
+    const empty = Object.fromEntries(COLUMNS[canonical].map((column) => [`${key}.${column}`, null]));
+    for (const row of rows) {
+      const composite = keys.map((entry) => text(row[entry.outer])).join("\u0000");
+      const matches = index.get(composite);
+      if (matches === undefined) {
+        if (join.kind === "left") joined.push({ ...row, ...empty });
+        continue;
+      }
+      for (const match of matches) joined.push({ ...row, ...match });
+    }
+    rows = joined;
+  }
+
+  const display = displayIndex(session);
+  if (plan.paramCount > params.length) {
+    sqlBad(`the statement uses ${plan.paramCount} ? parameters but ${params.length} were supplied`);
+  }
+
+  function value(node, row) {
+    if (node.kind === "literal") return node.value;
+    if (node.kind === "param") return params[node.index] ?? null;
+    if (node.kind === "column") return row[scope.resolve(node).key] ?? null;
+    if (node.kind === "df") {
+      const resolved = scope.resolve(node.column);
+      const source = DF_SOURCE[resolved.column];
+      if (source === undefined) sqlBad(`BUILTIN.DF is not supported for column ${quote(node.column.name)}`);
+      const raw = row[resolved.key] ?? null;
+      if (source === "status") return raw;
+      if (raw === null) return null;
+      return display.get(source)?.get(String(raw)) ?? null;
+    }
+    if (node.kind === "call") {
+      const args = node.args.map((argument) => value(argument, row));
+      if (node.name === "UPPER") return args[0] === null ? null : text(args[0]).toUpperCase();
+      if (node.name === "LOWER") return args[0] === null ? null : text(args[0]).toLowerCase();
+      return args[0] === null ? (args[1] ?? null) : args[0];
+    }
+    if (node.kind === "aggregate") {
+      const bucket = Object.hasOwn(row, "__bucket__") ? row.__bucket__ : null;
+      if (!Array.isArray(bucket)) sqlBad("an aggregate is only supported in the select list, HAVING and ORDER BY");
+      if (node.args[0].kind === "star") return bucket.length;
+      return aggregate(node.name, bucket.map((entry) => value(node.args[0], entry)), node.distinct);
+    }
+    if (node.kind === "star") sqlBad("* cannot be used here");
+    sqlBad("unsupported expression");
+    return null;
+  }
+
+  function test(node, row) {
+    if (node.kind === "and") return test(node.left, row) && test(node.right, row);
+    if (node.kind === "or") return test(node.left, row) || test(node.right, row);
+    if (node.kind === "not") return !test(node.operand, row);
+    if (node.kind === "isNull") {
+      const actual = value(node.operand, row);
+      return node.negated ? actual !== null : actual === null;
+    }
+    if (node.kind === "like") {
+      const result = likeMatch(value(node.left, row), value(node.right, row));
+      return node.negated ? !result : result;
+    }
+    if (node.kind === "between") {
+      const actual = value(node.left, row);
+      const low = compareValues(actual, value(node.low, row));
+      const high = compareValues(actual, value(node.high, row));
+      const result = low !== null && high !== null && low >= 0 && high <= 0;
+      return node.negated ? !result : result;
+    }
+    if (node.kind === "in") {
+      const actual = value(node.left, row);
+      const result = node.values.some((entry) => compareValues(actual, value(entry, row)) === 0);
+      return node.negated ? !result : result;
+    }
+    const order = compareValues(value(node.left, row), value(node.right, row));
+    if (order === null) return false;
+    switch (node.operator) {
+      case "=": return order === 0;
+      case "<>": return order !== 0;
+      case "<": return order < 0;
+      case "<=": return order <= 0;
+      case ">": return order > 0;
+      default: return order >= 0;
+    }
+  }
+
+  if (plan.where !== null) {
+    const filtered = [];
+    for (const row of rows) {
+      if (test(plan.where, row)) filtered.push(row);
+    }
+    rows = filtered;
+  }
+  return { plan, scope, rows, value, test, display };
+}
+
+export { SqlError };

package/firedrill/tools/netsuite/lib/suiteql-select.mjs

@@ -0,0 +1,118 @@
+// SuiteQL projection: select list, DISTINCT, GROUP BY / HAVING, ORDER BY and FETCH FIRST, rendered as NetSuite does.
+import { runSql } from "./suiteql-run.mjs";
+import { sqlBad } from "./suiteql-parse.mjs";
+
+const hasAggregate = (node) => {
+  if (node === null || node === undefined) return false;
+  if (node.kind === "aggregate") return true;
+  if (node.kind === "call") return node.args.some(hasAggregate);
+  return false;
+};
+
+/** NetSuite renders every scalar in a SuiteQL result as a JSON string; null stays null. */
+const render = (value) => {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "boolean") return value ? "T" : "F";
+  return String(value);
+};
+
+function columnName(item, index, scope) {
+  if (item.alias !== null && item.alias !== undefined) return item.alias.toLowerCase();
+  if (item.expression.kind === "column") return scope.resolve(item.expression).column;
+  if (item.expression.kind === "df") return `df_${scope.resolve(item.expression.column).column}`;
+  return `expr${index + 1}`;
+}
+
+/** Execute a SuiteQL statement and return plain result rows (all scalars already rendered). */
+export function executeSql(session, statement, params) {
+  const { plan, scope, rows, value, test } = runSql(session, statement, params);
+
+  const expanded = [];
+  for (const [index, item] of plan.select.entries()) {
+    if (item.expression.kind === "star") {
+      for (const column of scope.star(item.expression.qualifier)) {
+        expanded.push({ name: column.name, read: (row) => row[column.key] ?? null });
+      }
+      continue;
+    }
+    const name = columnName(item, index, scope);
+    expanded.push({ name, expression: item.expression, read: (row) => value(item.expression, row) });
+  }
+
+  const grouped = plan.groupBy.length > 0 || plan.select.some((item) => hasAggregate(item.expression));
+  let resultRows;
+  if (!grouped) {
+    if (plan.having !== null) sqlBad("HAVING needs a grouped statement");
+    resultRows = rows.map((row) => {
+      const output = {};
+      for (const column of expanded) output[column.name] = column.read(row);
+      return { output, source: row };
+    });
+  } else {
+    const keys = plan.groupBy.map((reference) => scope.resolve(reference).key);
+    const buckets = new Map();
+    for (const row of rows) {
+      const composite = keys.map((key) => (row[key] === null ? "\u0001" : String(row[key]))).join("\u0000");
+      const bucket = buckets.get(composite);
+      if (bucket === undefined) buckets.set(composite, [row]);
+      else bucket.push(row);
+    }
+    if (keys.length === 0) buckets.set("", rows);
+    resultRows = [];
+    for (const bucket of buckets.values()) {
+      const first = bucket[0] ?? {};
+      const output = {};
+      const carrier = { ...first, __bucket__: bucket };
+      for (const column of expanded) {
+        output[column.name] = column.expression !== undefined && hasAggregate(column.expression)
+          ? value(column.expression, carrier)
+          : column.read(first);
+      }
+      const groupRow = { output, source: first, bucket, carrier };
+      if (plan.having === null || test(plan.having, carrier)) resultRows.push(groupRow);
+    }
+  }
+
+  if (plan.distinct === true) {
+    const seen = new Set();
+    resultRows = resultRows.filter((entry) => {
+      const key = JSON.stringify(entry.output);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
+  for (const order of [...plan.orderBy].reverse()) {
+    // ORDER BY may name a select alias, as Oracle allows; otherwise it is an expression over the source row.
+    const alias = order.expression.kind === "column" && order.expression.qualifier === null
+      ? order.expression.name.toLowerCase()
+      : null;
+    const read = (entry) => {
+      if (alias !== null && Object.hasOwn(entry.output, alias)) return entry.output[alias];
+      return order.expression.kind === "column"
+        ? entry.source[scope.resolve(order.expression).key] ?? null
+        : value(order.expression, entry.carrier ?? entry.source);
+    };
+    resultRows = [...resultRows].sort((left, right) => {
+      const a = read(left);
+      const b = read(right);
+      if (a === b) return 0;
+      if (a === null) return 1;
+      if (b === null) return -1;
+      const numeric = Number(a) - Number(b);
+      const compared = Number.isFinite(numeric) && String(a).trim() !== "" && String(b).trim() !== ""
+        ? numeric
+        : String(a) < String(b) ? -1 : 1;
+      return order.direction === "desc" ? -compared : compared;
+    });
+  }
+
+  if (plan.fetch !== null) resultRows = resultRows.slice(0, plan.fetch);
+
+  return resultRows.map((entry) => {
+    const output = {};
+    for (const [key, raw] of Object.entries(entry.output)) output[key] = render(raw);
+    return output;
+  });
+}

package/firedrill/tools/netsuite/lib/suiteql-tables.mjs

@@ -0,0 +1,162 @@
+// The analytics tables the SuiteQL subset exposes, built from state rows and filtered by the session's subsidiary scope.
+import { invStatus, payStatus, soStatus } from "./project.mjs";
+
+export const TABLES = new Map([
+  ["customer", "customer"],
+  ["transaction", "transaction"],
+  ["transactionline", "transactionLine"],
+  ["item", "item"],
+  ["employee", "employee"],
+  ["subsidiary", "subsidiary"],
+]);
+
+export const COLUMNS = {
+  customer: [
+    "id", "entityid", "companyname", "email", "phone", "isperson", "isinactive",
+    "subsidiary", "datecreated", "lastmodifieddate", "firstname", "lastname", "creditlimit",
+  ],
+  transaction: [
+    "id", "type", "entity", "trandate", "tranid", "status", "foreigntotal",
+    "memo", "subsidiary", "duedate", "createdfrom",
+  ],
+  transactionLine: [
+    "id", "transaction", "linesequencenumber", "item", "quantity", "rate", "netamount", "subsidiary",
+  ],
+  item: ["id", "itemid", "displayname", "description", "baseprice", "cost", "quantityonhand", "itemtype", "isinactive"],
+  employee: ["id", "entityid", "firstname", "lastname", "email", "title", "subsidiary", "supervisor", "isinactive"],
+  subsidiary: ["id", "name", "parent", "country", "currency", "isinactive"],
+};
+
+/** Columns whose BUILTIN.DF renders another record's display name. */
+export const DF_SOURCE = {
+  entity: "customer",
+  customer: "customer",
+  item: "item",
+  subsidiary: "subsidiary",
+  supervisor: "employee",
+  parent: "subsidiary",
+  transaction: "transaction",
+  createdfrom: "transaction",
+  status: "status",
+};
+
+const inScope = (session, subsidiaryId) => session.inScope(subsidiaryId);
+
+export function buildTables(session) {
+  const cache = new Map();
+  return {
+    rows(name) {
+      if (cache.has(name)) return cache.get(name);
+      const built = build(session, name);
+      cache.set(name, built);
+      return built;
+    },
+  };
+}
+
+function build(session, name) {
+  if (name === "customer") {
+    return session.rows("customers").filter((row) => inScope(session, row.subsidiaryId)).map((row) => ({
+      id: row.id,
+      entityid: row.entityId,
+      companyname: row.companyName,
+      email: row.email,
+      phone: row.phone,
+      isperson: row.isPerson ? "T" : "F",
+      isinactive: row.isInactive ? "T" : "F",
+      subsidiary: row.subsidiaryId,
+      datecreated: row.dateCreated,
+      lastmodifieddate: row.lastModifiedDate,
+      firstname: row.firstName,
+      lastname: row.lastName,
+      creditlimit: row.creditLimit,
+    }));
+  }
+  if (name === "transaction") {
+    const rows = [];
+    for (const order of session.rows("sales-orders")) {
+      if (!inScope(session, order.subsidiaryId)) continue;
+      rows.push({
+        id: order.id, type: "SalesOrd", entity: order.entityId, trandate: order.tranDate,
+        tranid: order.tranId, status: soStatus(order.status).refName, foreigntotal: order.total,
+        memo: order.memo, subsidiary: order.subsidiaryId, duedate: null, createdfrom: null,
+      });
+    }
+    for (const invoice of session.rows("invoices")) {
+      if (!inScope(session, invoice.subsidiaryId)) continue;
+      rows.push({
+        id: invoice.id, type: "CustInvc", entity: invoice.entityId, trandate: invoice.tranDate,
+        tranid: invoice.tranId, status: invStatus(invoice.status).refName, foreigntotal: invoice.total,
+        memo: invoice.memo, subsidiary: invoice.subsidiaryId, duedate: invoice.dueDate,
+        createdfrom: invoice.createdFromId,
+      });
+    }
+    for (const payment of session.rows("customer-payments")) {
+      if (!inScope(session, payment.subsidiaryId)) continue;
+      rows.push({
+        id: payment.id, type: "CustPymt", entity: payment.entityId, trandate: payment.tranDate,
+        tranid: payment.tranId, status: payStatus(payment.status).refName, foreigntotal: payment.payment,
+        memo: payment.memo, subsidiary: payment.subsidiaryId, duedate: null, createdfrom: null,
+      });
+    }
+    rows.sort((left, right) => Number(left.id) - Number(right.id));
+    return rows;
+  }
+  if (name === "transactionLine") {
+    const rows = [];
+    const push = (record) => {
+      if (!inScope(session, record.subsidiaryId)) return;
+      for (const line of record.lines) {
+        rows.push({
+          id: `${record.id}.${line.line}`,
+          transaction: record.id,
+          linesequencenumber: line.line,
+          item: line.itemId,
+          quantity: line.quantity,
+          rate: line.rate,
+          netamount: line.amount,
+          subsidiary: record.subsidiaryId,
+        });
+      }
+    };
+    for (const order of session.rows("sales-orders")) push(order);
+    for (const invoice of session.rows("invoices")) push(invoice);
+    return rows;
+  }
+  if (name === "item") {
+    return session.rows("items")
+      .filter((row) => row.subsidiaryIds.some((id) => inScope(session, id)))
+      .map((row) => ({
+        id: row.id, itemid: row.itemId, displayname: row.displayName, description: row.description,
+        baseprice: row.basePrice, cost: row.cost, quantityonhand: row.quantityOnHand,
+        itemtype: row.itemType === "inventoryItem" ? "InvtPart" : "Service",
+        isinactive: row.isInactive ? "T" : "F",
+      }));
+  }
+  if (name === "employee") {
+    return session.rows("employees").filter((row) => inScope(session, row.subsidiaryId)).map((row) => ({
+      id: row.id, entityid: row.entityId, firstname: row.firstName, lastname: row.lastName,
+      email: row.email, title: row.title, subsidiary: row.subsidiaryId, supervisor: row.supervisorId,
+      isinactive: row.isInactive ? "T" : "F",
+    }));
+  }
+  return session.rows("subsidiaries").filter((row) => inScope(session, row.id)).map((row) => ({
+    id: row.id, name: row.name, parent: row.parentId, country: row.country,
+    currency: row.currencyName, isinactive: row.isInactive ? "T" : "F",
+  }));
+}
+
+/** Display names for BUILTIN.DF, resolved once per request. */
+export function displayIndex(session) {
+  const index = new Map();
+  index.set("customer", new Map(session.rows("customers").map((row) => [row.id, row.entityId])));
+  index.set("item", new Map(session.rows("items").map((row) => [row.id, row.itemId])));
+  index.set("subsidiary", new Map(session.rows("subsidiaries").map((row) => [row.id, row.name])));
+  index.set("employee", new Map(session.rows("employees").map((row) => [row.id, row.entityId])));
+  const transactions = new Map();
+  for (const order of session.rows("sales-orders")) transactions.set(order.id, order.tranId);
+  for (const invoice of session.rows("invoices")) transactions.set(invoice.id, invoice.tranId);
+  for (const payment of session.rows("customer-payments")) transactions.set(payment.id, payment.tranId);
+  index.set("transaction", transactions);
+  return index;
+}

package/firedrill/tools/netsuite/lib/tran.mjs

@@ -0,0 +1,133 @@
+// Shared transaction rules: reference resolution, line building, totals, derived status and document numbers.
+import { quote } from "./errors.mjs";
+import { round2, round4 } from "./primitives.mjs";
+import { numberField, referenceField, stringField } from "./body.mjs";
+
+const TAX_RATES = new Map([["1", 0.086], ["2", 0.05]]);
+export const taxRateFor = (subsidiaryId) => TAX_RATES.get(subsidiaryId) ?? 0;
+
+export function resolveCustomer(session, entityId, path = "entity") {
+  const customer = session.get("customers", entityId);
+  if (customer === null || !session.inScope(customer.subsidiaryId)) {
+    session.fail("INVALID_KEY_OR_REF", `Invalid customer reference key ${quote(String(entityId))}.`, { errorPath: path });
+  }
+  if (customer.isInactive === true) {
+    session.fail("USER_ERROR", `The customer ${quote(customer.entityId)} is inactive and cannot be used on a transaction.`, {
+      errorPath: path,
+    });
+  }
+  return customer;
+}
+
+export function resolveItem(session, itemId, subsidiaryId, path) {
+  const item = session.get("items", itemId);
+  if (item === null) {
+    session.fail("INVALID_KEY_OR_REF", `Invalid item reference key ${quote(String(itemId))}.`, { errorPath: path });
+  }
+  if (item.isInactive === true) {
+    session.fail("USER_ERROR", `The item ${quote(item.itemId)} is inactive and cannot be used on a transaction.`, { errorPath: path });
+  }
+  if (!item.subsidiaryIds.includes(subsidiaryId)) {
+    session.fail("INVALID_KEY_OR_REF", `The item ${quote(item.itemId)} is not available in the subsidiary of this transaction.`, {
+      errorPath: path,
+    });
+  }
+  return item;
+}
+
+/** Build the item sublist from a wire body; `quantityBilled` is preserved from an existing line when given. */
+export function buildLine(session, entry, subsidiaryId, lineNumber, prefix, existing = null) {
+  const itemId = referenceField(session, entry, "item", prefix);
+  if (itemId === undefined && existing === null) {
+    session.fail("INVALID_KEY_OR_REF", `The line ${quote(`${prefix}item`)} must carry an item reference.`, { errorPath: `${prefix}item` });
+  }
+  const resolvedItemId = itemId ?? existing.itemId;
+  const item = resolveItem(session, resolvedItemId, subsidiaryId, `${prefix}item`);
+  const quantity = numberField(session, entry, "quantity", { min: 0, max: 1000000, prefix });
+  const rate = numberField(session, entry, "rate", { min: 0, max: 100000000, prefix });
+  const description = stringField(session, entry, "description", 999, prefix);
+  const taxRate = numberField(session, entry, "taxRate", { min: 0, max: 0.25, prefix });
+  const finalQuantity = round4(quantity ?? existing?.quantity ?? 1);
+  const finalRate = round4(rate ?? existing?.rate ?? item.basePrice);
+  const finalTaxRate = taxRate ?? existing?.taxRate ?? taxRateFor(subsidiaryId);
+  const amount = round2(finalQuantity * finalRate);
+  const billed = existing === null ? 0 : existing.quantityBilled;
+  if (finalQuantity < billed) {
+    session.fail("USER_ERROR", `The quantity on line ${lineNumber} cannot be lower than the quantity already billed (${billed}).`, {
+      errorPath: `${prefix}quantity`,
+    });
+  }
+  return {
+    line: lineNumber,
+    itemId: resolvedItemId,
+    quantity: finalQuantity,
+    rate: finalRate,
+    amount,
+    description: description === undefined ? existing?.description ?? null : description,
+    taxRate: finalTaxRate,
+    taxAmount: round2(amount * finalTaxRate),
+    orderLine: existing === null ? null : existing.orderLine,
+    quantityBilled: billed,
+  };
+}
+
+export function totals(lines) {
+  const subtotal = round2(lines.reduce((sum, line) => sum + line.amount, 0));
+  const taxTotal = round2(lines.reduce((sum, line) => sum + line.taxAmount, 0));
+  return { subtotal, taxTotal, total: round2(subtotal + taxTotal) };
+}
+
+/** Billed value of an order, tax included, from each line's quantityBilled. */
+export function billedTotal(lines) {
+  return round2(lines.reduce((sum, line) => sum + round2(line.quantityBilled * line.rate) * (1 + line.taxRate), 0));
+}
+
+/** Sales-order status derived from billed quantities; a closed order stays closed. */
+export function orderStatus(order) {
+  if (order.status === "closed") return "closed";
+  const billedLines = order.lines.filter((line) => line.quantityBilled > 0);
+  if (billedLines.length === 0) return order.status === "pendingApproval" ? "pendingApproval" : "pendingFulfillment";
+  const fullyBilled = order.lines.every((line) => line.quantityBilled >= line.quantity);
+  if (fullyBilled) return "billed";
+  return "pendingBillingPartFulfilled";
+}
+
+export function invoiceStatus(invoice) {
+  if (invoice.status === "voided" || invoice.status === "pendingApproval") return invoice.status;
+  return round2(invoice.total - invoice.amountPaid) <= 0 && invoice.total > 0 ? "paidInFull" : "open";
+}
+
+const PREFIX_PATTERN = /^([A-Z]+)([0-9]+)$/;
+
+/** Next document number for a transaction namespace, continuing the seeded sequence. */
+export function nextTranId(session, namespace, prefix) {
+  let highest = 1000;
+  for (const row of session.rows(namespace)) {
+    const parts = PREFIX_PATTERN.exec(row.tranId);
+    if (parts === null || parts[1] !== prefix) continue;
+    const value = Number(parts[2]);
+    if (Number.isSafeInteger(value) && value > highest) highest = value;
+  }
+  return `${prefix}${highest + 1}`;
+}
+
+export function checkDuplicateTranId(session, namespaces, tranId, ownId) {
+  for (const namespace of namespaces) {
+    for (const row of session.rows(namespace)) {
+      if (row.id !== ownId && row.tranId === tranId) {
+        session.fail("USER_ERROR", `The document number ${quote(tranId)} is already in use by another transaction.`, {
+          errorPath: "tranId",
+        });
+      }
+    }
+  }
+}
+
+export function lineCounter(session, transactionId) {
+  const row = session.get("line-counters", transactionId);
+  return row === null || !Number.isInteger(row.nextLine) ? 1 : row.nextLine;
+}
+
+export function setLineCounter(session, transactionId, nextLine) {
+  session.put("line-counters", transactionId, { nextLine });
+}