attest

type Area struct {
	Page     int  `json:"page"`
	BBox     Rect `json:"bbox"`
	Rotation int  `json:"rotation,omitempty"`
	DPI      int  `json:"dpi,omitempty"`
}

type Artifact struct {
	MIME string
	Body []byte

	// Digest is the producer's digest of what it just rendered, computed the
	// same way it computed Unit.Evidence when it read the unit.
	//
	// Computed by the producer rather than by attest over Body, because the
	// canonical form is not always the served form: an audio window is digested
	// as decoded samples, since re-encoding is not byte-reproducible, but what
	// gets served to a browser is a container with a header. The producer is the
	// only party that knows the difference.
	//
	// This does not defend against a lying producer, and is not meant to. It
	// catches the thing that actually happens: a renderer upgrade that silently
	// produces different pixels at the same nominal dpi, months after the
	// verdicts were recorded.
	Digest string
}

type AsSeenEvidence interface {
	AsSeen(ctx context.Context, asset Asset, u Unit) (Artifact, error)
}

type Asset struct {
	// ID is the stable handle a consumer uses to refer to this asset: a path, a
	// URI, a content id. attest does not interpret it.
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	// Kind is audio | image | pdf | text. It selects which locator shape is
	// meaningful and which evidence the reviewer must be shown; it is not a MIME
	// type.
	Kind   string `json:"kind"`
	SHA256 string `json:"sha256,omitempty"`
}

type Entry struct {
	Kind Kind `json:"kind"`

	// Unit is what this entry rules on. Empty when Blanket is set, and for
	// Resegment entries that only add units.
	Unit string `json:"unit,omitempty"`

	// Blanket applies this entry to every unit with no ruling EARLIER IN THE
	// LOG. Only meaningful with Affirmed.
	//
	// One line rather than one line per unit, so the sweep keeps its identity:
	// who swept and when is a single fact about the pass, and reconstructing it
	// by counting per-unit flags is how a reader ends up reporting the wrong
	// thing. Units added after this line are not covered — a sweep is a
	// statement about what had been read at the time it was made.
	Blanket bool `json:"blanket,omitempty"`

	// Text and Label carry a correction. Empty means "not disputed", not
	// "cleared to empty" — clearing text is a Resegment or an Unsupported, both
	// of which say something a blank field does not.
	Text  string `json:"text,omitempty"`
	Label string `json:"label,omitempty"`

	// Note is the reason: what the region actually says, why this paragraph is
	// about the septic and not the pole.
	Note string `json:"note,omitempty"`

	// Statement is the reviewer's own words on a blanket affirmation — the terms
	// they are accepting the remainder under.
	//
	// Separate from Note and never generated. An affirmation is a qualified claim
	// with a standard in it: "reasonably certain there are only minor errors or
	// mis-transcriptions that should not be materially relevant to the best of my
	// ability" is a different assertion from "the rest is right", and a tool that
	// paraphrases the first as the second has changed what somebody attested to.
	// Provenance QUOTES this rather than summarising it.
	//
	// Empty is honest and means the terms were not recorded — which is the case
	// for anything imported from a tool that had no field for them.
	Statement string `json:"statement,omitempty"`

	// Units and Supersedes are the payload of a Resegment.
	Units      []Unit   `json:"units,omitempty"`
	Supersedes []string `json:"supersedes,omitempty"`

	// By is the PERSON who made this ruling — or a machine identity like
	// `ocr-text-layer` when a process did.
	//
	// Self-declared, and required. Self-declared because the person at the
	// keyboard is routinely not the account holder: an attorney hands a
	// paralegal the link and the paralegal does the review, which is normal and
	// authorized and has to be recordable. Required because a defaulted author
	// reads afterwards exactly like a real one.
	//
	// The distinction that matters downstream is not who signed but whether a
	// PERSON did: a machine can honestly report that a string is or is not in a
	// text layer; it cannot report that a recording does not SUPPORT what was
	// transcribed.
	By string `json:"by"`

	// Auth is the authenticated account the ruling was made under, supplied by
	// the host's Identity and never by the caller.
	//
	// The other half of the pair. By alone lets any holder of a link type any
	// name; Auth alone files a delegate's work under the account holder's name.
	// Together they say what happened: authorized as X, performed by Y. Empty
	// means the mount is not account-based — a loopback binding, a shared link —
	// which is worth saying plainly rather than papering over with an invented
	// account.
	Auth string `json:"auth,omitempty"`

	At string `json:"at,omitempty"` // RFC3339
}

type Evidence interface {
	Render(ctx context.Context, asset Asset, u Unit) (Artifact, error)
}

type Guest struct{}

type HumaneEvidence interface {
	Humane(ctx context.Context, asset Asset, u Unit) (Artifact, error)
}

type Identity interface {
	// Principal is the authenticated account, written to Entry.Auth. Empty is
	// legal and means the mount is not account-based — a link, a loopback
	// binding — in which case the permission check is the whole of the
	// authorization and the record says so honestly rather than inventing an
	// account.
	Principal(ctx context.Context) (string, error)

	// Can reports whether this caller may do p to this asset. Asset-scoped
	// rather than global so a host can publish one corpus and restrict another
	// without mounting attest twice.
	Can(ctx context.Context, asset string, p Permission) (bool, error)
}

type Kind string

type Locator struct {
	Time *TimeSpan `json:"time,omitempty"`
	Area *Area     `json:"area,omitempty"`
	Span *Span     `json:"span,omitempty"`
}

type Permission string

type ReadOnly struct{ Identity }

type Reading struct {
	Version int    `json:"version"`
	Asset   Asset  `json:"asset"`
	Units   []Unit `json:"units"`

	// Producer identifies what read the asset — "oidio/parakeet",
	// "raglit/regions". Two readings of the same asset by different producers
	// are different claims and are meant to be comparable, which is what makes
	// scoring one against a human pass possible.
	Producer string `json:"producer,omitempty"`
	Read     string `json:"read,omitempty"` // RFC3339
}

type Rect struct {
	X float64 `json:"x"`
	Y float64 `json:"y"`
	W float64 `json:"w"`
	H float64 `json:"h"`
}

type Rendering string

type Span struct {
	From int `json:"from"`
	To   int `json:"to"`
}

type State struct {
	Asset    Asset        `json:"asset"`
	Producer string       `json:"producer,omitempty"`
	Units    []UnitStatus `json:"units"`
	Stats    Stats        `json:"stats"`

	// Orphaned names verdicts that rule on units this reading does not contain
	// — the cost of a re-read that changed what the machine claims.
	//
	// Reported rather than dropped, and rather than matched onto whatever is
	// nearest. A verdict silently re-attached to a claim nobody ruled on is a
	// FALSE attestation, which is worse than a lost one. Recovering the overlap
	// is a rebinding pass that proposes matches for a person to accept.
	Orphaned []Entry `json:"orphaned,omitempty"`
}

type Stats struct {
	Total       int `json:"total"`
	Confirmed   int `json:"confirmed"`
	Corrected   int `json:"corrected"`
	Affirmed    int `json:"affirmed"`
	Unclear     int `json:"unclear"`
	Unsupported int `json:"unsupported"`
	Untouched   int `json:"untouched"`

	// Authored is how many units a person cut themselves. A high count means the
	// machine's decomposition was wrong, which is a different complaint from its
	// text being wrong and is worth surfacing separately.
	Authored int `json:"authored"`

	// SweptBy, SweptAt and SweptStatement record the last blanket affirmation, so
	// a consumer can state provenance without reconstructing it by counting flags.
	//
	// SweptStatement is the reviewer's own words, and an empty one means the terms
	// were not recorded rather than that there were none. Provenance says which.
	SweptBy        string `json:"swept_by,omitempty"`
	SweptAt        string `json:"swept_at,omitempty"`
	SweptStatement string `json:"swept_statement,omitempty"`
}

type TimeSpan struct {
	Start float64 `json:"start"`
	End   float64 `json:"end"`
}

type Unit struct {
	// ID is content-addressed — see UnitID. Assigned by Seal, not by the
	// producer.
	ID string `json:"id"`

	// Parent nests this unit under another, for producers that read
	// hierarchically: raglit's descent reads a sheet, then a drawing interior,
	// then a corner of it. Empty for a flat read.
	//
	// A parent REFERENCE rather than nested children, because the id is a digest
	// of the unit and nesting would make a parent's id depend on what was found
	// underneath it — so descending one level deeper would renumber the whole
	// ancestry and orphan every verdict above the new leaf.
	Parent string `json:"parent,omitempty"`

	Locator Locator `json:"locator"`

	// Text is what the machine read here. Empty is legitimate: a unit may carry
	// only a label, or be a container whose children hold the text.
	Text string `json:"text,omitempty"`

	// Label is the machine's CATEGORICAL claim: the diarizer's cluster, the
	// region's kind, the figure's class. Kept separate from Text because they
	// fail differently and a person rules on them separately — the words can be
	// right while the speaker is wrong, and conflating them is what made oidio's
	// first pass ambiguous.
	Label string `json:"label,omitempty"`

	// Evidence digests the EXACT artifact this claim was read from: the cropped
	// PNG, or the decoded PCM of the time window. Not the whole asset — the
	// whole asset is not what produced the claim, and showing a person the whole
	// asset is asking them to attest against a different image.
	//
	// Producers should record this. A unit without it can still be reviewed, but
	// nothing can then say whether what the reviewer saw is what the machine
	// saw, and Reproducible reports false.
	Evidence string `json:"evidence,omitempty"`

	// Flags are conditions that either hold or do not — low-resolution,
	// repetition, exhausted. Deliberately not a confidence score: a number here
	// would be an invented statistic, and the useful signal is categorical.
	Flags []string `json:"flags,omitempty"`

	// Extra is producer-specific data attest does not interpret and carries
	// through untouched — raglit's tokens-per-square-inch and downscale count,
	// oidio's word timings.
	//
	// Deliberately NOT part of the id. A producer adding a diagnostic field must
	// not orphan every verdict in the corpus.
	Extra json.RawMessage `json:"extra,omitempty"`
}

type UnitStatus struct {
	Unit Unit `json:"unit"`

	// Kind is the ruling in force, or empty for untouched.
	Kind Kind `json:"kind,omitempty"`

	// Text and Label are what this unit says NOW — the correction where one was
	// made, the machine's reading otherwise. A consumer rendering a transcript
	// wants these; a consumer scoring the machine wants Unit.Text and these both,
	// which is why the original is never overwritten.
	Text  string `json:"text,omitempty"`
	Label string `json:"label,omitempty"`

	Note string `json:"note,omitempty"`

	// By is the person who ruled; Auth is the account they were authorized
	// under. Both are carried, because a delegate doing the work is normal and a
	// reader asking "who actually reviewed this" must not be handed the account
	// holder's name instead. See identity.go.
	By   string `json:"by,omitempty"`
	Auth string `json:"auth,omitempty"`
	At   string `json:"at,omitempty"`

	// Authored marks a unit a person created with a Resegment, rather than one
	// the machine proposed. It is not itself a ruling: someone may cut a turn in
	// the right place and still not have decided who is speaking.
	Authored bool `json:"authored,omitempty"`

	// Swept marks a ruling that came from a blanket affirmation rather than a
	// line about this unit. Kind is Affirmed either way; this says whether anyone
	// named it. Not a demotion: the reviewer went through it, and the affirmation
	// they signed says under what terms.
	Swept bool `json:"swept,omitempty"`
}