Loading
docs(adr): add ADR 021 for entity context expansion in the context endpoint
Note
Click here to see the rendered version
What does this MR do and why?
Adds ADR 021 for the Orbit context endpoint. It limits context to one token per request. With expand it runs at most one Orbit query, so one request is at most one billed query. Several tokens wait until billing can count them as one. What the expansion queries contain stays with the Orbit team.
Related Issues
Related to #1262
Testing
Docs only. I ran markdownlint, Vale, and the prose and secrets hooks on the file. mise lint:links reports one error in .gitlab/.argo/mr_template_doc_ai.md, which this MR doesn't touch.
Performance Analysis
- This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context: long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered
- One new file:
docs/design-documents/decisions/021_entity_context_expansion.md. It was 019 untilmaintook that number for the GQL response format ADR. Mechanics (fields, leak rules) sit in collapsed blocks inside the ADR. tokensstays an array for forward compatibility but must hold exactly one string. Eachentities[]entry carries its ownexpansion(null,result, orerror), so lifting the limit later is additive.- Transport: the expansion is one ordinary named query, so the contract is transport-independent.
expandruns on the Rails path behindorbit_query_in_rails(#1381), with no Workhorse merge logic. While the flag is off,expandreturns anexpansion_unavailableerror and the summaries still succeed. If #1381 slips, the fallback is a single-stream Workhorse merge. - Billing: GKG emits one event per
ExecuteQueryand has no grouping field, andcorrelation_idis logging-only per ADR 007. The ADR records the team's preference for multi-token requests (N sub-queries billed as one, for example via a sharedbillable_request_id) as deferred work that needs billing-owner sign-off. - Rejected or deferred: N tokens billed as one, a single cross-type query (not possible today), Workhorse fan-out, Rails execution for several tokens (changes where redaction and merge run, not the query count), GKG batch multiplexing, client-side two-call composition.
- Authorization-safe pagination is tracked in a confidential issue and doesn't block this ADR. The fix must keep
truncated.
Edited by Dmitry Gruzd