Add DATEV accounting adapter boundary

docs/accounting-adapter-boundary.md

@@ -0,0 +1,87 @@
+# External accounting adapter boundary
+
+Decision date: 2026-08-11
+
+## Decision
+
+DATEV Unternehmen online (DUO) is the default and authoritative external
+GoBD bookkeeping and document-retention system. fin-hub remains the source of
+a reporting-only billing basis; it is not a bookkeeping system and does not
+issue invoices or handle payments.
+
+Qonto is the first complementary candidate when a needed function is not
+provided conveniently by DUO. In particular, Qonto may provide the customer
+invoice draft/delivery workflow and the managed transfer of bank data,
+documents, and structured invoice data to DUO. Selecting Qonto for one of
+these capabilities does not make it the bookkeeping authority.
+
+Other GoBD-capable systems remain possible through the same adapter contract.
+No provider is selected implicitly because another provider lacks a feature.
+The caller must request a capability and explicitly select a non-default
+adapter.
+
+## Data and authority flow
+
+```text
+fin-hub billing-basis v0.1
+        |
+        | side-effect-free, version-pinned adapter
+        v
+provider draft / exception report
+        |
+        | authorized external workflow and legal/tax completion
+        v
+DATEV Unternehmen online (bookkeeping and document authority)
+```
+
+The preferred operational route is Qonto's managed DATEV integration when the
+invoice workflow already occurs in Qonto and it preserves all required fields.
+A direct DATEV integration is the fallback for non-Qonto sources or missing
+Qonto capabilities. Provider activation, credentials, tax configuration,
+customer master data, invoice numbering, delivery, and retention validation
+are deliberately outside the current adapter.
+
+## Contract
+
+`fin_hub.accounting` defines:
+
+- a manifest with stable adapter ID, semantic adapter version, provider role,
+  exact input schema version, and declared capabilities;
+- a side-effect-free `prepare` operation producing an incomplete provider
+  draft with the source billing-basis ID as its idempotency reference;
+- an explicit schema-migration graph. An adapter rejects an unsupported source
+  schema, including a new major version, unless a reviewed migration is
+  registered;
+- capability checks that fail closed. The registry never silently falls back
+  from DATEV to Qonto or another provider.
+
+Provider payloads retain the billing-basis reference, client/engagement
+reference, service period, currency, amount, price reference, and source
+evidence IDs where supported. They explicitly mark legal and tax completion
+as required and contain no invoice number, issue date, or payment state.
+
+## Change and migration controls
+
+Before a provider or adapter upgrade is promoted:
+
+1. Pin and review the new provider API/export and adapter versions.
+2. Add an explicit billing-basis schema migration if the exact input version
+   changes; never reinterpret fields in place.
+3. Run contract and golden-payload tests, then dual-run old and new adapters
+   against the same billing-basis IDs.
+4. Reconcile record counts, amounts, currency, exception sets, and evidence
+   references in a non-production tenant.
+5. Obtain bookkeeping/tax-owner acceptance before cutover, retain the prior
+   adapter for rollback, and record the cutover decision.
+
+## Custody and retention
+
+- fin-hub retains reporting inputs, derivations, corrections, allocations, and
+  export provenance according to its financial-evidence policy.
+- DATEV/Steuerbüro owns bookkeeping records, document retention, tax treatment,
+  legal invoice completion, and correction/cancellation procedures.
+- Qonto owns bank records and any Qonto-created invoice/document workflow; its
+  DATEV transfer must be monitored and reconciled rather than treated as proof
+  of successful bookkeeping.
+- Secrets and provider credentials are never stored in billing-basis artifacts,
+  workplans, logs, or adapter configuration committed to Git.