consolidation

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

type ClaimData struct {
	WindowID string `json:"window_id"`
	CortexID string `json:"cortex_id"`
}

type ClusterInput struct {
	Traces []TraceInput
}

type ClusterResult struct {
	IDs        []string      `json:"ids"`
	Bucket     string        `json:"bucket"` // groupKey() output, e.g. "note|2026-04-13"
	Profile    string        `json:"profile"`
	Outcome    string        `json:"outcome"` // distilled | rejected | skipped | fallback | error
	Title      string        `json:"title,omitempty"`
	Tags       []string      `json:"tags,omitempty"`
	Body       string        `json:"body,omitempty"`
	Confidence float64       `json:"confidence,omitempty"`
	Reason     string        `json:"reason,omitempty"`
	Sources    []SourceTrace `json:"sources,omitempty"` // only populated on --emit-json
}

type CompletionRequest struct {
	Model           string
	Messages        []Message
	Temperature     float64
	MaxTokens       int
	DisableThinking bool
}

type Config struct {
	// Cron is the nightly trigger time in "HH:MM" (local clock). Empty
	// disables the cron trigger.
	Cron string
	// IdleMinutes fires a pass when no mutation has hit the event log
	// for this many minutes. Zero disables.
	IdleMinutes int
	// ThresholdShort fires a pass when the short-term tier count
	// exceeds this. Zero disables.
	ThresholdShort int
	// PollInterval controls how often the cadence state is re-evaluated.
	// Zero defaults to 60s — tight enough that cron fires within a
	// minute of the configured time, loose enough that the agent is
	// effectively free of background cost.
	PollInterval time.Duration
	// CronRetryWindow is how long to wait after a cron trigger fires
	// before checking whether it actually resulted in a consolidation
	// pass running (locally or on a peer). If no success event has
	// landed within this window, the trigger re-fires up to
	// CronMaxRetries times. Zero disables retries entirely — useful for
	// single-node cortexes whose passes don't emit success events, and
	// for tests that drive evaluateAndMaybeRun directly. Issue #56:
	// without this, a staggered-restart election can have every peer
	// defer to another, nobody runs, and the cron opportunity is burned
	// until tomorrow.
	CronRetryWindow time.Duration
	// CronMaxRetries bounds how many times a single cron fire will
	// re-attempt before the agent gives up and marks the day as failed.
	// Zero treated as "no retries", same as CronRetryWindow=0. Defaults
	// applied in cmd_serve, not here, so tests can probe the zero case.
	CronMaxRetries int
}

type Cortex interface {
	LastMutationTime() (time.Time, error)
	ShortTierCount() (int, error)
	// HasConsolidationSuccessAfter is queried by the cron retry path
	// to detect whether a fired trigger actually resulted in a pass
	// running (locally or on any peer that replayed a success event
	// back to us via federation). See checkCronRetry for the protocol.
	HasConsolidationSuccessAfter(cutoff time.Time) (bool, error)
}

type Distillation struct {
	Cohesive   bool
	Title      string
	Body       string
	Tags       []string
	Confidence float64
}

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

type ElectionConfig struct {
	// CortexID is this cortex's stable ULID. Decide compares it against
	// the winning CortexID to classify self-won vs. other-won vs. none.
	CortexID string

	// PeerNames lists federated peers whose ranks should be gathered
	// from federation_state when Decide is called. Pass an empty slice
	// for single-node cortexes; Decide degenerates to "we're the only
	// eligible peer" automatically.
	PeerNames []string

	// QuietPeriod is the minimum age (now - ObservedAt) for a rank
	// entry to count toward the election. Matches 2 × federation.
	// interval per the plan. Callers in tests may pass zero to disable.
	QuietPeriod time.Duration

	// Now is injected for tests; zero defaults to time.Now.
	Now func() time.Time

	// State provides read access to rank entries. Required.
	State *federation.State

	// Emitter is the target for Claim / Success / Fail events.
	// Required.
	Emitter EventEmitter

	// Log is the optional logger; nil is a safe no-op.
	Log func(format string, args ...any)
}

type EligibilityConfig struct {
	// Enabled reflects cortex.md consolidation.enabled. When false the
	// loop advertises Rank=0 unconditionally so peers see this cortex as
	// opted out.
	Enabled bool

	// LLMEnabled reflects cortex.md consolidation.llm_enabled. When false
	// the loop also advertises Rank=0 — a cortex without an LLM cannot
	// run distillation passes and so cannot legitimately win a round.
	LLMEnabled bool

	// TriggersConfigured is true when the cortex has at least one
	// scheduling trigger (cron / idle_minutes / threshold_short) set.
	// startConsolidator returns nil without starting the agent when no
	// trigger is configured; if this loop kept advertising a non-zero
	// rank in that state, the peer would become a "phantom winner" that
	// other peers defer to forever — the ring would stall because the
	// elected leader never claims a window. Forcing Rank=0 here is the
	// signal to the ring that this peer cannot legitimately run a pass.
	TriggersConfigured bool

	// FederationMode is the effective federation mode of this cortex
	// (sync / publish / subscribe). When "subscribe", the loop forces
	// Rank=0 because a read-only mirror cannot legitimately run a
	// consolidation pass — matches the §14 mode table in the plan.
	// Empty string is treated as "sync" (the EffectiveMode default).
	FederationMode string

	// Endpoint is the OpenAI-compatible base URL probed on every tick.
	// Empty endpoint is treated as unreachable.
	Endpoint string

	// CortexID is this cortex's stable ULID, stamped into every
	// RankEntry so remote peers can attribute the advertisement.
	CortexID string

	// CheckInterval is the probe cadence. Zero defaults to
	// defaultCheckInterval (15 min).
	CheckInterval time.Duration

	// Now injects a clock for tests. Zero defaults to time.Now.
	Now func() time.Time

	// Probe injects a probe function for tests. Zero defaults to
	// ProbeEndpoint with a real HTTP client.
	Probe func(ctx context.Context, endpoint string) bool

	// State persists the advertised RankEntry in federation_state.
	// Required; constructors that receive a nil State will panic at
	// first write rather than silently no-op.
	State *federation.State

	// Log is the optional logger; nil is a safe no-op.
	Log func(format string, args ...any)
}

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

type EventEmitter interface {
	EmitCoordinationEvent(action event.Action, windowID string, data any) error
}

type FailData struct {
	WindowID string `json:"window_id"`
	CortexID string `json:"cortex_id"`
	Reason   string `json:"reason"`
}

type GraduationConfig struct {
	// MinAge is the minimum age a mid-tier trace must reach before it
	// can be considered for graduation. Zero defaults to 14 days.
	MinAge time.Duration

	// MinReadCount is the minimum read_count for graduation. Zero
	// defaults to 3.
	MinReadCount int

	// AllowModified opts OUT of the stability gate. Zero value is
	// false, which matches the plan's "base truths are unmodified
	// since creation" default — so a caller who forgets to set this
	// field still gets the strict behavior. Flip to true in cortexes
	// where edits are routine and shouldn't block graduation.
	//
	// Inverted from the originally-proposed RequireUnmodified to make
	// the zero-value safe: the runtime type is consumed by an
	// internal caller (cmd_serve.go) that translates from the YAML-
	// facing cortex.GraduationConfig, but shipping a struct where
	// the safe default requires an explicit assignment is a
	// maintenance trap.
	AllowModified bool
}

type GraduationProvider interface {
	GraduationCandidates(minAge time.Duration) ([]cortex.PromotionCandidate, error)
	Promote(id, newTier string) error
}

type HTTPLLMClient struct {
	Endpoint   string       // base URL, e.g. "http://localhost:11434/v1"
	APIKey     string       // optional bearer token
	HTTPClient *http.Client // nil means a reasonable default is used
}

type HeuristicProvider interface {
	PromotionCandidates(tier string, window time.Duration) ([]cortex.PromotionCandidate, error)
	Promote(id, newTier string) error
}

type LLMClient interface {
	Complete(ctx context.Context, req CompletionRequest) (string, error)
}

type LLMCortex interface {
	PromotionCandidates(tier string, window time.Duration) ([]cortex.PromotionCandidate, error)
	Promote(id, newTier string) error
	CreateDistilledTrace(spec cortex.DistilledTraceSpec) (string, error)
	TraceFile(id string, archived bool) string
	Get(id string) (*cortex.Row, error)
}

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type Outcome struct {
	// ShouldRun is true when the caller should proceed with the pass.
	ShouldRun bool

	// Winner is the CortexID of the elected peer, or empty if no one
	// qualified.
	Winner string

	// Reason is a short human-readable explanation for logs.
	Reason string
}

type PassConfig struct {
	// Window bounds the candidate pool to traces created within the
	// last N. Zero defaults to 24h.
	Window time.Duration

	// PromotionThreshold is the minimum blended score a candidate
	// needs to promote from short to mid. Zero defaults to 5 (tuned
	// so: 5 agent reads qualifies, 1 explicit user vote qualifies,
	// 2 derived-from references qualifies).
	PromotionThreshold int

	// Per-signal weights. Zero uses the defaults:
	//   reads    = 1  (weakest; easy to inflate)
	//   modifies = 2  (stronger; agent actively edited)
	//   lineage  = 3  (stronger still; others reference this)
	//   votes    = 5  (strongest; explicit user/agent intent)
	WeightReads    int
	WeightModifies int
	WeightLineage  int
	WeightVotes    int
}

type PassFn func(ctx context.Context, trigger string) error

type PassResult struct {
	Trigger    string
	Considered int
	Promoted   int
	Skipped    int
}

type PipelineConfig struct {
	Window     time.Duration
	ModelTier  string
	ModelName  string
	MaxRetries int
	DryRun     bool
}

type PipelineResult struct {
	CandidatesConsidered int
	ClustersAttempted    int
	DistillationsCreated int
	FallbackPromotions   int
	Rejected             int
	Skipped              int

	// ClusterResults is the per-cluster breakdown. Populated for every
	// cluster the pipeline considered — distilled, rejected, skipped,
	// or fallback-promoted. Used by --emit-json for prompt-tuning
	// evaluation (a frontier model can score each distillation against
	// its sources to turn vibes into numbers).
	ClusterResults []ClusterResult `json:"cluster_results,omitempty"`
}

type Profile interface {
	Name() string
	MaxClusterSize() int
	Run(ctx context.Context, llm LLMClient, model string, cluster ClusterInput) (Distillation, error)
}

type SourceTrace struct {
	ID    string   `json:"id"`
	Title string   `json:"title"`
	Tags  []string `json:"tags,omitempty"`
	Body  string   `json:"body,omitempty"`
}

type SuccessData struct {
	WindowID             string `json:"window_id"`
	CortexID             string `json:"cortex_id"`
	DistillationsCreated int    `json:"distillations_created,omitempty"`
	SourcesPromoted      int    `json:"sources_promoted,omitempty"`
}

type TraceInput struct {
	ID    string
	Title string
	Body  string
	Tags  []string
}

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

type WatchdogConfig struct {
	// DB is the cortex's SQLite connection. Required; the sweep query
	// joins the events table to itself to find orphaned claims.
	DB *sql.DB

	// Emitter is the target for the closing fail events. In production
	// this is the same *cortex.Cortex that EligibilityLoop and Election
	// share; the narrow interface lets tests substitute a recorder.
	Emitter EventEmitter

	// LocalCortexID is this cortex's stable ULID. Stamped into every
	// emitted fail event so observers can attribute the closing
	// decision to a specific peer for audit purposes.
	LocalCortexID string

	// Timeout is how old a claim must be (now - claim.timestamp) before
	// the watchdog treats it as orphaned. Generous by default — the
	// longest legitimate pass we expect is LLM distillation on a
	// large window, which still completes well inside this budget.
	// Zero defaults to defaultWatchdogTimeout.
	Timeout time.Duration

	// Interval is the sweep cadence. Sweeps are cheap (one indexed
	// query) so a tight cadence is fine; the trade-off is mostly how
	// long an actually-stuck pass blocks the ring before being
	// closed out. Zero defaults to defaultWatchdogInterval.
	Interval time.Duration

	// Now is injected for tests; zero defaults to time.Now.
	Now func() time.Time

	// Log is the optional logger; nil is a safe no-op.
	Log func(format string, args ...any)
}