ADR 0018: EPC and Untrusted-Access SDK Boundary

Status

Accepted

Date

2026-06-26

Context

The SDK is beginning a work stream that harvests reusable primitives from an ePDG-derived source packet for EPC and untrusted-access CNF use cases. Task 0.1 produced the committed inventory in docs/refactoring/epdg-sdk-harvest-inventory.md and the fixture provenance map in docs/refactoring/epdg-sdk-fixture-provenance.md. Those documents classify the source material as planning and provenance context, not as SDK-ready implementation, conformance evidence, or product claims.

This boundary matters because ePDG and EPC systems mix reusable mechanisms with deployment policy:

• reusable protocol framing, bounded parsing, evidence schemas, resource models, redaction classes, and narrow kernel UAPI adapters can belong in a neutral SDK;
• product-specific attach procedures, APN/realm/PLMN selection, retransmission policy, IKE/Child SA state machines, lawful-intercept workflow, charging policy, CRDs, Helm values, carrier acceptance, and deployment defaults must remain outside the SDK.

The current public SDK already states that GTP-U is applicable to LTE/EPC user plane while EPC control-plane protocols such as GTP-C, Diameter, and S1AP are not currently provided. This ADR authorizes future mechanism work for selected EPC/untrusted-access primitives without converting the SDK into an ePDG product, an EPC core, or a carrier-accepted deployment.

Decision

Adopt the following boundary for ePDG-derived EPC and untrusted-access work.

1. Source-use and provenance rule

The task 0.1 inventory and fixture provenance map are the normative inputs for the first harvest tranche. They are not copy-paste authorization. Each SDK change MUST re-author reusable behavior in SDK style and MUST keep product bytes, product tests, and product claims out of conformance evidence unless they later satisfy ADR 0015 provenance requirements.

If a source crate or directory lacks an explicit compatible license marker, code copying is blocked until source ownership is confirmed. Concepts may still be used to design independently authored SDK APIs when that does not import source implementation.

2. Mechanism is SDK-owned; policy is product-owned

The SDK MAY own product-neutral mechanisms that are reusable by multiple packet core CNFs:

• pure Rust wire codecs and typed views that preserve unknown/raw fields;
• bounded parser limits, hostile-input behavior, fuzz targets, and CONFORMANCE.md records required by ADR 0015;
• transport-neutral protocol metadata, dictionaries, and peer-test utilities;
• narrow Linux UAPI/sys boundaries plus safe wrappers, where an ADR authorizes the unsafe exception and mechanical gates enforce it;
• redaction and regulated-data classification primitives;
• resource/capability models and preflight validators;
• runtime health-gate aggregation primitives;
• simulator scaffolding and release-evidence schemas.

The product that embeds the SDK MUST own deployment and business policy:

• ePDG attach orchestration and subscriber/session lifecycle decisions;
• APN, DNN, realm, PLMN, PGW, AAA/HSS/CDF, and charging policy;
• IKE SA and Child SA state machines, EAP-AKA procedure, cookie/retransmit policy, key derivation choices, and 3GPP profile enforcement;
• XFRM SA/SPD policy, namespaces, privileges, kernel module loading, and rollout defaults;
• readiness thresholds, drain routing, peer-selection policy, CRD/YANG/Helm shapes, lawful-intercept workflow, and carrier acceptance claims.

SDK APIs for these primitives MUST be named and documented as mechanism surfaces, not as an epdg product facade or production-ready EPC control plane.

3. Surface-specific boundary

4. Dependency, safety, and implementation guardrails

All future work under this boundary inherits existing SDK policy:

1. ADR 0014 remains in force: rustls only, tokio only, workspace MSRV 1.88, compatible licenses, justified dependencies, and no unauthorized gRPC stack.
2. ADR 0015 remains in force for every opc-proto-* codec: spec-authored or independent fixtures, byte-exact decode/encode where claimed, raw preservation, hostile-input tests, fuzz targets, and honest CONFORMANCE.md coverage.
3. ADR 0017 is the pattern for kernel UAPI exceptions. Any XFRM/IPsec sys crate MUST be narrow, mechanically checked, locally documented with adjacent SAFETY: comments, and kept below a safe public wrapper. This does not authorize FFI protocol parsers.
4. ePDG-derived fixture bytes are parity evidence until the provenance map's intake checklist is satisfied. They may test migration compatibility, but they MUST NOT be counted as SDK conformance proof by themselves.
5. Public APIs that can expose subscriber identifiers, key material, TEIDs, SPIs, Diameter Session-Id values, or lawful-intercept identifiers MUST include redaction-safe Debug, Display, error, metric, and evidence behavior.

5. Maturity and claim language

New crates and APIs created from this work stream start as experimental unless a separate RFC/ADR, conformance record, and product-neutral test suite justify a stronger status. Documentation MUST distinguish:

• "SDK provides a reusable primitive/mechanism";
• "a downstream product may compose the primitive into an ePDG/EPC function"; and
• "a downstream product has completed carrier acceptance."

Only the first claim is an SDK claim. The other two remain product claims.

Consequences

• The SDK can grow reusable EPC and untrusted-access mechanisms without importing ePDG product policy, product defaults, or carrier-readiness claims.
• Future implementation tasks have a durable boundary to cite when deciding what belongs in crates/*, operators/operator-sdk-go, and test/evidence crates.
• Reviews can reject changes that make an SDK crate choose APN/realm policy, lawful-intercept workflow, charging behavior, production privileges, or attach orchestration, even if the source product contained that logic next to reusable mechanisms.
• The task 0.1 inventory remains the source map for this harvest tranche, while ADR 0014, ADR 0015, and ADR 0017 remain the dependency, conformance, and unsafe boundary gates.