notes

type Anchor struct {
	Kind   AnchorKind `json:"kind" yaml:"kind"`
	Target string     `json:"target" yaml:"target"`
	// Digest fingerprints the anchored content as of the last review, so a CHANGE is
	// detectable and not merely a deletion. Existence checks catch a rename or a delete;
	// this catches the far more common case where the code still exists and quietly
	// stopped meaning what the note says. Empty when the kind has no content to hash,
	// and empty until the note has been verified once.
	Digest string `json:"digest,omitempty" yaml:"digest,omitempty"`
	// DeclDigest fingerprints only the anchored subject's DECLARATION - see DigestDecl. It
	// grades what Digest detects: when both moved, what the subject IS changed, and the note
	// is very likely wrong; when only Digest moved, the body was edited under an unchanged
	// signature, which is the case that almost never invalidates prose.
	//
	// Empty for a kind with no declaration to speak of (a whole file, a project, a target),
	// and empty on a note stamped before grading existed. Both are ungraded, never a verdict.
	DeclDigest string `json:"decl_digest,omitempty" yaml:"decl_digest,omitempty"`
	// Commit is the revision this anchor was last reviewed against. PROVENANCE ONLY -
	// resolution always runs against the working tree. A pinned revision never breaks,
	// which is precisely why it must never be the anchor: it would go on pointing at
	// correct-looking frozen content long after the thing it described was deleted.
	Commit string `json:"commit,omitempty" yaml:"commit,omitempty"`
}

type AnchorHit struct {
	Note  string `json:"note" yaml:"note"`
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// Pos is the anchor's position in its note. Exported because it is half the documented
	// sort key, so a caller can check the ordering rather than trust it.
	Pos    int        `json:"pos" yaml:"pos"`
	Kind   AnchorKind `json:"kind" yaml:"kind"`
	Target string     `json:"target" yaml:"target"`
	// Matched is the changed thing that produced this hit: a symbol NODE ID for MatchSymbol, a
	// file path for MatchFile and MatchNeighbor. It answers the reader's next question - which of
	// the diff's many paths pulled this note in - which neither the anchor nor the strength
	// can answer alone.
	Matched string        `json:"matched" yaml:"matched"`
	Match   MatchStrength `json:"match" yaml:"match"`
	// Status is the anchor's drift finding carried through untouched: "" when it is clean and
	// StatusUngraded when nothing graded it. This join reports what a diff TOUCHES and never
	// grades, so it can neither invent a verdict nor upgrade an ungraded anchor to clean.
	Status IssueCode `json:"status,omitempty" yaml:"status,omitempty"`
}

type AnchorKind string

type Capture struct {
	// Title is what a reader scans for months later. A capture with a generated title is
	// findable only by the code it touched, which is why the caller is asked for one.
	Title  string
	Source Source
	Tags   []string
	// Entries are in the order they should be read, which is the caller's judgment rather
	// than this package's - a review thread reads by file, a chat log by time.
	Entries []CaptureEntry
}

type CaptureEntry struct {
	// Subject is what the message was about, in the source's own terms - a file path for a
	// review comment. It becomes a file anchor, so a capture is findable from the code.
	Subject string
	// Locator narrows Subject within itself, rendered beside it and never parsed. A hunk
	// index for a review comment; empty when the source has no such notion.
	Locator string
	Author  string
	Body    string
	// Resolved marks a thread the participants closed. Kept because "we discussed this and
	// settled it" and "we discussed this and stopped" are different things to find later.
	Resolved bool
}

type Issue struct {
	Severity Severity  `json:"severity" yaml:"severity"`
	Code     IssueCode `json:"code" yaml:"code"`
	Path     string    `json:"path,omitempty" yaml:"path,omitempty"`
	Note     string    `json:"note,omitempty" yaml:"note,omitempty"`
	Message  string    `json:"message" yaml:"message"`
	Hint     string    `json:"hint,omitempty" yaml:"hint,omitempty"`
}

type IssueCode string

type MatchStrength string

type Note struct {
	// Name is the note's identity in memory: its ID when one is declared, otherwise its
	// path within the store. Never serialized under this key - see ID.
	Name string `json:"name" yaml:"-"`
	// ID is an optional stable identity, and it is what makes a store survive being a
	// vault someone reorganizes.
	//
	// Without it a note is identified by its path, and Obsidian's rename - which helpfully
	// rewrites every [[wikilink]] and knows nothing about magus - silently changes the
	// note's graph ID and dangles every note-kind anchor pointing at it. That is the exact
	// failure this feature argues against everywhere else: an identity that encodes a
	// location. magus stamps one on every note it creates; a hand-written vault note gets
	// path identity until its author adds one.
	ID      string   `json:"id,omitempty" yaml:"id,omitempty"`
	Title   string   `json:"title" yaml:"title"`
	Tags    []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	Anchors []Anchor `json:"anchors" yaml:"anchors"`
	// Source records where the prose came from when a person did not type it here. Nil on a
	// written note, which is the overwhelming majority and the reason it is a pointer: an
	// empty block in every hand-written note's frontmatter would be litter in someone's vault.
	Source *Source `json:"source,omitempty" yaml:"source,omitempty"`
	Body   string  `json:"body,omitempty" yaml:"-"`
	// Modified is the file's modification time, filled in on read. It is observed, not
	// stored, so it cannot disagree with the file it describes.
	Modified time.Time `json:"modified" yaml:"-"`
	// Path is the file this note was read FROM, observed on read for the same reason
	// Modified is: it cannot disagree with the file it describes.
	//
	// It exists because Name cannot answer the question. A note that declares an id is
	// identified by that id, and the id is deliberately independent of where the file
	// sits - that is the whole point of having one. So joining the store dir to Name
	// names a real file only while the two happen to agree, and names a file that does
	// not exist the moment someone renames the note in their vault. Two callers derived
	// it that way and both were wrong: the console showed a reader a path they could not
	// open, and `notes edit` scaffolded a SECOND note beside the one being edited.
	//
	// Empty on a Note that was built rather than read (Scaffold, a new note from stdin),
	// where there is no file yet to have a path.
	Path string `json:"-" yaml:"-"`
}

type ResolvedAnchor struct {
	// Note is the declaring note's Name and Title its heading. Both ride along because a hit
	// is rendered with the diff in hand and the store nowhere near it.
	Note  string `json:"note" yaml:"note"`
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// Pos is the anchor's 0-based position in the note's anchor list, and the second half of
	// the output's sort key. It is carried rather than inferred from slice order: a join whose
	// result depended on the order its input arrived in would report differently for the same
	// workspace depending on who assembled the slice.
	Pos    int    `json:"pos" yaml:"pos"`
	Anchor Anchor `json:"anchor" yaml:"anchor"`
	// File is where a symbol anchor's subject currently lives, workspace-relative, and "" when
	// unknown. SUPPLIED rather than derived: a SCIP symbol key names a package and a
	// descriptor but never a file, and only the graph knows where a symbol sits - which this
	// package deliberately never learns (see internal/graph/knowledge.NoteResolver, whose doc
	// states the one-way dependency). Empty costs the weaker neighbor match and nothing else.
	File string `json:"file,omitempty" yaml:"file,omitempty"`
	// NodeID is the knowledge graph's id for this anchor's subject, and "" when the caller
	// did not mint one. SUPPLIED for the same reason File is: the id spelling belongs to the
	// graph (knowledge.AnchorNodeID), and this package must not learn it.
	//
	// A symbol anchor without one cannot match at all. A diff names its changed symbols by
	// node id while an anchor carries the bare SCIP key, so comparing the two vocabularies
	// directly never matched anything, and the headline case - the note attached to the
	// symbol you just edited - silently reported nothing.
	NodeID string `json:"node_id,omitempty" yaml:"node_id,omitempty"`
	// Status is the IssueCode resolution reported for this anchor, "" when it is clean, and
	// StatusUngraded when nothing graded it.
	Status IssueCode `json:"status,omitempty" yaml:"status,omitempty"`
}

type Resolver interface {
	// Resolves reports whether the given anchor still names a live entity.
	Resolves(ctx context.Context, a Anchor) bool
	// Digest returns the CURRENT fingerprint of the anchored content.
	//
	// An empty digest with a nil error means the kind has nothing to hash: nothing to say,
	// and nothing wrong. A non-nil error means the fingerprint COULD NOT be computed - an
	// unbuilt symbol index, an indexer that reported no enclosing range, an unreadable
	// file.
	//
	// Neither is drift, and that direction is deliberate: a gate that manufactures a change
	// out of its own blind spot gets ignored, and an ignored gate is worse than none. They
	// are separated because they are differently actionable - nothing to hash is the end of
	// the story, while a failure names something a reader can go fix. Collapsing both into
	// "" hid four distinct causes behind one silence.
	Digest(ctx context.Context, a Anchor) (string, error)
	// DeclDigest returns the CURRENT fingerprint of the anchored subject's declaration, or
	// "" when the kind has no declaration to speak of.
	//
	// Errors are NOT reported separately from Digest's: this only ever grades a change
	// Digest already found, so a declaration that cannot be computed degrades to an ungraded
	// finding rather than to a second complaint about the same anchor.
	DeclDigest(ctx context.Context, a Anchor) (string, error)
}

type Scope string

type Severity string

type Source struct {
	Kind SourceKind `json:"kind" yaml:"kind"`
	// Ref identifies the conversation within Kind - a review session id. Opaque here.
	Ref string `json:"ref,omitempty" yaml:"ref,omitempty"`
	// AsOf is the subject's identity at capture time: for a review thread, the digest of the
	// patch the comments were written against. It is what makes a stale capture detectable
	// rather than merely old.
	AsOf string `json:"as_of,omitempty" yaml:"as_of,omitempty"`
	// Captured is when the transcript was taken, which is NOT the note file's mtime: editing
	// a capture's surrounding prose later moves the mtime and must not move this.
	//
	// A stored timestamp, and deliberately not the created/updated fields Note refuses above.
	// Those describe the FILE, which git and the filesystem already describe and which a hand
	// edit immediately falsifies. This describes an event that happened once somewhere else
	// and that nothing in the repository records, so a later edit cannot make it wrong.
	Captured time.Time `json:"captured,omitempty" yaml:"captured,omitempty"`
}

type SourceKind string

type Verification struct {
	Notes  int     `json:"notes" yaml:"notes"`
	Issues []Issue `json:"issues" yaml:"issues"`
}