Edge Node — Event Envelope (Operator Guide)

Slice 0 of the edge-node detection engine. This is the wire shape that every edge-side detector (built-in, declarative, scripted, sidecar) uses when posting to POST /api/v1/edge/events. Full design spec lives at docs/superpowers/specs/2026-05-21-edge-event-envelope-design.md. BI: BI-9FE9D48D.

TL;DR

Envelope shape

{
  "runKey": "7c2d6f4a-3b1e-4d8a-9e1b-1234567890ab",
  "nodeId": "edge_abc",
  "observedAt": "2026-05-21T02:30:01Z",
  "eventsVersion": "1",
  "events": [
    {
      "dedupKey": "snmp.trap:10.0.0.5:ifaceDown:ifIndex=42",
      "source": "snmp.trap",
      "component": "10.0.0.5",
      "eventGroup": "network",
      "eventClass": "interface_down",
      "severity": "error",
      "action": "trigger",
      "summary": "Interface ifIndex=42 link state down on 10.0.0.5",
      "occurredAt": "2026-05-21T02:30:00Z",
      "customDetails": { "ifIndex": 42, "ifDescr": "GigabitEthernet0/1" }
    }
  ]
}

Field reference

Envelope

EdgeEvent

Dedup key composition

The portal collapses events on (edgeNodeId, dedupKey). Detectors are responsible for composing keys that collapse correctly:

<source>:<component>:<eventClass>[:<instance>]

Examples:

snmp.trap:10.0.0.5:ifaceDown:ifIndex=42
syslog:fw01:login_failure:src_ip=192.0.2.7
ping:192.168.0.10:loss
ups.nut:rack-a:on_battery
unifi.events:aa:bb:cc:dd:ee:ff:client_blocked

If a detector observes genuinely distinct conditions on the same component, vary instance so the portal keeps them separate.

Lifecycle

Response

{
  "ok": true,
  "runKey": "7c2d6f4a-3b1e-4d8a-9e1b-1234567890ab",
  "nodeId": "edge_abc",
  "accepted": 5,          // events in this batch
  "created": 2,           // new rows
  "reopened": 1,          // resolved -> triggered
  "acknowledged": 0,
  "resolved": 1,
  "updated": 1,           // trigger replay against an open row
  "remaining": 29,        // rate-limit budget remaining this minute
  "route": "/api/v1/edge/events"
}

Error responses

Capability declaration

Edge nodes that emit events should advertise events.emit in advertisedCapabilities during enroll and report status in heartbeats. The portal’s accepted-capabilities negotiation includes it in RESERVED_CAPABILITIES (packages/db/src/edge-node-types.ts).

Quick local check (cURL)

curl -X POST https://localhost:3000/api/v1/edge/events \
  -H "Authorization: Bearer dpfedge_<your_token>" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "runKey": "7c2d6f4a-3b1e-4d8a-9e1b-1234567890ab",
  "observedAt": "2026-05-21T02:30:01Z",
  "eventsVersion": "1",
  "events": [{
    "dedupKey": "ping:192.168.0.10:loss",
    "source": "ping",
    "component": "192.168.0.10",
    "severity": "warn",
    "action": "trigger",
    "summary": "Packet loss to 192.168.0.10 (35% over 60s)",
    "occurredAt": "2026-05-21T02:30:00Z"
  }]
}
JSON

Change events (Slice 1)

Slice 1 of the detection engine. BI: BI-8405FDA5. Spec: 2026-05-21-edge-change-events-design.md.

Set eventType: "change" on an event to record a point-in-time fact — a deploy, config push, feature-flag flip, infra apply — that the correlation engine (separate slice) joins to alerts that fire shortly after. This is the highest-leverage pattern borrowed from PagerDuty’s PD-CEF model: most production incidents trace back to a recent change, and surfacing the join shaves the biggest single chunk off MTTR.

Wire shape: identical to an alert event. The discriminator is eventType. Omit it (or set "alert") and the event lands in EdgeEvent with the Slice 0 lifecycle. Set it to "change" and the event lands in ChangeEvent instead.

Semantic differences from alerts:

Example — a deploy:

{
  "eventType": "change",
  "dedupKey": "git.deploy:web@abcdef1",
  "source": "git.deploy",
  "component": "web",
  "eventGroup": "deploy",
  "eventClass": "deploy",
  "severity": "info",
  "action": "trigger",
  "summary": "Deploy abcdef1 to web (production)",
  "occurredAt": "2026-05-21T02:28:30Z",
  "customDetails": {
    "gitSha": "abcdef1",
    "deployedBy": "ci-bot",
    "targetEnv": "production"
  }
}

A mixed batch (alerts + changes) is fine — they share one envelope and land in one transaction. The route response splits the counts:

{ "ok": true, "accepted": 4, "created": 2, "changes": 2, ... }

What this is NOT (yet)

Slice 0 + Slice 1 ship the envelope + ingest + per-event persistence only. There is no event list UI, no correlation engine joining alerts to changes, no escalation, no on-call. Those land in follow-on slices:

• Slice 2 — edge detector framework (registry/scheduler/bus/dedupe/transport in edge-node-go)
• Slice 3 — first built-in detector pack (reachability, SNMP poll+trap, syslog, ARP/DHCP, host self)
• Portal slice — alert ⇄ change correlation engine (N-minute window join)
• Portal slices A / B / C — incident lifecycle UX, escalation, on-call

Track the parent BI BI-9FE9D48D (foundation) and follow-on BI-8405FDA5 (Slice 1 change events).