Contexts and lineage

A service is one logical thing. Its production deployment and staging deployment are not. VegaGraph represents that without copying the whole service page for every environment.

Context lens

A context is a named hierarchical lens such as:

prod
└── aws
    └── us-east-1
        └── eks/main
            └── payments

It also has structured dimensions:

{
  "stage": "prod",
  "cloud": "aws",
  "region": "us-east-1",
  "account": "123456789012",
  "platform": "eks",
  "cluster": "main",
  "namespace": "payments"
}

An aspect or edge with no context_id is canonical. A context read includes canonical facts, selected-context facts and facts from parent contexts; the nearest aspect version wins.

Origins returned by the API

Origin	Meaning
`canonical`	`context_id` is null and the fact applies everywhere.
`direct`	The fact belongs to the selected context.
`inherited`	The fact belongs to a parent of the selected context.
`context_specific`	The fact has a context but the request did not choose a lens.

Clients should show this origin. Hiding it makes inherited configuration look like a direct production assertion.

Logical entity and runtime instance

Keep stable meaning on a canonical entity and runtime placement on a context-specific entity.

canonical service
  fqn: service/payments-api
  context: null

production deployment
  fqn: deployment/payments-api/prod/aws/us-east-1/eks/main/payments
  context: prod/aws/us-east-1/eks/main/payments
  canonical_entity_id: service/payments-api

An instance_of edge can also connect the deployment to the service. Ownership, API contracts and documentation stay on the canonical service. The environment selector adds the deployments, image tags, endpoints, workloads, incidents and data paths visible in that lens.

Boundary rules

A canonical edge can only connect canonical endpoint entities and canonical field refs.
A context-specific edge can connect canonical endpoints or endpoints in that same context.
It cannot connect a production field ref to a staging entity.
Entity identity is not the context alone; runtime FQNs include enough source placement to remain workspace-unique.

These rules stop environments from blending into a graph that looks connected but is operationally false.

Traverse

GET .../entities/{entity_id}/traverse?direction=outbound&max_depth=3&context_id={context_id}

Traversal is bounded by depth and service limits. Filter by relationship type when the question is specific. “Everything within five hops” on a large catalog is rarely useful and is expensive to explain.

Hierarchy and 360 views

Hierarchy path and children endpoints use structural contains semantics. Entity 360 combines the entity, current aspects, relationships, fields and context summaries needed for a detail page. Friendly projections add common questions:

/kpis/{id}/lineage and /kpis/{id}/impact
/services/{id}/dependencies and /services/{id}/runtime
/tables/{id}/columns and /tables/{id}/path
/repositories/{id}/services
/environments/{id}/runtime