gapreport

type Aggregate struct {
	// Key is the group's identity, and the name of the CapabilityGap object the
	// API projects from it: CapabilityKey when there is one, otherwise the
	// single report's own ID — see [Store].Aggregate.
	Key string
	// CapabilityKey is the model-coined key, empty for a group of one
	// keyless (pre-key, or filed-without-one) report.
	CapabilityKey string
	// ServiceName is the provider service the gap belongs to. Keys are
	// per-service: the same key filed against two services is two gaps.
	ServiceName string
	// Capability and Kind are taken from the most recent occurrence — the
	// freshest description of a gap that has been re-filed several times.
	Capability string
	Kind       Kind
	// Conversations counts DISTINCT ContextIDs, which is literally "how many
	// conversations hit this". Robust to one conversation filing twice.
	Conversations int
	// Occurrences counts reports, which can exceed Conversations.
	Occurrences int
	FirstSeen   time.Time
	LastSeen    time.Time
}

type Evidence struct {
	// Tool is the tool whose output is at fault, e.g. "workloads_list".
	Tool string
	// Observed is what that tool returned, e.g. "actionability: transient".
	Observed string
	// ContradictedBy is the fact that makes Observed wrong, thin, or
	// impossible to act on, e.g. "instance unchanged for 9d".
	ContradictedBy string
}

type InsertParams struct {
	ProviderProject string
	ServiceName     string
	ConsumerProject string
	ContextID       string
	// CapabilityKey is optional but is what makes de-duplication work; see
	// [Report].CapabilityKey. Validated against [ValidateCapabilityKey].
	CapabilityKey string
	Capability    string
	Summary       string
	// Kind is optional; empty means KindMissingCapability.
	Kind Kind
	// Evidence is optional. Expected for every kind but MissingCapability,
	// though not required — see [Store].Insert.
	Evidence Evidence
}

type Kind string

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

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

type Report struct {
	ID string
	// ProviderProject is the write key: the provider's own project
	// (spec.reportingProject on the capability document), where the
	// provider's team reviews reports.
	ProviderProject string
	// ServiceName is the provider service the gap belongs to (spec.serviceName).
	ServiceName string
	// ConsumerProject is the project the conversation happened in — provenance only.
	ConsumerProject string
	// ContextID is the conversation the gap arose in — provenance only.
	ContextID string
	// CapabilityKey names the gap in a form two conversations can agree on,
	// e.g. "workload-metrics". Capability is prose no two writings of the same
	// gap match; the key is what makes occurrences group. Empty on rows written
	// before keys existed, and on any report filed without one.
	//
	// It lives per occurrence and grouping happens at read time, so merging two
	// synonym keys stays one UPDATE and the next Aggregate re-derives every
	// count — the reason this is not an upsert onto a counter.
	CapabilityKey string
	// Capability is a short description of the capability at fault, e.g.
	// "list pipelines for StreamCo".
	Capability string
	// Summary is what the user was trying to do.
	Summary string
	// Kind classifies the shortfall. Always set on a report returned by a
	// [Store]; an unset stored value reads back as KindMissingCapability.
	Kind Kind
	// Evidence quotes the offending tool output. Zero for most
	// MissingCapability reports, which have nothing to quote.
	Evidence  Evidence
	CreatedAt time.Time
}

type Store interface {
	// List returns a provider project's reports, newest first. An unknown
	// project yields nil, nil. This is the occurrence view: one row per
	// report filed, each with its own evidence.
	List(ctx context.Context, providerProject string) ([]Report, error)
	// Aggregate returns a provider project's distinct gaps, one entry per
	// (service, capability key), most-hit first — ordered by Conversations
	// descending, then LastSeen descending, then Key ascending so the result
	// is deterministic. An unknown project yields nil, nil.
	//
	// Reports with no capability key are NOT merged with each other: each is
	// its own single-occurrence entry keyed by its report ID. Free prose is
	// exactly what cannot establish that two are the same gap, so merging them
	// would be a guess presented as a count. They still appear, unmerged, so
	// nothing already filed drops out of the provider's view.
	Aggregate(ctx context.Context, providerProject string) ([]Aggregate, error)
	// CapabilityKeys returns the keys already filed against one service in
	// one provider project, most-hit first (same ordering as Aggregate),
	// capped at limit (<= 0 means no cap). Reports with no key contribute
	// nothing.
	//
	// It returns bare keys and nothing else, on purpose: the result is injected
	// into a prompt running in SOME OTHER consumer's conversation. A key is a
	// bounded slug naming the provider's own capability; the report prose
	// around it is not, and has no business crossing into another tenant's
	// turn. This signature is where that boundary is enforced.
	CapabilityKeys(ctx context.Context, providerProject, serviceName string, limit int) ([]string, error)
	// Insert records a new report, assigning ID and CreatedAt, and defaulting
	// an empty Kind to KindMissingCapability. It returns ErrCapabilityTooLong,
	// ErrSummaryTooLong, ErrCapabilityKeyTooLong, ErrInvalidCapabilityKey,
	// ErrEvidenceTooLong, ErrUnknownKind, or ErrProjectFull; the store is left
	// unchanged.
	//
	// A malformed capability key is REJECTED because the caller can fix it on
	// the spot and retry. An omitted key is fine — it just does not group.
	//
	// A kind that [NeedsEvidence] with no evidence is ACCEPTED, not rejected:
	// rejecting drops the signal entirely and pushes the caller toward
	// relabelling it MissingCapability, and a wrong classification is worse for
	// the reader than a thin one. The nudge belongs in the tool result.
	Insert(ctx context.Context, params InsertParams) (Report, error)
}