thread

type Reply struct {
	Author   string    `yaml:"author"`
	At       time.Time `yaml:"at"`
	Body     string    `yaml:"body"`
	Mentions []string  `yaml:"mentions,omitempty"`
}

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

type Store interface {
	// List returns all threads for a spec, in deterministic order.
	List(specID string) ([]Thread, error)
	// Create appends a new open thread anchored to a section and returns it.
	// mentions are explicit handles from the caller (e.g. a --to flag); they
	// are unioned with @handles parsed from question. Pass nil when there are
	// no explicit handles — inline mentions are still parsed either way.
	Create(specID, section, author, question string, mentions []string) (Thread, error)
	// Reply appends a reply to an existing thread. mentions are unioned with
	// @handles parsed from body, same as Create.
	Reply(specID, threadID, author, body string, mentions []string) (Thread, error)
	// Resolve marks a thread resolved. Resolving an already-resolved thread
	// is a no-op that returns the thread unchanged.
	Resolve(specID, threadID, by string) (Thread, error)
	// Reopen undoes a resolution.
	Reopen(specID, threadID string) (Thread, error)
}

type Thread struct {
	// ID is a short, stable, content-independent identifier (e.g. "T-7f3a").
	// It never changes, so replies and resolves never collide on renumbering.
	ID string `yaml:"id"`

	// Section is the markdown section slug the thread is anchored to.
	// This is the only anchor in v1 — a thread is never orphaned by line shifts.
	Section string `yaml:"section"`

	// Status is open or resolved.
	Status string `yaml:"status"`

	// Author is the handle/name of whoever asked the question.
	Author string `yaml:"author"`

	// Created is when the question was asked (UTC).
	Created time.Time `yaml:"created"`

	// Question is the opening message.
	Question string `yaml:"question"`

	// Replies are appended in chronological order.
	Replies []Reply `yaml:"replies,omitempty"`

	// ResolvedBy and ResolvedAt are set when the thread is resolved.
	ResolvedBy string     `yaml:"resolved_by,omitempty"`
	ResolvedAt *time.Time `yaml:"resolved_at,omitempty"`

	// Mentions are the handles addressed by the question, in first-seen order.
	// Derived from the body (and any explicit --to handles) at write time;
	// never hand-edited.
	Mentions []string `yaml:"mentions,omitempty"`

	// Quote is the verbatim text span the thread refers to within Section.
	// Optional. When the text no longer appears in the section, the thread
	// degrades to a section-level anchor — it is never orphaned.
	Quote string `yaml:"quote,omitempty"`

	// QuotePrefix is a short run of text immediately before Quote, used to
	// disambiguate when Quote appears more than once in the section.
	QuotePrefix string `yaml:"quote_prefix,omitempty"`
}