# Graph Overlay & Cache Schema (draft placeholder)

**Status:** Draft v0.2 · owner-proposed

## Scope
- Overlay/cache schema for graph tiles used by Web gateway and UI overlays.
- Validation rules for bbox/zoom/path; pagination tokens; deterministic ordering.
- Error codes and sampling/telemetry fields.

## Schema (draft)
```jsonc
{
  "version": "2025-12-06",
  "tenantId": "tenant-default",
  "tile": {
    "id": "graph-tile::asset::<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": "", "severity": "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 } ],
  "overlays": {
    "policy": [ { "nodeId": "nodeId", "badge": "pass|warn|fail|waived", "policyId": "", "verdictAt": "2025-12-05T09:00:00Z" } ],
    "vex": [ { "nodeId": "nodeId", "state": "not_affected|fixed|under_investigation|affected", "statementId": "", "lastUpdated": "2025-12-05T09:10:00Z" } ],
    "aoc": [ { "nodeId": "nodeId", "status": "pass|fail|warn", "lastVerified": "2025-12-05T10:11:12Z" } ]
  },
  "telemetry": { "generationMs": 0, "cache": "hit|miss", "samples": 0 }
}
```

## Constraints (proposal)
- Max nodes per tile: 2,000; max edges: 4,000.
- Zoom range: 0–12; tiles must include bbox and etag.
- Arrays must be pre-sorted: nodes by `id`, edges by `id`, overlays by `nodeId` then `policyId|statementId`.

## Samples
- `docs/api/graph/samples/overlay-sample.json`

## Outstanding
- Confirm max sizes, allowed edge types, and etag hashing rule.
- Provide validation error example and rate-limit headers for gateway responses.