storage

type Chain struct {
	// Nodes is the walk output in node-first order: index 0 is the node
	// the walk started from, and the last element is either a real root
	// or the last resolvable node whose parent could not be found.
	Nodes []*merkle.Node

	// Incomplete is true when the walk stopped short of a real root,
	// whether because a parent_hash could not be resolved (see
	// MissingParent) or because a cycle was detected (see CycleDetected).
	Incomplete bool

	// MissingParent is the parent_hash that could not be resolved in this
	// store. Only set when Incomplete is true due to a dangling pointer;
	// left empty for cycle-detected incompletes (the cycle-triggering
	// hash is present in Nodes already).
	MissingParent string

	// CycleDetected is true when the walk stopped because it was about
	// to re-visit a hash already in Nodes. Drivers guard every walk with
	// a per-chain seen-set so a corrupt parent edge can never spin
	// forever; when this flag trips, the chain is the largest
	// acyclic prefix reachable from the starting hash.
	//
	// In practice this never trips on a healthy store. It exists because
	// a single corrupted parent_hash would otherwise hang any endpoint
	// that walks ancestry, which is a blast radius out of proportion to
	// the likelihood.
	CycleDetected bool
}

type DeriveQueue interface {
	// MarkDeriveDirty queues (or re-bumps) one harness session.
	MarkDeriveDirty(ctx context.Context, orgID, harnessID, harnessSessionID string) error

	// ListDeriveDirty returns sessions whose dirty mark has settled
	// (DirtiedAt <= dirtiedBefore), oldest first, capped at limit.
	ListDeriveDirty(ctx context.Context, dirtiedBefore, firstDirtiedBefore time.Time, limit int32) ([]DeriveQueueEntry, error)

	// GetDeriveDirty re-reads one queue entry. Returns nil (no error)
	// when the session is clean.
	GetDeriveDirty(ctx context.Context, orgID, harnessID, harnessSessionID string) (*DeriveQueueEntry, error)

	// ClearDeriveDirty removes the entry only if its DirtiedAt is
	// unchanged from e.DirtiedAt. Returns false when the session was
	// re-dirtied (or already cleared) in the meantime.
	ClearDeriveDirty(ctx context.Context, e DeriveQueueEntry) (bool, error)

	// SweepDeriveDirty enqueues every harness session with raw-layer
	// activity at or after activeSince (the worker's slow backstop for
	// lost marks, bounded so a restart doesn't stampede the queue with
	// all of history). The zero time sweeps every session. Sessions
	// already queued keep their DirtiedAt. Returns how many sessions
	// were newly enqueued.
	SweepDeriveDirty(ctx context.Context, activeSince time.Time) (int64, error)

	// DeriveQueueStats reports queue depth and the oldest dirty mark.
	// Cheap (one aggregate over the small dirty-queue table); the
	// worker calls it every poll and the readiness probe leans on it
	// as the "store reachable, queue pollable" check.
	DeriveQueueStats(ctx context.Context) (DeriveQueueStats, error)
}

type DeriveQueueEntry struct {
	// OrgID is the canonical UUID string; empty means "no org context"
	// and maps to the nil-UUID sentinel, mirroring raw_turns.org_id.
	OrgID string

	HarnessID        string
	HarnessSessionID string

	// DirtiedAt is when the most recent raw turn dirtied the session.
	// The worker debounces on it and clears the entry only if it is
	// unchanged since read — a bump mid-derive survives the clear.
	DirtiedAt time.Time

	// FirstDirtiedAt is when the session was first marked dirty in this
	// queued window (it survives re-marks, unlike DirtiedAt). The worker
	// derives a continuously-streaming session — whose DirtiedAt never
	// settles past the debounce cutoff — once FirstDirtiedAt crosses the
	// max-lag bound, so live views see bounded lag.
	FirstDirtiedAt time.Time
}

type DeriveQueueStats struct {
	// Depth is the number of queued (dirty) sessions.
	Depth int64

	// OldestDirtiedAt is the oldest dirty mark still queued — "derive
	// lag" is now minus this. Zero when the queue is empty.
	OldestDirtiedAt time.Time
}

type Driver interface {
	// Open initializes the backing store and makes it ready for use.
	Open(ctx context.Context) error

	// Close closes the store and releases any resources.
	Close() error
}

type IngestTurnRequest struct {
	// Session is the optional session-tracking envelope. nil is a
	// legitimate value (legacy clients): implementations fall back
	// to a Merkle-derived synthetic harness_session_id.
	Session *sessions.IngestEnvelope

	// Nodes is the in-memory chain of nodes for this turn, ordered
	// root-to-leaf. The first element is the conversation root; the
	// last is the assistant response. Consumed for session identity
	// and status folding only — never persisted.
	Nodes []*merkle.Node

	// DerivedTitle folds a title-gen shadow call's output onto the
	// session (sessions.derived_title). Empty for every other call
	// kind; non-empty values overwrite (the harness regenerates the
	// title as the session evolves, so the latest wins).
	DerivedTitle string
}

type IngestTurnResult struct {
	// SessionID is the resolved/created sessions row id as a 36-char
	// canonical UUID string. Stable across retries (idempotent on
	// natural key).
	SessionID string
}

type ModelUsage struct {
	Model        string  `json:"model"`
	Calls        int64   `json:"calls"`
	InputTokens  int64   `json:"input_tokens"`
	OutputTokens int64   `json:"output_tokens"`
	CostUSD      float64 `json:"cost_usd"`
}

type NotFoundError struct {
	Hash string
}

type RawTurnHeader struct {
	ID            int64
	Source        string
	Provider      string
	AgentName     string
	RequestID     string
	ReceivedAt    time.Time
	Meta          json.RawMessage
	RequestBytes  int64
	ResponseBytes int64
}

type RawTurnRecord struct {
	// OrgID is the canonical UUID string from the validated session
	// envelope. Empty means "no org context" and maps to the nil-UUID
	// sentinel, mirroring nodes.org_id.
	OrgID string

	// Source is one of the RawTurnSource* constants.
	Source string

	Provider  string
	AgentName string

	// HarnessID / HarnessSessionID echo the session envelope's natural
	// key so a session's raw turns are queryable without decoding the
	// envelope JSONB. Empty when the turn carried no envelope.
	HarnessID        string
	HarnessSessionID string

	// RequestID is the capture adapter's per-call id (extproc forwards
	// the Envoy request id). It dedupes retried POSTs of the same
	// captured turn; empty disables deduplication for the row.
	RequestID string

	// RawRequest is the provider request body, verbatim.
	RawRequest json.RawMessage

	// Response is the reduced provider response, verbatim from the
	// envelope.
	Response json.RawMessage

	// Meta is the capture adapter's metadata block (model, stream,
	// upstream status, byte counts, elapsed seconds, …), verbatim.
	Meta json.RawMessage

	// SessionEnvelope is the session-tracking block, verbatim.
	SessionEnvelope json.RawMessage

	// ReceivedAt is populated by the store on read; ignored on write
	// (the database stamps insertion time).
	ReceivedAt time.Time

	// ID is the store-assigned monotonic row id, populated on read.
	ID int64
}

type RawTurnStore interface {
	// PutRawTurn appends one captured turn. Returns false when the
	// row was deduplicated (same org + request id already stored).
	PutRawTurn(ctx context.Context, rec RawTurnRecord) (bool, error)

	// ListRawTurns scans the raw layer in insertion order, returning
	// up to pageSize rows with id greater than afterID. Pass 0 to
	// start from the beginning.
	ListRawTurns(ctx context.Context, afterID int64, pageSize int32) ([]RawTurnRecord, error)

	// CountRawTurns reports the total number of raw rows.
	CountRawTurns(ctx context.Context) (int64, error)
}

type SessionIngester interface {
	// IngestTurn resolves/UPSERTs the sessions row for the turn
	// (optionally resolving the parent_session_id FK), folds
	// derived_status and tool counts from the in-memory chain, and
	// folds the derived title when present. It persists no nodes.
	IngestTurn(ctx context.Context, req IngestTurnRequest) (IngestTurnResult, error)
}

type SessionListOpts struct {
	Limit       int
	Sort        SessionSortField // zero value == SortLastActive
	Dir         SortDirection    // zero value == SortDesc
	CursorVal   *string          // boundary row's sort column, canonical ::text form
	CursorID    *string          // boundary row's id (UUID), the keyset tiebreak
	Since       *time.Time
	Until       *time.Time
	AuthSubject string
}

type SessionRecord struct {
	ID               string
	HarnessID        string
	HarnessSessionID string
	// Name is the session's display label with the name column taking
	// precedence over the folded title: the value stored on the identity
	// row (a user rename or the harness-supplied session name) when set,
	// otherwise DerivedTitle as the fallback. Empty only when neither
	// exists.
	Name string
	// DerivedTitle is the deriver's folded session title
	// (sessions.derived_title), generated from the conversation. Empty
	// until title generation produces one. Unlike Name it never falls back
	// to the identity-row name, so it is the pure descriptive title.
	DerivedTitle      string
	Cwd               string // empty when not set
	HarnessVersion    string // empty when not set
	ParentSessionID   string // empty when not set
	StartedAt         time.Time
	LastSeenAt        time.Time
	EndedAt           *time.Time // nil when session is still live
	HarnessMetadata   map[string]any
	TotalInputTokens  int64
	TotalOutputTokens int64
	TotalCostUsd      float64
	TurnCount         int
	// DerivedStatus is the chain-aware session status (completed / failed /
	// abandoned / unknown), denormalized at ingest. 'unknown' until the first
	// turn lands or, for pre-feature rows, until the status backfill runs.
	DerivedStatus string
	// Model is the dominant conversation-spine model, folded at derive
	// time (sessions.derived_model). Empty until the session derives.
	Model string
	// ModelUsage is the per-model spend breakdown folded at derive time
	// across every thread (sessions.model_usage), cost-weighted so the
	// share reflects spend rather than call count. Nil until the session
	// derives; ordered dominant-model-first (by cost).
	ModelUsage []ModelUsage
	// Tasks is the deriver's session-scoped TaskCreate/TaskUpdate fold and
	// KindCounts the per-call_kind span tally (sessions.tasks /
	// sessions.kind_counts), both JSONB served verbatim on the composite
	// traces response. Nil until the session derives.
	Tasks      json.RawMessage
	KindCounts json.RawMessage
	Preview    string // first user turn text, truncated; empty when unavailable
	// AuthSubject is the gateway-stamped JWT subject (the WorkOS user id)
	// captured at ingest. Empty for rows captured before the edge began
	// stamping the x-paper-auth-subject header.
	AuthSubject string
	// SortVal is the canonical ::text form of this row's active sort column,
	// populated by ListSessionRecords so the API can mint an exact next cursor.
	// Empty on records returned by point lookups.
	SortVal string
}

type SessionSortField string

type SkillCounts struct {
	Total int64
	Mine  int64
}

type SkillListOpts struct {
	Query     string // name/description/tag search (empty = no filter)
	Author    string // only skills authored by this subject ("mine")
	NotAuthor string // exclude this subject ("team")
	// Sort selects the ordering and which cursor column applies:
	// "downloads" orders by download_count DESC (keyset on CursorDownloads);
	// anything else orders by updated_at DESC (keyset on CursorTs). Both
	// tiebreak on id DESC.
	Sort            string
	CursorTs        *time.Time // recent keyset: updated_at of the prior page's last row
	CursorDownloads *int64     // downloads keyset: download_count of that row
	CursorID        string     // keyset tiebreak: id of that last row
	Limit           int        // page size; zero falls back to DefaultListLimit
}

type SkillRecord struct {
	// ID is the opaque, immutable identity (the route/URL key), mirroring
	// sessions. Slug is a cosmetic, non-unique display label and SKILL.md
	// filename derived from the name.
	ID                      string
	Slug                    string
	Name                    string
	Description             string
	Type                    string // "workflow" | "domain-knowledge" | "prompt-template"
	Version                 string // semver, e.g. "0.1.0"
	Visibility              string // "private" | "team"
	Tags                    []string
	Content                 string // markdown body
	IsAIGenerated           bool
	GeneratedFromSessionIDs []string
	ParentID                string // empty when not a fork
	// AuthorSubject is the WorkOS user id (JWT sub) of the creator, stamped
	// from the gateway-trusted x-paper-auth-subject header the same way
	// sessions.auth_subject is captured. Empty when no header was present.
	AuthorSubject string
	// DownloadCount is a real usage signal — how many times the SKILL.md has
	// been downloaded.
	DownloadCount int64
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

type SkillVersionRecord struct {
	SkillID       string
	VersionNumber int
	Semver        string
	Changelog     string
	Content       string
	AuthorSubject string
	PublishedAt   time.Time
}

type SortColumn struct {
	// contains filtered or unexported fields
}

type SortDirection string

type SpanLinkRecord struct {
	FromTraceID string
	FromSpanID  string
	FromIO      string
	ToTraceID   string
	ToSpanID    string
	ToIO        string
	Kind        string
}

type SpanModelReader interface {
	ListSessionSpanModel(ctx context.Context, sessionID string) ([]SpanTurnRecord, []SpanRecord, []SpanLinkRecord, error)
	ListTraceSummaries(ctx context.Context, sessionID string) ([]TraceSummaryRecord, error)
	// ListSessionLinks returns a session's dataflow links alone — the
	// payload-free half of ListSessionSpanModel. It backs the per-trace
	// streaming export, which loads the light turn headers and links whole
	// but reads the heavy spans one trace at a time.
	ListSessionLinks(ctx context.Context, sessionID string) ([]SpanLinkRecord, error)
	// ListTraceSpans returns one trace's spans in presentation order — the
	// same per-trace read GetTraceDetail performs, without the turn/link
	// round-trips. It backs the per-trace streaming export.
	ListTraceSpans(ctx context.Context, orgID, traceID string) ([]SpanRecord, error)
	GetTraceDetail(ctx context.Context, orgID, traceID string) (*SpanTurnRecord, []SpanRecord, []SpanLinkRecord, error)
	GetSpanRecord(ctx context.Context, orgID, traceID, spanID string) (*SpanRecord, error)
	ListRawTurnHeaders(ctx context.Context, orgID, harnessID, harnessSessionID string) ([]RawTurnHeader, error)
}

type SpanRecord struct {
	TraceID      string
	SpanID       string
	ParentSpanID string
	Kind         string
	Name         string
	Status       string
	CallKind     string
	ThreadID     string
	Model        string
	StopReason   string
	StartedAt    time.Time
	DurationNS   int64
	// Seq is the deriver's emit ordinal within the trace —
	// presentation order, since started_at ties inside one llm call.
	Seq       int64
	Input     json.RawMessage
	Output    json.RawMessage
	Usage     json.RawMessage
	RawTurnID int64
	NodeHash  string
	// Verdict is the deriver-written security-monitor disposition JSON
	// (null on non-permission-check spans). Served verbatim on the wire.
	Verdict json.RawMessage
}

type SpanStats struct {
	TurnCount           int
	SessionCount        int
	CompletedCount      int
	InputTokens         int64
	OutputTokens        int64
	CacheCreationTokens int64
	CacheReadTokens     int64
	TotalDurationNS     int64
	TotalCostUSD        float64
	ToolCalls           int
}

type SpanStatsReader interface {
	AggregateSpanStats(ctx context.Context, orgID string, since, until *time.Time) (SpanStats, error)
}

type SpanTurnRecord struct {
	TraceID    string
	SessionID  string
	UserPrompt string
	// ResponsePreview is the derive-time fold of the closing spine llm
	// call's text output — the turn card's answer line.
	ResponsePreview string
	Synthetic       string
	Status          string
	// Source is the capture origin of the turn's raw rows ("wire" |
	// "transcript"), promoted from raw_turns.source at derive time.
	Source            string
	StartedAt         time.Time
	EndedAt           *time.Time
	DurationNS        int64
	TotalInputTokens  int64
	TotalOutputTokens int64
	// Main* counts only conversation-spine llm calls; the difference
	// from Total* is shadow spend.
	MainInputTokens     int64
	MainOutputTokens    int64
	CacheReadTokens     int64
	CacheCreationTokens int64
	TotalCostUSD        float64
}

type TraceSummaryRecord struct {
	SpanTurnRecord
	SpanCount int
}