Lineage and blast radius
Lineage answers two questions before anyone acts: what feeds this object, and what breaks if it changes. One graph covers sources, datasets, saved queries, dashboard widgets, alert rules, destinations, exports, joins, rollups and pipeline rules. It is read three ways, and all three read the same code:
| Door | What it is |
|---|---|
egress_map_get with include: ["lineage"] |
an agent's read (adds about 1,200 tokens) |
GET /orgs/{orgSlug}/lineage |
the dashboard's panel on the egress map card |
| the approval cards of destinations, pipelines, sources and saved queries | the dependents, listed before the act |
The graph
An edge runs from the upstream object to the downstream one, the way data flows: from feeds to.
dataset:spans -> saved_query:Q with relation reads says Q reads spans.
| Relation | Means | Declared by (the to end unless noted) |
|---|---|---|
reads |
reads a dataset, a join or a saved query | saved queries, widgets, exports |
alerts_on |
watches a dataset | alert rules (telemetry conditions) |
joins |
a typed join's two sides | joins |
exports_to |
what a destination sends | destinations |
feeds |
feeds something (declaring object is the from end) |
sources, pipeline rules |
writes |
writes into something (declaring object is the from end) |
exports, into their destination |
fieldPath names the field an edge is about (http.user_agent) and is empty for an edge between
whole objects. Every spec spells a field its own way in text, so one function
(canonicalFieldPath) is the only place a field path is normalised.
Every edge is declared by one object, from that object's own spec. Nothing is inferred by a model, and nothing is guessed from a log. The declaring object is always one named end of the edge, which is what lets a rewrite replace exactly the edges an object declared and nothing another object declared: a destination's rewrite never touches the edge an export declared into it. A declarer that returns an edge it does not own is refused.
Keeping it current
Each owner registers a declarer (registerLineageDeclarer(kind, fn); the built-in ones are in
lineage-declarers.ts) and calls rewriteLineageFor(tx, { orgId, kind, id }) in the same
transaction as its own write, and removeLineageFor when it deletes. rebuildLineage(db, orgId)
runs every declarer over every object of an organization: the backfill, and the repair for an owner
that does not call the seam yet. It is idempotent and removes edges whose declaring object is gone.
Saved queries (the change apply and the delete) and sources (the change apply) call the seam today.
The alert-rule, widget, destination, export, join and pipeline-rule writers are wired by the wiring
package; until each is, its edges are as fresh as the last rebuildLineage. An object that no longer
exists is dropped from every read whatever its edges say.
Reading it
lineageFor(principal, { orgId, kind, id, fieldPath?, direction, depth }) walks up, down or both,
at most three hops, breadth first, with a visited set (so a cycle terminates) and a cap on objects.
It returns the objects with their state, owner and last run, the edges, and what it could not show.
Asking about a field (fieldPath: "http.user_agent" on dataset:spans) narrows the first hop to the
edges that name the field plus the edges that read the whole dataset. The second kind are marked
match: "whole_object": they may read the field without naming it, so they are listed apart rather
than claimed as readers.
What a caller sees is narrowed to their own reach:
- every query carries the organization, and every object is looked up with it, so another organization's id names nothing;
- an edge declared by a project the caller cannot read is not followed; an org-level object needs
org:read; - another person's draft saved query or private board is counted in
hiddenPrivateand never named, and the walk stops there; - a deleted, archived or tombstoned object disappears with its edges.
Object names and owner names are text a member or an agent wrote. Every door lists them as untrusted;
the MCP tool scrubs and bounds them under an F-16 class (service_name).
Dependents on a card
dependentsFor(db, { orgId, projectId, kind, id }) is what every approval card calls. It lists what
sits downstream within three hops and what writes into the object directly (an export names its
destination), with owners, states and last runs. A card reader is not authorized per project, so the
object's own project and org-level objects are named and the rest are counted (hiddenScope).
status is not_available only when no declarer is registered at all. Otherwise zero is zero, and
coverage.undeclared names any kind with no declarer, so a dependent that is missing is never read
as one that is absent.
The destination card, the pipeline preview and the source card carry the block today. The export family's card carries it when P3-175 lands.