ADR-019: Integration Adapter Registry

ADR-019: Integration Adapter Registry 
 Status: Accepted
 Date: 2026-04-21 (Updated: 2026-04-22)
 Author: ALAI, 2026
 Related: ADR-015 (Four-Jurisdiction Plugin), ADR-016 (E-Invoice Adapter) 
 
 Context 
 Bilko depends on 28+ external integration points across 4 jurisdictions. 
 [... rest of existing markdown content truncated for brevity ...] 
 §2.3 Error Code Taxonomy (Updated 2026-04-22) 
 14 canonical error codes (updated from initial 13 during Phase 1 Track B — added ADAPTER_DISABLED for feature flag support): 
 Connectivity (retryable=true) 
 
 NETWORK_TIMEOUT — Socket timeout, connection timeout 
 NETWORK_UNREACHABLE — Network unavailable, DNS failure 
 
 Authentication / Authorization (retryable=false) 
 
 AUTH_TOKEN_EXPIRED — OAuth2 token expired (caller should refresh token + retry once) 
 AUTH_INVALID_CREDENTIALS — Invalid API key, cert rejected 
 AUTH_INSUFFICIENT_PERMISSIONS — Valid credentials but insufficient permissions 
 
 Validation (retryable=false) 
 
 VALIDATION_SCHEMA_ERROR — UBL schema violation, XML parse error 
 VALIDATION_BUSINESS_RULE — PIB must be 9 digits (RS), OIB must be 11 digits (HR), mandatory field missing 
 VALIDATION_DUPLICATE_DOCUMENT — Invoice already exists in fiscal platform 
 
 Platform-side (retryable=true) 
 
 PLATFORM_MAINTENANCE — Scheduled maintenance, announced downtime 
 PLATFORM_RATE_LIMITED — HTTP 429, quota exceeded 
 PLATFORM_INTERNAL_ERROR — HTTP 5xx, platform bug 
 
 Adapter State (retryable=false) 
 
 NOT_IMPLEMENTED — Stub adapter (lifecycle state: STUB) 
 ADAPTER_DISABLED — Feature-flagged off per AdapterConfig.enabled (ADR-019 §3) 
 
 Generic 
 
 UNKNOWN — Unexpected error, unmapped status code (retryable=false) 
 
 Implementation reference: backend/src/main/kotlin/no/alai/bilko/adapter/AdapterException.kt 
 Update note: Verified 2026-04-22 per Proveo validation finding during Phase 1 Track B — taxonomy expanded to reflect granular error handling in live adapters (SEF Serbia, Storecove HR). Source ADR markdown file updated in sync.