query

type ActivationReranker struct {
	Base   retrieval.Retriever
	Score  ActivationScoreFn
	Alpha  float64 // weight on RRF score, normalized to [0, 1]
	Beta   float64 // weight on activation score, normalized to [0, 1]
	FetchN int     // candidates to fetch from base; rerank operates on these
}

type ActivationRetriever struct {
	DB     *index.DB
	ExpDB  *experiment.DB
	Params experiment.ActivationParams
	// Now is the reference time for activation decay. Nil means time.Now().
	// Tests set a fixed instant so ranking is deterministic rather than
	// depending on sub-millisecond timing between access events and scoring.
	Now func() time.Time
}

type ActivationScoreFn func(ids []string) (map[string]float64, error)

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

type ArcMatch struct {
	ID    string
	Title string
	Score float64
}

type AskConfig struct {
	Query            string
	Budget           int
	MaxItems         int
	SearchLimit      int
	ActivationScores map[string]float64
	// Embedder is optional. When non-nil, raw cosine similarities are computed
	// and used for spreading activation scoring via ActivationFunc.
	Embedder embedding.Embedder
	// ActivationFunc optionally recomputes activation scores after similarities
	// are known. When provided and similarities are available, the returned
	// scores replace ActivationScores for context-pack sorting. This enables
	// spreading activation without coupling query to the experiment package.
	ActivationFunc func(similarities map[string]float64) map[string]float64
	// NoiseFloor is the vault's noise-floor N (the cosine an off-topic query gets
	// to any note). When HasNoiseFloor is true and cosine similarities are
	// available, the top-hit confidence is derived honestly from N and the
	// dispersion below (see internal/noisefloor) instead of the legacy RRF gap.
	NoiseFloor float64
	// NoiseFloorSigma is the vault's note-to-note cosine dispersion σ — the scale
	// for z = (top_cosine − N)/σ. The caller passes a measured, clamped σ; when
	// zero/unset, Ask falls back to the embedder's DefaultDispersion.
	NoiseFloorSigma float64
	HasNoiseFloor   bool
	// VaultLowContrast marks a tight vault (high note-to-note μ) where even
	// correct top hits read "weak". Surfaced on the result so the formatter can
	// explain a weak label rather than let an agent misread it as "irrelevant".
	VaultLowContrast bool
	// SuppressOnNoMatch is the recall floor: when the top hit lands at/below the
	// noise floor (no_match), Ask returns before the context pack and the access
	// fan-out — so an ambient recall on an off-domain prompt neither injects
	// noise nor reinforces the irrelevant note it happened to surface. Opt-in
	// (the recall hook sets it); interactive ask leaves it false.
	SuppressOnNoMatch bool
	// PointersOnly and JSONOutput describe the OUTPUT MODE, which is what
	// decides whether text actually reached the caller. Without them the access
	// ledger inferred delivery from `Target.Body != ""` — that is packHasText,
	// not delivery: under --pointers-only the pack is assembled and withheld at
	// render, so every row was marked delivered for a command that handed over
	// nothing. See AskResult.DeliveredTo.
	PointersOnly bool
	JSONOutput   bool

	// ExcerptTokens caps a per-item excerpt used when a whole note body will not
	// fit the remaining budget. 0 keeps the released all-or-nothing packing,
	// where such an item contributes no text and the pack still counts it —
	// which is how a hook reports "3 items" while delivering only titles.
	ExcerptTokens int

	// ShownBefore names notes whose text this conversation received recently.
	// They stay in the pack as titles (see memory.ContextItem.ShownBefore);
	// their text is not sent again and their access is not a delivered read.
	ShownBefore map[string]bool
}

type AskResult struct {
	Query            string                    `json:"query"`
	TopHits          []retrieval.ScoredResult  `json:"top_hits"`
	Context          *memory.ContextPackResult `json:"context,omitempty"`
	RetrievalMode    string                    `json:"retrieval_mode,omitempty"`
	TopHitConfidence string                    `json:"top_hit_confidence,omitempty"`
	Similarities     map[string]float64        `json:"-"` // raw cosine similarities (not serialized)
	// Noise-floor relevance (populated when HasNoiseFloor + similarities exist).
	// TopHitCosine is the raw cosine of the query against the top hit; NoiseFloor
	// is N; NoiseFloorSigma is σ; RelevanceZ = (TopHitCosine − N)/σ is the label's
	// derivation; RelevanceR = TopHitCosine − N is the raw cosine margin, kept for
	// agents that want the un-normalized number. All surfaced so an agent sees the
	// real values, not just the tier word.
	// NoiseFloorApplied is true when TopHitConfidence was derived from the
	// noise-floor relevance (not the RRF-gap fallback). The formatter uses it to
	// print honest "nothing relevant" / "z above noise floor" labels, and JSON
	// consumers use it to know the floats below are meaningful (rather than
	// zero-because-unset). Because it disambiguates, the floats are NOT omitempty
	// — a MiniLM floor of 0.0 or an exact-boundary z of 0.0 must still serialize
	// rather than silently vanish.
	NoiseFloorApplied bool    `json:"noise_floor_applied,omitempty"`
	TopHitCosine      float64 `json:"top_hit_cosine,omitempty"`
	NoiseFloor        float64 `json:"noise_floor"`
	NoiseFloorSigma   float64 `json:"noise_floor_sigma"`
	RelevanceR        float64 `json:"relevance_r"`
	RelevanceZ        float64 `json:"relevance_z"`
	// LowContrastVault is true when the vault is tight (high note-to-note μ), so
	// a "weak" top hit often means the best available correct match, not
	// "irrelevant". The formatter renders a one-line hint when it's set.
	LowContrastVault bool `json:"low_contrast_vault,omitempty"`
	// VaultNoteCount is how many notes the vault holds, used to decide whether a
	// relevance judgement is meaningful at all. Below noisefloor.MinCalibNotes
	// the floor is a shipped default calibrated for a large corpus, so a "weak"
	// or "nothing relevant" verdict states a measurement the vault is too small
	// to support. Zero means "not measured" and preserves the original
	// behaviour for any caller that doesn't populate it.
	VaultNoteCount int `json:"vault_note_count,omitempty"`

	// Federated, when non-empty, is the cross-vault merged ranking. TopHits
	// stays the OWNING vault's own list: the two answer different questions
	// ("what did this vault rank?" vs "what did the federation rank?") and
	// collapsing them would hide which vault's floor produced the verdict.
	Federated []FederatedHit `json:"federated,omitempty"`
	// Vault names the vault that delivered the body, set only under
	// federation. Without it "here is a note" gives no way to answer "from
	// where?", which is the first question a three-vault agent asks.
	Vault string `json:"vault,omitempty"`
	// FederatedVaults reports every vault that was SEARCHED and what its own
	// floor said, so a reader can tell an empty vault from an unsearched one.
	FederatedVaults []FederatedVaultStatus `json:"federated_vaults,omitempty"`
	// contains filtered or unexported fields
}

type AutoRetrieverResult struct {
	Retriever retrieval.Retriever
	Embedder  embedding.Embedder // nil when keyword-only (no embeddings)
	Cleanup   func()             // always non-nil; safe to defer unconditionally
	// EmbedderErr is WHY the embedder did not load when the vault has
	// embeddings but the model could not start (e.g. an ONNX runtime too old
	// for the binary). nil when hybrid is up, or when the vault simply has no
	// embeddings. Callers must say it out loud: the fallback is keyword-only,
	// and it used to be reported as "this vault has no embeddings".
	EmbedderErr error
}

type BadCitation struct {
	NoteID     string `json:"note_id"`
	SourceID   string `json:"source_id"`
	SourceType string `json:"source_type"`
}

type BankRate struct {
	WindowDays int
	Added      int
	// Total is every note in the vault, so a bank count reads against the size
	// of the thing it is supposedly feeding.
	Total int
}

type BothResult struct {
	Out struct {
		SourceID string          `json:"source_id"`
		Links    []graph.OutLink `json:"links"`
	} `json:"out"`
	In struct {
		TargetID string         `json:"target_id"`
		Links    []graph.InLink `json:"links"`
	} `json:"in"`
}

type CandidateSearcher interface {
	SearchAmong(ctx context.Context, query string, limit int, filters index.SearchFilters, ids []string) ([]retrieval.ScoredResult, int, error)
}

type ColBERTEmbedFunc func(ctx context.Context, text string) ([][]float32, error)

type ColBERTRetriever struct {
	DB           *index.DB
	EmbedColBERT ColBERTEmbedFunc
	Dims         int
}

type ContentDrift struct {
	NoteID      string `json:"note_id"`
	Path        string `json:"path"`
	CurrentHash string `json:"current_hash"` // sha256(file content)
	StoredHash  string `json:"stored_hash"`  // notes.hash from index DB
}

type DoctorAllResult struct {
	Rollup DoctorRollup    `json:"rollup"`
	Vaults []*DoctorResult `json:"vaults"`
	Failed []FailedVault   `json:"failed,omitempty"`
}

type DoctorBackup struct {
	State string `json:"state"`
	// Upstream is the tracked remote branch ("origin/main"), empty when none.
	Upstream string `json:"upstream,omitempty"`
	// Unpushed counts commits the upstream does not have.
	Unpushed int `json:"unpushed"`
	// OldestUnpushedDays is the age of the oldest such commit. The COUNT alone
	// under-reports the risk: 3 commits from this hour and 3 from last month
	// are very different amounts of unrecoverable work.
	OldestUnpushedDays int      `json:"oldest_unpushed_days"`
	Warnings           []string `json:"warnings,omitempty"`
}

type DoctorCallerUse struct {
	Caller     string `json:"caller"`
	Injections int    `json:"injections"`
	Consumed   int    `json:"consumed"`
}

type DoctorEmbeddings struct {
	TotalNotes           int    `json:"total_notes"`
	DenseCount           int    `json:"dense_count"`
	SparseCount          int    `json:"sparse_count"`
	ColBERTCount         int    `json:"colbert_count"`
	Model                string `json:"model"` // "bge-m3", "minilm", "mixed", or "" when no dense embeddings
	SemanticReady        bool   `json:"semantic_ready"`
	HasModalityImbalance bool   `json:"has_modality_imbalance"`
	// MixedModel is non-nil when the vault has notes embedded with more than
	// one model (e.g. mid-upgrade from MiniLM to BGE-M3). Each entry pairs a
	// model name with its row count. When set, Model == "mixed". Surfacing
	// this explicitly prevents the silent-failure shape where doctor reports
	// "bge-m3" while half the rows are still MiniLM. See vaultmind#22.
	MixedModel []DoctorModelBreakdown `json:"mixed_model,omitempty"`
	// RuntimeError is set when the embeddings exist but the runtime that
	// would load their model fails to start — semantic search is down while
	// every count above looks healthy. Populated by the cmd layer.
	RuntimeError string `json:"runtime_error,omitempty"`
}

type DoctorIssues struct {
	DuplicateIDs              int                `json:"duplicate_ids"`
	BrokenReferences          int                `json:"broken_references"`
	MissingRequiredFields     int                `json:"missing_required_fields"`
	MalformedMarkers          int                `json:"malformed_markers"`
	UnresolvedLinks           int                `json:"unresolved_links"`
	NotesMissingIDOrType      int                `json:"notes_missing_id_or_type"`
	UnresolvedLinkDetails     []UnresolvedLink   `json:"unresolved_link_details,omitempty"`
	ObsidianIncompatibleLinks int                `json:"obsidian_incompatible_links"`
	IncompatibleLinkDetails   []IncompatibleLink `json:"incompatible_link_details,omitempty"`
	PathPseudoIDLinks         int                `json:"path_pseudo_id_links"`
	PathPseudoIDDetails       []UnresolvedLink   `json:"path_pseudo_id_details,omitempty"`

	// StaleIndex counts domain notes whose current file content hash
	// differs from the indexer's stored hash — i.e. notes edited AFTER
	// the last `vaultmind index` pass. The operator-visible signal that
	// downstream artifacts (index, embeddings, marker sections) are out
	// of sync with the source. See DetectContentDrift for the detection
	// contract.
	//
	// Replaced an earlier mtime-based detector that produced ~95% false
	// positives on real vaults — git checkouts/branch switches/pulls
	// bump mtime without touching content, and the prior signal could
	// not distinguish "edited" from "VCS-touched". Hash comparison is
	// precise: only actual content edits trigger drift.
	StaleIndex        int            `json:"stale_index"`
	StaleIndexDetails []ContentDrift `json:"stale_index_details,omitempty"`

	// OrphanedEntries counts index rows whose file is gone from disk. Until the
	// next incremental pass sweeps them they answer queries and cannot be
	// opened. Previously invisible: the drift detector `continue`d on the read
	// error, and its own test was named DeletedFileSilent.
	OrphanedEntries      int             `json:"orphaned_entries"`
	OrphanedEntryDetails []OrphanedEntry `json:"orphaned_entry_details,omitempty"`

	// UnindexedFiles counts *.md files on disk with no index row — notes that
	// are in no query result. total_files cannot reveal them: that count comes
	// from the database, so a never-indexed note is not even a mismatch.
	// Symlinks the scanner refused are NOT counted here; see IndexTruth.Skipped.
	UnindexedFiles       int      `json:"unindexed_files"`
	UnindexedFileDetails []string `json:"unindexed_file_details,omitempty"`

	// DuplicateIDDetails names each contested id and every file claiming it.
	// The counter above it used to come from a SQL query against a UNIQUE
	// column, which is structurally zero; this comes from the disk, which is
	// the only place the collision is visible.
	DuplicateIDDetails []DuplicateOnDisk `json:"duplicate_id_details,omitempty"`

	// HookDrift counts Claude Code hook scripts in the project's
	// `.claude/scripts/` whose bytes differ from the embedded canonical
	// in `internal/hookscripts/`. Surfaces "the foundation has rotted"
	// — copies were edited, or the binary was upgraded but old copies
	// linger. Resolution: `vaultmind hooks install --force <project>`.
	// Populated by cmd/doctor.go (project dir comes from there); query
	// layer keeps the type but doesn't import internal/hooks (business
	// layer isolation per ADR-009).
	HookDrift        int      `json:"hook_drift"`
	HookDriftDetails []string `json:"hook_drift_details,omitempty"`

	// LegacyHooksJSON is true when `.claude/hooks.json` exists at the
	// project root. That standalone file is no longer recognized by
	// Claude Code 2.1.129+ — projects with it have silently broken
	// hooks. The fix is to migrate the contents into
	// `.claude/settings.json` under a top-level `hooks` key.
	// Live evidence from companion project dogfood 2026-05-06/07.
	// Populated by cmd/doctor.go (project dir comes from there); query
	// layer keeps the type but doesn't import internal/hooks per
	// ADR-009 business-business isolation.
	LegacyHooksJSON bool `json:"legacy_hooks_json"`
}

type DoctorMemoryUse struct {
	WindowDays      int `json:"window_days"`
	Injections      int `json:"injections"`
	BodiesDelivered int `json:"bodies_delivered"`
	Consumed        int `json:"consumed"`
	NotesBanked     int `json:"notes_banked"`
	VaultNotes      int `json:"vault_notes"`
	// PerCaller is each hook's own verdict. The aggregate hides which of the
	// three injection points is earning its tokens, and they are different bets:
	// session-start, mid-task, and compaction.
	PerCaller []DoctorCallerUse `json:"per_caller,omitempty"`
}

type DoctorMeshIdentity struct {
	// Tier 1 — identity custody (local, keyless).
	KeyPresent      bool `json:"key_present"`
	KeyModeOK       bool `json:"key_mode_ok"`
	KeySizeOK       bool `json:"key_size_ok"`
	SignerReachable bool `json:"signer_reachable"` // INFO — signer is on-demand

	// Tier 2 — binding resolves in the live mesh (authenticated).
	Pinned          bool   `json:"pinned"`
	Authenticated   bool   `json:"authenticated"` // M4 top-level boolean
	NetworkID       string `json:"network_id,omitempty"`
	BindingResolves bool   `json:"binding_resolves"`
	HoldsBindingKey bool   `json:"holds_binding_key"` // selfVerify proof-of-possession
	Status          string `json:"status"`

	// Tier 3 — chat reachability (honest labels).
	DaemonReachable       bool   `json:"daemon_reachable"`
	DaemonMode            string `json:"daemon_mode,omitempty"`
	EnforcementActive     bool   `json:"enforcement_active"` // always false today
	WatcherHeartbeatFresh bool   `json:"watcher_heartbeat_fresh"`
	WatcherHeartbeatAge   int    `json:"watcher_heartbeat_age_secs"`
	// WatcherHeartbeatState is one of the Heartbeat* constants. Fresh==true iff
	// State=="fresh" (both kept for back-compat readers of the JSON).
	WatcherHeartbeatState string `json:"watcher_heartbeat_state"`
	// WatcherHeartbeatPath is WHERE the check looked. Always carried: a verdict
	// about a file whose location is undisclosed cannot be audited, and an
	// undisclosed path is exactly how a wrong directory stayed wrong for months.
	WatcherHeartbeatPath string `json:"watcher_heartbeat_path,omitempty"`
	// WatcherRearmed is false when lastwake postdates lastarm (see checkRearm).
	WatcherRearmed bool `json:"watcher_rearmed"`

	// Warnings each also drive an envelope.AddWarning in the cmd layer.
	Warnings []string `json:"warnings,omitempty"`
}

type DoctorModelBreakdown struct {
	Model string `json:"model"` // "bge-m3", "minilm", or "unknown"
	Count int    `json:"count"`
}

type DoctorResult struct {
	VaultPath         string `json:"vault_path"`
	TotalFiles        int    `json:"total_files"`
	DomainNotes       int    `json:"domain_notes"`
	UnstructuredNotes int    `json:"unstructured_notes"`
	IndexStatus       string `json:"index_status"`
	// IndexStatusReason is set only when IndexStatus is "unknown": what stopped
	// the disk reconciliation from running. Absent otherwise.
	IndexStatusReason string                    `json:"index_status_reason,omitempty"`
	Embeddings        *DoctorEmbeddings         `json:"embeddings,omitempty"`
	Types             map[string]StatusTypeInfo `json:"types,omitempty"`
	ValidationSummary *StatusIssuesSummary      `json:"validation_summary,omitempty"`
	Issues            DoctorIssues              `json:"issues"`

	// MemoryUse is the "is this vault actually used" section: notes surfaced to
	// an agent, how many carried a body, how many were then read, and how many
	// notes were banked. A POINTER with omitempty, on the same principle as
	// ValidationSummary — nil means "not measured" (no usage log on this
	// machine), which must stay distinguishable from a measured zero.
	//
	// It lives on doctor rather than only in `experiment memory` because a
	// number behind a command nobody remembers to run is the same failure as a
	// pointer nobody follows. This is the health hub; this is health.
	MemoryUse *DoctorMemoryUse `json:"memory_use,omitempty"`

	// MeshIdentity is the Contract-B identity-health section. It is a POINTER
	// with omitempty so it is ABSENT from --json unless a mesh signal exists
	// (identity key file present, an anchor exists, a --mesh-* flag passed, or
	// the daemon is reachable). Populated by the cmd layer (paths come from xdg +
	// flags + env). nil ⇒ no mesh substrate, the section is omitted entirely.
	MeshIdentity *DoctorMeshIdentity `json:"mesh_identity,omitempty"`

	// Backup is the "does this vault exist anywhere but this disk" section.
	// Populated by the cmd layer, same arrangement as MeshIdentity. A vault is
	// the one artifact here that cannot be rebuilt, so this is health.
	Backup *DoctorBackup `json:"backup,omitempty"`

	// BadCitations are source_ids edges pointing at types the vault declares
	// non-authoritative — evidence that is not allowed to be evidence. Empty
	// unless the vault opted in by declaring a type non-authoritative.
	BadCitations []BadCitation `json:"bad_citations,omitempty"`
}

type DoctorRollup struct {
	VaultCount int `json:"vault_count"`
	Discovered int `json:"discovered"`
	Diagnosed  int `json:"diagnosed"`
	Failed     int `json:"failed"`
	TotalNotes int `json:"total_notes"`
	// TotalErrors/TotalWarnings are the SURFACED set — the sum of each vault's
	// query.ResultSurfacedIssueCounts, the same axis each per-vault report
	// prints — so the rollup totals reconcile with summing the per-vault
	// reports. They deliberately do NOT count the raw schema-validation
	// aggregate (see TotalRawValidationFindings), which is a different axis.
	TotalErrors   int `json:"total_errors"`
	TotalWarnings int `json:"total_warnings"`
	// TotalRawValidationFindings is the RAW schema-validation aggregate summed
	// across vaults: each vault's ValidationSummary.Errors+Warnings (nil ⇒ 0).
	// It is a DIFFERENT axis from TotalErrors/TotalWarnings — it includes
	// unknown_type / invalid_status findings the per-vault text report never
	// surfaces as per-item lines. Kept under its own distinctly-labeled key so
	// the two axes are explicit rather than collapsed, mirroring how the
	// single-vault envelope keeps validation_summary alongside the surfaced set.
	TotalRawValidationFindings int `json:"total_raw_validation_findings"`

	// VaultsWithIssues lists the paths of vaults with errors or warnings, in the
	// order the vaults were diagnosed (already deterministic — discovery sorts
	// them). Always non-nil so JSON consumers see [] for a clean workspace
	// rather than null.
	VaultsWithIssues []string `json:"vaults_with_issues"`
	// contains filtered or unexported fields
}

type DuplicateOnDisk struct {
	ID    string   `json:"id"`
	Paths []string `json:"paths"`
}

type EmbeddingRetriever struct {
	DB       *index.DB
	Embedder embedding.Embedder
}

type FTSRetriever struct {
	DB *index.DB
}

type FailedVault struct {
	VaultPath string `json:"vault_path"`
	Error     string `json:"error"`
}

type FederatedHit struct {
	retrieval.ScoredResult
	// Vault is the name of the vault this note was ranked highest in. One
	// owner per note: delivery, access recording and plasticity all follow it.
	Vault string `json:"vault"`
	// RRFScore is the fused rank score. Deliberately separate from Score,
	// which stays the ORIGINATING vault's own number — overwriting it would
	// hide the per-vault evidence behind a cross-vault artifact.
	RRFScore float64 `json:"rrf_score"`
	// Ranks records the 1-based rank this note achieved in each vault that
	// returned it, so an amplified hit can show its work.
	Ranks map[string]int `json:"ranks,omitempty"`
}

type FederatedVaultStatus struct {
	Name        string `json:"name"`
	Verdict     string `json:"verdict,omitempty"`
	Contributed bool   `json:"contributed"`
	// NoHits marks a vault the search returned nothing from. It is kept apart
	// from an empty Verdict, which means unmeasured (no embedder): with --type
	// or --tag, a vault holding no such notes is ordinary, not broken.
	NoHits bool `json:"no_hits,omitempty"`
}

type FilteredRetriever struct {
	Base    retrieval.Retriever
	Filters index.SearchFilters
}

type FloorResolver func(dims int) (floor, sigma float64)

type GitStatusResult struct {
	RepoDetected     bool     `json:"repo_detected"`
	Branch           string   `json:"branch"`
	Detached         bool     `json:"detached"`
	MergeInProgress  bool     `json:"merge_in_progress"`
	RebaseInProgress bool     `json:"rebase_in_progress"`
	WorkingTreeClean bool     `json:"working_tree_clean"`
	StagedFiles      []string `json:"staged_files"`
	UnstagedFiles    []string `json:"unstaged_files"`
	UntrackedFiles   []string `json:"untracked_files"`
}

type HybridRetriever struct {
	Retrievers []retrieval.NamedRetriever
	K          int // RRF smoothing constant; zero-value falls back to DefaultRRFK
}

type InResult struct {
	TargetID string         `json:"target_id"`
	Links    []graph.InLink `json:"links"`
}

type IncompatibleLink struct {
	SourceID     string `json:"source_id"`
	SourcePath   string `json:"source_path"`
	TargetRaw    string `json:"target_raw"`
	SuggestedFix string `json:"suggested_fix"`
}

type IndexTruth struct {
	// Drifted: row and file both exist, content differs. The note was edited
	// after the last index pass, so the index, the embeddings and any rendered
	// marker sections describe an older version of it.
	Drifted []ContentDrift `json:"drifted,omitempty"`

	// Orphaned: row exists, file does not. Until the next incremental pass
	// sweeps it, the note answers queries and cannot be opened.
	Orphaned []OrphanedEntry `json:"orphaned,omitempty"`

	// Unindexed: file exists, no row. Invisible to every query, and invisible
	// to total_files too — that count comes from the database, so a
	// never-indexed note does not even show up as a mismatch.
	Unindexed []string `json:"unindexed,omitempty"`

	// Duplicate: one id claimed by two or more files on disk. Not a database
	// question — notes.id is UNIQUE, so at most one of them is ever stored and
	// the SQL check is structurally incapable of seeing the collision. Only the
	// disk can answer it.
	Duplicate []DuplicateOnDisk `json:"duplicate,omitempty"`

	// Skipped: *.md symlinks the scanner refused to follow. Reported so they
	// are distinguishable from Unindexed — a symlink is a deliberate exclusion,
	// and counting it as staleness would make every vault holding one
	// permanently unhealthy. That is how a signal gets ignored, then disabled.
	Skipped []string `json:"skipped,omitempty"`
}

type LinksConfig struct {
	Input      string
	Direction  string // "out", "in", or "both"
	EdgeType   string
	JSONOutput bool
	VaultPath  string
	IndexHash  string
}

type MeasuredCalibration struct {
	NoiseFloor       float64
	NoiseFloorProbes int
	ProbeSetVersion  int
	NTNCosineMu      float64
	NTNCosineSigma   float64
	NTNSampleCount   int
	NoteCount        int
	EmbeddingDims    int
}

type MeshDaemonClient interface {
	FetchRoot(ctx context.Context) (doctorclient.WellKnownRoot, error)
	FetchDirectory(ctx context.Context) ([]byte, error)
	Whoami(ctx context.Context) (bool, string, error)
}

type MeshDoctorInput struct {
	// Tier-1 custody (STAT-ONLY — never read).
	KeyPath    string
	SocketPath string

	// Tier-2 authenticity.
	PinnedRootPub ed25519.PublicKey // nil ⇒ UNPINNED path (never green)
	NetworkID     string
	RegistryBytes []byte // offline registry override (--mesh-registry); else fetched
	// MaxStaleness is the DECLARED hub bound. Zero means undeclared, in which
	// case doctor falls back to its conservative default and says so rather
	// than asserting a refusal date it cannot know.
	MaxStaleness time.Duration
	// RegistryUnread carries a DECLARED registry path that could not be read,
	// so the cmd layer's failure reaches the section instead of vanishing.
	RegistryUnread string
	Slug           string
	Signer         MeshSigner // keyless proof-of-possession

	// Tier-3 reachability.
	Daemon        MeshDaemonClient
	HeartbeatPath string
	// LastwakePath / LastarmPath feed the re-arm check; either empty disables it.
	LastwakePath string
	LastarmPath  string

	// Clock seam.
	Now time.Time
}

type MeshSigner interface {
	Sign(canonicalBytes []byte) ([]byte, error)
}

type MgetResult struct {
	Notes    []index.FullNote `json:"notes"`
	NotFound []string         `json:"not_found"`
	Total    int              `json:"total"`
}

type NeighborEdge struct {
	SourceID   string  `json:"source_id"`
	EdgeType   string  `json:"edge_type"`
	Confidence string  `json:"confidence"`
	Weight     float64 `json:"weight"`
}

type NeighborNode struct {
	ID       string        `json:"id"`
	Distance int           `json:"distance"`
	EdgeFrom *NeighborEdge `json:"edge_from,omitempty"`
}

type NeighborsResult struct {
	StartID         string         `json:"start_id"`
	Nodes           []NeighborNode `json:"nodes"`
	MaxNodesReached bool           `json:"max_nodes_reached"`
}

type NoteGetConfig struct {
	Input           string
	FrontmatterOnly bool
	JSONOutput      bool
	VaultPath       string
}

type NoteGetOutcome struct {
	// NoteID is the RESOLVED id, empty when the input did not resolve.
	NoteID string
	// BodyDelivered is whether note text was actually rendered — false for
	// --frontmatter-only, for misses, and for ambiguous input.
	BodyDelivered bool
}

type OrphanedEntry struct {
	NoteID string `json:"note_id"`
	Path   string `json:"path"`
}

type OutResult struct {
	SourceID string          `json:"source_id"`
	Links    []graph.OutLink `json:"links"`
}

type SearchConfig struct {
	Query      string
	Limit      int
	Offset     int
	TypeFilter string
	TagFilter  string
	JSONOutput bool
	VaultPath  string
}

type SearchResult struct {
	Query  string                   `json:"query"`
	Offset int                      `json:"offset"`
	Limit  int                      `json:"limit"`
	Hits   []retrieval.ScoredResult `json:"hits"`
	Total  int                      `json:"total"`
}

type SelfConfig struct {
	Limit          int
	StaleThreshold time.Duration
	DecayD         float64
	Now            time.Time
}

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

type SparseEmbedFunc func(ctx context.Context, text string) (map[int32]float32, error)

type SparseRetriever struct {
	DB          *index.DB
	EmbedSparse SparseEmbedFunc
}

type StatusIssuesSummary struct {
	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
}

type StatusResult struct {
	VaultPath         string `json:"vault_path"`
	TotalFiles        int    `json:"total_files"`
	DomainNotes       int    `json:"domain_notes"`
	UnstructuredNotes int    `json:"unstructured_notes"`
	IndexStatus       string `json:"index_status"`
	// IndexStatusReason is set only when IndexStatus is "unknown": what stopped
	// the disk reconciliation. Absent otherwise. Mirrors DoctorResult so the two
	// commands report an unavailable check the same way.
	IndexStatusReason string `json:"index_status_reason,omitempty"`
	// IndexStale is meaningful ONLY when IndexStatus is "current" or "stale".
	// A bool cannot express "not checked", so when IndexStatus is "unknown"
	// this field is false for lack of a third state, NOT because the index is
	// fresh. Branch on IndexStatus first.
	IndexStale    bool                      `json:"index_stale"`
	Types         map[string]StatusTypeInfo `json:"types"`
	IssuesSummary StatusIssuesSummary       `json:"issues_summary"`
}

type StatusTypeInfo struct {
	Count    int      `json:"count"`
	Required []string `json:"required"`
	Statuses []string `json:"statuses"`
}

type UnresolvedLink struct {
	SourceID   string `json:"source_id"`
	SourcePath string `json:"source_path"`
	TargetRaw  string `json:"target_raw"`
}

type ValidateIssue struct {
	Path     string `json:"path"`
	ID       string `json:"id"`
	Severity string `json:"severity"`
	Rule     string `json:"rule"`
	Message  string `json:"message"`
	Field    string `json:"field,omitempty"`
	Value    string `json:"value,omitempty"`
	// BrokenRefs carries the reference ids that did not resolve, for
	// RuleBrokenReference. It exists so a caller can group by TARGET rather than
	// by source file: eight broken references across two vaults turned out to be
	// one missing note referenced four times plus four unrelated problems, and
	// the per-file view made that look like eight separate things.
	BrokenRefs []string `json:"broken_refs,omitempty"`
}

type ValidateResult struct {
	FilesChecked int             `json:"files_checked"`
	Valid        int             `json:"valid"`
	Issues       []ValidateIssue `json:"issues"`
}

type VaultSource struct {
	Name      string
	Retriever retrieval.Retriever
	// Verdict is this vault's OWN top-hit confidence, computed against its own
	// noise floor. Empty means unmeasured (no embedder), which is kept rather
	// than assumed irrelevant.
	Verdict string
	// RelevanceZ is this vault's own top-hit z, used only to break RANK TIES
	// between vaults. It is never compared as a score across vaults for
	// ordering — that is precisely what RRF exists to avoid.
	RelevanceZ float64
}