planner

type AffinityBeadInputs struct {
	BeadID       string
	Concepts     []ConceptTag
	Targets      []string // repo-relative paths
	Repositories []string
	Branch       string // optional; "" = no branch preference
}

type AffinityScores struct {
	ConceptOverlap  float64 `json:"concept_overlap"`
	FileFamiliarity float64 `json:"file_familiarity"`
	WorkspaceMatch  float64 `json:"workspace_match"`
	Recency         float64 `json:"recency"`
	Headroom        float64 `json:"headroom"`
	// Combined is the weighted sum. Tracked separately so the
	// explanation surface always carries the same number it
	// rendered the breakdown for — never re-derive on the consumer
	// side.
	Combined float64 `json:"combined"`
}

type AffinityWeights struct {
	ConceptOverlap  float64 `json:"concept_overlap"`
	FileFamiliarity float64 `json:"file_familiarity"`
	WorkspaceMatch  float64 `json:"workspace_match"`
	Recency         float64 `json:"recency"`
	Headroom        float64 `json:"headroom"`
}

type AgentLookup interface {
	ReadAgent(ctx context.Context, id core.AgentID) (*core.AgentRef, error)
}

type AnalysisScopeStatus struct {
	Backend       string    `json:"backend,omitempty"`
	State         string    `json:"state"`
	IndexedAt     time.Time `json:"indexed_at,omitempty"`
	IndexedCommit string    `json:"indexed_commit,omitempty"`
	HeadSHA       string    `json:"head_sha,omitempty"`
	Reason        string    `json:"reason,omitempty"`
}

type AssignmentLookup interface {
	FindAssignment(ctx context.Context, assignmentID string) (*core.Assignment, error)
}

type BeadConceptLookup interface {
	// BeadConcepts returns the concept-tag → weight map associated
	// with the given completed bead. Returning a nil/empty map +
	// nil error is "no concepts known for this bead" — the planner
	// treats it as a non-error skip.
	BeadConcepts(ctx context.Context, beadID core.WorkItemID) (map[ConceptTag]float64, error)
}

type BeadTarget struct {
	BeadID       string
	Repository   string
	Branch       string
	WorktreePath string
}

type ClaimEvent struct {
	SessionID    string
	AssignmentID string
	AgentID      core.AgentID
	BeadID       core.WorkItemID
	// Concepts / Files come from the bead's declared targets +
	// concepts (gm-s47n.1 once it lands; provider's structured
	// extras until then).
	Concepts []ConceptTag
	Files    []string
	// HalfLife overrides DefaultDecayHalfLife per call so a future
	// per-rig setting can flow through without changing the API.
	HalfLife int
	// Now is injected for deterministic test runs; nil → time.Now.
	Now func() time.Time
}

type CompletionEvent struct {
	SessionID      string
	AssignmentID   string
	AgentID        core.AgentID
	BeadID         core.WorkItemID
	ActualConcepts []ConceptTag
	ActualFiles    []string
	// TokensUsed / ContextWindowMax are optional snapshots the
	// adaptor may have observed at completion time (e.g. via the
	// agent's telemetry hook). Zero values leave the existing
	// profile fields untouched.
	TokensUsed       int
	ContextWindowMax int
	HalfLife         int
	Now              func() time.Time
}

type ConceptTag string

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

type DispatchPolicy struct {
	// Enabled is the master kill switch. false → AllowDispatch
	// always returns ("no", "auto-dispatch disabled"). Default
	// false (opt-in per spec §4 Layer 5).
	Enabled bool `json:"enabled"`
	// MinIntervalPerSession is the minimum wall-clock gap between
	// successive auto-dispatches against the same session id.
	// Zero falls back to DefaultMinIntervalPerSession.
	MinIntervalPerSession time.Duration `json:"min_interval_per_session"`
	// MaxConcurrent caps the number of auto-dispatches the gate
	// will allow to be in flight at any instant. Zero falls back
	// to DefaultMaxConcurrent.
	MaxConcurrent int `json:"max_concurrent"`
}

type EventContribution struct {
	Concepts []ConceptTag
	Files    []string
	Weight   float64
}

type GitScopeStatus struct {
	State        string `json:"state"`
	ChangedFiles int    `json:"changed_files,omitempty"`
	Ahead        int    `json:"ahead,omitempty"`
	Behind       int    `json:"behind,omitempty"`
	HeadSHA      string `json:"head_sha,omitempty"`
	Upstream     string `json:"upstream,omitempty"`
	Reason       string `json:"reason,omitempty"`
}

type OperationalContext struct {
	Agent       *core.AgentRef   `json:"agent,omitempty"`
	Session     *core.Session    `json:"session,omitempty"`
	Workspace   *core.Workspace  `json:"workspace,omitempty"`
	Assignment  *core.Assignment `json:"assignment,omitempty"`
	Profile     *SessionProfile  `json:"profile,omitempty"`
	Health      *SessionHealth   `json:"health,omitempty"`
	ScopeStatus *ScopeStatus     `json:"scope_status,omitempty"`
}

type OperationalContextReaders struct {
	Sessions    SessionLookup
	Agents      AgentLookup
	Assignments AssignmentLookup
	Workspaces  WorkspaceLookup
	Profiles    ProfileLookup
	// BeadConcepts is the optional gm-s47n.5.1 concept-drift input.
	// When wired, ComputeHealth uses it to derive the last-N concept
	// vector from profile.LastBeads and compute concept_drift; nil
	// leaves drift at zero. The concrete impl ships with gm-s47n.1
	// WorkItem-concept enrichment.
	BeadConcepts BeadConceptLookup
	Now          func() time.Time
}

type ProfileLookup interface {
	GetProfile(ctx context.Context, sessionID string) (*SessionProfile, error)
}

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

type ProfileWriter interface {
	RecordClaim(ctx context.Context, ev ClaimEvent) (*SessionProfile, error)
	RecordCompletion(ctx context.Context, ev CompletionEvent) (*SessionProfile, error)
	UpsertProfile(ctx context.Context, p *SessionProfile) error
}

type RecycleDecision struct {
	Recycle      bool           `json:"recycle"`
	Reason       RecycleReason  `json:"reason"`
	DriverScores RecycleDrivers `json:"drivers"`
}

type RecycleDrivers struct {
	ContextPressure  float64 `json:"context_pressure"`
	ConceptDrift     float64 `json:"concept_drift"`
	TimeOnTaskHours  float64 `json:"time_on_task_hours"`
	IncomingAffinity float64 `json:"incoming_affinity"`
	MedianAffinity   float64 `json:"median_affinity"`
	ConceptOverlap   float64 `json:"concept_overlap"`
}

type RecycleInputs struct {
	// Health is the SessionHealth snapshot from gm-s47n.5.1. nil
	// → all driver thresholds skip.
	Health *SessionHealth

	// IncomingBead is the candidate bead the planner is about to
	// dispatch against this session. Empty Concepts means rule 2
	// can't compute the overlap; rule 3 falls back to "this is
	// the start of a new area" if the session profile has any
	// concepts at all (the bead's empty list cannot intersect).
	IncomingBead AffinityBeadInputs

	// IncomingAffinityScores are the precomputed Affinity scores
	// for (IncomingBead, this session). Saves the caller the
	// recompute when ShouldRecycle runs alongside the affinity
	// pass. Combined drives rule 1.
	IncomingAffinityScores AffinityScores

	// ReadySetAffinities is the combined-affinity score of every
	// ready bead against this session. Used to compute the median
	// for rule 1. Empty slice → rule 1 cannot fire.
	ReadySetAffinities []float64

	// SessionConcepts is the lifetime concept profile. Used to
	// compute the new-area / overlap drivers for rules 2 + 3.
	// nil → rules 2 and 3 fall back to the safest answer
	// (no concepts known, so the bead is "all new" — defended
	// below in evaluateConceptOverlap).
	SessionConcepts map[ConceptTag]float64
}

type RecycleReason string

type ScopeStatus struct {
	Git      *GitScopeStatus      `json:"git,omitempty"`
	Analysis *AnalysisScopeStatus `json:"analysis,omitempty"`
}

type SemanticBeadInputs struct {
	BeadID  string
	Targets []sourceanalysis.Target
}

type SemanticConflict struct {
	A      string `json:"a"`
	B      string `json:"b"`
	Reason string `json:"reason"`
}

type SessionHealth struct {
	// ContextPressure = TokensUsed / ContextWindowMax. Zero when
	// ContextWindowMax is not yet observed (session pre-telemetry).
	ContextPressure float64 `json:"context_pressure"`
	// ConceptDrift = cosine distance between the session's last-N
	// concept vector and the lifetime concept vector. Range [0, 1];
	// 0 means "still on the same topic", 1 means "completely shifted".
	ConceptDrift float64 `json:"concept_drift"`
	// TimeOnTask is wall clock since core.Session.StartedAt.
	TimeOnTask time.Duration `json:"time_on_task_ns"`
}

type SessionLookup interface {
	// FindSession returns the session by id. Implementations should
	// return (nil, nil) for "not found" so callers can distinguish
	// transient errors from genuine absence; an error here is treated
	// as fatal by ReadOperationalContext.
	FindSession(ctx context.Context, sessionID string) (*core.Session, error)
}

type SessionProfile struct {
	// SessionID matches core.Session.ID — primary key in the dolt
	// table.
	SessionID string `json:"session_id"`
	// AssignmentID denormalised from core.Assignment so the planner
	// can answer "what is this session currently on?" in one read.
	AssignmentID string `json:"assignment_id"`
	// AgentID denormalised from core.AgentRef.ID so per-agent
	// rollups don't require a second lookup.
	AgentID core.AgentID `json:"agent_id"`

	// Concepts is the recency-decayed concept profile: tag → weight.
	// JSON object on the wire; dolt column is JSON.
	Concepts map[ConceptTag]float64 `json:"concepts,omitempty"`

	// Files is the recency-decayed file-touch profile: repo-relative
	// path → weight. Same shape as Concepts.
	Files map[string]float64 `json:"files,omitempty"`

	// TokensUsed is the most recent observed token usage on the
	// session's underlying LLM context. Surfaced via the agent's
	// telemetry hook (gm-s47n.2.3).
	TokensUsed int `json:"tokens_used,omitempty"`
	// ContextWindowMax is the agent's hard context window. Stored
	// alongside TokensUsed so a single read computes
	// `tokens_used / context_window_max` without a separate manifest
	// lookup. May be zero on first observation.
	ContextWindowMax int `json:"context_window_max,omitempty"`
	// ContextPct is the precomputed `TokensUsed / ContextWindowMax`
	// snapshot — derived but persisted so the SPA / planner share the
	// same number without re-deriving. Always in [0, 1] when
	// ContextWindowMax is non-zero; zero when not yet observed.
	ContextPct float64 `json:"context_pct,omitempty"`

	// LastBeads is the ring buffer of the last N completed bead ids
	// (newest last). Capped at LastBeadsRingSize. The retrospective
	// (gm-s47n.8) reads it to detect "session just shipped X" cases.
	LastBeads []core.WorkItemID `json:"last_beads,omitempty"`

	// LastActivityAt is the timestamp of the most recent BEAD-EVENT
	// boundary (claim or completion) on this session — distinct from
	// core.Session.LastHeartbeat which updates on every health ping.
	// "Activity" here means "the session moved the planner's world".
	LastActivityAt time.Time `json:"last_activity_at"`

	// CreatedAt / UpdatedAt — table audit columns. The planner reads
	// UpdatedAt to break ties when two sessions have the same
	// affinity (newer profile wins).
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type WorkspaceCollision struct {
	// A and B are bead ids. For bead↔live edges, B is the bead
	// being blocked by the live session and A is left empty —
	// callers branch on LiveSessionID being non-empty rather than
	// on string sentinels.
	A string `json:"a,omitempty"`
	B string `json:"b"`

	// Reason is a one-line human explanation: "same repo+branch",
	// "same worktree_path", "live session in branch X", etc. The
	// .4.3 composer surfaces this verbatim in the coach UI; never
	// parse it back.
	Reason string `json:"reason"`

	// LiveSessionID is non-empty when this edge is a bead↔live
	// collision. The corresponding live OperationalContext can be
	// looked up via the planner's session resolver.
	LiveSessionID string `json:"live_session_id,omitempty"`
}

type WorkspaceLookup interface {
	InspectWorkspace(ctx context.Context, workspaceID string) (core.Workspace, error)
}