gensqlc

package
v0.37.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 23, 2026 License: Apache-2.0, MIT Imports: 4 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AggregateSpanStatsParams added in v0.16.0 

type AggregateSpanStatsParams struct {
	OrgID             pgtype.UUID
	SinceFilter       pgtype.Timestamptz
	UntilFilter       pgtype.Timestamptz
	AuthSubjectFilter pgtype.Text
}

type AggregateSpanStatsRow added in v0.16.0 

type AggregateSpanStatsRow struct {
	TurnCount           int64
	SessionCount        int64
	CompletedCount      int64
	InputTokens         int64
	OutputTokens        int64
	CacheCreationTokens int64
	CacheReadTokens     int64
	TotalDurationNs     int64
	TotalCostUsd        pgtype.Numeric
	ToolCalls           int64
}

type ClearDeriveDirtyParams added in v0.16.0 

type ClearDeriveDirtyParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
	DirtiedAt        pgtype.Timestamptz
}

type DBTX 

type DBTX interface {
	Exec(context.Context, string, ...interface{}) (pgconn.CommandTag, error)
	Query(context.Context, string, ...interface{}) (pgx.Rows, error)
	QueryRow(context.Context, string, ...interface{}) pgx.Row
}

type DeleteEmptyUnreferencedSessionParams added in v0.30.0 

type DeleteEmptyUnreferencedSessionParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type DeleteSessionParams added in v0.22.0 

type DeleteSessionParams struct {
	OrgID pgtype.UUID
	ID    pgtype.UUID
}

type DeriveQueue added in v0.16.0 

type DeriveQueue struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
	DirtiedAt        pgtype.Timestamptz
	FirstDirtiedAt   pgtype.Timestamptz
}

type DeriveQueueStatsRow added in v0.16.0 

type DeriveQueueStatsRow struct {
	Depth           int64
	OldestDirtiedAt pgtype.Timestamptz
}

type DerivedProjectionSchema added in v0.17.0 

type DerivedProjectionSchema struct {
	CompatibilityDate pgtype.Date
	SpanTurnsTable    string
	SpansTable        string
	SpanLinksTable    string
	CreatedAt         pgtype.Timestamptz
}

type FindRawTurnIDsByPaperProxyRequestIDParams added in v0.30.0 

type FindRawTurnIDsByPaperProxyRequestIDParams struct {
	OrgID               pgtype.UUID
	PaperProxyRequestID string
}

type GetDeriveDirtyParams added in v0.16.0 

type GetDeriveDirtyParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type GetRawTurnAttributionForUpdateParams added in v0.30.0 

type GetRawTurnAttributionForUpdateParams struct {
	OrgID     pgtype.UUID
	RawTurnID int64
}

type GetRawTurnAttributionForUpdateRow added in v0.30.0 

type GetRawTurnAttributionForUpdateRow struct {
	ID                              int64
	OrgID                           pgtype.UUID
	SessionEnvelope                 []byte
	ReceivedAt                      pgtype.Timestamptz
	HarnessID                       string
	HarnessSessionID                string
	ThreadID                        string
	HasCorrection                   bool
	CorrectedParentHarnessSessionID string
	RawParentHarnessSessionID       string
}

type GetRawTurnRow added in v0.30.0 

type GetRawTurnRow struct {
	ID                  int64
	OrgID               pgtype.UUID
	Source              string
	Provider            string
	AgentName           string
	HarnessID           string
	HarnessSessionID    string
	RequestID           string
	RawRequest          []byte
	Response            []byte
	Meta                []byte
	SessionEnvelope     []byte
	ReceivedAt          pgtype.Timestamptz
	RawResponse         []byte
	RawResponseEncoding string
}

type GetSessionByNaturalKeyParams added in v0.10.0 

type GetSessionByNaturalKeyParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type GetSessionRecordParams added in v0.12.0 

type GetSessionRecordParams struct {
	OrgID pgtype.UUID
	ID    pgtype.UUID
}

type GetSpanParams added in v0.16.0 

type GetSpanParams struct {
	OrgID   pgtype.UUID
	TraceID string
	SpanID  string
}

type GetSpanTurnParams added in v0.16.0 

type GetSpanTurnParams struct {
	OrgID   pgtype.UUID
	TraceID string
}

type InsertRawTurnAttributionCorrectionParams added in v0.30.0 

type InsertRawTurnAttributionCorrectionParams struct {
	OrgID                  pgtype.UUID
	RawTurnID              int64
	HarnessID              string
	HarnessSessionID       string
	ThreadID               string
	ParentHarnessSessionID pgtype.Text
	Reason                 string
}

type InsertRawTurnParams added in v0.16.0 

type InsertRawTurnParams struct {
	OrgID               pgtype.UUID
	Source              string
	Provider            string
	AgentName           string
	HarnessID           string
	HarnessSessionID    string
	RequestID           string
	RawRequest          []byte
	Response            []byte
	Meta                []byte
	SessionEnvelope     []byte
	RawResponse         []byte
	RawResponseEncoding string
	RawResponseDropped  bool
}

type InsertSessionPlaceholderParams added in v0.10.0 

type InsertSessionPlaceholderParams struct {
	ID               pgtype.UUID
	OrgID            pgtype.UUID
	AuthSubject      string
	HarnessID        string
	HarnessSessionID string
	Now              pgtype.Timestamptz
}

type ListChangedSpanTurnsParams added in v0.30.0 

type ListChangedSpanTurnsParams struct {
	OrgID       pgtype.UUID
	AfterCursor int64
	PageSize    int32
}

type ListChangedSpanTurnsRow added in v0.30.0 

type ListChangedSpanTurnsRow struct {
	OrgID       pgtype.UUID
	TraceID     string
	SessionID   pgtype.UUID
	ContentHash string
	DeriveSeq   int64
	Fidelity    string
}

type ListChangedSpansParams added in v0.30.0 

type ListChangedSpansParams struct {
	OrgID       pgtype.UUID
	AfterCursor int64
	PageSize    int32
}

type ListChangedSpansRow added in v0.30.0 

type ListChangedSpansRow struct {
	OrgID        pgtype.UUID
	TraceID      string
	SpanID       string
	ParentSpanID string
	Kind         string
	Name         string
	ContentHash  string
	DeriveSeq    int64
	Fidelity     string
}

type ListDeriveDirtyParams added in v0.16.0 

type ListDeriveDirtyParams struct {
	DirtiedBefore      pgtype.Timestamptz
	FirstDirtiedBefore pgtype.Timestamptz
	PageSize           int32
}

type ListRawTurnHeadersBySessionParams added in v0.16.0 

type ListRawTurnHeadersBySessionParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type ListRawTurnHeadersBySessionRow added in v0.16.0 

type ListRawTurnHeadersBySessionRow struct {
	ID                 int64
	OrgID              pgtype.UUID
	Source             string
	Provider           string
	AgentName          string
	RequestID          string
	ReceivedAt         pgtype.Timestamptz
	Meta               []byte
	RequestBytes       int64
	ResponseBytes      int64
	RawResponseBytes   int64
	RawResponseDropped bool
}

type ListRawTurnIndexBySessionParams added in v0.16.0 

type ListRawTurnIndexBySessionParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type ListRawTurnIndexBySessionRow added in v0.16.0 

type ListRawTurnIndexBySessionRow struct {
	ID               int64
	OrgID            pgtype.UUID
	Source           string
	HarnessID        string
	HarnessSessionID string
	ReceivedAt       pgtype.Timestamptz
	Meta             []byte
}

type ListRawTurnIndexParams added in v0.16.0 

type ListRawTurnIndexParams struct {
	AfterID  int64
	PageSize int32
}

type ListRawTurnIndexRow added in v0.16.0 

type ListRawTurnIndexRow struct {
	ID               int64
	OrgID            pgtype.UUID
	Source           string
	HarnessID        string
	HarnessSessionID string
	ReceivedAt       pgtype.Timestamptz
	Meta             []byte
}

type ListRawTurnsBySessionParams added in v0.16.0 

type ListRawTurnsBySessionParams struct {
	OrgID            pgtype.UUID
	HarnessSessionID string
}

type ListRawTurnsBySessionRow added in v0.30.0 

type ListRawTurnsBySessionRow struct {
	ID                  int64
	OrgID               pgtype.UUID
	Source              string
	Provider            string
	AgentName           string
	HarnessID           string
	HarnessSessionID    string
	RequestID           string
	RawRequest          []byte
	Response            []byte
	Meta                []byte
	SessionEnvelope     []byte
	ReceivedAt          pgtype.Timestamptz
	RawResponse         []byte
	RawResponseEncoding string
	RawResponseDropped  bool
}

type ListRawTurnsParams added in v0.16.0 

type ListRawTurnsParams struct {
	AfterID  int64
	PageSize int32
}

type ListRawTurnsRow added in v0.30.0 

type ListRawTurnsRow struct {
	ID                  int64
	OrgID               pgtype.UUID
	Source              string
	Provider            string
	AgentName           string
	HarnessID           string
	HarnessSessionID    string
	RequestID           string
	RawRequest          []byte
	Response            []byte
	Meta                []byte
	SessionEnvelope     []byte
	ReceivedAt          pgtype.Timestamptz
	RawResponse         []byte
	RawResponseEncoding string
	RawResponseDropped  bool
}

type ListSessionsByHarnessSessionIDParams added in v0.36.0 

type ListSessionsByHarnessSessionIDParams struct {
	OrgID            pgtype.UUID
	HarnessSessionID string
}

type ListSessionsForRederiveRow added in v0.30.0 

type ListSessionsForRederiveRow struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type ListSpanLinksByTraceParams added in v0.16.0 

type ListSpanLinksByTraceParams struct {
	OrgID       pgtype.UUID
	FromTraceID string
}

type ListSpanTurnsParams added in v0.16.0 

type ListSpanTurnsParams struct {
	OrgID           pgtype.UUID
	Limit           int32
	CursorStartedAt pgtype.Timestamptz
	CursorTraceID   pgtype.Text
}

type ListSpansByTraceParams added in v0.16.0 

type ListSpansByTraceParams struct {
	OrgID   pgtype.UUID
	TraceID string
}

type ListTraceSummariesBySessionRow added in v0.16.0 

type ListTraceSummariesBySessionRow struct {
	OrgID               pgtype.UUID
	TraceID             string
	SessionID           pgtype.UUID
	UserPrompt          string
	ResponsePreview     string
	Synthetic           string
	Status              string
	Source              string
	StartedAt           pgtype.Timestamptz
	EndedAt             pgtype.Timestamptz
	DurationNs          int64
	TotalInputTokens    int64
	TotalOutputTokens   int64
	MainInputTokens     int64
	MainOutputTokens    int64
	CacheReadTokens     int64
	CacheCreationTokens int64
	TotalCostUsd        pgtype.Numeric
	SpanCount           int64
}

type MarkDeriveDirtyParams added in v0.16.0 

type MarkDeriveDirtyParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type PruneSpanLinksParams added in v0.16.0 

type PruneSpanLinksParams struct {
	OrgID            pgtype.UUID
	SessionIds       []pgtype.UUID
	KeepFromTraceIds []string
	KeepFromSpanIds  []string
	KeepToTraceIds   []string
	KeepToSpanIds    []string
	KeepFromIos      []string
	KeepToIos        []string
}

type PruneSpanTurnsParams added in v0.16.0 

type PruneSpanTurnsParams struct {
	OrgID        pgtype.UUID
	SessionIds   []pgtype.UUID
	KeepTraceIds []string
}

type PruneSpansParams added in v0.16.0 

type PruneSpansParams struct {
	OrgID        pgtype.UUID
	SessionIds   []pgtype.UUID
	KeepTraceIds []string
	KeepSpanIds  []string
}

type Queries 

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

func New 

func New(db DBTX) *Queries

func (*Queries) AggregateSpanStats added in v0.16.0 

func (q *Queries) AggregateSpanStats(ctx context.Context, arg AggregateSpanStatsParams) (AggregateSpanStatsRow, error)

/v1/stats from the span layer: trace-grain rollups summed over the window, so the numbers agree with what the session detail and trace views show. The node-layer aggregate this replaces summed per-call usage, which re-bills the conversation history on every call. 

turn_count        = traces started in the window
total_duration_ns = SUM of trace durations — agent time, not the
                    wall-clock MAX-MIN window (idle time between
                    turns no longer counts)
tool_calls        = SUM of the turn rollups' tool span counts,
                    windowed on the turn's started_at like every
                    other figure here. Counting kind='tool' rows in
                    spans_20260615 per request was the aggregate's
                    dominant cost: ~20x the rows, wide JSONB
                    payloads, and cold heap fetches (PCC-936)

completed_count joins sessions once (LEFT JOIN, so a trace whose session identity is missing keeps its turn/token totals and simply doesn't count as completed) rather than a correlated EXISTS per matched trace — the per-row subquery is O(traces) index lookups and is the part that times out on a wide (30d) window at scale.

auth_subject_filter narrows every total to one gateway-stamped subject. Attribution lives on sessions and nowhere else — neither projection table carries a subject — so it is reached through session_id, once, in the matched CTE. Every figure including tool_calls comes from that CTE, so one predicate scopes them all.

Filtering also tightens the LEFT JOIN to an inner match, and deliberately: a trace whose session row is missing has no subject, so it belongs to no one and cannot match. `s.auth_subject = @filter` is NULL for those rows, which drops them. Unfiltered they still count, exactly as before.

func (*Queries) ClearDeriveDirty added in v0.16.0 

func (q *Queries) ClearDeriveDirty(ctx context.Context, arg ClearDeriveDirtyParams) (int64, error)

Conditional clear: only removes the row if dirtied_at is unchanged since the worker read it. A raw turn landing mid-derive bumps dirtied_at, the DELETE matches nothing, and the session survives for the next poll — re-dirty during derive is never lost.

func (*Queries) CountRawTurns added in v0.16.0 

func (q *Queries) CountRawTurns(ctx context.Context) (int64, error)

func (*Queries) DeleteEmptyUnreferencedSession added in v0.30.0 

func (q *Queries) DeleteEmptyUnreferencedSession(ctx context.Context, arg DeleteEmptyUnreferencedSessionParams) (int64, error)

Remove only the ghost identity left after attribution repair moves away its final effective raw turn. A zero-turn session that still anchors child lineage is a legitimate placeholder and must remain. This is deliberately narrower than the public subtree-cascading DeleteSession operation.

func (*Queries) DeleteSession added in v0.22.0 

func (q *Queries) DeleteSession(ctx context.Context, arg DeleteSessionParams) (int64, error)

Remove a session by its org-scoped id. Returns the affected row count so the handler can distinguish a real delete from a missing id. Dependent rows (subagent child sessions, spans/span_turns/span_links) are removed by the session_id ON DELETE CASCADE foreign keys, so this single statement tears down the whole subtree.

func (*Queries) DeriveQueueStats added in v0.16.0 

func (q *Queries) DeriveQueueStats(ctx context.Context) (DeriveQueueStatsRow, error)

Queue depth plus the oldest dirty mark: the worker polls this for its depth/lag gauges, and /readyz uses it as the "store reachable, queue pollable" probe. oldest_dirtied_at is NULL when the queue is empty.

func (*Queries) FindRawTurnIDsByPaperProxyRequestID added in v0.30.0 

func (q *Queries) FindRawTurnIDsByPaperProxyRequestID(ctx context.Context, arg FindRawTurnIDsByPaperProxyRequestIDParams) ([]int64, error)

func (*Queries) FoldSessionRollupsFromSpans added in v0.16.0 

func (q *Queries) FoldSessionRollupsFromSpans(ctx context.Context, sessionIds []pgtype.UUID) error

Session-level accounting is a derive-time fold over the trace rollups — the deriver is the single writer of these columns on span-model sessions. The ingest path never priced wire turns, its token counters double-count re-sent history (each call re-bills the whole conversation), and its turn counter counts wire calls rather than user-visible turns, so the span fold replaces all of them. derived_model is the dominant conversation-spine model, so the session overview never needs span payloads.

model_usage and derived_title are reset to NULL here for every covered session and re-written afterward only for the sessions that still produce one (priced/titled in Go, so they ride a per-key loop, not this fold). Without the reset a re-derive that drops a session's last model entry or its title would leave the previous value stale — not a pure function of raw.

func (*Queries) GetDeriveDirty added in v0.16.0 

func (q *Queries) GetDeriveDirty(ctx context.Context, arg GetDeriveDirtyParams) (DeriveQueue, error)

Re-read one queue row (the worker does this under the advisory lock to catch a concurrent worker having already derived + cleared it). first_dirtied_at rides along so the re-read can honor the max-lag bound: a continuously streaming session bumps dirtied_at past the debounce cutoff on every poll, but its first mark is what crossed the lag bound, and the worker must derive on that.

func (*Queries) GetRawTurn added in v0.16.0 

func (q *Queries) GetRawTurn(ctx context.Context, id int64) (GetRawTurnRow, error)

The derive read, through the attribution-correction overlay: identity columns COALESCE to the latest correction, meta's thread_id is overridden when corrected, and the session envelope is rewritten to match.

raw_response is selected ONLY for turns whose reduction is missing its content blocks — the shape the deriver skips.

The column runs to the ingest cap, so selecting it unconditionally would pull megabytes through every derive read to be discarded. Selecting it never is what left a failed reduction unrecoverable: the bytes were stored and no read path could reach them. This CASE is the whole difference, and it costs nothing on the common path because a healthy reduction returns NULL here.

The test is deliberately coarse — "no content blocks" rather than a faithful port of ingest's reducedResponseAbsent. It only decides whether to *fetch*; the caller re-checks authoritatively before reducing, so a false positive costs one wasted read and a false negative is impossible for the case that matters (an empty reduction always lacks content).

func (*Queries) GetRawTurnAttributionForUpdate added in v0.30.0 

func (q *Queries) GetRawTurnAttributionForUpdate(ctx context.Context, arg GetRawTurnAttributionForUpdateParams) (GetRawTurnAttributionForUpdateRow, error)

Locks the immutable row as a serialization point for competing repairs.

func (*Queries) GetSessionByNaturalKey added in v0.10.0 

func (q *Queries) GetSessionByNaturalKey(ctx context.Context, arg GetSessionByNaturalKeyParams) (Session, error)

Lookup by the unique (org_id, harness_id, harness_session_id) index. Used by the parent-FK resolution path in ingest: when an inbound request carries a parent_harness_session_id hint, ingest reads the parent's sessions.id this way and FKs it onto the new row.

func (*Queries) GetSessionRecord added in v0.12.0 

func (q *Queries) GetSessionRecord(ctx context.Context, arg GetSessionRecordParams) (Session, error)

func (*Queries) GetSpan added in v0.16.0 

func (q *Queries) GetSpan(ctx context.Context, arg GetSpanParams) (Spans20260615, error)

func (*Queries) GetSpanTurn added in v0.16.0 

func (q *Queries) GetSpanTurn(ctx context.Context, arg GetSpanTurnParams) (SpanTurns20260615, error)

func (*Queries) InsertRawTurn added in v0.16.0 

func (q *Queries) InsertRawTurn(ctx context.Context, arg InsertRawTurnParams) (int64, error)

raw_turns is append-only and immutable: INSERT is the only write this table ever sees. The ON CONFLICT arm matches the partial unique index raw_turns_org_request_uq so a retried POST of the same captured turn (same org, same extproc request_id) is a no-op rather than a duplicate raw row. Writers without a request_id (”) bypass the index and append unconditionally.

func (*Queries) InsertRawTurnAttributionCorrection added in v0.30.0 

func (q *Queries) InsertRawTurnAttributionCorrection(ctx context.Context, arg InsertRawTurnAttributionCorrectionParams) error

func (*Queries) InsertSessionPlaceholder added in v0.10.0 

func (q *Queries) InsertSessionPlaceholder(ctx context.Context, arg InsertSessionPlaceholderParams) (pgtype.UUID, error)

Insert the minimal-fields placeholder row used when the envelope names a fork-parent whose own first turn hasn't landed yet. The caller supplies the UUID; on natural-key conflict, the existing row's id is returned so the FK back-fills naturally when the parent's first real request lands.

Note: this uses `ON CONFLICT ... DO UPDATE SET last_seen_at = last_seen_at` (a no-op write) instead of DO NOTHING so the RETURNING clause still emits the existing row's id — sqlc/pgx treats DO NOTHING RETURNING as "no rows" on conflict.

func (*Queries) ListChangedSpanTurns added in v0.30.0 

func (q *Queries) ListChangedSpanTurns(ctx context.Context, arg ListChangedSpanTurnsParams) ([]ListChangedSpanTurnsRow, error)

Change feed over the turn projection: rows whose content changed after `after_cursor`, in cursor order.

The upper bound is the correctness of this query, not an optimisation. derive_seq holds the writing transaction's id, and everything below pg_snapshot_xmin(pg_current_snapshot()) has committed by definition — so excluding the rest means a pass that is still open cannot commit "behind" a cursor the consumer has already advanced past. Drop the bound and a concurrent derive that commits late is skipped permanently.

Consumers checkpoint on the largest derive_seq they have processed and pass it back as after_cursor. Rows from an in-flight pass are withheld until it commits, then delivered in order: latency, not loss.

func (*Queries) ListChangedSpans added in v0.30.0 

func (q *Queries) ListChangedSpans(ctx context.Context, arg ListChangedSpansParams) ([]ListChangedSpansRow, error)

Change feed over the span projection. Same contract and the same bound as ListChangedSpanTurns — see that query for why the upper bound is not optional.

func (*Queries) ListDeriveDirty added in v0.16.0 

func (q *Queries) ListDeriveDirty(ctx context.Context, arg ListDeriveDirtyParams) ([]DeriveQueue, error)

The worker's poll: sessions whose dirty mark has settled (no new raw turn since the debounce window) OR whose first mark has waited past the max-lag bound — a streaming session re-marks continuously and would otherwise never settle. Oldest first.

func (*Queries) ListRawTurnHeadersBySession added in v0.16.0 

func (q *Queries) ListRawTurnHeadersBySession(ctx context.Context, arg ListRawTurnHeadersBySessionParams) ([]ListRawTurnHeadersBySessionRow, error)

Operator wire log: identity + sizes, no payloads. The raw layer is the capture truth; this surfaces it without shipping the blobs.

func (*Queries) ListRawTurnIndex added in v0.16.0 

func (q *Queries) ListRawTurnIndex(ctx context.Context, arg ListRawTurnIndexParams) ([]ListRawTurnIndexRow, error)

Lightweight scan for the deriver's ordering pass: identity and timing only, no payloads. meta rides along because it carries the original capture time for backfilled rows.

func (*Queries) ListRawTurnIndexBySession added in v0.16.0 

func (q *Queries) ListRawTurnIndexBySession(ctx context.Context, arg ListRawTurnIndexBySessionParams) ([]ListRawTurnIndexBySessionRow, error)

Payload-free index of one harness session's raw turns, for the session-scoped deriver's ordering pass. Full rows are then streamed one at a time via GetRawTurn — same memory discipline as the full-org pass.

func (*Queries) ListRawTurns added in v0.16.0 

func (q *Queries) ListRawTurns(ctx context.Context, arg ListRawTurnsParams) ([]ListRawTurnsRow, error)

Keyset-paginated scan in insertion order, for the re-runnable deriver. Pass after_id = 0 to start from the beginning.

func (*Queries) ListRawTurnsBySession added in v0.16.0 

func (q *Queries) ListRawTurnsBySession(ctx context.Context, arg ListRawTurnsBySessionParams) ([]ListRawTurnsBySessionRow, error)

Every raw turn captured for one harness session, in insertion order.

func (*Queries) ListSessionsByHarnessSessionID added in v0.36.0 

func (q *Queries) ListSessionsByHarnessSessionID(ctx context.Context, arg ListSessionsByHarnessSessionIDParams) ([]Session, error)

Exact-match filter on harness_session_id alone, across every harness in the org. The id is unique within a harness (sessions_harness_uq), so this returns at most one row per harness that has seen it — in practice zero or one. Ordered by harness_id so the cross-harness collision case is deterministic.

func (*Queries) ListSessionsForRederive added in v0.30.0 

func (q *Queries) ListSessionsForRederive(ctx context.Context) ([]ListSessionsForRederiveRow, error)

Whole-store rederive enumerates persisted identities, including sessions whose last effective raw turn was repaired away, so their stale projection is still covered and pruned.

func (*Queries) ListSpanLinksBySession added in v0.16.0 

func (q *Queries) ListSpanLinksBySession(ctx context.Context, sessionID pgtype.UUID) ([]SpanLinks20260615, error)

Ordered by the unique key (org_id is constant within a session), so the session-scoped links array is deterministic across reads and re-derives — a heap-order scan otherwise shuffles the wire on every upsert.

func (*Queries) ListSpanLinksByTrace added in v0.16.0 

func (q *Queries) ListSpanLinksByTrace(ctx context.Context, arg ListSpanLinksByTraceParams) ([]SpanLinks20260615, error)

func (*Queries) ListSpanTurns added in v0.16.0 

func (q *Queries) ListSpanTurns(ctx context.Context, arg ListSpanTurnsParams) ([]SpanTurns20260615, error)

func (*Queries) ListSpanTurnsBySession added in v0.16.0 

func (q *Queries) ListSpanTurnsBySession(ctx context.Context, sessionID pgtype.UUID) ([]SpanTurns20260615, error)

Span model reads.

func (*Queries) ListSpansBySession added in v0.16.0 

func (q *Queries) ListSpansBySession(ctx context.Context, sessionID pgtype.UUID) ([]Spans20260615, error)

seq is the deriver's emit ordinal (presentation order); started_at/ span_id only break ties for pre-seq rows that haven't re-derived.

func (*Queries) ListSpansByTrace added in v0.16.0 

func (q *Queries) ListSpansByTrace(ctx context.Context, arg ListSpansByTraceParams) ([]Spans20260615, error)

func (*Queries) ListTraceSummariesBySession added in v0.16.0 

func (q *Queries) ListTraceSummariesBySession(ctx context.Context, sessionID pgtype.UUID) ([]ListTraceSummariesBySessionRow, error)

Session detail's lazy view: turn headers only, no span payloads.

func (*Queries) MarkDeriveDirty added in v0.16.0 

func (q *Queries) MarkDeriveDirty(ctx context.Context, arg MarkDeriveDirtyParams) error

Mark one harness session dirty for the derive worker. Upsert: a session already queued just gets its dirtied_at bumped, which is exactly the debounce signal (the worker waits for dirtied_at to settle before deriving).

func (*Queries) NextDeriveSeq added in v0.30.0 

func (q *Queries) NextDeriveSeq(ctx context.Context) (int64, error)

One cursor value per derive pass: the derive transaction's own id. Every row the pass changes is stamped with it, so a consumer that has seen value N has seen a whole pass, never half of one.

It is a transaction id rather than a sequence value on purpose. Any cursor allocated inside a transaction is assigned at write time, not commit time, so concurrent passes can commit out of cursor order — which makes a plain `> cursor` poll lossy no matter what the cursor is drawn from. The difference is that Postgres will tell you which *transactions* are still in flight and will not tell you that about a sequence: everything below pg_snapshot_xmin(pg_current_snapshot()) is committed by definition, so a reader bounded by it can never be overtaken. That bound is only expressible if the cursor is the transaction id, which is why this is not nextval().

Read through ListChangedSpanTurns / ListChangedSpans rather than rolling the bound by hand. See the 1781470000 migration for the full argument. 

func (q *Queries) PruneSpanLinks(ctx context.Context, arg PruneSpanLinksParams) (int64, error)

Same tuple-membership guard as PruneSpans: the six link key columns carry wire ids and cannot be safely '|'-joined into one string.

func (*Queries) PruneSpanTurns added in v0.16.0 

func (q *Queries) PruneSpanTurns(ctx context.Context, arg PruneSpanTurnsParams) (int64, error)

Deterministic ids make prune a no-op on unchanged raw; rows fall out only when the projection stops producing their key.

func (*Queries) PruneSpans added in v0.16.0 

func (q *Queries) PruneSpans(ctx context.Context, arg PruneSpansParams) (int64, error)

Keep-set membership is a tuple test over parallel arrays, NOT a delimiter-joined string: trace_id/span_id embed externally-supplied wire ids (request_id, tool_use_id) that can contain any byte, so a '|' delimiter would collapse distinct (trace, span) pairs and delete the wrong row inside the derive tx.

func (*Queries) RawTurnFidelityByIDs added in v0.30.0 

func (q *Queries) RawTurnFidelityByIDs(ctx context.Context, ids []int64) ([]RawTurnFidelityByIDsRow, error)

Provenance tier for a set of raw turns, for stamping the span projection.

The projection needs to know whether each row can be re-derived from stored bytes, which is a fact about how the turn was captured — not something the deriver can know, since it is a pure function of the rows it is handed and must not read storage state. Resolving it here keeps that separation while still letting the write stamp it. COALESCE so the column types as a plain bool rather than a nullable one: the predicate cannot actually be NULL, and a three-valued result would push an "unknown" case into the caller that has no meaning here.

func (*Queries) SessionIDByHarnessKey added in v0.16.0 

func (q *Queries) SessionIDByHarnessKey(ctx context.Context, arg SessionIDByHarnessKeyParams) (pgtype.UUID, error)

Resolve the sessions row for one raw turn's natural key. The deriver only attributes to existing sessions; it never creates them.

func (*Queries) SetSessionParent added in v0.30.0 

func (q *Queries) SetSessionParent(ctx context.Context, arg SetSessionParentParams) error

Repair supplies complete effective lineage and may deliberately clear it.

func (*Queries) SweepDeriveDirty added in v0.16.0 

func (q *Queries) SweepDeriveDirty(ctx context.Context, activeSince pgtype.Timestamptz) (int64, error)

The worker's slow backstop: enqueue every harness session with raw activity since active_since. Bounding to recently-active sessions keeps a worker restart in a large org from stampeding the queue with the entire raw-layer history; passing the zero time sweeps everything (the unbounded escape hatch). Sessions already queued keep their dirtied_at (DO NOTHING, not an upsert) so the sweep never resets an in-flight debounce window. Everything still funnels through the per-session locked derive path — the sweep itself never writes nodes, which is what makes it safe to run concurrently with session derives.

func (*Queries) UpdateSessionDerivedTitle added in v0.16.0 

func (q *Queries) UpdateSessionDerivedTitle(ctx context.Context, arg UpdateSessionDerivedTitleParams) error

Fold the title-gen shadow call's output onto the session. Written at capture time when the title call lands, and again on re-derive — idempotent either way.

func (*Queries) UpdateSessionDisplayName added in v0.27.0 

func (q *Queries) UpdateSessionDisplayName(ctx context.Context, arg UpdateSessionDisplayNameParams) (int64, error)

User-driven rename of a session's display title (Console edit affordance). Writes the dedicated `display_name` column — NOT `name`. `name` carries the harness-supplied session slug, which ingest re-sends on every turn (UpsertSession COALESCEs it back in), so a rename written there is clobbered on the next turn of a live session and also masks the derived title (PCC-970). display_name is touched only here, never by ingest, so a user's title is durable. Org-scoped in the WHERE clause (never just by id) so a cross-org id can never be updated; :execrows returns the affected-row count, which the caller uses to distinguish a successful update from an unknown/foreign id (0 rows). A NULL clears back to the derived/auto title (the read layer resolves the fallback).

func (*Queries) UpdateSessionKindCounts added in v0.25.0 

func (q *Queries) UpdateSessionKindCounts(ctx context.Context, arg UpdateSessionKindCountsParams) error

Write the per-call_kind span tally onto the session as a JSONB object. Re-derive overwrites it idempotently.

func (*Queries) UpdateSessionModelUsage added in v0.16.0 

func (q *Queries) UpdateSessionModelUsage(ctx context.Context, arg UpdateSessionModelUsageParams) error

Fold the per-model spend breakdown onto the session (#28). Unlike the token/cost rollups (a pure SQL fold over span_turns), this is priced per model in Go at derive time — the price table lives there, not in SQL — so the deriver writes it directly as a JSONB array. Re-derive overwrites it idempotently.

func (*Queries) UpdateSessionStatus added in v0.13.0 

func (q *Queries) UpdateSessionStatus(ctx context.Context, arg UpdateSessionStatusParams) error

Persist the recomputed chain-aware status. has_git_activity is a sticky flag and tool_result_count / tool_error_count are cumulative totals, folded over the session's tool spans across every thread. The deriver computes the values in Go via pkg/derive.FoldSessionStatus, so this query just writes them. derived_status mirrors pkg/sessions.DetermineStatus over those signals and the session's terminal main-spine span. Called only by the deriver (writeSpanSet) during the derive pass — the ingest path no longer writes status.

func (*Queries) UpdateSessionTasks added in v0.25.0 

func (q *Queries) UpdateSessionTasks(ctx context.Context, arg UpdateSessionTasksParams) error

Fold the TaskCreate/TaskUpdate replay onto the session. Like model_usage this is a Go-side fold (it depends on regex id extraction SQL can't do), written as a JSONB array. Re-derive overwrites it idempotently.

func (*Queries) UpsertSession added in v0.10.0 

func (q *Queries) UpsertSession(ctx context.Context, arg UpsertSessionParams) (Session, error)

Insert-or-merge keyed by the natural identity (org_id, harness_id, harness_session_id). The caller supplies the UUID for `id` (Postgres 17 has no native UUIDv7, so ingest mints one app-side); on conflict the existing row's id is preserved via RETURNING.

On conflict, mutable fields are merged: last_seen_at is bumped to the caller-supplied `now`, harness_metadata is JSON-merged (last-write-wins per key), and name is updated only when the new value is non-null. auth_subject is overwritten with the caller-supplied value: when a child session's first turn arrived before the parent's, InsertSessionPlaceholder wrote the parent row carrying the *child's* auth_subject; the parent's real upsert here is authoritative and must reclaim attribution. Counters are NOT touched here — the derive-time span fold (FoldSessionRollupsFromSpans) owns the token/turn/cost rollups.

func (*Queries) UpsertSessionForAttributionRepair added in v0.30.0 

func (q *Queries) UpsertSessionForAttributionRepair(ctx context.Context, arg UpsertSessionForAttributionRepairParams) (Session, error)

Materialize the corrected session identity and expand its liveness range from the repaired raw turn. LEAST/GREATEST make retries and out-of-order repairs idempotent. A missing repair subject must not erase a subject already attached to the target session.

func (*Queries) UpsertSpan added in v0.16.0 

func (q *Queries) UpsertSpan(ctx context.Context, arg UpsertSpanParams) error
func (q *Queries) UpsertSpanLink(ctx context.Context, arg UpsertSpanLinkParams) error

func (*Queries) UpsertSpanTurn added in v0.16.0 

func (q *Queries) UpsertSpanTurn(ctx context.Context, arg UpsertSpanTurnParams) error

Span model writes. Span identity is deterministic (minted from wire identity by the deriver), so re-derivation upserts the same keys in place and prune removes only rows a superseded projection wrote.

func (*Queries) WithTx 

func (q *Queries) WithTx(tx pgx.Tx) *Queries

type RawTurn added in v0.16.0 

type RawTurn struct {
	ID                  int64
	OrgID               pgtype.UUID
	Source              string
	Provider            string
	AgentName           string
	HarnessID           string
	HarnessSessionID    string
	RequestID           string
	RawRequest          []byte
	Response            []byte
	Meta                []byte
	SessionEnvelope     []byte
	ReceivedAt          pgtype.Timestamptz
	RawResponse         []byte
	RawResponseEncoding string
	RawResponseDropped  bool
}

type RawTurnAttributionCorrection added in v0.30.0 

type RawTurnAttributionCorrection struct {
	ID                     int64
	OrgID                  pgtype.UUID
	RawTurnID              int64
	HarnessID              string
	HarnessSessionID       string
	ThreadID               string
	ParentHarnessSessionID pgtype.Text
	Reason                 string
	CreatedAt              pgtype.Timestamptz
}

type RawTurnFidelityByIDsRow added in v0.30.0 

type RawTurnFidelityByIDsRow struct {
	ID                 int64
	HasRawResponse     bool
	RawResponseDropped bool
}

type Session added in v0.10.0 

type Session struct {
	ID                pgtype.UUID
	OrgID             pgtype.UUID
	AuthSubject       string
	HarnessID         string
	HarnessSessionID  string
	Name              pgtype.Text
	Cwd               pgtype.Text
	HarnessVersion    pgtype.Text
	ParentSessionID   pgtype.UUID
	StartedAt         pgtype.Timestamptz
	LastSeenAt        pgtype.Timestamptz
	EndedAt           pgtype.Timestamptz
	HarnessMetadata   []byte
	TotalInputTokens  int64
	TotalOutputTokens int64
	TotalCostUsd      pgtype.Numeric
	TurnCount         int32
	DerivedStatus     string
	HasGitActivity    bool
	ToolResultCount   int32
	ToolErrorCount    int32
	DerivedTitle      pgtype.Text
	DerivedModel      string
	ModelUsage        []byte
	TotalTokens       pgtype.Int8
	DurationNs        pgtype.Int8
	Tasks             []byte
	KindCounts        []byte
	DisplayName       pgtype.Text
}

type SessionIDByHarnessKeyParams added in v0.16.0 

type SessionIDByHarnessKeyParams struct {
	OrgID            pgtype.UUID
	HarnessID        string
	HarnessSessionID string
}

type SetSessionParentParams added in v0.30.0 

type SetSessionParentParams struct {
	ParentSessionID pgtype.UUID
	ID              pgtype.UUID
}

type SpanLinks20260615 added in v0.17.0 

type SpanLinks20260615 struct {
	OrgID       pgtype.UUID
	FromTraceID string
	FromSpanID  string
	FromIo      string
	ToTraceID   string
	ToSpanID    string
	ToIo        string
	Kind        string
	SessionID   pgtype.UUID
}

Derived span-link projection schema version 2026-06-15.

type SpanTurns20260615 added in v0.17.0 

type SpanTurns20260615 struct {
	OrgID               pgtype.UUID
	TraceID             string
	SessionID           pgtype.UUID
	UserPrompt          string
	Synthetic           string
	Status              string
	StartedAt           pgtype.Timestamptz
	EndedAt             pgtype.Timestamptz
	DurationNs          int64
	TotalInputTokens    int64
	TotalOutputTokens   int64
	TotalCostUsd        pgtype.Numeric
	MainInputTokens     int64
	MainOutputTokens    int64
	CacheReadTokens     int64
	CacheCreationTokens int64
	ResponsePreview     string
	Source              string
	ContentHash         string
	DeriveSeq           int64
	Fidelity            string
	ToolCalls           int64
}

Derived span-turn projection schema version 2026-06-15.

type Spans20260615 added in v0.17.0 

type Spans20260615 struct {
	OrgID        pgtype.UUID
	TraceID      string
	SpanID       string
	ParentSpanID string
	SessionID    pgtype.UUID
	Kind         string
	Name         string
	Status       string
	CallKind     string
	ThreadID     string
	Model        string
	StopReason   string
	StartedAt    pgtype.Timestamptz
	DurationNs   int64
	Input        []byte
	Output       []byte
	Usage        []byte
	RawTurnID    pgtype.Int8
	NodeHash     string
	Seq          int64
	Verdict      []byte
	ContentHash  string
	DeriveSeq    int64
	Fidelity     string
}

Derived span projection schema version 2026-06-15.

type TapesV1Session added in v0.35.0 

type TapesV1Session struct {
	ID                pgtype.UUID
	OrgID             pgtype.UUID
	AuthSubject       string
	HarnessID         string
	HarnessSessionID  string
	Name              pgtype.Text
	Cwd               pgtype.Text
	HarnessVersion    pgtype.Text
	ParentSessionID   pgtype.UUID
	StartedAt         pgtype.Timestamptz
	LastSeenAt        pgtype.Timestamptz
	EndedAt           pgtype.Timestamptz
	HarnessMetadata   []byte
	TotalInputTokens  int64
	TotalOutputTokens int64
	TotalCostUsd      pgtype.Numeric
	TurnCount         int32
	DerivedStatus     string
	HasGitActivity    bool
	ToolResultCount   int32
	ToolErrorCount    int32
	DerivedTitle      pgtype.Text
	DerivedModel      string
	ModelUsage        []byte
	TotalTokens       pgtype.Int8
	DurationNs        pgtype.Int8
	Tasks             []byte
	KindCounts        []byte
	DisplayName       pgtype.Text
}

v1 contract view over the sessions table.

type TapesV1Span added in v0.35.0 

type TapesV1Span struct {
	OrgID        pgtype.UUID
	TraceID      string
	SpanID       string
	ParentSpanID string
	SessionID    pgtype.UUID
	Kind         string
	Name         string
	Status       string
	CallKind     string
	ThreadID     string
	Model        string
	StopReason   string
	StartedAt    pgtype.Timestamptz
	DurationNs   int64
	Input        []byte
	Output       []byte
	Usage        []byte
	RawTurnID    pgtype.Int8
	NodeHash     string
	Seq          int64
	Verdict      []byte
	ContentHash  string
	DeriveSeq    int64
	Fidelity     string
}

v1 contract view over the current span projection generation (see derived_projection_schemas). 

type TapesV1SpanLink struct {
	OrgID       pgtype.UUID
	FromTraceID string
	FromSpanID  string
	FromIo      string
	ToTraceID   string
	ToSpanID    string
	ToIo        string
	Kind        string
	SessionID   pgtype.UUID
}

v1 contract view over the current span-link projection generation (see derived_projection_schemas).

type TapesV1SpanTurn added in v0.35.0 

type TapesV1SpanTurn struct {
	OrgID               pgtype.UUID
	TraceID             string
	SessionID           pgtype.UUID
	UserPrompt          string
	Synthetic           string
	Status              string
	StartedAt           pgtype.Timestamptz
	EndedAt             pgtype.Timestamptz
	DurationNs          int64
	TotalInputTokens    int64
	TotalOutputTokens   int64
	TotalCostUsd        pgtype.Numeric
	MainInputTokens     int64
	MainOutputTokens    int64
	CacheReadTokens     int64
	CacheCreationTokens int64
	ResponsePreview     string
	Source              string
	ContentHash         string
	DeriveSeq           int64
	Fidelity            string
}

v1 contract view over the current span-turn projection generation (see derived_projection_schemas).

type UpdateSessionDerivedTitleParams added in v0.16.0 

type UpdateSessionDerivedTitleParams struct {
	DerivedTitle pgtype.Text
	ID           pgtype.UUID
}

type UpdateSessionDisplayNameParams added in v0.27.0 

type UpdateSessionDisplayNameParams struct {
	DisplayName pgtype.Text
	ID          pgtype.UUID
	OrgID       pgtype.UUID
}

type UpdateSessionKindCountsParams added in v0.25.0 

type UpdateSessionKindCountsParams struct {
	KindCounts []byte
	ID         pgtype.UUID
}

type UpdateSessionModelUsageParams added in v0.16.0 

type UpdateSessionModelUsageParams struct {
	ModelUsage []byte
	ID         pgtype.UUID
}

type UpdateSessionStatusParams added in v0.13.0 

type UpdateSessionStatusParams struct {
	HasGitActivity  bool
	ToolResultCount int32
	ToolErrorCount  int32
	DerivedStatus   string
	ID              pgtype.UUID
}

type UpdateSessionTasksParams added in v0.25.0 

type UpdateSessionTasksParams struct {
	Tasks []byte
	ID    pgtype.UUID
}

type UpsertSessionForAttributionRepairParams added in v0.30.0 

type UpsertSessionForAttributionRepairParams struct {
	ID               pgtype.UUID
	OrgID            pgtype.UUID
	AuthSubject      string
	HarnessID        string
	HarnessSessionID string
	Name             pgtype.Text
	Cwd              pgtype.Text
	HarnessVersion   pgtype.Text
	ParentSessionID  pgtype.UUID
	CapturedAt       pgtype.Timestamptz
	HarnessMetadata  []byte
}

type UpsertSessionParams added in v0.10.0 

type UpsertSessionParams struct {
	ID               pgtype.UUID
	OrgID            pgtype.UUID
	AuthSubject      string
	HarnessID        string
	HarnessSessionID string
	Name             pgtype.Text
	Cwd              pgtype.Text
	HarnessVersion   pgtype.Text
	ParentSessionID  pgtype.UUID
	Now              pgtype.Timestamptz
	HarnessMetadata  []byte
}

type UpsertSpanLinkParams added in v0.16.0 

type UpsertSpanLinkParams struct {
	OrgID       pgtype.UUID
	FromTraceID string
	FromSpanID  string
	FromIo      string
	ToTraceID   string
	ToSpanID    string
	ToIo        string
	Kind        string
	SessionID   pgtype.UUID
}

type UpsertSpanParams added in v0.16.0 

type UpsertSpanParams struct {
	OrgID        pgtype.UUID
	TraceID      string
	SpanID       string
	ParentSpanID string
	SessionID    pgtype.UUID
	Kind         string
	Name         string
	Status       string
	CallKind     string
	ThreadID     string
	Model        string
	StopReason   string
	StartedAt    pgtype.Timestamptz
	DurationNs   int64
	Seq          int64
	Input        []byte
	Output       []byte
	Usage        []byte
	RawTurnID    pgtype.Int8
	NodeHash     string
	Verdict      []byte
	ContentHash  string
	DeriveSeq    int64
	Fidelity     string
}

type UpsertSpanTurnParams added in v0.16.0 

type UpsertSpanTurnParams struct {
	OrgID               pgtype.UUID
	TraceID             string
	SessionID           pgtype.UUID
	UserPrompt          string
	ResponsePreview     string
	Synthetic           string
	Status              string
	StartedAt           pgtype.Timestamptz
	EndedAt             pgtype.Timestamptz
	DurationNs          int64
	TotalInputTokens    int64
	TotalOutputTokens   int64
	MainInputTokens     int64
	MainOutputTokens    int64
	CacheReadTokens     int64
	CacheCreationTokens int64
	TotalCostUsd        pgtype.Numeric
	Source              string
	ToolCalls           int64
	ContentHash         string
	DeriveSeq           int64
	Fidelity            string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.