fusion

type BM25Args struct {
	Query string `json:"query"`
	Limit int    `json:"limit,omitempty"`
}

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

type Budget struct {
	MaxNodes int `json:"max_nodes,omitempty"`
	MaxBytes int `json:"max_bytes,omitempty"`
}

type Direction int

type Edge struct {
	Predicate string
	Target    string
}

type EdgeSpec struct {
	Predicate    string
	OutgoingRole string
	IncomingRole string  // "" to skip the reverse direction
	Facets       []Facet // nil/empty = all facets; else only the named facets
}

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

type Entity struct {
	ID      string
	Triples []message.Triple
}

type EntityStateArgs struct {
	EntityIDs []string `json:"entity_ids"`
}

type Evidence struct {
	// EntityID is the graph entity this evidence refers to. Required.
	EntityID string `json:"entity_id"`

	// Tier is the retrieval tier that surfaced this hit: "0" (rules /
	// predicate queries), "1" (BM25), or "2" (neural — deferred to
	// Phase 2). Operators may use it to filter evidence by retrieval
	// method.
	Tier string `json:"tier"`

	// Source is the retrieval source within the tier — e.g.
	// "classifier", "predicate_walk", "bm25_index". Required.
	Source string `json:"source"`

	// Score is the within-tier ranking score (higher = better).
	// Cross-tier comparison is not meaningful in Phase 1 (per-tier
	// ordering + recency tie-break); Phase 2 may add a learned ranker.
	Score float64 `json:"score,omitempty"`

	// SnippetText is a short inline preview (prompt-injection
	// friendly). Omit when the evidence has no readable preview.
	SnippetText string `json:"snippet_text,omitempty"`

	// ObjectStoreRef is the ObjectStore key for the full body when
	// the evidence has bulk content. Empty when the evidence is fully
	// expressed in the EntityID + triples on the graph.
	ObjectStoreRef string `json:"objectstore_ref,omitempty"`
}

type Facet string

type FuseOptions struct {
	// MaxParallelism caps concurrent sub-query execution. 0 uses DefaultMaxParallelism.
	MaxParallelism int

	// MaxResultsPerSubquery caps result count per sub-query before
	// ranking + budget enforcement run. 0 uses DefaultMaxResultsPerSubquery.
	MaxResultsPerSubquery int

	// BudgetTokens is the estimated-token budget for the returned
	// evidence set. 0 uses DefaultBudgetTokens.
	BudgetTokens int
}

type FuseResult struct {
	// Evidence is the kept evidence set after dedup, sort, and budget
	// enforcement. May be empty (degraded path or zero queries).
	Evidence []Evidence

	// Degraded flags incomplete fan-out — e.g. one or more sub-query
	// errors or a timeout. The caller should surface this to operators
	// or downstream LLM consumers as low-confidence input.
	Degraded bool

	// DegradedReason explains why Degraded is set. Multiple per-sub-query
	// failures are joined with "; ".
	DegradedReason string

	// BudgetTokensUsed is the estimated token cost of the kept evidence
	// array after budget enforcement. Useful for operator observability
	// and tuning budget parameters.
	BudgetTokensUsed int
}

type GraphQueryClient interface {
	EntityState(ctx context.Context, args EntityStateArgs, tier, source string, limit int) ([]Evidence, error)
	PredicateWalk(ctx context.Context, args PredicateWalkArgs, tier, source string, limit int) ([]Evidence, error)
	TemporalRange(ctx context.Context, args TemporalRangeArgs, tier, source string, limit int) ([]Evidence, error)
	BM25(ctx context.Context, args BM25Args, tier, source string, limit int) ([]Evidence, error)
}

type Impact struct {
	Nodes     int  `json:"nodes"`
	Files     int  `json:"files"`
	Truncated bool `json:"truncated"`
}

type IndexState string

type IndexStatus struct {
	Ready bool       `json:"ready"`
	State IndexState `json:"state"`
	// IndexedRevision / TargetRevision / Lag expose the exact revision-lag so a
	// caller that knows its own target revision can gate on IndexedRevision >=
	// myRev rather than the coarse global Ready bool (ADR-066).
	IndexedRevision uint64 `json:"indexed_revision,omitempty"`
	TargetRevision  uint64 `json:"target_revision,omitempty"`
	Lag             uint64 `json:"lag,omitempty"`
	Phase           string `json:"phase,omitempty"`
	Revision        string `json:"revision,omitempty"`
	LastSynced      string `json:"last_synced,omitempty"`
}

type Lens interface {
	// Name identifies the lens (e.g. "code", "docs"). Used as the registry key.
	Name() string

	// ResolveMode picks how to turn the raw query into seeds.
	ResolveMode(query string) ResolveMode

	// Edges are the relationship predicates to expand around each seed.
	Edges() []EdgeSpec

	// Label is the entity's human name (e.g. from dc.terms.title).
	Label(e *Entity) string

	// Kind is a short human kind for the entity (e.g. "function", "doc").
	Kind(e *Entity) string

	// Location returns the entity's domain-general place (file path or URL,
	// optional section fragment, optional line range).
	Location(e *Entity) Locator

	// Hydrate returns a HANDLE to the entity's verbatim body — never the bytes
	// themselves and never a filesystem read. The engine resolves the handle's
	// StorageInstance to a registered storage.Store and reads the body with
	// Get(Key) (ADR-062 hydration contract, increment 4). Returning a handle
	// (not a string) is what makes fusion deployment-independent: a remote
	// caller of a standalone fusion service (semsource ADR-0006) cannot read the
	// service's worktree, so bodies must be addressable through a backend-
	// agnostic store. Return (nil, nil) when the entity has no verbatim body.
	//
	// Error policy (engine contract): hydration is best-effort. A non-nil error
	// DEGRADES the response — the engine omits that node's body and continues —
	// it does NOT fail the fuse. This mirrors the engine's degrade-don't-fail
	// posture for sub-query failures (see Fuse). Lenses should return an error
	// only for genuine retrieval faults, not for "no body" (use (nil, nil)).
	Hydrate(ctx context.Context, e *Entity) (*message.StorageReference, error)
}

type Locator struct {
	Path     string // file path or URL
	Fragment string // section / anchor (docs)
	Lines    [2]int // line range (code); zero value means line-less
}

type MapStoreResolver map[string]storage.Store

type Miss struct {
	Query      string   `json:"query"`
	DidYouMean []string `json:"did_you_mean,omitempty"`
}

type Node struct {
	Name     string `json:"name"`
	Kind     string `json:"kind,omitempty"`
	Path     string `json:"path,omitempty"`
	Fragment string `json:"fragment,omitempty"`
	// Lines is [start,end] for code, nil for line-less domains (docs) — a slice
	// so omitempty actually omits it rather than emitting a spurious [0,0].
	Lines     []int            `json:"lines,omitempty"`
	Body      string           `json:"body,omitempty"`
	Relations map[string][]Ref `json:"relations,omitempty"`
	// Class is the BFO/CCO class IRI (provenance/debug; the agent ignores it).
	Class string `json:"class,omitempty"`
	// Handle is an opaque continuation token (internally the entity ID). Not an
	// addressing scheme: never parse or construct it.
	Handle string `json:"handle,omitempty"`
}

type Path struct {
	Names     []string `json:"names"`
	Truncated bool     `json:"truncated,omitempty"`
}

type PredicateWalkArgs struct {
	Seeds      []string `json:"seeds"`
	Predicates []string `json:"predicates,omitempty"`
	MaxHops    int      `json:"max_hops,omitempty"`
}

type Provenance string

type RankSignals interface {
	// ClassSpecificity scores how specific an ontology class IRI is: more
	// specific (deeper in the BFO/CCO subclass tree) = higher; 0 for an
	// unknown or unset class. A deeper class carries more information, so within
	// the same resolve/lexical tier a precisely-typed entity reorders ahead of a
	// vaguely-typed peer.
	ClassSpecificity(classIRI string) float64

	// PredicateSalience returns a predicate's stored salience weight, SIGNED:
	// positive boosts (an entity carrying the fact reorders ahead), negative
	// demotes (it reorders behind), 0 is neutral. Production reads vocabulary
	// PredicateMetadata.Weight. A negative weight is how a consumer down-ranks
	// structurally-identifiable noise (tests, generated code, mocks) that carries
	// the same boosted predicates as the real thing — additive boosting alone
	// cannot separate them (gh#441). The engine folds an entity's strongest boost
	// and strongest demotion together (see entitySalience), so a demotion is a
	// bounded secondary reordering, never an exclusion.
	PredicateSalience(predicate string) float64
}

type Ref struct {
	Name     string `json:"name"`
	Path     string `json:"path,omitempty"`
	Fragment string `json:"fragment,omitempty"`
	Line     int    `json:"line,omitempty"`
}

type Request struct {
	Query string `json:"query"`
	Want  []Want `json:"want,omitempty"`
	// Scope optionally constrains NL seed resolution to entities whose ID
	// matches at least one of these dot-delimited entity-ID prefixes
	// (OR-matched). Empty/absent means no filter — today's behavior. It lets a
	// lens instance over a shared embedding index retrieve only its own domain
	// so a smaller domain is not diluted by a larger co-resident one (ADR-071).
	// A list, not a scalar: one domain often spans several prefixes (semsource
	// "all code" = golang/python/ts/svelte). NL-only; ignored by symbol/prefix
	// resolve modes.
	Scope  []string `json:"scope,omitempty"`
	Budget Budget   `json:"budget,omitzero"`
}

type ResolveMode string

type ResolveQuery struct {
	Query string
	Mode  ResolveMode
	Scope []string
	Limit int
}

type Response struct {
	Index           IndexStatus `json:"index"`
	Provenance      Provenance  `json:"provenance"`
	Nodes           []Node      `json:"nodes,omitempty"`
	Paths           []Path      `json:"paths,omitempty"`
	Impact          *Impact     `json:"impact,omitempty"`
	Misses          []Miss      `json:"misses,omitempty"`
	Truncated       bool        `json:"truncated"`
	ContractVersion string      `json:"contract_version"`
}

type RetrievalClient interface {
	// Status reports graph readiness. The honesty envelope's Ready flag is
	// load-bearing — only Ready permits a not-found conclusion.
	Status(ctx context.Context) (IndexStatus, error)
	// Resolve maps a query to seed entity IDs, most relevant first. Its
	// arguments are a struct rather than positional so the NL-only Scope does
	// not force symbol/prefix callers to pass an ignored value, and so a future
	// resolve dimension adds a field instead of re-breaking every impl and fake
	// (ADR-071).
	Resolve(ctx context.Context, q ResolveQuery) ([]string, error)
	// Entity returns an entity by ID, or (nil, nil) if absent.
	Entity(ctx context.Context, id string) (*Entity, error)
	// Entities batch-fetches entities by ID. Absent IDs are omitted; a non-nil
	// error means a BACKEND failure, which callers MUST distinguish from genuine
	// absence (an empty result on a Ready graph is a miss, not a fault).
	Entities(ctx context.Context, ids []string) ([]*Entity, error)
	// Neighbors returns edges from id along the given predicates in a direction.
	Neighbors(ctx context.Context, id string, predicates []string, dir Direction) ([]Edge, error)
	// Names suggests entity display names near a query (for a miss's did_you_mean).
	Names(ctx context.Context, query string, limit int) ([]string, error)
}

type StoreResolver interface {
	// Store returns the store registered under instance, and whether one exists.
	Store(instance string) (storage.Store, bool)
}

type SubQuery struct {
	Type   SubQueryType `json:"type"`
	Tier   string       `json:"tier"`   // "0" (predicate) or "1" (BM25)
	Source string       `json:"source"` // e.g. "walk_seeds:drone-001"; surfaces on Evidence.Source

	// Per-type args. Exactly one is populated based on Type — the
	// executor switch enforces. Optional fields allow tests + future
	// templates to omit per-type primitives that don't apply.
	EntityState   *EntityStateArgs   `json:"entity_state,omitempty"`
	PredicateWalk *PredicateWalkArgs `json:"predicate_walk,omitempty"`
	TemporalRange *TemporalRangeArgs `json:"temporal_range,omitempty"`
	BM25          *BM25Args          `json:"bm25,omitempty"`
}

type SubQueryType string

type TemporalRangeArgs struct {
	// Start / End are RFC3339 strings; timezone handling stays in the
	// executor where the upstream graph-index-temporal surface lives.
	Start string `json:"start"`
	End   string `json:"end"`
	Topic string `json:"topic,omitempty"`
}

type Want string