@fin.cx/skr 2.0.1 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/skr",
-  "version": "2.0.1",
+  "version": "3.1.0",
   "description": "SKR03 and SKR04 German accounting standards for double-entry bookkeeping",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
@@ -34,6 +34,7 @@
     "node-forge": "^1.4.0"
   },
   "devDependencies": {
+    "@fin.cx/chartdata": "^2.1.0",
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsrun": "^2.0.5",
     "@git.zone/tstest": "^3.6.6",

package/readme.hints.md

@@ -14,6 +14,16 @@
   `readme.plan.md`; M0 = skr v2 core hardening. @fin.cx/calculation ships the cents
   module (TCents) that skr v2 money handling builds on.
 
+## Chart rebase (2026-07-09, v3)
+
+- The built-in SKR03/04 charts are now GENERATED from @fin.cx/chartdata >= 2.1.0
+  (`tsx tools/generate-chart-data.ts`) — the v1 hand-written charts were an
+  invented hybrid layout and are gone. Notable corrections: SKR03 revenue lives
+  in class 8 (8400/8300), expenses in class 4 (default 4900 — 4980 is
+  Mietleasing!), VSt/USt rate accounts fixed (1571/1771 = 7 %); SKR04 bank is
+  1800, Kasse 1600, controls 1200/3300, default expense 6300.
+- Account.isAutomaticAccount: SKR04 controls corrected to 1200/3300.
+
 ## M0 Phase 2 — stateless core (2026-07-09)
 
 - `ts/core/` is the pure booking core (exported as `core` from the package index):

package/readme.md

@@ -78,7 +78,7 @@ await api.initialize('SKR03');
 await api.postTransaction({
   date: new Date(),
   debitAccount: '1200',
-  creditAccount: '4000',
+  creditAccount: '8400',
   amount: 1000,
   description: 'Test sale',
   reference: 'INV-001',
@@ -96,16 +96,16 @@ await api.close();
 
 `initialize('SKR03')` loads the process-oriented chart.
 
-- Class 4: operating income
-- Class 5: material costs
-- Class 6: personnel costs
-- Class 7: other operating expenses
+- Class 3: Wareneingang
+- Class 4: betriebliche Aufwendungen
+- Class 8: Erlöse
+- Class 9: Vortrags- und Abschlusskonten
 
 `initialize('SKR04')` loads the financial-statement-oriented chart.
 
-- Class 2 and 3: expenses
-- Class 4 and 5: revenues
-- Class 8: reserved as `frei` for custom use
+- Class 4: betriebliche Erträge
+- Class 5 and 6: betriebliche Aufwendungen
+- Class 2: Eigenkapital, Class 3: Fremdkapital
 
 The test suite exercises both variants and includes full Jahresabschluss scenarios for each.
 

package/readme.plan.md

@@ -94,6 +94,35 @@ After **@fin.cx/calculation v1.1.0** (cents module — RELEASED 2026-07-09 ✓).
 
 ### M-A — `@fin.cx/chartdata` (new pkg; parallel to M0)
 
+**Status 2026-07-09: A1 seed COMPLETE locally** (repo at
+`/mnt/data/foss.global/fin.cx/chartdata`, committed, 12/12 tests): year-keyed
+SKR03/04 2026 datasets (~125 accounts each incl. all fiscally-relevant VAT/
+Skonto/igE/§13b/EUSt accounts missing from skr v1), Automatik functions +
+allowed BU keys, account→UStVA-Kennzahl mappings, scenario Kennzahlen table
+(89/93, 46/47, 84/85, 41, 43, 81, 86, 60, 66/61/67/62), coverage introspection,
+provenance per record, reproducible seed pipeline in tools/.
+**RELEASED as @fin.cx/chartdata v1.1.0** (2026-07-09, verdaccio + npmjs).
+**A1 REBASE COMPLETE (2026-07-09):** chartdata v2.1.0 = curated oracle-verified
+datasets (91 SKR03 / 78 SKR04 accounts, verification-only oracle, no foreign
+strings); skr v3.0.0 aligned: charts GENERATED from chartdata
+(tools/generate-chart-data.ts), policies corrected (expense default 4900/6300,
+SKR04 controls 1200/3300, bank 1800/Kasse 1600), all 98 tests remapped to real
+DATEV numbers and green. A2 HGB §266/§275 mappings DONE
+(chartdata v2.2.0: every non-statistical account carries hgb266Position or
+hgb275Position, validated against the statute Gliederung trees in
+chartdata.hgb.ts and verified against the oracle's position tags — 11
+documented modeling exceptions where German textbook treatment differs, e.g.
+USt liabilities in Passiva C.8). NEXT: A3 E-Bilanz taxonomy; D1 can now build
+the §266/§275 Gliederung from chartdata.
+
+**A1 cross-diff done (2026-07-09):** Odoo l10n_de oracle proves the skr-v1 seed
+charts are an invented hybrid (~50/125 SKR03 + ~66/130 SKR04 divergences);
+ALL fiscal A1 additions verified clean. Rate-label fixes released (v1.1.1:
+1570/1571/1770/1771). NEXT: A1 seed-base rebase (clean-room base set, remove
+invented blocks, align skr built-in charts + tests — coupled change), then A2
+(HGB mappings; Odoo tags as verification oracle), then A3. Details:
+chartdata/tools/a1-crossdiff-report.md.
+
 Year-versioned full SKR03/04: account master, Automatikkonto functions + allowed BU keys,
 UStVA-Kennzahl / HGB §266/§275 / E-Bilanz (de-gaap-ci) mappings. Pure data + lookup API;
 `getMappingCoverage()` fails loudly. Pipeline in unpublished tools/ (public sources,
@@ -104,6 +133,16 @@ oracle. Legal review before public MIT release.
 
 ### M-B — Subledgers + reconciliation
 
+**B1 status 2026-07-09: package layer RELEASED** — @fin.cx/camt v1.1.0
+(CAMT.052/053/054, exact cents, SEPA extraction, statement-internal balance
+check) and @fin.cx/bankrec v1.1.0 (canonical signed-cent transactions, camt +
+mt940 adapters, cross-statement continuity control, confidence-scored matching
+engine: direction filter, Skonto window, tie-forces-review, no double
+settlement). @fin.cx/mt940parser v1.1.1 published for the first time
+(modernized: smartconfig v2, direct npm publish, pnpm pinned). Remaining B1:
+regression run against real TVC bank statements (user to provide), then wire
+auto/review/unmatched decisions to skr recipes in the consuming app.
+
 B1 `@fin.cx/camt` (CAMT.052/053/054; MT940 = legacy) + `@fin.cx/bankrec` (canonical
 decimal bank txn with SEPA refs, adapters, balance-chain continuity, confidence-scored
 matching, auto-post above threshold, review queue below). B2 OPOS inside skr (ts/opos/:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/skr',
-  version: '2.0.1',
+  version: '3.1.0',
   description: 'SKR03 and SKR04 German accounting standards for double-entry bookkeeping'
 }

package/ts/core/core.accountpolicy.ts

@@ -80,7 +80,7 @@ export const SKR03_DEFAULT_POLICY: IAccountPolicy = {
     export: '8120',
     reverseCharge: '8337',
   },
-  expenseDefault: '4980',
+  expenseDefault: '4900',
   skonto: {
     receivedStandard: '3736',
     receivedReduced: '3731', // PROVISIONAL
@@ -119,7 +119,7 @@ export const SKR04_DEFAULT_POLICY: IAccountPolicy = {
     export: '4120',
     reverseCharge: '4337',
   },
-  expenseDefault: '6980',
+  expenseDefault: '6300',
   skonto: {
     receivedStandard: '5736',
     receivedReduced: '5731', // PROVISIONAL

package/ts/index.ts

@@ -19,6 +19,13 @@ export type {
   ITrialBalanceCents,
   IBalanceQueryOptions,
 } from './skr.balances.js';
+export {
+  listOpenItems,
+  getAging,
+  getControlTotals,
+  setOposMeta,
+} from './skr.opos.js';
+export type { IOpenItem, IAgingBucket, IControlTotals, TOposKind } from './skr.opos.js';
 export { verifyHashChain } from './skr.verify.js';
 export type { IChainVerificationResult } from './skr.verify.js';
 export { migrateToV2 } from './skr.migrate.js';

package/ts/skr.api.ts

@@ -1026,6 +1026,84 @@ export class SkrApi {
     return migrateToV2();
   }
 
+  // ========== OPOS (open items) ==========
+
+  public async listOpenItems(options?: {
+    kind?: import('./skr.opos.js').TOposKind;
+    accountNumber?: string;
+    asOf?: Date;
+    includeSettled?: boolean;
+  }): Promise<import('./skr.opos.js').IOpenItem[]> {
+    this.ensureInitialized();
+    const { listOpenItems } = await import('./skr.opos.js');
+    return listOpenItems(this.currentSKRType!, this.getDefaultPolicy(), options);
+  }
+
+  public async getOposAging(
+    kind: import('./skr.opos.js').TOposKind,
+    asOf: Date,
+    bucketDays?: number[],
+  ): Promise<import('./skr.opos.js').IAgingBucket[]> {
+    this.ensureInitialized();
+    const { getAging } = await import('./skr.opos.js');
+    return getAging(this.currentSKRType!, this.getDefaultPolicy(), kind, asOf, bucketDays);
+  }
+
+  public async getControlTotals(asOf?: Date): Promise<import('./skr.opos.js').IControlTotals> {
+    this.ensureInitialized();
+    const { getControlTotals } = await import('./skr.opos.js');
+    return getControlTotals(this.currentSKRType!, this.getDefaultPolicy(), asOf);
+  }
+
+  public async setDunning(params: {
+    accountNumber: string;
+    reference: string;
+    dunningLevel?: number;
+    dueDate?: string;
+  }): Promise<void> {
+    this.ensureInitialized();
+    const { setOposMeta } = await import('./skr.opos.js');
+    return setOposMeta({ skrType: this.currentSKRType!, ...params });
+  }
+
+  /**
+   * Settle an open item with a bank payment (Skonto and small-difference
+   * write-offs via the core recipe); ordinary v2 posting, fully audited.
+   */
+  public async settleOpenItem(params: {
+    item: import('./skr.opos.js').IOpenItem;
+    paidCents: number;
+    date: Date;
+    bankAccount?: string;
+    skonto?: { ratePercent: number };
+    diffToleranceCents?: number;
+    description?: string;
+  }): Promise<JournalEntry> {
+    this.ensureInitialized();
+    // a plain underpayment (no Skonto, beyond tolerance) is a PARTIAL
+    // settlement: book only the paid amount and leave the rest open
+    const shortfall = params.item.openCents - params.paidCents;
+    const isPartial =
+      !params.skonto && shortfall > (params.diffToleranceCents ?? 0);
+    const draft = core.bookBankPayment(
+      {
+        date: params.date,
+        direction: params.item.kind === 'debtor' ? 'incoming' : 'outgoing',
+        bankAccount: params.bankAccount,
+        counterpartyAccount: params.item.accountNumber,
+        expectedCents: isPartial ? params.paidCents : params.item.openCents,
+        paidCents: params.paidCents,
+        skonto: params.skonto,
+        diffToleranceCents: params.diffToleranceCents,
+        description:
+          params.description ?? `Ausgleich ${params.item.reference || params.item.accountNumber}`,
+        reference: params.item.reference || undefined,
+      },
+      this.getDefaultPolicy(),
+    );
+    return this.journalPoster.postDraft(draft, { policy: this.getDefaultPolicy() });
+  }
+
   /**
    * Get current SKR type
    */

package/ts/skr.classes.account.ts

@@ -202,14 +202,13 @@ export class Account extends SmartDataDbDoc {
    * Automatic accounts like 1400/1600 cannot be posted to directly
    */
   public static isAutomaticAccount(accountNumber: string, skrType: TSKRType): boolean {
+    // Sammelkonten (control accounts) must be addressed via personal accounts
     // SKR03: 1400 (Forderungen), 1600 (Verbindlichkeiten)
-    // SKR04: 1400 (Forderungen), 1600 (Verbindlichkeiten)
-    // Note: In SKR04, 3300 is "Fahrzeugkosten" (vehicle costs), NOT an automatic account
+    // SKR04: 1200 (Forderungen), 3300 (Verbindlichkeiten)
     if (skrType === 'SKR03') {
       return accountNumber === '1400' || accountNumber === '1600';
-    } else {
-      return accountNumber === '1400' || accountNumber === '1600';
     }
+    return accountNumber === '1200' || accountNumber === '3300';
   }
 
   /**

package/ts/skr.opos.ts

@@ -0,0 +1,258 @@
+/**
+ * OPOS (Offene-Posten-Buchhaltung): open-item accounting over the v2 ledger.
+ *
+ * Open items are DERIVED from the hashed journal — no separate bookkeeping
+ * state that could drift. A line on a personal account (debtors 10000-69999,
+ * creditors 70000-99999) belongs to the open item keyed by
+ * (account, belegfeld1); the item is open while its signed sum is non-zero.
+ * Settling an item is ordinary posting (core.bookBankPayment + JournalPoster),
+ * so Festschreibung and the audit chain apply unchanged.
+ *
+ * Only dunning metadata lives outside the ledger (OposMeta collection) —
+ * process state, not bookkeeping.
+ */
+import * as core from './core/index.js';
+import { getDbSync } from './skr.database.js';
+import { JOURNAL_ENTRY_COLLECTION } from './skr.period.js';
+import type { TSKRType } from './skr.types.js';
+
+export const OPOS_META_COLLECTION = 'OposMeta';
+
+export type TOposKind = 'debtor' | 'creditor';
+
+export interface IOpenItem {
+  accountNumber: string;
+  kind: TOposKind;
+  /** belegfeld1 of the originating lines (usually the invoice number) */
+  reference: string;
+  /** original claim (sum of the claim-side lines) */
+  invoiceCents: number;
+  /** settled so far (sum of the settlement-side lines) */
+  clearedCents: number;
+  /** invoiceCents - clearedCents; > 0 means open */
+  openCents: number;
+  firstDate: string;
+  lastDate: string;
+  entryIds: string[];
+  dunningLevel: number;
+  dueDate?: string;
+}
+
+export interface IAgingBucket {
+  label: string;
+  maxAgeDays: number | null;
+  items: IOpenItem[];
+  totalCents: number;
+}
+
+export interface IControlTotals {
+  debtorsCents: number;
+  creditorsCents: number;
+  debtorAccounts: number;
+  creditorAccounts: number;
+}
+
+function kindOf(accountNumber: string, policy: core.IAccountPolicy): TOposKind | null {
+  if (core.isDebtorAccount(policy, accountNumber)) return 'debtor';
+  if (core.isCreditorAccount(policy, accountNumber)) return 'creditor';
+  return null;
+}
+
+interface ILineRow {
+  entryId: string;
+  accountNumber: string;
+  belegfeld1?: string;
+  side: 'debit' | 'credit';
+  amountCents: number;
+  date: Date;
+}
+
+async function loadPersonalLines(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  accountNumber?: string,
+  asOf?: Date,
+): Promise<ILineRow[]> {
+  const match: Record<string, unknown> = {
+    skrType,
+    schemaVersion: 2,
+    status: { $in: ['posted', 'finalized'] },
+  };
+  if (asOf) match.date = { $lte: asOf };
+  if (accountNumber) match['lines.accountNumber'] = accountNumber;
+
+  const docs = await getDbSync()
+    .mongoDb.collection(JOURNAL_ENTRY_COLLECTION)
+    .find(match)
+    .sort({ date: 1, sequenceNumber: 1 })
+    .toArray();
+
+  const rows: ILineRow[] = [];
+  for (const doc of docs) {
+    for (const line of (doc.lines ?? []) as Array<Record<string, unknown>>) {
+      const account = line.accountNumber as string;
+      if (!kindOf(account, policy)) continue;
+      if (accountNumber && account !== accountNumber) continue;
+      rows.push({
+        entryId: doc.id as string,
+        accountNumber: account,
+        belegfeld1: (line.belegfeld1 as string) || (doc.reference as string) || '',
+        side: line.side as 'debit' | 'credit',
+        amountCents: (line.amountCents as number) ?? 0,
+        date: doc.date as Date,
+      });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Derive open items. Debtors: claims are debits, settlements credits;
+ * creditors inverse. Items with openCents === 0 are settled and omitted
+ * unless includeSettled is set.
+ */
+export async function listOpenItems(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  options?: {
+    kind?: TOposKind;
+    accountNumber?: string;
+    asOf?: Date;
+    includeSettled?: boolean;
+  },
+): Promise<IOpenItem[]> {
+  const rows = await loadPersonalLines(skrType, policy, options?.accountNumber, options?.asOf);
+  const groups = new Map<string, IOpenItem>();
+
+  for (const row of rows) {
+    const kind = kindOf(row.accountNumber, policy)!;
+    if (options?.kind && kind !== options.kind) continue;
+    const key = `${row.accountNumber}:${row.belegfeld1}`;
+    let item = groups.get(key);
+    if (!item) {
+      item = {
+        accountNumber: row.accountNumber,
+        kind,
+        reference: row.belegfeld1 ?? '',
+        invoiceCents: 0,
+        clearedCents: 0,
+        openCents: 0,
+        firstDate: row.date.toISOString().slice(0, 10),
+        lastDate: row.date.toISOString().slice(0, 10),
+        entryIds: [],
+        dunningLevel: 0,
+      };
+      groups.set(key, item);
+    }
+    const isClaim = (kind === 'debtor') === (row.side === 'debit');
+    if (isClaim) item.invoiceCents += row.amountCents;
+    else item.clearedCents += row.amountCents;
+    item.lastDate = row.date.toISOString().slice(0, 10);
+    if (!item.entryIds.includes(row.entryId)) item.entryIds.push(row.entryId);
+  }
+
+  const meta = await getDbSync().mongoDb.collection(OPOS_META_COLLECTION).find({ skrType }).toArray();
+  const metaByKey = new Map(meta.map((m) => [`${m.accountNumber}:${m.reference}`, m]));
+
+  const items: IOpenItem[] = [];
+  for (const item of groups.values()) {
+    item.openCents = item.invoiceCents - item.clearedCents;
+    const extra = metaByKey.get(`${item.accountNumber}:${item.reference}`);
+    if (extra) {
+      item.dunningLevel = (extra.dunningLevel as number) ?? 0;
+      item.dueDate = extra.dueDate as string | undefined;
+    }
+    if (item.openCents !== 0 || options?.includeSettled) items.push(item);
+  }
+  return items.sort((a, b) => a.accountNumber.localeCompare(b.accountNumber) || a.firstDate.localeCompare(b.firstDate));
+}
+
+/**
+ * Aging list relative to asOf, bucketed by days since dueDate (falling back
+ * to the item's first posting date).
+ */
+export async function getAging(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  kind: TOposKind,
+  asOf: Date,
+  bucketDays: number[] = [30, 60, 90],
+): Promise<IAgingBucket[]> {
+  const items = await listOpenItems(skrType, policy, { kind, asOf });
+  const buckets: IAgingBucket[] = [
+    ...bucketDays.map((days, index) => ({
+      label: index === 0 ? `0-${days}` : `${bucketDays[index - 1] + 1}-${days}`,
+      maxAgeDays: days,
+      items: [] as IOpenItem[],
+      totalCents: 0,
+    })),
+    { label: `> ${bucketDays[bucketDays.length - 1]}`, maxAgeDays: null, items: [], totalCents: 0 },
+  ];
+  for (const item of items) {
+    const anchor = item.dueDate ?? item.firstDate;
+    const ageDays = Math.max(0, Math.floor((asOf.getTime() - new Date(anchor).getTime()) / 86_400_000));
+    const bucket =
+      buckets.find((candidate) => candidate.maxAgeDays !== null && ageDays <= candidate.maxAgeDays) ??
+      buckets[buckets.length - 1];
+    bucket.items.push(item);
+    bucket.totalCents += item.openCents;
+  }
+  return buckets;
+}
+
+/**
+ * Subledger control totals: the aggregated personal-account balances that a
+ * balance sheet reports as Forderungen (B.II.1) / Verbindlichkeiten (C.4)
+ * aus Lieferungen und Leistungen. Control accounts themselves are blocked for
+ * posting, so these aggregates ARE the control balances.
+ */
+export async function getControlTotals(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  asOf?: Date,
+): Promise<IControlTotals> {
+  const rows = await loadPersonalLines(skrType, policy, undefined, asOf);
+  let debtorsCents = 0;
+  let creditorsCents = 0;
+  const debtorAccounts = new Set<string>();
+  const creditorAccounts = new Set<string>();
+  for (const row of rows) {
+    const signed = row.side === 'debit' ? row.amountCents : -row.amountCents;
+    if (kindOf(row.accountNumber, policy) === 'debtor') {
+      debtorsCents += signed;
+      debtorAccounts.add(row.accountNumber);
+    } else {
+      creditorsCents -= signed; // creditors carry credit balances positive
+      creditorAccounts.add(row.accountNumber);
+    }
+  }
+  return {
+    debtorsCents,
+    creditorsCents,
+    debtorAccounts: debtorAccounts.size,
+    creditorAccounts: creditorAccounts.size,
+  };
+}
+
+/**
+ * Dunning metadata (process state, not bookkeeping — letters are out of
+ * scope; the level/due-date state machine is in).
+ */
+export async function setOposMeta(params: {
+  skrType: TSKRType;
+  accountNumber: string;
+  reference: string;
+  dunningLevel?: number;
+  dueDate?: string;
+}): Promise<void> {
+  const update: Record<string, unknown> = { updatedAt: new Date() };
+  if (params.dunningLevel !== undefined) update.dunningLevel = params.dunningLevel;
+  if (params.dueDate !== undefined) update.dueDate = params.dueDate;
+  await getDbSync()
+    .mongoDb.collection(OPOS_META_COLLECTION)
+    .updateOne(
+      { skrType: params.skrType, accountNumber: params.accountNumber, reference: params.reference },
+      { $set: update },
+      { upsert: true },
+    );
+}