content

type Actor struct {
	ID        string // stable subject id (uuid text); empty when Anonymous
	Kind      string // opaque: "user" | "service" | "delegated" | ...
	IP        string // anon fallback key for reactions / poll votes
	Anonymous bool
}

type ActorReaction struct {
	contentref.ContentRef
	Value     int16     `json:"value"` // -1 or 1 (neutral rows are excluded)
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type AdminComment struct {
	Comment
	contentref.ContentRef
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

type Answer struct {
	Tenant     string
	QuestionID string
	AnswerID   string
	Revision   int64  // monotonic per answer; retries retain this revision
	SubjectID  string // opaque authenticated actor, never an IP
	Text       string
}

type AnswerClassifier interface {
	Classify(ctx context.Context, a Answer) (GroupAssignment, error)
}

type AuthorReactions struct {
	Likes    int64 `json:"likes"`
	Dislikes int64 `json:"dislikes"`
}

type Authorizer interface {
	Can(ctx context.Context, actor Actor, perm string) (bool, error)
}

type BasicModerator struct {
	AllowLinks  bool          // default false: reject bodies containing URLs
	DupWindow   time.Duration // 0 = 30s; negative disables
	CensorWords []string      // nil = built-in set; empty = none; whole words, case-insensitive
	// contains filtered or unexported fields
}

type Chain []ContentModerator

type ClassificationPage struct {
	Classified int
	Next       string
}

type Comment struct {
	ID         string      `json:"id"`
	ReplyToID  string      `json:"reply_to_id,omitempty"`
	UserID     string      `json:"user_id,omitempty"`
	AnonName   string      `json:"anon_name,omitempty"`
	Body       string      `json:"body"`
	Deleted    bool        `json:"deleted"`
	Likes      int         `json:"likes"`
	Dislikes   int         `json:"dislikes"`
	Mine       int16       `json:"mine"` // caller's own reaction: -1/0/1
	ReplyCount int         `json:"reply_count"`
	Author     *PublicUser `json:"author,omitempty"`
	// Moderation is "held" or "rejected" on the author's own unpublished
	// comments (with the reason); absent on published ones.
	Moderation       string    `json:"moderation,omitempty"`
	ModerationReason string    `json:"moderation_reason,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

type ContentCanonicalizer interface {
	Canonical(ref contentref.ContentRef) (contentref.ContentRef, bool)
}

type ContentCanonicalizerFunc func(ref contentref.ContentRef) (contentref.ContentRef, bool)

type ContentModerator interface {
	Screen(ctx context.Context, in ModerationInput) (Verdict, error)
}

type ContentProcessor interface {
	Sanitize(ctx context.Context, raw string) (string, error)
}

type ContentResolver interface {
	Resolve(ctx context.Context, ref contentref.ContentRef, actor Actor) (Resolution, error)
}

type Counts struct {
	Likes        int `json:"likes"`
	Dislikes     int `json:"dislikes"`
	Favorites    int `json:"favorites"`
	CommentCount int `json:"comment_count"`
}

type Decision string

type FavoriteItem struct {
	contentref.ContentRef
	CreatedAt time.Time `json:"created_at"`
}

type FeedItem struct {
	Comment
	contentref.ContentRef
}

type Group struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Count int    `json:"count"`
}

type GroupAssignment struct {
	GroupID string
	Label   string
}

type HeldItem struct {
	Kind     string `json:"kind"`     // KindComment | KindPost
	Revision int64  `json:"revision"` // required when resolving this exact screened text
	ID       string `json:"id"`
	// Ref is the commented content, or the post's own reference.
	Ref           contentref.ContentRef `json:"ref"`
	AuthorID      string                `json:"author_id,omitempty"`
	AnonName      string                `json:"anon_name,omitempty"`
	Title         string                `json:"title,omitempty"`
	Body          string                `json:"body"`
	Reason        string                `json:"reason"`
	Model         string                `json:"model,omitempty"`
	PromptVersion string                `json:"prompt_version,omitempty"`
	Confidence    float64               `json:"confidence,omitempty"`
	Error         string                `json:"error,omitempty"` // moderator failure that forced the hold
	HeldAt        time.Time             `json:"held_at"`
	CreatedAt     time.Time             `json:"created_at"`
}

type HeldPage struct {
	Items []HeldItem `json:"items"`
	Next  string     `json:"next,omitempty"`
}

type Identity interface {
	Actor(ctx context.Context) (Actor, bool)
}

type MediaStore interface {
	Put(ctx context.Context, key string, data []byte, contentType string) (url string, err error)
}

type ModerationInput struct {
	SubjectID string // opaque content author; may differ from editing moderator
	Tenant    string
	Actor     Actor
	// Ref is the content the item belongs to: the commented work for a
	// comment, the post's own reference for a post.
	Ref    contentref.ContentRef
	Kind   string // KindComment | KindPost
	ItemID string // the existing item on an edit; empty on create
	Title  string // posts only
	Text   string
}

type Options struct {
	// Pool is the host's shared pgx pool; the runtime does not own its lifecycle.
	Pool *pgxpool.Pool
	// Schema is the host-selected schema holding all ContentKit tables.
	Schema string
	// Tenant scopes every row, index, cursor and result. Required.
	Tenant string

	// Mandatory ports.
	Identity Identity
	Authz    Authorizer
	Resolver ContentResolver

	// Canonicalizer enables the preference boundary (preferences.go): the
	// reaction/favorite row, the counts rollup and the export all use the
	// reference it returns. nil = no preference export.
	Canonicalizer ContentCanonicalizer
	// PreferenceSyncOverlap bounds how long a preference write may take to
	// commit and still be picked up by SyncPreferences.
	// Default DefaultPreferenceSyncOverlap.
	PreferenceSyncOverlap time.Duration

	// Optional ports (nil -> default).
	Users             UserEnricher     // default: no enrichment (ids only)
	Media             MediaStore       // explicit override; usually leave nil and set Storage
	Processor         ContentProcessor // comments and post excerpts; default: strip tags
	PostBodyProcessor ContentProcessor // post bodies; default: Processor
	// Moderator screens comment/post writes; nil publishes everything.
	// Compose a BasicModerator in front of an AI moderator with Chain.
	Moderator ContentModerator
	// Classifier groups free-text poll answers; nil refuses free-text polls.
	Classifier AnswerClassifier

	// Storage configures the built-in S3-backed media store (poll/post image
	// upload to a public bucket); used when Media is nil. See StorageConfig.
	Storage *StorageConfig

	// ProviderDataEraser is required when moderator/classifier ports retain
	// external personal data.
	// Nil explicitly means stateless ports; never remove it during an outage.
	ProviderDataEraser ProviderDataEraser

	// Perms are the opaque host permission strings gating privileged writes.
	Perms Perms

	// ContentKinds are the commentable/reactable/favoritable kinds the host
	// registers (e.g. "gallery", "video", "post"). Unregistered kinds are 404.
	ContentKinds []string

	// Logger receives the access log: each request at DEBUG, a 500 at ERROR
	// with its cause. nil -> slog.Default().
	Logger *slog.Logger
}

type Perms struct {
	PostWrite        string // create/update/delete posts
	PollWrite        string // create/update/delete polls + options
	CommentModerate  string // moderator delete/restore of another actor's comment
	ModerationReview string // list and resolve held comments and posts
}

type Preference struct {
	contentref.ContentRef
	ActorID   string
	Axis      string
	Value     int16
	Revision  int64
	UpdatedAt time.Time
}

type PreferenceSender func(ctx context.Context, page []Preference) error

type PreferenceSyncReport struct {
	From int64
	Sent int
}

type ProviderDataEraser interface {
	EraseSubjects(ctx context.Context, tenant string, actorIDs []string) error
}

type PublicUser struct {
	ID       string `json:"id"`
	Username string `json:"username"`
	Avatar   string `json:"avatar,omitempty"`
}

type RejectedError struct{ Reason string }

type Resolution struct {
	// Ref is the canonical reference every row is stored and read under (an
	// alias or slug resolves to it). A zero Ref keeps the requested one; a Ref
	// of another tenant is an error.
	Ref contentref.ContentRef
	// Visible = published and not soft-deleted.
	Visible bool
	// Accessible = the actor may consume it: an opaque host verdict
	// (entitlement, purchase, ACL, flag). ContentKit imposes no access model.
	Accessible bool
}

type ReviewDecision struct {
	Revision int64 // the revision returned by ListHeld; stale decisions cannot publish edits
	Decision Decision
	Reviewer string
	Reason   string
}

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

type StatelessPolicy interface{ StatelessPolicy() }

type StorageConfig struct {
	Bucket          string
	Region          string
	Endpoint        string // custom S3 endpoint (MinIO/R2); empty = AWS default
	AccessKeyID     string
	SecretAccessKey string
	PublicBaseURL   string // public origin serving the bucket, e.g. https://cdn.example.com
	UsePathStyle    bool   // true for MinIO / most self-hosted S3
}

type UserEnricher interface {
	UsersByIDs(ctx context.Context, ids []string) (map[string]PublicUser, error)
}

type Verdict struct {
	Decision      Decision
	Reason        string
	Model         string
	PromptVersion string
	Confidence    float64
}