entity

type AICommentSource struct {
	Name       string
	Slug       string
	SchemaSlug string
	Attributes json.RawMessage
	UpdatedAt  time.Time
}

type AttrValueCount struct {
	Value string
	Count int
}

type BeforeSaveFunc func(ctx context.Context, in *BeforeSaveInput) error

type BeforeSaveInput struct {
	Operation  string
	ID         *uuid.UUID
	SchemaSlug string
	Name       string
	Slug       string
	// Locale is the entity's BCP 47 tag, informational only (never read back).
	// Empty on create or import when the caller did not set one: the entity then
	// takes the site language.
	Locale     string
	Attributes json.RawMessage
}

type BreadcrumbPathItem struct {
	ID   uuid.UUID `json:"id"`
	Name string    `json:"name"`
	Slug string    `json:"slug"`
}

type BuilderStore interface {
	GetEntity(ctx context.Context, id uuid.UUID) (*Entity, error)
	GetSchema(ctx context.Context, id uuid.UUID) (*EntitySchema, error)
	UpdateEntity(ctx context.Context, id uuid.UUID, userID *uuid.UUID, in *UpdateEntityInput) (*Entity, error)
	UpdateEntityStatus(ctx context.Context, id uuid.UUID, userID *uuid.UUID, status EntityStatus) (*Entity, error)
}

type Byline struct {
	PersonID *uuid.UUID
	Org      bool
	Name     string
}

type BylineResolver interface {
	// Resolve maps byline text to a credit: the site organisation when it is
	// the company name, else the person with that slug or name, creating a
	// non-public person without a login when there is none.
	Resolve(ctx context.Context, name string) (Byline, error)
	// Name is the display name of the credit: the person's name, or the
	// organisation's when personID is nil.
	Name(ctx context.Context, personID *uuid.UUID) (string, error)
	// Check returns ErrAuthorNotFound when id is not a person.
	Check(ctx context.Context, id uuid.UUID) error
	// Mirror returns the hatamoto_authors row that mirrors the person (made on
	// first use). author_id is dual-written with it so a rollback still shows
	// bylines.
	Mirror(ctx context.Context, personID uuid.UUID) (*uuid.UUID, error)
	// PersonChanged is called after a person entity was created or saved: it
	// refreshes the mirror row and the plain-text byline on their posts.
	PersonChanged(ctx context.Context, personID uuid.UUID) error
	// PersonDeleting is called before a person entity is deleted: their posts
	// lose the reference and keep the plain-text byline.
	PersonDeleting(ctx context.Context, personID uuid.UUID) error
}

type CreateEntityInput struct {
	SchemaID   uuid.UUID       `json:"schema_id"`
	Name       string          `json:"name"`
	Slug       string          `json:"slug,omitempty"`   // Auto-generated if empty
	Locale     string          `json:"locale,omitempty"` // BCP 47; empty stores the site language
	Attributes json.RawMessage `json:"attributes"`
	Metadata   json.RawMessage `json:"metadata,omitempty"`
	ParentID   *uuid.UUID      `json:"parent_id,omitempty"`
	AuthorID   *uuid.UUID      `json:"author_id,omitempty"`
	// BylinePersonID and BylineOrg set the byline (see Entity).
	BylinePersonID *uuid.UUID `json:"byline_person_id,omitempty"`
	BylineOrg      bool       `json:"byline_org,omitempty"`
	// Status is set by the service for a person or a block or part (see lockedStatus); a caller
	// cannot choose it. Unset stores a draft.
	Status *EntityStatus `json:"-"`
}

type CreateSchemaInput struct {
	Name        string          `json:"name"`
	Slug        string          `json:"slug,omitempty"` // Auto-generated if empty
	Description *string         `json:"description,omitempty"`
	Schema      json.RawMessage `json:"schema"`
	Settings    json.RawMessage `json:"settings,omitempty"`
}

type Descendant struct {
	Entity *Entity
	// Between holds the slugs of the rows between the starting entity and
	// this one, root first (empty for a direct child).
	Between []string
}

type DocProblem struct {
	Status int
	Code   string
	Msg    string
}

type DocState int

type EditorSetting string

type EditorialProvenance struct {
	ReviewedBy     string   `json:"reviewed_by,omitempty"`
	ReviewedAt     string   `json:"reviewed_at,omitempty"`
	FactChecked    bool     `json:"fact_checked,omitempty"`
	Sources        []string `json:"sources,omitempty"`
	LastVerifiedAt string   `json:"last_verified_at,omitempty"`
}

type Entity struct {
	ID          uuid.UUID       `json:"id"`
	SchemaID    uuid.UUID       `json:"schema_id"`
	Name        string          `json:"name"`
	Slug        string          `json:"slug"`
	Locale      string          `json:"locale"`
	Status      EntityStatus    `json:"status"`
	Attributes  json.RawMessage `json:"attributes"`
	Metadata    json.RawMessage `json:"metadata,omitempty"`
	Editorial   json.RawMessage `json:"editorial,omitempty"`
	Version     int             `json:"version"`
	CreatedBy   *uuid.UUID      `json:"created_by,omitempty"`
	UpdatedBy   *uuid.UUID      `json:"updated_by,omitempty"`
	CreatedAt   time.Time       `json:"created_at"`
	UpdatedAt   time.Time       `json:"updated_at"`
	PublishedAt *time.Time      `json:"published_at,omitempty"`

	// Hierarchy and content classification fields
	ParentID *uuid.UUID `json:"parent_id,omitempty"`
	// AuthorID references hatamoto_authors (a byline, not a user account).
	AuthorID *uuid.UUID `json:"author_id,omitempty"`
	// BylinePersonID is the person entity credited as the author; BylineOrg
	// credits the site organisation instead. They are exclusive. This is the
	// source of bylines; AuthorID is only dual-written so a rollback still
	// renders them. BylinePersonID has no foreign key: integrity is kept in code.
	BylinePersonID *uuid.UUID `json:"byline_person_id,omitempty"`
	BylineOrg      bool       `json:"byline_org,omitempty"`

	// Joined fields (not stored in DB)
	Schema *EntitySchema `json:"schema,omitempty"`
}

type EntityLinkSync interface {
	// Reindex refreshes hatamoto_entity_link_index for sourceEntityID based on
	// whatever <a data-entity-id> tags currently live in its stored content.
	// See internal/linking/v2/indexer.go.
	Reindex(ctx context.Context, sourceEntityID uuid.UUID) error

	// RewriteForEntity rewrites the href of every <a data-entity-id="X">
	// across the codebase to newCanonicalURL when X's own slug changes. See internal/linking/v2/rewriter.go.
	RewriteForEntity(ctx context.Context, targetEntityID uuid.UUID, newCanonicalURL, reason string, actor *uuid.UUID) error

	// ResolveCanonical returns the post-update canonical URL for the entity
	// whose slug changed, so the rewriter has a destination href.
	ResolveCanonical(ent *Entity) (string, error)
}

type EntityLocation struct {
	// Path is the canonical URL path ("/blog/x", "/about").
	Path string
	// Section is true for a section landing page served at /{slug}.
	Section bool
	// ArchivePath and ArchiveName describe the section index crumb that
	// precedes the entity; empty when the entity has none (no archive_path,
	// a section page, or a per-entity override).
	ArchivePath string
	ArchiveName string
}

type EntityRepository interface {
	Create(ctx context.Context, userID *uuid.UUID, input *CreateEntityInput) (*Entity, error)
	GetByID(ctx context.Context, id uuid.UUID) (*Entity, error)
	GetBySlug(ctx context.Context, slug string) (*Entity, error)
	Update(ctx context.Context, id uuid.UUID, userID *uuid.UUID, input *UpdateEntityInput) (*Entity, error)
	UpdateStatus(ctx context.Context, id uuid.UUID, userID *uuid.UUID, status EntityStatus) (*Entity, error)
	Delete(ctx context.Context, id uuid.UUID) error
	List(ctx context.Context, filter *ListEntitiesFilter, page *KeysetPage) (*PagedResult[*Entity], error)
	ListWithOffset(ctx context.Context, filter *ListEntitiesFilter, page *OffsetPage) (*OffsetPagedResult[*Entity], error)
	CountBySchemaStatus(ctx context.Context) ([]SchemaStatusCount, error)
	CountByParent(ctx context.Context, limit int) ([]ParentCount, error)
	CountChildren(ctx context.Context, parentIDs []uuid.UUID) (map[uuid.UUID]int, error)

	// Version operations
	CreateVersion(ctx context.Context, entityID uuid.UUID, version int, attributes json.RawMessage, changedBy *uuid.UUID, changeSummary *string) (*EntityVersion, error)
	PruneVersions(ctx context.Context, keep int) (int64, error)
	GetVersion(ctx context.Context, entityID uuid.UUID, version int) (*EntityVersion, error)
	ListVersions(ctx context.Context, entityID uuid.UUID, limit int) ([]*EntityVersion, error)
}

type EntitySchema struct {
	ID          uuid.UUID       `json:"id"`
	Name        string          `json:"name"`
	Slug        string          `json:"slug"`
	Description *string         `json:"description,omitempty"`
	Schema      json.RawMessage `json:"schema"`
	IsBuiltin   bool            `json:"is_builtin"`
	CreatedAt   time.Time       `json:"created_at"`
	UpdatedAt   time.Time       `json:"updated_at"`
	// Settings holds optional per-schema routing configuration (see
	// SchemaURLSettings). An empty object means "use the built-in defaults".
	Settings json.RawMessage `json:"settings"`
}

type EntityStatus string

type EntityURLBuilder func(baseURL, slug string) string

type EntityVersion struct {
	ID            uuid.UUID       `json:"id"`
	EntityID      uuid.UUID       `json:"entity_id"`
	Version       int             `json:"version"`
	Attributes    json.RawMessage `json:"attributes"`
	ChangedBy     *uuid.UUID      `json:"changed_by,omitempty"`
	ChangeSummary *string         `json:"change_summary,omitempty"`
	CreatedAt     time.Time       `json:"created_at"`
}

type Event struct {
	Kind       EventKind
	ID         uuid.UUID
	SchemaSlug string
	Slug       string
	Locale     string
	Name       string
	Status     string
	Version    int
	// Import is set for EventImportCompleted only; the entity fields are zero.
	Import *ImportSummary
}

type EventKind string

type EventSink interface {
	Emit(ctx context.Context, ev Event)
}

type EvidenceLinkForJSONLD struct {
	FieldPath       string
	LinkType        string
	ConfidenceScore int
	VerifiedAt      *string // ISO 8601 timestamp, nil if not verified
	SourceTitle     string
	SourceType      string
	// SourceURL is the URL used in citation blocks. For external_url sources
	// this is the user-supplied URL; for internal entity-backed sources the
	// server layer resolves the entity's canonical URL before passing in.
	SourceURL string
	// SourceURLType is the Schema.org @type of the citation block. Defaults
	// to "CreativeWork" when empty. Server layer sets this to "Article" /
	// "Person" / etc. for internal entity sources so LLMs and crawlers
	// see a specific type instead of the generic fallback.
	SourceURLType string
}

type FAQItem struct {
	Question string
	Answer   string
}

type FieldKindResolver func(sectionType string, path []string) string

type HierarchyStore interface {
	// Ancestors returns the parent chain of id, root first, without id itself.
	// A chain deeper than urlpattern.MaxPathDepth is cut at that depth, which
	// is also what ends a cycle.
	Ancestors(ctx context.Context, id uuid.UUID) ([]BreadcrumbPathItem, error)
	// Descendants returns every published descendant of id (children,
	// grandchildren, ...), parents before children.
	Descendants(ctx context.Context, id uuid.UUID) ([]*Descendant, error)
	// SubtreeHeight is how many levels of rows (any status) lie below id: 0
	// for a leaf, 1 with children only. Counting stops at twice
	// urlpattern.MaxPathDepth, which is also what ends a cycle.
	SubtreeHeight(ctx context.Context, id uuid.UUID) (int, error)
	// HasChildren reports whether any row has id as its parent.
	HasChildren(ctx context.Context, id uuid.UUID) (bool, error)
	// Child returns the base row (no variant) with this slug directly under
	// parent, or a root row when parent is nil; ErrEntityNotFound when none.
	// Slugs are unique per schema, not among all siblings: schemaSlug narrows
	// the lookup to one schema, and without it ErrAmbiguousSlug is returned
	// when rows of several schemas match.
	Child(ctx context.Context, parent *uuid.UUID, slug, schemaSlug string) (*Entity, error)
}

type ImportBatch struct {
	// Source labels the origin ("wordpress", "archive"); it is stored in the
	// entity metadata and sent in import.completed.
	Source string
	Items  []ImportItem
}

type ImportItem struct {
	// Key is the idempotency key, unique per source entity (for example
	// "wp:post:123"). An item whose key was imported before updates that
	// entity in place instead of creating another.
	Key        string
	SchemaSlug string
	Name       string
	Slug       string // generated from Name when empty
	Locale     string // BCP 47 tag; empty is the site language on insert and unchanged on update
	Status     EntityStatus
	Attributes json.RawMessage
	Metadata   json.RawMessage

	// ParentKey names the parent by import key (a row of this batch or of an
	// earlier one); ParentID by id. At most one is set.
	ParentKey string
	ParentID  *uuid.UUID

	// AuthorID is a legacy hatamoto_authors id; AuthorName resolves a person by name.
	// Without either, a plain-text attributes.author is resolved like a save.
	AuthorID   *uuid.UUID
	AuthorName string

	// BylinePersonID credits a person entity; BylineOrg the site organisation.
	BylinePersonID *uuid.UUID
	BylineOrg      bool

	// Dates; zero values default to now (created/updated) and, for a
	// published item, to its creation date (published).
	PublishedAt, CreatedAt, UpdatedAt time.Time
}

type ImportItemResult struct {
	Key     string
	ID      uuid.UUID
	Created bool
	Err     error
}

type ImportRecord struct {
	ID         *uuid.UUID // existing entity to update; nil inserts
	SchemaID   uuid.UUID
	Name, Slug string
	Status     EntityStatus
	Attributes json.RawMessage
	Metadata   json.RawMessage
	ParentID   *uuid.UUID
	AuthorID   *uuid.UUID
	ActorID    *uuid.UUID

	BylinePersonID *uuid.UUID
	BylineOrg      bool

	// Locale is a BCP 47 tag; empty inserts the site language and keeps the
	// stored value on update.
	Locale string

	CreatedAt, UpdatedAt, PublishedAt time.Time
}

type ImportResult struct {
	Created, Updated, Failed int
	Items                    []ImportItemResult
}

type ImportStore interface {
	// GetByImportKey returns the entity imported under key, ErrEntityNotFound
	// when there is none.
	GetByImportKey(ctx context.Context, key string) (*Entity, error)
	// ImportUpsert inserts rec, or updates the entity rec.ID names, keeping
	// the dates rec carries (the trigger-free import path). created is true
	// for an insert.
	ImportUpsert(ctx context.Context, rec *ImportRecord) (e *Entity, created bool, err error)
}

type ImportSummary struct {
	Source                   string
	Created, Updated, Failed int
}

type JSONLDBuilder func(jsonLD map[string]any, entity *Entity, attrs map[string]any, baseURL string)

type JSONLDEnricher func(ent *Entity, baseURL string, doc map[string]any)

type KeysetPage struct {
	Cursor    *string `json:"cursor,omitempty"` // Base64-encoded cursor
	Limit     int     `json:"limit"`
	Direction string  `json:"direction"` // "next" or "prev"
}

type ListEntitiesFilter struct {
	SchemaID *uuid.UUID `json:"schema_id,omitempty"`
	// ExcludeSchemaIDs drops the entities of these types.
	ExcludeSchemaIDs []uuid.UUID   `json:"exclude_schema_ids,omitempty"`
	Status           *EntityStatus `json:"status,omitempty"`
	Search           string        `json:"search,omitempty"`
	// AuthorID keeps entities with this byline.
	AuthorID *uuid.UUID `json:"author_id,omitempty"`
	// PersonID keeps entities credited to this person.
	PersonID *uuid.UUID `json:"person_id,omitempty"`
	// TermID keeps entities tagged with this term or one of its descendants.
	TermID *uuid.UUID `json:"term_id,omitempty"`
	// Under keeps the descendants (children, grandchildren, ...) of this entity.
	Under *uuid.UUID `json:"under,omitempty"`
	// UpdatedFrom (inclusive) and UpdatedBefore (exclusive) bound updated_at.
	UpdatedFrom   *time.Time `json:"updated_from,omitempty"`
	UpdatedBefore *time.Time `json:"updated_before,omitempty"`
	// Sort is name | status | updated | created (default updated, newest
	// first); Asc flips the direction. Only the offset listing honours it.
	Sort string `json:"sort,omitempty"`
	Asc  bool   `json:"asc,omitempty"`
}

type ListFilter struct {
	// SchemaSlugs restricts to these schemas (empty: any schema).
	SchemaSlugs []string
	// TermID restricts to entities attached to the term.
	TermID uuid.UUID
	// AuthorID restricts to entities written by this author.
	AuthorID uuid.UUID
	// PersonID restricts to entities credited to this person.
	PersonID uuid.UUID
	// Search is a websearch-syntax query matched against the entity's
	// full-text vector (name, excerpt, content), best match first. Entities
	// marked no_index never appear in search results.
	Search string
	// Attr restricts to entities whose attribute Attr equals AttrEq (a string,
	// or the number/boolean AttrEq spells), or that have the attribute at all
	// when AttrEq is empty and AttrEqSet is false. With AttrEqSet an empty
	// AttrEq matches the empty string only. The match is a JSONB containment test (@>), served
	// by the GIN index on attributes. An invalid key matches nothing.
	Attr, AttrEq string
	AttrEqSet    bool
	// IncludeScheduled adds scheduled entities (published_at is their date) to
	// the published ones. Drafts and archived entities never appear.
	IncludeScheduled bool
	// Order is "" (newest first), "-published_at", "published_at", "name",
	// "-name", "updated_at", "-updated_at", "attr:<key>" or "-attr:<key>" (numeric values sort as numbers,
	// before the rest; entities lacking the attribute last). Anything else
	// gives the default order.
	Order string
	// ExcludeID leaves this entity out (e.id <> ExcludeID) when set.
	ExcludeID uuid.UUID
	// Offset skips this many more rows on top of (page-1)*perPage; clamped to
	// 0..MaxListOffset. The returned total stays the raw match count.
	Offset int
}

type LiveFunc func(ctx context.Context, ids []uuid.UUID)

type OffsetPage struct {
	Page  int `json:"page"`
	Limit int `json:"limit"`
}

type OffsetPagedResult[T any] struct {
	Items      []T `json:"items"`
	Total      int `json:"total"`
	Page       int `json:"page"`
	Limit      int `json:"limit"`
	TotalPages int `json:"total_pages"`
}

type PagedResult[T any] struct {
	Items      []T     `json:"items"`
	NextCursor *string `json:"next_cursor,omitempty"`
	PrevCursor *string `json:"prev_cursor,omitempty"`
	HasMore    bool    `json:"has_more"`
	Total      *int    `json:"total,omitempty"` // Only populated when requested
}

type ParentCount struct {
	Parent *Entity
	Count  int
}

type PathChangeFunc func(ctx context.Context, before, after *Entity, actor *uuid.UUID)

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

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

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

type PublicPagedResult struct {
	Items       []*Entity `json:"items"`
	Total       int       `json:"total"`
	Page        int       `json:"page"`
	PerPage     int       `json:"per_page"`
	TotalPages  int       `json:"total_pages"`
	HasNext     bool      `json:"has_next"`
	HasPrevious bool      `json:"has_previous"`
}

type PublicRepository interface {
	// GetPublishedBySlug retrieves a published entity by slug for a tenant.
	GetPublishedBySlug(ctx context.Context, slug string) (*Entity, error)

	// GetPublishedByID retrieves a published entity by ID.
	GetPublishedByID(ctx context.Context, entityID uuid.UUID) (*Entity, error)

	// GetPublishedByIDs retrieves multiple published entities by their IDs.
	GetPublishedByIDs(ctx context.Context, ids []uuid.UUID) ([]*Entity, error)

	// ListPublished retrieves paginated published base entities of one schema.
	ListPublished(ctx context.Context, schemaSlug string, page, perPage int) (*PublicPagedResult, error)

	// ListPublishedBySchemas is ListPublished over several schema slugs (a
	// schema and its aliases).
	ListPublishedBySchemas(ctx context.Context, schemaSlugs []string, page, perPage int) (*PublicPagedResult, error)

	// ListAllPublished retrieves all published entities for sitemap generation.
	ListAllPublished(ctx context.Context) ([]*SitemapEntry, error)

	// ListAllPublishedWithAttrs is ListAllPublished that also hydrates
	// SitemapEntry.Attrs with the named top-level attributes (the ones schema
	// URL overrides compare against).
	ListAllPublishedWithAttrs(ctx context.Context, attrKeys []string) ([]*SitemapEntry, error)

	// GetHomepage retrieves the homepage entity (slug = "home" or first published page).
	GetHomepage(ctx context.Context) (*Entity, error)

	// GetPublishedBySlugAndSchema retrieves a published entity by slug filtered to a specific schema slug.
	GetPublishedBySlugAndSchema(ctx context.Context, slug string, schemaSlug string) (*Entity, error)

	// GetPublishedBySlugAndSchemas is GetPublishedBySlugAndSchema over several
	// schema slugs (a schema and its aliases).
	GetPublishedBySlugAndSchemas(ctx context.Context, slug string, schemaSlugs []string) (*Entity, error)

	// ListPublishedByAttribute retrieves published entities where a specific JSONB attribute matches a value.
	// Returns the matching entities, the total count, and any error.
	ListPublishedByAttribute(ctx context.Context, schemaSlugs []string, attrKey string, attrValue string, limit int, offset int) ([]*Entity, int, error)
}

type RefUser struct {
	ID         uuid.UUID
	Name, Slug string
	SchemaSlug string
	Status     EntityStatus
	UpdatedAt  time.Time
}

type ReuseStatus struct {
	Block, Part bool
}

type SQLDB interface {
	Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}

type SaveOpts struct {
	ChangeSummary string // "" keeps "Updated in the builder"
	Autosave      bool   // a background save: recorded as AutosaveSummary, coalesced with the last one
	Publish       bool   // flip the page live after the save
	// ExpectedVersion makes the write atomic with the version check: the store
	// compares it under its row lock and returns a *VersionConflictError.
	ExpectedVersion *int

	// AfterParse runs once the doc parsed and the role is known, before the
	// reuse rules; BeforeWrite runs after every check, before the write. A
	// non-nil result refuses the save.
	AfterParse  func(role string) *DocProblem
	BeforeWrite func() *DocProblem
	// Tune changes the update before it is written (the admin sets the title).
	Tune func(in *UpdateEntityInput)
	// PublishGate returns why a requested publish is skipped ("" publishes).
	PublishGate func(saved *Entity) string
}

type SavedDoc struct {
	Entity *Entity // as the service returned it, published when it was
	Parsed *builder.Doc
	// TakenSlug is the address Tune asked for that was in use; the entity kept its old one.
	TakenSlug string
	// PublishSkipped is the PublishGate's reason; PublishErr a failed status
	// change. Either way the doc is stored.
	PublishSkipped string
	PublishErr     error
}

type SchemaDefinition struct {
	Type          string                     `json:"type"`
	SchemaOrgType string                     `json:"x-schema-org-type,omitempty"`
	Properties    map[string]*SchemaProperty `json:"properties,omitempty"`
	Required      []string                   `json:"required,omitempty"`
}

type SchemaLister interface {
	List(ctx context.Context) ([]*EntitySchema, error)
}

type SchemaPatternFunc func(ctx context.Context, before, after *EntitySchema)

type SchemaProperty struct {
	Type              string                     `json:"type"`
	Format            string                     `json:"format,omitempty"`
	Title             string                     `json:"title,omitempty"`
	SchemaOrgType     string                     `json:"x-schema-org-type,omitempty"`
	SchemaOrgProperty string                     `json:"x-schema-org-property,omitempty"`
	Properties        map[string]*SchemaProperty `json:"properties,omitempty"`
	Items             *SchemaProperty            `json:"items,omitempty"`
	Required          []string                   `json:"required,omitempty"`
}

type SchemaRepository interface {
	Create(ctx context.Context, input *CreateSchemaInput) (*EntitySchema, error)
	GetByID(ctx context.Context, id uuid.UUID) (*EntitySchema, error)
	GetBySlug(ctx context.Context, slug string) (*EntitySchema, error)
	Update(ctx context.Context, id uuid.UUID, input *UpdateSchemaInput) (*EntitySchema, error)
	Delete(ctx context.Context, id uuid.UUID) error
	List(ctx context.Context) ([]*EntitySchema, error)
	CountEntities(ctx context.Context, schemaID uuid.UUID) (int, error)
}

type SchemaSitemapSettings struct {
	Priority   *float64 `json:"priority,omitempty"`
	ChangeFreq string   `json:"changefreq,omitempty"`
	Exclude    bool     `json:"exclude,omitempty"`
}

type SchemaStatusCount struct {
	SchemaID uuid.UUID
	Status   EntityStatus
	Count    int
}

type SchemaURLConfig struct {
	SchemaSlug string
	Name       string
	// Aliases are extra schema slugs resolving to this schema.
	Aliases     []string
	Pattern     *urlpattern.Pattern
	ArchivePath string
	// SitemapGroup is the sitemap group the schema's entries belong to.
	SitemapGroup string
	Overrides    []SchemaURLOverride
	Sitemap      SchemaSitemapSettings
	SectionPages bool
	// ArchiveTitle and ArchiveDescription are the trimmed settings values;
	// empty when unset.
	ArchiveTitle       string
	ArchiveDescription string
	// ArchiveCrumbLabel is the trimmed archive_crumb_label setting.
	ArchiveCrumbLabel string
	// Explicit is true when the schema's settings supplied url_pattern.
	Explicit bool
}

type SchemaURLOverride struct {
	Attribute    string `json:"attribute"`
	Equals       string `json:"equals"`
	URLPattern   string `json:"url_pattern"`
	SitemapGroup string `json:"sitemap_group,omitempty"`
}

type SchemaURLSettings struct {
	URLPattern   string                `json:"url_pattern,omitempty"`
	ArchivePath  string                `json:"archive_path,omitempty"`
	SitemapGroup string                `json:"sitemap_group,omitempty"`
	Aliases      []string              `json:"aliases,omitempty"`
	Overrides    []SchemaURLOverride   `json:"overrides,omitempty"`
	Sitemap      SchemaSitemapSettings `json:"sitemap"`
	SectionPages bool                  `json:"section_pages,omitempty"`
	// ArchiveTitle and ArchiveDescription override the archive page heading
	// and meta description (see MaxArchiveTitleLen / MaxArchiveDescriptionLen).
	ArchiveTitle       string `json:"archive_title,omitempty"`
	ArchiveDescription string `json:"archive_description,omitempty"`
	// ArchiveCrumbLabel is the section label in an entity's breadcrumb; it
	// falls back to ArchiveTitle, then the schema name.
	ArchiveCrumbLabel string `json:"archive_crumb_label,omitempty"`
	// SchemaOrgType is the JSON-LD @type for entities of schemas that have no
	// x-schema-org annotations and no plugin builder. Must be one of
	// AllowedSchemaOrgTypes (checked on write only). Types that require
	// fields the generic document cannot supply (FAQPage, Product, Event) are
	// excluded; use annotations or a plugin builder for those.
	SchemaOrgType string `json:"schema_org_type,omitempty"`
	// Editor selects the admin editing screen for the type: "" is the generic
	// form, EditorPost is the post (TipTap) editor used by blog posts.
	// Any other value, including a non-string, reads as "" (checked on write only).
	Editor EditorSetting `json:"editor,omitempty"`
}

type SeriesRow struct {
	ID, Name, Slug string
	Status         EntityStatus
	Attributes     []byte
	PublishedAt    *time.Time
}

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

type SettingsError struct{ Field, Msg string }

type SitemapEntry struct {
	// ID is the entity row id (not serialised); the paths endpoint matches it
	// against the configured homepage.
	ID            uuid.UUID `json:"-"`
	Slug          string    `json:"slug"`
	SchemaSlug    string    `json:"schema_slug"`
	UpdatedAt     string    `json:"updated_at"`
	Priority      float64   `json:"priority"`
	ChangeFreq    string    `json:"change_freq"`
	NoIndex       bool      `json:"no_index"`
	IncludeInLLMs bool      `json:"include_in_llms"`
	// EntityFormat is the value of attributes.format, used by the sitemap
	// generator to route playbook entities with format='online_report' to
	// /reports/{slug} instead of /playbooks/{slug} — reports have their
	// own canonical URL family even though they share the playbook schema.
	// Empty string for entities where attributes.format is unset or not a
	// string. Only playbook-schema entities use this today.
	EntityFormat string `json:"entity_format,omitempty"`
	// ParentSlug is the slug of the entity's parent ("" for roots); it fills
	// {parent} in URL patterns.
	ParentSlug string `json:"parent_slug,omitempty"`
	// AncestorPath is the slash-joined slugs of every ancestor, root first
	// ("" for roots); it fills {path}. ParentSlug is its last segment.
	AncestorPath string `json:"ancestor_path,omitempty"`
	// PublishedAt (created_at when unset) fills {year}, {month} and {day}.
	PublishedAt time.Time `json:"-"`
	// Attrs holds the top-level attributes requested through
	// ListAllPublishedWithAttrs, flattened to strings.
	Attrs map[string]string `json:"-"`
}

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

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

type UpdateEntityInput struct {
	Name          *string          `json:"name,omitempty"`
	Slug          *string          `json:"slug,omitempty"`
	Locale        *string          `json:"locale,omitempty"` // re-tags the entity; nil leaves it as stored
	Attributes    *json.RawMessage `json:"attributes,omitempty"`
	Metadata      *json.RawMessage `json:"metadata,omitempty"`
	ChangeSummary *string          `json:"change_summary,omitempty"`
	// Autosave marks a background save. It is recorded with AutosaveSummary,
	// and a run of autosaves by one person within AutosaveWindow keeps a single
	// version (the state before the run), so history holds checkpoints, not
	// every pause in typing. Explicit saves always create a version.
	Autosave bool `json:"-"`
	// ExpectedVersion, when set, makes the write conditional: the repository
	// compares it with the stored version under its row lock and returns a
	// *VersionConflictError instead of writing when they differ.
	ExpectedVersion *int `json:"-"`
	// KeepUpdatedAt leaves updated_at as it is (the version still advances).
	// Internal: used by `builder convert`, so a lossless shape
	// change does not look like a content edit (JSON-LD dateModified, sitemap lastmod).
	KeepUpdatedAt bool `json:"-"`
	// ParentID moves the entity under a parent; ClearParent makes it a root.
	// Both unset leaves the parent alone. The same holds for AuthorID.
	ParentID    *uuid.UUID `json:"parent_id,omitempty"`
	ClearParent bool       `json:"clear_parent,omitempty"`
	AuthorID    *uuid.UUID `json:"author_id,omitempty"`
	ClearAuthor bool       `json:"clear_author,omitempty"`
	// BylinePersonID sets the credited person and ClearBylinePerson removes
	// it; BylineOrg sets or clears the site-organisation byline. Both unset
	// leaves the byline alone. The columns are independent: a caller that
	// switches from a person to the organisation sets both.
	BylinePersonID    *uuid.UUID `json:"byline_person_id,omitempty"`
	ClearBylinePerson bool       `json:"clear_byline_person,omitempty"`
	BylineOrg         *bool      `json:"byline_org,omitempty"`
	// Status is set by the service for a person or a block/part (see lockedStatus); unset
	// leaves the status alone.
	Status *EntityStatus `json:"-"`
}

type UpdateSchemaInput struct {
	Name        *string          `json:"name,omitempty"`
	Description *string          `json:"description,omitempty"`
	Schema      *json.RawMessage `json:"schema,omitempty"`
	Settings    *json.RawMessage `json:"settings,omitempty"`
}

type UpdateStatusInput struct {
	Status EntityStatus `json:"status"`
}

type ValidationError struct {
	Path    string `json:"path"`
	Message string `json:"message"`
	// Keyword is the JSON Schema keyword that failed ("required", "maxLength",
	// ...), set on the leaf errors; the admin forms map it to friendly text.
	Keyword string `json:"keyword,omitempty"`
}

type ValidationResult struct {
	Valid  bool              `json:"valid"`
	Errors []ValidationError `json:"errors,omitempty"`
}

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

type VersionConflictError struct{ Current int }

type VersionDiff struct {
	Field    string `json:"field"`
	OldValue any    `json:"old_value"`
	NewValue any    `json:"new_value"`
}