propose

type Hit struct {
	ID, Path, Type, Title, Band string
}

type QuestionRank struct {
	Hits   []RankedHit
	Mode   string
	Window int
}

type QuestionRanker interface {
	RankQuestion(ctx context.Context, question string, includeDrafts bool) (QuestionRank, error)
}

type RankCheck struct {
	Mode        string    `json:"mode,omitempty"`
	Window      int       `json:"window"`
	Before      RankPlace `json:"before"`
	After       RankPlace `json:"after"`
	MeasuredOn  string    `json:"measured_on,omitempty"`
	OutrankedBy []string  `json:"outranked_by,omitempty"`
	// Decision is the hit that chose patch or new: the closest note on the
	// question and the finding. Rank is 1 when that note was found. The zero
	// value means the retrieval named nothing. Before stays the question-only
	// rank stored as rank_before.
	Decision RankPlace `json:"decision,omitempty"`
	// DecisionOn is the text that comparison used.
	DecisionOn string `json:"decision_on,omitempty"`
	// CloseBand is the weakest band the decision treated as close enough.
	CloseBand string `json:"close_band,omitempty"`
}

type RankPlace struct {
	ID   string `json:"id,omitempty"`
	Rank int    `json:"rank"`
	Band string `json:"band,omitempty"`
}

type RankedHit struct {
	ID, Band string
}

type Request struct {
	Question, Finding, CloseBand string
	// GapID, when set, stores closes_gap on the draft. An empty question
	// uses the gap's stored question.
	GapID string
	// DraftsDir is where a draft goes when it must not sit in an import
	// folder. Empty means notes. "." is the vault root.
	DraftsDir      string
	Sources        []string
	JSON           bool
	Now            time.Time // zero means time.Now().UTC()
	ID             string    // accept: the draft id
	Stdout, Stderr io.Writer
	// Embed runs after a note is re-indexed. rel is the note this command
	// just wrote, so the caller can avoid warning about other notes.
	Embed   func(vaultPath, rel string)
	WorkDir string
	// Ranker re-runs the original question after the draft is on disk.
	// Nil skips the check. The command sets it; tests that only place a
	// draft leave it nil so their output stays the placement report.
	Ranker QuestionRanker
	// contains filtered or unexported fields
}

type Retriever interface {
	Closest(ctx context.Context, vaultPath string, db *index.DB, text string) (Hit, bool, error)
}

type Vault struct {
	Path      string
	DB        *index.DB
	Config    *vault.Config
	Reg       *schema.Registry
	IndexHash func() string
}