core

type ActorType string

type BudgetUnit string

type CallType string

type Claim struct {
	ID        string
	SessionID string
	LeadID    string
	Text      string

	Source      string // URL, DOI, or "connector:<name>#<query_hash>"
	ToolCallID  string
	Quote       string
	QuoteOffset int64

	PublishedAt *time.Time
	RetrievedAt time.Time

	// Verification lineage. A per-row recheck counter cannot work: a follow-up
	// lead produces a NEW claim, which would start the counter over. Depth is
	// inherited and incremented so the cap actually binds.
	RootClaimID string
	VerifyDepth int

	// AssertionStrength is how clearly the SOURCE states this, as reported by
	// the extracting model. A property of the document, not of the world, and
	// that is all the mine prompt asks for.
	//
	// Not confidence, and kept separate from it because it was serving as
	// confidence: §11.3 rejects self-reported confidence as uncalibrated and
	// "mostly encoding fluency", and the report was ordered by it.
	AssertionStrength float64

	// Confidence is derived from graph structure (§11.3) — independent
	// corroborating publishers, source class, contradicting edges, grounding,
	// recency. Never asked of a model.
	//
	// Zero until the Verifier has scored the claim, which is the honest value:
	// nothing corroborates a claim that has not been compared to anything.
	Confidence float64
	Grounded   *bool
	// GroundingNote says how a grounding check reached its verdict, including the
	// two outcomes Grounded cannot express: the quote vanished from its source, or
	// the source could not be reached. Both leave Grounded nil, because neither is
	// evidence about the claim (§11.5).
	GroundingNote string

	// VerifiedAt records that the Verifier has scored this claim. Nil means it
	// has not, which Confidence cannot express on its own: §11.3's formula
	// legitimately returns 0 for an uncorroborated claim carrying a contradiction,
	// so a zero there means "scored badly" as often as "never examined".
	VerifiedAt *time.Time

	CreatedAt time.Time
	// Seq is this claim's position within the batch it was written in, assigned
	// by the store. It exists to make claim order total and reproducible.
	//
	// CreatedAt cannot do it alone: one timestamp is stamped for a whole batch,
	// so every claim from a lead ties, and the tie was being broken by SQLite's
	// unspecified row order. Order matters because citation numbers are assigned
	// by it, and under replay the resulting prompt is the cassette key.
	Seq int
}

type ClaimEdge struct {
	ID        string
	SessionID string
	FromID    string
	ToID      string
	Kind      EdgeKind
	Weight    float64
	CreatedBy string
	Rationale string
	CreatedAt time.Time
}

type Cost struct {
	USDMicros int64

	InputTokens      int64
	OutputTokens     int64
	CacheReadTokens  int64
	CacheWriteTokens int64
}

type Crossing struct {
	ID        string
	SessionID string
	LeadID    string

	// Connector is the registered name, and Query/QueryHash identify the
	// statement. A local claim cites "connector:<name>#<hash>", so this is what
	// makes a claim traceable back to the question that produced it.
	Connector string
	Query     string
	QueryHash string

	Outcome CrossingOutcome
	// Detail is mole's own reason string — a refusal's text, never a value from
	// the result.
	Detail string

	RowsDescribed   int64
	Columns         int
	ColumnsWithheld int
	Buckets         int
	Suppressed      int
	BeyondTopK      int
	Tests           int
	Truncated       bool
	CreatedAt       time.Time
}

type CrossingOutcome string

type Document struct {
	ID        string
	SessionID string

	URL   string
	Title string
	// Text is exactly what the caller was handed. It must not be re-normalised
	// after storage: a stored offset that no longer locates its quote is
	// provenance that lies.
	Text string
	// Truncated reports that the extractor cut the page short, so a quote from
	// beyond the cut will fail verification for a reason that is not the caller's
	// fault.
	Truncated bool

	// PublishedAt is when the source says it was published, when it says at all.
	// Zero means unstated, which is the common case and is not the same fact as
	// "published at the epoch" — the staleness rule needs a date on both sides
	// before it will rewrite anything.
	PublishedAt time.Time

	FetchedAt time.Time
	ExpiresAt time.Time
}

type EdgeKind string

type Lead struct {
	ID        string
	SessionID string
	ActorType ActorType
	Query     string
	ParentID  *string
	Depth     int
	Priority  int
	Status    LeadStatus

	// RootClaimID marks a lead spawned to resolve something about a claim —
	// §11.4's verification lineage. Nil on an ordinary planner lead.
	//
	// Claims the lead produces inherit it, so a chain of follow-ups all trace to
	// the claim that started the investigation. §11.4's point is that this cannot
	// be a per-claim counter: a follow-up produces a NEW claim, and a counter on
	// the row would start over every time.
	RootClaimID *string
	// VerifyDepth is how many follow-ups deep this lead sits. Claims inherit it.
	VerifyDepth int

	LeaseOwner   *string
	LeaseExpires *time.Time

	CreatedAt time.Time
	UpdatedAt time.Time
}

type LeadCost struct {
	ActorType ActorType
	Depth     int
	Cost      Cost
}

type LeadStatus string

type Mode string

type Reservation struct {
	ID         string
	SessionID  string
	LeadID     *string
	Amount     int64
	Status     ReservationStatus
	CreatedAt  time.Time
	ExpiresAt  time.Time
	ResolvedAt *time.Time
}

type ReservationStatus string

type Role string

type Session struct {
	ID         string
	Prompt     string
	Mode       Mode
	ActorTypes []ActorType

	BudgetUnit BudgetUnit
	Budget     int64 // micro-dollars, or tokens, per BudgetUnit
	Spent      int64 // materialized sum of the ledger
	Held       int64 // sum of outstanding reservations
	Escrow     int64 // held back for output + final verify

	// Unit-independent ceilings. Without these, token mode has a hole: search
	// and fetch calls cost no tokens, so an unbounded fetch loop would be free.
	MaxToolCalls  int64
	MaxLeads      int64
	MaxWallClock  time.Duration
	ToolCallCount int64
	LeadCount     int64

	Status    SessionStatus
	CreatedAt time.Time
	UpdatedAt time.Time
	// Report is the session's rendered answer, written when it finalizes.
	//
	// Persisted because §5.1's research.result is defined as returning it, and
	// the MCP flow — report, poll status, result — has no other moment where the
	// answer reaches the caller. Before this it lived only in memory: the CLI
	// printed it, and the daemon paid for it out of escrow and dropped it.
	Report string
	// ReportDegraded says why the prose is missing or unsynthesized, so an empty
	// Report can be told from a failed one.
	ReportDegraded string
}

type SessionStatus string

type Span struct {
	ID        string
	SessionID string
	LeadID    *string
	ParentID  *string
	Name      string
	StartedAt time.Time
	EndedAt   *time.Time
	Status    string
	Attrs     map[string]string
}

type ToolCall struct {
	ID         string
	SessionID  string
	LeadID     *string
	Role       Role
	Type       CallType
	Model      string
	Input      string // redacted or hashed for local queries
	Cost       Cost
	Err        string
	DurationMS int64
	CreatedAt  time.Time
}