Define durable value handles and value-selector resolution #10

New issue

Closed

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

JayKobe6k commented

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

Owner

Problem

A C declaration name is not enough to identify a value. Static symbols can repeat across translation units, local names can be shadowed, and one declaration can receive multiple semantic value definitions through assignments and control-flow merges. Existing IR IDs are explicitly index-local and cannot be exposed as durable CLI identifiers.

Goal

Define an unambiguous, revision-aware ValueHandle and a user-facing value selector that can seed lineage queries and be returned by search.

Identity inputs

Evaluate and document the required combination of:

index and revision identity;
translation-unit portable path;
enclosing function and record scope chain;
libclang USR/canonical symbol key where available;
declaration name and source anchor;
semantic definition/use role and occurrence anchor or ordinal.

The canonical machine handle must round-trip losslessly. A readable selector may omit components only when resolution is unique. Ambiguous selectors must return typed candidates rather than silently selecting one value.

Acceptance criteria

Distinguish symbols, declarations, value definitions, and value uses in all public types and documentation.
Handles are serializable in JSON, displayable in text, parseable by query lineage, and revision-aware.
Tests cover globals, TU-local statics, same-named functions, shadowed locals, struct fields, parameters, initial definitions, later assignments, merges, macro spelling/expansion anchors, and stale revisions.
Search hits include canonical handles that require no fuzzy re-resolution.
Selector resolution is an application/core service with a typed repository port, not CLI or raw Cypher logic.

Dependencies

Depends on #2 and #4; source facts from #7 inform the final handle shape.

## Problem A C declaration name is not enough to identify a value. Static symbols can repeat across translation units, local names can be shadowed, and one declaration can receive multiple semantic value definitions through assignments and control-flow merges. Existing IR IDs are explicitly index-local and cannot be exposed as durable CLI identifiers. ## Goal Define an unambiguous, revision-aware `ValueHandle` and a user-facing value selector that can seed lineage queries and be returned by search. ## Identity inputs Evaluate and document the required combination of: - index and revision identity; - translation-unit portable path; - enclosing function and record scope chain; - libclang USR/canonical symbol key where available; - declaration name and source anchor; - semantic definition/use role and occurrence anchor or ordinal. The canonical machine handle must round-trip losslessly. A readable selector may omit components only when resolution is unique. Ambiguous selectors must return typed candidates rather than silently selecting one value. ## Acceptance criteria - Distinguish symbols, declarations, value definitions, and value uses in all public types and documentation. - Handles are serializable in JSON, displayable in text, parseable by `query lineage`, and revision-aware. - Tests cover globals, TU-local statics, same-named functions, shadowed locals, struct fields, parameters, initial definitions, later assignments, merges, macro spelling/expansion anchors, and stale revisions. - Search hits include canonical handles that require no fuzzy re-resolution. - Selector resolution is an application/core service with a typed repository port, not CLI or raw Cypher logic. ## Dependencies Depends on #2 and #4; source facts from #7 inform the final handle shape.

JayKobe6k added this to the CLI + Core MVP milestone

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

JayKobe6k added the

type/foundation

area/core

area/query

labels

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

JayKobe6k referenced this issue

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

Analyze and persist producer-to-consumer value lineage #11

JayKobe6k referenced this issue