@fin.cx/chartdata 2.15.0 → 2.17.0

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

@@ -49,7 +49,33 @@ export type TAccountRole = 'asset_sale_proceeds' | 'disposal_book_value';
  *   deducted), 'foreign_tax_exempt_income' (a foreign tax on income exempt at
  *   home), and 'foreign_tax_refund' (a foreign tax to be refunded);
  * - 'margin_interest': the interest on a short-term debt, such as a broker's
- *   margin loan.
+ *   margin loan;
+ * - 'borrow_fees': interest-like expenses (zinsähnliche Aufwendungen), such as
+ *   the fees of securities borrowed for a short sale;
+ * - 'writedown_other_current': the write-down of a current asset that is
+ *   neither inventory nor a security, at the usual amount (an option bought,
+ *   a variation margin paid);
+ * - 'expected_loss_provision': the provision for an expected loss from a
+ *   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'
@@ -77,7 +103,25 @@ export type TSecuritiesRole =
   | 'foreign_withholding_tax'
   | 'foreign_tax_exempt_income'
   | 'foreign_tax_refund'
-  | 'margin_interest';
+  | 'margin_interest'
+  | 'borrow_fees'
+  | 'writedown_other_current'
+  | 'expected_loss_provision'
+  | '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
@@ -224,6 +268,13 @@ export interface IChartAccount {
   securitiesRole?: TSecuritiesRole;
   /** the income tax rule the account is kept for, as its DATEV name states it; unset = none of its own */
   taxRule?: TTaxRule;
+  /**
+   * DATEV's mark "HB": the account is posted in the commercial balance sheet only (Handelsbilanz), its amounts
+   * 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. */
@@ -289,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;
+}