Architecture Decision Records
This directory contains accepted and proposed architecture decisions for the OpenPacketCore SDK hardening and management-plane work.
ADRs are the durable record of architectural intent. The audit completion reports and implementation status matrix record what was validated; these ADRs record why the shape of the SDK is what it is. Proposed ADRs are included here when they gate in-progress work, but they do not authorize implementation until accepted.
Index
| ADR | Decision |
|---|---|
| 0001 | Config management is secure by default, commit-confirmed, audited, and explicitly authorized. |
| 0002 | Config persistence HA uses ConsensusConfigStore on the shared Openraft engine, with sealed/redacted commands, atomic authority fencing, shared authenticated transport, and exact offline legacy recovery. |
| 0003 | Authoritative session HA uses one Openraft-backed store with validated identity, committed state-machine application, and envelope encryption above consensus; standalone SQLite is not HA. |
| 0004 | Production identity, TLS, keys, and audit integrity are explicit SDK substrates with fail-closed adapters. |
| 0005 | Runtime health, admin/probe routes, metrics, and alarms are shared SDK surfaces with production authorization and redaction. |
| 0006 | Storage, security, runtime, HA, and release evidence are validated through fail-closed fault injection. |
| 0007 | Operator lifecycle policy logic lives in Rust SDK crates as reusable policy engines. |
| 0008 | Kubernetes operator integration is demonstrated by a Go reference harness without becoming a product CNF operator. |
| 0009 | Production data-plane claims require explicit node-resource, BPF, pod-security, and fallback validation. |
| 0010 | RFC 006 evidence, SBOM/VEX, provenance, bundle verification, performance baselines, and gates are first-class release inputs. |
| 0011 | opc-amf-lite is the SDK vertical integration proof, not a product NF. |
| 0012 | Diagnostics safety and privacy governance boundaries are structured, fail-closed, and compile-gated. |
| 0013 | NGAP requires generated ASN.1 APER code; hand-written and FFI codecs are rejected. |
| 0014 | rustls/tokio-only dependency policy, no gRPC stack in SDK crates, and a measured (not aspirational) MSRV. |
| 0015 | Protocol codecs are proven against spec-authored byte fixtures, never only their own encoder output. |
| 0016 | (proposed) tonic/prost are permitted only for opc-gnmi-server as the ADR 0014 §3 exception; core SDK crates stay gRPC-free. |
| 0017 | Explicitly allowlisted Linux kernel UAPI sys crates, including the fixed-profile descriptor-only opc-fs-verity-sys, plus the narrowly scoped opc-sqlite-file-control-sys descriptor, test-VFS, and ADR 0020 read-only snapshot VFS boundary, hold all reviewed unsafe FFI; this exception to ADR 0014 §8 does not reopen ADR 0013's rejection of foreign C codec FFI. |
| 0018 | EPC and untrusted-access additions are limited to SDK-owned reusable mechanisms; product policy, deployment defaults, ePDG orchestration, and carrier-readiness claims remain product-owned. |
| 0019 | Openraft is the only distributed-persistence consensus authority; domain state machines remain SDK-owned and the opc-persist migration is required before the workspace can claim a unified profile. |
| 0020 | Fixed membership is independent of snapshot integrity policy; portable snapshots verify the bytes consumed, including SQLite reads, while strict fs-verity remains explicit. Implementation qualification is pending. |
| 0021 | Historical private segmented WAL and SQLite-projection design; its ordered durable implementation is preserved, while ADR 0022 supersedes application composition and public activation. |
| 0022 | Native session storage supports explicit Durable and Async acknowledgement modes; Async restart requires a fresh live-quorum cut and fenced local catch-up before participation. |
| 0023 | Configuration history is pruned only by an acknowledged, exact-head consensus decision with authenticated boundaries, protected references, and atomic capacity rejection. |
| 0024 | Route operations exclude intersecting kernel keys while independent operations use bounded concurrent workers; dispatched inverses retain exclusion after cancellation. |
| 0025 | Management signing transitions, complete frozen exports and acknowledged pruning share the configuration authority and verify an independently stored monotonic checkpoint. |
| 0026 | An exclusive writer retaining no predecessor state can reset namespace XFRM tables and bound stores before ordinary actor commands, with ordered empty readback and monotonic writer epochs. |
| 0027 | An explicit exclusive workload reset removes incompatible eBPF leftovers across its declared interfaces while preserving writer locks, selector history and loaded-map reference guards. |
| 0028 | A never-provisioned exclusive scope can discard selector residue, its named interface's whole tc priority and SDK hooks at any priority, while limiting map-reference authority, releasing scope-pinned links and reporting foreign removals. |
| 0029 | An independently negotiated store profile binds terminal no-effect receipts for exact unbound V2 requests; the first binding wins and caller lifetime gates consumer reclamation. |
| 0030 | DNS freshness follows record provenance; consumers retain last-good keys and own asynchronous cache driving. |
| 0031 | Bounded asynchronous DNS uses configured servers, source-bound sockets, strict reply validation and real TTL provenance. |
| 0032 | SRV uses bounded priority/weighted target selection, source-bound address expansion and original record lifetimes. |
| 0033 | Shared checked N1-mode values have transport-specific IKEv2 Notify and directional S2b APCO codecs, value-free diagnostics and explicit duplicate rules. |
| 0034 | An immutable profile retains one pending lease-contention binding and permits explicit resumption of the original sealed request after correlated authoritative status. |