ProjectEventFeedPage

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/run402-com/json-schema/run402-com-project-event-feed-page-schema.json",
  "title": "ProjectEventFeedPage",
  "description": "One page of the cursored events feed — oldest-first by default (catch-up), newest-first with `order=desc` (display). Store `cursor` and pass it as `?cursor=` next time to catch up in one call; a desc page walks older history via `before_cursor` instead. Events become visible within seconds (a short visibility watermark orders concurrent commits, identically in both orders) and are never lost after it.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/run402-com-openapi.json#/components/schemas/ProjectEventFeedPage",
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ProjectEvent"
      }
    },
    "cursor": {
      "type": "string",
      "description": "High-water mark: the last served event's cursor (present even when `events` is empty — an empty page echoes your own `cursor` unchanged). On `order=desc` pages it is the LIVE high-water mark — the same value a caught-up ascending read with the same filters would return — so a display surface hands off to catch-up polling without a discovery call."
    },
    "has_more": {
      "type": "boolean",
      "description": "True when more events are immediately available past `cursor` — poll again right away. On `order=desc` pages: true when OLDER rows remain past this page (within any active `source`/`event_type` filter) — follow `before_cursor`."
    },
    "before_cursor": {
      "type": "string",
      "description": "`order=desc` pages only, and only when older rows remain (`has_more: true`): pass as `?order=desc&before=` for the next OLDER page. Absent on the oldest retained page — its absence IS the end-of-history signal, so you never fetch a trailing empty page. Same opaque cursor encoding as `cursor`."
    },
    "reset": {
      "type": "boolean",
      "description": "True when the supplied position was unusable — an ascending `cursor` that was malformed or older than the retention floor (swept rows can no longer be proven seen), or a malformed desc `before`. The page restarts (ascending: from the earliest retained event; desc: from the newest page) and `earliest_cursor` is provided — never a bare 4xx, never a silent skip."
    },
    "earliest_cursor": {
      "type": "string",
      "description": "Present only when `reset` is true: a cursor positioned just before the earliest retained event for this scope."
    },
    "platform_incidents": {
      "type": "array",
      "description": "Sidecar overlay of GLOBAL (unattributed) platform incidents — open incidents plus incidents resolved after the caller's cursor position. It is a sidecar, NOT interleaved into `events[]`: the numeric cursor stays monotonic and uncorrupted. Each entry carries a stable `id` so a client dedups across reads. Attributed (per-project) incidents are NOT here — they arrive as `platform_incident` entries inside `events[]`. Present only when at least one such global incident applies; omitted otherwise.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "subsystem",
          "severity",
          "scope",
          "status",
          "started_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable incident id (`inc_…`) — the dedup key across feed reads."
          },
          "subsystem": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "minor",
              "major"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "global"
            ],
            "description": "Always `global` in the overlay — attributed incidents ride `events[]`."
          },
          "status": {
            "type": "string",
            "enum": [
              "ongoing",
              "resolved"
            ]
          },
          "summary": {
            "type": "string"
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Null while the incident is ongoing."
          }
        }
      }
    },
    "platform_status": {
      "type": "string",
      "enum": [
        "degraded"
      ],
      "description": "Present and equal to `degraded` only while an open platform incident is global or affects this caller's projects; omitted when clear. A health-assessment rider (same field as on GET /agent/v1/me/status and GET /tiers/v1/status), never added to unrelated 200s."
    }
  },
  "required": [
    "events",
    "cursor",
    "has_more",
    "reset"
  ],
  "$defs": {
    "ProjectEvent": {
      "type": "object",
      "description": "One immutable fact from the project events feed. `id` doubles as a cursor: pass any event's id (or the page-level `cursor`) as `?cursor=` to resume after it.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Opaque event cursor (`evc_...`). Never parse it; store and echo it as `?cursor=`."
        },
        "event_type": {
          "type": "string",
          "description": "Flat snake_case event name, e.g. `deploy_activated`, `error_fingerprints_observed`, `platform_incident`, `mailbox_suspended`, `project_transfer_initiated`, `organization_past_due`, `verification_failed`, `webhook_disabled` (platform vocabulary) or an app-chosen name such as `signature_completed` (app-events-emit-lane, `source: \"app\"`). The vocabulary is the platform notification event set plus feed-native events plus whatever an app's own deployed code has emitted via `POST /projects/v1/:project_id/events`. `platform_incident` is an ATTRIBUTED platform-fault event: it lands on an affected project's feed when a platform incident resolves, with a compact payload `{ incident_id, subsystem, severity, scope, status, started_at, resolved_at, summary, impact: { count } }` — the real number of that project's invocations the platform, not the app, caused to fail. Global (unattributed) incidents ride the page-level `platform_incidents[]` overlay instead."
        },
        "severity": {
          "type": "string",
          "enum": [
            "info",
            "notice",
            "warn",
            "critical"
          ],
          "description": "event-attention-rules: how significant the event is, stamped at write and never updated. An app event carries what its emitter declared (`info` when it declared nothing); a platform event carries the level registered for its type. States what happened, not how important the class is: `verification_succeeded` is `notice`, `mailbox_suspended` is `warn`."
        },
        "class": {
          "type": "string",
          "description": "Event class stamped at write time: `lifecycle`, `threshold`, `security`, `recovery`, `billing_critical`, `destructive_lifecycle`, `verification`, `platform_incident`, `digest`, or `app` (app-events-emit-lane). Mandatory classes (`security`, `recovery`, `billing_critical`, `destructive_lifecycle`, `verification`, `platform_incident`) are retained 365 days; everything else — including `app`, which is NEVER a mandatory class — 90 days. `platform_incident` is mandatory for the retention floor only — the platform's confession log is not the first thing swept — and is never delivered as a preference-gated notification."
        },
        "source": {
          "type": "string",
          "description": "Producer discriminator. `\"app\"` for a row written by a project's own deployed code via `POST /projects/v1/:project_id/events`; any other value (`gateway`, `apply`, `email-lambda-events`, …) is a platform producer — the internal split among them is an implementation detail. Consumers key on `(source, event_type)` to tell app facts from platform facts; filter with `?source=app` / `?source=platform` on both feed GETs."
        },
        "occurred_at": {
          "type": "string",
          "format": "date-time"
        },
        "payload": {
          "type": "object",
          "description": "Compact fact: resource ids + verdict fields (never bodies or secret material). Oversize payloads carry `payload_truncated: true` + `dropped_keys[]`; the referenced domain resources hold full detail."
        },
        "next_actions": {
          "type": "array",
          "description": "Platform-synthesized drill-downs for this event — the highest-probability next call, identical across HTTP/SDK/CLI/MCP.",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "method": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "command": {
                "type": "string"
              },
              "why": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}