@firedrill-tools/quickbooks 0.1.2

package/firedrill/tools/quickbooks/lib/payments.mjs

@@ -0,0 +1,200 @@
+// Payment entity (receive payment): rendering, create / update / void / delete, with invoice balances kept in sync.
+import { bumpToken } from "./access.mjs";
+import { USD, clip, fromCents, isId, toCents } from "./common.mjs";
+import { updateTarget } from "./customers.mjs";
+import { INACTIVE_DETAIL } from "./invoice-draft.mjs";
+import { refName } from "./items.mjs";
+import { checkKeys, has, isObject, optDate, optMoney, optRef, optString, own } from "./fields.mjs";
+
+const WRITABLE = new Set(["CustomerRef", "TotalAmt", "TxnDate", "PaymentRefNum", "PaymentMethodRef", "DepositToAccountRef", "PrivateNote", "Line", "ProcessPayment", "CurrencyRef", "ExchangeRate"]);
+const READONLY = new Set(["Id", "SyncToken", "sparse", "domain", "MetaData", "UnappliedAmt"]);
+
+export function renderPayment(s, row) {
+  const applied = row.Line.reduce((sum, line) => sum + (toCents(line.Amount) ?? 0), 0);
+  const out = {
+    CustomerRef: refName(s, "customers", row.CustomerRef, "DisplayName"),
+    DepositToAccountRef: refName(s, "accounts", row.DepositToAccountRef, "Name"),
+    TotalAmt: row.TotalAmt,
+    UnappliedAmt: fromCents((toCents(row.TotalAmt) ?? 0) - applied),
+    ProcessPayment: false,
+    domain: "QBO",
+    sparse: false,
+    Id: row.Id,
+    SyncToken: row.SyncToken,
+    MetaData: row.MetaData,
+    TxnDate: row.TxnDate,
+    CurrencyRef: USD,
+    Line: row.Line.map((line) => ({ Amount: line.Amount, LinkedTxn: line.LinkedTxn.map((txn) => ({ TxnId: txn.TxnId, TxnType: txn.TxnType })) })),
+  };
+  for (const key of ["PaymentRefNum", "PaymentMethodRef", "PrivateNote"]) if (row[key] !== null) out[key] = row[key];
+  return out;
+}
+
+function perInvoice(lines) {
+  const map = new Map();
+  for (const line of lines) map.set(line.LinkedTxn[0].TxnId, (map.get(line.LinkedTxn[0].TxnId) ?? 0) + (toCents(line.Amount) ?? 0));
+  return map;
+}
+
+/** Move invoice balances by (old − new) applied cents; one invoice.changed Update per touched invoice. */
+function rebalance(s, oldLines, newLines) {
+  const before = perInvoice(oldLines);
+  const after = perInvoice(newLines);
+  const ids = [...new Set([...before.keys(), ...after.keys()])].sort((a, b) => Number(a) - Number(b));
+  for (const id of ids) {
+    const delta = (before.get(id) ?? 0) - (after.get(id) ?? 0);
+    if (delta === 0) continue;
+    const invoice = s.get("invoices", id);
+    if (invoice === null) continue;
+    const balance = (toCents(invoice.Balance) ?? 0) + delta;
+    s.put("invoices", { ...invoice, Balance: fromCents(Math.max(0, balance)), SyncToken: bumpToken(invoice), MetaData: { ...invoice.MetaData, LastUpdatedTime: s.clock.meta } });
+    s.emit("invoice.changed", "Invoice", id, "Update");
+  }
+}
+
+function parsePaymentLines(s, raw, customerId, currentLines, totalCents) {
+  if (!Array.isArray(raw)) s.fail("BUSINESS_VALIDATION", "Invalid value for Line: expected an array", "Line");
+  if (raw.length > 250) s.fail("BUSINESS_VALIDATION", "A payment can be applied to at most 250 transactions.", "Line");
+  const previous = perInvoice(currentLines);
+  const seen = new Set();
+  const lines = [];
+  let applied = 0;
+  for (const [index, line] of raw.entries()) {
+    const at = `Line[${index}]`;
+    if (!isObject(line) || Object.keys(line).some((key) => key !== "Amount" && key !== "LinkedTxn" && key !== "LineEx")) s.fail("BUSINESS_VALIDATION", `Invalid value for ${at}: expected { Amount, LinkedTxn }`, at);
+    const amount = toCents(line.Amount);
+    if (amount === null || amount === 0) s.fail("BUSINESS_VALIDATION", "A payment line Amount must be greater than zero with at most two decimals.", `${at}.Amount`);
+    const links = own(line, "LinkedTxn");
+    if (!Array.isArray(links) || links.length !== 1 || !isObject(links[0])) s.fail("BUSINESS_VALIDATION", "Each payment line must link exactly one transaction.", `${at}.LinkedTxn`);
+    if (own(links[0], "TxnType") !== "Invoice") s.fail("BUSINESS_VALIDATION", "Only Invoice transactions can be linked to a payment in this company.", `${at}.LinkedTxn.TxnType`);
+    const rawId = own(links[0], "TxnId");
+    const txnId = typeof rawId === "string" || typeof rawId === "number" ? String(rawId) : "";
+    const invoice = isId(txnId) ? s.get("invoices", txnId) : null;
+    if (invoice === null) s.fail("INVALID_REFERENCE", `Invalid Reference Id : Invoice ${clip(txnId, 64)} linked to this payment does not exist`, `${at}.LinkedTxn.TxnId`);
+    if (seen.has(invoice.Id)) s.fail("BUSINESS_VALIDATION", `Invoice ${invoice.Id} is linked by more than one line of this payment.`, `${at}.LinkedTxn.TxnId`);
+    seen.add(invoice.Id);
+    if (invoice.CustomerRef.value !== customerId) s.fail("BUSINESS_VALIDATION", `Invoice ${invoice.Id} belongs to another customer.`, `${at}.LinkedTxn.TxnId`);
+    if (invoice.voided) s.fail("BUSINESS_VALIDATION", `Invoice ${invoice.Id} is voided and can't receive a payment.`, `${at}.LinkedTxn.TxnId`);
+    const open = (toCents(invoice.Balance) ?? 0) + (previous.get(invoice.Id) ?? 0);
+    if (amount > open) s.fail("BUSINESS_VALIDATION", `The payment amount applied to invoice ${invoice.Id} exceeds its open balance of ${fromCents(open).toFixed(2)}.`, `${at}.Amount`);
+    applied += amount;
+    lines.push({ Amount: fromCents(amount), LinkedTxn: [{ TxnId: invoice.Id, TxnType: "Invoice" }] });
+  }
+  if (applied > totalCents) s.fail("BUSINESS_VALIDATION", "The amount applied to transactions exceeds the payment amount (TotalAmt).", "Line");
+  return lines;
+}
+
+export function savePayment(s, body, current, sparse) {
+  if (!isObject(body)) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Payment object", "Payment");
+  checkKeys(s, body, WRITABLE, READONLY);
+  if (current !== null && current.voided) s.fail("BUSINESS_VALIDATION", "A voided payment can't be changed.", "Id");
+  const keep = (key) => current !== null && sparse && !has(body, key);
+  const next = current === null ? { voided: false } : { ...current };
+  if (!keep("CustomerRef")) {
+    const customerId = optRef(s, body, "CustomerRef");
+    if (typeof customerId !== "string") s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: CustomerRef", "CustomerRef");
+    const customer = s.get("customers", customerId);
+    if (customer === null) s.fail("INVALID_REFERENCE", `Invalid Reference Id : Customer assigned to this transaction does not exist: ${clip(customerId, 64)}`, "CustomerRef");
+    if (!customer.Active && (current === null || current.CustomerRef.value !== customer.Id)) s.fail("INVALID_REFERENCE", INACTIVE_DETAIL, "CustomerRef");
+    next.CustomerRef = { value: customer.Id, name: customer.DisplayName };
+  }
+  if (!keep("TotalAmt")) {
+    if (!has(body, "TotalAmt") || body.TotalAmt === null) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: TotalAmt", "TotalAmt");
+    next.TotalAmt = fromCents(optMoney(s, body, "TotalAmt"));
+  }
+  const txnDate = optDate(s, body, "TxnDate");
+  if (txnDate !== undefined && txnDate !== null) next.TxnDate = txnDate;
+  else if (current === null) next.TxnDate = s.clock.date;
+  for (const [key, max] of [["PaymentRefNum", 21], ["PrivateNote", 4000]]) {
+    const value = optString(s, body, key, max);
+    if (value !== undefined) next[key] = value;
+    else if (current === null || !sparse) next[key] = null;
+  }
+  const method = optRef(s, body, "PaymentMethodRef");
+  if (method !== undefined) next.PaymentMethodRef = method === null ? null : { value: method, name: typeof own(body.PaymentMethodRef, "name") === "string" ? body.PaymentMethodRef.name.slice(0, 100) : null };
+  else if (current === null || !sparse) next.PaymentMethodRef = null;
+  const depositId = optRef(s, body, "DepositToAccountRef");
+  if (depositId !== undefined || current === null || !sparse) {
+    const id = typeof depositId === "string" ? depositId : "4";
+    const account = s.get("accounts", id);
+    if (account === null || !account.Active || (account.AccountType !== "Bank" && account.AccountSubType !== "UndepositedFunds")) {
+      s.fail("INVALID_REFERENCE", `Invalid Reference Id : Deposit account ${clip(id, 64)} does not exist or is not a bank or Undeposited Funds account.`, "DepositToAccountRef");
+    }
+    next.DepositToAccountRef = { value: account.Id, name: account.Name };
+  }
+  if (has(body, "ProcessPayment") && body.ProcessPayment !== false) s.fail("BUSINESS_VALIDATION", "Payment processing (ProcessPayment) is not available in this company.", "ProcessPayment");
+  const currency = own(body, "CurrencyRef");
+  if (currency !== undefined && currency !== null && own(currency, "value") !== "USD") s.fail("BUSINESS_VALIDATION", "Multicurrency is not enabled for this company: CurrencyRef must be USD.", "CurrencyRef");
+  if (has(body, "ExchangeRate") && body.ExchangeRate !== 1) s.fail("BUSINESS_VALIDATION", "Multicurrency is not enabled for this company: ExchangeRate is not accepted.", "ExchangeRate");
+  const oldLines = current === null ? [] : current.Line;
+  if (!keep("Line") || !keep("CustomerRef") || !keep("TotalAmt")) {
+    const raw = keep("Line") ? oldLines : has(body, "Line") && body.Line !== null ? body.Line : [];
+    next.Line = parsePaymentLines(s, raw, next.CustomerRef.value, oldLines, toCents(next.TotalAmt));
+  }
+  if (current === null) {
+    next.Id = s.nextId("payment", "payments");
+    next.SyncToken = "0";
+    next.MetaData = { CreateTime: s.clock.meta, LastUpdatedTime: s.clock.meta };
+  } else {
+    next.SyncToken = bumpToken(current);
+    next.MetaData = { CreateTime: current.MetaData.CreateTime, LastUpdatedTime: s.clock.meta };
+  }
+  s.put("payments", next);
+  s.emit("payment.changed", "Payment", next.Id, current === null ? "Create" : "Update");
+  rebalance(s, oldLines, next.Line);
+  return { row: next, action: current === null ? "create" : "update" };
+}
+
+export function voidPayment(s, current) {
+  if (current.voided) s.fail("BUSINESS_VALIDATION", "This payment is already voided.", "Id");
+  const note = current.PrivateNote === null ? "Voided" : `Voided - ${current.PrivateNote}`.slice(0, 4000);
+  const next = { ...current, TotalAmt: 0, Line: [], voided: true, PrivateNote: note, SyncToken: bumpToken(current), MetaData: { ...current.MetaData, LastUpdatedTime: s.clock.meta } };
+  s.put("payments", next);
+  s.emit("payment.changed", "Payment", current.Id, "Void");
+  rebalance(s, current.Line, []);
+  return { row: next, action: "void" };
+}
+
+export function deletePayment(s, current) {
+  s.remove("payments", current.Id);
+  s.emit("payment.changed", "Payment", current.Id, "Delete");
+  rebalance(s, current.Line, []);
+  return { row: current, action: "delete" };
+}
+
+export function paymentsPost(s, input) {
+  const operation = input.operation;
+  if (operation === undefined || operation === "update") {
+    const body = input.body;
+    const hasId = has(body, "Id") && body.Id !== null;
+    if (operation === "update" && !hasId) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Id", "Id");
+    const current = hasId ? updateTarget(s, "payments", body, "Id") : null;
+    if (has(body, "sparse") && typeof body.sparse !== "boolean") s.fail("BUSINESS_VALIDATION", "Invalid value for sparse: expected true or false", "sparse");
+    return savePayment(s, body, current, current !== null && body.sparse === true);
+  }
+  if (operation === "void" || operation === "delete") {
+    if (!isObject(input.body)) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Payment object", "Payment");
+    const current = updateTarget(s, "payments", input.body, "Id");
+    return operation === "void" ? voidPayment(s, current) : deletePayment(s, current);
+  }
+  return s.fail("BUSINESS_VALIDATION", `Operation ${clip(String(operation), 32)} is not supported for Payment.`, "operation");
+}
+
+/** create_payment (MCP argument shape) → Payment body. */
+export function paymentBodyFromMcp(input) {
+  const body = { CustomerRef: { value: input.customer_ref }, TotalAmt: input.total_amt };
+  if (input.payment_method_ref !== undefined) body.PaymentMethodRef = { value: input.payment_method_ref };
+  if (input.deposit_to_account_ref !== undefined) body.DepositToAccountRef = { value: input.deposit_to_account_ref };
+  if (input.txn_date !== undefined) body.TxnDate = input.txn_date;
+  if (input.private_note !== undefined) body.PrivateNote = input.private_note;
+  if (input.payment_ref_num !== undefined) body.PaymentRefNum = input.payment_ref_num;
+  if (input.currency_ref !== undefined) body.CurrencyRef = { value: input.currency_ref };
+  if (input.exchange_rate !== undefined) body.ExchangeRate = input.exchange_rate;
+  if (Array.isArray(input.line)) {
+    body.Line = input.line.map((line) => ({
+      Amount: own(line, "amount"),
+      LinkedTxn: (Array.isArray(own(line, "linked_txn")) ? line.linked_txn : []).map((txn) => ({ TxnId: own(txn, "txn_id"), TxnType: own(txn, "txn_type") })),
+    }));
+  }
+  return body;
+}

package/firedrill/tools/quickbooks/lib/pdf.mjs

@@ -0,0 +1,96 @@
+// Deterministic one-page invoice PDF (PDF 1.4, Helvetica, ASCII text) and a hand-written base64 codec.
+// The document derives only from state, so repeated runs produce identical bytes.
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** base64 of a string whose char codes are all < 256. */
+export function base64FromBinary(binary) {
+  let out = "";
+  for (let i = 0; i < binary.length; i += 3) {
+    const a = binary.charCodeAt(i);
+    const b = i + 1 < binary.length ? binary.charCodeAt(i + 1) : 0;
+    const c = i + 2 < binary.length ? binary.charCodeAt(i + 2) : 0;
+    out += B64[a >> 2] + B64[((a & 3) << 4) | (b >> 4)];
+    out += i + 1 < binary.length ? B64[((b & 15) << 2) | (c >> 6)] : "=";
+    out += i + 2 < binary.length ? B64[c & 63] : "=";
+  }
+  return out;
+}
+
+/** Strict base64 → Uint8Array, or null when the text is not canonical base64. */
+export function bytesFromBase64(text) {
+  if (typeof text !== "string" || text.length % 4 !== 0) return null;
+  const pad = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+  const bytes = new Uint8Array((text.length / 4) * 3 - pad);
+  let k = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    const values = [];
+    for (let j = 0; j < 4; j += 1) {
+      const char = text[i + j];
+      if (char === "=" && i + 4 === text.length && j >= 4 - pad) values.push(0);
+      else {
+        const index = B64.indexOf(char);
+        if (index < 0) return null;
+        values.push(index);
+      }
+    }
+    const n = (values[0] << 18) | (values[1] << 12) | (values[2] << 6) | values[3];
+    if (k < bytes.length) bytes[k++] = (n >> 16) & 255;
+    if (k < bytes.length) bytes[k++] = (n >> 8) & 255;
+    if (k < bytes.length) bytes[k++] = n & 255;
+  }
+  return bytes;
+}
+
+function pdfText(value) {
+  let out = "";
+  for (const char of String(value)) {
+    const code = char.codePointAt(0);
+    if (code < 32 || code > 126) out += "?";
+    else if (char === "(" || char === ")" || char === "\\") out += `\\${char}`;
+    else out += char;
+  }
+  return out.length > 120 ? `${out.slice(0, 117)}...` : out;
+}
+
+const money = (value) => `$${Number(value).toFixed(2)}`;
+
+/** Text lines of the invoice document. */
+export function invoiceLines(company, invoice) {
+  const lines = [company.CompanyName, "INVOICE", `Invoice no. ${invoice.DocNumber}`, `Invoice date: ${invoice.TxnDate}`, `Due date: ${invoice.DueDate}`, `Bill to: ${invoice.CustomerRef.name ?? invoice.CustomerRef.value}`];
+  if (invoice.BillEmail) lines.push(`Email: ${invoice.BillEmail.Address}`);
+  lines.push("");
+  for (const line of invoice.Line) {
+    if (line.DetailType !== "SalesItemLineDetail") continue;
+    const detail = line.SalesItemLineDetail;
+    const label = line.Description ?? detail.ItemRef.name ?? detail.ItemRef.value;
+    lines.push(`${line.LineNum}. ${label}  ${detail.Qty} x ${money(detail.UnitPrice)} = ${money(line.Amount)}`);
+  }
+  lines.push("", `Total: ${money(invoice.TotalAmt)}`, `Balance due: ${money(invoice.Balance)}`);
+  if (invoice.CustomerMemo) lines.push(`Message: ${invoice.CustomerMemo.value}`);
+  return lines;
+}
+
+/** Complete PDF file as a binary (Latin-1) string. */
+export function invoicePdf(company, invoice) {
+  const text = invoiceLines(company, invoice).slice(0, 60);
+  const stream = `BT /F1 10 Tf 13 TL 50 790 Td ${text.map((line) => `(${pdfText(line)}) Tj T*`).join(" ")} ET`;
+  const objects = [
+    "<< /Type /Catalog /Pages 2 0 R >>",
+    "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+    "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 842] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>",
+    "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    `<< /Length ${stream.length} >>\nstream\n${stream}\nendstream`,
+  ];
+  let file = "%PDF-1.4\n";
+  const offsets = [];
+  objects.forEach((body, index) => {
+    offsets.push(file.length);
+    file += `${index + 1} 0 obj\n${body}\nendobj\n`;
+  });
+  const xref = file.length;
+  file += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
+  for (const offset of offsets) file += `${String(offset).padStart(10, "0")} 00000 n \n`;
+  file += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`;
+  return file;
+}

package/firedrill/tools/quickbooks/lib/query-eval.mjs

@@ -0,0 +1,178 @@
+// Query evaluation over package state: entity metadata (filterable / sortable properties), typed comparisons,
+// QuickBooks' Active default, ordering, 1-based paging and a response byte budget. Shared by query.run and the
+// MCP search operations (criteria compile to the same AST).
+import { dayNumber, instantOf, utf8Bytes } from "./common.mjs";
+import { renderCustomer } from "./customers.mjs";
+import { renderInvoice } from "./invoices.mjs";
+import { renderItem } from "./items.mjs";
+import { compileLike, likeMatches } from "./like.mjs";
+import { renderPayment } from "./payments.mjs";
+import { renderAccount, renderCompany } from "./views.mjs";
+
+const META_TIMES = [["MetaData.CreateTime", "datetime"], ["MetaData.LastUpdatedTime", "datetime"]];
+const ENTITIES = new Map([
+  ["customer", { name: "Customer", namespace: "customers", capability: "customers.read", activeDefault: true, render: renderCustomer, props: new Map([["Id", "id"], ["DisplayName", "string"], ["GivenName", "string"], ["FamilyName", "string"], ["CompanyName", "string"], ["PrimaryEmailAddr", "email"], ["Active", "bool"], ["Balance", "number"], ...META_TIMES]) }],
+  ["item", { name: "Item", namespace: "items", capability: "items.read", activeDefault: true, render: renderItem, props: new Map([["Id", "id"], ["Name", "string"], ["Active", "bool"], ["Type", "string"], ["Sku", "string"], ...META_TIMES]) }],
+  ["invoice", { name: "Invoice", namespace: "invoices", capability: "invoices.read", activeDefault: false, render: renderInvoice, props: new Map([["Id", "id"], ["DocNumber", "string"], ["TxnDate", "date"], ["DueDate", "date"], ["CustomerRef", "ref"], ["Balance", "number"], ["TotalAmt", "number"], ["EmailStatus", "string"], ...META_TIMES]) }],
+  ["payment", { name: "Payment", namespace: "payments", capability: "payments.read", activeDefault: false, render: renderPayment, props: new Map([["Id", "id"], ["TxnDate", "date"], ["CustomerRef", "ref"], ["TotalAmt", "number"], ["PaymentRefNum", "string"], ...META_TIMES]) }],
+  ["account", { name: "Account", namespace: "accounts", capability: "accounts.read", activeDefault: true, render: renderAccount, props: new Map([["Id", "id"], ["Name", "string"], ["AccountType", "string"], ["Classification", "string"], ["Active", "bool"], ["CurrentBalance", "number"], ...META_TIMES]) }],
+  ["companyinfo", { name: "CompanyInfo", namespace: null, capability: "company.read", activeDefault: false, render: null, props: new Map([["Id", "id"], ...META_TIMES]) }],
+]);
+
+// Encoded-page budget (the framework refuses HTTP responses over 1 MiB). A stored invoice is bounded by
+// INVOICE_DESCRIPTION_BYTES (invoice-draft.mjs) so that any single rendered row plus the QueryResponse envelope
+// fits under this budget: the first row of a page is therefore always returned, and a page stops before the row
+// that would pass the budget (maxResults = rows returned, so STARTPOSITION + maxResults is the real next position).
+export const RESPONSE_BYTE_BUDGET = 900_000;
+export { utf8Bytes };
+
+export function entityMeta(s, name) {
+  const meta = typeof name === "string" ? ENTITIES.get(name.toLowerCase()) : undefined;
+  if (meta === undefined) s.fail("QUERY_VALIDATION_ERROR", `QueryValidationError: Invalid entity name: ${String(name).slice(0, 64)}`, "query");
+  return meta;
+}
+
+function invalidProp(s, prop, why = "is not queryable") {
+  return s.fail("QUERY_VALIDATION_ERROR", `QueryValidationError: property '${String(prop).slice(0, 64)}' ${why}`, "query");
+}
+
+/** Typed value of a rendered entity property (null when absent). */
+function valueOf(entity, prop, type) {
+  if (prop === "MetaData.CreateTime" || prop === "MetaData.LastUpdatedTime") {
+    const text = entity.MetaData?.[prop === "MetaData.CreateTime" ? "CreateTime" : "LastUpdatedTime"];
+    return typeof text === "string" ? instantOf(text) : null;
+  }
+  if (!Object.hasOwn(entity, prop)) return null;
+  const raw = entity[prop];
+  if (raw === null || raw === undefined) return null;
+  switch (type) {
+    case "id": return Number(raw);
+    case "email": return typeof raw.Address === "string" ? raw.Address.toLowerCase() : null;
+    case "ref": return typeof raw.value === "string" ? raw.value : null;
+    case "string": return typeof raw === "string" ? raw.toLowerCase() : null;
+    case "date": return dayNumber(raw);
+    default: return raw;
+  }
+}
+
+/** Literal → comparable value for the property type, or a QUERY_VALIDATION_ERROR. */
+function coerce(s, prop, type, literal) {
+  const bad = () => s.fail("QUERY_VALIDATION_ERROR", `QueryValidationError: value ${JSON.stringify(String(literal.value)).slice(0, 80)} is not valid for property '${prop}'`, "query");
+  const text = literal.kind === "bool" ? null : String(literal.value);
+  switch (type) {
+    case "id": {
+      if (text === null || text.length === 0 || text.length > 10) return bad();
+      for (let i = 0; i < text.length; i += 1) if (text.charCodeAt(i) < 48 || text.charCodeAt(i) > 57) return bad();
+      return Number(text);
+    }
+    case "string":
+    case "email":
+      return text === null ? bad() : text.toLowerCase();
+    case "ref":
+      return text === null ? bad() : text;
+    case "number": {
+      const n = text === null || text.trim().length === 0 || text.length > 32 ? Number.NaN : Number(text);
+      return Number.isFinite(n) ? n : bad();
+    }
+    case "bool":
+      if (literal.kind === "bool") return literal.value;
+      if (text === "true" || text === "false") return text === "true";
+      return bad();
+    case "date": {
+      const day = text === null ? null : dayNumber(text.slice(0, 10));
+      return day === null ? bad() : day;
+    }
+    default: {
+      const instant = text === null ? null : instantOf(text);
+      return instant === null ? bad() : instant;
+    }
+  }
+}
+
+function compileCondition(s, meta, condition) {
+  const type = meta.props.get(condition.prop);
+  if (type === undefined) invalidProp(s, condition.prop);
+  if (condition.op === "like") {
+    if (type !== "string" && type !== "email") invalidProp(s, condition.prop, "does not support LIKE");
+    const pattern = coerce(s, condition.prop, type, condition.values[0]);
+    const compiled = compileLike(pattern);
+    return (entity) => {
+      const value = valueOf(entity, condition.prop, type);
+      return typeof value === "string" && likeMatches(compiled, value);
+    };
+  }
+  const values = condition.values.map((literal) => coerce(s, condition.prop, type, literal));
+  return (entity) => {
+    const value = valueOf(entity, condition.prop, type);
+    if (value === null) return false;
+    switch (condition.op) {
+      case "in": return values.includes(value);
+      case "=": return value === values[0];
+      case "<": return value < values[0];
+      case ">": return value > values[0];
+      case "<=": return value <= values[0];
+      default: return value >= values[0];
+    }
+  };
+}
+
+function compare(a, b) {
+  if (a === b) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  return a < b ? -1 : 1;
+}
+
+/** Evaluate an AST. `all` ignores start/max (fetchAll). Returns { meta, entities (page), total }. */
+export function evaluate(s, ast, { all = false } = {}) {
+  const meta = entityMeta(s, ast.entity);
+  s.permit(meta.capability);
+  const tests = ast.where.map((condition) => compileCondition(s, meta, condition));
+  const order = ast.order.map(({ prop, dir }) => {
+    const type = meta.props.get(prop);
+    if (type === undefined) invalidProp(s, prop, "is not sortable");
+    return { prop, type, sign: dir === "desc" ? -1 : 1 };
+  });
+  const activeDefault = meta.activeDefault && !ast.where.some((condition) => condition.prop === "Active");
+  const source = meta.namespace === null ? [s.company] : s.rows(meta.namespace);
+  const matched = [];
+  for (const row of source) {
+    const entity = meta.namespace === null ? renderCompany(row) : meta.render(s, row);
+    if (activeDefault && entity.Active !== true) continue;
+    if (tests.every((test) => test(entity))) matched.push(entity);
+  }
+  matched.sort((a, b) => {
+    for (const key of order) {
+      const result = compare(valueOf(a, key.prop, key.type), valueOf(b, key.prop, key.type));
+      if (result !== 0) return result * key.sign;
+    }
+    return Number(a.Id) - Number(b.Id);
+  });
+  if (ast.select.kind === "count") return { meta, entities: [], total: matched.length };
+  const page = all ? matched : matched.slice(ast.start - 1, ast.start - 1 + ast.max);
+  const entities = [];
+  let bytes = 0;
+  for (const entity of page) {
+    const projected = ast.select.kind === "fields" ? project(entity, ast.select.fields) : entity;
+    const size = utf8Bytes(JSON.stringify(projected)) + 1;
+    if (size > RESPONSE_BYTE_BUDGET) {
+      // Last line of defence: a single row that can never fit a response answers the declared error instead of an opaque
+      // framework 500 (invoice-draft.mjs bounds stored invoices so this is unreachable through the public write surface).
+      s.fail("STATE_BOUND_EXCEEDED", `Entity ${projected.Id ?? ""} renders to ${size} bytes, over the response bound of ${RESPONSE_BYTE_BUDGET}.`, "query");
+    }
+    if (entities.length > 0 && bytes + size > RESPONSE_BYTE_BUDGET) {
+      // fetchAll has no next position to hand back; a paged query returns the rows that fit.
+      if (all) s.fail("STATE_BOUND_EXCEEDED", "Response too large; page with limit and offset instead of fetchAll.", "query");
+      break;
+    }
+    bytes += size;
+    entities.push(projected);
+  }
+  return { meta, entities, total: matched.length };
+}
+
+function project(entity, fields) {
+  const out = { Id: entity.Id, SyncToken: entity.SyncToken, domain: "QBO", sparse: true };
+  for (const field of fields) if (Object.hasOwn(entity, field)) out[field] = entity[field];
+  return out;
+}