@fin.cx/chartdata 2.16.0 → 3.0.0

package/dist_ts/index.d.ts

@@ -4,3 +4,5 @@ export * from './chartdata.hgb.js';
 export * from './chartdata.euer.js';
 export { SKR03_2026 } from './data/skr03.2026.js';
 export { SKR04_2026 } from './data/skr04.2026.js';
+export * from './chartdata.individual.js';
+export { DATEV_NUMBERS_SKR03_2026, DATEV_NUMBERS_SKR04_2026 } from './data/datevnumbers.2026.js';

package/dist_ts/index.js

@@ -4,4 +4,6 @@ export * from './chartdata.hgb.js';
 export * from './chartdata.euer.js';
 export { SKR03_2026 } from './data/skr03.2026.js';
 export { SKR04_2026 } from './data/skr04.2026.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUNsRCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sc0JBQXNCLENBQUMifQ==
+export * from './chartdata.individual.js';
+export { DATEV_NUMBERS_SKR03_2026, DATEV_NUMBERS_SKR04_2026 } from './data/datevnumbers.2026.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUNsRCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDbEQsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxPQUFPLEVBQUUsd0JBQXdCLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/chartdata",
-  "version": "2.16.0",
+  "version": "3.0.0",
   "private": false,
   "description": "Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, UStVA-Kennzahl and Anlage EÜR mappings",
   "main": "dist_ts/index.js",

package/readme.md

@@ -33,6 +33,11 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
   accounts), the costs of a sale, write-downs and write-ups, the taxes withheld
   from their income and the margin interest, listed per chart by
   `getAccountsBySecuritiesRole` and found one by one with `getSecuritiesAccount`
+- Payroll accounts with their payroll role (`payrollRole`): the pay and the
+  flat wage taxes (GuV 6a), the employer's contributions (GuV 6b), the debts
+  of a payroll until they are paid, the company-car benefit and the levy
+  refunds, and the clearing account, one account per role, found with
+  `getPayrollAccount`
 - DATEV's mark "HB" (`commercialOnly`): an account posted in the commercial
   balance sheet only
 - The tax rule an income or expense account is kept for (`taxRule`):
@@ -43,6 +48,11 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
   (§ 4 Abs. 3 EStG, § 60 Abs. 4 EStDV), with the lines of the 2025 and 2026
   forms (`ANLAGE_EUER_FORMS`); every account maps or is excluded with its
   reason (`euerExclusion`)
+- Individual accounts (Individualkonten): the books' own accounts on the
+  numbers DATEV leaves free after an account, inheriting that account's
+  mappings (`BooksChart`, `individualAccountProblemsOf`, `freeNumbersOf`),
+  checked against the numbers the DATEV Kontenrahmen assigns and reserves
+  (`getDatevNumbers`)
 - Coverage introspection that fails loudly on mapping gaps
 - Provenance on every record
 
@@ -142,6 +152,142 @@ sale other expenses (Kz 183), write-downs and write-ups values at a closing date
 interest-like expenses other debt interest (Kz 234), and the taxes on income a
 withdrawal (Kz 122, § 12 Nr. 3 EStG).
 
+DATEV holds no account of its own for options bought or written, a future's
+variation margin, accrued interest bought with a bond, securities lent or sold
+short, the cash collateral of a loan of securities, the results of
+Termingeschäfte, a writer's premium earned, a short sale's result and the
+compensations paid on securities sold short. Their roles (`options_held`,
+`variation_margin_paid`, `variation_margin_received`, `accrued_interest_claim`,
+`lending_claim`, `written_options`, `short_sale_obligations`,
+`collateral_received`, `termingeschaeft_gain`, `termingeschaeft_loss`,
+`stillhalter_income`, `short_sale_gain`, `short_sale_loss`,
+`compensation_paid`) name no account of the standard charts: the books give
+them an individual account, or book them on the account of their position.
+
+### Payroll
+
+A payroll run finds its accounts by the payroll role; within a chart each role
+names one account, and every role has its account in both standard charts.
+DATEV states each account's position beside it: the pay under "Löhne und
+Gehälter" (GuV 6a, § 275 Abs. 2 Nr. 6 a HGB), the employer's contributions
+under "Soziale Abgaben und Aufwendungen für Altersversorgung und für
+Unterstützung" (GuV 6b). DATEV's collective accounts (SKR03 4100, SKR04 6000
+and 6100) keep their positions and take no role.
+
+```typescript
+import { getPayrollAccount } from '@fin.cx/chartdata';
+
+getPayrollAccount('SKR03', 2026, 'salaries')?.accountNumber; // '4120' Gehälter
+getPayrollAccount('SKR04', 2026, 'wage_tax')?.accountNumber; // '3730' Verbindlichkeiten aus Lohn- und Kirchensteuer
+getPayrollAccount('SKR04', 2026, 'company_car_benefit')?.ustva; // { kennzahl: 81, role: 'base' }
+```
+
+| Role | What it books | SKR03 | SKR04 |
+| --- | --- | --- | --- |
+| `wages` | Löhne (GuV 6a) | 4110 | 6010 |
+| `salaries` | Gehälter (GuV 6a) | 4120 | 6020 |
+| `managing_director_salaries` | a GmbH's shareholder-managing directors (GuV 6a) | 4124 | 6024 |
+| `temporary_wages` | Aushilfslöhne (GuV 6a) | 4190 | 6030 |
+| `minijob_wages` | Löhne für Minijobs (GuV 6a) | 4195 | 6035 |
+| `benefits_in_kind` | Sachzuwendungen und Dienstleistungen an Arbeitnehmer (GuV 6a) | 4152 | 6072 |
+| `capital_formation_benefits` | vermögenswirksame Leistungen (GuV 6a) | 4170 | 6080 |
+| `commuting_allowances` | Fahrtkostenerstattung Wohnung/Arbeitsstätte (GuV 6a) | 4175 | 6090 |
+| `minijob_flat_tax` | the flat tax of a Minijob (GuV 6a) | 4194 | 6036 |
+| `employee_flat_tax` | the flat tax for employees (GuV 6a) | 4198 | 6039 |
+| `temporary_flat_tax` | the flat tax for temporary staff (GuV 6a) | 4199 | 6040 |
+| `employer_social_security` | the employer's contributions and the levies U1, U2, U3 (GuV 6b) | 4130 | 6110 |
+| `minijob_social_security` | the flat contributions of a Minijob (GuV 6b) | 4144 | 6171 |
+| `accident_insurance` | Berufsgenossenschaft (GuV 6b) | 4138 | 6120 |
+| `pension` | Aufwendungen für Altersversorgung (GuV 6b) | 4165 | 6140 |
+| `pension_flat_tax` | the flat tax on such benefits, Direktversicherungen (GuV 6b) | 4167 | 6147 |
+| `company_car_benefit` | the private use of a company car, 19 % VAT, UStVA Kz 81 (GuV 4) | 8611 | 4947 |
+| `levy_refunds` | Erstattungen nach dem Aufwendungsausgleichsgesetz (GuV 4) | 2749 | 4972 |
+| `levy_refund_claims` | the claim on the health insurer for them | 1520 | 1369 |
+| `net_pay` | the net pay owed | 1740 | 3720 |
+| `wage_tax` | wage tax, church tax and Solidaritätszuschlag owed | 1741 | 3730 |
+| `social_security` | the contributions owed | 1742 | 3740 |
+| `employee_withholdings` | what is withheld from an employee for another (a garnishment) | 1748 | 3725 |
+| `capital_formation_payable` | the savings an employee's contract receives | 1750 | 3770 |
+| `estimated_contributions` | the contributions estimated when due (§ 23 Abs. 1 SGB IV) | 1759 | 3759 |
+| `clearing` | the Lohn- und Gehaltsverrechnungskonto | 1755 | 3790 |
+
+In the Anlage EÜR every payroll expense is Zeile 31 (Kz 120), "einschließlich
+der gezahlten Lohnsteuer (auch Pauschalsteuer nach § 37b EStG) und anderer
+Nebenkosten" (Anleitung 2026); the company-car benefit is a taxable receipt
+(Kz 112), the levy refunds a non-taxable one (Kz 103). An individual account
+takes no payroll role: a role names the DATEV account.
+
+### Individual accounts
+
+The books may set up accounts of their own (Individualkonten) on the numbers
+the DATEV standard chart leaves free after one of its accounts. DATEV leaves
+those numbers for the account's own sub-accounts and passes the account's
+marks for its trade and corporate income tax programs ("G", "K") on to them, up
+to the next account of the standard chart (DATEV Kontenrahmen, Erläuterungen,
+S. 37). So an individual account belongs to the account it follows, its
+parent, and is what the parent is: its type, its HGB position, its UStVA and
+Anlage EÜR mapping, its account role, its tax rule and DATEV's mark "HB".
+Where the declaration changes one of them deliberately (`overrides`: a value
+replaces the parent's, `null` drops it), the provenance names it. It does not
+take the parent's tax automatism or BU-key rules, which DATEV applies only to
+the accounts it marks, nor its securities role, which names one account of a
+chart: an individual account books a securities role only where its
+declaration names one.
+
+The declarations are the books'; this package stores none. The validator
+refuses a declaration whose number:
+
+- has no four digits;
+- is one DATEV assigns or reserves, or one this package holds;
+- another declaration takes too;
+- has no name;
+- has a parent this package does not hold, or a parent that is itself an
+  individual account;
+- has a carry-forward, closing or statistical account as its parent;
+- lies in another account class than its parent;
+- does not follow its parent (another account of the chart stands between
+  them);
+- takes a securities role another account books under the same tax rule;
+- or has an override that names no HGB position, or one its type does not
+  take (a balance-sheet account has a balance-sheet position, a
+  profit-and-loss account an income-statement position), an Anlage EÜR line no
+  form year holds or a split line on the other side, or both a line and an
+  exclusion.
+
+```ts
+import { BooksChart, freeNumbersOf, individualAccountProblemsOf, type IIndividualAccountDeclaration } from '@fin.cx/chartdata';
+
+freeNumbersOf('SKR03', 2026, '2700'); // ['2701', '2702', '2703', '2704']
+freeNumbersOf('SKR04', 2026, '4905'); // []: DATEV's 4906 (§ 8b KStG) follows at once
+
+const declarations: IIndividualAccountDeclaration[] = [
+  { accountNumber: '2701', accountName: 'Erträge aus Termingeschäften', parentAccountNumber: '2700', securitiesRole: 'termingeschaeft_gain' },
+  { accountNumber: '2301', accountName: 'Verluste aus Termingeschäften', parentAccountNumber: '2300', securitiesRole: 'termingeschaeft_loss' },
+];
+individualAccountProblemsOf('SKR03', 2026, declarations); // []
+
+const books = BooksChart.of('SKR03', 2026, declarations); // throws IndividualAccountsError on problems
+books.getSecuritiesAccount('termingeschaeft_gain')?.accountNumber; // '2701'
+books.getAccount('2701')?.hgb275Position; // 'GuV 4', as 2700
+books.getMappingCoverage(usedAccountNumbers, 'hgb275');
+```
+
+A `BooksChart` is a chart (`IChart`) with the lookups of the chart over the
+DATEV accounts and the books' own: `getAccount`, `getAccountsByRole`,
+`getAccountsBySecuritiesRole`, `getSecuritiesAccount`, `getPayrollAccount`,
+`getMappingCoverage`, `getEuerLines`.
+
+`INDIVIDUAL_ACCOUNT_TEMPLATES` suggests the parent and name of the results the
+law keeps apart: the gains and losses of Termingeschäfte, which § 15 Abs. 4
+Satz 3 EStG offsets only against each other, under the other operating income
+and expenses, and beside them a writer's premium earned, a short sale's gain
+and loss and the compensations paid on securities sold short. SKR 03 leaves
+four numbers after 2700 and six after 2300, enough for all six; SKR 04 leaves
+one after 4830 and one after 6300, so there the Termingeschäfte take them and
+the books decide with their advisor where the others go. DATEV's ranges "zur
+freien Verfügung" (SKR 03 8000–8099, SKR 04 4000–4099 and others) count as
+assigned until this package holds the positions DATEV gives them.
+
 ### Anlage EÜR
 
 Every account of a chart either maps to the Anlage EÜR or is excluded from it
@@ -227,9 +373,18 @@ on an account without an EÜR decision, and on a Kennzahl or side a form year
 does not hold. E-Bilanz (de-gaap-ci) positions are not populated yet —
 `getMappingCoverage(..., 'ebilanz')` reports them as missing by design.
 
+The numbers the DATEV Kontenrahmen assigns and reserves (`getDatevNumbers`)
+are read from the text of the SKR 03 and SKR 04 PDFs, gültig für 2026, as
+`pdfjs` lays it out (one line per row, each item with its x position; the
+extraction script and the texts stay in the untracked `.nogit/`): every
+number DATEV lists, with the marks before it, the groups it lists under one
+designation ("AM 8400" … "-09") and the reserved ("R"). The tool checks that
+every account this package holds from the Kontenrahmen is among them.
+
 The generation pipeline lives in the unpublished `tools/` directory
-(`tsx tools/generate-charts.ts <oracle csvs>`); datasets are generated files —
-extend the curated table in the tool, never edit `ts/data/*` by hand.
+(`tsx tools/generate-charts.ts <oracle csvs>`, `tsx tools/generate-datev-numbers.ts <skr03 text> <skr04 text>`);
+datasets are generated files — extend the curated table in the tool, never
+edit `ts/data/*` by hand.
 
 ## Development
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/chartdata',
-  version: '2.16.0',
+  version: '3.0.0',
   description: 'Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, UStVA-Kennzahl and Anlage EÜR mappings'
 }

package/ts/chartdata.hgb.ts

@@ -65,7 +65,9 @@ export const HGB_275_GKV_POSITIONS: IHgbPosition[] = [
   { key: 'GuV 3', label: 'Andere aktivierte Eigenleistungen' },
   { key: 'GuV 4', label: 'Sonstige betriebliche Erträge' },
   { key: 'GuV 5', label: 'Materialaufwand' },
-  { key: 'GuV 6', label: 'Personalaufwand' },
+  // Nr. 6 Personalaufwand, by its two parts
+  { key: 'GuV 6a', label: 'Löhne und Gehälter' },
+  { key: 'GuV 6b', label: 'Soziale Abgaben und Aufwendungen für Altersversorgung und für Unterstützung' },
   { key: 'GuV 7', label: 'Abschreibungen' },
   { key: 'GuV 8', label: 'Sonstige betriebliche Aufwendungen' },
   { key: 'GuV 9', label: 'Erträge aus Beteiligungen' },

package/ts/chartdata.individual.ts

@@ -0,0 +1,321 @@
+import type {
+  IChart,
+  IChartAccount,
+  IDatevNumbers,
+  IIndividualAccountDeclaration,
+  IIndividualAccountProblem,
+  IIndividualAccountTemplate,
+  IMappingCoverage,
+  TAccountRole,
+  TChartName,
+  TEuerAccountLines,
+  TMappingDimension,
+  TPayrollRole,
+  TSecuritiesRole,
+  TTaxRule,
+} from './chartdata.types.js';
+import { euerLinesOf, getEuerFormLine, listEuerFormYears, type IEuerLinesOptions } from './chartdata.euer.js';
+import { HGB_266_POSITIONS, HGB_275_GKV_POSITIONS } from './chartdata.hgb.js';
+import { getChart, mappingCoverageOf } from './chartdata.lookup.js';
+import { DATEV_NUMBERS_SKR03_2026, DATEV_NUMBERS_SKR04_2026 } from './data/datevnumbers.2026.js';
+
+const DATEV_NUMBERS: IDatevNumbers[] = [DATEV_NUMBERS_SKR03_2026, DATEV_NUMBERS_SKR04_2026];
+
+/**
+ * The numbers the DATEV standard chart of a year assigns and reserves, as read from the DATEV Kontenrahmen. Throws
+ * for an unknown chart or year, as `getChart`.
+ */
+export function getDatevNumbers(chart: TChartName, year: number): IDatevNumbers {
+  const found = DATEV_NUMBERS.find((numbers) => numbers.chart === chart && numbers.year === year);
+  if (!found) {
+    throw new Error(`No DATEV numbers of ${chart} for year ${year}`);
+  }
+  return found;
+}
+
+/** Whether DATEV assigns or reserves the number in the chart of the year. */
+export function isDatevNumber(chart: TChartName, year: number, accountNumber: string): boolean {
+  return getDatevNumbers(chart, year).assigned.includes(accountNumber);
+}
+
+/**
+ * Suggestions for the individual accounts of the results the law keeps apart, which DATEV's standard charts hold
+ * no account of their own for: the results of Termingeschäfte, whose losses § 15 Abs. 4 Satz 3 EStG offsets only
+ * against such gains, under the other operating income and expenses; beside them a writer's premium earned, a
+ * short sale's gain and loss and the compensations paid on securities sold short, which an advisor should see
+ * apart. Each follows its parent in the free numbers DATEV leaves after it (`freeNumbersOf`): SKR 03 leaves four
+ * after 2700 and six after 2300, SKR 04 one after 4830 and one after 6300, so in SKR 04 the books give the
+ * Termingeschäfte those two and choose with their advisor where the others go. The books choose the numbers.
+ */
+export const INDIVIDUAL_ACCOUNT_TEMPLATES: Readonly<Record<TChartName, readonly IIndividualAccountTemplate[]>> = {
+  SKR03: templates('2700', '2300'),
+  SKR04: templates('4830', '6300'),
+};
+
+function templates(otherIncomeArg: string, otherExpenseArg: string): IIndividualAccountTemplate[] {
+  const of = (securitiesRole: TSecuritiesRole, parentAccountNumber: string, accountName: string): IIndividualAccountTemplate => ({ securitiesRole, parentAccountNumber, accountName });
+  return [
+    of('termingeschaeft_gain', otherIncomeArg, 'Erträge aus Termingeschäften (§ 15 Abs. 4 Satz 3 EStG)'),
+    of('termingeschaeft_loss', otherExpenseArg, 'Verluste aus Termingeschäften (§ 15 Abs. 4 Satz 3 EStG)'),
+    of('stillhalter_income', otherIncomeArg, 'Erträge aus Stillhalterprämien'),
+    of('short_sale_gain', otherIncomeArg, 'Erträge aus Leerverkäufen'),
+    of('short_sale_loss', otherExpenseArg, 'Aufwendungen aus Leerverkäufen'),
+    of('compensation_paid', otherExpenseArg, 'Kompensationszahlungen aus Leerverkäufen'),
+  ];
+}
+
+/**
+ * The numbers free for an individual account under a parent: those after it in its account class up to the next
+ * account of the chart (DATEV's or chartdata's), less those the books' declarations take, in order. Throws for an
+ * unknown chart, year or parent.
+ */
+export function freeNumbersOf(
+  chart: TChartName,
+  year: number,
+  parentAccountNumber: string,
+  declarations: readonly IIndividualAccountDeclaration[] = [],
+): string[] {
+  const standard = getChart(chart, year);
+  if (!standard.accounts.some((account) => account.accountNumber === parentAccountNumber)) {
+    throw new Error(`${chart} ${year} holds no account ${parentAccountNumber}`);
+  }
+  const taken = new Set(declarations.map((declaration) => declaration.accountNumber));
+  return followingNumbersOf(chart, year, parentAccountNumber).filter((number) => !taken.has(number));
+}
+
+/** The numbers of the chart's accounts, DATEV's and chartdata's. */
+function occupiedNumbersOf(chartArg: TChartName, yearArg: number): Set<string> {
+  return new Set([...getDatevNumbers(chartArg, yearArg).assigned, ...getChart(chartArg, yearArg).accounts.map((account) => account.accountNumber)]);
+}
+
+/** The account of the chart a number above another account follows: the next below it. */
+function precedingNumberOf(chartArg: TChartName, yearArg: number, numberArg: string): string {
+  const occupied = occupiedNumbersOf(chartArg, yearArg);
+  let value = Number(numberArg) - 1;
+  while (!occupied.has(String(value).padStart(4, '0'))) value--;
+  return String(value).padStart(4, '0');
+}
+
+/** The numbers after an account in its class up to the next account of the chart, DATEV's or chartdata's. */
+function followingNumbersOf(chartArg: TChartName, yearArg: number, accountNumberArg: string): string[] {
+  const occupied = occupiedNumbersOf(chartArg, yearArg);
+  const following: string[] = [];
+  for (let value = Number(accountNumberArg) + 1; value <= 9999; value++) {
+    const number = String(value).padStart(4, '0');
+    if (occupied.has(number) || number[0] !== accountNumberArg[0]) break;
+    following.push(number);
+  }
+  return following;
+}
+
+/** Everything that keeps the books' individual accounts from being accounts of the chart; an empty list means none. */
+export function individualAccountProblemsOf(
+  chart: TChartName,
+  year: number,
+  declarations: readonly IIndividualAccountDeclaration[],
+): IIndividualAccountProblem[] {
+  const standard = getChart(chart, year);
+  const byNumber = new Map(standard.accounts.map((account) => [account.accountNumber, account]));
+  const assigned = new Set(getDatevNumbers(chart, year).assigned);
+  const declared = new Map<string, number>();
+  for (const declaration of declarations) declared.set(declaration.accountNumber, (declared.get(declaration.accountNumber) ?? 0) + 1);
+  const problems: IIndividualAccountProblem[] = [];
+  const add = (accountNumber: string, code: IIndividualAccountProblem['code'], message: string): void => {
+    problems.push({ accountNumber, code, message });
+  };
+  // the securities roles and tax rules the chart's own accounts book
+  const roles = new Map<string, string>();
+  for (const account of standard.accounts) {
+    if (account.securitiesRole) roles.set(`${account.securitiesRole}:${account.taxRule ?? ''}`, account.accountNumber);
+  }
+  for (const declaration of declarations) {
+    const number = declaration.accountNumber;
+    if (!/^\d{4}$/.test(number)) {
+      add(number, 'number_invalid', `${number} is no account number of four digits`);
+      continue;
+    }
+    if (assigned.has(number)) add(number, 'number_assigned', `DATEV assigns or reserves ${number} in ${chart} ${year}`);
+    else if (byNumber.has(number)) add(number, 'number_assigned', `${chart} ${year} holds an account ${number}`);
+    if ((declared.get(number) ?? 0) > 1) add(number, 'number_duplicate', `${number} is declared more than once`);
+    if (declaration.accountName.trim() === '') add(number, 'name_missing', `${number} has no name`);
+    const parent = byNumber.get(declaration.parentAccountNumber);
+    if (!parent) {
+      add(
+        number,
+        declared.has(declaration.parentAccountNumber) ? 'parent_individual' : 'parent_unknown',
+        declared.has(declaration.parentAccountNumber)
+          ? `the parent ${declaration.parentAccountNumber} is itself an individual account; an individual account belongs to a DATEV account`
+          : `${chart} ${year} holds no account ${declaration.parentAccountNumber}`,
+      );
+      continue;
+    }
+    if (parent.euerExclusion === 'closing') {
+      add(number, 'parent_not_allowed', `the parent ${parent.accountNumber} (${parent.accountName}) is a carry-forward, closing or statistical account`);
+    }
+    if (number[0] !== parent.accountNumber[0]) {
+      add(number, 'class_mismatch', `${number} lies in account class ${number[0]}, its parent ${parent.accountNumber} in class ${parent.accountNumber[0]}`);
+    } else if (!assigned.has(number) && !byNumber.has(number) && !followingNumbersOf(chart, year, parent.accountNumber).includes(number)) {
+      add(
+        number,
+        'not_following_parent',
+        number < parent.accountNumber
+          ? `${number} lies before its parent ${parent.accountNumber}; an individual account follows it`
+          : `${number} follows ${precedingNumberOf(chart, year, number)}, not its parent ${parent.accountNumber}: DATEV passes the marks of the account a number follows on to it`,
+      );
+    }
+    const overrides = declaration.overrides ?? {};
+    const profitAndLoss = parent.accountType === 'revenue' || parent.accountType === 'expense';
+    if (typeof overrides.hgb266Position === 'string') {
+      if (!HGB_266_POSITIONS.some((position) => position.key === overrides.hgb266Position)) {
+        add(number, 'override_invalid', `${overrides.hgb266Position} is no balance-sheet position of § 266 HGB`);
+      } else if (profitAndLoss) {
+        add(number, 'override_invalid', `a balance-sheet position for ${number}, whose parent ${parent.accountNumber} is a profit-and-loss account (${parent.accountType})`);
+      }
+    }
+    if (typeof overrides.hgb275Position === 'string') {
+      if (!HGB_275_GKV_POSITIONS.some((position) => position.key === overrides.hgb275Position)) {
+        add(number, 'override_invalid', `${overrides.hgb275Position} is no income-statement position of § 275 Abs. 2 HGB`);
+      } else if (!profitAndLoss) {
+        add(number, 'override_invalid', `an income-statement position for ${number}, whose parent ${parent.accountNumber} is a balance-sheet account (${parent.accountType})`);
+      }
+    }
+    if (overrides.euer !== undefined && overrides.euerExclusion !== undefined) {
+      add(number, 'override_invalid', 'an account maps to the Anlage EÜR or is excluded from it, not both');
+    }
+    if (overrides.euer !== undefined) {
+      // a line of every form year; a split's debit on a line that counts debits, its credit on one that counts credits
+      const lines: Array<[number, 'debit' | 'credit' | undefined]> = 'kennzahl' in overrides.euer
+        ? [[overrides.euer.kennzahl, undefined]]
+        : [[overrides.euer.debitKennzahl, 'debit'], [overrides.euer.creditKennzahl, 'credit']];
+      for (const [kennzahl, side] of lines) {
+        for (const formYear of listEuerFormYears()) {
+          let line: ReturnType<typeof getEuerFormLine>;
+          try {
+            line = getEuerFormLine(formYear, kennzahl);
+          } catch {
+            add(number, 'override_invalid', `Kz ${kennzahl} is no line of the Anlage EÜR ${formYear}`);
+            continue;
+          }
+          if (side !== undefined && line.side !== side) {
+            add(number, 'override_invalid', `Kz ${kennzahl} counts ${line.side}s in the Anlage EÜR ${formYear}, not the ${side}s of a split`);
+          }
+        }
+      }
+    }
+    if (declaration.securitiesRole !== undefined) {
+      const taxRule = overrides.taxRule === undefined ? parent.taxRule : overrides.taxRule ?? undefined;
+      const key = `${declaration.securitiesRole}:${taxRule ?? ''}`;
+      const holder = roles.get(key);
+      if (holder !== undefined) add(number, 'role_taken', `${holder} already books ${declaration.securitiesRole}${taxRule ? ` under ${taxRule}` : ''}`);
+      else roles.set(key, number);
+    }
+  }
+  return problems;
+}
+
+/** Thrown where the books' individual accounts cannot be accounts of the chart; `problems` says why. */
+export class IndividualAccountsError extends Error {
+  constructor(public readonly problems: IIndividualAccountProblem[]) {
+    super(`individual accounts refused: ${problems.map((problem) => `${problem.accountNumber} ${problem.code}`).join(', ')}`);
+    this.name = 'IndividualAccountsError';
+  }
+}
+
+/** An individual account as an account of the chart: what its parent is, as its declaration changes it. */
+function individualAccountOf(parentArg: IChartAccount, declarationArg: IIndividualAccountDeclaration, yearArg: number): IChartAccount {
+  const overrides = declarationArg.overrides ?? {};
+  const pick = <T>(inherited: T | undefined, override: T | null | undefined): T | undefined => (override === undefined ? inherited : override ?? undefined);
+  const hgb266Position = pick(parentArg.hgb266Position, overrides.hgb266Position);
+  const hgb275Position = pick(parentArg.hgb275Position, overrides.hgb275Position);
+  const ustva = pick(parentArg.ustva, overrides.ustva);
+  const accountRole = pick<TAccountRole>(parentArg.accountRole, overrides.accountRole);
+  const taxRule = pick<TTaxRule>(parentArg.taxRule, overrides.taxRule);
+  const commercialOnly = pick<true>(parentArg.commercialOnly, overrides.commercialOnly);
+  const euerFromOverride = overrides.euer !== undefined || overrides.euerExclusion !== undefined;
+  const euer = euerFromOverride ? overrides.euer : parentArg.euer;
+  const euerExclusion = euerFromOverride ? overrides.euerExclusion : parentArg.euerExclusion;
+  return {
+    accountNumber: declarationArg.accountNumber,
+    accountName: declarationArg.accountName,
+    accountClass: Number.parseInt(declarationArg.accountNumber[0]!, 10),
+    accountType: parentArg.accountType,
+    ...(accountRole ? { accountRole } : {}),
+    ...(declarationArg.securitiesRole ? { securitiesRole: declarationArg.securitiesRole } : {}),
+    ...(taxRule ? { taxRule } : {}),
+    ...(commercialOnly ? { commercialOnly } : {}),
+    ...(ustva ? { ustva } : {}),
+    ...(hgb266Position ? { hgb266Position } : {}),
+    ...(hgb275Position ? { hgb275Position } : {}),
+    ...(parentArg.ebilanzPosition ? { ebilanzPosition: parentArg.ebilanzPosition } : {}),
+    ...(euer ? { euer } : {}),
+    ...(euerExclusion ? { euerExclusion } : {}),
+    parentAccountNumber: parentArg.accountNumber,
+    provenance: `individual account of the books under ${parentArg.accountNumber} (${parentArg.accountName})${Object.keys(overrides).length > 0 ? `; overrides ${Object.keys(overrides).sort().join(', ')}` : ''}`,
+    validFrom: yearArg,
+  };
+}
+
+/**
+ * A chart of a year with the books' individual accounts: the lookups of the chart over its DATEV accounts and the
+ * books' own. Built by `BooksChart.of`, which refuses declarations with problems (`IndividualAccountsError`).
+ */
+export class BooksChart implements IChart {
+  public readonly chart: TChartName;
+  public readonly year: number;
+  public readonly accounts: IChartAccount[];
+  public readonly individualAccounts: IChartAccount[];
+  private readonly byNumber: Map<string, IChartAccount>;
+
+  private constructor(chartArg: TChartName, yearArg: number, individualArg: IChartAccount[]) {
+    this.chart = chartArg;
+    this.year = yearArg;
+    this.individualAccounts = individualArg;
+    this.accounts = [...getChart(chartArg, yearArg).accounts, ...individualArg].sort((a, b) => a.accountNumber.localeCompare(b.accountNumber));
+    this.byNumber = new Map(this.accounts.map((account) => [account.accountNumber, account]));
+  }
+
+  /** The chart of the year with the books' individual accounts; throws `IndividualAccountsError` for declarations with problems. */
+  public static of(chartArg: TChartName, yearArg: number, declarationsArg: readonly IIndividualAccountDeclaration[] = []): BooksChart {
+    const problems = individualAccountProblemsOf(chartArg, yearArg, declarationsArg);
+    if (problems.length > 0) throw new IndividualAccountsError(problems);
+    const standard = getChart(chartArg, yearArg);
+    const parents = new Map(standard.accounts.map((account) => [account.accountNumber, account]));
+    return new BooksChart(
+      chartArg,
+      yearArg,
+      declarationsArg.map((declaration) => individualAccountOf(parents.get(declaration.parentAccountNumber)!, declaration, yearArg)),
+    );
+  }
+
+  /** The account of the number, a DATEV account or one of the books; `null` where there is none. */
+  public getAccount(accountNumberArg: string): IChartAccount | null {
+    return this.byNumber.get(accountNumberArg) ?? null;
+  }
+
+  public getAccountsByRole(roleArg: TAccountRole): IChartAccount[] {
+    return this.accounts.filter((account) => account.accountRole === roleArg);
+  }
+
+  public getAccountsBySecuritiesRole(roleArg: TSecuritiesRole): IChartAccount[] {
+    return this.accounts.filter((account) => account.securitiesRole === roleArg);
+  }
+
+  /** The one account of the books that books the securities role under the tax rule (none: the account without one), or `null`. */
+  public getSecuritiesAccount(roleArg: TSecuritiesRole, taxRuleArg?: TTaxRule): IChartAccount | null {
+    return this.getAccountsBySecuritiesRole(roleArg).find((account) => account.taxRule === taxRuleArg) ?? null;
+  }
+
+  /** The one account of the books that books the payroll role, or `null`; an individual account takes none. */
+  public getPayrollAccount(roleArg: TPayrollRole): IChartAccount | null {
+    return this.accounts.find((account) => account.payrollRole === roleArg) ?? null;
+  }
+
+  public getMappingCoverage(usedAccountsArg: string[], dimensionArg: TMappingDimension): IMappingCoverage {
+    return mappingCoverageOf(this.accounts, usedAccountsArg, dimensionArg);
+  }
+
+  public getEuerLines(accountNumberArg: string, formYearArg: number, optionsArg: IEuerLinesOptions = {}): TEuerAccountLines | null {
+    const account = this.getAccount(accountNumberArg);
+    return account ? euerLinesOf(account, formYearArg, optionsArg) : null;
+  }
+}

package/ts/chartdata.lookup.ts

@@ -7,6 +7,7 @@ import type {
   TChartName,
   TEuerAccountLines,
   TMappingDimension,
+  TPayrollRole,
   TSecuritiesRole,
   TTaxRule,
 } from './chartdata.types.js';
@@ -113,6 +114,14 @@ export function getSecuritiesAccount(
   return getAccountsBySecuritiesRole(chart, year, role).find((account) => account.taxRule === taxRule) ?? null;
 }
 
+/**
+ * The one account of a chart that books the payroll role (`IChartAccount.payrollRole`), or `null` where the chart
+ * keeps none for it. Throws for unknown chart/year combinations, as `getChart`.
+ */
+export function getPayrollAccount(chart: TChartName, year: number, role: TPayrollRole): IChartAccount | null {
+  return getChart(chart, year).accounts.find((account) => account.payrollRole === role) ?? null;
+}
+
 function hasMapping(account: IChartAccount, dimension: TMappingDimension): boolean {
   switch (dimension) {
     case 'ustva':
@@ -138,8 +147,16 @@ export function getMappingCoverage(
   usedAccounts: string[],
   dimension: TMappingDimension,
 ): IMappingCoverage {
-  const dataset = getChart(chart, year);
-  const byNumber = new Map(dataset.accounts.map((account) => [account.accountNumber, account]));
+  return mappingCoverageOf(getChart(chart, year).accounts, usedAccounts, dimension);
+}
+
+/** `getMappingCoverage` over a list of accounts (a chart's, or a chart's with the books' individual accounts). */
+export function mappingCoverageOf(
+  accounts: readonly IChartAccount[],
+  usedAccounts: string[],
+  dimension: TMappingDimension,
+): IMappingCoverage {
+  const byNumber = new Map(accounts.map((account) => [account.accountNumber, account]));
   const missing: string[] = [];
   const unknown: string[] = [];
   let covered = 0;