maintain

type Action int

type AuthorBlocker struct {
	Kind  BlockKind
	Text  string
	Route string
}

type AuthorField int

type AuthorOp int

type AuthorPlan struct {
	Request AuthorRequest
	// Root is the root of the pin file. Guard is the observation of the
	// file that the plan read.
	Root  string
	Guard integration.FileGuard
	// Before is the file content; After is the verified candidate, or
	// nil when no candidate exists.
	Before, After []byte
	// Diff is the redacted display diff; Added and Removed count lines.
	Diff           string
	Added, Removed int
	// Old is the entry as the plan read it. New is the entry that After
	// holds, or the requested pin when no candidate exists. Old is zero
	// for a create, and New is zero for a removal.
	Old, New reviews.PinRule
	// Link is the relationship of the entry. It is meaningful only when
	// LinksKnown is true, and it is zero for a create.
	Link       pinfile.Link
	LinksKnown bool
	// EntryApplied and EntryPending are the IDs of the rows that match
	// the entry, in ascending order.
	EntryApplied, EntryPending []int64
	// Proposal and ProposalGuard are the linked row of a linked entry.
	Proposal      *model.Proposal
	ProposalGuard *store.RowGuard
	// OldOwners hold the key of the entry; NewOwners hold the new key.
	// The edited entry is never its own owner.
	OldOwners, NewOwners pinfile.Owners
	// KeyChanged and IdentityChanged compare the old and the new pin of
	// an edit: the link key, and the firing identity of the deliveries.
	KeyChanged, IdentityChanged bool
	// Write is distill.write at plan time; GateErr is its read failure.
	Write   bool
	GateErr error
	// NoOp is true for an edit whose fields all decode to the values of
	// the entry. Such a draft offers no write.
	NoOp bool
	// Issues are the verdicts of CheckDraft.
	Issues []FieldIssue
	// Blockers list every reason that the plan cannot be confirmed.
	Blockers []AuthorBlocker
	// Notes are the plain statements of the review.
	Notes []string
	// History holds the superseded and dismissed rows of the key. They
	// are history, never the source of the pin.
	History []model.Proposal
	// Missing lists the typed regions that name no file or directory
	// under Root yet. It is information, never a blocker.
	Missing []string
	// NewRef binds the new or edited entry in After; nil otherwise.
	NewRef *pinfile.EntryRef
	// Confirmable is true when nothing blocks the write.
	Confirmable bool
}

type AuthorRequest struct {
	Op AuthorOp
	// Ref binds an edit or a removal to the entry that the person saw.
	Ref pinfile.EntryRef
	// Rule and Note are the typed texts.
	Rule, Note string
	// Scope and Regions are the typed scope. Regions holds the rows as
	// the person typed them; the check normalizes them.
	Scope   ScopeChoice
	Regions []string
	// RuleSet, NoteSet, and ScopeSet mark the fields of an edit that the
	// person changed. A create ignores them.
	RuleSet, NoteSet, ScopeSet bool
}

type AuthorResult struct {
	Outcome WriteOutcome
	// Err is the refusal or the write failure. It can hold file paths,
	// so a caller sanitizes it before display.
	Err error
	// NewRef binds the new or edited entry when the outcome is Written.
	NewRef *pinfile.EntryRef
}

type AuthorWriter interface {
	// Write writes after over the file that expect observed. create
	// allows an absent file. An error that wraps ErrStale,
	// pinfile.ErrStale, or pinfile.ErrNotWritable means that nothing was
	// written. Every other error is an error of the write step.
	Write(reg *integration.Registry, root string, expect integration.FileGuard, after []byte, create bool) error
}

type BlockKind int

type ConfidenceReading struct {
	Known  bool
	Reason string
	Tier   confidence.Tier
	Facts  confidence.Facts
	// Living holds the cited findings that are still in the index. They
	// are metadata: the finding bodies are not read.
	//
	// A cited finding leaves the index when it ages out of the mining
	// window, when a later commit reverts its fix, or when a re-mine no
	// longer finds it. The proposal still cites it, but it is not living.
	// The members of the proposal keep its ID, so a caller can name each
	// cited finding that Living does not hold.
	Living []model.Finding
}

type Deps struct {
	// Root is the effective repository root: the root that the index
	// records, else the workspace root.
	Root string
	// Reg is the client registry of the setup engine.
	Reg *integration.Registry
	// Reader reads the ledger and the evidence. NewPlan accepts a
	// read-only store. Commit plans again through it.
	Reader *store.Store
	// Ledger writes the ledger. Nil uses Reader, which must then be
	// writable.
	Ledger LedgerWriter
	// Files writes the pin file. Nil uses the guarded pinfile write.
	Files FileWriter
	// Author writes the pin file of an authoring commit. Nil uses the
	// guarded pinfile write. It is separate from Files, because an
	// authoring commit can create the file and restores nothing.
	Author AuthorWriter
	// ForeignRoot is set by the caller when Root is not the root of this
	// workspace (P4-16). The caller owns the root rule. An authoring plan
	// then carries a blocker with its text, and CommitAuthor refuses
	// with it. The maintenance planner ignores it.
	ForeignRoot error
	// Probe is a fresh observation of the index. A retarget needs a
	// ready index, because the scope advice reads its history.
	Probe workspace.IndexProbe
	// Now reads the clock. Nil reads the system clock.
	Now func() time.Time
}

type ExposureReading struct {
	Known    bool
	Reason   string
	Exposure reviews.Exposure
	// Fired is true when the firing log holds a delivery of the identity.
	Fired bool
}

type FieldIssue struct {
	Field AuthorField
	// Index is the 0-based row of a region issue. It is -1 for an issue
	// of a whole field.
	Index int
	Text  string
	// Info marks a line that explains a normalization of a region, such
	// as a removed trailing "/". It never blocks the draft.
	Info bool
}

type FileWriter interface {
	// Replace writes after over the file that expect observed. An error
	// that wraps pinfile.ErrStale means that the file changed first.
	Replace(reg *integration.Registry, root string, expect integration.FileGuard, after []byte) error
	// Restore writes original back, but only while the file holds the
	// bytes with the SHA-256 written.
	Restore(reg *integration.Registry, root string, written [32]byte, original []byte) error
}

type Inspection struct {
	// Doc is the read of the pin file; nil when DocErr is set.
	Doc *pinfile.Document
	// DocErr is a read failure of the file itself: a path that is not a
	// regular file, or an I/O error. The listing is then empty.
	DocErr error
	// Links is the classification of the entries against the ledger. It
	// is nil when the ledger cannot be read.
	Links *pinfile.Links
	// LinkErr says why no link is known: pinfile.ErrUnreadable for a pin
	// file that cannot be read, or an error that wraps ErrNoLedger. It is
	// nil when every link is known.
	LinkErr error
	// Pins holds one item per Doc.Entries item, in file order.
	Pins []Pin
	// Superseded is the read-only history of pruned proposals, in
	// ascending ID order.
	Superseded []model.Proposal
	// Clusters groups the pins whose wording restates each other, by
	// index in Pins. Only present, linked pins take part.
	Clusters [][]int
	// LedgerErr is the read failure of the ledger; ReadingsErr joins the
	// read failures of the readings.
	LedgerErr, ReadingsErr error
	// Index is the index probe that the readings used.
	Index workspace.IndexProbe
	// At is the time that the readings used.
	At time.Time
}

type ItemStatus int

type LedgerWriter interface {
	ProposalsWithIDs(ids []int64) ([]model.Proposal, error)
	RetargetApplied(changes []store.RegionChange) error
	SupersedeExact(guards []store.RowGuard) error
}

type OutcomeReading struct {
	Known   bool
	Reason  string
	Reading outcome.Reading
}

type Pin struct {
	Entry    pinfile.Entry
	Link     pinfile.EntryLink
	Readings Readings
}

type Plan struct {
	Action  Action
	Request Request
	Items   []PlanItem
	// Change is the verified candidate file of the ready items; nil when
	// no item is ready.
	Change *pinfile.Change
	// Retarget and Supersede are the guarded ledger changes of the ready
	// items, in item order.
	Retarget  []store.RegionChange
	Supersede []store.RowGuard
	// Write is distill.write at plan time; GateErr is its read failure.
	Write   bool
	GateErr error
	// FileBlock is the reason the pin file cannot be edited or replaced.
	// It can name a path, so a caller sanitizes it before display.
	FileBlock string
	// Confirmable is true when every item is ready, the gate is on, and
	// the file can be replaced. Only such a plan can be committed.
	Confirmable bool
	// Blocked lists the reasons that the plan cannot be confirmed. One
	// reason can quote FileBlock, so a caller sanitizes them.
	Blocked []string
	// Evidence binds a retarget to its inputs: the living findings, the
	// trigger fields, the computed regions, and the index run.
	Evidence [32]byte
	// File is the observation of the pin file that the plan read.
	File integration.FileGuard
	// Notes are plain statements for the preview.
	Notes     []string
	PlannedAt time.Time
	// Recovery is set on a plan from PlanRecovery. Such a plan completes
	// the ledger only and commits through CommitRecovery.
	Recovery *Recovery
}

type PlanItem struct {
	// Ref is the reviewed binding of the entry.
	Ref pinfile.EntryRef
	// Pin is the entry as the plan read it, with its link. A plan fills
	// only the scope and trigger readings; the other readings stay
	// unknown. Pin is zero when the entry changed since the review.
	Pin    Pin
	Status ItemStatus
	// Reason explains a blocked or no-op item. For a ready prune it says
	// whether a retained alternative is established. It can quote a
	// pinfile error with a rule or a path from the file, so a caller
	// sanitizes it before display.
	Reason string
	// From is the live region set; To is the computed set of a retarget.
	// Nil is repository-wide. To is meaningful only for a ready or a
	// no-op retarget. Both hold paths from the file or the model, so a
	// caller sanitizes them before display.
	From, To []string
	// Broader and RepoWide label a retarget that widens the scope.
	Broader, RepoWide bool
	// Facts explain what supports the computed scope. They hold file and
	// model data, so a caller sanitizes them before display.
	Facts []string
	// Kept lists the similar pins that stay in the file and stay linked
	// after a prune. Similar wording does not prove the same coverage.
	// Their entries hold file text, so a caller sanitizes it.
	Kept []Pin
	// Rows are the applied proposals linked to the entry. Their rule and
	// note come from the ledger, so a caller sanitizes them.
	Rows []model.Proposal
}

type Readings struct {
	Confidence ConfidenceReading
	Scope      ScopeReading
	Trigger    TriggerReading
	Outcome    OutcomeReading
	Exposure   ExposureReading
	// Similar holds the indexes in Inspection.Pins of the other pins of
	// the same redundancy cluster. Similar wording does not prove the
	// same coverage, so a similar pin is no reason to prune. A prune
	// plan decides its items first and then only lists the similar pins
	// that stay (PlanItem.Kept).
	Similar []int
}

type Recovery struct {
	Action  Action
	Request Request
	// Items are the reviewed items, in the order of the edits and the
	// ledger changes.
	Items []PlanItem
	// Written is the SHA-256 of the bytes that the session wrote.
	Written [32]byte
	// Before and After are the reviewed file contents. They hold file
	// data, so a caller sanitizes them before display.
	Before, After []byte
	// Edits and NewKeys are the reviewed file edits and their target keys.
	Edits   []pinfile.Edit
	NewKeys []reviews.PinKey
	// Retarget and Supersede are the ledger changes that did not complete.
	Retarget  []store.RegionChange
	Supersede []store.RowGuard
}

type Request struct {
	Action Action
	// Refs are the reviewed entries, in selection order.
	Refs []pinfile.EntryRef
	// Cursor is true when no entry was marked and the request names the
	// cursor row. The preview then says so.
	Cursor bool
}

type Result struct {
	Action Action
	// FileWritten is true when the pin file holds the new bytes, or when
	// a failed write could not be checked. It never claims an untouched
	// file that was not observed.
	FileWritten bool
	FileErr     error
	// LedgerDone is true when every planned row holds its target values.
	LedgerDone bool
	LedgerErr  error
	// Restored is true only when the restore write succeeded.
	Restored   bool
	RestoreErr error
	// RestoreRefused says why no restore ran over the file of another
	// writer.
	RestoreRefused string
	// Observed holds the planned rows as read again after a failure;
	// ObservedErr is the failure of that read.
	Observed    []model.Proposal
	ObservedErr error
	// Moved lists the proposals that this commit changed, ascending.
	Moved []int64
	// Recovery is the session proof of a partial operation. It is set
	// when the commit neither restored the file nor completed the ledger,
	// and the session saw its own write land. A write that could not be
	// checked offers no recovery, because a prune recovery then rests on
	// a bare absence (D-13).
	Recovery *Recovery
	// Note is one plain sentence about the outcome. It names the step
	// that failed: the file write or the ledger update.
	Note string
}

type ScopeChoice int

type ScopeReading struct {
	Known  bool
	Reason string
	Advice distill.ScopeAdvice
}

type StaleError struct {
	Differences []string
}

type TriggerReading struct {
	Known  bool
	Reason string
	// Open is true when an extraction can ask the question.
	Open  bool
	State distill.TriggerReason
	// Blocked holds the confirmed triggers that the region set does not
	// deliver. They come from the scope reading, so they are empty while
	// that reading is unknown.
	Blocked []distill.TriggerFact
}

type WriteOutcome int