@fin.cx/skr 3.1.0 → 3.3.0

package/readme.plan.md

@@ -1,219 +0,0 @@
-# fin.cx Accounting Program — "No External Tax Accountant"
-
-Program-level plan anchored in @fin.cx/skr. Supersedes the original build checklist
-(that scaffold was stale; the package is long past it — see changelog).
-Status source of truth for current findings: `readme.hints.md`.
-
-## Context
-
-Run German company books end-to-end — bookkeeping, VAT filings, year-end — without an
-external Steuerberater for the mechanical work. skr v1.x is a solid bookkeeping core but
-not filing-grade: float money with 0.01-epsilon balance checks, non-atomic 3-write
-posting, no GoBD Festschreibung (mutable docs, non-gapless numbering, no audit trail),
-6 BU keys, ~110-account chart subsets, non-importable DATEV export stub, no stateless
-booking API, and zero filing coverage (ELSTER/E-Bilanz/HGB statements/OPOS/
-Anlagenbuchhaltung/bank reconciliation).
-
-**Critical path:** skr v2 hardening → complete FiBu → UStVA via ELSTER (removes monthly
-StB dependency) → E-Bilanz + HGB year-end (removes annual dependency).
-
-## Decisions (assumptions where user confirmation pending)
-
-1. Full program roadmap; each milestone gets its own detailed plan when it starts.
-2. Own company books first; APIs product-grade; multi-tenant/RBAC deferred.
-3. ELSTER owned: ERiC native lib via @git.zone/tsrust + @push.rocks/smartrust →
-   `@fin.cx/elster`.
-4. Full SKR03/04 + E-Bilanz taxonomy mapping from public sources (no DATEV license);
-   legal review before public release.
-5. Payroll OUT of scope (integrate provider, import GL postings).
-6. Statutory WP audit (§316 HGB) out of scope by law. Goal = "StB consulted on judgment
-   calls only".
-
-## Calendar anchors (from 2026-07-09, FY = calendar year)
-
-UStVA parallel-run 09–11/2026 → first live self-filed UStVA 12/2026 or 01/2027 →
-FY2026 Jahresabschluss self-prepared H1 2027 (one paid StB review as backstop;
-KSt/GewSt/UStJE deadline ~31 Jul 2027; Offenlegung 31 Dec 2027) → fully solo from FY2027.
-
-**Week-0 actions (hard external clocks, user):**
-1. ELSTER developer registration (Bayerisches LfSt) → Hersteller-ID + ERiC access
-   (days–4 wks).
-2. Confirm/obtain ELSTER Organisationszertifikat for TVC GmbH (post, 1–2 wks).
-3. Bundesanzeiger/Unternehmensregister publisher registration.
-
-## Milestones
-
-### M0 — skr v2.0.0 core hardening (foundation; blocks B, C2, D, E1)
-
-After **@fin.cx/calculation v1.1.0** (cents module — RELEASED 2026-07-09 ✓).
-
-- **Money:** ledger amounts = integer cents (`TCents`); exact `===` balance checks.
-  Fractional math via calculation cents module (`vatFromNetCents`, `splitGrossCents`
-  with net+vat===gross guarantee, `allocateCents` largest-remainder, `convertCents`,
-  `centsFromFloat` with drift guard). ROUND_HALF_UP = kaufmännisches Runden.
-- **Stateless core `ts/core/`** (imports only @fin.cx/calculation + each other):
-  `core.types.ts` (IJournalDraft/IJournalLineDraft with explicit per-line Gegenkonto;
-  TBuKey as string union; TTaxScenario), `core.bukeys.ts` (full BU table from official
-  DATEV Steuerschlüssel docs — v1 table + finance.plus logic both suspect, do not copy
-  blind), `core.taxscenario.ts` (confidence-scored cascade), `core.accountpolicy.ts`
-  (IAccountPolicy + SKR03/04 defaults incl. Geldtransit, FX gain/loss, rounding-diff),
-  `core.recipes.ts` (pure builders: vendor/customer invoice incl. reverse-charge +
-  intra-EU paired VAT, bank payment clearing with Skonto, internal transfer via
-  Geldtransit, suspense book/resolve, FX difference lines), `core.validate.ts`,
-  `core.datev.ts` (full Buchungsstapel row model, EXTF 700, buSchluessel on every row),
-  `core.hash.ts` (canonical serialization + SHA-256 chain).
-- **Atomic posting:** smartdata 7.1.7 sessions (verified supported). Mongo MUST be a
-  replica set; `SkrApi.initialize()` probes and fails hard. `JournalPoster`
-  (skr.posting.ts): pre-flight → withTransaction: period-lock re-check, gapless sequence
-  via $inc findOneAndUpdate, hash chain CAS on head. JournalEntry = single source of
-  truth (v1 Transaction explosion removed; collection frozen as legacy read model).
-  Balances recomputed via aggregation (skr.balances.ts); Account.updateBalance deleted
-  from posting path.
-- **Festschreibung:** posted == immutable (corrections via Storno only). JournalEntry +=
-  sequenceNumber (gapless per skrType+fiscalYear), prevHash/entryHash, finalizedAt,
-  status posted|finalized, schemaVersion 2. beforeSave()/delete() throw on mutation of
-  hashed docs; reversedBy derived (not stored). LedgerPeriod doc + festschreibePeriod();
-  closePeriod() posts P&L-zero entries then festschreibt. verifyHashChain() in
-  skr.verify.ts. SecurityManager: keep CAdES-B; RFC-3161 stub → loud NotImplementedError;
-  fix require('crypto') ESM bug in skr.export.ts.
-- **Migration** (idempotent, offline, float fields kept): M001 cents backfill (abort on
-  drift > 0.5 cent) → M002 unify legacy Transactions into synthesized JournalEntries →
-  M003 sequence + chain assignment + operator-confirmed festschreiben. JSON report.
-- **Phases (status 2026-07-09):** (0) replica-set env ✓ (gitzone services ≥2.23.0),
-  EXTF-700/v13 layout ✓ (verified vs DATEV-importable reference; official
-  Steuerschlüssel doc 0904313 portal-gated → manual import check per RC remains) →
-  (1) calculation v1.1.1 ✓ released → (2) stateless core ✓ → (3) persistence
-  hardening ✓ → (4) facade/reports rewiring + security descope ✓ →
-  (5) migrations + docs + v2.0.0 release ✓. **M0 COMPLETE** except the standing
-  per-RC manual DATEV import validation.
-- **Tests:** recipe goldens (both charts, exact cents), byte-exact EXTF files, property
-  tests (seeded PRNG), concurrency (N parallel posts → gapless, chain verifies, exact
-  trial balance), locked-period race, immutability throws, txn-abort no-partials,
-  migration round-trip; existing 65 tests green minus documented divergences; manual
-  DATEV import check per RC.
-
-### 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,
-provenance per record). A1 chart+Automatik+Kennzahlen → A2 HGB → A3 E-Bilanz taxonomy
-(esteuer.de). Own-books account coverage first. Verify: schema checks, cross-diff vs
-Kivitendo/Odoo l10n_de (reviewed, not copied), SKR PDF spot checks, ERiC as E-Bilanz
-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/:
-masters, open items, clearItems with Skonto+VAT correction, aging, dunning states;
-invariant: subledger == control account). B3 `@fin.cx/assets` (AfA schedules from BMF
-tables, GWG/degressive as year-keyed policy, Anlagespiegel → D1). B1 before live UStVA;
-B2/B3 may trail.
-
-### M-C — `@fin.cx/elster` (ERiC via Rust bridge) — first-win lane
-
-Thin transport: validate / submitTest (Testmerker) / submitLive / confirmation PDF.
-Rust binary dlopens ERiC from operator-supplied ERIC_HOME (ERiC never enters npm/repo;
-version-compat matrix + checksum gate). Kennzahl computation in `@fin.cx/tax` (VAT module
-ships early). C1 bridge → C2 UStVA 3-month parallel-run (3 consecutive zero/explained-diff
-months required) → C2' live + E1 → C3 DFV/ZM/UStJE.
-
-### M-D — Year-end (`@fin.cx/jahresabschluss` + `@fin.cx/tax`, Q1–Q2 2027)
-
-D1 §266/§275 Gliederung + §267 size classes + Anhang skeleton + Anlagespiegel. D3 tax
-engine (§4(5) EStG, §8b KStG, GewSt §8/§9 add-backs, loss carryforwards, KSt 15%+Soli,
-GewSt Hebesatz Bremen 460%; provisions posted back to skr). D2 E-Bilanz XBRL writer
-(ERiC validates locally — no heavyweight XBRL lib) via elster. D4 Offenlegung generator +
-checklist (semi-manual upload). Verify: "re-file the past" vs StB-filed prior year +
-Bescheide; tie-outs; paid StB review of first Abschluss.
-
-### M-E — Operational readiness (thin, inside skr)
-
-E1 Verfahrensdoku generator (ships WITH first live UStVA — GoBD requires from go-live).
-E2 GDPdU/GoBD Z3 Datenträgerüberlassung (Beschreibungsstandard index.xml + IDEA CSVs, on
-BagIt export). E3 retention (10y books, 8y Belege post-2025).
-
-## Waves
-
-1. **W0 (now):** registrations; A1 pipeline; M0 start. ✓ calculation v1.1.0 released.
-2. **W1 (Jul–Sep 2026):** M0 lands; C1; tax VAT module; A1; B1 MVP; parallel-run from
-   09/2026.
-3. **W2 (Q4 2026):** live UStVA + E1 ⇒ monthly StB dependency removed. C3 DFV. B2/B3/A2/A3.
-4. **W3 (Q1–Q2 2027):** D1→D3→D2→D4 for FY2026; StB review ⇒ fully solo from FY2027.
-5. **Continuous:** E2/E3; annual maintenance ~4–8 wks/yr (ERiC Nov release = hard
-   calendar item; taxonomy bump; form-year schemas; year-keyed tax parameters).
-
-## Top risks
-
-1. Incorrect live filing → parallel-run gate, re-file-the-past regression, ERiC+Testmerker
-   CI, human sign-off, StB review yr 1.
-2. ERiC licensing/platform (non-redistributable; ARM64 TBD) → ERIC_HOME + compat matrix;
-   x86_64 first.
-3. DATEV database rights on chart data → multi-source, provenance, legal review.
-4. Completeness failures → balance-chain continuity as monthly-close gate; OPOS
-   invariants.
-5. Regulatory churn → year-keyed data concentrated in chartdata+elster; DATEV export as
-   permanent escape hatch.
-
-## Open questions (user)
-
-1. Location of `fin-accountingbackend` repo (not on this machine; finance.plus used as
-   reference).
-2. ELSTER Organisationszertifikat present? Dauerfristverlängerung in place?
-3. **Ist- oder Soll-Versteuerung (§20 UStG)?** Blocks Wave-1 VAT engine design.
-4. Intra-EU B2B supplies (ZM needed)?
-5. elster deployment host architecture (ERiC aarch64 TBD)?
-6. chartdata public MIT immediately or after legal review?
-7. Beleg archival: doclake vs skr export bundles?
-8. StB cooperation for parallel-run (filed Kennzahlen + prior-year working papers)?
-9. Festschreibung: posted==immutable OK, or correction window until UStVA submission?
-10. RFC-3161 descope in M0 OK (loud failure instead of fake stub)?
-11. One company per DB confirmed (sequences keyed skrType+fiscalYear)?
-
-## Program gates
-
-- **Gate 1 (before live UStVA):** 3 zero/explained-diff parallel months + B1 continuity
-  green + E1 published.
-- **Gate 2 (before FY2026 self-filing):** re-file-the-past matches StB filings +
-  Bescheide; ERiC-valid E-Bilanz; StB review sign-off.