resource

type Claims struct {
	Sub             string   // Keycloak subject (user ID)
	Email           string   // user email
	Personas        []string // persona names the user belongs to
	Roles           []string // raw roles from auth (may have prefix, e.g., "dp_admin")
	IsAdmin         bool     // resolved by the caller from persona config
	AdminOfPersonas []string // persona names this user can admin (resolved by caller from role patterns)
	// OnBehalfOf is the address of the person an unattended caller acts for,
	// carried from PlatformContext.OnBehalfOfEmail. A managed-script run
	// authenticates as script:<name>, a principal that owns nothing a person
	// owns, so claims built on the principal alone refuse a run the very files
	// its own author can edit -- and file a resource it creates in a library
	// nobody can see. Every rule below that turns on "is this you?" reads this
	// too, so a run reaches what its author reaches and nothing else (#1419,
	// #1487).
	//
	// Empty for every human caller, which is what keeps this inert everywhere
	// else. An empty value must never match an empty owner or an empty scope
	// id: absence of an identity is not a shared identity.
	OnBehalfOf string
}

type ClaimsExtractor func(r *http.Request) (*Claims, error)

type Deps struct {
	Store     Store
	S3Client  S3Client
	S3Bucket  string
	URIScheme string          // defaults to "mcp" if empty
	OnCreate  func(*Resource) // called after successful create to register with MCP
	OnDelete  func(string)    // called after successful delete with URI to unregister
	// OnDeleteID is called after a successful delete with the resource's ID,
	// so a consumer keyed on the record rather than on its MCP URI can clean
	// up after it -- the tables registered over its file (#1327). Separate
	// from OnDelete because that one exists to unregister an MCP resource and
	// is keyed on the URI it was registered under.
	OnDeleteID func(context.Context, string)
	// OnRevised is called after a revision moves the resource's head -- a
	// replacement or a restore -- with the version number it was recorded as,
	// so the tables registered over the file follow it (#1536). It returns
	// what happened to each table, which the response carries; the revision
	// is never failed by it. Nil on a deployment that cannot register tables.
	OnRevised func(ctx context.Context, id string, version int) []string

	// Versions records content revisions. Absent on a deployment whose store
	// does not implement VersionStore, which disables the revision and version
	// routes (503) and leaves create, metadata edits, and reads unaffected.
	Versions VersionStore
	// MaxVersions is the retention cap; non-positive selects DefaultMaxVersions.
	MaxVersions int
	// ReadRecorder audits served content reads. Absent when audit is disabled,
	// which silences read events without affecting the reads themselves.
	ReadRecorder ReadRecorder
	// Usage supplies audit-derived read counts for the detail read. Absent when
	// audit is disabled, which leaves the usage field off the response.
	Usage UsageReader
	// MoveRecorder audits a resource refiled into another library. Absent when
	// audit is disabled, which silences the event without affecting the move.
	MoveRecorder MoveRecorder
	// Producers records what wrote each resource (#1569): the script, session
	// or person behind the create and behind every content revision since.
	// Absent on a deployment with no database, which records nothing and
	// leaves the writes themselves unaffected.
	Producers producedby.Store
}

type Destination struct {
	Scope   Scope
	ScopeID string
	Path    string
}

type Filter struct {
	Scopes []ScopeFilter // visibility scopes (derived from claims)
	// Path narrows the listing to one folder and everything beneath it. Empty
	// is the whole library. It is a prefix rather than an equality so opening a
	// folder reports what the folder holds, subfolders included, which is what
	// makes a count under a folder mean anything.
	Path   string
	Tag    string // optional tag filter
	Query  string // optional text search in display_name/description
	Sort   Sort   // ordering; empty selects SortUpdated
	Limit  int
	Offset int
	// AllScopes lists every library in the deployment, whatever Scopes holds.
	//
	// It is the one predicate a set of (scope, scope_id) pairs cannot express:
	// the user libraries are keyed by subject and address, and the platform
	// keeps no roster of them to enumerate, so "every library" has to be said
	// rather than listed. Only a platform administrator's unnarrowed listing
	// sets it (ListScopes), and nothing else in the package reads Scopes when
	// it is set.
	AllScopes bool
}

type Folder struct {
	// Path is the folder's full slash-separated path inside its library.
	Path string `json:"path" example:"data/media-manager"`
	// Count is the resources filed at this path and beneath it.
	Count int `json:"count" example:"12"`
}

type FolderMove struct {
	From string `json:"from"`
	To   string `json:"to"`
	// Moved is one entry per resource rewritten, in listing order.
	Moved []FolderMoveEntry `json:"moved"`
}

type FolderMoveEntry struct {
	ID      string `json:"id"`
	Path    string `json:"path"`
	URI     string `json:"uri"`
	FromURI string `json:"from_uri"`
}

type FolderRename struct {
	Library ScopeFilter
	From    string
	To      string
}

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

type Move struct {
	// ID is the resource being refiled. It is on the value rather than a
	// separate argument because a folder rename hands the store a batch.
	ID      string
	Scope   Scope
	ScopeID string
	Path    string
	URI     string
	FromURI string
}

type MoveEvent struct {
	ResourceID  string
	DisplayName string
	FromScope   Scope
	FromScopeID string
	FromPath    string
	FromURI     string
	ToScope     Scope
	ToScopeID   string
	ToPath      string
	ToURI       string
	UserID      string
	UserEmail   string
}

type MoveRecorder interface {
	RecordMove(ctx context.Context, ev MoveEvent)
}

type NewResource struct {
	Scope       Scope
	ScopeID     string
	Path        string
	Filename    string
	DisplayName string
	Description string
	Tags        []string
	// Data is the content, and MIMEType the type it is stored under.
	Data     []byte
	MIMEType string
	// DeclaredMIMEType is what the caller said the bytes were, kept so a
	// detection that replaced it is recorded. Empty when nothing was declared.
	DeclaredMIMEType string
}

type ParsedURI struct {
	Scope   Scope
	ScopeID string
	Path    string
}

type ReadEvent struct {
	ResourceID string
	URI        string
	// Surface is one of the Surface* constants: which door served the content.
	Surface string
	// Version is the revision served, or 0 when the head was served without
	// naming a version.
	Version   int
	UserID    string
	UserEmail string
	Persona   string
	SessionID string
	RequestID string
}

type ReadRecorder interface {
	RecordRead(ctx context.Context, ev ReadEvent)
}

type ReadTracker interface {
	TouchRead(ctx context.Context, id string, at time.Time) error
}

type Resource struct {
	ID      string `json:"id" example:"res_01HK7R9F"`
	Scope   Scope  `json:"scope" example:"persona"`
	ScopeID string `json:"scope_id,omitempty" example:"data-engineer"` // persona name or user sub; empty for global
	// Path is the slash-separated folder path this resource is filed under
	// inside its library, and the tail of its URI ahead of the filename. A
	// one-segment path is what every resource carried before folders (#1529).
	Path          string    `json:"path" example:"runbooks/etl"`
	Filename      string    `json:"filename" example:"etl-runbook.md"`
	DisplayName   string    `json:"display_name" example:"ETL Runbook"`
	Description   string    `json:"description" example:"Step-by-step procedures for ETL pipeline operations"`
	MIMEType      string    `json:"mime_type" example:"text/markdown"`
	SizeBytes     int64     `json:"size_bytes" example:"34000"`
	S3Key         string    `json:"s3_key" example:"resources/res_01HK7R9F/etl-runbook.md"`
	URI           string    `json:"uri" example:"mcp://persona/data-engineer/runbooks/etl-runbook.md"`
	Tags          []string  `json:"tags"`
	UploaderSub   string    `json:"uploader_sub" example:"550e8400-e29b-41d4-a716-446655440000"`
	UploaderEmail string    `json:"uploader_email" example:"marcus.johnson@example.com"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
	// LastReadAt is when the resource's content was last served through any
	// surface, stamped by the read recorder. NULL means never read since the
	// deployment began auditing reads (#1014). It is the durable answer, unlike
	// the audit-derived Usage.LastReadAt, which is bounded by audit retention.
	LastReadAt *time.Time `json:"last_read_at,omitempty"`
	// Usage is the audit-derived read activity of this resource. It is not a
	// stored column: the detail read fills it from the audit rollup, and it is
	// absent everywhere the rollup was not consulted.
	Usage *Usage `json:"usage,omitempty"`

	// ThumbnailS3Key and ThumbnailDarkS3Key are the captured PNGs stored beside
	// the resource's own object, empty until one is taken (#1554). The library
	// used to draw the original file scaled down instead, which meant a
	// non-image had no tile at all and an image cost its full size to show.
	ThumbnailS3Key     string `json:"thumbnail_s3_key,omitempty"`
	ThumbnailDarkS3Key string `json:"thumbnail_dark_s3_key,omitempty"`
	// ThumbnailCapturedAt and ThumbnailDarkCapturedAt are when each capture was
	// taken. A capture older than the resource's UpdatedAt is behind the file it
	// came from, which is what the pending list is built on; see migration
	// 000134 for why this is a timestamp rather than a version.
	ThumbnailCapturedAt     *time.Time `json:"thumbnail_captured_at,omitempty"`
	ThumbnailDarkCapturedAt *time.Time `json:"thumbnail_dark_captured_at,omitempty"`
}

type Revision struct {
	ResourceID    string
	MIMEType      string
	SizeBytes     int64
	S3Key         string
	UploaderSub   string
	UploaderEmail string
	// RestoredFrom names the version a restore re-promoted, or nil for a fresh
	// upload.
	RestoredFrom *int
	// ChangeSummary says why the content changed. Empty for an upload; set by a
	// caller revising on somebody's behalf, which is the case the version panel
	// cannot otherwise explain.
	ChangeSummary string
}

type RevisionUpload struct {
	Data     []byte
	MIMEType string
	// RestoredFrom names the version a restore re-promoted, nil otherwise.
	RestoredFrom *int
	// ChangeSummary says why the content changed, for a revision written on the
	// uploader's behalf. Empty for an upload the uploader picked themselves.
	ChangeSummary string
}

type S3Client interface {
	PutObject(ctx context.Context, bucket, key string, data []byte, contentType string) error
	GetObject(ctx context.Context, bucket, key string) (body []byte, contentType string, err error)
	DeleteObject(ctx context.Context, bucket, key string) error
}

type Scope string

type ScopeFilter struct {
	Scope   Scope
	ScopeID string // empty for global
}

type ScoredResource struct {
	Resource Resource `json:"resource"`
	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
	Scopes    []ScopeFilter // caller's visible scopes; mandatory
	Limit     int           // max results; clamped into [1, maxSearchLimit]
}

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

type Sort string

type Store interface {
	Insert(ctx context.Context, r Resource) error
	Get(ctx context.Context, id string) (*Resource, error)
	// GetByIDs returns the resources among ids that exist, keyed by id. An id
	// with no row is simply absent: the caller is reading a set of references
	// and a missing one is an answer, not a failure.
	//
	// It is the read a listing over records that POINT AT resources needs, so
	// a page costs one query rather than one per row.
	GetByIDs(ctx context.Context, ids []string) (map[string]*Resource, error)
	GetByURI(ctx context.Context, uri string) (*Resource, error)
	List(ctx context.Context, filter Filter) ([]Resource, int, error)
	// Folders returns every folder holding a resource the filter admits, with
	// the exact number filed under each at every depth.
	//
	// It exists because a folder is derived from the paths in use rather than
	// stored, and the portal used to derive it in the browser from the paged
	// listing: drawing four folder names cost a fetch of the whole library, the
	// counts read "25+" until the last page arrived, and the root offered a
	// Load-more control over rows it never displayed (#1555). One grouped query
	// answers it exactly and in one round trip.
	Folders(ctx context.Context, filter Filter) ([]Folder, error)
	// SetThumbnail records a capture: the object it was stored under and the
	// moment it was taken.
	//
	// It is not an Update. Update bumps updated_at and drops the stored
	// embedding, and a capture must do neither: bumping the timestamp would
	// mark the capture that just landed as older than the row it came from,
	// which is the definition of pending, so every capture would queue itself
	// again forever (#1554).
	SetThumbnail(ctx context.Context, id string, t ThumbnailCapture) error
	// ClearThumbnail forgets a capture, which is how a wrong tile is asked to
	// be taken again.
	ClearThumbnail(ctx context.Context, id, variant string) error
	// PendingThumbnails lists resources whose capture is missing or older than
	// the file it came from, most recently changed first, capped at limit.
	PendingThumbnails(ctx context.Context, filter Filter, limit int) ([]Resource, error)
	// Tags returns the distinct tags carried by the resources the filter
	// admits, so the tag facet offers what the library holds rather than what
	// one page of it happened to carry.
	Tags(ctx context.Context, filter Filter) ([]string, error)
	Update(ctx context.Context, id string, u Update) error
	// Move refiles resources, rewriting the four columns that say where each one
	// lives -- scope, scope_id, path and uri -- and recording the URI each used
	// to answer to so an already-written citation keeps resolving.
	//
	// It is separate from Update because it is not a metadata edit: it changes
	// who can see the file, it changes the resource's address, and the address
	// is UNIQUE, so it is the one write on this table that another resource can
	// refuse. A caller must be prepared for ErrURIConflict.
	//
	// It takes a batch because renaming a folder is one relocation per resource
	// beneath it and a half-renamed folder is not a state anyone should be able
	// to observe (#1529). Every element commits or none does, which is also what
	// makes the batch refusable as a whole.
	//
	// The blob is not touched. The S3 key embeds the scope only because
	// BuildS3Key composed it at creation; nothing re-derives it on read, so the
	// object stays where it is and the row keeps pointing at it.
	Move(ctx context.Context, moves []Move) error
	Delete(ctx context.Context, id string) error
}

type ThumbnailCapture struct {
	Variant    string
	S3Key      string
	CapturedAt time.Time
}

type Update struct {
	DisplayName *string  `json:"display_name,omitempty"`
	Description *string  `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	// Path refiles the resource in another folder of its library. Like Scope it
	// is not metadata: the folder path is half of the resource's URI, so an edit
	// to it rewrites the address and records the one it vacated (#1528).
	Path *string `json:"path,omitempty"`
	// Scope names the library to move the resource into. Nil leaves it where it
	// is, which is what every request that is not a move sends.
	Scope *Scope `json:"scope,omitempty"`
	// ScopeID is the persona name or the user's sub or address, and is empty for
	// the global library. It is read only when Scope is set: a scope id on its
	// own names no library.
	ScopeID *string `json:"scope_id,omitempty"`
	// ThumbnailS3Key and ThumbnailCapturedAt record a capture (#1554). They are
	// written by the capture route alone and are not part of the metadata edit
	// the PATCH route accepts: a person editing a description is not saying
	// anything about the image.
	ThumbnailS3Key      *string    `json:"-"`
	ThumbnailCapturedAt *time.Time `json:"-"`
	// ThumbnailVariant names which of the two a capture is for. Empty is the
	// light one.
	ThumbnailVariant string `json:"-"`
}

type Usage struct {
	// Reads30d and Reads90d count audited reads in the trailing 30 and 90
	// days. Both are bounded by the audit retention window: a deployment
	// keeping 30 days of audit reports the same number twice.
	Reads30d int64 `json:"reads_30d" example:"42"`
	Reads90d int64 `json:"reads_90d" example:"117"`
	// BySurface30d breaks the 30-day count down by Surface* value.
	BySurface30d map[string]int64 `json:"by_surface_30d,omitempty"`
	// LastReadAt is the most recent audited read within the retention window.
	// The durable answer lives on the resource row (Resource.LastReadAt), which
	// outlives retention; this field is what the rollup itself saw.
	LastReadAt *time.Time `json:"last_read_at,omitempty"`
}

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

type Version struct {
	ResourceID    string `json:"resource_id" example:"a1b2c3d4e5f67890a1b2c3d4e5f67890"`
	Version       int    `json:"version" example:"3"`
	MIMEType      string `json:"mime_type" example:"text/markdown"`
	SizeBytes     int64  `json:"size_bytes" example:"34000"`
	S3Key         string `json:"s3_key" example:"resources/persona/data-engineer/a1b2/v3/etl-runbook.md"`
	UploaderSub   string `json:"uploader_sub" example:"550e8400-e29b-41d4-a716-446655440000"`
	UploaderEmail string `json:"uploader_email" example:"marcus.johnson@example.com"`
	// RestoredFrom names the version this revision re-promoted, or nil when the
	// revision was a fresh upload. A restore is recorded as a new head revision
	// rather than a rewind so the trail stays append-only.
	RestoredFrom *int `json:"restored_from,omitempty" example:"1"`
	// ChangeSummary says why the content changed, for a revision written on the
	// uploader's behalf rather than picked by them. Empty for an upload, where
	// the uploader is the answer. It is what the version panel shows beside the
	// revision, so a reader of the history sees the reason without having to
	// find the operation that caused it.
	ChangeSummary string    `json:"change_summary,omitempty" example:"put 3 rows back onto one line"`
	CreatedAt     time.Time `json:"created_at"`
}

type VersionStore interface {
	// AddRevision records a revision and points the resource head at its blob,
	// in one transaction. The version number is assigned inside that
	// transaction as one past the highest recorded, so two concurrent revisions
	// cannot claim the same number, and the stored row is returned.
	AddRevision(ctx context.Context, rev Revision) (*Version, error)

	// ListVersions returns every recorded revision of a resource, newest first.
	ListVersions(ctx context.Context, resourceID string) ([]Version, error)

	// GetVersion returns one recorded revision. A missing revision surfaces as
	// a wrapped sql.ErrNoRows (see IsNotFound).
	GetVersion(ctx context.Context, resourceID string, version int) (*Version, error)

	// PruneVersions deletes the oldest revisions beyond the newest keep and
	// returns the deleted rows so the caller can remove their blobs. It never
	// deletes a row whose S3 key is currently referenced by the resource head,
	// so pruning can never orphan the live content.
	PruneVersions(ctx context.Context, resourceID string, keep int) ([]Version, error)
}