knowledgepage

type BuiltinPage struct {
	Slug    string
	Title   string
	Summary string
	Body    string
	Tags    []string
}

type BuiltinReconcileStats struct {
	Created int
	Updated int
	Skipped int
	Pruned  int
}

type BuiltinReconciler interface {
	// ReconcileBuiltins upserts the shipped set and prunes builtin rows whose
	// slug left it. Per shipped page: a live builtin row is updated only when
	// its content differs from the shipped content (which is exact, because
	// Update refuses builtin rows, so nothing else writes one); a live
	// non-builtin row on the slug means the operator superseded the topic and
	// is left alone; a soft-deleted builtin row means the operator hid the
	// page and it is not resurrected; otherwise the page is inserted. A
	// content update flows through the same invalidation an ordinary edit
	// does, so the page is re-embedded and re-versioned. Page-level failures
	// are joined, not short-circuited: one bad page does not block the rest.
	ReconcileBuiltins(ctx context.Context, pages []BuiltinPage) (BuiltinReconcileStats, error)

	// RestoreHidden un-hides every operator-hidden builtin page (a builtin
	// tombstone still holding its slug) whose slug no live page occupies, and
	// returns how many came back. It is the way back from Hide, so hiding is
	// never a one-way door; the caller follows it with ReconcileBuiltins so a
	// restored page is refreshed to the running release (and pruned again if
	// the release no longer ships it).
	RestoreHidden(ctx context.Context) (int, error)
}

type DedupCandidate struct {
	ID    string  `json:"id"`
	Slug  string  `json:"slug,omitempty"`
	Title string  `json:"title"`
	Score float64 `json:"score"`
	// Builtin marks a platform-shipped, read-only page (#1390): it cannot be
	// consolidated onto, so a caller shown this candidate either hides it and
	// writes their own page or knowingly creates a separate one (force_new).
	Builtin bool `json:"builtin,omitempty"`
}

type DuplicateProber interface {
	SemanticSearch(ctx context.Context, embedding []float32, limit int) ([]ScoredPage, error)
}

type EntityRef struct {
	ID             string `json:"id,omitempty"`
	PageID         string `json:"page_id,omitempty"`
	TargetType     string `json:"target_type"`
	AssetID        string `json:"asset_id,omitempty"`
	PromptID       string `json:"prompt_id,omitempty"`
	CollectionID   string `json:"collection_id,omitempty"`
	RefPageID      string `json:"ref_page_id,omitempty"`
	ConnectionKind string `json:"connection_kind,omitempty"`
	ConnectionName string `json:"connection_name,omitempty"`
	EntityURN      string `json:"entity_urn,omitempty"`
	InsightID      string `json:"insight_id,omitempty"`
	// MemoryID is set only by the parser for an mcp:memory: reference (fetch-only);
	// it is never persisted, since memory is not citable on a page (#699).
	MemoryID string `json:"memory_id,omitempty"`
	// ResourceID is set only by the parser for an mcp:resource: reference
	// (fetch-only); it is never persisted, since a managed resource is not citable
	// on a page (#1012).
	ResourceID string `json:"resource_id,omitempty"`
	// ScriptID is set only by the parser for an mcp:script: reference (#1302). Like
	// the memory and resource ids it is never persisted on a page, since a managed
	// script is not citable there; a prompt stores the serialized reference instead.
	ScriptID string `json:"script_id,omitempty"`
	// CallID is set only by the parser for an mcp:call: reference (#1321): the
	// audit event id of one recorded query or API invocation. Never persisted
	// on a page — a call record is per-user, so it is not citable there.
	CallID string `json:"call_id,omitempty"`
	// SessionID is set only by the parser for an mcp:session: reference
	// (#1322): the id of the session whose calls are read back from the audit
	// log. Never persisted on a page — a session is per-user, so it is not
	// citable there.
	SessionID string    `json:"session_id,omitempty"`
	Source    string    `json:"source,omitempty"`
	CreatedBy string    `json:"created_by,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type Filter struct {
	Tag    string
	Query  string
	Limit  int
	Offset int
}

type GraphReader interface {
	// ListEntityRefsForPages returns the references of every given page in one
	// query, so a corpus-wide graph is one round trip rather than N+1.
	ListEntityRefsForPages(ctx context.Context, pageIDs []string) ([]EntityRef, error)
}

type Page struct {
	ID             string   `json:"id" example:"kp_01HK7R8Z8M0Y6A5G1R6FQ2VQNK"`
	Slug           string   `json:"slug,omitempty" example:"fiscal-calendar"`
	Title          string   `json:"title" example:"Fiscal Calendar"`
	Summary        string   `json:"summary,omitempty" example:"How the company defines fiscal quarters."`
	Body           string   `json:"body" example:"# Fiscal Calendar\n\nQ1 begins..."`
	Tags           []string `json:"tags"`
	CreatedBy      string   `json:"created_by,omitempty" example:"alice@example.com"`
	CreatedEmail   string   `json:"created_email,omitempty" example:"alice@example.com"`
	UpdatedBy      string   `json:"updated_by,omitempty" example:"bob@example.com"`
	CurrentVersion int      `json:"current_version" example:"3"`
	// Builtin marks a page the platform ships in its binary and reconciles at
	// startup (#1390). Content edits are refused (ErrBuiltinReadOnly) because
	// the next release would overwrite them; SoftDelete stays available and is
	// the operator's way to hide the page — the reconcile respects the
	// tombstone instead of resurrecting it.
	Builtin   bool       `json:"builtin,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

type PageGuards struct {
	DedupThreshold   float64
	OversizeBytes    int
	OversizeSections int
}

type PageGuardsConfig struct {
	// DedupThreshold is the cosine similarity [0,1] at or above which creating a page
	// is blocked as a near-duplicate. Defaults to DefaultDedupThreshold. The gate only
	// acts when a real embedding provider is configured (cosine is undefined without).
	DedupThreshold float64 `yaml:"dedup_threshold"`
	// DedupDisabled turns the duplicate gate off entirely.
	DedupDisabled bool `yaml:"dedup_disabled"`
	// OversizeBytes is the body byte size at or above which the (non-blocking) split
	// suggestion fires. Defaults to DefaultOversizeBytes; negative disables this arm.
	OversizeBytes int `yaml:"oversize_bytes"`
	// OversizeSections is the markdown-heading count at or above which the split
	// suggestion fires. Defaults to DefaultOversizeSections; negative disables it.
	OversizeSections int `yaml:"oversize_sections"`
}

type PageRef struct {
	ID    string `json:"id"`
	Slug  string `json:"slug"`
	Title string `json:"title"`
}

type ReverseLookup interface {
	ListPagesReferencing(ctx context.Context, ref EntityRef) ([]PageRef, error)
}

type ScoredPage struct {
	Page  Page    `json:"page"`
	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
	Limit     int       // max results; clamped into [1, MaxHonoredLimit]
}

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

type Store interface {
	Insert(ctx context.Context, page Page) error
	Get(ctx context.Context, id string) (*Page, error)
	GetBySlug(ctx context.Context, slug string) (*Page, error)
	List(ctx context.Context, filter Filter) ([]Page, int, error)
	Update(ctx context.Context, id string, updates Update) error
	SoftDelete(ctx context.Context, id string) error
	ListVersions(ctx context.Context, pageID string, limit, offset int) ([]Version, int, error)
	GetVersion(ctx context.Context, pageID string, version int) (*Version, error)
	// Entity references (#664): the entities a page provides knowledge about.
	ListEntityRefs(ctx context.Context, pageID string) ([]EntityRef, error)
	// ValidateRefTargets checks each FK-backed reference target exists, so a
	// citation to a missing entity is rejected before the page is written (#690).
	ValidateRefTargets(ctx context.Context, refs []EntityRef) error
	// FilterExistingRefTargets returns the subset of refs whose target exists,
	// dropping stale references carried from a source insight (#690).
	FilterExistingRefTargets(ctx context.Context, refs []EntityRef) ([]EntityRef, error)
	AddEntityRefs(ctx context.Context, pageID string, refs []EntityRef) error
	ReplaceEntityRefs(ctx context.Context, pageID string, refs []EntityRef) error
	ReplaceEntityRefsBySource(ctx context.Context, pageID, source string, refs []EntityRef) error
	// ListPagesReferencing is the reverse lookup: the pages that reference a target.
	ListPagesReferencing(ctx context.Context, ref EntityRef) ([]PageRef, error)
}

type StoreSearcher interface {
	Store
	Searcher
	DuplicateProber
}

type Update struct {
	Slug          *string
	Title         *string
	Summary       *string
	Body          *string
	Tags          *[]string
	UpdatedBy     string
	ChangeSummary string
}

type Version struct {
	ID            string    `json:"id" example:"kpv_01HK7R9A"`
	PageID        string    `json:"page_id" example:"kp_01HK7R8Z8M0Y6A5G1R6FQ2VQNK"`
	Version       int       `json:"version" example:"2"`
	Title         string    `json:"title" example:"Fiscal Calendar"`
	Summary       string    `json:"summary,omitempty"`
	Body          string    `json:"body"`
	Tags          []string  `json:"tags"`
	CreatedBy     string    `json:"created_by,omitempty" example:"bob@example.com"`
	ChangeSummary string    `json:"change_summary,omitempty" example:"Clarified Q1 start"`
	CreatedAt     time.Time `json:"created_at"`
}