docs(adr): 0005-lineage-acyclicity — enforce DAG at write time#93
Merged
Conversation
Closes #65. The README and `LineageEdge` doc both claim "DAG". Until #42 closed single-hop self-loops at the storage layer, nothing enforced that claim. After #42, multi-hop cycles (A → B → A, …) still slip through. Lineage is write-only today, so the cost of a cycle is invisible — but every documented traversal (V-L1-D2 lineage queries, impact-analysis, transitive provenance) needs acyclicity for soundness. ADR-0005 picks **enforce-at-write-time**: * Refuse inserts where `(source, target)` would close a cycle. * Implementation uses recursive CTEs (works on SQLite 3.8.3+ and Postgres) emitted at codegen time, so the cost stays in SQL. * Concurrent inserts serialise on the cycle check (same V-L2-L1 per-entity pattern). * Storage-layer single-hop CHECK (#42) remains as the last line of defence. Alternatives considered & rejected: - Rename to "Lineage Graph" and ship cycles. Rejected: every documented use of lineage needs acyclicity for soundness; write cost is small, read cost across every future consumer is not. - SQL triggers only. Rejected: triggers vary across backends; application-layer enforcement returns a structured error type carrying the cycle path. The implementation lands in V-L1-G2 (to be filed). This ADR is binding for that follow-up. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Per V-L1-G1: README claims "DAG" but multi-hop cycles still slip through after #42 (which only blocks self-loops). Pick enforce-at-write-time:
(source, target)would close a cycle (recursive CTE reachability check).Alternatives rejected: rename to "Lineage Graph" (every consumer would have to defend against cycles forever), SQL triggers only (varies across backends).
Implementation lands in V-L1-G2 (to be filed). This ADR is binding for that follow-up.
Closes
Test plan
docs/decisions/0005-lineage-acyclicity.adocwith full ADR structureDoc-only; no code or DDL changes. The README's existing "DAG" claim is now backed by a binding decision, not aspirational language.