# Graph overlay and tile cache schema (draft)

## Overview

This document describes the cached/materialized tile representation used by gateway/UI components to store graph tiles alongside overlay data.

This cache schema is separate from the streaming NDJSON tile protocol:
- Streaming API contract: `docs/api/graph-gateway-spec-draft.yaml`
- Sample cached tile: `docs/api/graph/samples/overlay-sample.json`

## Cached tile shape

A cached tile document is a single JSON object with:
- `version`: cache schema version (string; bump only for breaking changes)
- `tenantId`: tenant partition for the cache entry
- `tile`: tile identity + spatial key (`id`, `bbox`, `zoom`) and cache validator (`etag`)
- `nodes`: node records
- `edges`: edge records
- `overlays`: overlay arrays keyed by overlay kind
- `telemetry`: generation/caching metadata

## Schema (draft)

```jsonc
{
  "version": "0.2",
  "tenantId": "tenant-default",
  "tile": {
    "id": "graph-tile::<scope>::<hash>::z8/x12/y5",
    "bbox": { "minX": -122.41, "minY": 37.77, "maxX": -122.38, "maxY": 37.79 },
    "zoom": 8,
    "etag": "c0ffee-etag"
  },
  "nodes": [
    {
      "id": "asset:...",
      "kind": "asset|component|vuln",
      "label": "optional display label",
      "severity": "critical|high|medium|low|info",
      "reachability": "reachable|unreachable|unknown",
      "attributes": {}
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "nodeId",
      "target": "nodeId",
      "type": "depends_on|contains|evidence",
      "weight": 0.0,
      "attributes": {}
    }
  ],
  "overlays": {
    "policy": [
      { "nodeId": "nodeId", "badge": "pass|warn|fail|waived", "policyId": "policy://...", "verdictAt": "2025-01-02T03:04:05Z" }
    ],
    "vex": [
      { "nodeId": "nodeId", "state": "not_affected|fixed|under_investigation|affected", "statementId": "vex:...", "lastUpdated": "2025-01-02T03:04:05Z" }
    ],
    "aoc": [
      { "nodeId": "nodeId", "status": "pass|fail|warn", "lastVerified": "2025-01-02T03:04:05Z" }
    ]
  },
  "telemetry": { "generationMs": 0, "cache": "hit|miss", "samples": 0 }
}
```

## Determinism rules

- Arrays are pre-sorted:
  - `nodes` by `id`
  - `edges` by `id`
  - overlay arrays by `nodeId` then secondary key (`policyId`, `statementId`, etc.)
- Timestamps are ISO-8601 UTC.
- Hashes are lower-case hex.

## Constraints (draft)

- Max nodes per tile: 2,000
- Max edges per tile: 4,000
- Zoom range: 0-12