Edge Node Deployment Topology — SysML Architecture Note

This models the deployment topology of the edge node (how it is deployed, where, with what footprint, at what scale, under what sovereignty/observability constraints) — not the discovery wire-contract internals, which the binding 2026-05-09 spec already owns. The canonical model is the DPF EA graph (EaElement/EaRelationship); this markdown is the human-readable companion and the source for the future seed. Per the substrate spec’s stance, the edge node is the planned Phase D “network topology bridge” of the living-architecture program; this note is the hand-authored interim until that extractor makes the model self-maintaining (see §8 — the convergence plan).

Legend. [D] = deterministic fact (grounded in code/schema/scripts today). [J] = architect-authored judgment (design intent from the source spec, not yet realized). Verification status: green = automated test passes today; planned = future slice.

SysML Architecture Note (skill template)

• Scope: the Authority-Core ↔ edge-node deployment relationship — deploy posture (opt-in), remote provisioning, minimal footprint, the fleet-across-contexts pattern (base + retail + MSP), and the operational envelope the review pass made first-class (sovereignty, network/auth boundary, fleet scale/backpressure, Authority-side observability). It changes the platform’s deployment decomposition; it does not change the discovery ingestion contract.
• Changed requirements/constraints: REQ-EDGE-1…14 + CON-EDGE-1 (footprint/outbound-only/scope-from-token) + CON-EDGE-2 (observability cardinality + sovereignty redaction). REQ-EDGE-1/2/6/7 deterministic today; REQ-EDGE-3/4/5/8–14 are the realized-later posture + operational changes.
• Changed interfaces/ports: no change to /api/v1/edge/* wire shapes [D]; adds the portal “add a node on another machine” provisioning interface [J], an install-state.json edge deploy-record port [J], and an Authority-side fleet-metrics exporter port [J] (Prometheus reads the exporter, never the remote node).
• Allocations: agent → services/edge-node{,-go}; enrollment/trust → apps/web/app/api/v1/edge/* + resolveEdgeNodeAuth; fleet registry → EdgeNode/BootstrapToken + /platform/edge-nodes; deploy gate → install-dpf.sh/fresh-install.ps1/dpf-start.* + docker-compose.edge*.yml; observability → /api/v1/edge/metrics + metrics-loop.ts + Authority Prometheus/Grafana. (Full table §3.)
• Verification cases: VC-EDGE-LIFECYCLE, VC-EDGE-STATE, VC-EDGE-AIRGAP, VC-EDGE-REMOTE-LAN green today; VC-EDGE-OPTIN, VC-EDGE-REMOTE-EASY, VC-EDGE-FOOTPRINT, VC-EDGE-FLEET-*, VC-EDGE-NETAUTH, VC-EDGE-SCALE, VC-EDGE-OBS, VC-EDGE-SOVEREIGNTY planned.
• Data authority impact: no new source-of-truth tables. Identity stays on Principal/PrincipalAlias; node state on EdgeNode/BootstrapToken/EdgeNodeCapability; the only new fact is a non-DB install-state.json edge record. Every derived operational record is scope-tagged from resolveEdgeNodeAuth. The SysML model seeds into the existing EA graph (no new EA tables — substrate spec §3 boundary).
• EA/current-state catch-up: first SysML coverage of the edge node at all; closes part of the living-graph Phase D gap with a hand-authored note ahead of the extractor.
• Open architecture risks: (1) note vs. future extractor drift — this note is the interim source, the extractor BI links to EP-ARCH-GRAPH-LIVE. (2) Default-flip must grandfather running local nodes. (3) Retail per-location scope is [J] pending a site-model audit. (4) Authority Core fan-in + Prometheus cardinality are the scale risks; sovereignty can leak through observability outputs, not just API payloads. (Full list: source spec §14.)

1. Requirements (requirement)

Stable IDs are the infraCiKeys for the future EA seed (sysml:req:REQ-EDGE-N).

2. Constraints / parametric (constraint)

CON-EDGE-1 — Edge footprint & isolation constraint. For all topologies:

• inbound_listeners(edge) = ∅ — outbound-only to DPF_AUTHORITY_URL (FP1). [D]
• persistent_stores(edge) = { state.json } — no relational/graph/vector store (FP2). [D]
• llm_runtimes(edge) = ∅ — no inference on the edge (FP3). [D]
• install_artifacts(edge) ⊆ { single_binary, single_compose_file } — no monorepo clone (FP4). [J]
• scrape_endpoints(edge) = ∅ by default — no inbound Prometheus target (FP5). [J]
• scope(node) = scope(bootstrapToken) — derived at enrollment, server-enforced; customerSiteId ⇒ customerAccountId. [D]
• deploy(local_node) ⇒ operator_choice ∧ recorded(install-state.json.edge) — the deploy gate (REQ-EDGE-3). [J]

CON-EDGE-2 — Observability & sovereignty constraint. (FP6–FP7, REQ-EDGE-11/14):

• label_set(metrics) ⊆ { scopeIds, nodeId, capability, trustState, versionFamily } — bounded cardinality. [J]
• {MAC, hostname, SSID, VLAN, controllerName} ∩ (metric_labels ∪ grafana_annotations ∪ long_lived_audit_text) = ∅ — raw identifiers stay in inventory/query tables, redacted from observability + command output + logs. [J]
• scrape_targets(authority_prometheus) ∩ remote_customer_nodes = ∅ — edge metrics arrive only by authenticated push to /api/v1/edge/metrics. [J]
• saas_export(edge_evidence) = off by default — a deliberate export is a recorded lower-assurance estate choice, not hidden behavior. [J]

Realized by: the standalone/edge compose overlays’ network_mode/${VAR:?} guards + cap_add minimalism [D]; resolveEdgeNodeAuth scope derivation [D]; the proposed install-state.json edge record + start-script reads, the Authority-side exporter, and redaction/retention guards [J].

3. Part definitions (part_definition) and allocations

4. Interfaces / ports (interface_definition)

5. State machines (state)

SM-DEPLOY — Local deploy gate [J] (REQ-EDGE-3): absent (default) → operator-chooses → recorded(install-state) → overlay-included → enrolled. Today the path is installed → bundled → auto-enrolled → auto-trusted with no absent start state — that inversion is what this model changes.

SM-TRUST — Node trust lifecycle [D] (REQ-EDGE-6): pending → trusted → { quarantined → trusted | revoked(terminal) }. Local chosen node may transition enrolled → trusted automatically; remote node holds at pending until operator approve. Quarantine is route-effective: a quarantined node may heartbeat (so operators see it) but its discovery/metrics submissions are rejected/diverted (REQ-EDGE-12).

SM-ENROLL — Agent enrollment [D]: first-run(has bootstrap token) → enroll → persist state.json(node token) → { heartbeat-loop ∥ sweep-loop ∥ metrics-loop } → on 401 node_revoked → clear state → exit. Subsequent runs skip enroll and read state.json.

SM-LIFECYCLE — Operational node lifecycle [J] (REQ-EDGE-13, spec §8A.3): created → pending → trusted → degraded → quarantined → revoked → retired. degraded is an observability/UX concept, not a trustState column value: a node that is trusted yet behind on version, missing a capability, failing a collector, exceeding its cardinality budget, or running on stale policy. Surfaced by PART-EDGE-observability, acted on by PART-EDGE-fleetops.

6. Verification cases (verification_case)

7. Traceability summary

REQ-EDGE-1 ──satisfies── PART-EDGE-authority, PART-EDGE-agent, PART-EDGE-enroll ──verifies── VC-EDGE-LIFECYCLE ✓
REQ-EDGE-3 ──satisfies── PART-EDGE-deploygate ──verifies── VC-EDGE-OPTIN (planned)
REQ-EDGE-4 ──satisfies── PART-EDGE-provision, PART-EDGE-token ──verifies── VC-EDGE-REMOTE-EASY (planned)
REQ-EDGE-5 ──satisfies── PART-EDGE-agent ──refines── CON-EDGE-1 ──verifies── VC-EDGE-STATE ✓, VC-EDGE-AIRGAP ✓, VC-EDGE-FOOTPRINT (planned)
REQ-EDGE-11 ─satisfies── PART-EDGE-ingest, PART-EDGE-observability ──refines── CON-EDGE-2 ──verifies── VC-EDGE-SOVEREIGNTY (planned)
REQ-EDGE-12 ─satisfies── PART-EDGE-enroll, PART-EDGE-token, PART-EDGE-provision ──verifies── VC-EDGE-NETAUTH (planned)
REQ-EDGE-13 ─satisfies── PART-EDGE-fleetops, PART-EDGE-ingest ──verifies── VC-EDGE-SCALE (planned)
REQ-EDGE-14 ─satisfies── PART-EDGE-observability ──refines── CON-EDGE-2 ──verifies── VC-EDGE-OBS (planned)
CON-EDGE-1 ──refines──── REQ-EDGE-5, REQ-EDGE-7, REQ-EDGE-3
CON-EDGE-2 ──refines──── REQ-EDGE-11, REQ-EDGE-14
PART-EDGE-agent ──sysml_allocates──▶ code:subsystem:services/edge-node-go
PART-EDGE-registry ──sysml_traces──▶ prisma:model:EdgeNode   (the Phase-D cross-layer edge, per PR #2073 pattern)
PART-EDGE-observability ──sysml_traces──▶ archimate:application_component (Authority Prometheus/Grafana)

8. What is modeled now vs. the extractor convergence plan

Authored now [J] (this note): the full deployment-topology model — REQ-EDGE-1…14, CON-EDGE-1/2, the ten parts, nine interfaces, four state machines, thirteen verification cases. Hand-authored architect judgment over verified current state, including the operational/sovereignty/observability envelope the review pass made first-class.

Deterministic today [D]: the Authority-client topology, deployment-target-neutral binary, outbound-only footprint, pending→approve trust, scope-from-token, and the authenticated metrics push are all real and (for the first four) test-backed (VC-EDGE-LIFECYCLE / STATE / AIRGAP / REMOTE-LAN green).

Convergence plan (Phase D extractor). This note is the interim source of truth. The living-architecture program’s network-topology bridge will add buildEdgeTopologyModel(facts) → SysmlDesiredModel, projecting each live EdgeNode row as a part_usage (layer="network", refinementLevel="actual", sysmlKey="runtime:edge-node:<nodeId>") allocated to PART-EDGE-agent and traces-linked to prisma:model:EdgeNode — the cross-layer edge pattern established by PR #2073. The fleet-metrics/observability parts likewise project from the metrics + EdgeNodeCapability substrate. When that lands, the actual fleet self-maintains in the graph and this note keeps only the logical definitions + judgment. The extractor is filed against EP-ARCH-GRAPH-LIVE (source spec §13 BI 5) so the two never compete.