Phase 2 Semantic Ceiling (tatara-memory) Implementation Plan¶

//go:build integration

package codegraph_test

import (
    "context"
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func colExists(t *testing.T, ctx context.Context, db interface {
    QueryRowContext(context.Context, string, ...any) *rowQuerier
}, table, col string) bool {
    t.Helper()
    return false
}

func TestMigratePhase2Schema(t *testing.T) {
    s, db, ctx := freshStoreWithDB(t)
    _ = s

    tableExists := func(name string) bool {
        var ok bool
        require.NoError(t, db.QueryRowContext(ctx, `
            SELECT EXISTS(SELECT 1 FROM information_schema.tables WHERE table_name=$1)`, name).Scan(&ok))
        return ok
    }
    columnExists := func(table, col string) bool {
        var ok bool
        require.NoError(t, db.QueryRowContext(ctx, `
            SELECT EXISTS(SELECT 1 FROM information_schema.columns WHERE table_name=$1 AND column_name=$2)`, table, col).Scan(&ok))
        return ok
    }

    require.True(t, columnExists("code_edges", "extractor"), "code_edges.extractor must exist")
    require.True(t, columnExists("code_entities", "extractor"), "code_entities.extractor must exist")
    require.True(t, columnExists("code_hyperedges", "extractor"), "code_hyperedges.extractor must exist")

    require.True(t, tableExists("semantic_extractions"), "semantic_extractions table must exist")
    require.True(t, tableExists("code_communities"), "code_communities table must exist")
    require.True(t, tableExists("repo_analytics_state"), "repo_analytics_state table must exist")

    // extractor defaults to 'ast'
    _, err := db.ExecContext(ctx, `INSERT INTO code_entities(repo, id, name, type, file_path) VALUES ('m4','m4:e','e','go_func','a.go')`)
    require.NoError(t, err)
    var extractor string
    require.NoError(t, db.QueryRowContext(ctx, `SELECT extractor FROM code_entities WHERE repo='m4' AND id='m4:e'`).Scan(&extractor))
    require.Equal(t, "ast", extractor)

    _ = codegraph.MigrationSQL()
}

type rowQuerier struct{}

//go:build integration

package codegraph_test

import (
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func TestMigratePhase2Schema(t *testing.T) {
    _, db, ctx := freshStoreWithDB(t)

    tableExists := func(name string) bool {
        var ok bool
        require.NoError(t, db.QueryRowContext(ctx, `
            SELECT EXISTS(SELECT 1 FROM information_schema.tables WHERE table_name=$1)`, name).Scan(&ok))
        return ok
    }
    columnExists := func(table, col string) bool {
        var ok bool
        require.NoError(t, db.QueryRowContext(ctx, `
            SELECT EXISTS(SELECT 1 FROM information_schema.columns WHERE table_name=$1 AND column_name=$2)`, table, col).Scan(&ok))
        return ok
    }

    require.True(t, columnExists("code_edges", "extractor"))
    require.True(t, columnExists("code_entities", "extractor"))
    require.True(t, columnExists("code_hyperedges", "extractor"))
    require.True(t, tableExists("semantic_extractions"))
    require.True(t, tableExists("code_communities"))
    require.True(t, tableExists("repo_analytics_state"))

    _, err := db.ExecContext(ctx, `INSERT INTO code_entities(repo, id, name, type, file_path) VALUES ('m4','m4:e','e','go_func','a.go')`)
    require.NoError(t, err)
    var extractor string
    require.NoError(t, db.QueryRowContext(ctx, `SELECT extractor FROM code_entities WHERE repo='m4' AND id='m4:e'`).Scan(&extractor))
    require.Equal(t, "ast", extractor)

    _ = codegraph.MigrationSQL()
}

package codegraph

import (
    "context"
    "database/sql"
    _ "embed"
)

//go:embed migrations/0001_codegraph.sql
var migration0001 string

//go:embed migrations/0002_cross_repo_symbols.sql
var migration0002 string

//go:embed migrations/0003_phase0_graphify.sql
var migration0003 string

//go:embed migrations/0004_phase2_semantic.sql
var migration0004 string

// MigrationSQL returns the DDL for the code-graph schema (all migrations concatenated).
func MigrationSQL() string {
    return migration0001 + "\n" + migration0002 + "\n" + migration0003 + "\n" + migration0004
}

// Migrate applies the code-graph schema to db, creating tables if they do not exist.
func Migrate(ctx context.Context, db *sql.DB) error {
    if _, err := db.ExecContext(ctx, migration0001); err != nil {
        return err
    }
    if _, err := db.ExecContext(ctx, migration0002); err != nil {
        return err
    }
    if _, err := db.ExecContext(ctx, migration0003); err != nil {
        return err
    }
    _, err := db.ExecContext(ctx, migration0004)
    return err
}

func TestGraphPushExtractorFileSHAsJSONTags(t *testing.T) {
    p := codegraph.GraphPush{
        Repo:      "r",
        Extractor: "semantic",
        Files:     []string{"a.go"},
        FileSHAs:  map[string]string{"a.go": "sha1"},
    }
    b, err := json.Marshal(p)
    require.NoError(t, err)
    s := string(b)
    require.Contains(t, s, `"extractor":"semantic"`)
    require.Contains(t, s, `"file_shas":{"a.go":"sha1"}`)

    // omitempty: extractor and file_shas absent when zero
    b2, err := json.Marshal(codegraph.GraphPush{Repo: "r", Files: []string{"a.go"}})
    require.NoError(t, err)
    require.NotContains(t, string(b2), "extractor")
    require.NotContains(t, string(b2), "file_shas")

    // FileSHA decodes path/content_sha tags
    var fs codegraph.FileSHA
    require.NoError(t, json.Unmarshal([]byte(`{"path":"a.go","content_sha":"deadbeef"}`), &fs))
    require.Equal(t, "a.go", fs.Path)
    require.Equal(t, "deadbeef", fs.ContentSHA)
}

// FileSHA is one file's content hash, used by the semantic-misses cache check
// and as the per-path value of GraphPush.FileSHAs.
type FileSHA struct {
    Path       string `json:"path"`
    ContentSHA string `json:"content_sha"`
}

// GraphPush is one ingest request: the changed file set plus the entities and
// edges those files own. Reconciliation deletes the prior graph owned by Files
// (scoped by Extractor) then inserts Entities, Edges, Symbols, and Hyperedges,
// in one transaction. When FileSHAs is set the semantic_extractions cache is
// upserted for those paths.
type GraphPush struct {
    Repo       string            `json:"repo"`
    Commit     string            `json:"commit,omitempty"`
    Extractor  string            `json:"extractor,omitempty"`
    Files      []string          `json:"files"`
    Entities   []Entity          `json:"entities"`
    Edges      []Edge            `json:"edges"`
    Symbols    []SymbolRow       `json:"symbols,omitempty"`
    Hyperedges []Hyperedge       `json:"hyperedges,omitempty"`
    FileSHAs   map[string]string `json:"file_shas,omitempty"`
}

// ExtractorAST is the default origin tag written to graph rows when a push omits
// Extractor. Reconcile scopes its per-src_file deletes by this tag.
const ExtractorAST = "ast"

// ExtractorSemantic tags rows produced by the LLM semantic extraction stage.
const ExtractorSemantic = "semantic"

//go:build integration

package codegraph_test

import (
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func TestReconcile_ExtractorScopedDeletesPreserveOtherOrigin(t *testing.T) {
    s, db, ctx := freshStoreWithDB(t)

    // AST push for a.go
    _, err := s.Reconcile(ctx, codegraph.GraphPush{
        Repo:      "ex",
        Extractor: codegraph.ExtractorAST,
        Files:     []string{"a.go"},
        Entities:  []codegraph.Entity{ent("ex:a", "go_func", "a.go"), ent("ex:b", "go_func", "a.go")},
        Edges:     []codegraph.Edge{{From: "ex:a", To: "ex:b", Relation: "calls", SrcFile: "a.go"}},
    })
    require.NoError(t, err)

    // semantic push for the SAME file a.go
    _, err = s.Reconcile(ctx, codegraph.GraphPush{
        Repo:      "ex",
        Extractor: codegraph.ExtractorSemantic,
        Files:     []string{"a.go"},
        Entities:  []codegraph.Entity{{ID: "concept:ex:auth", Name: "auth", Type: codegraph.EntityConcept, FilePath: "a.go"}},
        Edges:     []codegraph.Edge{{From: "ex:a", To: "concept:ex:auth", Relation: codegraph.RelConceptuallyRelated, SrcFile: "a.go"}},
        FileSHAs:  map[string]string{"a.go": "sha-1"},
    })
    require.NoError(t, err)

    count := func(q string) int {
        var n int
        require.NoError(t, db.QueryRowContext(ctx, q).Scan(&n))
        return n
    }
    // Both origins coexist.
    require.Equal(t, 2, count(`SELECT count(*) FROM code_entities WHERE repo='ex' AND extractor='ast'`))
    require.Equal(t, 1, count(`SELECT count(*) FROM code_entities WHERE repo='ex' AND extractor='semantic'`))
    require.Equal(t, 1, count(`SELECT count(*) FROM code_edges WHERE repo='ex' AND extractor='ast'`))
    require.Equal(t, 1, count(`SELECT count(*) FROM code_edges WHERE repo='ex' AND extractor='semantic'`))

    // Re-ingest AST for a.go: semantic rows survive.
    _, err = s.Reconcile(ctx, codegraph.GraphPush{
        Repo:      "ex",
        Extractor: codegraph.ExtractorAST,
        Files:     []string{"a.go"},
        Entities:  []codegraph.Entity{ent("ex:a", "go_func", "a.go")},
    })
    require.NoError(t, err)
    require.Equal(t, 1, count(`SELECT count(*) FROM code_entities WHERE repo='ex' AND extractor='ast'`))
    require.Equal(t, 1, count(`SELECT count(*) FROM code_entities WHERE repo='ex' AND extractor='semantic'`), "semantic entity must survive AST re-ingest")
    require.Equal(t, 1, count(`SELECT count(*) FROM code_edges WHERE repo='ex' AND extractor='semantic'`), "semantic edge must survive AST re-ingest")

    // semantic_extractions cache row written.
    var sha string
    require.NoError(t, db.QueryRowContext(ctx, `SELECT content_sha FROM semantic_extractions WHERE repo='ex' AND file_path='a.go'`).Scan(&sha))
    require.Equal(t, "sha-1", sha)

    // repo_analytics_state marked dirty on reconcile.
    var dirty bool
    require.NoError(t, db.QueryRowContext(ctx, `SELECT dirty FROM repo_analytics_state WHERE repo='ex'`).Scan(&dirty))
    require.True(t, dirty)
}

func TestReconcile_DefaultExtractorIsAST(t *testing.T) {
    s, db, ctx := freshStoreWithDB(t)
    _, err := s.Reconcile(ctx, codegraph.GraphPush{
        Repo:     "def",
        Files:    []string{"a.go"},
        Entities: []codegraph.Entity{ent("def:a", "go_func", "a.go")},
    })
    require.NoError(t, err)
    var extractor string
    require.NoError(t, db.QueryRowContext(ctx, `SELECT extractor FROM code_entities WHERE repo='def' AND id='def:a'`).Scan(&extractor))
    require.Equal(t, "ast", extractor)
}

// Reconcile deletes the prior graph owned by p.Files for p's Extractor origin,
// then inserts p.Entities, p.Edges, p.Symbols, and p.Hyperedges (all tagged with
// that extractor). When p.FileSHAs is set it upserts the semantic_extractions
// cache. It always marks repo_analytics_state dirty. All in one transaction.
func (s *PGStore) Reconcile(ctx context.Context, p GraphPush) (PushResult, error) {
    ext := p.Extractor
    if ext == "" {
        ext = ExtractorAST
    }

    tx, err := s.db.BeginTx(ctx, nil)
    if err != nil {
        return PushResult{}, err
    }
    defer func() { _ = tx.Rollback() }()

    for _, f := range p.Files {
        if _, err := tx.ExecContext(ctx, `DELETE FROM code_edges WHERE repo=$1 AND src_file=$2 AND extractor=$3`, p.Repo, f, ext); err != nil {
            return PushResult{}, err
        }
        if _, err := tx.ExecContext(ctx, `DELETE FROM code_entities WHERE repo=$1 AND file_path=$2 AND extractor=$3`, p.Repo, f, ext); err != nil {
            return PushResult{}, err
        }
        if ext == ExtractorAST {
            if _, err := tx.ExecContext(ctx, `DELETE FROM cross_repo_symbols WHERE repo=$1 AND src_file=$2`, p.Repo, f); err != nil {
                return PushResult{}, err
            }
        }
        if _, err := tx.ExecContext(ctx,
            `DELETE FROM code_hyperedge_members WHERE repo=$1 AND hyperedge_id IN (
                SELECT id FROM code_hyperedges WHERE repo=$1 AND src_file=$2 AND extractor=$3)`, p.Repo, f, ext); err != nil {
            return PushResult{}, err
        }
        if _, err := tx.ExecContext(ctx, `DELETE FROM code_hyperedges WHERE repo=$1 AND src_file=$2 AND extractor=$3`, p.Repo, f, ext); err != nil {
            return PushResult{}, err
        }
    }

    for _, e := range p.Entities {
        if _, err := tx.ExecContext(ctx, `
            INSERT INTO code_entities(repo, id, name, type, description, file_path, properties,
                line_start, line_end, source_url, author, captured_at, extractor)
            VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,$8,$9,$10,$11,$12,$13)
            ON CONFLICT (repo, id) DO UPDATE SET
                name=EXCLUDED.name, type=EXCLUDED.type, description=EXCLUDED.description,
                file_path=EXCLUDED.file_path, properties=EXCLUDED.properties,
                line_start=EXCLUDED.line_start, line_end=EXCLUDED.line_end,
                source_url=EXCLUDED.source_url, author=EXCLUDED.author, captured_at=EXCLUDED.captured_at,
                extractor=EXCLUDED.extractor`,
            p.Repo, e.ID, e.Name, e.Type, e.Description, e.FilePath, marshalProps(e.Properties),
            nullInt(e.LineStart), nullInt(e.LineEnd), nullStr(e.SourceURL), nullStr(e.Author), nullTime(e.CapturedAt), ext); err != nil {
            return PushResult{}, err
        }
    }

    for _, e := range p.Edges {
        score := e.ConfidenceScore
        tier := e.ConfidenceTier
        if score == 0 && tier == "" {
            score, tier = 1.0, TierExtracted
        } else if tier == "" {
            tier = TierFor(score)
        }
        if _, err := tx.ExecContext(ctx, `
            INSERT INTO code_edges(repo, from_id, to_id, relation, src_file, properties, confidence_score, confidence_tier, extractor)
            VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7,$8,$9)
            ON CONFLICT (repo, from_id, to_id, relation) DO UPDATE SET
                src_file=EXCLUDED.src_file, properties=EXCLUDED.properties,
                confidence_score=EXCLUDED.confidence_score, confidence_tier=EXCLUDED.confidence_tier,
                extractor=EXCLUDED.extractor`,
            p.Repo, e.From, e.To, e.Relation, e.SrcFile, marshalProps(e.Properties), score, tier, ext); err != nil {
            return PushResult{}, err
        }
    }

    for _, sym := range p.Symbols {
        if _, err := tx.ExecContext(ctx, `
            INSERT INTO cross_repo_symbols(repo, symbol, lang, kind, role, entity_id, src_file)
            VALUES ($1,$2,$3,$4,$5,$6,$7)
            ON CONFLICT (repo, symbol, role, entity_id) DO UPDATE SET
                lang=EXCLUDED.lang, kind=EXCLUDED.kind, src_file=EXCLUDED.src_file`,
            p.Repo, sym.Symbol, sym.Lang, sym.Kind, sym.Role, sym.EntityID, sym.SrcFile); err != nil {
            return PushResult{}, err
        }
    }

    for _, h := range p.Hyperedges {
        score := h.ConfidenceScore
        if score == 0 {
            score = 1.0
        }
        if _, err := tx.ExecContext(ctx, `
            INSERT INTO code_hyperedges(repo, id, label, relation, confidence_score, src_file, properties, extractor)
            VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,$8)
            ON CONFLICT (repo, id) DO UPDATE SET
                label=EXCLUDED.label, relation=EXCLUDED.relation,
                confidence_score=EXCLUDED.confidence_score, src_file=EXCLUDED.src_file,
                properties=EXCLUDED.properties, extractor=EXCLUDED.extractor`,
            p.Repo, h.ID, h.Label, h.Relation, score, h.SrcFile, marshalProps(h.Properties), ext); err != nil {
            return PushResult{}, err
        }
        for _, m := range h.Members {
            if _, err := tx.ExecContext(ctx, `
                INSERT INTO code_hyperedge_members(repo, hyperedge_id, entity_id)
                VALUES ($1,$2,$3)
                ON CONFLICT (repo, hyperedge_id, entity_id) DO NOTHING`,
                p.Repo, h.ID, m); err != nil {
                return PushResult{}, err
            }
        }
    }

    for path, sha := range p.FileSHAs {
        if _, err := tx.ExecContext(ctx, `
            INSERT INTO semantic_extractions(repo, file_path, content_sha, extracted_at)
            VALUES ($1,$2,$3, now())
            ON CONFLICT (repo, file_path) DO UPDATE SET
                content_sha=EXCLUDED.content_sha, extracted_at=now()`,
            p.Repo, path, sha); err != nil {
            return PushResult{}, err
        }
    }

    if _, err := tx.ExecContext(ctx, `
        INSERT INTO repo_analytics_state(repo, dirty, reconciled_at)
        VALUES ($1, true, now())
        ON CONFLICT (repo) DO UPDATE SET dirty=true, reconciled_at=now()`, p.Repo); err != nil {
        return PushResult{}, err
    }

    if err := tx.Commit(); err != nil {
        return PushResult{}, err
    }
    return PushResult{
        Repo:             p.Repo,
        Files:            len(p.Files),
        EntitiesUpserted: len(p.Entities),
        EdgesUpserted:    len(p.Edges),
    }, nil
}

//go:build integration

package codegraph_test

import (
    "sort"
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func TestSemanticMisses_AbsentDifferentAndMatching(t *testing.T) {
    s, _, ctx := freshStoreWithDB(t)

    // Seed cache: a.go -> sha-a (match), b.go -> sha-old (will differ).
    _, err := s.Reconcile(ctx, codegraph.GraphPush{
        Repo:      "sm",
        Extractor: codegraph.ExtractorSemantic,
        Files:     []string{"a.go", "b.go"},
        FileSHAs:  map[string]string{"a.go": "sha-a", "b.go": "sha-old"},
    })
    require.NoError(t, err)

    misses, err := s.SemanticMisses(ctx, "sm", []codegraph.FileSHA{
        {Path: "a.go", ContentSHA: "sha-a"},   // hit (matches)
        {Path: "b.go", ContentSHA: "sha-new"}, // miss (differs)
        {Path: "c.go", ContentSHA: "sha-c"},   // miss (absent)
    })
    require.NoError(t, err)
    sort.Strings(misses)
    require.Equal(t, []string{"b.go", "c.go"}, misses)
}

func TestSemanticMisses_EmptyInput(t *testing.T) {
    s, _, ctx := freshStoreWithDB(t)
    misses, err := s.SemanticMisses(ctx, "sm2", nil)
    require.NoError(t, err)
    require.Empty(t, misses)
}

// SemanticMisses returns the subset of files whose stored content_sha differs
// from the supplied sha or is absent from the semantic_extractions cache.
// These are the paths the ingester must re-extract with the LLM.
func (s *PGStore) SemanticMisses(ctx context.Context, repo string, files []FileSHA) ([]string, error) {
    var out []string
    for _, f := range files {
        var stored string
        err := s.db.QueryRowContext(ctx,
            `SELECT content_sha FROM semantic_extractions WHERE repo=$1 AND file_path=$2`,
            repo, f.Path).Scan(&stored)
        if errors.Is(err, sql.ErrNoRows) {
            out = append(out, f.Path)
            continue
        }
        if err != nil {
            return nil, err
        }
        if stored != f.ContentSHA {
            out = append(out, f.Path)
        }
    }
    return out, nil
}

    SemanticMisses(ctx context.Context, repo string, files []FileSHA) ([]string, error)

// SemanticMisses returns the files whose cached content_sha differs or is absent.
func (s *Service) SemanticMisses(ctx context.Context, repo string, files []FileSHA) ([]string, error) {
    return s.store.SemanticMisses(ctx, repo, files)
}

//go:build integration

package codegraph_test

import (
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func TestRelated_SemanticEdgesWithConfidence(t *testing.T) {
    s, _, ctx := freshStoreWithDB(t)

    _, err := s.Reconcile(ctx, codegraph.GraphPush{
        Repo:      "rel",
        Extractor: codegraph.ExtractorSemantic,
        Files:     []string{"a.go"},
        Entities: []codegraph.Entity{
            {ID: "rel:a", Name: "A", Type: "go_func", FilePath: "a.go"},
            {ID: "rel:b", Name: "B", Type: "go_func", FilePath: "a.go"},
            {ID: "rel:c", Name: "C", Type: "go_func", FilePath: "a.go"},
        },
        Edges: []codegraph.Edge{
            {From: "rel:a", To: "rel:b", Relation: codegraph.RelConceptuallyRelated, SrcFile: "a.go", ConfidenceScore: 0.9, ConfidenceTier: codegraph.TierInferred},
            {From: "rel:a", To: "rel:c", Relation: codegraph.RelSemanticallySimilar, SrcFile: "a.go", ConfidenceScore: 0.4, ConfidenceTier: codegraph.TierInferred},
        },
    })
    require.NoError(t, err)

    // All semantic relations, min_confidence 0 -> both targets.
    all, err := s.Related(ctx, "rel", "rel:a", nil, 0)
    require.NoError(t, err)
    require.Len(t, all, 2)

    // min_confidence 0.5 -> only rel:b survives.
    hi, err := s.Related(ctx, "rel", "rel:a", nil, 0.5)
    require.NoError(t, err)
    require.Len(t, hi, 1)
    require.Equal(t, "rel:b", hi[0].Entity.ID)
    require.Equal(t, codegraph.RelConceptuallyRelated, hi[0].Relation)
    require.InDelta(t, 0.9, hi[0].ConfidenceScore, 1e-6)

    // relation filter narrows to one relation.
    sim, err := s.Related(ctx, "rel", "rel:a", []string{codegraph.RelSemanticallySimilar}, 0)
    require.NoError(t, err)
    require.Len(t, sim, 1)
    require.Equal(t, "rel:c", sim[0].Entity.ID)
}

func TestHyperedges_AndHyperedge(t *testing.T) {
    s, _, ctx := freshStoreWithDB(t)

    _, err := s.Reconcile(ctx, codegraph.GraphPush{
        Repo:      "hy",
        Extractor: codegraph.ExtractorSemantic,
        Files:     []string{"a.go"},
        Entities: []codegraph.Entity{
            {ID: "hy:a", Name: "A", Type: "go_func", FilePath: "a.go"},
            {ID: "hy:b", Name: "B", Type: "go_func", FilePath: "a.go"},
            {ID: "hy:c", Name: "C", Type: "go_func", FilePath: "a.go"},
        },
        Hyperedges: []codegraph.Hyperedge{
            {ID: "hy:auth-flow", Label: "auth flow", Relation: "participate_in", SrcFile: "a.go", Members: []string{"hy:a", "hy:b", "hy:c"}},
        },
    })
    require.NoError(t, err)

    // All hyperedges in repo.
    all, err := s.Hyperedges(ctx, "hy", "")
    require.NoError(t, err)
    require.Len(t, all, 1)
    require.Equal(t, "hy:auth-flow", all[0].ID)
    require.ElementsMatch(t, []string{"hy:a", "hy:b", "hy:c"}, all[0].Members)

    // Filter by entity membership.
    byEnt, err := s.Hyperedges(ctx, "hy", "hy:b")
    require.NoError(t, err)
    require.Len(t, byEnt, 1)

    none, err := s.Hyperedges(ctx, "hy", "hy:zzz")
    require.NoError(t, err)
    require.Empty(t, none)

    // Single hyperedge by id.
    one, err := s.Hyperedge(ctx, "hy", "hy:auth-flow")
    require.NoError(t, err)
    require.Equal(t, "auth flow", one.Label)
    require.Len(t, one.Members, 3)

    _, err = s.Hyperedge(ctx, "hy", "nope")
    require.ErrorIs(t, err, codegraph.ErrEntityNotFound)
}

// RelatedResult is a semantic neighbor of an entity: the target entity plus the
// semantic relation and confidence of the edge that reached it.
type RelatedResult struct {
    Entity
    Relation        string  `json:"relation"`
    ConfidenceScore float64 `json:"confidence_score"`
    ConfidenceTier  string  `json:"confidence_tier"`
}

// HyperedgeDetail is a hyperedge plus its resolved member entity IDs.
type HyperedgeDetail struct {
    Hyperedge
}

// semanticRelations is the relation vocabulary served by Related when the caller
// does not narrow it.
var semanticRelations = []string{
    RelConceptuallyRelated,
    RelSemanticallySimilar,
    RelRationaleFor,
    RelSharesDataWith,
    RelCites,
}

// Related returns the semantic-extractor neighbors of id: targets reached by a
// semantic relation edge with confidence_score >= minConfidence. When relations
// is empty the full semantic relation vocabulary is used.
func (s *PGStore) Related(ctx context.Context, repo, id string, relations []string, minConfidence float64) ([]RelatedResult, error) {
    rels := relations
    if len(rels) == 0 {
        rels = semanticRelations
    }
    relStr := strings.Join(rels, ",")
    rows, err := s.db.QueryContext(ctx, `
        SELECT en.id, en.name, en.type, en.description, en.file_path, en.properties,
               e.relation, e.confidence_score, e.confidence_tier
        FROM code_edges e
        JOIN code_entities en ON en.repo=e.repo AND en.id=e.to_id
        WHERE e.repo=$1 AND e.from_id=$2
          AND e.extractor='semantic'
          AND e.relation = ANY(string_to_array($3, ','))
          AND e.confidence_score >= $4
        ORDER BY e.confidence_score DESC, en.id`,
        repo, id, relStr, minConfidence)
    if err != nil {
        return nil, err
    }
    defer func() { _ = rows.Close() }()
    var out []RelatedResult
    for rows.Next() {
        var r RelatedResult
        var raw []byte
        if err := rows.Scan(&r.ID, &r.Name, &r.Type, &r.Description, &r.FilePath, &raw,
            &r.Relation, &r.ConfidenceScore, &r.ConfidenceTier); err != nil {
            return nil, err
        }
        r.Properties = scanProps(raw)
        out = append(out, r)
    }
    return out, rows.Err()
}

// Hyperedges returns the hyperedges in repo. When entityID is non-empty only
// hyperedges whose members include it are returned.
func (s *PGStore) Hyperedges(ctx context.Context, repo, entityID string) ([]Hyperedge, error) {
    var rows *sql.Rows
    var err error
    if entityID == "" {
        rows, err = s.db.QueryContext(ctx, `
            SELECT id, label, relation, confidence_score, src_file, properties
            FROM code_hyperedges WHERE repo=$1 ORDER BY id`, repo)
    } else {
        rows, err = s.db.QueryContext(ctx, `
            SELECT h.id, h.label, h.relation, h.confidence_score, h.src_file, h.properties
            FROM code_hyperedges h
            JOIN code_hyperedge_members m ON m.repo=h.repo AND m.hyperedge_id=h.id
            WHERE h.repo=$1 AND m.entity_id=$2 ORDER BY h.id`, repo, entityID)
    }
    if err != nil {
        return nil, err
    }
    defer func() { _ = rows.Close() }()
    var out []Hyperedge
    for rows.Next() {
        h, err := s.scanHyperedge(rows)
        if err != nil {
            return nil, err
        }
        out = append(out, h)
    }
    if err := rows.Err(); err != nil {
        return nil, err
    }
    for i := range out {
        members, err := s.hyperedgeMembers(ctx, repo, out[i].ID)
        if err != nil {
            return nil, err
        }
        out[i].Members = members
    }
    return out, nil
}

// Hyperedge returns a single hyperedge with its members, or ErrEntityNotFound.
func (s *PGStore) Hyperedge(ctx context.Context, repo, id string) (Hyperedge, error) {
    row := s.db.QueryRowContext(ctx, `
        SELECT id, label, relation, confidence_score, src_file, properties
        FROM code_hyperedges WHERE repo=$1 AND id=$2`, repo, id)
    h, err := s.scanHyperedge(row)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return Hyperedge{}, ErrEntityNotFound
        }
        return Hyperedge{}, err
    }
    members, err := s.hyperedgeMembers(ctx, repo, id)
    if err != nil {
        return Hyperedge{}, err
    }
    h.Members = members
    return h, nil
}

func (s *PGStore) scanHyperedge(r rowScanner) (Hyperedge, error) {
    var h Hyperedge
    var raw []byte
    if err := r.Scan(&h.ID, &h.Label, &h.Relation, &h.ConfidenceScore, &h.SrcFile, &raw); err != nil {
        return Hyperedge{}, err
    }
    h.Properties = scanProps(raw)
    return h, nil
}

func (s *PGStore) hyperedgeMembers(ctx context.Context, repo, id string) ([]string, error) {
    rows, err := s.db.QueryContext(ctx,
        `SELECT entity_id FROM code_hyperedge_members WHERE repo=$1 AND hyperedge_id=$2 ORDER BY entity_id`, repo, id)
    if err != nil {
        return nil, err
    }
    defer func() { _ = rows.Close() }()
    var out []string
    for rows.Next() {
        var m string
        if err := rows.Scan(&m); err != nil {
            return nil, err
        }
        out = append(out, m)
    }
    return out, rows.Err()
}