fusion

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

type BodyReason string

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 GraphEdge struct {
	ID        string          `json:"id"`
	Source    string          `json:"source"`
	Target    string          `json:"target"`
	Predicate string          `json:"predicate"`
	Direction string          `json:"direction"`
	Evidence  []GraphEvidence `json:"evidence,omitempty"`
	Truncated bool            `json:"truncated,omitempty"`
}

type GraphEvidence struct {
	Source     string   `json:"source,omitempty"`
	Timestamp  string   `json:"timestamp,omitempty"`
	Confidence *float64 `json:"confidence,omitempty"`
	Context    string   `json:"context,omitempty"`
}

type GraphFact struct {
	Predicate string          `json:"predicate"`
	Value     json.RawMessage `json:"value"`
	Datatype  string          `json:"datatype,omitempty"`
	Evidence  []GraphEvidence `json:"evidence,omitempty"`
	// Truncated reports the per-fact evidence cap was hit; surviving entries
	// are a prefix of the discovered contributions, and the projection-level
	// Truncated flag is set alongside.
	Truncated bool `json:"truncated,omitempty"`
}

type GraphNode struct {
	Handle string      `json:"handle"`
	Facts  []GraphFact `json:"facts,omitempty"`
	// FactsTruncated reports the fact list was capped; FactsDropped counts the
	// distinct facts cut. Both are omitted when nothing was dropped.
	FactsTruncated bool `json:"facts_truncated,omitempty"`
	FactsDropped   int  `json:"facts_dropped,omitempty"`
}

type GraphProjection struct {
	Nodes        []GraphNode  `json:"nodes"`
	Edges        []GraphEdge  `json:"edges,omitempty"`
	ViewRevision ViewRevision `json:"view_revision"`
	// Truncated reports that ANY node- or edge-level cap below cut content
	// (facts, edges, or evidence), or that an edge walk faulted and left the
	// edge set incomplete — a partial projection never reads as exact.
	Truncated bool `json:"truncated"`
}

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 Hydration struct {
	// Entities are the hydrated entities IN REQUESTED ORDER.
	Entities []*Entity
	// Unhydrated names every requested ID absent from Entities. Nil when complete.
	Unhydrated []Unhydrated
}

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"`
	Code   string     `json:"code,omitempty"`
	Reason string     `json:"reason,omitempty"`
	// BootstrapComplete reports whether the producer finished its initial build in
	// its current process lifetime (ADR-084 D2) — the wire-observable form of the
	// gh#474 cutover window. Absent reads false (fail closed). See
	// graph.IndexStatusResponse.BootstrapComplete for the full contract; fusion
	// mirrors the field verbatim so the direct decode keeps working.
	BootstrapComplete bool `json:"bootstrap_complete"`
	// 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"`
	// FailedCount / FailedReasons / FirstFailureAt relay a producer's BOUNDED failure
	// detail (#613): a degraded producer's outage-vs-poison-entities breakdown reaches
	// the operator through the response envelope fusion already attaches, decoded
	// field-identically from the producer's GRAPH_STATUS envelope (no new endpoint).
	// All additive/omitempty — a producer without failures (e.g. graph-index) carries
	// none, so the wire is unchanged. See graph.IndexStatusResponse for the full
	// contract; fusion mirrors the fields verbatim so the direct decode keeps working.
	// Field ORDER matches graph.IndexStatusResponse (between Lag and StalenessMs) so the
	// gate-projection round-trip stays byte-identical.
	FailedCount    uint64            `json:"failed_count,omitempty"`
	FailedReasons  map[string]uint64 `json:"failed_reasons,omitempty"`
	FirstFailureAt string            `json:"first_failure_at,omitempty"`
	// StalenessMs is the age of the view in milliseconds (ADR-083). 0 carries no
	// information (Ready, or not computable); any computed staleness is >= 1ms.
	// See graph.IndexStatusResponse.StalenessMs for the full presence encoding —
	// fusion mirrors that field verbatim so the direct decode keeps working.
	StalenessMs uint64 `json:"staleness_ms,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"`
	// BodyReason names why Body is absent when a body was requested (WantBody) but
	// could not be loaded — a bounded, closed reason (not_found / error) so a
	// missing body is a partial-result SIGNAL, never a silent empty string
	// (gh#616, #600). It is DISTINCT from Response.Unhydrated: a missing body is a
	// node that exists and ranks, so the reason rides on the node itself rather
	// than the top-level list. A failed body hydration never defers the response
	// or synthesizes a Miss — the node still ships.
	//
	// Omitted from the wire when the body hydrates, so a fully-hydrated response is
	// byte-unchanged for existing consumers.
	BodyReason BodyReason       `json:"body_reason,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"`
	// Rank is this node's 1-based position in RESOLVE order — where the index put it
	// before the engine re-ranked. Present only when the request set IncludeScores.
	//
	// Deliberately not the node's position in the response: that is the array index,
	// which the caller can already count. Ranking reorders (lexical, ontology,
	// salience), so the GAP between resolve rank and response position is the whole
	// signal — it is what makes "why did this come out third?" answerable.
	Rank int `json:"rank,omitempty"`
	// Similarity is the resolve mode's own relevance score, present only when
	// IncludeScores was set AND the mode reports one (semantic does; symbol and prefix
	// do not). Joined to this node by entity ID, never by position.
	//
	// A POINTER so the wire is self-describing: absent means the mode does not score,
	// present means this is the score — including a genuine 0.0, which a bare
	// `float64,omitempty` would erase into indistinguishability from "unavailable".
	// A separate has_similarity bool round-trips correctly in Go but forces every
	// non-Go consumer to learn that an absent key means zero rather than nothing.
	Similarity *float64 `json:"similarity,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"`
	// IncludeScores asks for per-node rank and resolve similarity. Opt-in so the
	// default response is byte-unchanged: scores are debugging and calibration
	// signal, and most callers act on the ordering rather than the numbers.
	IncludeScores bool `json:"include_scores,omitempty"`
}

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"`
	// Graph is the structured graph projection (WantGraph): typed property
	// facts, explicit directed edges, and verbatim evidence, with its own caps
	// and view-revision contract. Its truncation metadata is self-contained —
	// graph-facet truncation NEVER sets the top-level Truncated bit, and a
	// request without the graph want omits the field entirely (the v1 wire
	// shape is unchanged for non-requesting callers).
	Graph  *GraphProjection `json:"graph,omitempty"`
	Misses []Miss           `json:"misses,omitempty"`
	// Unhydrated names requested seeds that did not load — DISTINCT from Misses. A
	// Miss says "the graph was asked and had nothing"; an Unhydrated entry says "we
	// could not read this one", a statement about the read rather than about the
	// world. Neither licenses an absence conclusion (ADR-084), and the
	// all-seeds-unhydrated case deliberately synthesizes NO Miss: claiming a miss
	// there would assert exactly the thing the failed read left unknown.
	//
	// Omitted when everything hydrated, so a complete response is byte-unchanged.
	Unhydrated []Unhydrated `json:"unhydrated,omitempty"`
	// Deferred reports that the engine WITHHELD rather than answered: the empty
	// result is a refusal to look, not a finding.
	//
	// It is an explicit field because the honesty envelope cannot carry the fact.
	// Index describes the GRAPH-INDEX producer, and a defer can be caused by
	// something else entirely — an internal read against graph-ingest or
	// graph-embedding returning the readiness transient while graph-index is
	// perfectly healthy. Re-sampling graph-index then yields a HEALTHY envelope
	// attached to an empty response, so a consumer applying the canonical gate to
	// Index would conclude "healthy, and it found nothing" — precisely the
	// misreading ADR-084 exists to prevent, arrived at from the other side.
	//
	// Check this, not Index, to answer "did I get an answer?".
	Deferred bool `json:"deferred,omitempty"`
	// DeferReason is why, from graph.DeferReason's closed set plus the engine-level
	// causes (an internal dependency's readiness transient). Empty when not deferred.
	DeferReason     string `json:"defer_reason,omitempty"`
	Truncated       bool   `json:"truncated"`
	ContractVersion string `json:"contract_version"`
}

type RetrievalClient interface {
	// Status reports graph readiness for the honesty envelope. Callers gate on
	// HEALTH (graph.EvaluateReadinessGate), not on the Ready coverage bit — which
	// never licensed a not-found conclusion and no longer withholds a response
	// (ADR-084). A quiet or unvouchable feed returns ErrReadinessUnknown; a wiring
	// failure returns a plain error.
	Status(ctx context.Context) (IndexStatus, error)
	// Resolve maps a query to seeds, most relevant first. Both its argument and its
	// result are structs rather than bare values, for the same reason: the NL-only
	// Scope must not force symbol/prefix callers to pass an ignored value, and a
	// future resolve dimension should add a field instead of re-breaking every impl
	// and fake (ADR-071).
	Resolve(ctx context.Context, q ResolveQuery) ([]Seed, error)
	// Entity returns an entity by ID, or (nil, nil) if the read found nothing.
	// "Found nothing" is not proof of absence — see Hydration.
	Entity(ctx context.Context, id string) (*Entity, error)
	// Entities batch-fetches entities by ID and reports what it could not hydrate.
	// A non-nil error means a BACKEND failure, which callers MUST distinguish from
	// an entity that is simply absent.
	//
	// It returns a struct rather than a bare slice for the same reason Resolve takes
	// one (see above): partial hydration needed a second output, and a future one
	// should add a field instead of re-breaking every impl and fake.
	//
	// IMPLEMENTATIONS MUST return Entities in the REQUESTED ORDER. The engine's
	// resolve-rank base is position-derived, so hydration order is the ranking prior,
	// not a presentation detail — a transport that returns "whatever order was
	// convenient" silently reorders results by cache residency (see
	// fusionnats.Client.Entities, which restores order for exactly this reason).
	Entities(ctx context.Context, ids []string) (Hydration, 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 Seed struct {
	// ID is the resolved entity ID.
	ID string
	// Similarity is the resolve mode's own relevance score, when it has one.
	// Semantic resolve reports cosine similarity; symbol and prefix report none.
	Similarity float64
	// HasSimilarity distinguishes "this mode scored it 0" from "this mode does not
	// score". Without it a prefix seed would surface as a perfect zero-relevance
	// match, which is a claim the prefix wire never made.
	HasSimilarity bool
}

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 Unhydrated struct {
	// Handle is the opaque token for the seed that did not load. Never parse or
	// construct it.
	Handle string           `json:"handle"`
	Reason UnhydratedReason `json:"reason"`
}

type UnhydratedReason string

type ViewRevision struct {
	Start uint64 `json:"start"`
	End   uint64 `json:"end"`
}

type Want string