Implement bounded upstream/downstream lineage queries #12

New issue

Closed

opened 2026-09-03 14:22:18 +00:00 by JayKobe6k · 0 comments

JayKobe6k commented

2026-09-03 14:22:18 +00:00

Owner

Goal

Resolve one value and return a bounded, cycle-safe lineage subgraph in either or both directions.

Command contract

claritree query --index <index-selector> lineage <value-selector> \
  [--max-upstream-depth <n>] [--max-downstream-depth <n>]

Upstream follows incoming lineage toward definitions that produced or contributed to the selected value.
Downstream follows outgoing lineage toward uses, consumers, and derived definitions.
Depth 0 includes only the selected value; each traversed lineage relationship increments depth by one.
Define safe defaults and explicit maximum limits to prevent accidental unbounded graph expansion.

Result contract

Return a typed subgraph containing the selected value, typed definition/use nodes, explicit directed edges, depth/direction metadata, certainty, source anchors, and truncation information. Text output should be readable without discarding identity; JSON output must be stable and lossless. Cycles and shared descendants must be represented once rather than recursively duplicating output.

Acceptance criteria

Resolve canonical handles and readable unique selectors; ambiguity returns candidate handles.
Either depth flag may be used independently or together.
Invalid/negative/excessive depths fail with actionable errors.
Traversal is deterministic, cycle-safe, revision-scoped, and tested independently of LadybugDB.
LadybugDB query mapping tests prove direction and boundary behavior.
CLI tests cover text/JSON, not found, ambiguous selector, truncation, upstream-only, downstream-only, and bidirectional results.
The CLI never accepts Cypher and never queries LadybugDB directly.

Dependencies

Depends on #3, #4, #10, and #11.

## Goal Resolve one value and return a bounded, cycle-safe lineage subgraph in either or both directions. ## Command contract ```text claritree query --index <index-selector> lineage <value-selector> \ [--max-upstream-depth <n>] [--max-downstream-depth <n>] ``` - **Upstream** follows incoming lineage toward definitions that produced or contributed to the selected value. - **Downstream** follows outgoing lineage toward uses, consumers, and derived definitions. - Depth `0` includes only the selected value; each traversed lineage relationship increments depth by one. - Define safe defaults and explicit maximum limits to prevent accidental unbounded graph expansion. ## Result contract Return a typed subgraph containing the selected value, typed definition/use nodes, explicit directed edges, depth/direction metadata, certainty, source anchors, and truncation information. Text output should be readable without discarding identity; JSON output must be stable and lossless. Cycles and shared descendants must be represented once rather than recursively duplicating output. ## Acceptance criteria - Resolve canonical handles and readable unique selectors; ambiguity returns candidate handles. - Either depth flag may be used independently or together. - Invalid/negative/excessive depths fail with actionable errors. - Traversal is deterministic, cycle-safe, revision-scoped, and tested independently of LadybugDB. - LadybugDB query mapping tests prove direction and boundary behavior. - CLI tests cover text/JSON, not found, ambiguous selector, truncation, upstream-only, downstream-only, and bidirectional results. - The CLI never accepts Cypher and never queries LadybugDB directly. ## Dependencies Depends on #3, #4, #10, and #11.

JayKobe6k added this to the CLI + Core MVP milestone

2026-09-03 14:22:18 +00:00

JayKobe6k added the

labels

2026-09-03 14:22:18 +00:00

JayKobe6k referenced this issue

2026-09-03 14:22:18 +00:00

Add end-to-end CLI workflows and user documentation #18