prompt

type Argument struct {
	Name        string `json:"name" example:"date"`
	Description string `json:"description" example:"The date to analyze (YYYY-MM-DD)"`
	Required    bool   `json:"required" example:"true"`
}

type Attachment struct {
	PromptID   string `json:"prompt_id" example:"prompt_a1b2c3d4"`
	ResourceID string `json:"resource_id" example:"res_01HK7R9F"`

	// Position orders attachments within a prompt, starting at 0. The order is
	// authored, not incidental: an SOP that says "fill the template, then check
	// it against the rubric" needs the template first.
	Position int `json:"position" example:"0"`

	// AttachedBy is the email of the author who created the link, kept for the
	// same reason approval stamps are kept: an operator reading a shared SOP
	// needs to know who put the material there.
	AttachedBy string `json:"attached_by,omitempty" example:"analyst@example.com"`
}

type AttachmentProvider interface {
	// Attachments returns the underlying attachment capability, or nil when the
	// backing store does not support attachments.
	Attachments() AttachmentStore
}

type AttachmentScope struct {
	// ResourceID identifies the resource in error messages.
	ResourceID string
	// DisplayName names the resource in error messages, so an author who is
	// blocked learns which attachment is at fault without a second lookup.
	DisplayName string
	// Scope is the resource's visibility: "global", "persona", or "user".
	Scope string
	// ScopeID is the persona name for a persona-scoped resource, the owning
	// user's subject for a user-scoped one, and empty for a global one.
	ScopeID string
}

type AttachmentStore interface {
	// Attach links a resource to a prompt at the end of the prompt's ordered
	// attachment list. Attaching an already-attached resource is a no-op that
	// preserves the existing position, so a double-click never reorders.
	Attach(ctx context.Context, a Attachment) error

	// Detach removes one link. Returns ErrAttachmentNotFound when no such link
	// exists. Remaining attachments keep their relative order.
	Detach(ctx context.Context, promptID, resourceID string) error

	// ListByPrompt returns one prompt's attachments in authored order.
	ListByPrompt(ctx context.Context, promptID string) ([]Attachment, error)

	// ListByResource returns the ids of prompts that attach a resource, so the
	// resource detail view can answer "what depends on this file?" before an
	// operator deletes it.
	ListByResource(ctx context.Context, resourceID string) ([]string, error)

	// Reorder rewrites one prompt's attachment order to exactly the given
	// resource ids. Ids not currently attached are rejected; omitting a
	// currently attached id detaches it.
	Reorder(ctx context.Context, promptID string, resourceIDs []string) error
}

type Collection struct {
	ID          string    `json:"id" example:"col_a1b2c3d4"`
	Name        string    `json:"name" example:"Sales Reporting"`
	Description string    `json:"description" example:"Weekly and daily sales SOPs"`
	CreatedBy   string    `json:"created_by" example:"jane@example.com"`
	PromptCount int       `json:"prompt_count" example:"7"`
	CreatedAt   time.Time `json:"created_at" example:"2026-07-01T14:30:00Z"`
	UpdatedAt   time.Time `json:"updated_at" example:"2026-07-01T14:30:00Z"`
}

type CollectionProvider interface {
	// Collections returns the underlying collection capability, or nil when
	// the backing store does not support collections.
	Collections() CollectionStore
}

type CollectionStore interface {
	// CreateCollection persists a new collection, generating its ID. Returns
	// ErrCollectionExists on a name collision.
	CreateCollection(ctx context.Context, c *Collection) error

	// GetCollection retrieves a collection by ID. Returns nil, nil if not found.
	GetCollection(ctx context.Context, id string) (*Collection, error)

	// ListCollections returns every collection with its prompt count, ordered
	// by name.
	ListCollections(ctx context.Context) ([]Collection, error)

	// UpdateCollection renames or re-describes a collection. Returns
	// ErrCollectionExists on a name collision.
	UpdateCollection(ctx context.Context, id, name, description string) error

	// DeleteCollection removes a collection, releasing its prompts to the
	// default (uncollected) group.
	DeleteCollection(ctx context.Context, id string) error

	// SetPromptCollection assigns a prompt to a collection, or clears the
	// assignment when collectionID is empty. It touches only the assignment:
	// no version snapshot is produced and the review gate is not involved
	// (placement is not reviewable substance).
	SetPromptCollection(ctx context.Context, promptID, collectionID string) error
}

type EditOutcome struct {
	// Applied is true when the live row was updated (the edit is being served).
	Applied bool `json:"applied"`
	// PendingVersion is the draft version number when the edit was deferred
	// for review; zero when Applied.
	PendingVersion int `json:"pending_version,omitempty"`
}

type ListFilter struct {
	Scope           string   // "global", "persona", "personal", or "" for all
	Personas        []string // filter by persona membership (OR match)
	OwnerEmail      string   // filter by owner
	Enabled         *bool    // filter by enabled state
	Search          string   // free-text search on name, display_name, description
	ReviewRequested *bool    // filter by pending promotion request (admin queue)
	Source          string   // include only this origin (operator, agent, system); "" for all
	ExcludeSource   string   // exclude this origin (e.g. "system" to hide ingested static prompts)
}

type Prompt struct {
	ID          string     `json:"id" example:"prompt_a1b2c3d4"`
	Name        string     `json:"name" example:"daily-sales-report"`
	DisplayName string     `json:"display_name" example:"Daily Sales Report"`
	Description string     `json:"description" example:"Generate a daily sales summary by region"`
	Content     string     `json:"content" example:"Analyze sales data for {date} grouped by region."`
	Arguments   []Argument `json:"arguments"`
	Category    string     `json:"category" example:"analysis"`
	Scope       string     `json:"scope" example:"persona"`
	Personas    []string   `json:"personas" example:"analyst,data-engineer"`
	OwnerEmail  string     `json:"owner_email" example:"admin@example.com"`
	Source      string     `json:"source" example:"database"`
	Enabled     bool       `json:"enabled" example:"true"`
	Tags        []string   `json:"tags" example:"sales,reporting"`

	// Promotion lifecycle.
	Status       string     `json:"status" example:"approved"`
	ApprovedBy   string     `json:"approved_by,omitempty" example:"admin@example.com"`
	ApprovedAt   *time.Time `json:"approved_at,omitempty"`
	DeprecatedAt *time.Time `json:"deprecated_at,omitempty"`
	SupersededBy string     `json:"superseded_by,omitempty" example:"daily-sales-report-v2"`

	// CollectionID places the prompt in at most one collection (#1010); empty
	// means uncollected. Placement is organizational metadata, not reviewable
	// substance: it is never versioned and changing it never triggers review.
	CollectionID string `json:"collection_id,omitempty" example:"col_a1b2c3d4"`

	// Version is the number of the snapshot the live row currently serves
	// (see VersionStore). Pending draft versions above this number exist in
	// the version history but are not served until approved.
	Version int `json:"version" example:"4"`

	// Serve-derived usage (see UsageReader). Populated only on read surfaces
	// wired to a usage reader (manage_prompt get, the prompt usage REST
	// endpoints); omitted elsewhere. Zero/absent means never served within the
	// audit retention window.
	RunCount  int64      `json:"run_count,omitempty" example:"37"`
	LastRunAt *time.Time `json:"last_run_at,omitempty"`

	// Promotion request: an owner asks to move a personal prompt into a shared
	// scope. ReviewRequested marks the prompt as pending in the admin queue;
	// RequestedScope/RequestedPersonas record the target. Cleared on approve or
	// reject (see ApplyPromotionRequest / ApprovePromotion).
	ReviewRequested   bool     `json:"review_requested" example:"false"`
	RequestedScope    string   `json:"requested_scope,omitempty" example:"persona"`
	RequestedPersonas []string `json:"requested_personas,omitempty" example:"analyst"`

	CreatedAt time.Time `json:"created_at" example:"2026-01-15T14:30:00Z"`
	UpdatedAt time.Time `json:"updated_at" example:"2026-01-15T14:30:00Z"`
}

type ScoredPrompt struct {
	Prompt Prompt  `json:"prompt"`
	Score  float64 `json:"score"`
}

type SearchQuery struct {
	Embedding  []float32 // query vector; nil selects lexical-only ranking
	QueryText  string    // raw query text for the lexical arm
	OwnerEmail string    // caller identity, for personal-scope visibility
	Persona    string    // caller persona, for persona-scope visibility
	IsAdmin    bool      // admin callers rank across all approved prompts
	Scope      string    // optional explicit scope filter ("" = all visible)
	Limit      int       // max results; see EffectiveLimit
}

type Searcher interface {
	Search(ctx context.Context, q SearchQuery) ([]ScoredPrompt, error)
}

type Store interface {
	// Create persists a new prompt.
	Create(ctx context.Context, p *Prompt) error

	// Get retrieves a non-personal (global or persona) prompt by name, which is
	// globally unique. Returns nil, nil if not found. Personal prompts are
	// per-owner and must be fetched with GetPersonal.
	Get(ctx context.Context, name string) (*Prompt, error)

	// GetPersonal retrieves a personal prompt by its owner and name. Personal
	// names are unique only within an owner, so the owner is required to
	// disambiguate. Returns nil, nil if not found.
	GetPersonal(ctx context.Context, ownerEmail, name string) (*Prompt, error)

	// ListPersonalByName retrieves every personal prompt with the given name,
	// across all owners. Personal names are unique only within an owner, so this
	// may return more than one row; callers with platform-wide visibility (an
	// admin resolving a prompt they did not author) use it to address a personal
	// prompt by name and to disambiguate by owner. Returns an empty slice if none
	// match.
	ListPersonalByName(ctx context.Context, name string) ([]Prompt, error)

	// GetByID retrieves a prompt by ID. Returns nil, nil if not found.
	GetByID(ctx context.Context, id string) (*Prompt, error)

	// Update modifies an existing prompt.
	Update(ctx context.Context, p *Prompt) error

	// Delete removes a prompt by name.
	Delete(ctx context.Context, name string) error

	// DeleteByID removes a prompt by ID.
	DeleteByID(ctx context.Context, id string) error

	// List returns prompts matching the filter.
	List(ctx context.Context, filter ListFilter) ([]Prompt, error)

	// Count returns the number of prompts matching the filter.
	Count(ctx context.Context, filter ListFilter) (int, error)
}

type Usage struct {
	RunCount  int64      `json:"run_count" example:"37"`
	LastRunAt *time.Time `json:"last_run_at,omitempty"`
}

type UsageReader interface {
	PromptUsage(ctx context.Context, promptIDs []string) (map[string]Usage, error)
}

type Version struct {
	ID          string     `json:"id" example:"ver_a1b2c3d4"`
	PromptID    string     `json:"prompt_id" example:"prompt_a1b2c3d4"`
	Version     int        `json:"version" example:"4"`
	DisplayName string     `json:"display_name" example:"Daily Sales Report"`
	Description string     `json:"description" example:"Generate a daily sales summary by region"`
	Content     string     `json:"content" example:"Analyze sales data for {date} grouped by region."`
	Arguments   []Argument `json:"arguments"`
	Tags        []string   `json:"tags" example:"sales,reporting"`
	Author      string     `json:"author" example:"jane@example.com"`
	Status      string     `json:"status" example:"applied"`
	ApprovedBy  string     `json:"approved_by,omitempty" example:"admin@example.com"`
	ApprovedAt  *time.Time `json:"approved_at,omitempty"`
	CreatedAt   time.Time  `json:"created_at" example:"2026-06-12T14:30:00Z"`
}

type VersionStore interface {
	// UpdateWithVersion persists p like Store.Update and, when any versioned
	// snapshot field (content, display name, description, arguments, tags)
	// differs from the stored row, records a new applied version authored by
	// author and advances p.Version to it.
	UpdateWithVersion(ctx context.Context, p *Prompt, author string) error

	// CreateDraftVersion snapshots proposed's versioned fields as a new draft
	// version of the prompt without touching the live row, returning the new
	// version number. The live row continues to be served unchanged until the
	// draft is approved.
	CreateDraftVersion(ctx context.Context, promptID string, proposed *Prompt, author string) (int, error)

	// ListVersions returns every version of the prompt, newest first.
	ListVersions(ctx context.Context, promptID string) ([]Version, error)

	// GetVersion returns one version with its full content, or nil, nil when
	// the prompt has no such version.
	GetVersion(ctx context.Context, promptID string, version int) (*Version, error)

	// ApproveVersion applies draft version's snapshot to the live prompt row,
	// marks the prompt approved with approver's stamp, binds the same stamp to
	// the version row (status applied), and supersedes any other pending
	// drafts. Returns the updated prompt.
	ApproveVersion(ctx context.Context, promptID string, version int, approver string) (*Prompt, error)

	// RejectVersion marks a pending draft version rejected, leaving the live
	// prompt row untouched.
	RejectVersion(ctx context.Context, promptID string, version int) error
}