@diy-accounting-uk/diya-gl 1.2.65 → 1.2.66

package/dist/app/data/releases.json

@@ -1923,6 +1923,32 @@
           "scorecard": "101608 passed, 0 warnings, 0 failed"
         }
       }
+    },
+    {
+      "tag": "diya-gl-v1.2.65",
+      "date": "2026-10-31",
+      "formatVersion": "diya-gl/2",
+      "engineVersion": "1.2.65+abe8b1846",
+      "taxDataHash": "51bdff60e993",
+      "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
+      "templates": {
+        "bst": {
+          "hash": "0d003e10e00c",
+          "scorecard": "812 passed, 0 warnings, 0 failed"
+        },
+        "taxi": {
+          "hash": "1ff69654d64d",
+          "scorecard": "700 passed, 0 warnings, 0 failed"
+        },
+        "se": {
+          "hash": "064605ae76ed",
+          "scorecard": "8015 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "b90d8b0f54a0",
+          "scorecard": "101608 passed, 0 warnings, 0 failed"
+        }
+      }
     }
   ]
 }

package/dist/app/lib/product-sheets/format.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+
+import { canonicalForUnit } from "../canonical-report-value.js";
+
+export function fmt(v, unit = "money") {
+  if (v === null || v === undefined || v === "" || v === " ") return "—";
+  if (typeof v === "number") {
+    const canonical = Number(canonicalForUnit(v, unit));
+    // A nil that arrived by negation carries a sign bit and prints as "-0",
+    // which reads as a defect in a statement.
+    return (canonical === 0 ? 0 : canonical).toLocaleString("en-GB", { minimumFractionDigits: 0, maximumFractionDigits: 2 });
+  }
+  return String(v);
+}

package/dist/app/lib/product-sheets/payslips.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+
+import { toExcelSerial } from "../spreadsheet-runner.js";
+import { parseDate } from "../scenario-loader.js";
+import {
+  PAYE_DUE_DAY,
+  PAYE_SCHEDULE_FIRST_ROW,
+  PAYE_SCHEDULE_MONTH_TABS,
+  PAYSLIPS_EMPLOYEE_BASE_ROWS,
+  PAYSLIPS_EMPLOYEE_START_DATE_OFFSET,
+  PAYSLIPS_ENTRY_COLUMNS,
+  payeTaxMonthDates,
+  payslipsMonthEntryRows,
+  payslipsStartDate,
+  payslipsWagesPaidCell,
+} from "../payslips-layout.js";
+
+// Payslips.xlsx Jul (sheet5.xml) and Aug (sheet6.xml) shipped with 35 dead
+// #REF! cells: Jul!F11:F15 lost the weekly-block pay-date reference
+// (Employee!F$24/F$26 compared against E$9), Jul!T41 carried a stray
+// formula where every other month has a literal 0, and Aug!H11:M15 (K only
+// on rows 12-15) lost the previous month's row-41 brought-forward
+// reference. additionalReads never read either tab directly -- only the
+// Payment/Admin aggregates -- so none of it ever surfaced. Every fixture's
+// employees pay monthly, so the weekly-block gate (Employee!D$28 etc = "m")
+// and the carry-forward gate (Aug!T$9 = "Y") are never true: both blocks
+// always resolve to their blank/nil branch regardless of what the broken
+// formula pointed at, which is exactly why the #REF!s shipped unnoticed.
+export const PAYSLIPS_WEEKLY_ROWS = [11, 12, 13, 14, 15];
+export const PAYSLIPS_JUL_DEAD_CELLS = [...PAYSLIPS_WEEKLY_ROWS.map((row) => `F${row}`), "T41"];
+export const PAYSLIPS_AUG_BROUGHT_FORWARD_CELLS = PAYSLIPS_WEEKLY_ROWS.flatMap((row) => {
+  const cells = ["H", "I", "J", "L", "M"].map((col) => `${col}${row}`);
+  if (row >= 12) cells.push(`K${row}`);
+  return cells;
+});
+
+// The cells Payslips.xlsx cellWrites populates for a month's payroll, one
+// employee a row down the month's own monthly block, plus the wages-paid date
+// the block is dated from.
+export const payslipsMonthEntryCells = (monthIndex) => [
+  payslipsWagesPaidCell(monthIndex),
+  ...payslipsMonthEntryRows(monthIndex).flatMap((row) => Object.values(PAYSLIPS_ENTRY_COLUMNS).map((col) => `${col}${row}`)),
+];
+
+// The Employee sheet of Payslips.xlsx: the business details and up to five
+// employee blocks. payrollStart is the payroll year the package's calendar runs
+// on, payrollOpened the date the payroll record opened.
+export function writePayslipsEmployee(scenario, { payrollStart, payrollOpened, shiftDate }) {
+  // Employee blocks start at rows 13, 39, 65, 91, 117 (26-row intervals)
+  const EMP_BASE_ROWS = PAYSLIPS_EMPLOYEE_BASE_ROWS;
+  const emp = {};
+
+  // Business details in Payslips Employee sheet
+  const biz = scenario.business || {};
+  if (biz.name) emp.D5 = biz.name;
+  if (biz.address) emp.D6 = biz.address;
+  if (biz.town) emp.D7 = biz.town;
+  if (biz.postcode) emp.D9 = biz.postcode;
+
+  for (let i = 0; i < Math.min(scenario.employees.length, 5); i++) {
+    const e = scenario.employees[i];
+    const base = EMP_BASE_ROWS[i];
+    if (e.name) {
+      const parts = e.name.split(" ");
+      emp[`D${base + 2}`] = parts.slice(-1)[0]; // surname
+      emp[`D${base + 3}`] = parts.slice(0, -1).join(" "); // forename(s)
+    }
+    if (e.niNumber) emp[`M${base + 2}`] = e.niNumber;
+    // The date the employee joined, read against the payroll year this
+    // package's calendar runs on. Without it the employee's line on every
+    // month tab stays blank and the printed payslip prints no figures.
+    if (e.startDate && payrollStart) {
+      const joined = parseDate(e.startDate);
+      const onSheet = payslipsStartDate(joined, payrollOpened, shiftDate(joined), payrollStart);
+      emp[`D${base + PAYSLIPS_EMPLOYEE_START_DATE_OFFSET}`] = toExcelSerial(
+        onSheet.getUTCFullYear(),
+        onSheet.getUTCMonth() + 1,
+        onSheet.getUTCDate(),
+      );
+    }
+    emp[`D${base + 15}`] = e.payFrequency === "weekly" ? "W" : "M";
+    // The payroll number, not the scenario's own employee id. The printed
+    // payslip adds this cell to its block's start row to find the
+    // employee's line on the month tab, so a name in it takes the whole
+    // page's arithmetic with it.
+    emp[`D${base + 16}`] = i + 1;
+    emp[`D${base + 17}`] = e.isDirector ? "D" : e.niCategory || "A";
+  }
+  return emp;
+}
+
+// The PAYE remittance schedule: one row per tax month, each with the month it
+// ends and the day the payment falls due.
+export function checkPayeSchedule({ check, num }, paymentSchedule, payrollYearOpens) {
+  if (paymentSchedule && payrollYearOpens) {
+    const asSerial = (day) => toExcelSerial(day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate());
+    PAYE_SCHEDULE_MONTH_TABS.forEach((tab, taxMonth) => {
+      const row = PAYE_SCHEDULE_FIRST_ROW + taxMonth;
+      const { ends, due } = payeTaxMonthDates(payrollYearOpens, taxMonth);
+      check(
+        `Payslips!Payment B${row} tax month ${taxMonth + 1} ends on the last day of ${tab}`,
+        num(paymentSchedule[`B${row}`]),
+        asSerial(ends),
+        0,
+      );
+      check(
+        `Payslips!Payment C${row} tax month ${taxMonth + 1} is due on the ${PAYE_DUE_DAY}th after it`,
+        num(paymentSchedule[`C${row}`]),
+        asSerial(due),
+        0,
+      );
+    });
+  }
+}

package/dist/app/lib/product-sheets/salesinvoice.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+
+// ── Sales invoice sample line (Salesinvoice.xlsx) ───────────────────────────
+// The customer-facing invoice template has no external link into the rest of
+// the book, so its own VAT rate is proved directly: the generator now writes
+// the tax year's standard rate into Product Details!D2:D99 (generator.js),
+// and this checks one sample invoice line, anchored to the fixture's own
+// first sale, computes the right net, VAT and gross from it. Row 2 of
+// Product Details already ships the template's own placeholder product code
+// (A2 = 1001); this only sets its selling price. Business Details!B11 is the
+// VAT registration number the invoice template itself gates its per-row VAT
+// lookup on (verified against the XML: Invoice Template!N38 reads
+// 'Product Details'!D:D only when O8, which reads 'Business Details'!B11, is
+// not blank) -- an unregistered business is left untouched, the same as the
+// template's own guidance for it. The invoice also carries a carriage charge
+// (Invoice Database!E, the "Carriage Charge" column), which the template
+// taxes separately from the product lines in Invoice Template!P62. That term
+// used to read a literal 0.2; it now reads 'Product Details'!$D$2, the same
+// cell every row of D2:D99 carries the tax year's rate into, so carriage is
+// taxed at the written rate like every other line.
+export const SALESINVOICE_VAT_REG_CELL = "B11";
+// The same sheet's "Telephone" box, the entry cell beside its A8 label.
+export const SALESINVOICE_TELEPHONE_CELL = "B8";
+export const SALESINVOICE_SAMPLE_PRODUCT_CODE = 1001;
+export const SALESINVOICE_SAMPLE_PRODUCT_ROW = 2;
+export const SALESINVOICE_SAMPLE_CARRIAGE_CHARGE = 37.5;
+export const SALESINVOICE_PRODUCT_DETAILS_COLUMNS = { code: "A", price: "C", vatRate: "D" };
+export const SALESINVOICE_INVOICE_DATABASE_COLUMNS = {
+  activate: "A",
+  invoiceNumber: "B",
+  carriage: "E",
+  productCode1: "F",
+  quantity1: "G",
+};
+export const SALESINVOICE_INVOICE_TEMPLATE_CELLS = { netTotal: "P58", carriageNet: "P60", vatTotal: "P62", grossTotal: "P64" };
+export const SALESINVOICE_LINE1_CELLS = { productCode: "C38", unitPrice: "J38", quantity: "L38", lineNet: "P38", lineVat: "V38" };
+
+// The Salesinvoice.xlsx writes for a scenario: the telephone number, and one
+// sample invoice line for a VAT-registered business.
+export function writeSalesinvoice(scenario, rate) {
+  // Anchored to the fixture's own first sale so the customer-facing invoice
+  // total and VAT can be checked against a real figure (see checkSalesinvoice).
+  const salesinvoiceWrites = {};
+  // The invoice's own letterhead carries the business telephone number,
+  // which no other sheet in these workbooks has a box for.
+  if (scenario.business?.phone) salesinvoiceWrites["Business Details"] = { [SALESINVOICE_TELEPHONE_CELL]: scenario.business.phone };
+  const firstInvoiceSale = Object.values(scenario.sales || {}).flat()[0];
+  if (rate > 0 && scenario.business?.vat_number && firstInvoiceSale) {
+    salesinvoiceWrites["Business Details"] = {
+      ...salesinvoiceWrites["Business Details"],
+      [SALESINVOICE_VAT_REG_CELL]: scenario.business.vat_number,
+    };
+    salesinvoiceWrites["Invoice Database"] = {
+      [`${SALESINVOICE_INVOICE_DATABASE_COLUMNS.activate}2`]: 1,
+      [`${SALESINVOICE_INVOICE_DATABASE_COLUMNS.invoiceNumber}2`]: 1,
+      [`${SALESINVOICE_INVOICE_DATABASE_COLUMNS.carriage}2`]: SALESINVOICE_SAMPLE_CARRIAGE_CHARGE,
+      [`${SALESINVOICE_INVOICE_DATABASE_COLUMNS.productCode1}2`]: SALESINVOICE_SAMPLE_PRODUCT_CODE,
+      [`${SALESINVOICE_INVOICE_DATABASE_COLUMNS.quantity1}2`]: 1,
+    };
+    salesinvoiceWrites["Product Details"] = {
+      [`${SALESINVOICE_PRODUCT_DETAILS_COLUMNS.price}${SALESINVOICE_SAMPLE_PRODUCT_ROW}`]: firstInvoiceSale.amount,
+    };
+  }
+  return salesinvoiceWrites;
+}
+
+// The customer-facing invoice against the tax year's own VAT rate.
+export function checkSalesinvoice({ check, num }, results, expected, taxData, rate) {
+  // Salesinvoice.xlsx carries no external link to the rest of the book, so a
+  // wrong figure here never reaches the accounts -- it reaches the
+  // customer's customer. The generator writes the tax year's standard rate
+  // into Product Details!D2:D99 (generator.js); this checks the rate landed
+  // and that the one sample invoice line, plus the invoice's carriage
+  // charge, both compute their VAT correctly from it, hand-computed from the
+  // fixture's own first sale and the sample carriage charge.
+  const invoiceProductDetails = results["Salesinvoice.xlsx!Product Details"];
+  const invoiceTemplate = results["Salesinvoice.xlsx!Invoice Template"];
+  if (invoiceProductDetails && invoiceTemplate && taxData) {
+    const standardRatePercent = Math.round(taxData.vat.standard_rate * 100);
+    check(
+      "Salesinvoice Product Details: VAT Rate = the tax year's standard rate",
+      num(invoiceProductDetails[`${SALESINVOICE_PRODUCT_DETAILS_COLUMNS.vatRate}${SALESINVOICE_SAMPLE_PRODUCT_ROW}`]),
+      standardRatePercent,
+      0,
+    );
+
+    // cellWrites only puts the sample invoice line and carriage charge on the
+    // sheet for a VAT-registered business (rate > 0 and a VAT number) --
+    // otherwise Salesinvoice.xlsx keeps its blank template state, and these
+    // five figures would have nothing to compare against.
+    const firstInvoiceSale = Object.values(expected.sales || {}).flat()[0];
+    if (rate > 0 && expected.business?.vat_number && firstInvoiceSale) {
+      const expectedNet = firstInvoiceSale.amount;
+      const expectedLineVat = (expectedNet * standardRatePercent) / 100;
+      const expectedCarriageVat = (SALESINVOICE_SAMPLE_CARRIAGE_CHARGE * standardRatePercent) / 100;
+      const expectedVatTotal = expectedLineVat + expectedCarriageVat;
+      check(
+        "Salesinvoice: line VAT = price x quantity x the tax year's standard rate",
+        num(invoiceTemplate[SALESINVOICE_LINE1_CELLS.lineVat]),
+        expectedLineVat,
+        0.01,
+      );
+      check(
+        "Salesinvoice: net total = the invoice's one line",
+        num(invoiceTemplate[SALESINVOICE_INVOICE_TEMPLATE_CELLS.netTotal]),
+        expectedNet,
+        0.01,
+      );
+      check(
+        "Salesinvoice: carriage charge lands on the invoice",
+        num(invoiceTemplate[SALESINVOICE_INVOICE_TEMPLATE_CELLS.carriageNet]),
+        SALESINVOICE_SAMPLE_CARRIAGE_CHARGE,
+        0.01,
+      );
+      check(
+        "Salesinvoice: VAT total = line VAT plus carriage VAT at the tax year's standard rate",
+        num(invoiceTemplate[SALESINVOICE_INVOICE_TEMPLATE_CELLS.vatTotal]),
+        expectedVatTotal,
+        0.01,
+      );
+      check(
+        "Salesinvoice: amount payable = net plus carriage plus VAT",
+        num(invoiceTemplate[SALESINVOICE_INVOICE_TEMPLATE_CELLS.grossTotal]),
+        expectedNet + SALESINVOICE_SAMPLE_CARRIAGE_CHARGE + expectedVatTotal,
+        0.01,
+      );
+    }
+  }
+}

package/dist/app/lib/product-sheets/serial-dates.js

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+
+// The date an Excel serial stands for.
+export function excelSerialToUtcDate(serial) {
+  const epoch = Date.UTC(1899, 11, 30);
+  return new Date(epoch + Math.round(serial) * 24 * 60 * 60 * 1000);
+}
+
+export function formatSerialDate(serial) {
+  return excelSerialToUtcDate(serial).toLocaleDateString("en-GB", { timeZone: "UTC", day: "numeric", month: "long", year: "numeric" });
+}
+
+// The " (period ending d Month yyyy)" a VAT return line carries, or nothing
+// at all when the form has no date on it.
+export function periodEnding(serial) {
+  return serial ? ` (period ending ${formatSerialDate(serial)})` : "";
+}

package/dist/app/lib/product-sheets/vat-chain.js

@@ -0,0 +1,342 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+
+import { toExcelSerial } from "../spreadsheet-runner.js";
+import { parseDate } from "../scenario-loader.js";
+import { vatCycleRows, vatReturnCoverage } from "../report-generator.js";
+import { fmt } from "./format.js";
+import { formatSerialDate, periodEnding } from "./serial-dates.js";
+import { netOfVat } from "./vat-rate.js";
+
+// ── Vatinterface layout ────────────────────────────────────────────────────
+// One row per VAT period, in date order. Rows 6-17 are the twelve accounting
+// months in period order. Rows 4 and 5 are the two VAT periods before the
+// accounting year, rows 18 to 20 the three after it; each is fed by its own
+// S/P entry sheet rather than by a month tab. Column B is the period end date
+// every VATQtr sheet looks up on, C the payment due date, D/F the period's
+// sales net and output VAT, H/J its purchases net and input VAT, and E/G/I/K
+// the rolling three-row sums the VAT boxes read. M carries the flat-rate flag
+// box 6 switches on.
+export const VATINTERFACE_ROWS = { first: 4, last: 20, firstMonth: 6 };
+
+// Straddling VAT period name to the Vatinterface row it feeds, and to the
+// pair of entry sheets it is entered on (S<period> and P<period>).
+export const STRADDLING_PERIOD_ROWS = { "02Y1": 4, "03Y1": 5, "04Y2": 18, "05Y2": 19, "06Y2": 20 };
+
+// A business that is not registered for VAT turns the rate off on the first
+// month's Sales tab, and the rest of the book follows that cell.
+export function writeVatRateCell(salesWrites, firstTab, rateCell, rate) {
+  if (!salesWrites[firstTab]) salesWrites[firstTab] = {};
+  salesWrites[firstTab][rateCell] = rate * 100;
+}
+
+// layout names what differs between the products' VAT workbooks:
+//   workbook     the VAT workbook's file name
+//   monthTabs    (results) => the month tab names, in accounting-year order
+//   salesNetCell, salesVatCell, purchasesNetCell, purchasesVatCell
+//                the cells of a month tab that hold its net and VAT totals
+
+// Straddling VAT periods: entries on the S<period> and P<period> entry sheets.
+export function writeStraddlingPeriod(vatReturnWrites, entries, sheetPrefix, nameField, columns, { workbook, shiftDate }) {
+  for (const entry of entries) {
+    if (!STRADDLING_PERIOD_ROWS[entry.period]) {
+      throw new Error(`Straddling VAT entry names period "${entry.period}", which ${workbook} has no sheet for`);
+    }
+    const sheetName = `${sheetPrefix}${entry.period}`;
+    if (!vatReturnWrites[sheetName]) vatReturnWrites[sheetName] = {};
+    const sheet = vatReturnWrites[sheetName];
+    // Matching the whole reference rather than its first letter keeps a
+    // write further right (AD, say) out of the count of rows already there.
+    const amountColumnKey = new RegExp(`^${columns.amount}\\d+$`);
+    const entryRow = Object.keys(sheet).filter((k) => amountColumnKey.test(k)).length + 5;
+    const d = shiftDate(parseDate(entry.date));
+    sheet[`${columns.date}${entryRow}`] = toExcelSerial(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+    if (entry[nameField]) sheet[`${columns.name}${entryRow}`] = entry[nameField];
+    if (entry.invoice) sheet[`${columns.invoice}${entryRow}`] = entry.invoice;
+    if (entry.description && columns.description) sheet[`${columns.description}${entryRow}`] = entry.description;
+    sheet[`${columns.amount}${entryRow}`] = entry.amount;
+  }
+}
+
+// The VAT the books actually charged, taken from the month tabs and from the
+// return itself. Every other statement in this report is stated net, so a
+// registered trader and an unregistered one carrying the same trade read
+// identically without it.
+export function vatSection(results, layout) {
+  const { workbook, salesVatCell, salesNetCell, purchasesVatCell, purchasesNetCell } = layout;
+  const tabs = layout.monthTabs(results).filter((tab) => results[`Sales.xlsx!${tab}`] || results[`Purchases.xlsx!${tab}`]);
+  const months = tabs.map((tab) => [results[`Sales.xlsx!${tab}`], results[`Purchases.xlsx!${tab}`]]);
+  if (months.length === 0) return null;
+  const monthCells = (file, ...refs) => tabs.flatMap((tab) => refs.map((ref) => `${file}!${tab}!${ref}`));
+
+  const num = (v) => (typeof v === "number" ? v : 0);
+  const sum = (side, cell) => months.reduce((total, pair) => total + num(pair[side]?.[cell]), 0);
+  const salesVat = sum(0, salesVatCell);
+  const salesNet = sum(0, salesNetCell);
+  const purchasesVat = sum(1, purchasesVatCell);
+  const purchasesNet = sum(1, purchasesNetCell);
+
+  const rows = [
+    {
+      label: "Sales invoiced including VAT",
+      value: fmt(salesNet + salesVat),
+      indent: 1,
+      cells: monthCells("Sales.xlsx", salesVatCell, salesNetCell),
+    },
+    { label: "VAT charged on sales", value: fmt(salesVat), indent: 1, cells: monthCells("Sales.xlsx", salesVatCell) },
+    { label: "Sales net of VAT", value: fmt(salesNet), indent: 1, cells: monthCells("Sales.xlsx", salesNetCell) },
+    {
+      label: "Purchases invoiced including VAT",
+      value: fmt(purchasesNet + purchasesVat),
+      indent: 1,
+      cells: monthCells("Purchases.xlsx", purchasesVatCell, purchasesNetCell),
+    },
+    { label: "VAT reclaimed on purchases", value: fmt(purchasesVat), indent: 1, cells: monthCells("Purchases.xlsx", purchasesVatCell) },
+    { label: "Purchases net of VAT", value: fmt(purchasesNet), indent: 1, cells: monthCells("Purchases.xlsx", purchasesNetCell) },
+    {
+      label: "**VAT due for the year**",
+      value: fmt(salesVat - purchasesVat),
+      indent: 0,
+      cells: [...monthCells("Sales.xlsx", salesVatCell), ...monthCells("Purchases.xlsx", purchasesVatCell)],
+    },
+  ];
+  // The package ships five return forms: four quarters from the VAT start
+  // month and one more, for a business whose quarter stagger does not line up
+  // with those four. Printing four left the fifth out of the report
+  // altogether. Each form carries the period it was filled in for, and the
+  // cycle rows above the boxes say which months each one reaches.
+  const forms = [];
+  const quarterRows = [];
+  for (let q = 1; q <= 5; q++) {
+    const boxes = results[`${workbook}!VATQtr${q}`];
+    if (!boxes) continue;
+    const end = num(boxes.G5);
+    forms.push({ name: `Q${q}`, end: vatinterfaceRowEnding(results, end, layout) });
+    const period = periodEnding(end);
+    const form = `${workbook}!VATQtr${q}`;
+    quarterRows.push({ label: `Q${q}${period} box 1: VAT due on sales`, value: fmt(num(boxes.G9)), indent: 1, cells: [`${form}!G9`] });
+    quarterRows.push({
+      label: `Q${q}${period} box 4: VAT reclaimed on purchases`,
+      value: fmt(num(boxes.G15)),
+      indent: 1,
+      cells: [`${form}!G15`],
+    });
+    quarterRows.push({ label: `Q${q}${period} box 5: net VAT due`, value: fmt(num(boxes.G17)), indent: 1, cells: [`${form}!G17`] });
+  }
+  if (quarterRows.length > 0) {
+    rows.push(...vatCycleRows(vatinterfacePeriods(results, layout), forms));
+    rows.push({ label: "**The return forms as the package fills them in**", value: "" });
+    rows.push(...quarterRows);
+  }
+  return { title: "VAT Returns", rows };
+}
+
+// The VAT periods the interface carries, one per row, with the VAT on each
+// side and whether the period is one of the twelve accounting months.
+export function vatinterfacePeriods(results, layout) {
+  const vatinterface = results[`${layout.workbook}!Vatinterface`];
+  if (!vatinterface) return [];
+  const num = (v) => (typeof v === "number" ? v : 0);
+  const periods = [];
+  for (let row = VATINTERFACE_ROWS.first; row <= VATINTERFACE_ROWS.last; row++) {
+    const end = num(vatinterface[`B${row}`]);
+    if (!end) continue;
+    periods.push({
+      row,
+      endLabel: formatSerialDate(end),
+      outputVat: num(vatinterface[`F${row}`]),
+      inputVat: num(vatinterface[`J${row}`]),
+      inAccountingYear: row >= VATINTERFACE_ROWS.firstMonth && row < VATINTERFACE_ROWS.firstMonth + 12,
+      cells: {
+        end: `${layout.workbook}!Vatinterface!B${row}`,
+        output: `${layout.workbook}!Vatinterface!F${row}`,
+        input: `${layout.workbook}!Vatinterface!J${row}`,
+      },
+    });
+  }
+  return periods;
+}
+
+// The interface row a return form's own period end date lands on, or null
+// when the form names a date the interface does not carry.
+export function vatinterfaceRowEnding(results, end, layout) {
+  const vatinterface = results[`${layout.workbook}!Vatinterface`];
+  if (!vatinterface || !end) return null;
+  for (let row = VATINTERFACE_ROWS.first; row <= VATINTERFACE_ROWS.last; row++) {
+    if (Math.round(typeof vatinterface[`B${row}`] === "number" ? vatinterface[`B${row}`] : 0) === Math.round(end)) return row;
+  }
+  return null;
+}
+
+// The Vatinterface and the five return forms against the month tabs and
+// straddling entry sheets that feed them.
+export function checkVatChain({ check, num, rate }, results, expected, layout) {
+  // ── Vatinterface: where in the VAT chain a break happened ────────────────
+  //
+  // The box checks above catch a break; these say where it is. Each interface
+  // row is compared against the leaf workbook or the straddling entry sheet
+  // that feeds it, each quarter column against the three period rows it sums,
+  // and each VAT box against the interface row its LOOKUP lands on. A month
+  // link that stops carrying fails on that month and side alone.
+  const vatinterface = results[`${layout.workbook}!Vatinterface`];
+  if (vatinterface) {
+    layout.monthTabs(results).forEach((tab, i) => {
+      const row = VATINTERFACE_ROWS.firstMonth + i;
+      const salesMonth = results[`Sales.xlsx!${tab}`];
+      const purchasesMonth = results[`Purchases.xlsx!${tab}`];
+      if (salesMonth) {
+        check(
+          `Vatinterface D${row}: ${tab} sales net = Sales.xlsx ${tab}`,
+          num(vatinterface[`D${row}`]),
+          num(salesMonth[layout.salesNetCell]),
+        );
+        check(
+          `Vatinterface F${row}: ${tab} output VAT = Sales.xlsx ${tab}`,
+          num(vatinterface[`F${row}`]),
+          num(salesMonth[layout.salesVatCell]),
+        );
+      }
+      if (purchasesMonth) {
+        check(
+          `Vatinterface H${row}: ${tab} purchases net = Purchases.xlsx ${tab}`,
+          num(vatinterface[`H${row}`]),
+          num(purchasesMonth[layout.purchasesNetCell]),
+        );
+        check(
+          `Vatinterface J${row}: ${tab} input VAT = Purchases.xlsx ${tab}`,
+          num(vatinterface[`J${row}`]),
+          num(purchasesMonth[layout.purchasesVatCell]),
+        );
+      }
+    });
+
+    // The straddling periods, anchored in the entries the scenario put on
+    // their own sheets. The sheets compute VAT from the gross figure at the
+    // standard rate, so the expectation splits the same gross the same way.
+    const straddlingGross = (entries) => {
+      const byPeriod = {};
+      for (const entry of entries || []) byPeriod[entry.period] = (byPeriod[entry.period] || 0) + entry.amount;
+      return byPeriod;
+    };
+    const straddlingSales = straddlingGross(expected.vat_straddling_sales);
+    const straddlingPurchases = straddlingGross(expected.vat_straddling_purchases);
+    if (expected.vat_straddling_sales || expected.vat_straddling_purchases) {
+      for (const [period, row] of Object.entries(STRADDLING_PERIOD_ROWS)) {
+        const salesGross = straddlingSales[period] || 0;
+        const purchasesGross = straddlingPurchases[period] || 0;
+        check(
+          `Vatinterface D${row}: ${period} sales net = the straddling sales entered for that period`,
+          num(vatinterface[`D${row}`]),
+          netOfVat(salesGross, rate),
+        );
+        check(
+          `Vatinterface F${row}: ${period} output VAT = the straddling sales entered for that period`,
+          num(vatinterface[`F${row}`]),
+          salesGross - netOfVat(salesGross, rate),
+        );
+        check(
+          `Vatinterface H${row}: ${period} purchases net = the straddling purchases entered for that period`,
+          num(vatinterface[`H${row}`]),
+          netOfVat(purchasesGross, rate),
+        );
+        check(
+          `Vatinterface J${row}: ${period} input VAT = the straddling purchases entered for that period`,
+          num(vatinterface[`J${row}`]),
+          purchasesGross - netOfVat(purchasesGross, rate),
+        );
+      }
+    }
+
+    const quarterColumns = [
+      ["E", "D", "sales net"],
+      ["G", "F", "output VAT"],
+      ["I", "H", "purchases net"],
+      ["K", "J", "input VAT"],
+    ];
+    for (let q = 1; q <= 5; q++) {
+      const qtr = results[`${layout.workbook}!VATQtr${q}`];
+      if (!qtr || typeof qtr.G5 !== "number") continue;
+      let row = null;
+      for (let r = VATINTERFACE_ROWS.first; r <= VATINTERFACE_ROWS.last; r++) {
+        if (Math.round(num(vatinterface[`B${r}`])) === Math.round(qtr.G5)) row = r;
+      }
+      check(`VAT Q${q}: quarter end date is one of the Vatinterface periods`, row === null ? 0 : 1, 1, 0);
+      if (row === null) continue;
+
+      if (row - 2 >= VATINTERFACE_ROWS.first) {
+        for (const [total, period, label] of quarterColumns) {
+          check(
+            `Vatinterface ${total}${row}: quarter ${label} = its three period rows`,
+            num(vatinterface[`${total}${row}`]),
+            num(vatinterface[`${period}${row - 2}`]) + num(vatinterface[`${period}${row - 1}`]) + num(vatinterface[`${period}${row}`]),
+          );
+        }
+      }
+
+      check(`VAT Q${q}: box 1 (G9) = Vatinterface quarter VAT due (G${row})`, num(qtr.G9), num(vatinterface[`G${row}`]));
+      check(`VAT Q${q}: box 4 (G15) = Vatinterface quarter VAT reclaimed (K${row})`, num(qtr.G15), num(vatinterface[`K${row}`]));
+      check(`VAT Q${q}: box 7 (G23) = Vatinterface quarter purchases net (I${row})`, num(qtr.G23), num(vatinterface[`I${row}`]));
+      // Box 6 is sales net of VAT, or sales including VAT when the flat rate
+      // scheme flag in column M is set.
+      const flatRate = num(vatinterface[`M${row}`]) > 0;
+      check(
+        `VAT Q${q}: box 6 (G21) = Vatinterface quarter sales ${flatRate ? "including" : "net of"} VAT`,
+        num(qtr.G21),
+        num(vatinterface[`E${row}`]) + (flatRate ? num(vatinterface[`G${row}`]) : 0),
+      );
+      check(
+        `VAT Q${q}: payment due date (G7) = Vatinterface final date for payment (C${row})`,
+        num(qtr.G7),
+        num(vatinterface[`C${row}`]),
+        0,
+      );
+    }
+
+    // ── The five return forms as one cycle ────────────────────────
+    //
+    // Each form's own date decides which three interface rows it declares, so
+    // the five together are checked as a cycle: distinct periods, each a
+    // quarter after the one before it, Q1 to Q4 covering the twelve accounting
+    // months once each, and the fifth on the last period the interface
+    // carries.
+    const periods = vatinterfacePeriods(results, layout);
+    const returnForms = [];
+    for (let q = 1; q <= 5; q++) {
+      const qtr = results[`${layout.workbook}!VATQtr${q}`];
+      if (qtr && typeof qtr.G5 === "number") returnForms.push({ name: `Q${q}`, end: vatinterfaceRowEnding(results, qtr.G5, layout) });
+    }
+    const coverage = vatReturnCoverage(periods, returnForms);
+    if (coverage.placed.length === 5) {
+      const [q1, q2, q3, q4, q5] = coverage.placed;
+      check("VAT: the five returns end on five different periods", new Set(coverage.placed.map((form) => form.row)).size, 5, 0);
+      for (const [earlier, later] of [
+        [q1, q2],
+        [q2, q3],
+        [q3, q4],
+        [q4, q5],
+      ]) {
+        check(`VAT: ${later.name} ends a quarter after ${earlier.name}`, later.row - earlier.row, 3, 0);
+      }
+      const quarterlyRows = new Set([q1, q2, q3, q4].flatMap((form) => form.covers));
+      check(
+        "VAT: Q1-Q4 cover every month of the accounting year",
+        periods.filter((period) => period.inAccountingYear && quarterlyRows.has(period.row)).length,
+        periods.filter((period) => period.inAccountingYear).length,
+        0,
+      );
+      check("VAT: Q5 ends on the last period the Vatinterface carries", q5.row, VATINTERFACE_ROWS.last, 0);
+
+      // Five consecutive quarters need fifteen periods and the interface
+      // carries seventeen, so no two returns reach the same one. A period
+      // declared twice would be filed twice, so it fails rather than warns,
+      // and the output VAT on it says what the second filing would repeat.
+      check("VAT: periods more than one of the five returns declares", coverage.shared.length, 0, 0);
+      check(
+        "VAT: output VAT declared on more than one of the five returns",
+        coverage.shared.reduce((total, period) => total + period.outputVat, 0),
+        0,
+        0,
+      );
+    }
+  }
+}