callrecord

type Artifact struct {
	// Kind is one of the SatisfiedBy values.
	Kind string `json:"kind" example:"asset"`
	ID   string `json:"id" example:"ast_7c1e"`
	Name string `json:"name" example:"Q3 revenue by region"`
}

type Config struct {
	// RetentionDays bounds how long an unused record is kept. Zero or
	// negative takes the default.
	RetentionDays int
}

type CuratedQueryWriter interface {
	CreateCuratedQuery(ctx context.Context, datasetURNs []string, name, sql, description string) (string, error)
}

type Example struct {
	Connection  string
	OperationID string
	Method      string
	Path        string
	Name        string
	Description string
	// CallRecordID is the record the example was promoted from, so the
	// endpoint can lead back to the call that produced it.
	CallRecordID string
	CreatedBy    string
}

type ExampleWriter interface {
	SaveExample(ctx context.Context, ex Example) (string, error)
}

type Fetcher struct {
	SessionID string
	UserID    string
}

type Filter struct {
	// UserID restricts the list to one caller's records. Empty is
	// unrestricted, which only the operator surface may ask for.
	UserID string
	// Kind, Connection and Outcome are exact-match facets.
	Kind       string
	Connection string
	Outcome    string
	// Target keeps records addressing one dataset URN.
	Target string
	// SessionID keeps the calls one session made.
	SessionID string
	// EventIDs keeps the records of named audit events. It is how a caller
	// that already holds a page of events — a session's timeline — reads the
	// records for exactly those events, rather than reading a session's whole
	// history and discarding most of it. Empty states no restriction.
	EventIDs []string
	// Search matches the purpose and the statement.
	Search string
	// PromotableOnly keeps the records a reviewer can act on: satisfied, not
	// yet promoted, not rejected. It is the review queue.
	PromotableOnly bool
	Limit          int
	Offset         int
}

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

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

type Promotion struct {
	URN   string
	Actor string
}

type Record struct {
	ID string `json:"id" example:"9b1c0f26-1a3e-4c5f-9d0b-2f7a6e5c4d31"`
	// EventID is the audit event this call was recorded under and the key of
	// its mcp:call:<event_id> reference.
	EventID string `json:"event_id" example:"a1b2c3d4e5f6g7h8"`
	// Reference is EventID in the form an agent cites.
	Reference string `json:"reference" example:"mcp:call:a1b2c3d4e5f6g7h8"`
	Kind      string `json:"kind" example:"sql"`
	ToolName  string `json:"tool_name" example:"trino_query"`
	// Connection is the named connection the call went through. It is part of
	// a record's identity: the same statement against two warehouses is two
	// records, and reuse never crosses connections.
	Connection string `json:"connection,omitempty" example:"acme-warehouse"`

	// Statement is the SQL text, on a sql record.
	Statement string `json:"statement,omitempty"`
	// Method, Path and OperationID are the request line, on an api record.
	Method      string `json:"method,omitempty" example:"GET"`
	Path        string `json:"path,omitempty" example:"/v1/orders"`
	OperationID string `json:"operation_id,omitempty" example:"listOrders"`

	// Targets are what the call addressed: DataHub dataset URNs parsed from
	// the SQL, or the endpoint identity for an API call. Sorted and
	// deduplicated, so two records over the same tables compare equal.
	Targets []string `json:"targets"`

	// Purpose is the reason the caller stated for making the call (#1317).
	Purpose   string `json:"purpose,omitempty" example:"Sizing Q3 revenue by region for the board deck."`
	UserID    string `json:"user_id,omitempty" example:"550e8400-e29b-41d4-a716-446655440000"`
	UserEmail string `json:"user_email,omitempty" example:"marcus.johnson@example.com"`
	SessionID string `json:"session_id,omitempty" example:"dps_9f2c1a4b8e7d6c5a"`
	Persona   string `json:"persona,omitempty" example:"data-engineer"`

	Success       bool   `json:"success" example:"true"`
	ErrorMessage  string `json:"error_message,omitempty"`
	DurationMS    int64  `json:"duration_ms" example:"143"`
	ResponseChars int    `json:"response_chars" example:"2450"`

	// Outcome is derived on every read; see the package comment.
	Outcome string `json:"outcome" example:"satisfied"`
	// SatisfiedBy names the route that satisfied the record (asset, export,
	// capture). Empty on every other outcome.
	SatisfiedBy string `json:"satisfied_by,omitempty" example:"capture"`
	// Artifacts are what was built from this call: the assets, exports and
	// captured insights that cite it.
	Artifacts []Artifact `json:"artifacts,omitempty"`
	// ReuseCount is how many later sessions fetched this record and then ran
	// what it holds. It is the only signal on a record that a stranger, and
	// not its author, found it worth running.
	ReuseCount int `json:"reuse_count" example:"2"`

	PromotedURN   string     `json:"promoted_urn,omitempty" example:"urn:li:query:abc123"`
	PromotedAt    *time.Time `json:"promoted_at,omitempty"`
	PromotedBy    string     `json:"promoted_by,omitempty" example:"marcus.johnson@example.com"`
	RejectedAt    *time.Time `json:"rejected_at,omitempty"`
	RejectedBy    string     `json:"rejected_by,omitempty" example:"marcus.johnson@example.com"`
	RejectionNote string     `json:"rejection_note,omitempty"`

	CreatedAt time.Time `json:"created_at"`
}

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

type Rejection struct {
	Actor string
	Note  string
}

type Scope struct {
	ID string
	// UserID restricts the read to that caller's own records. Empty is
	// unrestricted.
	UserID string
}

type Scored struct {
	Record Record
	Score  float64
}

type SearchQuery struct {
	// Text is the natural-language query, matched lexically.
	Text string
	// Embedding is the query vector. Empty selects lexical-only ranking,
	// which is what a deployment with no embedding provider gets.
	Embedding []float32
	// UserID scopes the search to one caller's records. A search with no
	// caller returns nothing rather than everyone's calls.
	UserID string
	Limit  int
}

type Store interface {
	// Insert records one call. It is idempotent on event id: the same call
	// recorded twice yields one record.
	Insert(ctx context.Context, r Record) error
	// List returns records matching the filter, newest first, with their
	// outcomes derived.
	List(ctx context.Context, f Filter) ([]Record, error)
	// Count returns how many records match the filter, ignoring its paging.
	Count(ctx context.Context, f Filter) (int, error)
	// Get returns one record with its outcome, artifacts and reuse count, or
	// ErrNotFound when the scope admits none.
	Get(ctx context.Context, scope Scope) (*Record, error)
	// GetByEventID returns the record for one audit event id, scoped the same
	// way Get is. It is how an mcp:call:<event_id> reference resolves.
	GetByEventID(ctx context.Context, eventID, userID string) (*Record, error)
	// RecordFetch notes that a session dereferenced this record, which is the
	// first half of reuse.
	RecordFetch(ctx context.Context, recordID string, by Fetcher) error
	// CreditReuse credits every earlier record that the given call re-ran:
	// one this session had fetched, produced by a different session, with the
	// same kind, connection and statement (or operation). Returns how many
	// records were credited.
	CreditReuse(ctx context.Context, r Record) (int, error)
	// ForTargets returns satisfied records addressing any of the given
	// dataset URNs, most reused first. It is what the enrichment path shows
	// beside a table.
	ForTargets(ctx context.Context, urns []string, userID string, limit int) ([]Record, error)
	// Promote stores what the record became.
	Promote(ctx context.Context, id string, p Promotion) error
	// Reject records that the record was declined.
	Reject(ctx context.Context, id string, r Rejection) error
}

type URNBuilder func(connectionKind, connection, catalog, schema, table string) string