model

type Author struct {
	OpenAlexID string
	Name       string
	ORCID      *string
	Position   int // 0-based; first author is 0
}

type Edge struct {
	FromWork string // the citing work — the newer one
	ToWork   string // the cited work

	// Context is the sentence around the citation marker in the citing paper.
	// Nobody provides this for free; it is what makes retrieval better than
	// keyword search over abstracts.
	Context string

	// Intent and Section are extracted, therefore fallible — unlike the edge
	// itself. Confidence exists so a caller can tell one from the other.
	Intent  Intent
	Section Section

	// Confidence in the Intent and Section extraction, 0..1. nil means nothing
	// has tried yet, which is different from having tried and scored zero.
	Confidence *float64
}

type ExpansionResult struct {
	SeedID string

	Hydrated   int // works fetched during this run
	Stubs      int // works left unhydrated on the frontier
	Edges      int // citation edges recorded during this run
	Unresolved int // IDs OpenAlex had no record of

	// Merged counts works OpenAlex holds twice — a second record under a new
	// ID with the same DOI — folded into the record already in the library
	// rather than added as a duplicate node (hard rule 6).
	Merged int

	// Skipped counts works left as stubs because their batch failed for a
	// reason that may not recur. §7: one bad batch must not kill a 500-node
	// run. They stay on the frontier, so the next run picks them up.
	Skipped int

	// DeadEnds counts hydrated works that came back with no reference list, so
	// the graph cannot continue through them. Reporting it is not optional
	// polish: in arts and humanities it is the great majority of the frontier
	// (D12), and a user who is not told will read a graph that stops after one
	// hop as a broken tool rather than as missing data.
	DeadEnds int

	MaxDepthReached int
	StoppedBecause  StopReason
	Duration        time.Duration
}

type FrontierItem struct {
	OpenAlexID string
	Depth      int

	// InDegree is how many works already in this library cite this one.
	//
	// It is the ranking signal that makes expansion best-first rather than
	// breadth-first, and it is free: computed from edges already stored, with no
	// API call. A work cited by five papers the user already has is a better use
	// of the budget than one cited by a single paper, whatever the global count
	// says about either.
	InDegree int
}

type HydratedWork struct {
	Work
	ReferencedWorks []string
}

type Intent string

type OAStatus string

type Section string

type Source string

type StopReason string

type Work struct {
	// OpenAlexID is the primary key and the deduplication key (hard rule 6).
	// Bare form, "W2741809807" — not the https://openalex.org/... URL OpenAlex
	// returns. Normalising that is internal/identity's job, and the store should
	// reject anything else rather than silently create a second node for the same
	// paper under a different spelling.
	OpenAlexID string

	// External identifiers. All absent on a stub, and often absent afterwards:
	// roughly a third of hydrated works have no DOI.
	DOI     *string
	ArXivID *string
	PMID    *string

	// Bibliographic metadata. All zero on a stub.
	Title    *string
	Abstract string
	Year     *int
	Venue    string
	Type     WorkType

	// CitedByCount is OpenAlex's global count — how often the whole world cites
	// this work. It is not the in-graph in-degree, which is computed from cites
	// and is the better ranking signal because it is relative to this library.
	// See FrontierItem.InDegree.
	CitedByCount int

	// Open access. OAURL is the only sanctioned route to a full text (hard rule 1).
	OAStatus OAStatus
	OAURL    *string

	// Full text on disk. Both nil until M3.
	PDFSHA256  *string
	PDFLicense *string

	// State flags, all persisted so that expansion resumes from the frontier
	// rather than starting over.
	Hydrated    bool // metadata fetched
	FetchedRefs bool // this work's own references have been recorded
	Unresolved  bool // OpenAlex has no record of it — stop retrying

	// Provenance.
	Depth   *int // hops from the nearest seed; nil until the work is first reached
	IsSeed  bool
	Source  Source
	AddedAt time.Time

	// Authors comes from the authorship join and is populated only when a caller
	// asks for it, so the nil-versus-empty distinction carries meaning here the
	// same way it does for the pointer fields above:
	//
	//	nil            not loaded — this query did not ask for authors
	//	[]Author{}     loaded, and the work genuinely has none
	//
	// Use AuthorsLoaded rather than len() to tell them apart. A byline hidden on
	// len(Authors) == 0 disappears for every work whose authors were simply never
	// queried.
	Authors []Author
}

type WorkType string