docs consolidation

docs/api/graph/overlay-schema.md

@@ -1,42 +1,82 @@
-# Graph Overlay & Cache Schema (draft placeholder)
+# Graph overlay and tile cache schema (draft)
 
-**Status:** Draft v0.2 · owner-proposed
+## Overview
 
-## 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.
+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": "2025-12-06",
+  "version": "0.2",
   "tenantId": "tenant-default",
   "tile": {
-    "id": "graph-tile::asset::<hash>::z8/x12/y5",
+    "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": "", "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 } ],
+  "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": "", "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" } ]
+    "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 }
 }
 ```
 
-## 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`.
+## Determinism rules
 
-## Samples
-- `docs/api/graph/samples/overlay-sample.json`
+- 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.
 
-## Outstanding
-- Confirm max sizes, allowed edge types, and etag hashing rule.
-- Provide validation error example and rate-limit headers for gateway responses.
+## Constraints (draft)
+
+- Max nodes per tile: 2,000
+- Max edges per tile: 4,000
+- Zoom range: 0-12