Invariants

The AutonomyOps ADK enforces thirteen architectural invariants (INV-01–INV-13). Violating any invariant is a build-breaking failure. CI guardrails and failure injection tests detect violations automatically. No invariant may be relaxed without a signed-off Architecture Decision Record (ADR).

For the machine-readable traceability table (invariant → code module → CI guardrail → FI test), see Traceability → Invariant Map.

Summary Table

Inv

Name

Enforcement Layer

FI Coverage

INV-01

No Shared State

Startup path check + edge/ci/scan_prohibited

scan-only

INV-02

No Convergence Tracking

edge/ci/scan_prohibited (prohibited symbols)

scan-only

INV-03

No Leader Election

edge/ci/scan_prohibited + code review

scan-only

INV-04

Disk Ceiling

edge/storage/localstore.go, eviction, statfs

FI-C1-01, FI-C2-01, FI-C2-02

INV-05

Platform Assurance Binding

edge/assurance/assurance.go, cgroup v2 probe

FI-C1-05

INV-06

Local-Only Activation

Scheduler local-only params; code review

structural

INV-07

Bounded Memory

cgroup v2 + pool-bounded transport buffers

via INV-05 FI

INV-08

Idempotent Segment Receive

Segment ID dedup in local index

unit tests

INV-09

Authorization Boundary

mTLS + CRL in transport layer

FI-C3-02

INV-10

Mission-Layer Decoupling

edge/ci/scan_dependencies (import graph)

FI-C1-03

INV-11

Deterministic Relay

Lexicographic comparator, no PRNG in relay path

structural

INV-12

Bounded Retry

edge/retry/retry.go monotonic counter

FI-C4-01, FI-C4-02, FI-C4-03

INV-13

Bounded Per-Peer Ingest Quota

edge/quota/localquota.go token bucket

FI-C3-03

INV-01 — No Shared State

Statement: All persistent segment storage, peer metadata, and decision logs are local-root-only. No NFS, CIFS, cluster filesystem, distributed store, or shared-memory IPC mechanism is permitted.

Rationale: Shared state introduces coordination dependencies that violate the local-only decision authority model and create liveness hazards under network partition.

Code modules: edge/storage/localstore.go (local-root path check), edge/config/startup.go (startup abort on out-of-root path)

Enforcement:

  • Startup: path resolved against $EDGE_LOCAL_ROOT; out-of-root path → abort (exit code 2)

  • edge/ci/scan_prohibited — rejects NFS/CIFS/cluster-FS volume types in manifests and image layers

INV-02 — No Convergence Tracking

Statement: No convergence protocol, vector clock, CRDT, gossip, or anti-entropy mechanism may exist in any edge/ package.

Rationale: Convergence requires shared coordination state, which violates INV-01 and introduces undefined behaviour under network partition. The edge capability is designed for deterministic relay, not eventual consistency.

Enforcement:

  • edge/ci/scan_prohibited — prohibited symbols: raft, paxos, gossip_convergence, vector_clock, crdt, anti_entropy, and related patterns

INV-03 — No Leader Election

Statement: No node may be designated a leader, primary, or coordinator. All nodes are peers with identical role and authority.

Rationale: Leader election is a form of convergence coordination. It also creates a single point of failure incompatible with the autonomous node model.

Enforcement:

  • edge/ci/scan_prohibited — prohibited election/nomination patterns

  • Code-review checklist sign-off required for any change touching peer selection

INV-04 — Disk Ceiling

Statement: Disk usage never exceeds storage.disk_ceiling_bytes after any Write+fsync returns successfully. The runtime pre-evicts before the ceiling is reached. If pre-eviction cannot free sufficient space, writes are rejected with ErrCeilingExceeded.

Code modules: edge/storage/localstore.go (ceiling check, WithDiskUsedFunc), edge/eviction/local.go, edge/storage/recovery.go

Enforcement:

  • After every Write+fsync: kernel statfs check

  • Synchronous eviction triggered when usage approaches the configured threshold

  • ErrCeilingExceeded returned if post-eviction space is still insufficient

FI Tests:

  • FI-C1-01 TestFI_DiskCeiling_ErrCeilingExceeded

  • FI-C2-01 TestFI_DiskCeiling_ConcurrentWritesAtBoundary

  • FI-C2-02 TestFI_DiskCeiling_EvictionFailure_WriteRejectedCleanly

See also: Disk Ceiling

INV-05 — Platform Assurance Binding

Statement: High-durability mode requires a validated cgroup v2 memory + CPU controller. If the platform cannot provide cgroup v2 assurance at startup, the node logs a warning (edge.assurance.reduced) and refuses to enter high-durability mode.

Code modules: edge/assurance/assurance.go, edge/config/cgroup_linux.go, edge/config/cgroup_other.go

Enforcement:

  • Startup: cgroup v2 probe; absent → LogAssuranceReduced() + edge.assurance.reduced log; high-durability operations refused

FI Tests:

  • FI-C1-05 TestFI_Assurance_HighDurabilityUnavailable

  • TestFI_Assurance_ReducedEnvelopeLogged

See also: cgroup v2

INV-06 — Local-Only Activation

Statement: Activation functions accept only local-state parameters. No remote identifiers, fleet-wide tokens, external coordination primitives, or peer-sourced inputs may appear in activation function signatures.

Code modules: edge/scheduler/local.go, edge/scheduler/scheduler.go

Enforcement: Code review checklist; edge/ci/scan_prohibited (remote-state call patterns)

INV-07 — Bounded Memory

Statement: Memory usage is bounded by the configured resource envelope. cgroup v2 enforces this at the OS level when available. Transport layer transfer buffers are pool-bounded and never grow without bound as peer count scales.

Code modules: edge/storage/localstore.go, edge/transport/transport.go (pool-bounded buffers), edge/quota/localquota.go

Enforcement:

  • cgroup v2 memory controller (when present, via INV-05)

  • Load shedding on inbound when approaching memory ceiling

INV-08 — Idempotent Segment Receive

Statement: Receiving the same segment ID multiple times is safe and has no net effect after the first receive. Deduplication is handled locally; no peer coordination is required.

Code modules: edge/index/localindex.go, edge/storage/localstore.go

Enforcement:

  • Segment ID checked against local index before write

  • Duplicate segment → silently discarded; no error returned to peer

Tests: edge/storage/store_test.go, edge/index/localindex_test.go (unit)

INV-09 — Authorization Boundary

Statement: Segment exchange requires a mutually authenticated TLS connection (mTLS). No segment data is transmitted on unauthenticated or partially-authenticated connections. CRL/OCSP is checked locally for every connection.

Code modules: edge/transport/tcptls.go (mTLS), edge/transport/crl.go (CRL), edge/transport/conn.go

Enforcement:

  • mTLS handshake required and completed before any segment exchange begins

  • Revoked cert → ErrCertRevoked + connection closed immediately

FI Tests:

  • FI-C3-02 TestFI_Transport_RevokedCert_Rejected

  • TestFI_Transport_ValidCert_Passes

  • TestFI_Transport_ExpiredCert_Rejected

See also: Security → mTLS

INV-10 — Mission-Layer Decoupling

Statement: The edge/ module must not import adk/runtime, adk/policy, adk/orchestrator, or any mission-layer package. The edge capability operates independently of whatever agent framework (LangChain, custom, etc.) is running alongside it.

Code modules: edge/ (import isolation enforced at compile time)

Enforcement:

  • edge/ci/scan_dependencies — import-graph check runs on every PR; fails if prohibited imports found

  • Compile-time isolation (build will fail if imports are added)

FI Tests:

  • FI-C1-03 TestFI_MissionDecoupled_NoMissionImport

  • FI-C1-03 TestFI_MissionProcessKill_RelayUnaffected

  • Shell: FI-C1-03_mission_kill.sh

INV-11 — Deterministic Relay

Statement: Relay order and peer selection are fully deterministic for a given local state. No PRNG, wall-clock tie-breaking, or randomized selection is used in the relay path.

Code modules: edge/scheduler/local.go (lexicographic tie-breaking), edge/segment/segment.go

Enforcement:

  • edge/ci/scan_prohibited — PRNG/random call patterns flagged in relay code paths

  • Structural: no PRNG import in relay path

INV-12 — Bounded Retry

Statement: Each segment-relay attempt increments a monotonic counter associated with that segment. When MaxRetryCount is reached, the segment enters the EXHAUSTED terminal state and is never retried again. The counter does not reset on reconnect, timer expiry, or daemon restart (it is persisted in the local index).

Code modules: edge/retry/retry.go (Tracker, RetryExhausted terminal state)

Enforcement:

  • RecordAttempt() monotonically increments; no reset path

  • Terminal EXHAUSTED on reaching MaxRetryCount; subsequent calls return ErrRetryExhausted

FI Tests:

  • FI-C4-01 TestFI_RetryExhaustion_TerminalState

  • FI-C4-02 TestFI_RetryCount_Monotonic

  • FI-C4-03 TestFI_RetryExhausted_NoBeyondWindow

  • Shell: FI-C4-01_retry_exhaustion.sh

See also: Retries

INV-13 — Bounded Per-Peer Ingest Quota

Statement: Ingest from each peer is bounded by a rolling-window token bucket. When the per-peer quota is exceeded, ErrQuotaExceeded is returned and logged as edge.quota.exceeded. The peer session remains open; quota exhaustion is not a disconnection event.

Code modules: edge/quota/localquota.go (LocalEnforcer, rolling-window token bucket)

Enforcement:

  • Per-peer bucket checked on every ingest call

  • edge.quota.exceeded log entry on breach

FI Tests:

  • FI-C3-03 TestFI_Quota_EnforcedPerPeer

  • TestFI_Quota_PeerIsolation

Do Not Do

  • ❌ Do NOT add a convergence/gossip/CRDT import to any edge/ package — edge/ci/scan_prohibited catches this in CI

  • ❌ Do NOT designate any node as a leader, primary, or coordinator for any purpose

  • ❌ Do NOT reset a retry counter on reconnect or timeout — INV-12 requires monotonic persistence

  • ❌ Do NOT allow segment exchange before mTLS handshake completes — INV-09

  • ❌ Do NOT import adk/runtime, adk/policy, or adk/orchestrator from edge/ — INV-10

  • ❌ Do NOT use PRNG or wall-clock tie-breaking in the relay scheduler path — INV-11

See Also