Documentation
¶
Index ¶
- type AggregateSessionsByModelParams
- type AggregateSessionsByModelRow
- type AggregateSessionsParams
- type AggregateSessionsRow
- type AggregateSpanStatsParams
- type AggregateSpanStatsRow
- type AncestryChainsParams
- type AncestryChainsRow
- type ClearDeriveDirtyParams
- type CountSkillsParams
- type CountSkillsRow
- type CreateSkillVersionParams
- type DBTX
- type DeleteSessionParams
- type DeleteSkillParams
- type DeleteSkillVersionsParams
- type DeriveQueue
- type DeriveQueueStatsRow
- type DerivedProjectionSchema
- type GetDeriveDirtyParams
- type GetSessionByNaturalKeyParams
- type GetSessionRecordParams
- type GetSkillByIDParams
- type GetSpanParams
- type GetSpanTurnParams
- type IncrementSkillDownloadsParams
- type InsertNodeParams
- type InsertRawTurnParams
- type InsertSessionPlaceholderParams
- type ListDeriveDirtyParams
- type ListParentRefsRow
- type ListRawTurnHeadersBySessionParams
- type ListRawTurnHeadersBySessionRow
- type ListRawTurnIndexBySessionParams
- type ListRawTurnIndexBySessionRow
- type ListRawTurnIndexParams
- type ListRawTurnIndexRow
- type ListRawTurnsBySessionParams
- type ListRawTurnsParams
- type ListSessionSkillsParams
- type ListSessionsParams
- type ListSkillVersionsParams
- type ListSkillsPageByDownloadsParams
- type ListSkillsPageParams
- type ListSpanLinksByTraceParams
- type ListSpanTurnsParams
- type ListSpansByTraceParams
- type ListTraceSummariesBySessionRow
- type MarkDeriveDirtyParams
- type MaxSkillVersionNumberParams
- type Node
- type PruneDerivedNodesParams
- type PruneSpanLinksParams
- type PruneSpanTurnsParams
- type PruneSpansParams
- type Queries
- func (q *Queries) AggregateSessions(ctx context.Context, arg AggregateSessionsParams) (AggregateSessionsRow, error)
- func (q *Queries) AggregateSessionsByModel(ctx context.Context, arg AggregateSessionsByModelParams) ([]AggregateSessionsByModelRow, error)
- func (q *Queries) AggregateSpanStats(ctx context.Context, arg AggregateSpanStatsParams) (AggregateSpanStatsRow, error)
- func (q *Queries) AncestryChains(ctx context.Context, arg AncestryChainsParams) ([]AncestryChainsRow, error)
- func (q *Queries) ClearDeriveDirty(ctx context.Context, arg ClearDeriveDirtyParams) (int64, error)
- func (q *Queries) CountRawTurns(ctx context.Context) (int64, error)
- func (q *Queries) CountSkills(ctx context.Context, arg CountSkillsParams) (CountSkillsRow, error)
- func (q *Queries) CreateSkillVersion(ctx context.Context, arg CreateSkillVersionParams) (SkillVersion, error)
- func (q *Queries) DeleteSession(ctx context.Context, arg DeleteSessionParams) (int64, error)
- func (q *Queries) DeleteSkill(ctx context.Context, arg DeleteSkillParams) (int64, error)
- func (q *Queries) DeleteSkillVersions(ctx context.Context, arg DeleteSkillVersionsParams) error
- func (q *Queries) DeriveQueueStats(ctx context.Context) (DeriveQueueStatsRow, error)
- func (q *Queries) DuckdbForceExecution(ctx context.Context) error
- func (q *Queries) FoldSessionRollupsFromSpans(ctx context.Context, sessionIds []pgtype.UUID) error
- func (q *Queries) GetDeriveDirty(ctx context.Context, arg GetDeriveDirtyParams) (DeriveQueue, error)
- func (q *Queries) GetNode(ctx context.Context, hash string) (Node, error)
- func (q *Queries) GetNodesByParent(ctx context.Context, parentHash pgtype.Text) ([]Node, error)
- func (q *Queries) GetRawTurn(ctx context.Context, id int64) (RawTurn, error)
- func (q *Queries) GetRootNodes(ctx context.Context) ([]Node, error)
- func (q *Queries) GetSessionByNaturalKey(ctx context.Context, arg GetSessionByNaturalKeyParams) (Session, error)
- func (q *Queries) GetSessionRecord(ctx context.Context, arg GetSessionRecordParams) (Session, error)
- func (q *Queries) GetSkillByID(ctx context.Context, arg GetSkillByIDParams) (Skill, error)
- func (q *Queries) GetSpan(ctx context.Context, arg GetSpanParams) (Spans20260615, error)
- func (q *Queries) GetSpanTurn(ctx context.Context, arg GetSpanTurnParams) (SpanTurns20260615, error)
- func (q *Queries) HasNode(ctx context.Context, hash string) (bool, error)
- func (q *Queries) IncrementSkillDownloads(ctx context.Context, arg IncrementSkillDownloadsParams) error
- func (q *Queries) InsertNode(ctx context.Context, arg InsertNodeParams) (int64, error)
- func (q *Queries) InsertRawTurn(ctx context.Context, arg InsertRawTurnParams) (int64, error)
- func (q *Queries) InsertSessionPlaceholder(ctx context.Context, arg InsertSessionPlaceholderParams) (pgtype.UUID, error)
- func (q *Queries) ListDeriveDirty(ctx context.Context, arg ListDeriveDirtyParams) ([]DeriveQueue, error)
- func (q *Queries) ListLeaves(ctx context.Context) ([]Node, error)
- func (q *Queries) ListNodes(ctx context.Context) ([]Node, error)
- func (q *Queries) ListNodesBySession(ctx context.Context, sessionID pgtype.UUID) ([]Node, error)
- func (q *Queries) ListParentRefs(ctx context.Context) ([]ListParentRefsRow, error)
- func (q *Queries) ListRawTurnHeadersBySession(ctx context.Context, arg ListRawTurnHeadersBySessionParams) ([]ListRawTurnHeadersBySessionRow, error)
- func (q *Queries) ListRawTurnIndex(ctx context.Context, arg ListRawTurnIndexParams) ([]ListRawTurnIndexRow, error)
- func (q *Queries) ListRawTurnIndexBySession(ctx context.Context, arg ListRawTurnIndexBySessionParams) ([]ListRawTurnIndexBySessionRow, error)
- func (q *Queries) ListRawTurns(ctx context.Context, arg ListRawTurnsParams) ([]RawTurn, error)
- func (q *Queries) ListRawTurnsBySession(ctx context.Context, arg ListRawTurnsBySessionParams) ([]RawTurn, error)
- func (q *Queries) ListSessionSkills(ctx context.Context, arg ListSessionSkillsParams) ([]Skill, error)
- func (q *Queries) ListSessions(ctx context.Context, arg ListSessionsParams) ([]Node, error)
- func (q *Queries) ListSkillVersions(ctx context.Context, arg ListSkillVersionsParams) ([]SkillVersion, error)
- func (q *Queries) ListSkillsPage(ctx context.Context, arg ListSkillsPageParams) ([]Skill, error)
- func (q *Queries) ListSkillsPageByDownloads(ctx context.Context, arg ListSkillsPageByDownloadsParams) ([]Skill, error)
- func (q *Queries) ListSpanLinksBySession(ctx context.Context, sessionID pgtype.UUID) ([]SpanLinks20260615, error)
- func (q *Queries) ListSpanLinksByTrace(ctx context.Context, arg ListSpanLinksByTraceParams) ([]SpanLinks20260615, error)
- func (q *Queries) ListSpanTurns(ctx context.Context, arg ListSpanTurnsParams) ([]SpanTurns20260615, error)
- func (q *Queries) ListSpanTurnsBySession(ctx context.Context, sessionID pgtype.UUID) ([]SpanTurns20260615, error)
- func (q *Queries) ListSpansBySession(ctx context.Context, sessionID pgtype.UUID) ([]Spans20260615, error)
- func (q *Queries) ListSpansByTrace(ctx context.Context, arg ListSpansByTraceParams) ([]Spans20260615, error)
- func (q *Queries) ListTraceSummariesBySession(ctx context.Context, sessionID pgtype.UUID) ([]ListTraceSummariesBySessionRow, error)
- func (q *Queries) MarkDeriveDirty(ctx context.Context, arg MarkDeriveDirtyParams) error
- func (q *Queries) MaxSkillVersionNumber(ctx context.Context, arg MaxSkillVersionNumberParams) (int32, error)
- func (q *Queries) PruneDerivedNodes(ctx context.Context, arg PruneDerivedNodesParams) (int64, error)
- func (q *Queries) PruneSpanLinks(ctx context.Context, arg PruneSpanLinksParams) (int64, error)
- func (q *Queries) PruneSpanTurns(ctx context.Context, arg PruneSpanTurnsParams) (int64, error)
- func (q *Queries) PruneSpans(ctx context.Context, arg PruneSpansParams) (int64, error)
- func (q *Queries) SessionIDByHarnessKey(ctx context.Context, arg SessionIDByHarnessKeyParams) (pgtype.UUID, error)
- func (q *Queries) SetNodeSessionID(ctx context.Context, arg SetNodeSessionIDParams) error
- func (q *Queries) SetSkillVersion(ctx context.Context, arg SetSkillVersionParams) error
- func (q *Queries) SweepDeriveDirty(ctx context.Context, activeSince pgtype.Timestamptz) (int64, error)
- func (q *Queries) UpdateSessionCounters(ctx context.Context, arg UpdateSessionCountersParams) error
- func (q *Queries) UpdateSessionDerivedTitle(ctx context.Context, arg UpdateSessionDerivedTitleParams) error
- func (q *Queries) UpdateSessionModelUsage(ctx context.Context, arg UpdateSessionModelUsageParams) error
- func (q *Queries) UpdateSessionStatus(ctx context.Context, arg UpdateSessionStatusParams) error
- func (q *Queries) UpdateUsage(ctx context.Context, arg UpdateUsageParams) error
- func (q *Queries) UpsertDerivedNode(ctx context.Context, arg UpsertDerivedNodeParams) (int64, error)
- func (q *Queries) UpsertSession(ctx context.Context, arg UpsertSessionParams) (Session, error)
- func (q *Queries) UpsertSkill(ctx context.Context, arg UpsertSkillParams) (Skill, error)
- func (q *Queries) UpsertSpan(ctx context.Context, arg UpsertSpanParams) error
- func (q *Queries) UpsertSpanLink(ctx context.Context, arg UpsertSpanLinkParams) error
- func (q *Queries) UpsertSpanTurn(ctx context.Context, arg UpsertSpanTurnParams) error
- func (q *Queries) WithTx(tx pgx.Tx) *Queries
- type RawTurn
- type Session
- type SessionIDByHarnessKeyParams
- type SetNodeSessionIDParams
- type SetSkillVersionParams
- type Skill
- type SkillVersion
- type SpanLinks20260615
- type SpanTurns20260615
- type Spans20260615
- type UpdateSessionCountersParams
- type UpdateSessionDerivedTitleParams
- type UpdateSessionModelUsageParams
- type UpdateSessionStatusParams
- type UpdateUsageParams
- type UpsertDerivedNodeParams
- type UpsertSessionParams
- type UpsertSkillParams
- type UpsertSpanLinkParams
- type UpsertSpanParams
- type UpsertSpanTurnParams
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AggregateSessionsByModelParams ¶ added in v0.8.0
type AggregateSessionsByModelRow ¶ added in v0.8.0
type AggregateSessionsParams ¶ added in v0.8.0
type AggregateSessionsRow ¶ added in v0.8.0
type AggregateSpanStatsParams ¶ added in v0.16.0
type AggregateSpanStatsParams struct {
OrgID pgtype.UUID
SinceFilter pgtype.Timestamptz
UntilFilter pgtype.Timestamptz
}
type AggregateSpanStatsRow ¶ added in v0.16.0
type AncestryChainsParams ¶
type AncestryChainsRow ¶
type AncestryChainsRow struct {
StartHash interface{}
Hash interface{}
ParentHash interface{}
Bucket interface{}
Type interface{}
Role interface{}
Content interface{}
Model interface{}
Provider interface{}
AgentName interface{}
StopReason interface{}
PromptTokens interface{}
CompletionTokens interface{}
TotalTokens interface{}
CacheCreationInputTokens interface{}
CacheReadInputTokens interface{}
TotalDurationNs interface{}
PromptDurationNs interface{}
Project interface{}
CreatedAt pgtype.Timestamptz
Depth int32
HasUsage bool
NodeKind interface{}
ParentToolUseID interface{}
}
type ClearDeriveDirtyParams ¶ added in v0.16.0
type CountSkillsParams ¶ added in v0.20.0
type CountSkillsRow ¶ added in v0.20.0
type CreateSkillVersionParams ¶ added in v0.20.0
type DeleteSessionParams ¶ added in v0.22.0
type DeleteSkillParams ¶ added in v0.20.0
type DeleteSkillVersionsParams ¶ added in v0.20.0
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 GetDeriveDirtyParams ¶ added in v0.16.0
type GetSessionByNaturalKeyParams ¶ added in v0.10.0
type GetSessionRecordParams ¶ added in v0.12.0
type GetSkillByIDParams ¶ added in v0.20.0
type GetSpanParams ¶ added in v0.16.0
type GetSpanTurnParams ¶ added in v0.16.0
type IncrementSkillDownloadsParams ¶ added in v0.20.0
type InsertNodeParams ¶
type InsertNodeParams struct {
OrgID pgtype.UUID
Hash string
Bucket []byte
Type pgtype.Text
Role pgtype.Text
Content []byte
Model pgtype.Text
Provider pgtype.Text
AgentName pgtype.Text
StopReason pgtype.Text
PromptTokens pgtype.Int4
CompletionTokens pgtype.Int4
TotalTokens pgtype.Int4
CacheCreationInputTokens pgtype.Int4
CacheReadInputTokens pgtype.Int4
TotalDurationNs pgtype.Int8
PromptDurationNs pgtype.Int8
Project pgtype.Text
CreatedAt pgtype.Timestamptz
ParentHash pgtype.Text
RequestSystem pgtype.Text
RequestMaxTokens pgtype.Int4
RequestTemperature pgtype.Float8
RequestStream pgtype.Bool
RequestToolCount pgtype.Int4
NodeKind pgtype.Text
ParentToolUseID pgtype.Text
ThreadID pgtype.Text
}
type InsertRawTurnParams ¶ added in v0.16.0
type InsertSessionPlaceholderParams ¶ added in v0.10.0
type ListDeriveDirtyParams ¶ added in v0.16.0
type ListDeriveDirtyParams struct {
DirtiedBefore pgtype.Timestamptz
FirstDirtiedBefore pgtype.Timestamptz
PageSize int32
}
type ListParentRefsRow ¶
type ListRawTurnHeadersBySessionParams ¶ added in v0.16.0
type ListRawTurnHeadersBySessionRow ¶ added in v0.16.0
type ListRawTurnIndexBySessionParams ¶ added in v0.16.0
type ListRawTurnIndexBySessionRow ¶ added in v0.16.0
type ListRawTurnIndexParams ¶ added in v0.16.0
type ListRawTurnIndexRow ¶ added in v0.16.0
type ListRawTurnsBySessionParams ¶ added in v0.16.0
type ListRawTurnsParams ¶ added in v0.16.0
type ListSessionSkillsParams ¶ added in v0.20.0
type ListSessionsParams ¶
type ListSkillVersionsParams ¶ added in v0.20.0
type ListSkillsPageByDownloadsParams ¶ added in v0.20.0
type ListSkillsPageParams ¶ added in v0.20.0
type ListSpanLinksByTraceParams ¶ added in v0.16.0
type ListSpanTurnsParams ¶ added in v0.16.0
type ListSpansByTraceParams ¶ added in v0.16.0
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
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 MaxSkillVersionNumberParams ¶ added in v0.20.0
type Node ¶
type Node struct {
Hash string
Bucket []byte
Type pgtype.Text
Role pgtype.Text
Content []byte
Model pgtype.Text
Provider pgtype.Text
AgentName pgtype.Text
StopReason pgtype.Text
PromptTokens pgtype.Int4
CompletionTokens pgtype.Int4
TotalTokens pgtype.Int4
CacheCreationInputTokens pgtype.Int4
CacheReadInputTokens pgtype.Int4
TotalDurationNs pgtype.Int8
PromptDurationNs pgtype.Int8
Project pgtype.Text
CreatedAt pgtype.Timestamptz
ParentHash pgtype.Text
SessionID pgtype.UUID
OrgID pgtype.UUID
RequestSystem pgtype.Text
RequestMaxTokens pgtype.Int4
RequestTemperature pgtype.Float8
RequestStream pgtype.Bool
RequestToolCount pgtype.Int4
NodeKind pgtype.Text
ParentToolUseID pgtype.Text
ThreadID pgtype.Text
}
type PruneDerivedNodesParams ¶ added in v0.16.0
type PruneSpanLinksParams ¶ added in v0.16.0
type PruneSpanTurnsParams ¶ added in v0.16.0
type PruneSpansParams ¶ added in v0.16.0
type Queries ¶
type Queries struct {
// contains filtered or unexported fields
}
func (*Queries) AggregateSessions ¶ added in v0.8.0
func (q *Queries) AggregateSessions(ctx context.Context, arg AggregateSessionsParams) (AggregateSessionsRow, error)
Single-pass aggregate that powers /v1/stats. SUMs and turn/stem/root counts apply to the set of nodes matching the supplied per-node filters.
session_count and completed_count are session-grained, keyed on the first-class sessions table via nodes.session_id (PCC-565):
session_count = distinct sessions touched by the matching nodes
completed_count = distinct sessions whose denormalized derived_status
is 'completed' (chain-aware, computed at ingest by
pkg/sessions.DetermineStatus — PCC-515)
Nodes with no session_id (legacy / non-session-tracked writers) are not counted as sessions; COUNT(DISTINCT session_id) ignores their NULLs.
stem_count is the leaf count (one per Merkle chain, matching /v1/stems) — the value session_count used to report before the sessions table existed.
total_duration_ns is wall-clock span MAX(created_at) - MIN(created_at) across the matching set, NOT SUM(nodes.total_duration_ns). The nodes.total_duration_ns column is currently never populated by the proxy (verified against jason@'s local store: 0 of 1460 rows have a non-zero value) — see PCC-514. Until that lands, SUMming the column would always return 0, which is misleading; wall-clock span is a meaningful "Agent Time" proxy that doesn't depend on the dead column.
The tool_calls subquery scans content JSONB per node to count tool_use blocks. This is acceptable at current corpus sizes; if it becomes a bottleneck the right next step is denormalizing tool_use_count onto the nodes table at write time.
func (*Queries) AggregateSessionsByModel ¶ added in v0.8.0
func (q *Queries) AggregateSessionsByModel(ctx context.Context, arg AggregateSessionsByModelParams) ([]AggregateSessionsByModelRow, error)
Per-model token rollup that powers the cost fold in /v1/stats. Filters apply per-node, matching aggregate_sessions.sql. Nodes with a NULL or empty model are excluded — they cannot be priced.
The API handler walks these rows, applies pkg/sessions.PricingForModel and pkg/sessions.CostForTokensWithCache to each, and sums into StatsResponse.TotalCost. Pricing intentionally lives in Go.
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
root_count = traces opened by a genuine prompt (synthetic = '')
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 = tool spans_20260615 started in the window
func (*Queries) AncestryChains ¶
func (q *Queries) AncestryChains(ctx context.Context, arg AncestryChainsParams) ([]AncestryChainsRow, error)
func (*Queries) ClearDeriveDirty ¶ added in v0.16.0
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 (*Queries) CountSkills ¶ added in v0.20.0
func (q *Queries) CountSkills(ctx context.Context, arg CountSkillsParams) (CountSkillsRow, error)
Tab counts for the current search: total matching, and how many are authored by the caller. "team" is derived client-side as total - mine. Counts ignore scope and cursor so every tab shows its full size for the active query.
func (*Queries) CreateSkillVersion ¶ added in v0.20.0
func (q *Queries) CreateSkillVersion(ctx context.Context, arg CreateSkillVersionParams) (SkillVersion, error)
Append an immutable published snapshot of a skill's content.
func (*Queries) DeleteSession ¶ added in v0.22.0
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, derived nodes, 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) DeleteSkill ¶ added in v0.20.0
Remove a skill by its org-scoped id. Returns the affected row count so the handler can distinguish a real delete from a missing id.
func (*Queries) DeleteSkillVersions ¶ added in v0.20.0
func (q *Queries) DeleteSkillVersions(ctx context.Context, arg DeleteSkillVersionsParams) error
Remove a skill's published history. skill_versions has no FK cascade to skills, so deleting a skill must drop its versions explicitly.
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) DuckdbForceExecution ¶
func (*Queries) FoldSessionRollupsFromSpans ¶ added in v0.16.0
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) GetNodesByParent ¶
func (*Queries) GetRawTurn ¶ added in v0.16.0
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 (*Queries) GetSkillByID ¶ added in v0.20.0
Org-scoped point read used by GET /v1/skills/:id and the write handlers.
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) IncrementSkillDownloads ¶ added in v0.20.0
func (q *Queries) IncrementSkillDownloads(ctx context.Context, arg IncrementSkillDownloadsParams) error
Bump the real download counter when a skill's SKILL.md is downloaded.
func (*Queries) InsertNode ¶
nodes is keyed by composite PK (org_id, hash) so the same content (e.g. a verbatim system prompt) can land for multiple orgs without the first writer permanently owning the row. Legacy non-session writers pass the nil-UUID (00000000-0000-0000-0000-000000000000) per the migration default; session-aware writers (IngestTurn) pass the validated cloud-trusted org_id.
func (*Queries) InsertRawTurn ¶ added in v0.16.0
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) 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) 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) ListNodesBySession ¶ added in v0.12.0
All nodes attributed to a session, ordered by capture time (chronological).
func (*Queries) ListParentRefs ¶
func (q *Queries) ListParentRefs(ctx context.Context) ([]ListParentRefsRow, error)
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
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) ([]RawTurn, error)
Every raw turn captured for one harness session, in insertion order.
func (*Queries) ListSessionSkills ¶ added in v0.20.0
func (q *Queries) ListSessionSkills(ctx context.Context, arg ListSessionSkillsParams) ([]Skill, error)
Skills generated from a given session (reverse lookup over the provenance array), newest-edited first. Small result set, so no pagination.
func (*Queries) ListSessions ¶
func (*Queries) ListSkillVersions ¶ added in v0.20.0
func (q *Queries) ListSkillVersions(ctx context.Context, arg ListSkillVersionsParams) ([]SkillVersion, error)
func (*Queries) ListSkillsPage ¶ added in v0.20.0
One keyset page of skills for an org, newest-edited first, with optional full-text search (name/description/tags) and author scope. The cursor is the (updated_at, id) of the last row on the previous page; the tiebreak on id keeps pagination stable when updated_at ties. Fetch lim+1 to detect has_more.
func (*Queries) ListSkillsPageByDownloads ¶ added in v0.20.0
func (q *Queries) ListSkillsPageByDownloads(ctx context.Context, arg ListSkillsPageByDownloadsParams) ([]Skill, error)
Same as ListSkillsPage but ordered by most-downloaded. The keyset is (download_count, id); the cursor carries the last row's download_count and id.
func (*Queries) ListSpanLinksBySession ¶ added in v0.16.0
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) MaxSkillVersionNumber ¶ added in v0.20.0
func (q *Queries) MaxSkillVersionNumber(ctx context.Context, arg MaxSkillVersionNumberParams) (int32, error)
Highest version_number for a skill (0 when none published yet).
func (*Queries) PruneDerivedNodes ¶ added in v0.16.0
func (q *Queries) PruneDerivedNodes(ctx context.Context, arg PruneDerivedNodesParams) (int64, error)
Remove derived rows for the given sessions whose hashes are no longer produced by re-deriving the raw layer (e.g. rows written under a superseded projection). Scoped to sessions the deriver actually rebuilt, so legacy sessions without raw coverage are untouched.
func (*Queries) PruneSpanLinks ¶ added in v0.16.0
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
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
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) 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) SetNodeSessionID ¶ added in v0.10.0
func (q *Queries) SetNodeSessionID(ctx context.Context, arg SetNodeSessionIDParams) error
Stamp session_id onto an already-inserted nodes row. The existing InsertNode query is left intact (additive ALTER added the column with no NOT NULL constraint), so ingest can either use this safety hatch or extend InsertNode in a follow-up. Scoped to (org_id, hash) to match the composite PK introduced in this migration: a write that only matched on hash would clobber rows for unrelated orgs.
func (*Queries) SetSkillVersion ¶ added in v0.20.0
func (q *Queries) SetSkillVersion(ctx context.Context, arg SetSkillVersionParams) error
Bump the skill's current published semver (and updated_at) at publish time.
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) UpdateSessionCounters ¶ added in v0.10.0
func (q *Queries) UpdateSessionCounters(ctx context.Context, arg UpdateSessionCountersParams) error
Roll the per-turn counters into the sessions row. Called by ingest after the nodes insert, inside the same Tx.
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) 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, all accumulated across the session's turns and stems — the caller computes the new values in Go from the prior row state plus this turn's new nodes, so this query just writes them. derived_status mirrors pkg/sessions.DetermineStatus over those signals and the session's latest leaf. Called by ingest in the same Tx as UpdateSessionCounters.
func (*Queries) UpdateUsage ¶
func (q *Queries) UpdateUsage(ctx context.Context, arg UpdateUsageParams) error
func (*Queries) UpsertDerivedNode ¶ added in v0.16.0
func (q *Queries) UpsertDerivedNode(ctx context.Context, arg UpsertDerivedNodeParams) (int64, error)
The re-runnable deriver's write: insert a node derived from the raw layer, or — when the content row already exists for this org — refresh only the DERIVED columns (typing, edges, session attribution, promoted request params). bucket/content/usage are part of the content row and never change for a given hash; created_at is preserved on conflict so capture-time chronology survives re-derives.
func (*Queries) UpsertSession ¶ added in v0.10.0
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 — UpdateSessionCounters handles that after the nodes insert in the same Tx.
func (*Queries) UpsertSkill ¶ added in v0.20.0
Insert-or-replace a skill keyed by (org_id, id). Create/generate/duplicate mint a fresh id (a plain insert); PUT and publish pass the existing id (an update). slug is a cosmetic, non-unique display label, so it is overwritten on update like any other mutable field. created_at and author_subject are preserved on conflict (original creation time and creator stay authoritative).
func (*Queries) UpsertSpan ¶ added in v0.16.0
func (q *Queries) UpsertSpan(ctx context.Context, arg UpsertSpanParams) error
func (*Queries) UpsertSpanLink ¶ added in v0.16.0
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.
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
}
type SessionIDByHarnessKeyParams ¶ added in v0.16.0
type SetNodeSessionIDParams ¶ added in v0.10.0
type SetSkillVersionParams ¶ added in v0.20.0
type Skill ¶ added in v0.20.0
type Skill struct {
OrgID pgtype.UUID
Slug string
Name string
Description string
Type string
Version string
Visibility string
Tags []string
Content string
IsAiGenerated bool
GeneratedFromSessionIds []string
CreatedAt pgtype.Timestamptz
UpdatedAt pgtype.Timestamptz
AuthorSubject string
DownloadCount int64
ID pgtype.UUID
ParentID pgtype.UUID
}
type SkillVersion ¶ added in v0.20.0
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
}
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
}
Derived span projection schema version 2026-06-15.
type UpdateSessionCountersParams ¶ added in v0.10.0
type UpdateSessionDerivedTitleParams ¶ added in v0.16.0
type UpdateSessionModelUsageParams ¶ added in v0.16.0
type UpdateSessionStatusParams ¶ added in v0.13.0
type UpdateUsageParams ¶
type UpsertDerivedNodeParams ¶ added in v0.16.0
type UpsertDerivedNodeParams struct {
OrgID pgtype.UUID
Hash string
Bucket []byte
Type pgtype.Text
Role pgtype.Text
Content []byte
Model pgtype.Text
Provider pgtype.Text
AgentName pgtype.Text
StopReason pgtype.Text
PromptTokens pgtype.Int4
CompletionTokens pgtype.Int4
TotalTokens pgtype.Int4
CacheCreationInputTokens pgtype.Int4
CacheReadInputTokens pgtype.Int4
TotalDurationNs pgtype.Int8
PromptDurationNs pgtype.Int8
Project pgtype.Text
CreatedAt pgtype.Timestamptz
ParentHash pgtype.Text
RequestSystem pgtype.Text
RequestMaxTokens pgtype.Int4
RequestTemperature pgtype.Float8
RequestStream pgtype.Bool
RequestToolCount pgtype.Int4
NodeKind pgtype.Text
ParentToolUseID pgtype.Text
SessionID pgtype.UUID
ThreadID pgtype.Text
}
type UpsertSessionParams ¶ added in v0.10.0
type UpsertSkillParams ¶ added in v0.20.0
type UpsertSkillParams struct {
OrgID pgtype.UUID
ID pgtype.UUID
Slug string
Name string
Description string
Type string
Version string
Visibility string
Tags []string
Content string
IsAiGenerated bool
GeneratedFromSessionIds []string
ParentID pgtype.UUID
AuthorSubject string
CreatedAt pgtype.Timestamptz
UpdatedAt pgtype.Timestamptz
}
type UpsertSpanLinkParams ¶ added in v0.16.0
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
}
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 Files
¶
- aggregate_sessions.sql.go
- aggregate_sessions_by_model.sql.go
- ancestry_chains.sql.go
- db.go
- derive.sql.go
- derive_queue.sql.go
- duckdb_force_execution.sql.go
- get_node.sql.go
- get_nodes_by_parent.sql.go
- get_root_nodes.sql.go
- has_node.sql.go
- insert.node.sql.go
- list_leaves.sql.go
- list_nodes.sql.go
- list_parent_refs.sql.go
- list_sessions.sql.go
- models.go
- raw_turns.sql.go
- sessions.sql.go
- skills.sql.go
- spans.sql.go