{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://synacl.com/protocol/v1/schemas/crash.json",
  "title": "Crash report",
  "description": "A one-shot report of the previous boot's crash, published once on `<prefix>/crash` after the gateway reconnects following a reset whose `esp_reset_reason()` was a panic, an interrupt or task watchdog, or a brownout — then cleared, so it is never sent twice. A deliberate restart, a power cycle or a firmware update is NOT a crash: do not publish for those. `crumbs` are breadcrumbs the firmware keeps warm in RTC memory across the reset (RTC_NOINIT, validated by a magic word and CRC): the last log lines, the task that was running or that the task watchdog named as stuck, the device and function code being polled, free heap. `summary` is the ESP-IDF core-dump summary — the faulting program counter and backtrace as raw addresses — on boards that have a `coredump` partition (factory-flashed; OTA cannot add one). The platform symbolizes those addresses against the release's symbol table, so send them untouched. It stores the report for 90 days (GET /gateway/:id/crashes), raises a critical `gateway/crash` event with a push notification, and relays it live as `gw:crash`. A brownout is a power problem, not a firmware bug: say so in your own logs too.",
  "type": "object",
  "required": [
    "ts",
    "reason",
    "uptimeMs",
    "fw"
  ],
  "properties": {
    "ts": {
      "description": "Epoch milliseconds when the report was published (after reconnect, when the gateway clock is synced).",
      "type": "integer",
      "minimum": 0
    },
    "reason": {
      "description": "Mapped from `esp_reset_reason()`: `panic` (ESP_RST_PANIC — an exception or abort()), `int_wdt` (ESP_RST_INT_WDT), `task_wdt` (ESP_RST_TASK_WDT), `brownout` (ESP_RST_BROWNOUT), `unknown` for any other reason you still consider a crash.",
      "type": "string",
      "enum": [
        "panic",
        "int_wdt",
        "task_wdt",
        "brownout",
        "unknown"
      ]
    },
    "uptimeMs": {
      "description": "How long the crashed boot had been running, from the breadcrumbs (0 if they did not survive).",
      "type": "integer",
      "minimum": 0
    },
    "fw": {
      "description": "The firmware version that CRASHED (semver, as in the capability report). It names the symbol table the backtrace is resolved against, so it must be the version that was running — not the one now installed, if an OTA happened in between.",
      "type": "string",
      "maxLength": 32
    },
    "crumbs": {
      "description": "Breadcrumbs kept warm across the reset. Omit the whole object when they did not validate.",
      "type": "object",
      "properties": {
        "lastLog": {
          "description": "The last log lines before the reset, oldest first.",
          "type": "array",
          "maxItems": 8,
          "items": {
            "type": "string",
            "maxLength": 64
          }
        },
        "task": {
          "description": "The FreeRTOS task that was running — or, for `task_wdt`, the one the watchdog reported as stuck.",
          "type": "string",
          "maxLength": 32
        },
        "lastDevice": {
          "description": "The device (config/push `_id`, or its name) being polled when the crumbs were last updated.",
          "type": "string",
          "maxLength": 64
        },
        "lastFc": {
          "description": "The Modbus function code of the poll in flight.",
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "freeHeap": {
          "description": "Free heap in bytes at the last crumb update.",
          "type": "integer",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "summary": {
      "description": "ESP-IDF `esp_core_dump_get_summary()`, raw. Only boards with a `coredump` partition have it (capability `coredump`).",
      "type": "object",
      "properties": {
        "excTask": {
          "description": "The task that faulted.",
          "type": "string",
          "maxLength": 32
        },
        "excPc": {
          "description": "Program counter at the fault, as an unsigned integer (decimal, not a hex string).",
          "type": "integer",
          "minimum": 0
        },
        "excCause": {
          "description": "Xtensa EXCCAUSE register.",
          "type": "integer",
          "minimum": 0
        },
        "excVaddr": {
          "description": "Faulting virtual address (EXCVADDR).",
          "type": "integer",
          "minimum": 0
        },
        "bt": {
          "description": "Backtrace program counters, innermost first, as unsigned integers. At most 16.",
          "type": "array",
          "maxItems": 16,
          "items": {
            "type": "integer",
            "minimum": 0
          }
        },
        "elfSha": {
          "description": "SHA-256 of the firmware ELF the core dump was taken from (hex, as the IDF reports it), to confirm the symbol table matches.",
          "type": "string",
          "maxLength": 64
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}
