@fin.cx/chartdata 2.16.0 → 2.17.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": "2.17.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

@@ -43,6 +43,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 +147,89 @@ 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.
+
+### 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`, `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 +315,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: '2.17.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.individual.ts

@@ -0,0 +1,315 @@
+import type {
+  IChart,
+  IChartAccount,
+  IDatevNumbers,
+  IIndividualAccountDeclaration,
+  IIndividualAccountProblem,
+  IIndividualAccountTemplate,
+  IMappingCoverage,
+  TAccountRole,
+  TChartName,
+  TEuerAccountLines,
+  TMappingDimension,
+  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;
+  }
+
+  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

@@ -138,8 +138,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;

package/ts/chartdata.types.ts

@@ -59,6 +59,23 @@ export type TAccountRole = 'asset_sale_proceeds' | 'disposal_book_value';
  *   pending transaction (§ 249 Abs. 1 HGB: a written option worth more than
  *   its premium), which tax law does not allow (§ 5 Abs. 4a EStG);
  * - 'provision_release': the income of a provision released.
+ * The roles DATEV's standard charts hold no account of their own for: the
+ * books book them on the account of their position, or on an individual
+ * account (`IIndividualAccountDeclaration`) where they keep them apart;
+ * `INDIVIDUAL_ACCOUNT_TEMPLATES` suggests the parent of the results the law
+ * keeps apart:
+ * - balances: 'options_held' (options bought, at their premium),
+ *   'variation_margin_paid' and 'variation_margin_received' (a future's or a
+ *   CFD's daily settlement held until it closes), 'accrued_interest_claim'
+ *   (Stückzinsen paid, interest accrued), 'lending_claim' (securities lent:
+ *   the claim to their return), 'written_options' (a writer's obligation at
+ *   the premium received), 'short_sale_obligations' (securities owed after a
+ *   short sale), 'collateral_received' (cash collateral to give back);
+ * - results kept apart: 'termingeschaeft_gain' and 'termingeschaeft_loss'
+ *   (§ 15 Abs. 4 Satz 3 EStG offsets the losses only against such gains),
+ *   'stillhalter_income' (a writer's premium earned), 'short_sale_gain' and
+ *   'short_sale_loss', 'compensation_paid' (payments in place of a dividend
+ *   on securities sold short).
  */
 export type TSecuritiesRole =
   | 'holding_fixed'
@@ -90,7 +107,21 @@ export type TSecuritiesRole =
   | 'borrow_fees'
   | 'writedown_other_current'
   | 'expected_loss_provision'
-  | 'provision_release';
+  | 'provision_release'
+  | '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';
 
 /**
  * A rule of the income tax law an income or expense account is kept for, as
@@ -242,6 +273,8 @@ export interface IChartAccount {
    * are no part of the tax balance sheet; unset = both
    */
   commercialOnly?: true;
+  /** an individual account of the books (`IIndividualAccountDeclaration`): the DATEV account it belongs to; unset = a DATEV account */
+  parentAccountNumber?: string;
   description?: string;
   automatikFunction?: TAutomatikFunction;
   /** BU keys allowed on lines of this account ('' = none). Unset = all. */
@@ -307,3 +340,91 @@ export interface IScenarioKennzahlen {
   inputVatReverseCharge: number; // Kz 67 (Vorsteuer §13b)
   importVat: number; // Kz 62 (entrichtete EUSt)
 }
+
+/** The numbers a DATEV standard chart of a year assigns (listed accounts and headings), and of them those it reserves ("R"). */
+export interface IDatevNumbers {
+  chart: TChartName;
+  year: number;
+  assigned: readonly string[];
+  reserved: readonly string[];
+}
+
+/**
+ * What an individual account changes deliberately of what it inherits from its parent: a value replaces the
+ * parent's, `null` drops it. The Anlage EÜR takes `euer` or `euerExclusion`, not both.
+ */
+export interface IIndividualAccountOverrides {
+  hgb266Position?: string | null;
+  hgb275Position?: string | null;
+  ustva?: IUstvaMapping | null;
+  euer?: TEuerMapping;
+  euerExclusion?: TEuerExclusion;
+  accountRole?: TAccountRole | null;
+  taxRule?: TTaxRule | null;
+  commercialOnly?: true | null;
+}
+
+/**
+ * An account the books set up themselves (an Individualkonto) on a number the DATEV standard chart leaves free,
+ * belonging to one of its accounts (the parent, `parentAccountNumber`): it is what its parent is — its type, its
+ * balance-sheet or income-statement position, its UStVA and Anlage EÜR mapping, its account role, its tax rule
+ * and DATEV's mark "HB" — unless `overrides` changes one deliberately. It does not take the parent's DATEV tax
+ * automatism (DATEV applies one only to the accounts it marks) nor its securities role, which names one account of
+ * a chart: an individual account takes one only where its declaration names it. The declarations are the books';
+ * chartdata stores none.
+ */
+export interface IIndividualAccountDeclaration {
+  accountNumber: string;
+  accountName: string;
+  parentAccountNumber: string;
+  securitiesRole?: TSecuritiesRole;
+  overrides?: IIndividualAccountOverrides;
+}
+
+/**
+ * Why an individual account cannot be:
+ * - `number_invalid`: its number is no four digits;
+ * - `number_assigned`: DATEV assigns or reserves the number in the chart of the year;
+ * - `number_duplicate`: two declarations take the number;
+ * - `name_missing`: the account has no name;
+ * - `parent_unknown`: the chart holds no account of the parent's number;
+ * - `parent_individual`: the parent is itself an individual account;
+ * - `parent_not_allowed`: the parent is a carry-forward, closing or statistical account, which records no business
+ *   transaction;
+ * - `class_mismatch`: the number lies in another account class (its first digit) than the parent;
+ * - `not_following_parent`: the number does not follow its parent: an account of the chart stands between them.
+ *   DATEV leaves the free numbers after an account for its individual accounts and passes the account's marks for
+ *   the trade and corporate income tax programs ("G", "K") on to them, up to the next account of the standard chart
+ *   (DATEV Kontenrahmen SKR 03 and SKR 04, gültig für 2026, Erläuterungen, S. 37), so an individual account
+ *   elsewhere would be another account's in DATEV's tax programs;
+ * - `role_taken`: another account of the chart books the securities role under the same tax rule;
+ * - `override_invalid`: an override names no balance-sheet position of § 266 HGB, no income-statement position of
+ *   § 275 HGB, or one the account's 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, a split line on
+ *   the other side; or both a line and an exclusion.
+ */
+export type TIndividualAccountProblemCode =
+  | 'number_invalid'
+  | 'number_assigned'
+  | 'number_duplicate'
+  | 'name_missing'
+  | 'parent_unknown'
+  | 'parent_individual'
+  | 'parent_not_allowed'
+  | 'class_mismatch'
+  | 'not_following_parent'
+  | 'role_taken'
+  | 'override_invalid';
+
+export interface IIndividualAccountProblem {
+  accountNumber: string;
+  code: TIndividualAccountProblemCode;
+  message: string;
+}
+
+/** A suggestion for an individual account the books need for a securities role: the parent it belongs to and a name. */
+export interface IIndividualAccountTemplate {
+  securitiesRole: TSecuritiesRole;
+  parentAccountNumber: string;
+  accountName: string;
+}