Functional specification

Users and jobs

PersonaJob
Analytics engineer"I want to rename customers.email. Which models break?"
Data platform ownerGate pull requests that break consumers (--fail-on, --fail-on-breaking)
Data stewardCheck contracts and see which columns look sensitive by name
Security / privacy reviewerConfirm the tool is offline and never reads rows (audit)
AI-coding-agent userGive Claude Code, Cursor, Codex, Copilot or Gemini CLI a safe, evidence-bound lineage skill

Capabilities

IDCapabilityInputOutput
F1Scanfolder of .sqlsealed graph: datasets, edges (direct/derived/indirect), warnings
F2dbt importmanifest.jsondataset graph from depends_on (metadata only)
F3Impactgraph, table, optional column, change typeconfirmed, possible, proof paths, checklist, test ideas
F4Upstreamgraph, table, columnsources and origins
F5Comparetwo graphsadded/removed edges, column changes, breaking consumers
F6Contractgraph, contract JSONfindings; freshness/owner not-run
F7Verifyany reportseal valid or not
F8Auditoptional SQL folderMD + HTML + JSON audit
F9Skills installhost, projectproject-local SKILL.md copies
F10MCP / HTTPfolder or reportread-only tools / JSON

Edge semantics

Acceptance behaviours

  1. Renaming customers.email in the sample shows three confirmed consumers, one at two hops.
  2. An ambiguous unqualified column over two joined tables yields a warning, not an edge.
  3. A column used only in a WHERE clause is possible, never confirmed.
  4. Text inside comments and strings never creates lineage.
  5. scan of unchanged files produces an identical seal regardless of file order.
  6. Editing any byte of a report makes verify fail.
  7. Unknown table in impact returns TARGET_NOT_FOUND, not an empty success.
  8. Gates: exit 3 when --fail-on, --strict or --fail-on-breaking trips.

Non-goals

Executing SQL, connecting to databases, modifying SQL or migrations, measuring freshness, classifying PII, certifying any dialect, replacing tests or review.