@diy-accounting-uk/diya-gl 1.1.2 → 1.2.0

package/README.md

@@ -49,8 +49,8 @@ Each subcommand is also its own command, if you only want one on your `PATH`:
 - **read-workbook** takes an `.xlsx`, a package zip, or a diya-gl zip or JSON file
   (`--file`), and writes `book.toml`, `lines.jsonl`, `report.json` and `bookchecks.json`.
 - **write-workbook** takes a diya-gl book (`--data` or `--file`) and writes the Excel
-  package its product composes onto its template — the same client-side path the site's
-  books page uses, so it never needs LibreOffice. Add `--zip` for the package as one zip.
+  package its product composes onto its template — the same client-side path the DIYA-GL
+  pages use, so it never needs LibreOffice. Add `--zip` for the package as one zip.
 - **mcp** runs a stdio [MCP](https://modelcontextprotocol.io) server with four tools:
   `extract_book`, `report`, `edit_lines`, `save_workbook`. Point an MCP client at
   `diya-gl-mcp` (or `diya-gl mcp`) with no arguments.

package/bin/diya-gl-write-workbook.js

@@ -4,7 +4,7 @@
 //
 // diya-gl-write-workbook.js — writes the Excel package a diya-gl book
 // composes onto its product's template, with no LibreOffice: the same
-// client-side compose path the books page uses. See
+// client-side compose path the DIYA-GL pages use. See
 // app/bin/write-workbook.js in the source repository for the full option
 // list (--data or --file, plus --zip for the package download).
 

package/dist/app/bin/export.js

@@ -13,7 +13,7 @@
 //
 // --source-dir reads a package the pipeline already unpacked into its own
 // directory, and always needs --package to say which product's extractors
-// to run. --file takes any of the kinds books-interchange.js reads -- a
+// to run. --file takes any of the kinds diya-gl-interchange.js reads -- a
 // customer's own download, not a directory this repo laid out -- and writes
 // beside that input unless --output-dir says otherwise; --package is
 // optional there, since the file itself says which product it is (the
@@ -59,7 +59,7 @@ import {
   InvalidDiyaGlJsonError,
   PackagePartError,
   ProductNotAvailableError,
-} from "../lib/books-interchange.js";
+} from "../lib/diya-gl-interchange.js";
 import { PRODUCTS } from "../lib/products.js";
 
 // A book read through --file whose sniffed product disagrees with the
@@ -74,7 +74,7 @@ export class PackageMismatchError extends Error {
 
 // Every error a book source can refuse a read with, named rather than a
 // stack trace: --file prints the message and exits, exactly as the anchor
-// guard already did before books-interchange.js grew four more ways a file
+// guard already did before diya-gl-interchange.js grew four more ways a file
 // can be rejected.
 const NAMED_BOOK_SOURCE_ERRORS = [
   AnchorError,
@@ -192,13 +192,13 @@ async function writeBookChecksJson(outputDir, book, lines) {
   console.log(`  bookchecks.json: ${results.length} rules, ${failing} failing`);
 }
 
-// The whole --file extraction: books-interchange.js sniffs the input and
+// The whole --file extraction: diya-gl-interchange.js sniffs the input and
 // turns it into D (a workbook or a package zip runs the anchor guard and
 // the extractors over a workbook set; a diya-gl zip, a JSON file or that
 // JSON zipped validate straight against the published schemas), then this
 // builds R from that D. --source-dir's CLI path and the MCP server's
 // extract_book tool both call this rather than each reaching into
-// books-interchange.js on their own, so a change to how D or R are produced
+// diya-gl-interchange.js on their own, so a change to how D or R are produced
 // can only ever happen in one place.
 //
 // The product is whichever of the four the file sniffs as; a caller that

package/dist/app/bin/write-workbook.js

@@ -4,7 +4,7 @@
 //
 // write-workbook.js — diya-gl data in, an Excel package out. The other
 // direction from export.js: this takes a book.toml + lines.jsonl (or any of
-// the kinds books-interchange.js reads) and writes the workbook(s) the
+// the kinds diya-gl-interchange.js reads) and writes the workbook(s) the
 // template composes them onto, through product-workbook.js's saveWorkbook
 // path. No LibreOffice: the writes land as cached formula results the same
 // way the books page's client-side export does, never a recalculation pass.
@@ -17,7 +17,7 @@
 import { readFileSync, writeFileSync, mkdirSync } from "fs";
 import { resolve } from "path";
 import { loadDiyaGlData } from "../lib/diya-gl-loader.js";
-import { readBookSource } from "../lib/books-interchange.js";
+import { readBookSource } from "../lib/diya-gl-interchange.js";
 import { saveWorkbook, saveWorkbookFiles, savePackageZip, productOf } from "../lib/product-workbook.js";
 import { productModule, PRODUCTS } from "../lib/products.js";
 

package/dist/app/data/releases.json

@@ -207,6 +207,32 @@
           "scorecard": "101279 passed, 0 warnings, 0 failed"
         }
       }
+    },
+    {
+      "tag": "diya-gl-v1.1.2",
+      "date": "2026-09-09",
+      "formatVersion": "diya-gl-books/1",
+      "engineVersion": "1.1.2+25fe6af937aa",
+      "taxDataHash": "6a9c036b5f9c",
+      "reconciledCommit": "",
+      "templates": {
+        "bst": {
+          "hash": "0d003e10e00c",
+          "scorecard": "810 passed, 0 warnings, 0 failed"
+        },
+        "taxi": {
+          "hash": "1ff69654d64d",
+          "scorecard": "686 passed, 0 warnings, 0 failed"
+        },
+        "se": {
+          "hash": "c6a50059cc90",
+          "scorecard": "7679 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "0c18ceeaced4",
+          "scorecard": "101279 passed, 0 warnings, 0 failed"
+        }
+      }
     }
   ]
 }

package/dist/app/lib/anchors/se.js

@@ -445,7 +445,7 @@ export function isSeInputCell(file, sheet, cellRef) {
  * baseline from, one per file SE_ANCHORS names. Resolved lazily: path and
  * url are Node-only, so this module only reaches them when a caller actually
  * asks for the paths, keeping SE_ANCHORS and isSeInputCell safe to import
- * under the books bundle's node-absent stubs (see build-books-bundle.mjs).
+ * under the books bundle's node-absent stubs (see build-diya-gl-bundle.mjs).
  * @returns {Promise<Object>} { [file]: templatePath }
  */
 export async function seTemplatePaths() {

package/dist/app/lib/app-resources.js

@@ -30,8 +30,12 @@ const SCHEMA_ROOT_FROM_APP = ["..", "web", "spreadsheets.diyaccounting.co.uk", "
 // so the published npm package and the image leave them out. A repository
 // checkout has app/templates and reads it straight off disk. A packaged install
 // has not, so the loader takes the same file from the site, which already
-// serves the templates the books page uses, and keeps it in a user cache so
+// serves the templates the DIYA-GL pages use, and keeps it in a user cache so
 // every later run works with no network.
+//
+// This stays on /books/ while the site still serves the pages there. Every
+// published version fetches this URL, so it moves only once the live site
+// redirects it, and the redirect keeps the older versions working after that.
 const TEMPLATE_PREFIX = "templates/";
 const DEFAULT_TEMPLATE_SOURCE = "https://spreadsheets.diyaccounting.co.uk/books/assets/";
 

package/dist/app/lib/calculators/se-derivations.js

@@ -0,0 +1,521 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// se-derivations.js — the two named ITSA derivations for the Self Employed
+// product: the quarterly update HMRC's Self Employment Business API expects
+// four times a year, and the annual submission that closes the year. Both
+// sit beside the Ltd derivations in this directory and follow the same
+// shape: read the engine's own cells, add no arithmetic beyond summing and
+// picking boxes, and let a caller with only a book and lines get an answer.
+//
+// Every HMRC field name comes from app/data/hmrc/sa103-mtd-mapping.json --
+// this module never restates a box's API field name in code, so a mapping
+// correction there reaches both derivations with no code change.
+
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { diyaGlToScenario } from "../diya-gl-loader.js";
+import { calculateSeCells } from "./se.js";
+import { SE_YEAR_END_MONTH } from "../../products/se.js";
+import { extractTaxYearStart, parseDate } from "../scenario-loader.js";
+import { shiftMonths, periodShiftMonths } from "../period-shift.js";
+import { splitVat } from "../tax/vat.js";
+
+let cachedMapping = null;
+
+// Resolved on first use, not at import: the engine bundle loads in the browser,
+// where import.meta.url is an http URL and fileURLToPath throws.
+function loadMapping() {
+  if (!cachedMapping) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const mappingPath = resolve(here, "..", "..", "data", "hmrc", "sa103-mtd-mapping.json");
+    cachedMapping = JSON.parse(readFileSync(mappingPath, "utf8"));
+  }
+  return cachedMapping;
+}
+
+function sa103fBoxes() {
+  return loadMapping().boxes.filter((entry) => entry.form === "SA103F");
+}
+
+function boxEntry(boxes, boxNumber) {
+  const entry = boxes.find((candidate) => candidate.box === boxNumber);
+  if (!entry) throw new Error(`sa103-mtd-mapping.json carries no SA103F box ${boxNumber}`);
+  if (!entry.field) throw new Error(`SA103F box ${boxNumber} carries no API field in sa103-mtd-mapping.json`);
+  return entry;
+}
+
+// A box HMRC's own mapping shares between two fields lists them "a | b". The
+// first is the one this template's cell actually answers -- section 8 of the
+// design records which, box by box -- so a caller asking for "the field this
+// box answers" gets that one unless told to reach past it.
+function fieldsOf(entry) {
+  return entry.field.split("|").map((field) => field.trim());
+}
+
+function primaryField(boxes, boxNumber) {
+  return fieldsOf(boxEntry(boxes, boxNumber))[0];
+}
+
+function setPath(target, path, value) {
+  const parts = path.split(".");
+  let node = target;
+  for (let i = 0; i < parts.length - 1; i++) node = node[parts[i]] ||= {};
+  node[parts[parts.length - 1]] = value;
+}
+
+function round2(value) {
+  return Math.round(value * 100) / 100;
+}
+
+// Every quarter is rounded to the penny and the fourth carries whatever the
+// first three left behind, so the four always sum to the annual box exactly
+// -- the invariant the reconciliation tests below hold the derivation to.
+function quartersWithResidue(values, annual) {
+  const q1 = round2(values[0]);
+  const q2 = round2(values[1]);
+  const q3 = round2(values[2]);
+  const q4 = round2(round2(annual) - q1 - q2 - q3);
+  return [q1, q2, q3, q4];
+}
+
+function vatRateFor(scenario) {
+  return scenario?.metadata?.vat_registered === false ? 0 : 0.2;
+}
+
+function isoDate(year, month, day) {
+  return `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+
+// HMRC's standard quarterly periods, published guidance (the phase 2 plan
+// names these). Confirmed.
+function standardQuarterBoundaries(startYear) {
+  return [
+    { start: isoDate(startYear, 4, 6), end: isoDate(startYear, 7, 5) },
+    { start: isoDate(startYear, 7, 6), end: isoDate(startYear, 10, 5) },
+    { start: isoDate(startYear, 10, 6), end: isoDate(startYear + 1, 1, 5) },
+    { start: isoDate(startYear + 1, 1, 6), end: isoDate(startYear + 1, 4, 5) },
+  ];
+}
+
+// The calendar election's exact dates are understood but not confirmed
+// against a live filing (no spec in this repository states them). Isolated
+// here so a confirmed change is a one-line edit. They only affect the dates
+// reported back to the caller -- the calendar quarters are computed as three
+// whole P&L month columns regardless of the exact day either boundary falls
+// on, so a correction here changes no figure.
+function calendarQuarterBoundaries(startYear) {
+  return [
+    { start: isoDate(startYear, 4, 6), end: isoDate(startYear, 6, 30) },
+    { start: isoDate(startYear, 7, 1), end: isoDate(startYear, 9, 30) },
+    { start: isoDate(startYear, 10, 1), end: isoDate(startYear, 12, 31) },
+    { start: isoDate(startYear + 1, 1, 1), end: isoDate(startYear + 1, 4, 5) },
+  ];
+}
+
+// A book's own first and last postings can fall a few days either side of
+// the nominal 6 April / 5 April boundary (the fixtures carry lines dated 1
+// to 5 April). The first quarter's lower edge and the last quarter's upper
+// edge are widened to unbounded so those postings always land inside the
+// year rather than being dropped as before-the-period or after-it; the two
+// boundaries in between stay exactly as given.
+function widenOuterEdges(boundaries) {
+  return boundaries.map((boundary, index) => ({
+    start: index === 0 ? null : boundary.start,
+    end: index === boundaries.length - 1 ? null : boundary.end,
+  }));
+}
+
+function withinBoundary(dateIso, boundary) {
+  if (boundary.start !== null && dateIso < boundary.start) return false;
+  if (boundary.end !== null && dateIso > boundary.end) return false;
+  return true;
+}
+
+function quarterIndexFor(dateIso, boundaries) {
+  const index = boundaries.findIndex((boundary) => withinBoundary(dateIso, boundary));
+  if (index === -1) throw new Error(`no quarter boundary covers ${dateIso}`);
+  return index;
+}
+
+function flatten(journal) {
+  return Object.values(journal || {}).flat();
+}
+
+function taxYearLabel(taxData, book) {
+  if (taxData?.tax_year?.label) return taxData.tax_year.label;
+  const periodEnd = book?.documentInfo?.periodCoveredEnd;
+  if (!periodEnd) throw new Error("no tax year: taxData.tax_year.label is absent and book.documentInfo.periodCoveredEnd is missing");
+  const year = parseDate(periodEnd).getUTCFullYear();
+  return `${year - 1}-${String(year).slice(-2)}`;
+}
+
+const MONTH_COLS = ["C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N"];
+
+function quarterSumOverRows(pl, rows, quarterIndex) {
+  const columns = MONTH_COLS.slice(quarterIndex * 3, quarterIndex * 3 + 3);
+  let total = 0;
+  for (const column of columns) for (const row of rows) total += pl[`${column}${row}`] || 0;
+  return total;
+}
+
+// The calendar election is three whole P&L month columns a quarter, so the
+// quarterly figures come straight off the monthly grid the engine already
+// computes -- the same grid app/test/se-anchors.test.js and the committed
+// reports check against the Excel package. This path carries every mixed
+// row's own addback (the payroll addition to row 21, the mileage claim in
+// row 25, the stock movement in row 14's March cell) automatically, because
+// the engine already folded each into the month it belongs to.
+function quarterlyFromMonthlyGrid(pl) {
+  const perQuarter = (rows) => [0, 1, 2, 3].map((quarter) => quarterSumOverRows(pl, rows, quarter));
+  return {
+    turnover: perQuarter([5, 6, 7, 8]),
+    other: perQuarter([38]),
+    costOfGoods: perQuarter([14, 16]),
+    paymentsToSubcontractors: perQuarter([15]),
+    wagesAndStaffCosts: perQuarter([21]),
+    carVanTravelExpenses: perQuarter([25, 26]),
+    premisesRunningCosts: perQuarter([22]),
+    maintenanceCosts: perQuarter([23]),
+    adminCosts: perQuarter([24]),
+    advertisingCosts: perQuarter([27]),
+    interestOnBankOtherLoans: perQuarter([30]),
+    financeCharges: perQuarter([31]),
+    irrecoverableDebts: perQuarter([29]),
+    professionalFees: perQuarter([28]),
+    depreciation: perQuarter([33, 34]),
+    otherExpenses: perQuarter([32]),
+    depreciationDisallowable: perQuarter([34]),
+  };
+}
+
+// Sales and purchases code letters that feed a P&L row with no other
+// adjustment mixed in, read off app/lib/scenario-extractor.js's own account
+// maps by way of the code letters scenario transactions already carry.
+const SALES_QUARTERLY_ROW = { a: 5, b: 6, c: 7, d: 8 };
+const PURCHASES_QUARTERLY_ROW = { s: 14, c: 15, o: 16, w: 21, p: 22, m: 23, g: 24, v: 25, h: 26, a: 27, l: 28, y: 32 };
+
+const MONTH_KEYS = ["apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec", "jan", "feb", "mar"];
+const MONTH_SHEET_NAMES = {
+  apr: "Apr",
+  may: "May",
+  jun: "Jun",
+  jul: "Jul",
+  aug: "Aug",
+  sep: "Sep",
+  oct: "Oct",
+  nov: "Nov",
+  dec: "Dec",
+  jan: "Jan",
+  feb: "Feb",
+  mar: "Mar",
+};
+
+// HMRC's standard periods cut three month tabs mid-month, so no cell in the
+// package holds either half of a cut month and the quarterly figures come
+// off the dated lines instead: each line goes through the same code-to-row
+// map the engine uses, splits VAT at the book's own rate, and lands in
+// whichever quarter its (period-shifted) posting date falls in. Two things
+// the lines cannot carry are added separately: the depreciation pair, which
+// the schedule spreads evenly across the year regardless of period type, and
+// the stock movement, which sits wholly in the quarter holding the
+// accounting period end. The mileage claim is banded monthly rather than
+// per line, so its month's whole claim is bucketed by the calendar quarter
+// its month falls in either way, the same routing the calendar election uses.
+function quarterlyFromLines(scenario, rawResults, rate, monthOffset, boundaries) {
+  const rows = {};
+  for (const row of [5, 6, 7, 8, 14, 15, 16, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 38]) rows[row] = [0, 0, 0, 0];
+
+  const shiftedIso = (dateValue) => {
+    const shifted = shiftMonths(parseDate(dateValue), monthOffset);
+    return isoDate(shifted.getUTCFullYear(), shifted.getUTCMonth() + 1, shifted.getUTCDate());
+  };
+
+  for (const tx of flatten(scenario.sales)) {
+    if (tx.mileage) continue;
+    const net = splitVat(tx.amount, rate).net;
+    const quarter = quarterIndexFor(shiftedIso(tx.date), boundaries);
+    if (tx.code in SALES_QUARTERLY_ROW) rows[SALES_QUARTERLY_ROW[tx.code]][quarter] += net;
+    else if (tx.code === "o") rows[29][quarter] -= net;
+  }
+  for (const tx of flatten(scenario.purchases)) {
+    if (tx.mileage) continue;
+    const row = PURCHASES_QUARTERLY_ROW[tx.code];
+    if (!row) continue;
+    const net = splitVat(tx.amount, rate).net;
+    const quarter = quarterIndexFor(shiftedIso(tx.date), boundaries);
+    rows[row][quarter] += net;
+  }
+  for (const entry of flatten(scenario.payroll)) {
+    const quarter = quarterIndexFor(shiftedIso(entry.date), boundaries);
+    rows[21][quarter] += (entry.grossPay || 0) + (entry.employerNI || 0);
+  }
+  for (const tx of flatten(scenario.bank)) {
+    if (tx.code === "BC") continue;
+    const quarter = quarterIndexFor(shiftedIso(tx.date), boundaries);
+    const isCash = tx.account === "1220";
+    if (!isCash && tx.direction === "out" && tx.code === "J") rows[30][quarter] += tx.amount;
+    if (!isCash && tx.direction === "out" && tx.code === "B") rows[31][quarter] += tx.amount;
+    if (isCash && tx.direction === "out" && tx.code === "J") rows[31][quarter] += tx.amount;
+    if (!isCash && tx.direction === "in" && tx.code === "K") rows[38][quarter] += tx.amount;
+  }
+
+  const mileageByQuarter = [0, 0, 0, 0];
+  MONTH_KEYS.forEach((key, index) => {
+    const claim = rawResults[`Purchases.xlsx!${MONTH_SHEET_NAMES[key]}`]?.G2 || 0;
+    mileageByQuarter[Math.floor(index / 3)] += claim;
+  });
+
+  // The stock movement sits only in the closing month's own cell, which
+  // carries no code of its own to bucket by line. Isolating it as the gap
+  // between the engine's own annual row 14 and this quarter table's own
+  // code-s total keeps it out of the per-line loop above and lets it land
+  // wholly on the quarter that holds the accounting period end.
+  const annualCodeSNet = rows[14].reduce((total, value) => total + value, 0);
+  const stockMovement = rawResults["Profit & Loss Account"].B14 - annualCodeSNet;
+  rows[14][3] += stockMovement;
+
+  const depreciationQuarter = rawResults["SE Full"].D114 / 4;
+  const depreciationDisallowableQuarter = rawResults["SE Full"].O114 / 4;
+
+  return {
+    turnover: [0, 1, 2, 3].map((q) => rows[5][q] + rows[6][q] + rows[7][q] + rows[8][q]),
+    other: rows[38],
+    costOfGoods: [0, 1, 2, 3].map((q) => rows[14][q] + rows[16][q]),
+    paymentsToSubcontractors: rows[15],
+    wagesAndStaffCosts: rows[21],
+    carVanTravelExpenses: [0, 1, 2, 3].map((q) => rows[25][q] + rows[26][q] + mileageByQuarter[q]),
+    premisesRunningCosts: rows[22],
+    maintenanceCosts: rows[23],
+    adminCosts: rows[24],
+    advertisingCosts: rows[27],
+    interestOnBankOtherLoans: rows[30],
+    financeCharges: rows[31],
+    irrecoverableDebts: rows[29],
+    professionalFees: rows[28],
+    depreciation: [depreciationQuarter, depreciationQuarter, depreciationQuarter, depreciationQuarter],
+    otherExpenses: rows[32],
+    depreciationDisallowable: [
+      depreciationDisallowableQuarter,
+      depreciationDisallowableQuarter,
+      depreciationDisallowableQuarter,
+      depreciationDisallowableQuarter,
+    ],
+  };
+}
+
+/**
+ * The four quarterly period summaries HMRC's Self Employment Business API
+ * expects, built off the same engine the reconciliation runs.
+ *
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {Object} taxData - the tax year file (or extractTaxDataFromBook's
+ *   result) the package is generated against
+ * @param {Object} [options]
+ * @param {Object} [options.scenario] - a scenario already built by
+ *   diyaGlToScenario; built from book and lines when absent
+ * @param {"calendar"|"standard"} [options.quarterlyPeriodType] - which
+ *   quarter boundaries to fall back to when options.periods is absent.
+ *   Defaults to "calendar".
+ * @param {Array<{periodStartDate: string, periodEndDate: string}>} [options.periods] -
+ *   the four periods HMRC's own obligations response named. Overrides
+ *   quarterlyPeriodType.
+ */
+export function buildSelfEmploymentQuarterlyUpdates(book, lines, taxData, options = {}) {
+  const scenario = options.scenario || diyaGlToScenario(book, lines, "se");
+  const rate = vatRateFor(scenario);
+  const startYear = taxData?.tax_year?.start ? new Date(taxData.tax_year.start).getUTCFullYear() : extractTaxYearStart(scenario);
+  if (!startYear) throw new Error("buildSelfEmploymentQuarterlyUpdates: no tax year could be read from taxData or scenario");
+  const monthOffset = periodShiftMonths(scenario, startYear, SE_YEAR_END_MONTH);
+
+  const rawResults = calculateSeCells(book, lines, taxData, scenario);
+  const pl = rawResults["Profit & Loss Account"];
+  const seFull = rawResults["SE Full"];
+  const boxes = sa103fBoxes();
+
+  const explicitPeriods = options.periods ? options.periods.map((p) => ({ start: p.periodStartDate, end: p.periodEndDate })) : null;
+  const quarterlyPeriodType = options.quarterlyPeriodType || "calendar";
+  const nominalBoundaries =
+    explicitPeriods || (quarterlyPeriodType === "standard" ? standardQuarterBoundaries(startYear) : calendarQuarterBoundaries(startYear));
+
+  const usesMonthlyGrid = !explicitPeriods && quarterlyPeriodType === "calendar";
+  const quarterly = usesMonthlyGrid
+    ? quarterlyFromMonthlyGrid(pl)
+    : quarterlyFromLines(scenario, rawResults, rate, monthOffset, widenOuterEdges(nominalBoundaries));
+
+  const annualAnchor = {
+    turnover: seFull.D55,
+    other: seFull.O55,
+    costOfGoods: seFull.D66,
+    paymentsToSubcontractors: seFull.D70,
+    wagesAndStaffCosts: seFull.D74,
+    carVanTravelExpenses: seFull.D78,
+    premisesRunningCosts: seFull.D82,
+    maintenanceCosts: seFull.D86,
+    adminCosts: seFull.D90,
+    advertisingCosts: seFull.D94,
+    interestOnBankOtherLoans: seFull.D98,
+    financeCharges: seFull.D102,
+    irrecoverableDebts: seFull.D106,
+    professionalFees: seFull.D110,
+    depreciation: seFull.D114,
+    otherExpenses: seFull.D118,
+    depreciationDisallowable: seFull.O114,
+  };
+
+  const quarters = {};
+  for (const key of Object.keys(annualAnchor)) quarters[key] = quartersWithResidue(quarterly[key], annualAnchor[key]);
+
+  const incomeField = { turnover: primaryField(boxes, "15"), other: primaryField(boxes, "16") };
+  const expenseField = {
+    costOfGoods: primaryField(boxes, "17"),
+    paymentsToSubcontractors: primaryField(boxes, "18"),
+    wagesAndStaffCosts: primaryField(boxes, "19"),
+    carVanTravelExpenses: primaryField(boxes, "20"),
+    premisesRunningCosts: primaryField(boxes, "21"),
+    maintenanceCosts: primaryField(boxes, "22"),
+    adminCosts: primaryField(boxes, "23"),
+    advertisingCosts: primaryField(boxes, "24"),
+    interestOnBankOtherLoans: primaryField(boxes, "25"),
+    financeCharges: primaryField(boxes, "26"),
+    irrecoverableDebts: primaryField(boxes, "27"),
+    professionalFees: primaryField(boxes, "28"),
+    depreciation: primaryField(boxes, "29"),
+    otherExpenses: primaryField(boxes, "30"),
+  };
+  const disallowableField = primaryField(boxes, "44");
+
+  const periods = nominalBoundaries.map((boundary, index) => {
+    // Each mapping field name already carries its own top-level branch
+    // ("periodIncome.turnover", "periodExpenses.costOfGoods", ...), so every
+    // field for this quarter lands on one shared root and the three
+    // branches fall out of that root rather than being built separately and
+    // then walked into again.
+    const period = { periodDates: { periodStartDate: boundary.start, periodEndDate: boundary.end } };
+    setPath(period, incomeField.turnover, quarters.turnover[index]);
+    setPath(period, incomeField.other, quarters.other[index]);
+    for (const [key, field] of Object.entries(expenseField)) setPath(period, field, quarters[key][index]);
+    setPath(period, disallowableField, quarters.depreciationDisallowable[index]);
+    return period;
+  });
+
+  const warnings = [];
+  const box24 = boxEntry(boxes, "24");
+  warnings.push({
+    field: fieldsOf(box24)[1],
+    reason: "SA103F box 24 combines advertising and business entertainment in one Profit & Loss Account row; the template cannot separate them.",
+  });
+  warnings.push({
+    field: "periodExpenses.consolidatedExpenses",
+    reason: "a customer election for turnover at or below the VAT threshold, offered on the filing page; never derived from the books.",
+  });
+  warnings.push({
+    field: disallowableField,
+    reason:
+      'SA103F box 44 is Profit & Loss Account row 34 alone; a loss on disposal (row 33) stays inside box 29\'s allowable total, ' +
+      "which is not an allowable deduction, with nothing moved to a disallowable box.",
+    handComputed: round2(pl.B33 || 0),
+  });
+  for (const entry of boxes) {
+    if (entry.route !== "quarterly" || !entry.field) continue;
+    if (!entry.field.includes("periodDisallowableExpenses.")) continue;
+    if (entry.box === "44") continue;
+    for (const field of fieldsOf(entry)) {
+      warnings.push({
+        field,
+        reason: `SA103F box ${entry.box} is printed with no formula behind it ("Not captured in DIY Accounting" on the VitalTax sheet); no book field carries it.`,
+      });
+    }
+  }
+
+  return {
+    taxYear: taxYearLabel(taxData, book),
+    quarterlyPeriodType: explicitPeriods ? options.quarterlyPeriodType : quarterlyPeriodType,
+    periods,
+    warnings,
+  };
+}
+
+// Every annual field this book can source, and a warning naming the box for
+// every one it cannot -- section 8 of the design records why each is out of
+// reach today: no cell in the template, a cell the customer fills by hand,
+// or a box the schema has no field for.
+const NO_SOURCE_ANNUAL_BOXES = [
+  { box: "51", pick: 0 }, // allowances.capitalAllowanceSpecialRatePool
+  { box: "51", pick: 1 }, // allowances.capitalAllowanceSingleAssetPool (shared with box 50)
+  { box: "52.1", pick: 0 }, // allowances.zeroEmissionsCarAllowance
+  { box: "53", pick: 0 }, // allowances.structuredBuildingAllowance
+  { box: "53.1", pick: 0 }, // allowances.enhancedStructuredBuildingAllowance
+  { box: "55", pick: 1 }, // allowances.businessPremisesRenovationAllowance (shared with enhancedCapitalAllowance)
+  { box: "59", pick: 1 }, // adjustments.balancingChargeBpra (shared with balancingChargeOther)
+  { box: "62", pick: 0 }, // adjustments.includedNonTaxableProfits
+  { box: "68", pick: 0 }, // adjustments.basisAdjustment
+  { box: "71", pick: 0 }, // adjustments.accountingAdjustment
+  { box: "73.3", pick: 0 }, // adjustments.transitionProfitAmount
+  { box: "73.3", pick: 1 }, // adjustments.transitionProfitAccelerationAmount
+];
+
+/**
+ * The annual submission that closes the year, built off the same engine the
+ * reconciliation runs.
+ *
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {Object} taxData - the tax year file (or extractTaxDataFromBook's
+ *   result) the package is generated against
+ * @param {Object} [options]
+ * @param {Object} [options.scenario] - a scenario already built by
+ *   diyaGlToScenario; built from book and lines when absent
+ */
+export function buildSelfEmploymentAnnualSubmission(book, lines, taxData, options = {}) {
+  const scenario = options.scenario || diyaGlToScenario(book, lines, "se");
+  const rawResults = calculateSeCells(book, lines, taxData, scenario);
+  const seFull = rawResults["SE Full"];
+  const boxes = sa103fBoxes();
+
+  // Each mapping field name already carries its own top-level branch
+  // ("allowances.annualInvestmentAllowance", "adjustments.balancingChargeOther",
+  // ...), so both branches land on one shared root and fall out of it rather
+  // than being built separately and then walked into again.
+  const root = {};
+  setPath(root, primaryField(boxes, "49"), round2(seFull.D139));
+  setPath(root, primaryField(boxes, "50"), round2(seFull.D144));
+  setPath(root, primaryField(boxes, "55"), round2(seFull.O144));
+  setPath(root, primaryField(boxes, "56"), round2(seFull.O149));
+
+  setPath(root, primaryField(boxes, "59"), round2(seFull.O160));
+  const ownUseField = primaryField(boxes, "60");
+  setPath(root, ownUseField, round2(seFull.D169));
+  setPath(root, primaryField(boxes, "75"), round2(seFull.O204));
+
+  const allowances = root.allowances || {};
+  const adjustments = root.adjustments || {};
+
+  const enhancedCapitalAllowanceField = primaryField(boxes, "55");
+  const warnings = [
+    {
+      field: ownUseField,
+      reason: "Business Details!O50 is a customer input cell the book schema has no field for; the template always carries nil here.",
+    },
+    {
+      field: enhancedCapitalAllowanceField,
+      reason:
+        "SA103F box 55 is the small pools write-off (Schedule S1, once the pool balance and the writing down allowance together are under £1,000), not a genuine 100% or enhanced capital allowance; HMRC's own field mapping still files it here.",
+    },
+  ];
+  for (const { box: boxNumber, pick } of NO_SOURCE_ANNUAL_BOXES) {
+    const entry = boxEntry(boxes, boxNumber);
+    warnings.push({
+      field: fieldsOf(entry)[pick],
+      reason: `SA103F box ${boxNumber} has no cell the template computes; the customer fills it in by hand.`,
+    });
+  }
+
+  const result = { taxYear: taxYearLabel(taxData, book) };
+  if (Object.keys(allowances).length > 0) result.allowances = allowances;
+  if (Object.keys(adjustments).length > 0) result.adjustments = adjustments;
+  result.warnings = warnings;
+  return result;
+}

package/dist/app/lib/diya-gl-calculator.js

@@ -16,6 +16,7 @@ import { calculateSeCells, calculateSeResults } from "./calculators/se.js";
 import { calculateLtdCells, calculateLtdResults } from "./calculators/ltd.js";
 
 export { aggregateByAccountAndMonth, annualTotal, sumValues, aggregateByCode } from "./calculators/shared.js";
+export { buildSelfEmploymentQuarterlyUpdates, buildSelfEmploymentAnnualSubmission } from "./calculators/se-derivations.js";
 
 /**
  * Main entry point. Calculate financial reports from diya-gl data.

package/dist/app/lib/diya-gl-canonical.js

@@ -182,7 +182,7 @@ export function canonicalLinesJsonl(lines) {
 
 /**
  * One line's own fields reordered to the schema's declared order, values
- * untouched -- the shape writeBookJson (books-interchange.js) serialises a
+ * untouched -- the shape writeBookJson (diya-gl-interchange.js) serialises a
  * line as. Any field the schema does not declare is kept, after the
  * declared ones, so an unrecognised key is lost to validation rather than
  * to this reordering.
@@ -336,7 +336,7 @@ export function canonicalBookToml(book) {
 
 /**
  * The book's top-level tables reordered to the schema's declared order,
- * values untouched -- the shape writeBookJson (books-interchange.js)
+ * values untouched -- the shape writeBookJson (diya-gl-interchange.js)
  * serialises a book as. Any table the schema does not declare is kept,
  * after the declared ones.
  * @param {Object} book - parsed book.toml

package/dist/app/lib/{books-interchange.js → diya-gl-interchange.js}

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2006-2026 DIY Accounting Limited
 //
-// books-interchange.js — what a byte array handed to the CLI, the MCP
+// diya-gl-interchange.js — what a byte array handed to the CLI, the MCP
 // server or the books page actually is, and the one place that turns it
 // into D (a diya-gl book and its lines) or back into bytes. Every caller
 // sniffs and reads through detectBookSource/readBookSource, so a file that
@@ -49,9 +49,15 @@ import * as bst from "../products/bst.js";
 
 export { AnchorError };
 
-const JSON_FORMAT = "diya-gl-books";
+const JSON_FORMAT = "diya-gl";
 const JSON_VERSION = 1;
 
+// A file written before the format's name changed from "diya-gl-books" to
+// "diya-gl" carries the old name in its "format" field. The version number
+// alone did not change, so a legacy file still reads once its format name is
+// recognised here -- the writer only ever emits JSON_FORMAT.
+const LEGACY_JSON_FORMATS = ["diya-gl-books"];
+
 // The workbook every multi-file package is built around; its siblings say
 // which product the package is.
 const PACKAGE_HUB = "Financialaccounts.xlsx";
@@ -104,7 +110,7 @@ export class InvalidDiyaGlBookError extends Error {
   }
 }
 
-/** A JSON file that is not this module's own diya-gl-books format. */
+/** A JSON file that is not this module's own diya-gl format. */
 export class InvalidDiyaGlJsonError extends Error {
   constructor(why) {
     super(`This JSON file is not a diya-gl book: ${why}`);
@@ -401,7 +407,9 @@ function undeclaredProduct(book) {
   );
 }
 
-// { "format": "diya-gl-books", "version": 1, "product": "bst", "book": {...}, "lines": [...] }
+// { "format": "diya-gl", "version": 1, "product": "bst", "book": {...}, "lines": [...] }
+// A file saved before the format's rename still reads: its "format" is one
+// of LEGACY_JSON_FORMATS rather than JSON_FORMAT.
 function parseJsonDocument(text) {
   let document;
   try {
@@ -409,8 +417,9 @@ function parseJsonDocument(text) {
   } catch (cause) {
     throw new InvalidDiyaGlJsonError(`the text does not parse as JSON (${cause.message})`);
   }
-  if (document.format !== JSON_FORMAT) {
-    throw new InvalidDiyaGlJsonError(`expected "format": ${JSON.stringify(JSON_FORMAT)}, found ${JSON.stringify(document.format)}`);
+  if (document.format !== JSON_FORMAT && !LEGACY_JSON_FORMATS.includes(document.format)) {
+    const expected = [JSON_FORMAT, ...LEGACY_JSON_FORMATS].map((f) => JSON.stringify(f)).join(" or ");
+    throw new InvalidDiyaGlJsonError(`expected "format": ${expected}, found ${JSON.stringify(document.format)}`);
   }
   if (document.version !== JSON_VERSION) {
     throw new InvalidDiyaGlJsonError(`expected "version": ${JSON_VERSION}, found ${JSON.stringify(document.version)}`);

package/dist/app/lib/diya-gl-loader.js

@@ -658,7 +658,7 @@ export function diyaGlToScenario(book, lines, product) {
  *
  * Resolves app/data's path from import.meta.url lazily, on the first call,
  * rather than at module load: this module is bundled into the books page
- * (books-engine.js re-exports diyaGlToScenario from it), where url and path
+ * (diya-gl-engine.js re-exports diyaGlToScenario from it), where url and path
  * are stubs that throw when called -- extractTaxDataFromBook itself is
  * Node-only and never reached from the bundle, but a module-scope call
  * would run for every importer, browser included.

package/dist/app/lib/diya-gl-schema.js

@@ -47,7 +47,7 @@ export function useSchemas(bookSchema, linesSchema) {
  * Security Policy with no `unsafe-eval` forbids the `new Function` inside
  * ajv.compile, which useSchemas() and loadSchemasFrom() both reach. The
  * books bundle takes a different route to the same result (see
- * scripts/build-books-bundle.mjs: it resolves ajv's own imports to functions
+ * scripts/build-diya-gl-bundle.mjs: it resolves ajv's own imports to functions
  * generateStandaloneValidatorSource() built ahead of time, so useSchemas()
  * and loadSchemasFrom() keep working unchanged); this function is the direct
  * seam for a caller - a test proving the two validator sources agree, or a

package/dist/app/lib/mcp/diya-gl-tools.js

@@ -3,10 +3,10 @@
 //
 // diya-gl-tools.js — the four MCP tools, each a thin call into a function
 // phase 1 already tests: extract_book wraps export.js's --file pipeline
-// (books-interchange.js underneath, so every kind it reads loads here too),
+// (diya-gl-interchange.js underneath, so every kind it reads loads here too),
 // report and edit_lines wrap the diya-gl-calculator/report-serializer loop
 // and diya-gl-edits.js, save_workbook wraps product-workbook.js for a workbook
-// or package zip and books-interchange.js for the two diya-gl formats. No
+// or package zip and diya-gl-interchange.js for the two diya-gl formats. No
 // engine code lives here.
 //
 // extract_book and report both carry a bookChecks field alongside report --
@@ -30,7 +30,7 @@ import { resolve as resolvePath } from "path";
 import { extractBookFromFile, buildFileReportDocument, calculatedResultsFor } from "../../bin/export.js";
 import { canonicalBookToml, canonicalLinesJsonl } from "../diya-gl-canonical.js";
 import { stampBook } from "../provenance.js";
-import { writeDiyaGlZip, writeBookJson } from "../books-interchange.js";
+import { writeDiyaGlZip, writeBookJson } from "../diya-gl-interchange.js";
 import { saveWorkbook, savePackageZip, loadTaxDataForBook, productOf } from "../product-workbook.js";
 import { productModule } from "../products.js";
 import {

package/dist/app/lib/overtype-sidecar.js

@@ -93,7 +93,7 @@ function attribute(file, sheet, cellRef, extractionMap, reportLabels) {
 // process. A BST or SE template is a file in this repo that never changes
 // while a process runs, so the path itself is the cache key; Taxi's own
 // baseline is a workbook the generator builds fresh for the book's own tax
-// year (see readWorkbookSource in books-interchange.js), which has no path
+// year (see readWorkbookSource in diya-gl-interchange.js), which has no path
 // on disk to key on, so its entry in options.templates carries its own cache
 // key (a string like "taxi:se-2025-2026") alongside a loader that is only
 // called on a cache miss.

package/dist/app/lib/product-workbook.js

@@ -83,8 +83,8 @@ export function productOf(book) {
   return product;
 }
 
-// Re-exported for product-workbook.js's own callers (books-engine.js,
-// books-interchange.js, the workbook tests); its home is tax-year.js so
+// Re-exported for product-workbook.js's own callers (diya-gl-engine.js,
+// diya-gl-interchange.js, the workbook tests); its home is tax-year.js so
 // diya-gl-loader.js can share it without importing this module.
 export { taxYearFileName };
 

package/dist/app/lib/provenance-data.js

@@ -11,10 +11,10 @@
 // stamped by any of the three surfaces carries the same values.
 
 export const PROVENANCE_DATA = {
-  "formatVersion": "diya-gl-books/1",
-  "engineVersion": "1.1.2+25fe6af937aa",
+  "formatVersion": "diya-gl/1",
+  "engineVersion": "1.2.0+a39469f30c42",
   "taxDataHash": "6a9c036b5f9c",
-  "reconciledCommit": "",
+  "reconciledCommit": "320b4b8a1585e16fa170c2d312c14df38d0bcf5b",
   "templates": {
     "bst": {
       "hash": "0d003e10e00c",

package/dist/app/lib/provenance.js

@@ -18,7 +18,7 @@ import { PROVENANCE_DATA } from "./provenance-data.js";
 
 // The same schema-name-to-product-id mapping xlsx-exporter.js's
 // productIdOf() carries, kept as a small map of its own rather than an
-// import: report-serializer.js and books-interchange.js both reach this
+// import: report-serializer.js and diya-gl-interchange.js both reach this
 // module from one side of a cycle through xlsx-exporter.js (which itself
 // imports scenario-extractor.js), and a static import back into
 // xlsx-exporter.js from here closes that cycle -- a genuine circular ESM

package/dist/app/lib/report-serializer.js

@@ -299,7 +299,7 @@ function checkEntries(checks) {
     const entry = {
       key: `check/${check.name}${seen > 1 ? `#${seen}` : ""}`,
       unit: "verdict",
-      value: check.pass ? "pass" : "fail",
+      value: check.pass ? "pass" : check.severity === "warning" ? "warn" : "fail",
     };
     const expected = canonicalValue(check.expected);
     const actual = canonicalValue(check.actual);

package/dist/app/lib/xlsx-exporter.js

@@ -2737,7 +2737,7 @@ function transactionRegionIndex() {
  *
  * bstExtractionMap() is the BST caller's own name for this factory, kept so
  * the books page (which calls it directly, by this name, through
- * books-engine.js) does not have to change here; the four multi-file
+ * diya-gl-engine.js) does not have to change here; the four multi-file
  * extractors below build the same shape for SE and Ltd.
  * @param {string} [bookFieldProduct] - which product's bookFieldCells() the
  *   field-lookup half answers from; defaults to "bst", this factory's first

package/dist/app/products/se.js

@@ -1339,6 +1339,16 @@ export function standardReads() {
       // months that traded and tie the projected year to the actual one.
       9,
       38,
+      // Materials after the stock adjustment, wages and staff costs, bank
+      // interest paid and finance charges: the only rows an ITSA quarterly
+      // update needs a monthly split for that the netting table above does
+      // not already carry (row 14 mixes a stock movement into its own
+      // closing-month cell, row 21 mixes a payroll addback, and rows 30/31
+      // come off the bank books rather than a purchases analysis column).
+      14,
+      21,
+      30,
+      31,
     ]),
   ];
   reads["Profit & Loss Account"] = reads["Profit & Loss Account"] || [];
@@ -1878,9 +1888,14 @@ export function categoryNetting(results, scenario) {
 export function checkCompliance(results, expected, taxData, calculateExpectedTax, packageYearEnd) {
   const checks = [];
 
-  function check(name, actual, expectedVal, tolerance = 1) {
+  // A fourth, optional argument marks a check "warning": the shipped
+  // template genuinely diverges from the figure named here and no fixture
+  // closes the gap, so the report is asked to carry the divergence rather
+  // than fail outright. The diff column is what a hand computation would
+  // call the size of that gap.
+  function check(name, actual, expectedVal, tolerance = 1, severity) {
     const pass = Math.abs(actual - expectedVal) <= tolerance;
-    checks.push({ name, actual, expected: expectedVal, pass, diff: actual - expectedVal, tolerance });
+    checks.push({ name, actual, expected: expectedVal, pass, diff: actual - expectedVal, tolerance, severity });
   }
 
   // The same whole-year shift cellWrites applies before writing a posting
@@ -2243,6 +2258,56 @@ export function checkCompliance(results, expected, taxData, calculateExpectedTax
       check(`SA103F ${caption} (${cell}) = the profit and loss account`, num(seFull[cell]), plFigure);
     }
 
+    // Box 44 is row 34 alone, so a loss on the disposal of an asset (row 33)
+    // stays inside box 29's allowable total with nothing moved to a
+    // disallowable box, even though a loss on disposal is not an allowable
+    // deduction: the balancing allowance in box 56 is what relieves it. The
+    // template has no fix available -- this warns of the gap rather than
+    // failing on it, carrying the loss itself as the size of what box 44
+    // leaves out.
+    check(
+      "SA103F box 44 disallowable depreciation (O114) leaves the loss on disposal (row 33) out of the disallowable total that box 29 (D114) carries",
+      num(seFull.O114),
+      num(seFull.D114),
+      0.01,
+      "warning",
+    );
+
+    // VitalTax pools rows 5 to 7 for its own annual sales figure; box 15
+    // pools rows 5 to 8, the extra row being sales coded "d" ("Other
+    // Income" on the P&L, despite the name a turnover line). A trader
+    // reading VitalTax as a running total of the year's turnover would
+    // undercount it by that row. The shipped template has no fix
+    // available -- this warns of the gap rather than failing, carrying
+    // the excluded row as the size of the gap.
+    if (vt) {
+      check(
+        "VitalTax annual sales (G5) excludes the Other Income sales that SA103F box 15 (D55) includes",
+        num(vt.G5),
+        num(seFull.D55),
+        0.01,
+        "warning",
+      );
+
+      // VitalTax's own other-income row sums three P&L rows together --
+      // Other Income (turnover), Investment Grants and Interest received --
+      // where SA103F keeps them apart: the grants reach box 75 (O204), not
+      // box 16 (O55). A trader reading VitalTax's other-income row as a
+      // quarterly "other business income" figure would carry the grants
+      // there too, double-counting them against the annual return. The
+      // Other Income row's own contribution is anchored on the scenario's
+      // own sales coded "d" rather than on the P&L cell it feeds, so a
+      // wrong Other Income line cannot hide inside this check.
+      const otherIncomeSales = journalTotalsByCode(expected.sales, rate, "a").net.d || 0;
+      check(
+        "VitalTax other income (rows 8, 11 and 38 folded together) treats Investment Grants as ordinary other income, while SA103F reports them apart at box 75 (O204) rather than box 16 (O55)",
+        num(pl.B8) + num(pl.B11) + num(pl.B38),
+        num(seFull.O55) + otherIncomeSales,
+        0.01,
+        "warning",
+      );
+    }
+
     // The form's own arithmetic, each total against the boxes it adds up.
     check(
       "SA103F box 57 total capital allowances (O154) = boxes 49 to 56",

package/dist/web/spreadsheets.diyaccounting.co.uk/public/schema/diya-gl-book-v2.schema.json

@@ -75,7 +75,7 @@
         },
         "diya-gl:formatVersion": {
           "type": "string",
-          "description": "diya-gl: extension — The diya-gl-books format name and version this file is written as, e.g. \"diya-gl-books/1\"."
+          "description": "diya-gl: extension — The diya-gl format name and version this file is written as, e.g. \"diya-gl/1\"."
         },
         "diya-gl:engineVersion": {
           "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diy-accounting-uk/diya-gl",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "type": "module",
   "description": "Recalculate, read and write DIYA-GL books from the command line",
   "license": "Apache-2.0",