orbitrecord

type Call struct {
	// Action is the canonical action ID whose handler made the call.
	Action string `json:"action"`
	// Variant tells two calls of one action apart: the response format it
	// asked for, what else it asked (an expanded node), or "default" for a
	// route that takes no parameter and so has one answer.
	Variant string `json:"variant"`
	// Output is the Go type the handler returned, repository relative
	// (internal/tools/orbit.StatusOutput). It is what the audit judges
	// against the keys below.
	Output string `json:"output"`
	// RetrievedAt is the day the call was answered when it is not the
	// record's own: a call carried from an earlier recording because GitLab
	// refused the account on the day of this one, while the request the
	// handler builds was still the one that recording made. Empty for a call
	// made on [Source.RetrievedAt].
	RetrievedAt string   `json:"retrieved_at,omitempty"`
	Request     Request  `json:"request"`
	Response    Response `json:"response"`
}

type CallID struct {
	Action  string
	Variant string
}

type Document struct {
	SchemaVersion int    `json:"schema_version"`
	Note          string `json:"note"`
	Source        Source `json:"source"`
	// Calls are the recorded calls, sorted by action and variant.
	Calls []Call `json:"calls"`
	// Unrecorded are the expected calls the recording could not make and had
	// no earlier answer to carry for, each with the reason, sorted by action
	// and variant. A recording leaves a call here only when it was told GitLab
	// might refuse the account (gen_orbit_record -allow-unanswered) and GitLab
	// refused it or answered it with null.
	Unrecorded []Unrecorded `json:"unrecorded,omitempty"`
}

type Key struct {
	Path  string   `json:"path"`
	Kinds []string `json:"kinds"`
	// Verbatim marks a subtree recorded as its root only, because its keys
	// are data rather than a response shape. Nothing below it is recorded.
	Verbatim bool `json:"verbatim,omitempty"`
}

type Request struct {
	Method string `json:"method"`
	// Path is the route below /api/v4, or [GraphQLPath].
	Path string `json:"path"`
	// Query are the query parameter names the handler sent, sorted.
	Query []string `json:"query,omitempty"`
	// Body are the top-level names of the JSON body the handler sent, sorted.
	Body []string `json:"body,omitempty"`
	// Operation is what the request asked of an endpoint that serves more than
	// one thing at one route: a GraphQL document's type and name ("query
	// OrbitServiceStatus"), or an MCP request's method and the tool it calls
	// ("tools/call list_commands"). Empty for a REST route.
	Operation string `json:"operation,omitempty"`
	// Arguments are the names of what the operation was asked with, sorted:
	// a GraphQL document's variables, or the MCP tool's arguments.
	Arguments []string `json:"arguments,omitempty"`
}

type Response struct {
	Status int `json:"status"`
	// ContentType is the media type without its parameters.
	ContentType string `json:"content_type"`
	// Root is where in the body the key tree is taken from: a path below a
	// GraphQL answer's data ("data.orbit.serviceStatus"), whose connections are
	// recorded as the lists they page, the JSON-RPC result of an MCP answer
	// ("result"), or the text of an MCP tool result ("result.content[].text"),
	// decoded when it is JSON. Empty for the whole body, which is a REST
	// route's.
	Root string `json:"root,omitempty"`
	// RootContentType is the media type of what the root holds when it is not
	// the whole body: application/json, or text/plain for an MCP tool's text
	// that is not JSON.
	RootContentType string `json:"root_content_type,omitempty"`
	// Keys is every path the body carried, sorted, the body itself first.
	Keys []Key `json:"keys"`
}

type Source struct {
	// Instance is the GitLab the calls were made against.
	Instance string `json:"instance"`
	// OrbitVersion is the Knowledge Graph service version GitLab.com
	// reported in the status call, which is what moves between two
	// recordings far more often than GitLab's own release does.
	OrbitVersion string `json:"orbit_version"`
	// QueryGrammar names the query language GitLab.com published beside the
	// answers (orbit.dsl, raw): the description of the query_graph command,
	// which is the GQL grammar, and the JSON Schema of its input, as
	// [GrammarStamp] writes them. GQL carries no version of its own the way
	// the JSON DSL's $id and version field did, so the stamp is a digest of
	// what GitLab says the language is, which moves whenever GitLab says it
	// differently. It is the drift alarm issue 1031 asked for: [Diff] reports
	// it changing, so a recording fails until somebody has read orbit.query's
	// guidance against the new language and committed the record.
	QueryGrammar string `json:"query_grammar"`
	// Namespace is the fixture namespace the indexing status and the query
	// were asked about (test/fixtures/orbit, docs/development/orbit-fixtures.md).
	Namespace string `json:"namespace"`
	// RetrievedAt is the day of the recording, YYYY-MM-DD.
	RetrievedAt string `json:"retrieved_at"`
}

type Unrecorded struct {
	Action  string `json:"action"`
	Variant string `json:"variant"`
	// Reason is what GitLab answered and when, in the words a reader needs to
	// tell whether a new recording can make the call.
	Reason string `json:"reason"`
}