memory

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

type AttachmentBlock struct {
	// Filename is the sanitized, user-supplied name.
	Filename string `json:"filename"`
	// MIME is the kind-reported content type — a hint, not a verified fact.
	MIME string `json:"mime"`
	// SizeBytes is the kind-reported size. May be 0 when unreported.
	SizeBytes int64 `json:"sizeBytes,omitempty"`
	// Ref is the artifactstore handle for the original bytes.
	Ref string `json:"ref"`
	// TextRef is the artifactstore handle for the extracted text; EMPTY when no
	// extractor exists for this MIME (images, today). Its presence is
	// load-bearing: with TextRef empty the runner keeps a native block attached
	// for the whole session, since nothing else represents the file; with it set
	// the block is kept only on the arrival turn, because the text carries it
	// after.
	TextRef string `json:"textRef,omitempty"`
	// ArchiveRef is the handle of the ARCHIVE this member came out of; empty
	// for a file the user attached directly.
	//
	// Load-bearing at hydration: an archive member is excluded from the
	// persistent native-block window unless pinned, because its archive's
	// index already named it and stated its readability. Without this field a
	// bundle of 187 log files would fill that window with four arbitrary
	// members and name them in an unreadable-attachments note the agent was
	// never told about.
	ArchiveRef string `json:"archiveRef,omitempty"`

	// Pages is the extractor-reported page/slide count; 0 when the format has no
	// real notion of pages.
	Pages int `json:"pages,omitempty"`
}

type Authorizer interface {
	// AuthorizePut runs AFTER the Local.Put door has already authorized the
	// write, so it is NOT itself the write-permission gate. Its job is to WRITE
	// the entry-level relationships (memory_entry#session, #creator, and
	// caller-independent ones like artifact#parent) so future reads/deletes can
	// be checked. A non-nil error — e.g. a failed relationship write — denies
	// the write and reaches the caller as-is.
	//
	// With CallerFrom(ctx) absent (in-process controller calls),
	// implementations SHOULD allow the write unconditionally.
	AuthorizePut(ctx context.Context, e Entry) error

	// AuthorizeQuery post-filters a backend result once the EnsureApproval door
	// has authorized the scope as a whole, returning only the entries the
	// caller (CallerFrom(ctx)) may read. Invoked only when a caller is present,
	// so it is a finer per-entry layer on the door, not the read gate itself.
	// Implementations bulk-check to minimize round-trips.
	AuthorizeQuery(ctx context.Context, entries []Entry) ([]Entry, error)

	// AuthorizeDelete runs before backend.Delete; a non-nil error denies the
	// deletion. With CallerFrom(ctx) absent, implementations SHOULD allow.
	AuthorizeDelete(ctx context.Context, scope Scope, kind, id string) error

	// CleanupScope idempotently removes all entry-level authorization
	// relationships for the scope.
	CleanupScope(ctx context.Context, scope Scope) error
}

type Backend interface {
	Capabilities() Capabilities

	Put(ctx context.Context, e Entry) error
	Get(ctx context.Context, scope Scope, kind, id string) (Entry, bool, error)
	Delete(ctx context.Context, scope Scope, kind, id string) error
	// DeleteScope removes every entry under scope. Idempotent — an
	// empty scope is not an error.
	DeleteScope(ctx context.Context, scope Scope) error

	Query(ctx context.Context, q Query) (QueryResult, error)
	// QueryAllScopes is Query without the single-scope restriction; see
	// CrossScopeQuery. Backends must apply ordering before Offset/Limit.
	QueryAllScopes(ctx context.Context, q CrossScopeQuery) (QueryResult, error)
	Status(ctx context.Context, scope Scope) (ScopeStatus, error)
}

type Capabilities struct {
	// ContentSchemas: honors Kind.ContentSchema() for FieldEquals predicates.
	ContentSchemas bool
	// FieldRange: honors FieldFilter.Op values other than Eq (Lt, Lte, Gt, Gte,
	// IsNil, NotNil). Backends reporting false silently move non-Eq FieldFilter
	// predicates into DroppedPredicates.
	FieldRange bool
	// LinkTraversal: max hop depth. 0 = no link queries, 1 = one-hop,
	// -1 = unbounded.
	LinkTraversal int
	// ReverseLinks: can answer "what links TO this entry?".
	ReverseLinks bool
	// TagFilters: honors Query.Tags.
	TagFilters bool
	// TimeRange: honors Query.Since / Query.Until.
	TimeRange bool
}

type ContentBlock struct {
	// Type selects which of the fields below is populated: "text", "tool_use",
	// "tool_result" or "attachment".
	Type string `json:"type"`
	// Text is the block's prose; set only when Type == "text".
	Text string `json:"text,omitempty"`
	// ToolUse is the model's tool invocation; set only when Type == "tool_use".
	ToolUse *ToolUseBlock `json:"toolUse,omitempty"`
	// ToolResult is the tool's answer; set only when Type == "tool_result".
	ToolResult *ToolResultBlock `json:"toolResult,omitempty"`
	// Attachment carries a stored inbound file's handles and metadata, set only
	// when Type == "attachment" — one block per inbound attachment whose bytes
	// reached the store, whether or not extraction also succeeded (see
	// AttachmentBlock.TextRef).
	Attachment *AttachmentBlock `json:"attachment,omitempty"`
}

type CrossScopeQuery struct {
	ScopeKind string     // required, e.g. "session"
	Kinds     []string   // required, non-empty
	Since     *time.Time // inclusive
	Until     *time.Time // exclusive
	OrderDesc bool       // true = newest first
	Limit     int        // 0 = no limit
	Offset    int        // rows to skip after ordering
}

type EmbeddingProvider interface {
	Embed(ctx context.Context, text string) ([]float32, error)
}

type Entry struct {
	// Scope is the sub-universe the entry belongs to; queries never cross it.
	Scope Scope `json:"scope"`
	// Kind names the registered Kind; an unregistered one is refused at Put.
	Kind string `json:"kind"`
	// ID MUST start with the Kind's registered IDPrefix — enforced at Put.
	ID string `json:"id"`
	// CreatedAt is authorship time; canonicalized to microseconds before any
	// sameness comparison, since that is all a TIMESTAMPTZ column keeps.
	CreatedAt time.Time `json:"createdAt"`
	// Links are typed references out of this entry; nil and empty are the same
	// entry to the signed digest.
	Links []Link `json:"links,omitempty"`
	// Tags are an unordered SET — the digest sorts them, so two orderings are
	// one entry; nil and empty are likewise the same.
	Tags []string `json:"tags,omitempty"`
	// Content is the Kind's ContentSchema payload, opaque when it declares none.
	Content json.RawMessage `json:"content,omitempty"`
	// Provenance is nil on mutable kinds and required on append-only ones
	// wherever a ProvenanceVerifier is configured.
	Provenance *Provenance `json:"provenance,omitempty"`
}

type FieldFilter struct {
	// Path is the key the value is STORED under — the Content struct's `json`
	// tag, NOT its Go field name. Backends render the predicate as
	// content->>'<Path>', so "TurnIndex" for a field tagged `json:"turnIndex"`
	// extracts NULL and can never be true. Local.Query rejects a Path naming no
	// content key of the Kinds queried, rather than answering empty forever.
	//
	// Path is a TOP-LEVEL key, not a nesting expression: both SQL backends read
	// a dot as part of the key name (postgres's jsonb ->> takes a literal key,
	// sqlite's ->> quotes the operand into $."a.b"), so "a.b" selects a key
	// literally named "a.b" and never reaches a nested {"a":{"b":…}}. Nested
	// content is not queryable. The Kind should also list the key in
	// IndexedFields().
	Path string `json:"path"`
	// Op is the comparison; empty means equality.
	Op FieldOp `json:"op,omitempty"`
	// Value is the right-hand side; ignored by the IsNil/NotNil ops.
	Value any `json:"value,omitempty"`
}

type FieldOp string

type KGCommunity struct {
	// UUID is the graph's identifier for the cluster.
	UUID string `json:"uuid"`
	// Name is the cluster's generated label.
	Name string `json:"name"`
	// Summary describes what its members have in common.
	Summary string `json:"summary"`
	// Members are the entity UUIDs in the cluster.
	Members []string `json:"members"`
}

type KGEntity struct {
	// UUID is the graph's identifier, stable across re-ingestion of the same entity.
	UUID string `json:"uuid"`
	// Name is the entity as the extractor named it.
	Name string `json:"name"`
	// Summary is the graph's rolling description, rewritten as facts accumulate.
	Summary string `json:"summary"`
	// Attributes are extractor-supplied properties; absent when none were found.
	Attributes map[string]string `json:"attributes,omitempty"`
}

type KGFact struct {
	// UUID is the graph's identifier for this edge.
	UUID string `json:"uuid"`
	// Name is the relationship type.
	Name string `json:"name"`
	// Fact is the natural-language assertion.
	Fact string `json:"fact"`
	// FromEntity is the source entity's UUID.
	FromEntity string `json:"fromEntity"`
	// ToEntity is the target entity's UUID.
	ToEntity string `json:"toEntity"`
	// ValidAt is when the fact began holding; nil when the graph could not date it.
	ValidAt *time.Time `json:"validAt,omitempty"`
	// InvalidAt is when a later fact contradicted this one; nil means still current.
	InvalidAt *time.Time `json:"invalidAt,omitempty"`
}

type KGInput struct {
	// GroupID partitions the graph per session; it is the isolation boundary a
	// scoped read is checked against.
	GroupID string `json:"groupId"`
	// Content is the raw text to extract entities and facts from.
	Content string `json:"content"`
	// Role attributes the content ("user", "assistant", …).
	Role string `json:"role"`
}

type KGProvider interface {
	Ingest(ctx context.Context, input KGInput) error
	SearchFacts(ctx context.Context, query string, limit int) ([]KGFact, error)
	GetEntity(ctx context.Context, uuid string) (*KGEntity, error)
	EntityFacts(ctx context.Context, entityUUID string) ([]KGFact, error)
	RelatedEntities(ctx context.Context, entityUUID string, limit int) ([]KGEntity, error)
	Communities(ctx context.Context, groupID string) ([]KGCommunity, error)
}

type Kind interface {
	// Name is the entry's Kind field and the registry's primary key
	// (e.g., "authz_decision"). Must be non-empty and unique across
	// the registry.
	Name() string
	// IDPrefix is the literal byte prefix every Entry of this Kind's
	// ID must start with (e.g., "authzd-"). Required, non-empty, and
	// must not be a prefix-of nor be prefixed-by any other registered
	// Kind's prefix.
	IDPrefix() string
	// Retention advertises this Kind's preferences to the backend.
	Retention() Retention
	// ContentSchema optionally declares the Kind's Content struct so backends
	// advertising Capabilities.ContentSchemas can index declared fields.
	// nil means opaque content.
	ContentSchema() reflect.Type
	// IndexedFields names the fields the Kind wants indexed, as the keys they
	// are STORED under — the Content struct's `json` tags, NOT the Go field
	// names. FieldFilter.Path draws from the same vocabulary and accessor
	// authors read this list before writing a query, so a Go name here is
	// misinformation that reappears as a predicate matching nothing. Only
	// meaningful when ContentSchema is non-nil.
	IndexedFields() []string
	// WriteAuthority declares WHICH CREDENTIAL CLASS may author entries of this
	// Kind. An interface method rather than a table in a consumer, so a new Kind
	// cannot be registered without answering the question.
	WriteAuthority() WriteAuthority
	// NewScopeHooks materializes the per-(Scope, Kind) hook signals are
	// dispatched to, lazily on the first SendSignal touching the scope. Keep it
	// cheap — long-running work belongs in OnSignal.
	NewScopeHooks(scope Scope) ScopeHooks
}

type Link struct {
	// Relation is a free-form label from a small conventional vocabulary
	// ("of_operation", "for_resource", "by_subject", "approved_by", …).
	Relation string `json:"relation"`
	// Scope of the target; zero means the containing entry's own scope.
	Scope Scope `json:"scope"`
	// Kind of the target. An unregistered Kind skips ID-prefix validation.
	Kind string `json:"kind"`
	// ID of the target; validated against Kind's IDPrefix when Kind is registered.
	ID string `json:"id"`
}

type LinkFilter struct {
	// Relation to match; empty matches any relation.
	Relation string
	// Kind of the linked entry.
	Kind string
	// ID of the linked entry.
	ID string
}

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

type LocalOption func(*Local)

type Memory interface {
	Put(ctx context.Context, e Entry) (Entry, error)
	Query(ctx context.Context, q Query) (QueryResult, error)
	Search(ctx context.Context, req SearchRequest) (MergedSearchResult, error)
	SendSignal(ctx context.Context, sig Signal) error
}

type MergedSearchResult struct {
	// Entries are the ranked, authorization-filtered hits across all providers.
	Entries []ScoredEntry `json:"entries"`
	// PerProvider keeps each provider's raw answer for diagnosis; a provider
	// that errored is absent rather than present-and-empty. Each answer may
	// hold one hit more than SearchRequest.Limit — the probe row the searcher
	// asks for to decide Truncated, kept here because this is the raw answer.
	PerProvider map[string]SearchResult `json:"perProvider,omitempty"`
	// Truncated reports that SearchRequest.Limit ended this page before the
	// matches did: at least one further hit ranked below the cut. False means
	// every match is in Entries.
	//
	// Like QueryResult.Truncated it describes the READ: an Authorizer
	// post-filter may leave fewer than Limit hits in Entries with Truncated
	// still true.
	Truncated bool `json:"truncated"`
}

type NamespacedName struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
}

type OrderBy struct {
	// Field is the column to order by; "createdAt" is the only value any
	// backend honors, and anything else falls back to the backend's default.
	Field string
	// Desc: true for newest-first.
	Desc bool
}

type Permission string

type PoolReader interface {
	QueryPool(ctx context.Context, sessionScope, poolScope Scope, q Query) (QueryResult, error)
}

type PoolWriter interface {
	PutToPool(ctx context.Context, sessionScope, poolScope Scope, e Entry) (Entry, error)
}

type Provenance struct {
	// Publisher identifies the signer; equals the memory layer's caller ID for
	// the writer (per-session IDs for runners/CLI; "system:channelsd",
	// "system:authzd", "system:operator").
	Publisher string `json:"publisher"`
	// KeyID is the hex SHA-256 (first 16 bytes) of the Ed25519 public key, used
	// to look the key up in the publisher-key registry.
	KeyID string `json:"keyId"`
	// Seq is the publisher's per-scope 1-based monotonic sequence, spanning all
	// append-only kinds the publisher writes in the scope. A gap means loss.
	Seq uint64 `json:"seq"`
	// PrevHash is the EntryDigest of the publisher's previous entry in this
	// scope; empty only for Seq 1.
	PrevHash string `json:"prevHash,omitempty"`
	// Sig is the Ed25519 signature over the canonical entry digest.
	Sig []byte `json:"sig"`
}

type ProvenanceVerifier interface {
	VerifyEntry(ctx context.Context, caller string, e Entry) error
}

type PtTagContent struct {
	TagID   string `json:"tagID"`
	Content string `json:"content"`
	MIME    string `json:"mime,omitempty"`
}

type PtTagMintRequest struct {
	// ToolUseID is the tool_use block whose result carried the datum into
	// context, matching the link infoleakage_taint records under the same name.
	ToolUseID string `json:"toolUseID,omitempty"`

	// Resources are the objects the call read, as SpiceDB type/id pairs. The
	// minter expands each to its authorized subjects. Required for a LEAF mint.
	Resources []PtTagResourceRef `json:"resources,omitempty"`

	// DerivedFrom names existing tags this datum was assembled from. When set,
	// the mint is DERIVED: it takes no resources and no audience of its own,
	// because `reader` resolves the intersection of these through SpiceDB.
	DerivedFrom []string `json:"derivedFrom,omitempty"`

	// UntrustedOrigin marks a leaf whose source may carry injected content.
	// Meaningful only on a leaf mint: integrity is declared where a datum
	// enters and inherited below it through carries_untrusted.
	UntrustedOrigin bool `json:"untrustedOrigin,omitempty"`

	// Content is the datum itself, stored behind the tag so the PLATFORM can
	// resolve it later — to place it in a child's context when a data slot is
	// bound, or to answer an audit. Optional: a tag with no content is still a
	// complete provenance record, it just cannot be handed onward.
	//
	// Note this does NOT put the content anywhere the agent can reach. It
	// lands in pt_tag_content, whose SessionReadable is false precisely so
	// that query_memory — which takes arbitrary Kind names — cannot ask for it
	// straight back.
	//
	// Written in the same call as the tag, never separately: content stored
	// under a tag that failed to mint would be bytes nobody's audience governs,
	// and a tag whose content arrived later would have a window in which a
	// disclosure decision was made about something not yet there.
	Content string `json:"content,omitempty"`

	// MIME describes Content, so a platform forwarding the datum can label it.
	MIME string `json:"mime,omitempty"`
}

type PtTagMintResponse struct {
	TagID string `json:"tagID"`
}

type PtTagRegion struct {
	ID      string `json:"id"`
	Content string `json:"content"`
}

type PtTagResolveRequest struct {
	// TagIDs are the tags whose content the caller asks for. The scope in the
	// URL is where the bytes live (the caller's own scope for a derive, the
	// PARENT scope for a bound slot); entitlement is per-tag, not per-scope.
	TagIDs []string `json:"tagIDs"`
}

type PtTagResolveResponse struct {
	Contents []PtTagContent `json:"contents,omitempty"`
}

type PtTagResourceRef struct {
	Type string `json:"type"`
	ID   string `json:"id"`
	// Permission is the permission the read was authorized under, so the
	// minter expands the right subject set rather than guessing one.
	Permission string `json:"permission"`
}

type PtTagVerifyRequest struct {
	// Regions are the nonce-matched pt-untrusted regions the runner parsed out
	// of the outbound payload — each an id the payload claims plus the bytes it
	// carried under that id.
	Regions []PtTagRegion `json:"regions"`
}

type PtTagVerifyResponse struct {
	// Verified are the ids whose supplied content matched what the platform
	// stored for them.
	Verified []string `json:"verified,omitempty"`
	// AllBound is true only when EVERY requested region bound. A partially
	// forged payload — one real region beside a fabricated one — is not one the
	// caller can reason about per-datum, so the caller drops the whole payload
	// to the coarse floor rather than honour the regions that happened to match.
	AllBound bool `json:"allBound"`
}

type Query struct {
	Scope        Scope         // required; the framework rejects an empty one
	Kinds        []string      // empty means all kinds in scope
	IDs          []string      // exact-id filter
	LinkedTo     []LinkFilter  // entries whose Links contain {Relation?, Kind, ID}
	LinkedFrom   []LinkFilter  // reverse: entries that ARE linked-to {Kind, ID}
	Tags         []string      // entries carrying ALL the listed tags
	FieldEquals  []FieldFilter // content predicates; dropped by backends lacking ContentSchemas
	Since, Until *time.Time    // half-open CreatedAt window; nil means unbounded
	OrderBy      OrderBy
	Limit        int // 0 means the backend's own cap
}

type QueryResult struct {
	// Entries matched the honored predicates; empty is a valid answer, not an error.
	Entries []Entry
	// DroppedPredicates names each Query predicate the backend could not honor
	// ("FieldEquals", "LinkedFrom", …). A capability signal for operators;
	// callers must not branch on it for correctness.
	DroppedPredicates []string
	// Partial is true iff len(DroppedPredicates) > 0.
	Partial bool
	// Truncated reports that Query.Limit ended this read before the matches
	// did: at least one more entry matched and is not in Entries. False means
	// Entries is every match, so a caller may treat it as the whole answer.
	//
	// It is set by Local.Query, which probes one row past the limit (see
	// ProbeLimit) rather than guessing from len(Entries) — a set holding
	// exactly Limit entries is otherwise indistinguishable from one the limit
	// cut short, and that ambiguity is what lets a reader act on part of a
	// result set believing it was all of it.
	//
	// It describes the READ, not the caller's view of it: an Authorizer
	// post-filter may drop entries afterwards, leaving fewer than Limit in
	// Entries with Truncated still true. That is correct — the store held more
	// than the limit allowed to be read, whatever was then filtered out.
	//
	// Backend implementations leave it false; the facade owns it.
	Truncated bool
}

type Ranker interface {
	Rank(results map[string]SearchResult, limit int) []ScoredEntry
}

type Retention struct {
	// EssentialWhileLive: never evict while ScopeStatus == Live.
	EssentialWhileLive bool
	// ArchiveOn names signal kinds that flip this Kind's entries
	// from "kept" to "eligible for eviction".
	ArchiveOn []SignalKind
	// TTLAfterArchive: how long after an ArchiveOn signal the
	// backend may drop the entry. Zero = backend default; negative
	// = never auto-drop after archive.
	TTLAfterArchive time.Duration
	// SoftCapPerScope is a per-scope FIFO cap for cache-shaped
	// Kinds (label). Zero = no cap.
	SoftCapPerScope int
	// AppendOnly: entries of this Kind are immutable once written. Put
	// may create (or idempotently re-put byte-identical content) but
	// never change an existing entry, and per-entry Delete is refused.
	// Scope-level deletion (retention, session GC) is unaffected — that
	// is the backend's retention policy, not entry mutation.
	AppendOnly bool

	// NeverForkCopy: a fork must NOT copy this Kind's entries into the child
	// scope. The forking code derives whatever the child needs instead.
	//
	// This exists for Kinds whose entries are a CHAIN rather than a set —
	// where meaning comes from order and from the (scope, publisher) provenance
	// sequence, not from each entry alone. Copying those into a new scope
	// produces a chain whose seq and prevHash refer to a history the child does
	// not have, so it verifies as gapped at best and replays in the wrong order
	// at worst.
	//
	// The plan gate is the motivating case: its rules ("a denial survives a
	// later supersede", "the last write wins for this ceiling") are all
	// order-dependent, so a mis-ordered replay in a child could resurrect
	// authority a human revoked.
	NeverForkCopy bool
}

type Scope struct {
	// Kind is the sub-universe's type — "session" or ScopeKindResource today.
	Kind string `json:"kind"`
	// ID identifies the scope within its Kind — "<namespace>/<name>" for
	// sessions, "<type>:<id>" for a resource pool. The two shapes are
	// deliberately disjoint; ResourceScope enforces it.
	ID string `json:"id"`
}

type ScopeHooks interface {
	OnSignal(ctx context.Context, sig Signal) error
}

type ScopeStatus struct {
	// State is the backend's verdict on the scope.
	State StatusState `json:"state"`
	// ArchivedAt is when the entries were shed; nil unless State is archived.
	ArchivedAt *time.Time `json:"archivedAt,omitempty"`
}

type ScoredEntry struct {
	// Entry is the stored entry, unmodified.
	Entry Entry `json:"entry"`
	// Score is comparable only within one Source; providers use different
	// scales, which is why merging goes through the ranker rather than a sort.
	Score float64 `json:"score"`
	// Source is the SearchProvider.Name that produced the hit.
	Source string `json:"source"`
}

type SearchCapabilities struct {
	// TextSearch: honors SearchRequest.Text lexically.
	TextSearch bool `json:"textSearch"`
	// VectorSearch: honors SearchRequest.Text by embedding similarity.
	VectorSearch bool `json:"vectorSearch"`
	// FieldFilters: honors SearchRequest.Fields.
	FieldFilters bool `json:"fieldFilters"`
	// TagFilters: honors SearchRequest.Tags.
	TagFilters bool `json:"tagFilters"`
	// TimeRange: honors SearchRequest.Since / Until.
	TimeRange bool `json:"timeRange"`
	// LinkTraversal: can follow entry links while searching.
	LinkTraversal bool `json:"linkTraversal"`
}

type SearchProvider interface {
	Name() string
	SearchCapabilities() SearchCapabilities
	Search(ctx context.Context, req SearchRequest) (SearchResult, error)
	Index(ctx context.Context, scope Scope, kind, id string, content []byte) error
	DeleteIndex(ctx context.Context, scope Scope, kind, id string) error
	DeleteScopeIndex(ctx context.Context, scope Scope) error
}

type SearchRequest struct {
	// Scopes to search; every one must be separately authorized.
	Scopes []Scope `json:"scopes"`
	// Text is the free-text / vector query; empty makes this structured-only.
	Text string `json:"text,omitempty"`
	// Kinds to restrict to; empty means all kinds.
	Kinds []string `json:"kinds,omitempty"`
	// Tags an entry must ALL carry to match.
	Tags []string `json:"tags,omitempty"`
	// Fields are content predicates; providers lacking FieldFilters drop them.
	Fields []FieldFilter `json:"fields,omitempty"`
	// Since bounds CreatedAt below; nil means unbounded.
	Since *time.Time `json:"since,omitempty"`
	// Until bounds CreatedAt above; nil means unbounded.
	Until *time.Time `json:"until,omitempty"`
	// Limit caps the MERGED result, not each provider's; 0 means the default.
	Limit int `json:"limit,omitempty"`
}

type SearchResult struct {
	// Entries are this provider's hits, its own best-first.
	Entries []ScoredEntry `json:"entries"`
	// DroppedFilters names request filters this provider could not honor, so a
	// narrower question silently answered as a wider one is visible.
	DroppedFilters []string `json:"droppedFilters,omitempty"`
}

type Searcher interface {
	Search(ctx context.Context, req SearchRequest) (MergedSearchResult, error)
}

type SessionReadabilityDecider interface {
	// SessionReadable reports whether a SESSION credential may read entries of
	// this Kind. False means platform components only.
	SessionReadable() bool
}

type Signal struct {
	// Kind selects which hooks react and what Payload's shape is.
	Kind SignalKind `json:"kind"`
	// Scope selects which (Scope, Kind) hooks receive the signal.
	Scope Scope `json:"scope"`
	// At is the event time as the sender observed it, not receipt time.
	At time.Time `json:"at"`
	// Payload is opaque to the framework; the Kind owning this SignalKind
	// defines its shape. Empty when the signal carries no data.
	Payload json.RawMessage `json:"payload,omitempty"`
}

type SignalKind string

type StatusState string

type ToolResultBlock struct {
	// ToolUseID is the ToolUseBlock.ID this result answers.
	ToolUseID string `json:"toolUseId"`
	// Content is the tool's output as the model will see it.
	Content string `json:"content"`
	// IsError marks a failed call; the content is then the error text.
	IsError bool `json:"isError,omitempty"`
	// RenderedLive records that the live surfaces already showed Content to the
	// user, so a resumed transcript must show it too — the live == reload
	// invariant. Set by the runner from tool.Result.RenderedLive, which only a
	// streaming/interactive toolkit's composed result carries; ordinary tool
	// output (a memory query's rows, a kubectl dump) leaves it false and stays
	// hidden. Read by turn.VisibleTimeline. Content is still the ENVELOPED form
	// the model saw — a renderer unwraps it (pkg/agent/toolenvelope).
	//
	// omitempty is load-bearing for the same reason as Turn.Via: the provenance
	// digest omits empty fields, so an unset flag must not perturb it, and
	// entries written before this existed stay verifiable byte-for-byte.
	RenderedLive bool `json:"renderedLive,omitempty"`
}

type ToolUseBlock struct {
	// ID correlates this call with the ToolResultBlock answering it.
	ID string `json:"id"`
	// Name is the tool as the agent loop knows it, not the upstream MCP name.
	Name string `json:"name"`
	// Input is raw JSON arguments, opaque to the store.
	Input []byte `json:"input"`
}

type Turn struct {
	// Index is the turn's 0-based position in the transcript; (Index, Role) is
	// the identity turn.Appender guards against conflicting re-writes.
	Index int `json:"index"`
	// Role is "user" | "assistant" | "system_note".
	Role string `json:"role"`
	// Content holds the provider-neutral blocks, persisted verbatim.
	Content []ContentBlock `json:"content"`
	// CreatedAt is when the turn was recorded.
	CreatedAt time.Time `json:"createdAt"`
	// Usage is token accounting; nil on anything but an assistant turn.
	Usage *Usage `json:"usage,omitempty"`
	// Author is the canonical subject (e.g. "user:YWxpY2U") of the human who
	// authored this turn, including the index-0 initial prompt, which carries
	// the session starter's subject. Empty for agent/runner-authored turns
	// (tool results), system notes, and kubectl/bento-driven sessions with no
	// human starter. In multiplayer sessions it is the actual sender, not the
	// session initiator.
	Author identity.Subject `json:"author,omitempty"`
	// Via names the browser/TUI surface that injected this turn, as a view URN
	// (urn:ap:view:artifact:artifact-3f2a1b8c/artrev-9d4e0117). Empty for turns
	// arriving through the Channel's own listener. Server-minted, never
	// client-supplied. omitempty is load-bearing: the provenance digest omits
	// empty fields, so an unset Via must not perturb it.
	Via string `json:"via,omitempty"`
	// Refused marks an assistant turn whose provider response carried
	// stop_reason=refusal. The turn stays in the append-only transcript for
	// audit, but replay excludes it from the reconstructed message history so a
	// retry regenerates it cleanly. omitempty for the same digest reason as Via.
	Refused bool `json:"refused,omitempty"`
	// Model is the uniform display id of the model that actually served the
	// turn, "<provider>/<served-model>". Empty on user turns.
	Model string `json:"model,omitempty"`
}

type Usage struct {
	// InputTokens billed for the prompt, cache reads excluded.
	InputTokens int64 `json:"inputTokens"`
	// OutputTokens billed for the completion.
	OutputTokens int64 `json:"outputTokens"`
	// CacheCreationTokens written into the prompt cache this turn.
	CacheCreationTokens int64 `json:"cacheCreationTokens,omitempty"`
	// CacheReadTokens served from the prompt cache instead of being billed as input.
	CacheReadTokens int64 `json:"cacheReadTokens,omitempty"`
}

type WriteAuthority uint8