graph

type AddTripleRequest struct {
	Triple    message.Triple `json:"triple"`
	TraceID   string         `json:"trace_id,omitempty"`
	RequestID string         `json:"request_id,omitempty"`
}

type AddTripleResponse struct {
	MutationResponse
	Triple       *message.Triple `json:"triple,omitempty"`
	Deduplicated bool            `json:"deduplicated,omitempty"`
}

type AddTriplesBatchRequest struct {
	Triples   []message.Triple `json:"triples"`
	TraceID   string           `json:"trace_id,omitempty"`
	RequestID string           `json:"request_id,omitempty"`
}

type AddTriplesBatchResponse struct {
	MutationResponse
	WrittenCount int `json:"written_count"`
	// Deduplicated counts submitted triples that were NOT appended because the
	// target entity already carried an identical six-field tuple (subject,
	// predicate, object, datatype, source, context), or because the same tuple
	// appeared earlier in this same request. It exists so a caller can
	// distinguish "already present" from "nothing happened" without paying an
	// authoritative read-back.
	//
	// This is a COUNT, not a no-op flag — it is non-zero on batches that also
	// committed writes (a mixed batch reports written=1, deduplicated=2). The
	// "nothing committed" predicate for this response is
	// `WrittenCount == 0 && len(FailedSubjects) == 0`. Do NOT pattern-match it
	// against AddTripleResponse.Deduplicated, which IS a boolean no-op flag;
	// gating on `Deduplicated > 0` here reintroduces the revision-claiming bug
	// that flag exists to prevent.
	Deduplicated   int               `json:"deduplicated,omitempty"`
	FailedSubjects map[string]string `json:"failed_subjects,omitempty"`
}

type AliasData struct {
	CanonicalID *string `json:"canonical_id"` // nil if not found
}

type AliasQueryResponse = QueryResponse[AliasData]

type BacklogStatusInputs struct {
	// Outstanding is total un-applied work across every bound consumer, IN MESSAGES —
	// the sum of NumPending (server-side, undelivered) and NumAckPending
	// (delivered, not yet acked) over all of them.
	//
	// THE SUM IS INVARIANT TO WHICH COUNTER HOLDS A MESSAGE, and that is why it is a
	// sum rather than either half. A message moves between the two continuously —
	// delivered (pending -> ack-pending), nak'd back (ack-pending -> pending),
	// redelivered again — so any single counter oscillates while work is steady.
	// Only the total is monotone with respect to real outstanding work. Do not
	// "simplify" this to NumPending: that under-reports by the whole in-process lane
	// queue (up to defaultIngestLanes(8) x ingestLaneQueueDepth(256) = 2048 messages
	// held delivered-but-unacked), which is precisely the backlog gh#712 tripped over.
	//
	// WHY NOT THE ACK FLOOR: measured 2026-07-30 against both deployed NATS versions
	// (2.10, 2.12), AckFloor.Stream does not advance past a MaxDeliver-exhausted
	// message, then jumps PAST it on the next unrelated ack — reading
	// permanently-not-caught-up while idle and falsely-covered under traffic. It never
	// means "everything at or below this is durable". See the change's design.md D0.
	//
	// HONESTY BOUNDARY: Outstanding == 0 means NO OUTSTANDING WORK, not EVERYTHING WAS
	// APPLIED. A MaxDeliver-parked message leaves BOTH counters (measured), so it is
	// invisible here. Caught-up is a backlog claim and cannot license an absence
	// claim; operator visibility for parked messages is gh#742.
	Outstanding uint64
	// BootstrapComplete is the producer's own initial-build latch. It is an INPUT, not
	// a projection: what constitutes the initial build differs per producer (a drained
	// boot sweep, a watcher replay sentinel), and only the producer can say.
	BootstrapComplete bool
	// BootstrapScope is the size of that initial build in the producer's unit; see the
	// field of the same name on IndexStatusResponse. Passed through untouched — the
	// projection never compares it to anything.
	BootstrapScope uint64
	// ObservationFailed reports that the producer could not read its own backlog (a
	// consumer.Info() failure). It projects to degraded AND forces Ready false,
	// mirroring graph-index's precedent for a failed target read
	// (processor/graph-index/watermark.go:69-80): a backend fault cannot honestly
	// confirm caught-up, and "building" would read as ordinary progress rather than a
	// fault. See the divergence note in ComputeBacklogStatus for why this is stronger
	// than ComputeIndexStatus's FailedCount handling.
	//
	// Outstanding may still be a PARTIAL sum when this is set (some consumers read,
	// one failed). That partial is kept on Lag as an honest lower bound rather than
	// zeroed — a lower bound under a degraded verdict is strictly more useful to an
	// operator than a fabricated 0, and no gate proceeds on degraded anyway.
	ObservationFailed bool
	// OldestOutstandingAt is the JetStream timestamp of the oldest outstanding
	// message. ZERO means "not computable" — the projection then leaves StalenessMs at
	// 0 rather than fabricating a fresh-looking view, matching the presence encoding
	// on that field.
	OldestOutstandingAt time.Time
	// Now is the compute instant; the zero value means time.Now().
	Now time.Time
	// LastSynced is the last-advance timestamp, RFC3339, for the envelope field.
	LastSynced string
}

type CompoundPredicateData struct {
	Entities []string `json:"entities"`
	Operator string   `json:"operator"`
	Matched  int      `json:"matched"`
}

type CompoundPredicateQuery struct {
	Predicates []string `json:"predicates"`
	Operator   string   `json:"operator"` // "AND" or "OR"
	Limit      int      `json:"limit,omitempty"`
}

type CompoundPredicateQueryResponse = QueryResponse[CompoundPredicateData]

type ContextEntry struct {
	EntityID  string `json:"entity_id"`
	Predicate string `json:"predicate"`
}

type CreateEntityRequest struct {
	Entity    *EntityState `json:"entity"`
	TraceID   string       `json:"trace_id,omitempty"`
	RequestID string       `json:"request_id,omitempty"`
}

type CreateEntityResponse struct {
	MutationResponse
	Entity *EntityState `json:"entity,omitempty"`
}

type CreateEntityWithTriplesRequest struct {
	Entity  *EntityState     `json:"entity"`
	Triples []message.Triple `json:"triples"`
	// IndexingProfile optionally declares the entity's indexing profile at
	// creation (ADR-054 channel b): one of "content"|"control"|"signal"|
	// "trace". When set, graph-ingest stamps entity.indexing.profile from it
	// (highest precedence). When empty, graph-ingest falls through to the
	// Graphable IndexingProfiler, then the fallback floor. Invalid values are
	// treated as absent (lenient). This is the channel the registry-only
	// design lacked — rule/lifecycle/loop/memory/research-graph writers use it
	// to declare intent. Only meaningful on CREATE; entity-birth is the only
	// place a profile is set (see also UpdateEntityWithTriplesRequest for the
	// explicit-override exception).
	IndexingProfile string `json:"indexing_profile,omitempty"`
	// OwnerToken is the writer's owner-identity lease token in the format
	// "<owner>#<incarnation>", where <owner> is the canonical owner id
	// (e.g. "rule-pack.my-pack", "mission-planner") and <incarnation> is a
	// per-process boot nonce (crypto/rand hex) that fences revived-stale
	// writers even when the owner id is unchanged. Empty = unowned or
	// legacy writer; graph-ingest skips the lease check when empty.
	// Compared at graph-ingest by a later increment (ADR-056); PR-1 stamps
	// it here for observe-only transit.
	OwnerToken string `json:"owner_token,omitempty"`
	TraceID    string `json:"trace_id,omitempty"`
	RequestID  string `json:"request_id,omitempty"`
}

type CreateEntityWithTriplesResponse struct {
	MutationResponse
	Entity       *EntityState `json:"entity,omitempty"`
	TriplesAdded int          `json:"triples_added"`
}

type DeferReason string

type DeleteEntityRequest struct {
	EntityID  string `json:"entity_id"`
	TraceID   string `json:"trace_id,omitempty"`
	RequestID string `json:"request_id,omitempty"`
}

type DeleteEntityResponse struct {
	MutationResponse
	Deleted bool `json:"deleted"`
}

type EntityBatchResponse struct {
	Entities []EntityState `json:"entities"`
	// Missing names the requested IDs not present in Entities, with a reason each.
	// Omitted entirely when nothing was missing.
	Missing []MissingEntity `json:"missing,omitempty"`
}

type EntityCriteria struct {
	EntityID   string         `json:"entity_id,omitempty"`
	Type       string         `json:"type,omitempty"`
	Properties map[string]any `json:"properties,omitempty"`
}

type EntityPredicateContractError struct {
	Violations []InvalidEntityPredicate `json:"violations"`
}

type EntityState struct {
	// ID is the 6-part entity identifier: org.platform.domain.system.type.instance
	// Used as NATS KV key for storage and retrieval.
	ID string `json:"id"`

	// Triples contains all semantic facts about this entity.
	// Properties, relationships, and domain-specific data are all stored as triples.
	Triples []message.Triple `json:"triples"`

	// StorageRef optionally points to where the full original message is stored.
	// Supports "store once, reference anywhere" pattern for large payloads.
	// Nil if message was not stored or storage reference not available.
	StorageRef *message.StorageReference `json:"storage_ref,omitempty"`

	// MessageType records the original message type that created/updated this entity.
	// Provides provenance and enables filtering by message source.
	MessageType message.Type `json:"message_type"`

	// Version is incremented on each update for optimistic concurrency control.
	Version uint64 `json:"version"`

	// UpdatedAt records when this entity state was last modified.
	UpdatedAt time.Time `json:"updated_at"`
}

type EntityStateContractError struct {
	Field       EntityStateContractField
	TripleIndex int
	Err         error
}

type EntityStateContractField string

type EntityTypeSummary struct {
	// Type is the domain.system.type triple — the bucket name.
	Type string `json:"type"`

	// Count is how many entities in the scanned sample fall in this
	// bucket. Approximate when EntitySampleTruncated is set on the
	// parent SummaryData.
	Count int `json:"count"`

	// Examples is up to ExamplesPerType real entity IDs from this
	// bucket. The caller uses these as starting points for
	// query_entity / query_relationships without having to invent IDs.
	Examples []string `json:"examples"`
}

type Event struct {
	Type       EventType      `json:"type"`
	EntityID   string         `json:"entity_id"`
	TargetID   string         `json:"target_id"`
	Properties map[string]any `json:"properties"`
	Metadata   EventMetadata  `json:"metadata"`
	Confidence float64        `json:"confidence"`
}

type EventMetadata struct {
	RuleName  string    `json:"rule_name"`
	Timestamp time.Time `json:"timestamp"`
	Source    string    `json:"source"`
	Reason    string    `json:"reason"`
	Version   string    `json:"version"`
}

type EventType string

type Graphable interface {
	// EntityID returns deterministic 6-part ID: org.platform.domain.system.type.instance
	EntityID() string

	// Triples returns all facts about this entity
	Triples() []message.Triple
}

type IncomingEdge struct {
	FromEntityID string    `json:"from_entity_id"`
	EdgeType     string    `json:"edge_type"`
	Weight       float64   `json:"weight,omitempty"`
	UpdatedAt    time.Time `json:"updated_at"`
}

type IncomingEdges struct {
	EntityID  string         `json:"entity_id"`
	Incoming  []IncomingEdge `json:"incoming"`
	UpdatedAt time.Time      `json:"updated_at"`
}

type IncomingEntry struct {
	FromEntityID string `json:"from_entity_id"`
	Predicate    string `json:"predicate"`
}

type IncomingQueryResponse = QueryResponse[IncomingRelationshipsData]

type IncomingRelationshipsData struct {
	Relationships []IncomingEntry `json:"relationships"`
}

type IndexStatusInputs struct {
	// Indexed is the low-water-of-pending watermark (revlag.Watermark.Indexed).
	Indexed uint64
	// Target is the query-time ENTITY_STATES stream LastSeq the index must reach.
	Target uint64
	// Stuck is the caller's own stuck-watermark detector verdict (-> degraded).
	Stuck bool
	// LastSynced is the last-advance timestamp, RFC3339, for the envelope field.
	LastSynced string
	// IndexedAt is the KV COMMIT time of the newest revision Indexed covers
	// (revlag.Watermark.IndexedAt). ZERO means "not computable" — the projection
	// then leaves StalenessMs at 0 rather than fabricating a fresh-looking view.
	IndexedAt time.Time
	// Now is the compute instant; the zero value means time.Now(). Tests set it to
	// keep the staleness projection deterministic instead of asserting on the wall
	// clock.
	Now time.Time
	// FailedCount is the number of index entries the producer CURRENTLY holds in a
	// failed terminal state. When > 0 it projects to State=degraded BEFORE the "ready
	// wins" branch, UNCONDITIONALLY (not gated on Ready): a producer whose watermark
	// has reached its target while holding failures is COVERED (Ready stays accurate)
	// but NOT healthy (a failed record is not a usable index entry). This makes the
	// shared projection finally enforce the graph-index-readiness `FailedCount > 0 →
	// degraded` rule for a producer (graph-embedding) whose watermark advances past
	// failures. graph-index leaves this 0 — it enforces the same rule caller-side via
	// its watermark hole + applyKnownIncompleteOverrides — so its projection output is
	// byte-unchanged (ADR-085, #613).
	FailedCount uint64
}

type IndexStatusResponse struct {
	Ready bool   `json:"ready"` // target>0 && indexed_revision>=target_revision
	State string `json:"state"` // "building" | "ready" | "degraded" | "reset_required"
	// Code and Reason carry bounded operator-actionable fatal readiness state.
	// They are empty during ordinary building/ready/degraded operation.
	Code   string `json:"code,omitempty"`
	Reason string `json:"reason,omitempty"`
	// BootstrapComplete reports whether this producer has finished its INITIAL BUILD
	// in the current process lifetime: enumeration of ENTITY_STATES plus replay up to
	// the enumeration-time target, including the authoritatively-empty 0/0 outcome. It
	// latches true once and resets to false on restart, so a restart into a format
	// cutover re-gates (ADR-084 D2).
	//
	// It exists because health is otherwise not evaluable from the wire: an index
	// halfway through a gh#474 cutover reports State=building with a plausible Lag,
	// indistinguishable from an index that is merely behind. Ready cannot answer it
	// (a caught-up index is bootstrapped, but a bootstrapped index under write is not
	// caught up) and TargetRevision==0 cannot either (it is false during a cutover and
	// wrongly deferred the empty graph).
	//
	// NOT omitempty, and absent reads FALSE — fail closed. An envelope from a
	// pre-ADR-084 producer therefore defers every health gate until the lockstep
	// upgrade lands; that is the accepted migration cost, and the explicit `false` on
	// the wire keeps "old producer" distinguishable from "not yet bootstrapped" in a
	// `nats kv get GRAPH_STATUS <producer>` dump.
	BootstrapComplete bool `json:"bootstrap_complete"`
	// IndexedRevision is the low-water-of-pending watermark: every delivered
	// ENTITY_STATES revision <= this has been applied and nothing <= it is still
	// in flight. A consumer that knows its own target revision can gate on
	// IndexedRevision >= myRev instead of the coarse global Ready bool.
	IndexedRevision uint64 `json:"indexed_revision,omitempty"`
	// TargetRevision is the ENTITY_STATES stream LastSeq read at query time — the
	// latest committed write the index must catch up to.
	TargetRevision uint64 `json:"target_revision,omitempty"`
	// Lag is TargetRevision - IndexedRevision; 0 means caught up.
	Lag uint64 `json:"lag,omitempty"`
	// FailedCount / FailedReasons / FirstFailureAt are the bounded failure detail a
	// producer that tracks per-entity failures carries on a DEGRADED envelope so an
	// operator can tell a whole-dependency outage from a few persistently-failing
	// entities WITHOUT any unbounded per-entity list on the watched key (#613).
	//
	// All three are additive and omitempty: a producer with no failures — including
	// graph-index, which enforces the same rule caller-side via its watermark hole —
	// emits none, so the wire is byte-unchanged. FailedReasons is bounded to a fixed
	// reason enum (a handful of keys), keeping the watched key compact on the hot KV
	// path. FirstFailureAt is RFC3339. FailedCount is echoed from the projection input
	// (it also drives State=degraded, see ComputeIndexStatus); the other two are set by
	// the producer after the projection.
	FailedCount    uint64            `json:"failed_count,omitempty"`
	FailedReasons  map[string]uint64 `json:"failed_reasons,omitempty"`
	FirstFailureAt string            `json:"first_failure_at,omitempty"`
	// StalenessMs is the AGE OF THE VIEW in milliseconds (ADR-083): now minus the
	// KV commit time of the newest ENTITY_STATES revision the index has fully
	// covered. It is the view-rate consumer's tolerance unit because it is
	// invariant to write rate and coalesce_ms, where a revision count is not
	// (gh#590: the correct revision bound shifted 2-4x with the coalesce dial
	// alone).
	//
	// PRESENCE ENCODING — 0 does NOT mean "zero staleness". It means the value
	// carries no information: either Ready is true (no staleness to report) or the
	// producer could not compute it (nothing covered yet / an early-return hard
	// stop). Any COMPUTED staleness is reported as at least 1ms, so a consumer can
	// treat `StalenessMs > 0` as the presence bit and never read an absent age as
	// "0ms fresh".
	//
	// It is REPORTED, never gating. EvaluateReadinessGate does not look at this field:
	// readiness withholds an answer only for index health, and how far behind the view
	// is rides on the answer instead (community detection stamps it on
	// staleness_at_detection_ms). A consumer that surfaces it must carry the presence
	// encoding with it — publishing a bare 0 as "caught up" is the one way to turn an
	// unknown age back into a false claim.
	//
	// It is a FLOOR, not an oracle: a revision still undelivered server-side cannot
	// age it. Total stalls surface through the wall-clock stuck detector
	// (State=degraded), not through this field.
	StalenessMs uint64 `json:"staleness_ms,omitempty"`
	// BootstrapScope is the SIZE OF THE INITIAL BUILD this producer latched
	// BootstrapComplete against, expressed in THE PRODUCER'S OWN UNIT — entities for
	// an enumerating producer, messages for a backlog producer, replayed values for a
	// watcher producer. It is deliberately not normalized across producers; a shared
	// unit would be a fiction, and every consumer reads it alongside the key it asked
	// for, so it already knows whose unit it is.
	//
	// It exists for exactly one distinction, which is NOT recoverable from the wire
	// today for any producer: `BootstrapComplete && BootstrapScope == 0` is
	// "authoritatively nothing to do" — the producer finished its initial build and
	// the build was empty — as opposed to "finished a build that had work in it".
	// gh#732 raises this: a consumer waiting for a bootstrap replay cannot otherwise
	// tell an empty-by-truth replay from one it observed too early.
	//
	// THE GATE MUST NOT READ IT. EvaluateReadinessGate does not look at this field and
	// must never start: the moment a verdict depends on a magnitude, this becomes a
	// threshold knob and readiness stops being a health question (ADR-085 deleted
	// max_staleness for the same reason). A test pins the gate's verdict as identical
	// across two envelopes differing only in this field.
	//
	// IT LICENSES NOTHING ABOUT ABSENCE. Scope 0 says the initial build found nothing
	// to do at the instant it latched — not that the underlying collection is empty,
	// and not that anything published later has been seen.
	BootstrapScope uint64 `json:"bootstrap_scope,omitempty"`
	// Phase is the optional friendly projection (ingesting | indexing | ready);
	// deferred — the numeric fields are load-bearing (ADR-066 open question).
	Phase      string `json:"phase,omitempty"`
	Revision   string `json:"revision,omitempty"`    // string IndexedRevision (now populated)
	LastSynced string `json:"last_synced,omitempty"` // last watermark advance (now populated)
}

type InvalidEntityPredicate struct {
	Predicate string                               `json:"predicate"`
	Reason    vocabulary.PredicateValidationReason `json:"reason"`
}

type MissingEntity struct {
	ID     string        `json:"id"`
	Reason MissingReason `json:"reason"`
}

type MissingReason string

type MutationResponse struct {
	// Degraded is true when the write COMMITTED but the post-write read-back
	// failed. It is never set for a failure or a no-op. See the type docstring
	// for the full contract. Omitted in JSON when false.
	Degraded bool `json:"degraded,omitempty"`
	// DegradedReason carries the read-back failure reason when Degraded is
	// true (ADR-060: replaces the retired Error field on the degraded path).
	DegradedReason string `json:"degraded_reason,omitempty"`
	TraceID        string `json:"trace_id,omitempty"`
	RequestID      string `json:"request_id,omitempty"`
	Timestamp      int64  `json:"timestamp"`             // Unix nano timestamp
	KVRevision     uint64 `json:"kv_revision,omitempty"` // KV bucket revision after write
}

type NameData struct {
	Matches []NameMatch `json:"matches"`
}

type NameIndexEntry struct {
	Name  string          `json:"name"` // the folded name (key source)
	Items []NameIndexItem `json:"items"`
}

type NameIndexItem struct {
	EntityID  string `json:"entity_id"`
	Name      string `json:"name"`      // original-case name as stored on the entity
	Predicate string `json:"predicate"` // the label predicate carrying it
	Priority  int    `json:"priority"`  // label-predicate salience (lower = higher)
}

type NameMatch struct {
	// EntityID is the matched entity (an opaque handle for the caller).
	EntityID string `json:"entity_id"`
	// MatchedName is the name as stored on the entity (original case).
	MatchedName string `json:"matched_name"`
	// Predicate is the label predicate that carried the name (e.g. dc.terms.title).
	Predicate string `json:"predicate"`
	// ExactCase is true when MatchedName equals the query verbatim (case included);
	// such matches rank above case-folded-only matches.
	ExactCase bool `json:"exact_case"`
}

type OutgoingEntry struct {
	ToEntityID string `json:"to_entity_id"`
	Predicate  string `json:"predicate"`
}

type OutgoingQueryResponse = QueryResponse[OutgoingRelationshipsData]

type OutgoingRelationshipsData struct {
	Relationships []OutgoingEntry `json:"relationships"`
}

type PredicateData struct {
	Entities []string `json:"entities"`
}

type PredicateListData struct {
	Predicates []PredicateSummary `json:"predicates"`
	Total      int                `json:"total"`
}

type PredicateListQuery struct {
	Namespace string `json:"namespace,omitempty"`
}

type PredicateListQueryResponse = QueryResponse[PredicateListData]

type PredicateQueryResponse = QueryResponse[PredicateData]

type PredicateStatsData struct {
	Predicate      string   `json:"predicate"`
	EntityCount    int      `json:"entity_count"`
	SampleEntities []string `json:"sample_entities"`
}

type PredicateStatsQueryResponse = QueryResponse[PredicateStatsData]

type PredicateSummary struct {
	Predicate   string `json:"predicate"`
	EntityCount int    `json:"entity_count"`
}

type PrefixQueryRequest struct {
	// Prefix is a dot-delimited entity-ID prefix (e.g. "acme.ops.robotics").
	// Empty string matches all entities. Do NOT include a trailing dot —
	// the server appends it automatically when filtering.
	Prefix string `json:"prefix"`

	// Limit is the maximum number of entities to return on this page.
	// <=0 means "use server default". Clamped to MaxPrefixQueryLimit.
	Limit int `json:"limit,omitempty"`

	// Cursor is the opaque page-continuation token from a previous response.
	// Leave empty to request the first page.
	Cursor string `json:"cursor,omitempty"`
}

type PrefixQueryResponse struct {
	// Entities is the full EntityState slice for this page.
	Entities []EntityState `json:"entities"`

	// NextCursor is the opaque continuation token; empty = exhausted.
	// Old consumers that do not know about pagination safely ignore this field.
	NextCursor string `json:"next_cursor,omitempty"`
}

type Provider interface {
	// GetAllEntityIDs returns all entity IDs in the graph.
	GetAllEntityIDs(ctx context.Context) ([]string, error)

	// GetNeighbors returns the entity IDs connected to the given entity.
	// direction: "outgoing", "incoming", or "both"
	GetNeighbors(ctx context.Context, entityID string, direction string) ([]string, error)

	// GetEdgeWeight returns the weight of the edge between two entities.
	// Returns 1.0 if edge exists but has no weight, 0.0 if no edge exists.
	GetEdgeWeight(ctx context.Context, fromID, toID string) (float64, error)
}

type QueryDirection int

type QueryResponse[T any] struct {
	Data      T         `json:"data"`
	RequestID string    `json:"request_id,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

type QueryResult struct {
	Entities      []map[string]any `json:"entities"`
	Relationships []map[string]any `json:"relationships"`
	Count         int              `json:"count"`
}

type RelationshipCriteria struct {
	FromID     string         `json:"from_id,omitempty"`
	ToID       string         `json:"to_id,omitempty"`
	Type       string         `json:"type,omitempty"`
	Properties map[string]any `json:"properties,omitempty"`
	Direction  QueryDirection `json:"direction,omitempty"`
}

type RemoveTripleRequest struct {
	Subject   string `json:"subject"`
	Predicate string `json:"predicate"`
	TraceID   string `json:"trace_id,omitempty"`
	RequestID string `json:"request_id,omitempty"`
}

type RemoveTripleResponse struct {
	MutationResponse
	Removed bool `json:"removed"`
}

type StateContractError struct {
	Reason   StateResetReason `json:"reason"`
	EntityID string           `json:"entity_id,omitempty"`
	Err      error            `json:"-"`
}

type StateResetReason string

type StatusReading struct {
	// Status is the last envelope received from the producer.
	Status IndexStatusResponse
	// Fresh reports that the reading is recent enough to vouch for. False means
	// UNKNOWN, which fails closed — not "not ready".
	Fresh bool
}

type SummaryData struct {
	// TotalEntities is the count of entities actually scanned (= sum
	// of EntityTypes counts). When EntitySampleTruncated is true,
	// the underlying graph holds more than this.
	TotalEntities int `json:"total_entities"`

	// EntitySampleTruncated is true when the entity scan hit
	// EntitySampleLimit before draining the bucket. The TotalEntities
	// and per-type counts are then approximate.
	EntitySampleTruncated bool `json:"entity_sample_truncated"`

	// EntityTypes is the sorted (highest-count-first) list of type
	// buckets discovered in the scanned sample.
	EntityTypes []EntityTypeSummary `json:"entity_types"`

	// Predicates is populated when IncludePredicates is true (default).
	// Each entry mirrors PredicateSummary — predicate name + the
	// entity count from the predicate index. Counts here are exact
	// (the predicate index maintains them at write time); they do
	// NOT inherit the entity-scan truncation.
	Predicates []PredicateSummary `json:"predicates,omitempty"`

	// PredicateTotal is len(Predicates). Convenience for callers
	// formatting "N predicates registered" lines.
	PredicateTotal int `json:"predicate_total,omitempty"`
}

type SummaryRequest struct {
	// IncludePredicates toggles the predicate counts section.
	// Defaults to true. Setting false is useful when the caller
	// already has the predicate list cached or when the response
	// would otherwise exceed the gateway's body budget at large
	// scales.
	IncludePredicates bool `json:"include_predicates"`

	// EntitySampleLimit caps how many entity IDs the type-distribution
	// aggregation walks. Defaults to 2000. The resulting type counts
	// are approximate when the scan is truncated; the response sets
	// EntitySampleTruncated=true and TotalEntities reflects what was
	// scanned, not what the graph holds. V2 candidates: write-time
	// type-count index for exact counts.
	EntitySampleLimit int `json:"entity_sample_limit"`

	// ExamplesPerType caps how many sample entity IDs to retain per
	// type bucket in the response. Defaults to 2. Example IDs are
	// load-bearing for the discovery use case (semspec's bug log
	// confirms models invent IDs when no examples are provided);
	// keep this >= 1.
	ExamplesPerType int `json:"examples_per_type"`
}

type UpdateEntityRequest struct {
	Entity    *EntityState `json:"entity"`
	TraceID   string       `json:"trace_id,omitempty"`
	RequestID string       `json:"request_id,omitempty"`
}

type UpdateEntityResponse struct {
	MutationResponse
	Entity  *EntityState `json:"entity,omitempty"`
	Version int64        `json:"version,omitempty"`
}

type UpdateEntityWithTriplesRequest struct {
	Entity *EntityState `json:"entity"`
	// AddTriples are applied with REPLACE-by-(subject,predicate) semantics
	// (MergeTriples — gh#244): every predicate present in AddTriples has its
	// prior values on the entity fully replaced. This is upsert, NOT
	// incremental append. For a SINGLE-valued predicate, send the one new
	// value (the old one is dropped). For a MULTI-valued predicate, send the
	// FULL desired set — a partial set drops the omitted siblings. To ADD to
	// a predicate while preserving existing values, use triple.add /
	// triple.add_batch instead. Predicates absent from AddTriples are
	// untouched.
	AddTriples    []message.Triple `json:"add_triples,omitempty"`
	RemoveTriples []string         `json:"remove_triples,omitempty"` // Predicates to delete (pure delete; runs before the AddTriples merge)
	// ExpectedRevision opts into single-pass CAS-on-condition writes.
	// Non-zero = require entity's current KV revision to match exactly;
	// zero = existing UpdateWithRetry behavior (no CAS check on caller
	// side; internal retry on conflict). Lifecycle Manager.Transition
	// uses the non-zero path per ADR-049 to preserve state-machine
	// correctness under concurrent writes.
	ExpectedRevision uint64 `json:"expected_revision,omitempty"`
	// IndexingProfile, when non-empty, is the EXPLICIT-OVERRIDE channel for an
	// entity's indexing profile (ADR-054 §5). A profile is otherwise immutable
	// after creation; setting it here replaces entity.indexing.profile
	// (RemoveTriples + AddTriples, single-valued). Empty leaves the existing
	// profile untouched. This is the only post-creation way to re-profile an
	// entity — a later triple.add by a different writer must NOT change it.
	IndexingProfile string `json:"indexing_profile,omitempty"`
	// OwnerToken is the writer's owner-identity lease token in the format
	// "<owner>#<incarnation>", where <owner> is the canonical owner id
	// (e.g. "rule-pack.my-pack", "mission-planner") and <incarnation> is a
	// per-process boot nonce (crypto/rand hex) that fences revived-stale
	// writers even when the owner id is unchanged. Empty = unowned or
	// legacy writer; graph-ingest skips the lease check when empty.
	// Compared at graph-ingest by a later increment (ADR-056); PR-1 stamps
	// it here for observe-only transit.
	OwnerToken string `json:"owner_token,omitempty"`
	TraceID    string `json:"trace_id,omitempty"`
	RequestID  string `json:"request_id,omitempty"`
}

type UpdateEntityWithTriplesResponse struct {
	MutationResponse
	Entity         *EntityState `json:"entity,omitempty"`
	TriplesAdded   int          `json:"triples_added"`
	TriplesRemoved int          `json:"triples_removed"`
	Version        int64        `json:"version,omitempty"`
}