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 PublishedColumnName struct {
	// contains filtered or unexported fields
}

type PublishedFilter struct {
	View      PublishedViewName
	TypeValue string
	// Column is the claim-declared value column the probe compares against
	// (match.value_column). Like View it reaches SQL in an identifier
	// position, so it is opaque: only its validating parser constructs it
	// and only its quoting helper renders it.
	Column PublishedColumnName
	Values []string
}

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

type PublishedViewProber interface {
	// ProbePublishedView reports nil when the view is readable in the shape
	// the claim declared. A non-nil error is either the store's own verdict
	// (the store answered and refused) or a *TransientProbeError when the
	// store could not be asked at all — implementations must keep the two
	// distinguishable, because callers that cache the verdict may only
	// change cached state on an actual answer.
	ProbePublishedView(ctx context.Context, view PublishedViewName, column PublishedColumnName) error
}

type RawTurnAttribution struct {
	RawTurnID              int64   `json:"raw_turn_id"`
	HarnessID              string  `json:"harness_id"`
	HarnessSessionID       string  `json:"harness_session_id"`
	ThreadID               string  `json:"thread_id"`
	ParentHarnessSessionID *string `json:"parent_harness_session_id,omitempty"`
}

type RawTurnAttributionRepairRequest struct {
	OrgID                  string  `json:"-"`
	RawTurnID              int64   `json:"raw_turn_id,omitempty"`
	PaperProxyRequestID    string  `json:"paper_proxy_request_id,omitempty"`
	HarnessID              string  `json:"harness_id"`
	HarnessSessionID       string  `json:"harness_session_id"`
	ThreadID               string  `json:"thread_id"`
	ParentHarnessSessionID *string `json:"parent_harness_session_id,omitempty"`
	Reason                 string  `json:"reason"`
}

type RawTurnAttributionRepairResult struct {
	Recorded  bool               `json:"recorded"`
	Previous  RawTurnAttribution `json:"previous"`
	Effective RawTurnAttribution `json:"effective"`

	// ProjectionsPending lists the sessions whose synchronous rebuild failed
	// after the correction committed. Empty on full success. When set, the
	// correction is effective at read time and the listed projections
	// converge via the derive queue (marked dirty in the correction
	// transaction); the call returns ErrRepairProjectionsPending alongside
	// this result.
	ProjectionsPending []RepairPendingSession `json:"projections_pending,omitempty"`

	// SourceCleanupPending reports that the best-effort removal of the
	// emptied previous-session row failed after the correction and both
	// projection rebuilds applied. The leftover row is cosmetic — it anchors
	// no effective turns — and nothing retries the deletion automatically:
	// the flag makes the response honest about the leftover, it is not a
	// promise of later cleanup. On its own it never accompanies an error;
	// when ProjectionsPending is empty too, the repair succeeded.
	SourceCleanupPending bool `json:"source_cleanup_pending,omitempty"`
}

type RawTurnAttributionRepairer interface {
	RepairRawTurnAttribution(context.Context, string, RawTurnAttributionRepairRequest) (RawTurnAttributionRepairResult, error)
}

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

	// RawResponse is the upstream response body exactly as it arrived on
	// the wire, before any reduction. Response is derived from these bytes
	// and is lossy — a field the reducing adapter didn't model is gone from
	// it, and the raw layer's promise that any future data-model change is
	// a re-derive rather than a re-capture only holds while the source
	// bytes survive.
	//
	// Nil when the capture adapter sent no raw response, or when one
	// arrived and exceeded the ingest cap; RawResponseDropped separates
	// those two cases.
	RawResponse []byte

	// RawResponseEncoding is the Content-Encoding RawResponse is stored
	// under ("identity", "gzip", …), empty when unknown or absent. The
	// bytes are kept as received rather than decompressed, because
	// re-compression is not guaranteed byte-identical and "verbatim" has to
	// mean verbatim for the column to be worth having.
	RawResponseEncoding string

	// RawResponseDropped marks a turn whose raw response existed and was not
	// kept — because it arrived too large to store, or because the producer
	// captured it and withheld it to fit the ingest transport limit. It is
	// the difference between "this turn never had verbatim bytes" and "it
	// did, and we chose not to keep them" — without it a fidelity gap is
	// indistinguishable from an absence.
	//
	// True implies RawResponse is empty: the two say opposite things about
	// the same bytes, so a row asserting both would be unreadable. Ingest
	// enforces it on both paths.
	RawResponseDropped bool

	// 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 RepairPendingSession struct {
	HarnessID        string `json:"harness_id"`
	HarnessSessionID string `json:"harness_session_id"`
}

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

	// ClaimedFilters are the claim-derived published-view filters, one per
	// claimed param the request supplied (empty when none was). Values
	// arrive already normalized per each claim's declared profile; every
	// value of every filter renders one EXISTS predicate against that
	// filter's own view and value column, all ANDed inside the same
	// paginating query. Rendering the whole set is the contract: a supplied
	// claimed param that never reached SQL would be silent unfiltering.
	ClaimedFilters []PublishedFilter
}

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
	// DisplayName is the user-set display title (sessions.display_name),
	// written only by the Console rename PATCH and never by ingest, so it
	// survives an active session (unlike Name, which the envelope re-sends
	// every turn). Empty means "no user title"; the API resolves the
	// display title as DisplayName -> DerivedTitle -> Preview -> Name
	// (PCC-970).
	DisplayName 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
	PreviewIsJSON bool   // full prompt was valid JSON before preview truncation
	// 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 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, authSubject string) (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
}

type TransientProbeError struct {
	Err error
}