evidence

Documentation

Overview

Package evidence ports the runtime-facing evidence pack and assembler from src/main/java/.../intelligence/evidence/. The pack bundles everything the caller (an MCP client, a REST consumer) needs to understand a symbol or file: matched symbols, related files, cross-references, source snippets, provenance, and capability notes.

Mirrors EvidencePack.java + EvidencePackAssembler.java; field names match the Java record 1:1 so the JSON shape is structurally identical.

Index

• type ArtifactMetadata
• type Assembler
  • func NewAssembler(lex LexFinder, snippets *lexical.SnippetStore, graph GraphReader, ...) *Assembler
  • func (a *Assembler) Assemble(ctx context.Context, req Request, meta *ArtifactMetadata) (Pack, error)
• type Capability
• type GraphReader
• type LexFinder
• type Pack
  • func EmptyPack(meta *ArtifactMetadata, note string) Pack
• type Request
  • func (r Request) IsEmpty() bool

Types

type ArtifactMetadata

type ArtifactMetadata struct {
	Repository    string         `json:"repository,omitempty"`
	Commit        string         `json:"commit,omitempty"`
	BuiltAt       string         `json:"built_at,omitempty"`
	Tooling       map[string]any `json:"tooling,omitempty"`
	Capabilities  map[string]any `json:"capabilities,omitempty"`
	IntegrityHash string         `json:"integrity_hash,omitempty"`
}

ArtifactMetadata is the provenance projection bundled into every pack. Mirrors Java intelligence/provenance/ArtifactMetadata.java. The Go-side provenance package is not yet ported, so this lives here as a forward declaration; once the dedicated package lands the type will move and an alias kept here for backwards compatibility.

Field names map to the Java record component names so cross-port diffs stay clean; Capabilities is a free-form map so we do not pull the intelligence/query package into the pack's public surface.

type Assembler

type Assembler struct {
	// contains filtered or unexported fields
}

Assembler builds an EvidencePack from a query intent.

Stateless and goroutine-safe — every field is set at construction time and only read thereafter. Mirrors Java EvidencePackAssembler.

func NewAssembler

func NewAssembler(
	lex LexFinder,
	snippets *lexical.SnippetStore,
	graph GraphReader,
	planner *iqquery.Planner,
	rootPath string,
	maxSnippetLines int,
) *Assembler

NewAssembler constructs a stateless assembler. rootPath is the absolute repo root used by SnippetStore for path-traversal guards; maxSnippetLines is the upper bound applied when a request does not specify its own. Mirrors the Java EvidencePackAssembler constructor + the CodeIqConfig.getRootPath / getMaxSnippetLines wiring.

func (*Assembler) Assemble

func (a *Assembler) Assemble(ctx context.Context, req Request, meta *ArtifactMetadata) (Pack, error)

Assemble produces an EvidencePack (or an empty one with a note) for the request. Mirrors Java EvidencePackAssembler.assemble:

• same ordering rules (insertion order of lexical results, sorted unique files);
• same degradation-note semantics;
• same provenance shape (filePath, lineStart, lineEnd, kind + prov_* properties).

type Capability

type Capability string

Capability captures the overall analysis fidelity for the primary language of the matched symbols. Mirrors Java CapabilityLevel enum (re-declared here so the evidence package does not depend on the query subpackage just to spell the level out).

const (
	// CapExact — full AST-level analysis available.
	CapExact Capability = "EXACT"
	// CapPartial — grammar-based analysis with structural gaps.
	CapPartial Capability = "PARTIAL"
	// CapLexicalOnly — regex / lexical detection only.
	CapLexicalOnly Capability = "LEXICAL_ONLY"
	// CapUnsupported — no detection at all for this language.
	CapUnsupported Capability = "UNSUPPORTED"
)

type GraphReader

type GraphReader interface {
	FindCallers(ctx context.Context, id string) ([]*model.CodeNode, error)
	FindDependents(ctx context.Context, id string) ([]*model.CodeNode, error)
}

GraphReader is the narrow interface the Assembler needs for cross-reference traversal (callers + dependents). *query.Service satisfies this in production via thin adapter functions; tests pass a hand-rolled fake.

The interface is context-aware on the Go side even though the Java callees are not — keeps the door open for per-call cancellation once a Kuzu request budget lands.

type LexFinder

type LexFinder interface {
	// FindByIdentifier returns lexical matches whose label / fqn fuzzy-match
	// the given symbol name. Empty slice for no matches; error for IO faults.
	FindByIdentifier(ctx context.Context, symbol string) ([]lexical.Result, error)

	// FindByFilePath returns lexical matches whose CodeNode.FilePath equals
	// the given path. Returned in deterministic order.
	FindByFilePath(ctx context.Context, filePath string) ([]lexical.Result, error)
}

LexFinder is the narrow interface the Assembler needs to retrieve lexical matches. *lexical.QueryService satisfies the by-identifier branch; the by-file-path branch is fulfilled by a graph-backed adapter wired at serve time. Defining it locally keeps the package CGo-free for unit tests and lets the MCP layer plug in a richer implementation without breaking this package's surface.

type Pack

type Pack struct {
	MatchedSymbols   []*model.CodeNode     `json:"matched_symbols"`
	RelatedFiles     []string              `json:"related_files"`
	References       []*model.CodeNode     `json:"references"`
	Snippets         []lexical.CodeSnippet `json:"snippets"`
	Provenance       []map[string]any      `json:"provenance"`
	DegradationNotes []string              `json:"degradation_notes"`
	ArtifactMetadata *ArtifactMetadata     `json:"artifact_metadata,omitempty"`
	CapabilityLevel  Capability            `json:"capability_level"`
}

Pack is the runtime-facing evidence pack returned by get_evidence_pack. Field names match the Java record EvidencePack 1:1 so the JSON output is structurally identical (per phase-3 success gate).

Slice fields are guaranteed non-nil after construction via EmptyPack or the Assembler — the MCP envelope contract requires arrays to serialize as `[]` rather than `null`.

func EmptyPack

func EmptyPack(meta *ArtifactMetadata, note string) Pack

EmptyPack returns a pack with no matches and (optionally) a single degradation note. Mirrors EvidencePack.empty. All slice fields are allocated as zero-length (non-nil) so JSON serialization produces `[]`.

type Request

type Request struct {
	Symbol            string `json:"symbol,omitempty"`
	FilePath          string `json:"file_path,omitempty"`
	MaxSnippetLines   *int   `json:"max_snippet_lines,omitempty"`
	IncludeReferences bool   `json:"include_references,omitempty"`
}

Request is the typed input for the assembler. Mirrors Java EvidencePackRequest. At least one of Symbol or FilePath must be non-blank.

func (Request) IsEmpty

func (r Request) IsEmpty() bool

IsEmpty reports whether the request carries neither a symbol nor a file path. Mirrors EvidencePackRequest#isEmpty.