feat: materialize ccg:// annotation refs into cross_refs

Add a cross_refs table (migration 000015, SQLite and PostgreSQL) that
stores every @see ccg://{namespace}/{path}#{symbol} annotation tag as a
queryable row with a symbolic target plus derived resolution state
(resolved_node_id, status resolved|dead, source annotation).

A new crossref.Service syncs the table after every ingest commit:
outbound rows are rebuilt from the namespace's current doc tags and
inbound rows are re-resolved because replace-style builds regenerate
node ids. The sync hook is optional on workflow.Service and wired in
CLI build/update, the MCP build tool, and the webhook server runtime.

Resolution reuses the matcher shared with lint (ccgRefNodeExists) so
dead-ref findings and cross_refs status never disagree. Namespace-scope
refs resolve without a node target; path-scope refs prefer the file
node; malformed refs are skipped (lint owns reporting).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tae2089

internal/adapters/inbound/cli/build.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/tae2089/trace"
 
+	"github.com/tae2089/code-context-graph/internal/app/crossref"
 	"github.com/tae2089/code-context-graph/internal/app/ingest"
 	"github.com/tae2089/code-context-graph/internal/app/ingest/workflow"
 	requestctx "github.com/tae2089/code-context-graph/internal/ctx"
@@ -47,6 +48,9 @@ func newBuildCmd(deps *Deps) *cobra.Command {
 				Walkers:    deps.Walkers,
 				Logger:     deps.Logger,
 			}
+			if crossRefStore, ok := deps.Store.(crossref.Store); ok {
+				svc.CrossRefs = crossref.New(crossRefStore)
+			}
 
 			opts := workflow.BuildOptions{
 				Dir:                 dir,

internal/adapters/inbound/cli/update.go

@@ -6,6 +6,7 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/tae2089/trace"
 
+	"github.com/tae2089/code-context-graph/internal/app/crossref"
 	"github.com/tae2089/code-context-graph/internal/app/ingest"
 	"github.com/tae2089/code-context-graph/internal/app/ingest/workflow"
 	requestctx "github.com/tae2089/code-context-graph/internal/ctx"
@@ -50,6 +51,9 @@ func newUpdateCmd(deps *Deps) *cobra.Command {
 				Walkers:    deps.Walkers,
 				Logger:     deps.Logger,
 			}
+			if crossRefStore, ok := deps.Store.(crossref.Store); ok {
+				svc.CrossRefs = crossref.New(crossRefStore)
+			}
 			stats, err := svc.Update(ctx, workflow.UpdateOptions{
 				BuildOptions: workflow.BuildOptions{
 					Dir:                 dir,

internal/adapters/inbound/mcp/handler_parse.go

@@ -11,6 +11,7 @@ import (
 	"github.com/tae2089/trace"
 
 	flowspkg "github.com/tae2089/code-context-graph/internal/app/analyze/flow"
+	"github.com/tae2089/code-context-graph/internal/app/crossref"
 	"github.com/tae2089/code-context-graph/internal/app/ingest"
 	"github.com/tae2089/code-context-graph/internal/app/ingest/workflow"
 	"github.com/tae2089/code-context-graph/internal/obs"
@@ -72,14 +73,18 @@ func (h *handlers) graphService() *workflow.Service {
 		graphStore = candidate
 	}
 	parseCache, _ := h.deps.Build.Store.(ingest.ParseCache)
-	return &workflow.Service{
+	svc := &workflow.Service{
 		Store:      graphStore,
 		UnitOfWork: h.deps.Build.UnitOfWork,
 		Search:     h.deps.Build.Search,
 		ParseCache: parseCache,
 		Parsers:    walkers,
 		Logger:     h.logger(),
 	}
+	if crossRefStore, ok := h.deps.Build.Store.(crossref.Store); ok {
+		svc.CrossRefs = crossref.New(crossRefStore)
+	}
+	return svc
 }
 
 // parseProject parses a project directory and stores discovered graph elements.

internal/adapters/outbound/graphgorm/crossref.go

@@ -0,0 +1,120 @@
+// @index GORM adapter for materialized cross-namespace reference rows and ccg ref resolution.
+package graphgorm
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	"github.com/tae2089/trace"
+
+	crossrefapp "github.com/tae2089/code-context-graph/internal/app/crossref"
+	"github.com/tae2089/code-context-graph/internal/domain/graph"
+	"github.com/tae2089/code-context-graph/internal/domain/reference"
+)
+
+var _ crossrefapp.Store = (*Store)(nil)
+
+// ListAnnotationCCGRefs returns every @see ccg:// tag value declared by nodes of one namespace.
+// @intent collect the source facts for rebuilding a namespace's outbound cross refs.
+func (s *Store) ListAnnotationCCGRefs(ctx context.Context, namespace string) ([]crossrefapp.AnnotationRef, error) {
+	var rows []crossrefapp.AnnotationRef
+	err := s.db.WithContext(ctx).Model(&graph.DocTag{}).
+		Select("annotations.node_id AS node_id, doc_tags.value AS value").
+		Joins("JOIN annotations ON annotations.id = doc_tags.annotation_id").
+		Joins("JOIN nodes ON nodes.id = annotations.node_id").
+		Where("doc_tags.kind = ?", graph.TagSee).
+		Where("doc_tags.value LIKE ?", reference.Scheme+"://%").
+		Where("nodes.namespace = ?", namespace).
+		Scan(&rows).Error
+	if err != nil {
+		return nil, trace.Wrap(err, "list annotation ccg refs")
+	}
+	return rows, nil
+}
+
+// ResolveCCGRef resolves a parsed ccg:// reference to a target node id.
+// @intent give cross-ref materialization the concrete node identity behind a symbolic reference.
+// @domainRule namespace-scope refs resolve with a zero node id when the namespace has any nodes.
+// @domainRule path-scope refs prefer the file node of the path; remaining ties resolve to the lowest node id.
+func (s *Store) ResolveCCGRef(ctx context.Context, ref reference.Ref) (uint, bool, error) {
+	if ref.Path == "" && ref.Symbol == "" {
+		var count int64
+		if err := s.db.WithContext(ctx).Model(&graph.Node{}).Where("namespace = ?", ref.Namespace).Count(&count).Error; err != nil {
+			return 0, false, trace.Wrap(err, "resolve namespace-scope ccg ref")
+		}
+		return 0, count > 0, nil
+	}
+	var node graph.Node
+	err := s.ccgRefNodeQuery(ctx, ref).
+		Order("CASE WHEN kind = 'file' THEN 0 ELSE 1 END, id").
+		First(&node).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return 0, false, nil
+	}
+	if err != nil {
+		return 0, false, trace.Wrap(err, "resolve ccg ref")
+	}
+	return node.ID, true, nil
+}
+
+// ReplaceCrossRefsFrom atomically replaces every cross ref originating from one namespace.
+// @intent make outbound cross-ref state a pure function of the namespace's current annotations.
+// @sideEffect deletes and inserts cross_refs rows in one transaction.
+func (s *Store) ReplaceCrossRefsFrom(ctx context.Context, fromNamespace string, refs []graph.CrossRef) error {
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Where("from_namespace = ?", fromNamespace).Delete(&graph.CrossRef{}).Error; err != nil {
+			return err
+		}
+		if len(refs) == 0 {
+			return nil
+		}
+		return tx.CreateInBatches(refs, 100).Error
+	})
+	if err != nil {
+		return trace.Wrap(err, "replace cross refs")
+	}
+	return nil
+}
+
+// ListInboundCrossRefs returns refs from other namespaces that target the given namespace.
+// @intent select the rows whose resolution may change after this namespace rebuilds.
+// @domainRule self-namespace refs are excluded because the outbound rebuild already re-resolved them.
+func (s *Store) ListInboundCrossRefs(ctx context.Context, toNamespace string) ([]graph.CrossRef, error) {
+	var rows []graph.CrossRef
+	err := s.db.WithContext(ctx).
+		Where("to_namespace = ? AND from_namespace <> ?", toNamespace, toNamespace).
+		Order("id").
+		Find(&rows).Error
+	if err != nil {
+		return nil, trace.Wrap(err, "list inbound cross refs")
+	}
+	return rows, nil
+}
+
+// ListOutboundCrossRefs returns every cross ref originating from one namespace.
+// @intent expose a namespace's declared external dependencies for listing and analysis.
+func (s *Store) ListOutboundCrossRefs(ctx context.Context, fromNamespace string) ([]graph.CrossRef, error) {
+	var rows []graph.CrossRef
+	err := s.db.WithContext(ctx).
+		Where("from_namespace = ?", fromNamespace).
+		Order("id").
+		Find(&rows).Error
+	if err != nil {
+		return nil, trace.Wrap(err, "list outbound cross refs")
+	}
+	return rows, nil
+}
+
+// UpdateCrossRefResolution updates one row's derived resolution state.
+// @intent remap or invalidate a reference after its target namespace rebuilt.
+// @sideEffect updates resolved_node_id and status of one cross_refs row.
+func (s *Store) UpdateCrossRefResolution(ctx context.Context, id uint, resolvedNodeID *uint, status graph.CrossRefStatus) error {
+	err := s.db.WithContext(ctx).Model(&graph.CrossRef{}).Where("id = ?", id).
+		Updates(map[string]any{"resolved_node_id": resolvedNodeID, "status": status}).Error
+	if err != nil {
+		return trace.Wrap(err, "update cross ref resolution")
+	}
+	return nil
+}

internal/adapters/outbound/graphgorm/crossref_test.go

@@ -0,0 +1,167 @@
+package graphgorm
+
+import (
+	"context"
+	"testing"
+
+	requestctx "github.com/tae2089/code-context-graph/internal/ctx"
+	"github.com/tae2089/code-context-graph/internal/domain/graph"
+	"github.com/tae2089/code-context-graph/internal/domain/reference"
+)
+
+func seedCrossRefNodes(t *testing.T, s *Store, namespace string, nodes []graph.Node) map[string]uint {
+	t.Helper()
+	ctx := requestctx.WithNamespace(context.Background(), namespace)
+	if err := s.UpsertNodes(ctx, nodes); err != nil {
+		t.Fatalf("seed nodes for %s: %v", namespace, err)
+	}
+	stored, err := s.GetNodesByFiles(ctx, uniqueFilePaths(nodes))
+	if err != nil {
+		t.Fatalf("load seeded nodes: %v", err)
+	}
+	ids := map[string]uint{}
+	for _, byFile := range stored {
+		for _, n := range byFile {
+			ids[n.QualifiedName] = n.ID
+		}
+	}
+	return ids
+}
+
+func uniqueFilePaths(nodes []graph.Node) []string {
+	seen := map[string]bool{}
+	paths := []string{}
+	for _, n := range nodes {
+		if !seen[n.FilePath] {
+			seen[n.FilePath] = true
+			paths = append(paths, n.FilePath)
+		}
+	}
+	return paths
+}
+
+func TestResolveCCGRef_Scopes(t *testing.T) {
+	s := setupTestDB(t)
+	ids := seedCrossRefNodes(t, s, "auth-svc", []graph.Node{
+		{QualifiedName: "internal/auth/token.go", Kind: graph.NodeKindFile, Name: "token.go", FilePath: "internal/auth/token.go", StartLine: 1, EndLine: 1},
+		{QualifiedName: "auth.ValidateToken", Kind: graph.NodeKindFunction, Name: "ValidateToken", FilePath: "internal/auth/token.go", StartLine: 10, EndLine: 20},
+		{QualifiedName: "auth.RenewToken", Kind: graph.NodeKindFunction, Name: "RenewToken", FilePath: "internal/auth/token.go", StartLine: 30, EndLine: 40},
+	})
+	ctx := context.Background()
+
+	cases := []struct {
+		name   string
+		ref    reference.Ref
+		wantID uint
+		wantOK bool
+	}{
+		{"path and symbol", reference.Ref{Namespace: "auth-svc", Path: "internal/auth/token.go", Symbol: "ValidateToken"}, ids["auth.ValidateToken"], true},
+		{"path only prefers file node", reference.Ref{Namespace: "auth-svc", Path: "internal/auth/token.go"}, ids["internal/auth/token.go"], true},
+		{"symbol only", reference.Ref{Namespace: "auth-svc", Symbol: "RenewToken"}, ids["auth.RenewToken"], true},
+		{"namespace scope resolves without node", reference.Ref{Namespace: "auth-svc"}, 0, true},
+		{"missing symbol", reference.Ref{Namespace: "auth-svc", Symbol: "Nope"}, 0, false},
+		{"missing namespace", reference.Ref{Namespace: "ghost"}, 0, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			id, ok, err := s.ResolveCCGRef(ctx, tc.ref)
+			if err != nil {
+				t.Fatalf("ResolveCCGRef: %v", err)
+			}
+			if ok != tc.wantOK || id != tc.wantID {
+				t.Fatalf("ResolveCCGRef = (%d, %v), want (%d, %v)", id, ok, tc.wantID, tc.wantOK)
+			}
+		})
+	}
+}
+
+func TestReplaceCrossRefsFrom_ReplacesAndLists(t *testing.T) {
+	s := setupTestDB(t)
+	ctx := context.Background()
+	first := []graph.CrossRef{
+		{FromNamespace: "web", FromNodeID: 1, Raw: "ccg://auth-svc/#Old", ToNamespace: "auth-svc", ToSymbol: "Old", Status: graph.CrossRefStatusDead, Source: graph.CrossRefSourceAnnotation},
+	}
+	if err := s.ReplaceCrossRefsFrom(ctx, "web", first); err != nil {
+		t.Fatalf("first replace: %v", err)
+	}
+	second := []graph.CrossRef{
+		{FromNamespace: "web", FromNodeID: 2, Raw: "ccg://auth-svc/#New", ToNamespace: "auth-svc", ToSymbol: "New", Status: graph.CrossRefStatusResolved, Source: graph.CrossRefSourceAnnotation},
+		{FromNamespace: "web", FromNodeID: 3, Raw: "ccg://billing/#Charge", ToNamespace: "billing", ToSymbol: "Charge", Status: graph.CrossRefStatusDead, Source: graph.CrossRefSourceAnnotation},
+	}
+	if err := s.ReplaceCrossRefsFrom(ctx, "web", second); err != nil {
+		t.Fatalf("second replace: %v", err)
+	}
+
+	inbound, err := s.ListInboundCrossRefs(ctx, "auth-svc")
+	if err != nil {
+		t.Fatalf("ListInboundCrossRefs: %v", err)
+	}
+	if len(inbound) != 1 || inbound[0].Raw != "ccg://auth-svc/#New" {
+		t.Fatalf("inbound after replace = %+v, want only the new auth-svc ref", inbound)
+	}
+
+	outbound, err := s.ListOutboundCrossRefs(ctx, "web")
+	if err != nil {
+		t.Fatalf("ListOutboundCrossRefs: %v", err)
+	}
+	if len(outbound) != 2 {
+		t.Fatalf("outbound rows = %d, want 2", len(outbound))
+	}
+}
+
+func TestListInboundCrossRefs_ExcludesSelfNamespace(t *testing.T) {
+	s := setupTestDB(t)
+	ctx := context.Background()
+	rows := []graph.CrossRef{
+		{FromNamespace: "auth-svc", FromNodeID: 1, Raw: "ccg://auth-svc/internal#Self", ToNamespace: "auth-svc", ToSymbol: "Self", Status: graph.CrossRefStatusResolved, Source: graph.CrossRefSourceAnnotation},
+	}
+	if err := s.ReplaceCrossRefsFrom(ctx, "auth-svc", rows); err != nil {
+		t.Fatalf("replace: %v", err)
+	}
+	inbound, err := s.ListInboundCrossRefs(ctx, "auth-svc")
+	if err != nil {
+		t.Fatalf("ListInboundCrossRefs: %v", err)
+	}
+	if len(inbound) != 0 {
+		t.Fatalf("inbound = %d rows, want 0 (self refs are rebuilt outbound)", len(inbound))
+	}
+}
+
+func TestUpdateCrossRefResolution_RemapsAndKills(t *testing.T) {
+	s := setupTestDB(t)
+	ctx := context.Background()
+	resolved := uint(42)
+	rows := []graph.CrossRef{
+		{FromNamespace: "web", FromNodeID: 1, Raw: "ccg://auth-svc/#Fn", ToNamespace: "auth-svc", ToSymbol: "Fn", ResolvedNodeID: &resolved, Status: graph.CrossRefStatusResolved, Source: graph.CrossRefSourceAnnotation},
+	}
+	if err := s.ReplaceCrossRefsFrom(ctx, "web", rows); err != nil {
+		t.Fatalf("replace: %v", err)
+	}
+	stored, err := s.ListInboundCrossRefs(ctx, "auth-svc")
+	if err != nil || len(stored) != 1 {
+		t.Fatalf("load stored row: %v (%d rows)", err, len(stored))
+	}
+
+	if err := s.UpdateCrossRefResolution(ctx, stored[0].ID, nil, graph.CrossRefStatusDead); err != nil {
+		t.Fatalf("kill resolution: %v", err)
+	}
+	after, err := s.ListInboundCrossRefs(ctx, "auth-svc")
+	if err != nil {
+		t.Fatalf("reload: %v", err)
+	}
+	if after[0].Status != graph.CrossRefStatusDead || after[0].ResolvedNodeID != nil {
+		t.Fatalf("after kill = %+v, want dead with nil node", after[0])
+	}
+
+	remapped := uint(99)
+	if err := s.UpdateCrossRefResolution(ctx, stored[0].ID, &remapped, graph.CrossRefStatusResolved); err != nil {
+		t.Fatalf("remap resolution: %v", err)
+	}
+	final, err := s.ListInboundCrossRefs(ctx, "auth-svc")
+	if err != nil {
+		t.Fatalf("reload final: %v", err)
+	}
+	if final[0].Status != graph.CrossRefStatusResolved || final[0].ResolvedNodeID == nil || *final[0].ResolvedNodeID != 99 {
+		t.Fatalf("after remap = %+v, want resolved node 99", final[0])
+	}
+}

internal/adapters/outbound/graphgorm/store.go

@@ -49,6 +49,7 @@ func (s *Store) AutoMigrate() error {
 		&graph.ParseCacheEntry{},
 		&graph.UnresolvedEdgeCandidate{},
 		&graph.UnresolvedIndexState{},
+		&graph.CrossRef{},
 	); err != nil {
 		return err
 	}