atelier/domains/edge/first-principles.md

# Edge — First Principles

## 1. The Principles

### P1. Proximity is the Design Driver
Compute, storage, and data are placed near the user or the data
source. At the edge, latency is a correctness constraint (C1), not a
performance preference — a late answer is a wrong answer when the
round trip to a central region exceeds the user's or device's
tolerance. This is the geographic expression of `C4 Locality`:
performance's locality is algorithmic (data near compute); edge's
locality is geographic (compute near user/data source). Placement is
a design decision, not an accident of deployment, and it is
constrained by `P8 Geographic Distribution`. The proximity angle is
the distinguishing trait of the edge domain per D-061: this is what
separates edge from `domains/performance/` (which owns *generic*
measurement and optimization, not placement).

### P2. Offline is a First-Class State
The system continues to operate when disconnected from the center.
Partition is the norm, not the exception; reconciliation happens on
reconnect, never assumed to be instant. An app that crashes on
disconnect has no offline state and is unengineered. Offline
operation derives from `C5 Reversibility` — the disconnected state
is reversible back to consistency via reconciliation — and `C1
Correctness`, because correctness under partition is the contract,
not eventual correctness as a hedge. This is the foundation for
`domains/edge/offline-first.md` and the precondition for the
bounded-conflict discipline of `P4`.

### P3. Resources are Constrained and Declared
Edge nodes — IoT sensors, gateways, point-of-sale devices, CDN PoP
caches, 5G MEC nodes — have bounded CPU, memory, power, and
bandwidth. Constraints are declared per node class, never assumed
infinite. An undeclared budget is a defect: unbounded growth is a
bug, and a constrained device with no budget will OOM or exhaust
power. This derives from `C8 Economy` (use no more than the task
requires) and `C1 Correctness` (a node that exceeds its bounds has
failed). This is the edge-specific angle on `domains/performance/P4
Resource Bounds` — performance owns the generic principle; edge owns
the constrained-device reality. See `domains/edge/iot.md` for the
per-device-class application.

### P4. Sync Conflicts are Bounded, Not Infinite
Divergent state across partitioned nodes converges. Oscillation and
infinite sync loops are correctness failures, not eventual
consistency. A merge that never terminates is a livelock; a CRDT
without merge semantics or an LWW without a monotonic clock can
oscillate forever. This derives from `C1 Correctness` (convergence is
a correctness contract) and `C5 Reversibility` (divergent state is
reversible back to convergence). The bound may be eventual (CRDTs) or
arbitrated (LWW with vector clocks), but it must exist. This is the
foundation for `domains/edge/sync.md` and the rule the
`edge-sync-loop` chaos anti-pattern breaches.

### P5. Edge Operations are Idempotent
Sync, cache fill, and device commands are retried by nature — the
network is partition-prone and the operation will be re-attempted.
Idempotency keys (or deterministic operations) make retries safe. A
non-idempotent edge write retried with side effects doubles the
effect; a non-idempotent cache fill under retry corrupts the cache.
This derives from `C1 Correctness`: correctness under retry is the
contract, not a nice-to-have. This parallels `domains/messaging/P3
Consumers are Idempotent` (cross-process delivery) and is the edge's
device-and-cache-flavored analog — see `domains/edge/iot.md` for
device command idempotency and `domains/edge/cdn.md` for cache-fill
idempotency.

### P6. Cache Invalidation is Explicit
Edge caches carry a defined invalidation or TTL strategy. A
stale-forever cache under partition is a silent correctness defect;
a TTL-less cache with no explicit invalidation is a bug, not a
feature. This derives from `C1 Correctness` (cached state must be
correct) and `C3 Simplicity` (a defined invalidation strategy is
simpler and clearer than ad-hoc staleness). This is distinct from
`domains/performance/P5 Caching with Intent`, which owns *generic*
caching and optimization; edge owns the *geographic,
partition-aware* invalidation angle — when a PoP is partitioned from
the origin, the invalidation strategy is the correctness mechanism.
See `domains/edge/cdn.md` for purge strategies (URL vs soft vs
surrogate-key) and the edge-cache-vs-origin decision matrix.

### P7. Partial Degradation is Engineered
The system degrades gracefully when an edge node or link fails. A
partial service is a designed state with a defined contract, not a
crash. One node's failure must not collapse the whole fleet; the
degraded mode is documented, observable, and recoverable. This
derives from `C1 Correctness` (the degraded contract is a
correctness bound) and `C5 Reversibility` (recovery from degradation
is reversible by construction). A crash-on-node-failure system has
no degradation contract — it has an all-or-nothing failure mode that
violates the fleet assumption. See `domains/edge/iot.md` for
device-drop degradation and `domains/edge/offline-first.md` for
partition degradation.

### P8. Geographic Distribution is a First-Class Constraint
The fleet is geo-distributed; routing, fan-out, and data placement
are location-aware decisions, not accidents of deployment. The
system is many nodes across many locations, not a single deployment.
Data residency, regional latency, and PoP selection are engineered,
not discovered in production. This derives from `C4 Locality` (the
placement of data and compute is a locality decision) and `C6
Composability` (the fleet composes from location-aware parts, each
with its own contract). This is the structural companion to `P1
Proximity`: P1 says *where* compute should be (near the user); P8
says the *distribution* of compute across geographies is a
first-class constraint. See `domains/edge/cdn.md` for multi-CDN
routing.

### P9. Identity is Constrained at the Edge
Edge devices and nodes hold scoped, minimal credentials. No edge
node is a cluster-admin-equivalent; device identity is per-device,
not shared. One compromise must not equal a fleet compromise. This
derives from `C1 Correctness` (security is a subset of correctness —
an exploitable edge node does not do what it was supposed to do) and
`C8 Economy` of trust (the credential scope is minimal for the task).
A shared edge-device credential is the edge analog of a
cluster-admin GitOps robot — blast radius is unbounded. See
`domains/security/secrets.md` for the general secret-hygiene
principles and `domains/edge/iot.md` for device provisioning.

### P10. Edge Observability Survives Partition
Telemetry is local-first: buffered on the node and forwarded on
reconnect. Partition does not blind the operator. A fire-and-forget
telemetry pipeline loses data when the link drops; a local-first
buffer survives. This derives from `C7 Observability` (the fleet's
behavior is visible to the operator) and `C5 Reversibility` (the
buffered telemetry is reversible back to visibility on reconnect).
This is distinct from `domains/observability/P1 Structured by
Default`, which owns *generic* structured telemetry; edge owns the
*partition-survivable, local-first* angle. See
`domains/observability/metrics.md` and
`domains/observability/logging.md` for the generic structured-
telemetry foundations edge builds on.

## 2. Core Principle Trace

Each edge P-rule derives from one or more core C-rules (C1–C8). The
matrix extension lands in P4 of the v0.4 plan; the traces below are
authoritative. Edge is a broad-derivation domain touching 7 of 8
core principles (C1, C3, C4, C5, C6, C7, C8); C2 (Clarity) is not a
primary derivation — edge clarity is indirect (a cache with explicit
invalidation is clearer than one without, but the primary trace is
C1/C3).

| P-rule | Core | Why |
|--------|------|-----|
| P1 Proximity is the Design Driver | C4, C1 | Locality of compute near user/data; correctness via latency |
| P2 Offline is a First-Class State | C1, C5 | Correctness under partition; reversibility of reconciliation |
| P3 Resources are Constrained and Declared | C8, C1 | Economy of constrained nodes; correctness of declared bounds |
| P4 Sync Conflicts are Bounded, Not Infinite | C1, C5 | Correctness of convergence; reversibility of divergent state |
| P5 Edge Operations are Idempotent | C1 | Correctness under retry |
| P6 Cache Invalidation is Explicit | C1, C3 | Correctness of cached state; simplicity of defined invalidation |
| P7 Partial Degradation is Engineered | C1, C5 | Correctness of degraded modes; reversibility of recovery |
| P8 Geographic Distribution is a First-Class Constraint | C4, C6 | Locality of placement; composability of the fleet |
| P9 Identity is Constrained at the Edge | C1, C8 | Correctness via security; economy of trust |
| P10 Edge Observability Survives Partition | C7, C5 | Observability of the fleet; reversibility of buffered telemetry |

## 3. What Violates These Principles

| Violation | Principle Breached |
|-----------|-------------------|
| Central-region-only deployment for a latency-bound workload | P1 Proximity is the Design Driver |
| App that crashes on disconnect (no offline state) | P2 Offline is a First-Class State |
| Undeclared edge-node resource budget (assumes infinite CPU/memory) | P3 Resources are Constrained and Declared |
| Sync loop that oscillates forever (CRDT without merge-semantics, LWW without monotonic clock) | P4 Sync Conflicts are Bounded, Not Infinite |
| Non-idempotent edge write (cache-fill or device command retried with side effects) | P5 Edge Operations are Idempotent |
| TTL-less edge cache under partition (stale-forever, no explicit invalidation) | P6 Cache Invalidation is Explicit |
| Crash-on-node-failure (no partial-degradation contract) | P7 Partial Degradation is Engineered |
| Random geographic placement (no location-aware routing) | P8 Geographic Distribution is a First-Class Constraint |
| Shared edge-device credential (one key for the whole fleet) | P9 Identity is Constrained at the Edge |
| Fire-and-forget telemetry (no on-node buffer; data lost on partition) | P10 Edge Observability Survives Partition |
| Blocking call on a constrained IoT device with no timeout | P3, P5 (blocks the node; retry unsafe without idempotency) |
| Multi-CDN routing with no PoP-selection logic (latency uncontrolled) | P8, P1 (placement not a design decision) |

## 4. Relationship to Other Domains

Edge computing is the engineering discipline of placing compute,
storage, and data **near the source of generation or consumption**
rather than in a centralized cloud. The distinguishing constraints are
latency-bound operation, resource-constrained nodes,
geo-distribution as a fleet, and partition-prone operation. Edge
overlaps three existing domains by *subject* but not by *angle*: per
D-061, edge owns the proximity/location/constraint/disconnection
concerns that only arise at the network edge. The C4 Locality
emphasis is the discriminator: performance's locality is algorithmic
(data near compute); edge's locality is geographic (compute near
user/data source). Cross-links are one-directional outward (per
D-026 extended); no back-link edits to v0.1/v0.2/v0.3 content.

- `domains/performance/frontend` ← P6 (edge owns geographic,
  partition-aware cache invalidation; performance owns *generic*
  caching and measurement — D-061 boundary)
- `domains/performance/P4 Resource Bounds` ← P3 (edge owns
  constrained-device reality; performance owns the generic
  unbounded-growth-is-a-bug principle)
- `domains/observability/metrics` ← P10 (cache-hit ratio, edge
  telemetry aggregation; edge owns the local-first angle, observability
  owns generic structured metrics)
- `domains/observability/logging` ← P10 (local-first logging buffered
  on-node and forwarded on reconnect)
- `domains/concurrency/patterns` ← P5 (the offline write-queue is
  the cross-partition analog of the in-process bounded buffer —
  concurrency owns in-process; edge owns partition-survivable)
- `domains/security/secrets` ← P9 (device credentials are scoped,
  per-device, never shared — edge owns the constrained-identity
  angle; security owns the general secret hygiene)
- `domains/security/input-validation` ← P6 (cache poisoning
  prevention — edge cache keys are a validation surface)
- `domains/data/migrations` ← P4 (schema migration under sync must
  reconcile across partitioned nodes; data owns the generic migration
  discipline, edge owns the partitioned-reconcile angle)

> Note: cross-links to `domains/messaging/` (e.g., MQTT QoS parallels
> for delivery semantics) are intentionally omitted here — the
> messaging domain is authored in P2. The intra-v0.4 edge↔messaging
> links are added in P5 (ATELIER-114 per IDEATE-40) once both
> domains exist; the dangling link is acceptable per D-053.