memq

type AdmissionVerdict struct {
	Admit  bool
	Reason string
	Detail string
}

type Backend interface {
	// Cells returns the page table as cells, carrying only SAFE metadata (never the
	// bytes of a sealed span). It is a snapshot; the executor does not mutate it.
	Cells(ctx context.Context) ([]Cell, error)
	// Materialize pages one cell's bytes in THROUGH THE TRUST GATE. A sealed/refused
	// cell returns an error wrapping ErrSealed; the bytes never cross the gate.
	Materialize(ctx context.Context, id string) ([]byte, error)
}

type Caps struct {
	Apply bool            `json:"apply"`
	Allow map[string]bool `json:"allow,omitempty"`
}

type Cell struct {
	ID         string            `json:"id"`             // stable address within the backend (e.g. "step:3")
	Step       int               `json:"step"`           // ordinal position (recall page step; -1 for unordered)
	Role       string            `json:"role,omitempty"` // the producer (tool name, "user", "system", "memq/consolidate")
	Kind       string            `json:"kind,omitempty"` // tool_result | reasoning | user | system | episode | disposition
	Descriptor string            `json:"descriptor"`     // SAFE extractive/sealed descriptor; never sealed bytes
	Digest     string            `json:"digest,omitempty"`
	Bytes      int64             `json:"bytes"`                // size (token-cost proxy)
	Durability string            `json:"durability,omitempty"` // turn | session | bounded | durable
	Sealed     bool              `json:"sealed,omitempty"`     // quarantined by the trust gate
	Tombstoned bool              `json:"tombstoned,omitempty"` // suppressed by context control
	Witness    string            `json:"witness,omitempty"`    // external trust witness
	Refs       []string          `json:"refs,omitempty"`       // digests/ids this cell references
	Attrs      map[string]string `json:"attrs,omitempty"`      // OPEN attribute bag (forward-compatible, drop-unknown)
}

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

type ConflictDecision struct {
	Outcome ConflictOutcome `json:"outcome"`
	Reason  string          `json:"reason"`
	// Winner is the record DetectFactConflict identifies as the one to keep acting on
	// when Outcome is ConflictPreferNewer (the zero value otherwise — ConflictAskUser
	// and ConflictKeepBothScoped never pick a single winner by construction).
	Winner PromotionRecord `json:"winner,omitempty"`
	// A and B are the two records the decision was computed over, always in the same
	// order they were passed to DetectFactConflict — never reordered, so a caller can
	// tell which side of the call produced Winner.
	A PromotionRecord `json:"a"`
	B PromotionRecord `json:"b"`
}

type ConflictOutcome string

type Driver struct {
	Name  string             `json:"name"`
	Doc   string             `json:"doc"`
	Build func(Params) Query `json:"-"`
}

type Effect struct {
	Kind         string   `json:"kind"`
	Applied      bool     `json:"applied"`
	Reason       string   `json:"reason,omitempty"`
	Cells        []string `json:"cells,omitempty"`
	Derived      *Cell    `json:"derived,omitempty"`
	DerivedBytes []byte   `json:"-"`
	Note         string   `json:"note,omitempty"`
}

type Explanation struct {
	CellID     string     `json:"cell_id"`
	Found      bool       `json:"found"`
	SourceSpan SourceSpan `json:"source_span,omitempty"`
	Durability string     `json:"durability,omitempty"`
	Consent    string     `json:"consent,omitempty"`
	Producer   string     `json:"producer,omitempty"`
	Expiry     string     `json:"expiry,omitempty"`
	Reason     string     `json:"reason,omitempty"`
	// Narrative is a fixed-template sentence assembled ONLY from the fields above —
	// string concatenation, not a model summarization call. It exists so a CLI/agent
	// has one human-readable line, without reopening the model-narration door the
	// issue explicitly closes.
	Narrative string `json:"narrative"`
}

type IndexOverflow struct {
	Reason  string          `json:"reason"` // always OverflowReason
	Budget  int64           `json:"budget"` // the byte cap enforced
	Kept    int             `json:"kept"`   // in-budget prefix count
	Dropped []OverflowEntry `json:"dropped"`
}

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

type NearDupPair struct {
	A     string  `json:"a"`
	B     string  `json:"b"`
	Score float64 `json:"score"`
}

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

type Op struct {
	Kind   string `json:"kind"`
	Pred   *Pred  `json:"pred,omitempty"`   // filter
	By     string `json:"by,omitempty"`     // rank key, or reclassify target class
	Desc   bool   `json:"desc,omitempty"`   // rank direction (default ascending)
	K      int    `json:"k,omitempty"`      // limit
	Bytes  int64  `json:"bytes,omitempty"`  // budget cap, or narrow's per-cell width cap (bytes)
	Window int    `json:"window,omitempty"` // rank relevance_span: pooling width in cells (odd, >= 1; 1 = identity kernel)
	Reason string `json:"reason,omitempty"` // tombstone/effect reason
	// StarveK is the OPT-IN deterministic anti-starvation credit for the cutline ops
	// (limit/budget), #4021. When > 0, every pass a cell falls below the op's cutline
	// advances a per-cell counter in Attrs[StarveAttr]; once the cell JUST below the
	// cutline is non-durable, unreferenced, and has sat below it for StarveK
	// consecutive passes, it is retained for ONE pass (counter reset) — the
	// NACL/Scissorhands anti-starvation axis with no RNG (see starve.go). 0 (the
	// default) is byte-identical to today.
	StarveK int `json:"starve_k,omitempty"`
	// Protect opts a budget op into the protected-floor split (#4017, NACL/
	// Scissorhands): every durable-class cell, plus the Recent most-recent cells
	// by Step, is charged against the cap FIRST — surviving regardless of
	// relevance rank — before the ephemeral remainder spends the leftover
	// headroom in working-set order. False (the default) is today's plain
	// prefix budget, byte-for-byte.
	Protect bool `json:"protect,omitempty"` // budget: opt-in protected floor (#4017)
	// Recent is the byte-exact recent-window size joined to the protected floor:
	// the top-N most-recent cells by Step, regardless of class (the NACL
	// pins ∪ recent union). Meaningful only with Protect; 0 protects the durable
	// class alone.
	Recent int `json:"recent,omitempty"` // budget: recent-window size (requires protect)
	// MergeFloor opts a budget op into merge-on-evict (#4015, LOOK-M/CAM/KVMerger):
	// instead of tail-dropping a below-budget cell, fold it into its single
	// most-similar SURVIVING cell (argmax simhash cosine) when that similarity is at
	// or above this floor. The evicted cell's Refs — and its own ID — ride onto the
	// survivor, so its provenance is preserved rather than lost, and it leaves the
	// overflow list. Cosine is in [-1,1]; a meaningful floor is in (0,1]. 0 (the
	// default) is off: the budget tail-drops exactly as before, byte-for-byte.
	MergeFloor float64 `json:"merge_floor,omitempty"` // budget: opt-in merge-on-evict similarity floor (#4015)
}

type OverflowEntry struct {
	ID         string `json:"id"`
	Descriptor string `json:"descriptor,omitempty"`
	Bytes      int64  `json:"bytes"`
}

type Params struct {
	Intent string `json:"intent,omitempty"`
	K      int    `json:"k,omitempty"`
	Budget int64  `json:"budget,omitempty"`
	Reason string `json:"reason,omitempty"`

	// NarrowBytes is the OPT-IN per-cell width cap for the second compression axis
	// (#4019): when > 0, render and compact chain an OpNarrow immediately before
	// their OpBudget, so an over-wide cell is slimmed (least-relevant Attrs fields
	// dropped, Descriptor re-headLined) instead of tail-dropped whole. Default 0
	// (off): the compiled Query is identical to before this field existed.
	NarrowBytes int64 `json:"narrow_bytes,omitempty"`

	// RetentionCount is the OPT-IN divergence-outlier exemption (MiniCache; #4018):
	// when > 0, the compact driver carves the RetentionCount most-divergent fold
	// candidates out of the set (OpExempt) before consolidating, so the cells a lossy
	// fold would approximate worst survive bit-exact. 0 (the zero value) builds the
	// exact pre-#4018 pipeline.
	RetentionCount int `json:"retention_count,omitempty"`

	// StarveK opts a driver's cutline op into the deterministic anti-starvation credit
	// (#4021; see Op.StarveK). 0 (the default) builds the exact same query as before.
	StarveK int `json:"starve_k,omitempty"`
	// ProtectFloor opts the render driver's budget stage into the protected-floor
	// split (#4017, NACL/Scissorhands): durable cells plus the ProtectRecent
	// most-recent cells are charged against the byte budget FIRST, so a standing
	// preference or the fresh tail is never tail-dropped by a low relevance rank.
	// Both zero values compile to exactly the query the driver built before the
	// knob existed — default off, byte-identical.
	ProtectFloor bool `json:"protect_floor,omitempty"`
	// ProtectRecent is the byte-exact recent-window size joined to the floor
	// (top-N by Step). Meaningful only with ProtectFloor. Note the render
	// driver's filter precedes its budget, so the window spans the filtered
	// candidate set (intent-matching ∪ durable); author a raw scan→rank→budget
	// query to protect the unconditional recency tail.
	ProtectRecent int `json:"protect_recent,omitempty"`
	// MergeFloor opts the render driver's budget stage into merge-on-evict (#4015):
	// a cell evicted by the byte budget is folded into its nearest surviving near-twin
	// (simhash cosine >= this floor) instead of tail-dropped, preserving the evicted
	// cell's refs on the survivor. Cosine is in [-1,1]; a meaningful floor is in (0,1].
	// 0 (the default) tail-drops as before — byte-identical.
	MergeFloor float64 `json:"merge_floor,omitempty"`
}

type Plan struct {
	Intent string     `json:"intent,omitempty"`
	Steps  []PlanStep `json:"steps"`
	// Effects lists the distinct effect kinds the pipeline would perform, and
	// Mutations the subset that change durable state (and so are proposal-only
	// without a Caps grant). An empty Mutations means the query is read-only.
	Effects   []string `json:"effects,omitempty"`
	Mutations []string `json:"mutations,omitempty"`
	Valid     bool     `json:"valid"`
	Error     string   `json:"error,omitempty"`
}

type PlanStep struct {
	Index       int    `json:"index"`
	Kind        string `json:"kind"`
	Detail      string `json:"detail"`
	Effect      bool   `json:"effect"`
	Mutation    bool   `json:"mutation"`
	RequiresCap string `json:"requires_cap,omitempty"`
}

type Pred struct {
	Op    string `json:"op"`
	Field string `json:"field,omitempty"` // durability|role|kind|descriptor|digest|witness|bytes|step|sealed|tombstoned|refcount|attr:<k> (unused by hasref, which reads Value against Refs)
	Value string `json:"value,omitempty"`
	Args  []Pred `json:"args,omitempty"` // sub-predicates for and/or/not
}

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

type PromotionMeta struct {
	Consent  string
	Producer string
	Expiry   string
	Reason   string
}

type PromotionRecord struct {
	// CellID is the address of the promoted cell (memq.Cell.ID) — the join key back to
	// the page table.
	CellID string `json:"cell_id"`
	// SourceSpan identifies WHERE the fact came from in the live turn: the ordinal
	// step, the producing role, and a safe extractive descriptor (never sealed bytes —
	// same posture as Cell.Descriptor). This is the "source span/reference" the issue
	// asks for.
	SourceSpan SourceSpan `json:"source_span"`
	// Durability is the class earned at promotion time (turn|session|bounded|durable —
	// reuses the existing memq/ctxmmu/recall vocabulary; NormDurability applied).
	Durability string `json:"durability"`
	// Consent records whether a human/operator explicitly asked for this promotion, or
	// whether it was inferred by a producer/classifier (ConsentExplicit|ConsentInferred
	// |ConsentUnknown; NormConsent applied).
	Consent string `json:"consent"`
	// Producer names WHAT wrote this cell: a tool name, "user", a driver
	// ("memq/consolidate"), or a backend ("codex:<path>"). Free text but always
	// populated — NormProducer defaults an empty value to "unknown" so the field is
	// never silently blank.
	Producer string `json:"producer"`
	// Expiry is the optional validity bound for a `bounded` promotion (an opaque,
	// caller-defined tick/step/timestamp string — memq does not interpret it, mirroring
	// recall.Page.ValidTo's "auditable, re-checked elsewhere" posture). Empty means no
	// stated expiry: a `durable` record is expected to leave this empty; a `bounded`
	// record without one is a data-quality fact Explain surfaces, not an error.
	Expiry string `json:"expiry,omitempty"`
	// Reason is the free-text justification the producer supplied (e.g. a driver's
	// tombstone/promotion reason, or "user said: remember this"). Never used as the
	// ONLY explanation — Explain renders it alongside the structured fields, not
	// instead of them.
	Reason string `json:"reason,omitempty"`
	// Seq is the ledger-assigned insertion order (0-based) — deterministic, so replay
	// over the same inputs produces byte-identical records (no wall-clock dependence).
	Seq int `json:"seq"`
}

type Pruner interface {
	Prune(ctx context.Context, apply bool) (blobs int, bytes int64, err error)
}

type Query struct {
	Intent string `json:"intent,omitempty"`
	// NearDupThreshold is the OPT-IN advisory near-duplicate flag (#2506). When > 0,
	// Run pages each non-sealed cell's body in through the trust gate, embeds it via
	// internal/simhash, and reports body-similar pairs (cosine >= threshold) on
	// Result.Advisory for a compactor (memory-compact) to consume. It is ADVISORY
	// only — a fuzzy signal never silently decides (the vdso/neardup.go discipline),
	// so the pair is reported, never collapsed. Default 0 (off).
	NearDupThreshold float64 `json:"near_dup_threshold,omitempty"`
	// Intents is the OPT-IN multi-intent recall slice (#4020, GQA group-reduce): the
	// N consumer intents that must share this one retained set. When non-empty it
	// supersedes Intent for relevance scoring — every cell is scored against every
	// intent and the per-intent scores fold to ONE shared score via ScoreAgg (see
	// reduceGroupScores in exec.go). Empty (the default) keeps the single-Intent
	// scoring path byte-identical to today; Intents={x} ranks identically to Intent=x.
	Intents []string `json:"intents,omitempty"`
	// ScoreAgg is the tunable reduction operator folding per-intent scores when
	// Intents is set: ScoreAggMean (the default when empty), ScoreAggAmax, or
	// ScoreAggSum. An unknown value fails Validate (fail-closed); without Intents
	// the field is inert.
	ScoreAgg string `json:"score_agg,omitempty"`
	Ops      []Op   `json:"ops"`
}

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

type Reclassifier interface {
	Reclassify(ctx context.Context, id, newClass, by string) (bool, error)
}

type Refusal struct {
	ID     string `json:"id"`
	Step   int    `json:"step"`
	Role   string `json:"role,omitempty"`
	Reason string `json:"reason"`
}

type RenderItem struct {
	ID         string `json:"id"`
	Step       int    `json:"step"`
	Role       string `json:"role,omitempty"`
	Descriptor string `json:"descriptor"`
	Bytes      int64  `json:"bytes"`
	Tokens     int    `json:"tokens"`
}

type Result struct {
	Intent   string         `json:"intent,omitempty"`
	Steps    []StepTrace    `json:"steps"`
	Rendered []RenderItem   `json:"rendered,omitempty"`
	Effects  []Effect       `json:"effects,omitempty"`
	Refused  []Refusal      `json:"refused,omitempty"`
	Advisory []NearDupPair  `json:"advisory,omitempty"` // opt-in near-dup pairs (#2506); advisory, never collapsed
	Overflow *IndexOverflow `json:"overflow,omitempty"` // typed over-budget verdict (#2430); nil when nothing overflowed
	Starve   *StarveReport  `json:"starve,omitempty"`   // typed anti-starvation verdict (#4021); nil unless an opt-in StarveK op changed a counter
	Working  []Cell         `json:"working,omitempty"`  // final working set (safe metadata only)
	Stats    Stats          `json:"stats"`
}

type SourceSpan struct {
	Step       int    `json:"step"`
	Role       string `json:"role,omitempty"`
	Descriptor string `json:"descriptor,omitempty"`
	Digest     string `json:"digest,omitempty"`
}

type StarveReport struct {
	Reason  string         `json:"reason"` // always StarveReason
	K       int            `json:"k"`
	Granted string         `json:"granted,omitempty"` // cell retained past the cutline this pass
	Updates []StarveUpdate `json:"updates,omitempty"`
}

type StarveUpdate struct {
	ID      string `json:"id"`
	Passes  int    `json:"passes"`            // new consecutive-below-cutline count to persist
	Granted bool   `json:"granted,omitempty"` // the one-pass survival credit fired (counter reset)
}

type Stats struct {
	CellsScanned    int   `json:"cells_scanned"`
	CellsSelected   int   `json:"cells_selected"` // final working-set size
	Rendered        int   `json:"rendered"`
	RenderedBytes   int64 `json:"rendered_bytes"`
	EstimatedTokens int   `json:"estimated_tokens"`
	Refused         int   `json:"refused"`
	EffectsProposed int   `json:"effects_proposed"`
	EffectsApplied  int   `json:"effects_applied"`
	// DedupCollapsed counts byte-identical cells folded by the read-side exact-digest
	// collapse (#2506). It is the read-side dedup counter the dedup census fold reads
	// alongside the write-side ledger (#2142).
	DedupCollapsed int `json:"dedup_collapsed"`
	// NearDupAdvisory counts body-similar pairs flagged by the opt-in simhash advisory
	// (#2506) — the fuzzy near-dup counter for the dedup census fold.
	NearDupAdvisory int `json:"near_dup_advisory"`
	// Narrowed counts cells whose width was pruned by the opt-in OpNarrow pass (#4019)
	// — the width-axis counter alongside the count-axis DedupCollapsed. omitempty keeps
	// a serialized Result byte-identical when the op is never used.
	Narrowed int `json:"narrowed,omitempty"`
	// MergedOnEvict counts below-budget cells folded into a surviving near-twin by the
	// opt-in merge-on-evict pass (#4015) instead of tail-dropped. omitempty keeps a
	// serialized Result byte-identical when the op is never used.
	MergedOnEvict int `json:"merged_on_evict,omitempty"`
}

type StepTrace struct {
	Index int    `json:"index"`
	Kind  string `json:"kind"`
	In    int    `json:"in"`
	Out   int    `json:"out"`
	Note  string `json:"note,omitempty"`
}

type Tombstoner interface {
	Tombstone(ctx context.Context, id, reason, by string) (bool, error)
}