application

type BehaviorFactory func(services BehaviorServices) entities.ResourceBehavior

type BehaviorInfo struct {
	Slug        string `json:"slug"`
	DisplayName string `json:"displayName"`
	Description string `json:"description"`
	Enabled     bool   `json:"enabled"`
	Manageable  bool   `json:"manageable"`
}

type BehaviorMetaRegistry map[string]entities.BehaviorMeta

type BehaviorServices struct {
	Resources     repositories.ResourceRepository
	Triples       repositories.TripleRepository
	ResourceTypes repositories.ResourceTypeRepository
	Logger        entities.Logger
	// Writer lets behaviors create, update, or delete other resources through
	// the full ResourceService pipeline. See lazyResourceWriter for the
	// cycle-breaking rationale behind how this is wired.
	Writer ResourceWriter
}

type ClassDescription struct {
	ClassIRI   string                `json:"class_iri"`
	Predicates []string              `json:"predicates"`
	Instances  []repositories.KGTerm `json:"instances,omitempty"`
}

type ConsolidationGroupParams struct {
	fx.In
	EventStore domain.EventStore
	Extractor  entities.FactExtractor `optional:"true"`
	Service    ResourceService
	TypeRepo   repositories.ResourceTypeRepository
	Registry   *PresetRegistry
	Logger     entities.Logger
}

type ConversationalAgent interface {
	// Configured reports whether an LLM is configured; when false, the other
	// methods return a clear not-configured error and the UI should say so.
	Configured() bool
	// Converse runs one turn synchronously and returns the response as the
	// versioned widget contract (pkg/widgets).
	Converse(ctx context.Context, conversationID, userID, message string) (widgets.Response, error)
	// ConverseStream runs one turn, emitting text deltas, any pending tool
	// confirmation (input_requested), then widgets and done. A non-empty
	// skill converses with that one skill directly — built as the turn's
	// root agent, bypassing coordinator routing — so a client's flow stays
	// deterministic; empty keeps the coordinator.
	ConverseStream(ctx context.Context, conversationID, userID, message, skill string, emit appagents.EventSink) error
	// ResumeConfirmation answers a pending mutating-tool confirmation and
	// streams the rest of the turn. Pending confirmations live in the
	// durable session, so they survive refreshes and restarts. A non-nil
	// payload on an approval replaces the tool call's arguments wholesale
	// (approve-with-edits): what executes is exactly what the user
	// submitted. A nil payload runs the original arguments; a payload on a
	// rejection is ignored. skill must repeat the value the paused turn ran
	// with (the resume rebuilds the same root agent).
	ResumeConfirmation(
		ctx context.Context, conversationID, userID, callID string, confirmed bool,
		payload map[string]any, skill string, emit appagents.EventSink,
	) error
	// History returns the conversation so far, oldest first.
	History(ctx context.Context, conversationID, userID string) ([]entities.AgentMessage, error)
}

type CreateResourceCommand struct {
	TypeSlug string
	Data     json.RawMessage
}

type CreateResourceTypeCommand struct {
	Name        string
	Slug        string
	Description string
	Context     json.RawMessage
	Schema      json.RawMessage
}

type DeleteResourceCommand struct {
	ID string
}

type DeleteResourceTypeCommand struct {
	ID string
}

type DisplayValuesGroupParams struct {
	fx.In
	EventStore domain.EventStore
	ProjMgr    repositories.ProjectionManager
	Logger     entities.Logger
}

type EnsureCheckpointFunc func(ctx context.Context, subscriber string, position int64) error

type EpisodicQuery struct {
	From         string
	Until        string
	Anchors      []string
	EventType    string
	ResourceType string
	// Limit caps results (default 20, max 100 — over-asks are capped, not errors).
	Limit  int
	Cursor string
}

type EpisodicRecall interface {
	Recall(ctx context.Context, q EpisodicQuery) (*EpisodicRecallResult, error)
	// Similar ranks events by deterministic structural similarity to the
	// seed event (see the weight constants in episodic_similar.go).
	Similar(ctx context.Context, q SimilarQuery) (*SimilarResult, error)
	// EventByURN returns one event's full stored payload — the explicit
	// drill-in complement to the compact shapes above.
	EventByURN(ctx context.Context, urn string) (*FetchedEvent, error)
}

type EpisodicRecallResult struct {
	Events  []RecalledEvent
	Cursor  string
	HasMore bool
}

type EventReferenceGroupParams struct {
	fx.In
	References repositories.EventReferenceRepository
	Logger     entities.Logger
}

type FetchedEvent struct {
	RecalledEvent
	Payload map[string]any `json:"payload"`
}

type FileService = services.FileService

type GrantPermissionCommand struct {
	ResourceID string          `json:"resource_id"`
	AgentID    string          `json:"agent_id"`
	Actions    json.RawMessage `json:"actions"` // JSON array: ["read","modify","delete"]
}

type InstallPresetResult struct {
	Created   []string       `json:"created"`
	Updated   []string       `json:"updated,omitempty"`
	Unchanged []string       `json:"unchanged,omitempty"`
	Skipped   []string       `json:"skipped"`
	Seeded    map[string]int `json:"seeded,omitempty"` // slug -> count of fixtures created
	Warnings  []string       `json:"warnings,omitempty"`
}

type KnowledgeGraphService interface {
	// Active reports whether the underlying store is connected. MCP tools
	// short-circuit when inactive so the LLM gets a clear "not configured"
	// signal instead of empty results.
	Active() bool

	// Query runs an arbitrary SPARQL query (SELECT/ASK/CONSTRUCT/DESCRIBE).
	// Use for the LLM-facing kg_sparql_query tool when something complex is
	// needed; the other methods cover most reasoning patterns more cheaply.
	Query(ctx context.Context, sparql string) (repositories.KGQueryResult, error)

	// ExpandEntity returns the one-hop neighborhood of an IRI as a list of
	// triples. depth defaults to 1; depths >1 walk reference chains via
	// SPARQL property paths.
	ExpandEntity(ctx context.Context, iri string, depth int) ([]repositories.Triple, error)

	// SearchEntities returns IRIs whose label-like properties (rdfs:label,
	// schema:name, foaf:name, dcterms:title) match q (case-insensitive
	// substring). When classIRI is non-empty, results are restricted to
	// instances of that class (subclasses included via rdfs:subClassOf*).
	// limit defaults to 20, capped at 100.
	SearchEntities(ctx context.Context, q, classIRI string, limit int) ([]repositories.KGTerm, error)

	// DescribeClass returns the predicates and (optionally) example instances
	// of a class IRI. Useful for LLM introspection — "what does foaf:Person
	// look like in this graph?".
	DescribeClass(ctx context.Context, classIRI string, sampleInstances int) (ClassDescription, error)

	// FindPath returns a best-effort path of triples connecting two IRIs
	// within maxHops. Returns nil triples when no path is found within the
	// hop budget; nil error in that case (path-not-found is not an error).
	FindPath(ctx context.Context, from, to string, maxHops int) ([]repositories.Triple, error)

	// ListClasses returns the IRIs of every class declared in the graph
	// (anything typed `rdfs:Class` or `owl:Class`). Useful for LLM
	// introspection — "what kinds of things does this user's graph
	// contain?".
	ListClasses(ctx context.Context) ([]repositories.KGTerm, error)
}

type KnownToolsFunc func(ctx context.Context) (map[string]bool, error)

type LexicalGroupParams struct {
	fx.In
	EventStore domain.EventStore
	Index      repositories.LexicalIndex
	Logger     entities.Logger
}

type LexicalSearch interface {
	// Search returns matches plus the mode that produced them
	// (LexicalModeFTS5 or LexicalModeGraphLabels).
	Search(ctx context.Context, query string, limit int) ([]repositories.LexicalHit, string, error)
}

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

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

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

type ManagerParams struct {
	EventStore  domain.EventStore
	Checkpoints subscriptions.CheckpointStore
	Parking     subscriptions.ParkingLot
	Notifier    WakeSource
	Config      config.Config
	Logger      entities.Logger
	Groups      []SubscriberGroup
	// RebuildOnStart names groups whose checkpoint is reset (and projection
	// truncated) before the workers launch — the OXIGRAPH_REBUILD path, now
	// expressed as a checkpoint reset so there is one replay mechanism.
	RebuildOnStart []string
	// EnsureCheckpoint backs SubscriberGroup.StartAtHead. nil is only valid
	// when no group sets StartAtHead — such a group would then never start.
	EnsureCheckpoint EnsureCheckpointFunc
}

type MemoryRecall interface {
	Recall(ctx context.Context, q RecallQuery) ([]RecalledFact, error)
}

type MountedHandler struct {
	Method    string
	Path      string
	Protected bool
	Handler   http.HandlerFunc
	Source    string
}

type OxigraphGroupParams struct {
	fx.In
	EventStore domain.EventStore
	Store      repositories.KnowledgeGraphStore
	TypeRepo   repositories.ResourceTypeRepository
	Logger     entities.Logger
}

type PlaybookService interface {
	RecordOutcome(ctx context.Context, id string, outcome entities.PlaybookOutcome, note string) (
		*entities.Resource, error)
}

type PresetDefinition struct {
	Name         string
	Description  string
	Types        []PresetResourceType
	Behaviors    map[string]BehaviorFactory       // slug -> factory invoked at startup with services
	BehaviorMeta map[string]entities.BehaviorMeta // slug -> metadata for UI/config
	Screens      fs.FS                            // optional embedded screen components
	Sidebar      *PresetSidebarConfig             // optional sidebar defaults
	Handlers     []PresetHTTPHandler              // optional HTTP routes mounted under /api
	// Links declares cross-type relationships that live outside any resource
	// type's schema. Each link activates when both SourceType and TargetType
	// are installed — enabling a "finance-education" integration preset to
	// link Invoice and Guardian without either preset depending on the other.
	// See PresetLinkDefinition for semantics.
	Links       []PresetLinkDefinition
	AutoInstall bool // if true, types are auto-created at startup
	// Consolidates lists resource type slugs whose resources carry
	// unstructured episodic content (notes, transcripts, captured web pages,
	// free-text observations) that memory consolidation should distill facts
	// from. Structured domain types are already semantic memory — their typed
	// data and graph projection state the knowledge directly — so running LLM
	// fact-extraction over them would only duplicate it at BYOK cost; leave
	// them undeclared. Nothing is eligible by default, and a preset may
	// declare slugs a companion preset defines. Memory types themselves
	// (fact, playbook) are never eligible regardless of declarations.
	Consolidates []string
}

type PresetHTTPHandler struct {
	Method    string // GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD
	Path      string // relative to /api, e.g. "/leads/upload"
	Factory   func(BehaviorServices) http.HandlerFunc
	Protected bool // true => mount behind auth middleware
}

type PresetHTTPHandlers []MountedHandler

type PresetLinkDefinition struct {
	Name            string
	SourceType      string
	TargetType      string
	PropertyName    string
	PredicateIRI    string
	DisplayProperty string
}

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

type PresetResourceType struct {
	Name        string
	Slug        string
	Description string
	Context     json.RawMessage
	Schema      json.RawMessage
	Fixtures    []json.RawMessage // optional seed data created on install
}

type PresetSidebarConfig struct {
	HiddenSlugs []string          // resource type slugs hidden by default
	MenuGroups  map[string]string // slug -> parent slug for sidebar nesting
}

type RecallQuery struct {
	// About restricts results to facts about this entity URN.
	About string
	// Keyword is a case-insensitive substring match on the fact statement.
	Keyword string
	// Limit caps results (default 20, max 100).
	Limit int
	// IncludeProvenance adds the prov:wasDerivedFrom source event IDs.
	IncludeProvenance bool
}

type RecalledEvent struct {
	// ID is the event URN (urn:event:<id>), consistent with the
	// prov:wasDerivedFrom identifiers in the memory preset.
	ID           string `json:"id"`
	EventType    string `json:"eventType"`
	Timestamp    string `json:"timestamp"`
	AggregateID  string `json:"aggregateId"`
	ResourceType string `json:"resourceType,omitempty"`
	Summary      string `json:"summary,omitempty"`
	// ReferencedResources lists the resource URNs the event references — the
	// aggregate itself plus resource URNs in the payload — from the
	// event-reference projection (story #411). Empty until the projection has
	// caught up with the event.
	ReferencedResources []string `json:"referencedResources,omitempty"`
}

type RecalledFact struct {
	ID              string  `json:"id"`
	Statement       string  `json:"statement"`
	About           string  `json:"about,omitempty"`
	Confidence      float64 `json:"confidence,omitempty"`
	AttributedTo    string  `json:"attributedTo,omitempty"`
	GeneratedAtTime string  `json:"generatedAtTime,omitempty"`
	WasRevisionOf   string  `json:"wasRevisionOf,omitempty"`
	// DerivedFrom holds the prov:wasDerivedFrom source event IDs.
	DerivedFrom []string `json:"wasDerivedFrom,omitempty"`
	// Source is "working" for facts read from the synchronous SQL projection
	// (may not be in the graph yet) or "graph" for knowledge-graph results.
	Source string `json:"source,omitempty"`
}

type ReferencePropertyDef struct {
	PropertyName    string // e.g. "invoiceId"
	PredicateIRI    string // e.g. "https://schema.org/object"
	TargetType      string // e.g. "invoice"
	DisplayProperty string // e.g. "name" — property on the target resource shown in lists
}

type ResourceBehaviorRegistry map[string]entities.ResourceBehavior

type ResourceCreator interface {
	Create(ctx context.Context, cmd CreateResourceCommand) (*entities.Resource, error)
}

type ResourcePermissionService interface {
	Grant(ctx context.Context, cmd GrantPermissionCommand) error
	Revoke(ctx context.Context, cmd RevokePermissionCommand) error
	ListForResource(ctx context.Context, resourceID string) ([]*entities.ResourcePermission, error)
}

type ResourceService interface {
	// FilterAccessibleResourceIDs returns the subset of `ids` that the
	// caller is allowed to read. Used by the knowledge-graph permission
	// filter to drop forbidden subjects/objects from query results before
	// they leave the MCP server. Nil identity (system context) returns the
	// input unchanged. `urn:person:*` and `urn:org:*` ARE gated alongside
	// regular resources because they carry FOAF/vCard PII; `urn:type:*` /
	// `urn:theme:*`, full ontology IRIs, blank nodes, and literals pass
	// through unchanged.
	FilterAccessibleResourceIDs(ctx context.Context, ids []string) ([]string, error)
	Create(ctx context.Context, cmd CreateResourceCommand) (*entities.Resource, error)
	GetByID(ctx context.Context, id string) (*entities.Resource, error)
	// GetFlat returns a single resource as a flat projection row (camelCase keys),
	// including denormalized _display columns for x-resource-type references.
	// Used by detail views so the frontend can render reference names without a
	// client-side ID→name lookup cache. Returns an error for types with no
	// projection table; caller should fall back to GetByID.
	GetFlat(ctx context.Context, typeSlug, id string) (map[string]any, error)
	List(ctx context.Context, typeSlug, cursor string, limit int, sort repositories.SortOptions) (
		repositories.PaginatedResponse[*entities.Resource], error)
	ListFlat(ctx context.Context, typeSlug, cursor string, limit int, sort repositories.SortOptions) (
		repositories.PaginatedResponse[map[string]any], error)
	ListByField(ctx context.Context, typeSlug, fieldName, fieldValue string) (
		repositories.PaginatedResponse[*entities.Resource], error)
	ListWithFilters(ctx context.Context, typeSlug string, filters []repositories.FilterCondition,
		cursor string, limit int, sort repositories.SortOptions) (
		repositories.PaginatedResponse[*entities.Resource], error)
	ListFlatWithFilters(ctx context.Context, typeSlug string, filters []repositories.FilterCondition,
		cursor string, limit int, sort repositories.SortOptions) (
		repositories.PaginatedResponse[map[string]any], error)
	Update(ctx context.Context, cmd UpdateResourceCommand) (*entities.Resource, error)
	Delete(ctx context.Context, cmd DeleteResourceCommand) error
}

type ResourceTypeService interface {
	Create(ctx context.Context, cmd CreateResourceTypeCommand) (*entities.ResourceType, error)
	GetByID(ctx context.Context, id string) (*entities.ResourceType, error)
	GetBySlug(ctx context.Context, slug string) (*entities.ResourceType, error)
	List(ctx context.Context, cursor string, limit int) (
		repositories.PaginatedResponse[*entities.ResourceType], error)
	Update(ctx context.Context, cmd UpdateResourceTypeCommand) (*entities.ResourceType, error)
	Delete(ctx context.Context, cmd DeleteResourceTypeCommand) error
	ListPresets() []PresetDefinition
	InstallPreset(ctx context.Context, presetName string, update bool) (*InstallPresetResult, error)
	ListBehaviors(ctx context.Context, typeSlug string) ([]BehaviorInfo, error)
	SetBehaviors(ctx context.Context, typeSlug string, slugs []string) error
}

type ResourceWriter interface {
	Create(ctx context.Context, cmd CreateResourceCommand) (*entities.Resource, error)
	Update(ctx context.Context, cmd UpdateResourceCommand) (*entities.Resource, error)
	Delete(ctx context.Context, cmd DeleteResourceCommand) error
}

type RevokePermissionCommand struct {
	ResourceID string `json:"resource_id"`
	AgentID    string `json:"agent_id"`
}

type SimilarEvent struct {
	RecalledEvent
	Similarity float64 `json:"similarity"`
}

type SimilarQuery struct {
	// Seed is the seed event URN (urn:event:<id>).
	Seed string
	// Limit caps results (default 20, max 100 — over-asks are capped).
	Limit int
}

type SimilarResult struct {
	Events []SimilarEvent
}

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

type SortOptions = repositories.SortOptions

type SubscriberGroup struct {
	// Name is the subscriber's checkpoint name. Processes using the same name
	// share one position, so it must be stable across restarts and unique
	// across groups.
	Name string
	// Handler processes a single event from the feed. A group-private
	// EventDispatcher's Dispatch method satisfies this signature.
	Handler subscriptions.Handler
	// Options are per-group overrides appended after the Manager's defaults
	// (e.g. a smaller batch size for an expensive handler).
	Options []subscriptions.SubscriberOption
	// Truncate optionally clears the group's projection so a checkpoint reset
	// rebuilds it from empty (e.g. the Oxigraph store's Clear). nil means the
	// group has no separate projection to clear — display-values, for instance,
	// writes denormalized columns into other types' rows rather than owning a
	// table — and `worker checkpoint reset --truncate` reports that.
	Truncate func(context.Context) error
	// StartAtHead initializes a group that has never run before at the
	// current feed head instead of position 0, so enabling it on an instance
	// with existing history does not replay that history through the handler.
	// Only a missing checkpoint row is initialized — an existing row is never
	// moved, so an explicit `worker checkpoint reset` (which creates the row
	// at 0) remains the opt-in backfill path. Groups whose head
	// initialization fails are not started that run (fail closed): for an
	// expensive handler like consolidation, silently falling back to a
	// full-history replay is worse than sitting out one process lifetime.
	StartAtHead bool
}

type UpdateResourceCommand struct {
	ID   string
	Data json.RawMessage
}

type UpdateResourceTypeCommand struct {
	ID          string
	Name        string
	Slug        string
	Description string
	Context     json.RawMessage
	Schema      json.RawMessage
	Status      string
}

type UploadParams = services.UploadParams

type UploadResult = services.UploadResult

type WakeSource interface {
	Subscribe() <-chan struct{}
}

type WorkingMemory interface {
	// RecentFacts returns the newest non-superseded facts from the SQL
	// projection, freshest first. A non-empty about restricts to facts about
	// that entity INSIDE the query — filtering after the limit would silently
	// drop matches once other facts crowd the freshness window. limit <= 0
	// uses the default working-set size.
	RecentFacts(ctx context.Context, about string, limit int) ([]RecalledFact, error)
}