store

Overview ¶

Qualified Name (qname) conventions for external consumers ¶

CKG stores every symbol with a qualified_name (qname) field whose format is language-specific but follows a consistent hierarchy:

Go:         "package.Type.Method"   e.g. "vault.Vault.Deposit"
TypeScript: "module.Class.method"   e.g. "auth.AuthService.login"
Solidity:   "Contract.function"     e.g. "GovStaking.deposit"

The qname is the primary lookup key for traversal methods:

Reader.FindSymbol(name, exact, opts)        — exact or suffix match
Reader.NeighborhoodByQname(qname, depth, reverse, edgeTypes...)
Reader.SubgraphByQname(qname, depth)

Canonical-helper pattern for cks/ckv ¶

External consumers (cks, ckv) typically receive user input that does not match the stored qname exactly — partial names, mixed case, or receiver-style prefixes (*pkg.Type). The recommended wrapping pattern uses FindSymbol with exact=false (suffix LIKE match) as the canonical resolution step, then passes the resolved qname to traversal methods:

r, _ := store.OpenReadOnly("/path/to/graph.db")
defer r.Close()

// Step 1: resolve user input → canonical qname(s).
// exact=false matches "%.Deposit" so "Deposit" finds
// "vault.Vault.Deposit" without the caller knowing the package.
nodes, _ := r.FindSymbol("Deposit", false, store.FindSymbolOptions{
    Language: "go",
    Kinds:    []string{"Function", "Method"},
})

// Step 2: use the resolved qname for traversal.
for _, n := range nodes {
    callers, edges, _ := r.NeighborhoodByQname(
        n.QualifiedName, 2, true,  // reverse=true → callers
    )
    // ... use callers, edges
}

Normalisation rules ¶

Before calling FindSymbol, strip these prefixes that leak from AST representations but are not stored in the graph:

• Go pointer receiver: "*pkg.Type.Method" → "pkg.Type.Method"
• Go address-of: "&pkg.New" → "pkg.New"

CKG's internal extractSymbols already applies these rules (see internal/eval/runner.go); external consumers should replicate the same strip before lookup to avoid zero-result queries.

SearchFTS vs FindSymbol ¶

Use FindSymbol when you have an identifier (exact or suffix). Use SearchFTS / SearchWithOpts when you have natural-language keywords or need BM25 ranking across the full corpus. The two paths are complementary — cks's typical flow is:

ckv (vocab bridge) → exact keywords → ckg FindSymbol or SearchFTS

Package store is the public, read-only graph access surface for external callers (eval harness, sister repos like code-knowledge-system). It re-exports the minimum useful subset of internal/persist as type aliases so callers don't have to depend on internal/persist directly. Write access stays internal — there is no Writer here by design.

Stability ¶

This surface follows semantic versioning once the sister-repo extraction lands. Until then, treat it as the single throat to choke when changing internal/persist — anything that breaks the alias here will break external consumers, even if in-repo callers compile fine.

What to import from where ¶

External consumers (anything outside this module) should import only from pkg/store and pkg/types. They cannot reach internal/persist by the Go `internal/` rule, and that's intentional: pkg/store decides what to promote to the public surface.

Reader covers the read API; SearchHit / SearchFTSOptions / FindSymbolOptions are the value types you'll touch when calling Reader.SearchFTS or Reader.FindSymbol. Manifest is the minimal mirror of build-time metadata — use the GetManifest helper rather than Reader.GetManifest directly so the projection (which drops incremental-cache fields) stays the single source of truth (CKG-7).

Do NOT ¶

External code MUST NOT type-alias persist.StoreReader on its own (the "self-shim" pattern surfaced by the cks dogfood). That duplicates the public surface and silently drifts the moment we change internal/persist. If you find yourself wanting one, it means a type you need isn't re-exported here yet — open a PR to add the alias instead.