brain

type ADR struct {
	ID           string   `json:"id"`
	Title        string   `json:"title"`
	Status       string   `json:"status"` // proposed | accepted | deprecated | superseded
	ContextText  string   `json:"context,omitempty"`
	Decision     string   `json:"decision"`
	Consequences string   `json:"consequences,omitempty"`
	LinkedFiles  []string `json:"linked_files,omitempty"` // file path glob patterns
	CreatedAt    string   `json:"created_at"`
	UpdatedAt    string   `json:"updated_at"`
}

type ADRRequest struct {
	ID           string   `json:"id"`
	Title        string   `json:"title"`
	Status       string   `json:"status"` // proposed | accepted | deprecated | superseded
	ContextText  string   `json:"context,omitempty"`
	Decision     string   `json:"decision"`
	Consequences string   `json:"consequences,omitempty"`
	LinkedFiles  []string `json:"linked_files,omitempty"`
}

type AgentStatus struct {
	AgentID   string `json:"agent_id"`
	Scope     string `json:"scope"`
	ScopeType string `json:"scope_type"`
	// ExpiresIn is the seconds until this claim expires (0 = unknown).
	ExpiresIn int `json:"expires_in_seconds,omitempty"`
}

type Brain interface {
	// Ingest summarizes a changed code snippet and persists it in brain.sqlite.
	// Called on file-save events for changed functions/methods/structs.
	// Returns immediately if LLM is unavailable.
	Ingest(ctx context.Context, req IngestRequest) (IngestResponse, error)

	// Enrich adds semantic summaries and a 2-sentence insight to a carved context subgraph.
	// Summaries are loaded from brain.sqlite (fast path, no LLM call).
	// Insight is generated by the LLM only if Enrich feature is enabled.
	Enrich(ctx context.Context, req EnrichRequest) (EnrichResponse, error)

	// ExplainViolation generates a plain-English explanation and fix for a rule violation.
	// Results are cached in brain.sqlite to avoid repeated LLM calls for the same violation.
	ExplainViolation(ctx context.Context, req ViolationRequest) (ViolationResponse, error)

	// Coordinate suggests work distribution when agents conflict on a scope.
	Coordinate(ctx context.Context, req CoordinateRequest) (CoordinateResponse, error)

	// Summary returns the stored semantic summary for a node ID.
	// Returns "" if no summary has been ingested for this node.
	Summary(projectID, nodeID string) string

	// Available returns true if the configured LLM backend is reachable.
	Available() bool

	// ModelName returns the configured LLM model tag.
	ModelName() string

	// EnsureModel checks if the configured model is present locally; if not,
	// it pulls it (Ollama registry for ollama, HuggingFace GGUF for local).
	// Returns nil when the model is ready, an error if the download fails.
	EnsureModel(ctx context.Context, w io.Writer) error

	// BuildContextPacket assembles a structured Context Packet for an agent.
	// Returns nil (with no error) when the Brain is unavailable — callers fall
	// back to raw Synapses context unchanged.
	BuildContextPacket(ctx context.Context, req ContextPacketRequest) (*ContextPacket, error)

	// LogDecision records an agent's completed work and updates co-occurrence
	// patterns in brain.sqlite. Non-fatal; errors are returned but do not
	// block the calling agent.
	LogDecision(ctx context.Context, req DecisionRequest) error

	// SetSDLCPhase persists the project's current SDLC phase.
	SetSDLCPhase(phase SDLCPhase, agentID string) error

	// SetQualityMode persists the project's current quality mode.
	SetQualityMode(mode QualityMode, agentID string) error

	// GetSDLCConfig returns the current SDLC config.
	GetSDLCConfig() SDLCConfig

	// GetPatterns returns learned co-occurrence patterns sorted by confidence.
	// If trigger is non-empty, only patterns with that trigger are returned.
	// limit caps the number of results (0 = default of 20).
	GetPatterns(trigger string, limit int) []PatternHint

	// Prune strips boilerplate (navigation, ads, footers) from raw web page text
	// using the Tier 0 (0.8B) model. Returns cleaned technical content.
	// Falls back to returning the original content if the LLM is unavailable.
	Prune(ctx context.Context, content string) (string, error)

	// Memorize synthesizes a session transcript into persistent memory entries
	// and code annotations. Powered by the Archivist fine-tuned model (T2, cold standby).
	// Returns empty response (no error) when the Archivist LLM is unavailable.
	Memorize(ctx context.Context, req archivist.MemorizeRequest) (archivist.MemorizeResponse, error)

	// Generate sends a raw prompt to the brain's primary LLM and returns the
	// response. Used for one-off LLM calls (e.g., brain-enhanced drift summaries)
	// that don't fit into the ingest/enrich/guardian pipeline.
	// Returns ("", err) if the LLM is unavailable.
	Generate(ctx context.Context, prompt string) (string, error)

	// UpsertADR creates or updates an Architectural Decision Record.
	UpsertADR(req ADRRequest) error

	// GetADR returns the ADR with the given ID.
	GetADR(id string) (ADR, error)

	// AllADRs returns all ADRs ordered by updated_at descending.
	AllADRs() ([]ADR, error)

	// GetADRsForFile returns accepted ADRs whose linked_files patterns match the given file path.
	GetADRsForFile(filePath string, limit int) ([]ADR, error)

	// QueryDecisions returns up to limit decision log entries, optionally
	// filtered by entityName (empty = all recent), ordered by created_at DESC.
	QueryDecisions(ctx context.Context, entityName string, limit int) ([]DecisionLogEntry, error)
}

type BrainStatsProvider interface {
	BrainStats() map[string]interface{}
}

type ClaimInput struct {
	AgentID   string `json:"agent_id"`
	Scope     string `json:"scope"`
	ScopeType string `json:"scope_type"`
	ExpiresAt string `json:"expires_at,omitempty"` // RFC3339
}

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

type ConstraintItem struct {
	RuleID      string `json:"rule_id"`
	Severity    string `json:"severity"` // "error" | "warning"
	Description string `json:"description"`
	// Hint is a cached fix suggestion (from violation_cache or derived from description).
	Hint string `json:"hint,omitempty"`
}

type ContextPacket struct {
	// Header
	AgentID     string      `json:"agent_id,omitempty"`
	EntityName  string      `json:"entity_name"`
	EntityType  string      `json:"entity_type,omitempty"`
	GeneratedAt string      `json:"generated_at"`
	Phase       SDLCPhase   `json:"phase"`
	QualityMode QualityMode `json:"quality_mode"`

	// Section 1: Semantic Focus (fast path — SQLite only, no LLM)
	// 1-sentence intent summary for the root entity.
	RootSummary string `json:"root_summary,omitempty"`
	// Summaries for key dependencies (entityName → summary). Replaces raw code.
	DependencySummaries map[string]string `json:"dependency_summaries,omitempty"`

	// Section 2: Architectural Insight (LLM path — optional, 2-3s)
	Insight  string   `json:"insight,omitempty"`
	Concerns []string `json:"concerns,omitempty"`

	// Section 3: Architectural Constraints
	ActiveConstraints []ConstraintItem `json:"active_constraints,omitempty"`

	// Section 4: Team Coordination
	TeamStatus []AgentStatus `json:"team_status,omitempty"`

	// Section 5: Quality Gate — concrete checklist for current phase+mode
	QualityGate QualityGate `json:"quality_gate"`

	// Section 6: Learned Patterns ("when editing X, also check Y")
	PatternHints []PatternHint `json:"pattern_hints,omitempty"`

	// Section 7: Phase Guidance — what the agent should do next
	PhaseGuidance string `json:"phase_guidance,omitempty"`

	// LLMUsed indicates whether a live LLM call was made during packet assembly.
	// False means all data came from brain.sqlite (sub-millisecond path).
	LLMUsed bool `json:"llm_used,omitempty"`

	// PacketQuality is a 0.0–1.0 heuristic reflecting how complete this packet is.
	// 0.0 = no summaries ingested yet; 0.5 = summaries present, no insight; 1.0 = full.
	// Agents can use this to decide whether to request a follow-up LLM enrichment pass.
	PacketQuality float64 `json:"packet_quality"`

	// GraphWarnings are actionable warnings derived from graph topology.
	// Examples: "High blast radius (12 callers)", "No tests found for this file".
	// These supplement the LLM Insight with deterministic, always-available guidance.
	GraphWarnings []string `json:"graph_warnings,omitempty"`

	// ComplexityScore is a dimensionless topology-derived risk indicator:
	// (fanIn + fanOut) * (1 + fanOut/10.0). Always populated when the enricher ran,
	// regardless of Ollama availability. 0.0 = isolated/leaf node.
	ComplexityScore float64 `json:"complexity_score,omitempty"`

	// DeterministicPath is true when Phase and ComplexityScore were derived from
	// graph topology without an LLM call. False only when the enricher was not invoked.
	DeterministicPath bool `json:"deterministic_path,omitempty"`
}

type ContextPacketRequest struct {
	AgentID     string                `json:"agent_id,omitempty"`
	ProjectID   string                `json:"project_id,omitempty"`
	Snapshot    SynapsesSnapshotInput `json:"snapshot"`
	Phase       SDLCPhase             `json:"phase,omitempty"`        // "" = use stored project phase
	QualityMode QualityMode           `json:"quality_mode,omitempty"` // "" = use stored project mode
	EnableLLM   bool                  `json:"enable_llm"`             // true = allow LLM insight (~2s)
}

type CoordinateRequest struct {
	// NewAgentID is the agent trying to claim work.
	NewAgentID string `json:"new_agent_id"`
	// NewScope is the scope the new agent wants to claim.
	NewScope string `json:"new_scope"`
	// ConflictingClaims are existing claims that overlap with NewScope.
	ConflictingClaims []WorkClaim `json:"conflicting_claims"`
}

type CoordinateResponse struct {
	// Suggestion is a plain-English recommendation for the new agent.
	Suggestion string `json:"suggestion"`
	// AlternativeScope is a concrete non-conflicting scope the new agent could claim instead.
	AlternativeScope string `json:"alternative_scope"`
	// Degraded is true when the orchestrate tier's circuit tripped and a
	// lower-tier fallback model was used for the coordination suggestion.
	Degraded bool `json:"degraded,omitempty"`
}

type DecisionLogEntry struct {
	ID              string   `json:"id"`
	AgentID         string   `json:"agent_id"`
	Phase           string   `json:"phase"`
	EntityName      string   `json:"entity_name"`
	Action          string   `json:"action"`
	RelatedEntities []string `json:"related_entities,omitempty"`
	Outcome         string   `json:"outcome"`
	Notes           string   `json:"notes,omitempty"`
	CreatedAt       string   `json:"created_at"`
}

type DecisionRequest struct {
	AgentID         string   `json:"agent_id"`
	Phase           string   `json:"phase"`
	EntityName      string   `json:"entity_name"`
	Action          string   `json:"action"` // "edit"|"test"|"review"|"fix_violation"
	RelatedEntities []string `json:"related_entities"`
	Outcome         string   `json:"outcome"` // "success"|"violation"|"reverted"|""
	Notes           string   `json:"notes"`
}

type EnrichRequest struct {
	// ProjectID scopes summary lookups to a specific project.
	ProjectID string `json:"project_id,omitempty"`
	// RootID is the graph node ID of the queried entity.
	RootID string `json:"root_id"`
	// RootName is the entity name (e.g., "AuthService").
	RootName string `json:"root_name"`
	// RootType is the node type (e.g., "struct").
	RootType string `json:"root_type"`
	// AllNodeIDs contains every node ID in the carved subgraph, for summary lookup.
	AllNodeIDs []string `json:"all_node_ids"`
	// CalleeNames are names of entities the root calls directly.
	CalleeNames []string `json:"callee_names"`
	// CallerNames are names of entities that call the root.
	CallerNames []string `json:"caller_names"`
	// RelatedNames are other nodes in the subgraph.
	RelatedNames []string `json:"related_names"`
	// TaskContext is optional context from a linked task (from task_id).
	TaskContext string `json:"task_context,omitempty"`
	// RootFile is the file path of the root entity; used for SDLC phase inference
	// and domain focus in the enricher's deterministic pass.
	RootFile string `json:"root_file,omitempty"`
	// FanIn is the total caller count (may exceed len(CallerNames) when capped).
	// Used for the deterministic complexity score calculation.
	FanIn int `json:"fan_in,omitempty"`
}

type EnrichResponse struct {
	// Insight is a 2-sentence analysis of the entity's architectural role.
	Insight string `json:"insight"`
	// Concerns are specific observations (e.g., "handles auth tokens", "rate limit boundary").
	Concerns []string `json:"concerns"`
	// Summaries maps nodeID → 1-sentence summary for nodes that have been ingested.
	// These are loaded from brain.sqlite (no LLM call needed — fast lookup).
	Summaries map[string]string `json:"summaries"`
	// LLMUsed is true when the LLM was called to generate the Insight field.
	// False means Insight is empty (LLM unavailable, feature disabled, or timed out).
	LLMUsed bool `json:"llm_used"`
	// Degraded is true when the primary enrich tier's circuit tripped and a
	// lower-tier fallback model was used. Summaries are still present; Insight
	// may be weaker. Callers can use this to decide whether to re-request later.
	Degraded bool `json:"degraded,omitempty"`
}

type HealthLevel int

type IngestRequest struct {
	// ProjectID scopes summaries to a specific project, preventing collisions
	// when multiple projects have identically-named entities (e.g., "auth.Login").
	ProjectID string `json:"project_id,omitempty"`
	// NodeID is the stable graph node identifier (e.g., "pkg:func:AuthService.Validate").
	NodeID string `json:"node_id"`
	// NodeName is the short name of the entity (e.g., "Validate").
	NodeName string `json:"node_name"`
	// NodeType is one of: "function", "method", "struct", "interface", "variable".
	NodeType string `json:"node_type"`
	// Package is the Go/language package name.
	Package string `json:"package"`
	// Code is the source snippet — capped at 500 chars to keep prompts small.
	Code string `json:"code"`
}

type IngestResponse struct {
	NodeID  string   `json:"node_id"`
	Summary string   `json:"summary"`        // 1-sentence intent summary
	Tags    []string `json:"tags,omitempty"` // 1-3 domain labels, e.g. ["auth","http"]
}

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

type NLCandidate struct {
	// Name is the normalised candidate name (lowercase, trimmed).
	Name string
	// Context is up to 200 chars of surrounding text for classification.
	Context string
	// NodeID is the existing graph NodeID of the knowledge node to update.
	// Empty means no node was created in Tier 0/1 (should not happen in practice).
	NodeID string
}

type NLClassifyRequest struct {
	// FilePath is the source markdown file, used as the scheduler dedup key.
	FilePath string
	// Candidates are the unresolved entity candidates from Tier 0/1 extraction.
	Candidates []NLCandidate
}

type NLClassifyResult struct {
	// NodeID matches the input NLCandidate.NodeID.
	NodeID string
	// NodeType is one of: concept | entity | artifact | decision.
	// Empty means the LLM returned an unrecognised value; caller keeps the default.
	NodeType string
	// Description is a one-sentence LLM-generated summary of the entity.
	// Empty when the LLM is unavailable or returns an invalid response.
	Description string
}

type NullBrain struct{}

type PatternHint struct {
	Trigger    string  `json:"trigger"`
	CoChange   string  `json:"co_change"`
	Reason     string  `json:"reason,omitempty"`
	Confidence float64 `json:"confidence"`
}

type QualityGate struct {
	RequireTests   bool     `json:"require_tests"`
	RequireDocs    bool     `json:"require_docs"`
	RequirePRCheck bool     `json:"require_pr_check"` // enterprise only
	Checklist      []string `json:"checklist"`
}

type QualityMode string

type RuleInput struct {
	RuleID      string `json:"rule_id"`
	Severity    string `json:"severity"`
	Description string `json:"description"`
}

type SDLCConfig struct {
	Phase       SDLCPhase   `json:"phase"`
	QualityMode QualityMode `json:"quality_mode"`
	UpdatedAt   string      `json:"updated_at"`
	UpdatedBy   string      `json:"updated_by,omitempty"`
}

type SDLCPhase string

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

type SetPhaseRequest struct {
	Phase string `json:"phase"`
}

type SnapshotInput = SynapsesSnapshotInput

type SynapsesSnapshotInput struct {
	RootNodeID      string       `json:"root_node_id,omitempty"`
	RootName        string       `json:"root_name"`
	RootType        string       `json:"root_type,omitempty"`
	RootFile        string       `json:"root_file,omitempty"`        // used for constraint hint lookups
	CalleeNames     []string     `json:"callee_names,omitempty"`     // what root calls directly
	CallerNames     []string     `json:"caller_names,omitempty"`     // what calls root directly
	RelatedNames    []string     `json:"related_names,omitempty"`    // transitive neighbours
	ApplicableRules []RuleInput  `json:"applicable_rules,omitempty"` // rules whose pattern matches RootFile
	ActiveClaims    []ClaimInput `json:"active_claims,omitempty"`    // work claims from other agents
	TaskContext     string       `json:"task_context,omitempty"`
	TaskID          string       `json:"task_id,omitempty"`
	HasTests        bool         `json:"has_tests"`          // whether *_test.go exists for root file
	FanIn           int          `json:"fan_in"`             // total caller count (may exceed len(CallerNames)
	RootDoc         string       `json:"root_doc,omitempty"` // AST doc comment; fallback summary when brain.sqlite has no summary)
}

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

type SystemState struct {
	// AvailableRAM is the amount of RAM free for allocation, in bytes.
	AvailableRAM int64

	// CPULoadNorm is the normalised 1-minute CPU load average in [0.0, 1.0].
	// Computed as load1 / numCPU, clamped to 1.0.
	CPULoadNorm float64

	// OllamaModelLoaded is the name of the model currently resident in Ollama,
	// or "" if Ollama is not running or no model is loaded.
	OllamaModelLoaded string

	// Health is the derived health classification for the current state.
	Health HealthLevel

	// SampledAt is the wall-clock time when this state was last updated.
	SampledAt time.Time
}

type TaskPriority int

type TierState struct {
	Open              bool    `json:"open"`
	Failures          int     `json:"failures"`
	CooldownRemaining float64 `json:"cooldown_remaining_s"`
}

type TierStatusProvider interface {
	TierStatus() map[string]TierState
}

type ViolationExplanation = ViolationResponse

type ViolationRequest struct {
	// RuleID is the unique rule identifier from synapses.json.
	RuleID string `json:"rule_id"`
	// RuleSeverity is "error" or "warning".
	RuleSeverity string `json:"rule_severity"`
	// Description is the rule's human-readable description.
	Description string `json:"description"`
	// SourceFile is the file that triggered the violation.
	SourceFile string `json:"source_file"`
	// TargetName is the entity name being imported/called in violation of the rule.
	TargetName string `json:"target_name"`
}

type ViolationResponse struct {
	// Explanation describes the violation in plain language.
	Explanation string `json:"explanation"`
	// Fix is a concrete, actionable suggestion to resolve the violation.
	Fix string `json:"fix"`
	// Degraded is true when the guardian tier's circuit tripped and a
	// lower-tier fallback model was used for the explanation.
	Degraded bool `json:"degraded,omitempty"`
}

type WorkClaim struct {
	AgentID   string `json:"agent_id"`
	Scope     string `json:"scope"`
	ScopeType string `json:"scope_type"`
}