stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
4c55b01222046e2138a2d00f18f28a6e59d3acd5
git.stella-ops.org/docs/modules/graph/prep/2025-11-24-graph-api-schema-review.md
StellaOps Bot 7c39058386
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
Symbols Server CI / symbols-smoke (push) Has been cancelled
Details
devportal-offline / build-offline (push) Has been cancelled
Details
up
2025-11-24 20:57:49 +02:00

1.6 KiB
Raw Blame History

Graph API schema review notes (planned)

Date: 2025-11-24 (target) Scope: Review OpenAPI/JSON schema for search/query/paths/diff/export, tiles, budgets, and overlays alignment (GRAPH-API-28-001).

Attendees

  • Graph API Guild: TBD
  • Policy Engine Guild: TBD
  • QA Guild (observer): TBD

Pre-reads

  • docs/api/graph-gateway-spec-draft.yaml
  • docs/modules/graph/prep/2025-11-22-graph-api-schema-outline.md
  • Policy overlay contract references: POLICY-ENGINE-30-001..003

Agenda

  • Validate tile envelope shape and budget semantics.
  • Confirm overlay payload fields and versioning handshake with Policy Engine.
  • Decide DSL vs structured filter scope for /graph/query v1.
  • Agree on export manifest shape and size caps for PNG/SVG.

Decisions

  • Tile envelope shape frozen for draft v0.0.3-pre: node|edge|stats|cursor|diagnostic, seq, optional cost, overlays keyed by overlay kind with {kind, version, data}.
  • Resume support will rely on cursor tokens; requests accept optional cursor field for search/query/diff to resume streams.
  • Path responses carry pathHop on node/edge tiles; depth capped at 6 as per sprint scope.
  • Rate-limit/budget headers documented (X-RateLimit-Remaining, Retry-After), with 429 response carrying error envelope.

Open items / follow-ups

  • Overlay payload contract (fields for policy/vex/advisory) to be versioned once POLICY-ENGINE-30-001..003 freeze; placeholder schema retained.
  • Export render limits (PNG/SVG size caps) still pending Observability/UX sign-off.

Outcomes snapshot

  • Draft spec updated at docs/api/graph-gateway-spec-draft.yaml (v0.0.3-pre) and referenced in sprint Execution Log.