config

type ApiEntryPattern struct {
	// NamePattern is a case-insensitive substring matched against the entity name.
	NamePattern string `json:"name_pattern,omitempty"`
	// FilePattern is a glob matched against the file base name, or a substring
	// matched against the full path for directory-style patterns (e.g. */handlers/*).
	FilePattern string `json:"file_pattern,omitempty"`
	// NodeType restricts to a specific entity type: function, method, etc.
	NodeType graph.NodeType `json:"node_type,omitempty"`
}

type BrainConfig struct {
	// Enabled controls whether the brain is active. Default: false.
	Enabled bool `json:"enabled"`
	// IntelligenceMode controls RAM residency and model quality tier.
	// "optimal" (8 GB, qwen3.5:2b), "standard" (16 GB, qwen3.5:4b),
	// "full" (32 GB+, qwen3.5:4b pinned). Leave empty for legacy auto-scaling.
	IntelligenceMode string `json:"intelligence_mode,omitempty"`
	// OllamaURL is the base URL of the Ollama server. Default: "http://localhost:11434".
	OllamaURL string `json:"ollama_url,omitempty"`
	// Model is the primary model tag. Default: "qwen3.5:2b".
	Model string `json:"model,omitempty"`
	// FastModel is the model for bulk ingestion. Default: "qwen3.5:2b".
	FastModel string `json:"fast_model,omitempty"`
	// ModelIngest overrides the model for the ingest tier.
	ModelIngest string `json:"model_ingest,omitempty"`
	// ModelGuardian overrides the model for the guardian tier.
	ModelGuardian string `json:"model_guardian,omitempty"`
	// ModelEnrich overrides the model for the enrich tier.
	ModelEnrich string `json:"model_enrich,omitempty"`
	// ModelOrchestrate overrides the model for the orchestrate tier.
	ModelOrchestrate string `json:"model_orchestrate,omitempty"`
	// ModelArchivist overrides the model for the archivist tier.
	ModelArchivist string `json:"model_archivist,omitempty"`
	// DBPath overrides the default SQLite path (~/.synapses/brain.sqlite).
	DBPath string `json:"db_path,omitempty"`
	// Ingest enables automatic code summarization on file save. Default: false.
	Ingest bool `json:"ingest"`
	// Enrich enables LLM enrichment of get_context responses. Default: false.
	Enrich bool `json:"enrich"`
	// ContextBuilder enables LLM-assembled context packets.
	// nil (omitted in JSON) → inherit from brain.Enabled (on when brain is on).
	// true  → always enabled.
	// false → explicitly disabled (opt-out).
	ContextBuilder *bool `json:"context_builder,omitempty"`
}

type Config struct {
	// Version is the config schema version. Currently "1".
	Version string `json:"version"`
	// Mode controls the project's operational mode.
	// "full" (default): full code intelligence with graph, parsing, file watching.
	// "knowledge": memory, events, tasks, and messages only — no code graph.
	// Knowledge mode is useful for non-code domains (marketing, ops, QA).
	Mode string `json:"mode,omitempty"`
	// Rules defines the architectural constraints the rule engine enforces.
	Rules []Rule `json:"rules"`
	// EdgeWeights overrides the default relevance weights for context carving.
	EdgeWeights map[graph.EdgeType]float64 `json:"edge_weights,omitempty"`
	// ContextCarve holds global carving defaults.
	ContextCarve ContextCarveConfig `json:"context_carve,omitempty"`
	// Linked is a list of paths to other indexed projects whose graphs are merged
	// into this project at startup. Paths may be absolute or relative to the
	// directory containing synapses.json. Useful for monorepos where multiple
	// sub-projects share exported types and functions.
	Linked []string `json:"linked,omitempty"`
	// EmbeddingEndpoint is an optional OpenAI-compatible HTTP endpoint for
	// generating vector embeddings. When set, semantic_search will request an
	// embedding for the query and rank results by cosine similarity in addition
	// to FTS5 BM25. Leave empty to use FTS5-only search (no external deps).
	// Compatible with Ollama (/api/embeddings) and OpenAI (/v1/embeddings).
	// Example: "http://localhost:11434/api/embeddings"
	EmbeddingEndpoint string `json:"embedding_endpoint,omitempty"`

	// Embeddings controls memory embedding generation mode.
	// "builtin" (default): pure-Go sentence-transformer inference using
	// nomic-embed-text-v1.5 ONNX model (~137MB). Zero external dependencies.
	// "ollama": delegates to a local Ollama instance (requires Ollama running).
	// Uses EmbeddingEndpoint or defaults to http://localhost:11434/api/embeddings.
	// "off": disabled, FTS5-only recall.
	// Embeddings are computed locally and never sent anywhere (Privacy value).
	Embeddings string `json:"embeddings,omitempty"`

	// EmbeddingModel overrides the Ollama model name. Defaults to "nomic-embed-text".
	// Examples: "mxbai-embed-large", "snowflake-arctic-embed-l", "nomic-embed-text".
	EmbeddingModel string `json:"embedding_model,omitempty"`

	// EmbedPoolSize controls the number of parallel ONNX inference workers when
	// Embeddings is "builtin". Valid range: 1–8. Defaults to 3.
	// Higher values improve throughput on multi-core machines at the cost of
	// additional memory (~137 MB per extra worker for the quantized model).
	EmbedPoolSize int `json:"embed_pool_size,omitempty"`

	// ApiEntries defines custom patterns for identifying API entry points via
	// get_api_contract. These supplement built-in convention detection (net/http,
	// gin, echo, fiber, gRPC, proto RPC). All non-empty fields in a pattern are
	// ANDed together.
	ApiEntries []ApiEntryPattern `json:"api_entries,omitempty"`

	// UseGoTypes enables type-checked CALLS resolution for Go files using
	// golang.org/x/tools/go/packages. When true, a second resolver pass runs
	// after tree-sitter parsing, using go list + type inference to detect
	// cross-package, interface-dispatch, and closure calls that the structural
	// resolver misses. Requires the project to be a valid Go module (go.mod
	// present, dependencies available). Falls back gracefully on error.
	// Default: false (opt-in to avoid adding latency for non-Go projects).
	UseGoTypes bool `json:"use_go_types,omitempty"`

	// UseTSTypes enables type-checked CALLS resolution for TypeScript (.ts/.tsx)
	// files using the TypeScript compiler API. When true, a Node.js subprocess
	// is spawned to resolve cross-file calls, interface implementations, and
	// re-exported symbols that tree-sitter cannot see. Requires Node.js on PATH
	// and the "typescript" npm package in the project's node_modules (or
	// globally installed). Falls back gracefully on error.
	// Default: false (opt-in to avoid latency for non-TypeScript projects).
	UseTSTypes bool `json:"use_ts_types,omitempty"`

	// MetricsDays is the git history window (in days) used when computing
	// per-file churn counts. A value of 0 defaults to 90 days. Churn is
	// computed at index time and stored as node metadata["churn"].
	MetricsDays int `json:"metrics_days,omitempty"`

	// CoverageProfile is a path to a go test -coverprofile output file.
	// When set, function and method nodes are annotated with metadata["coverage"]
	// (0.00–1.00, fraction of statements covered). The path may be absolute or
	// relative to the directory containing synapses.json.
	// Generate with: go test ./... -coverprofile=cover.out
	CoverageProfile string `json:"coverage_profile,omitempty"`

	// PprofProfile is a path to a Go pprof CPU profile file. When set, function
	// and method nodes are annotated with metadata["cpu_pct"] (flat CPU
	// percentage). The path may be absolute or relative to synapses.json.
	// Requires go tool pprof on PATH (standard with any Go installation).
	// Generate with: go test -cpuprofile=cpu.prof  OR  use runtime/pprof in app.
	PprofProfile string `json:"pprof_profile,omitempty"`

	// DataFlowSources defines additional custom source patterns (data entry points).
	// Built-in detection covers *http.Request, gin/echo contexts, Parse*/Decode*,
	// io.Reader, and env-var accessors. Use this to add project-specific sources.
	DataFlowSources []DataFlowPattern `json:"data_flow_sources,omitempty"`

	// DataFlowSinks defines additional custom sink patterns (dangerous data exits).
	// Built-in detection covers SQL exec/query, exec.Command, os.File writes, io.Writer.
	// Use this to add project-specific sinks (e.g. an internal audit log function).
	DataFlowSinks []DataFlowPattern `json:"data_flow_sinks,omitempty"`

	// DataFlowMaxHops is the maximum BFS depth when tracing source-to-sink paths.
	// A value of 0 defaults to 4. Higher values find more indirect paths but are slower.
	DataFlowMaxHops int `json:"data_flow_max_hops,omitempty"`

	// UseFlatGraph enables the FlatGraph SoA layout as an opt-in fast path for
	// PPR BFS candidate expansion. The pointer-based Graph remains the source of
	// truth; FlatGraph is derived from it at build time for cache-friendly traversal.
	// Default: false. Enable only after benchmarking on your specific graph size.
	UseFlatGraph bool `json:"use_flat_graph,omitempty"`

	// Plugins have been removed for security reasons (Workspace RCE).
	// They must now be configured globally via the CLI or user-level config.
	Plugins []PluginConfig `json:"-"`

	// Federation is a list of local sibling projects whose SQLite stores are
	// queried read-only for cross-project dependency tracking and drift detection.
	// Unlike Peers (HTTP-based), federation uses direct filesystem access — no
	// running daemon required. Paths may be absolute or relative to the directory
	// containing synapses.json.
	Federation []FederationEntry `json:"federation,omitempty"`

	// FederationACL controls which daemon-registered projects this project is
	// allowed to query via the projects= parameter on cross-project tools
	// (recall, get_events, get_messages, get_agents, etc.).
	// Default (nil or empty AllowReadFrom): deny-all — no cross-project reads.
	// Set AllowReadFrom to ["*"] to allow reading from all registered projects.
	// Set to specific project names (directory basenames) to allow only those.
	FederationACL *FederationACLConfig `json:"federation_acl,omitempty"`

	// Constitution defines project-wide principles that are injected into every
	// agent session and get_context response. Use this to codify architectural
	// laws, coding standards, and constraints that every AI agent must respect.
	Constitution ConstitutionConfig `json:"constitution,omitempty"`

	// Brain configures the optional synapses-intelligence integration.
	// When set, get_context returns LLM-enriched Context Packets, violations
	// include plain-English explanations, and file changes are auto-ingested.
	Brain BrainConfig `json:"brain,omitempty"`

	// Pulse configures the optional synapses-pulse analytics sidecar.
	// When set, every tool call is reported to the pulse service for token
	// savings and cost attribution telemetry. All errors are silently discarded.
	Pulse PulseConfig `json:"pulse,omitempty"`

	// Session configures agent session memory behavior.
	Session SessionConfig `json:"session,omitempty"`

	// RateLimits configures per-session token-bucket rate limiting for write
	// operations and expensive read operations on the MCP stdio transport.
	// All limits are per-session (per MCP connection) and measured per minute.
	// Set any limit to -1 to disable that category. Defaults apply when omitted.
	RateLimits RateLimitConfig `json:"rate_limits,omitempty"`

	// ContentSafety configures the prompt injection scanner that runs on all
	// externally-sourced content before storage. Covers remember(), send_message(),
	// annotate_node(), and web_annotate() inputs.
	ContentSafety ContentSafetyConfig `json:"content_safety,omitempty"`

	// Recall configures the quad-channel retrieval pipeline.
	Recall RecallConfig `json:"recall,omitempty"`
}

type ConstitutionConfig struct {
	// Principles is a list of terse statements, e.g. "No CGo", "All handlers fail-silent".
	Principles []string `json:"principles,omitempty"`
	// InjectInContext controls whether principles are appended to get_context compact output.
	// Defaults to true when Principles is non-empty.
	InjectInContext bool `json:"inject_in_context,omitempty"`
	// InjectInSessionInit controls whether principles are included in session_init output.
	// Defaults to true when Principles is non-empty.
	InjectInSessionInit bool `json:"inject_in_session_init,omitempty"`
}

type ContentSafetyConfig struct {
	// Enabled controls whether the scanner is active. Default: true.
	Enabled *bool `json:"enabled,omitempty"`
	// Mode controls the response when injection patterns are detected.
	// "warn" (default): log + annotate response, allow storage.
	// "truncate": strip matched content before storage.
	// "reject": return error, refuse to store.
	Mode string `json:"mode,omitempty"`
}

type ContextCarveConfig struct {
	// DefaultDepth is the BFS hop limit when depth is not specified by the caller.
	DefaultDepth int `json:"default_depth,omitempty"`
	// DecayFactor controls relevance falloff per hop (0 < factor ≤ 1).
	DecayFactor float64 `json:"decay_factor,omitempty"`
	// TokenBudget caps the output size in approximate tokens.
	TokenBudget int `json:"token_budget,omitempty"`
	// MinRelevance is the minimum score for a node to appear in the output.
	// Nodes below this threshold are pruned before the token budget is applied.
	MinRelevance float64 `json:"min_relevance,omitempty"`
	// ExcludeTestFiles omits _test.go nodes from get_context output.
	// Defaults to true; set to false to include test nodes in context.
	ExcludeTestFiles *bool `json:"exclude_test_files,omitempty"`
	// DirectionBoost is a relevance multiplier (e.g. 0.2 = +20%) applied to
	// nodes reached via outgoing CALLS edges (callees). Higher values make the
	// token-budget pruner prefer forward call dependencies over callers.
	// Default: 0.2. Set to 0 to disable.
	DirectionBoost float64 `json:"direction_boost,omitempty"`
	// HybridLambda controls the semantic blend weight for hybrid scoring:
	//   finalScore = (1-λ)×structural + λ×cosineSim(embed(root), embed(n))
	// Range [0, 1]. nil = not configured (server applies default of 0.3).
	// Set to 0.0 to disable hybrid scoring entirely (pure structural, fastest).
	// Set to any value in (0, 1] to use that blend ratio.
	// Only applied when node embeddings are available; otherwise ignored.
	// Uses *float64 (pointer) so that explicit 0 is distinguishable from unset.
	HybridLambda *float64 `json:"hybrid_lambda,omitempty"`
	// UsePPR enables Personalized PageRank traversal in get_context instead of
	// the default BFS heuristic. PPR captures multi-path importance — a node
	// reached by N independent call paths scores proportionally higher than a
	// single-path node at the same structural distance. Validated by Sprint 13
	// spike: 4.69× diamond boost, 5.68× wide-fan boost over BFS max-score.
	//
	// Default: true. Set to false to revert to BFS (e.g. for debugging or on
	// very small repos where PPR overhead is unnecessary). Uses *bool so that
	// explicit false is distinguishable from unset (which defaults to true).
	UsePPR *bool `json:"use_ppr,omitempty"`
	// PPRAlpha is the PPR teleport probability — the chance the random walk
	// restarts from the root at each step. Range (0, 1).
	//   Lower alpha → broader reach, more global importance captured.
	//   Higher alpha → tighter focus on root, shorter effective reach.
	// Default: 0.15 (standard PageRank restart rate, validated in spike tests).
	// Values outside (0, 1) are clamped to 0.15. Only used when use_ppr=true.
	PPRAlpha float64 `json:"ppr_alpha,omitempty"`
}

type DataFlowPattern struct {
	// NamePattern is a case-insensitive substring matched against the entity name.
	NamePattern string `json:"name_pattern,omitempty"`
	// SigPattern is a substring matched against the node's signature metadata.
	SigPattern string `json:"sig_pattern,omitempty"`
	// FilePattern is a glob matched against the file base name.
	FilePattern string `json:"file_pattern,omitempty"`
	// NodeType restricts to a specific entity type: function or method.
	NodeType graph.NodeType `json:"node_type,omitempty"`
	// Role is "source" (data entry) or "sink" (dangerous data exit).
	Role string `json:"role"`
	// Label is a human-readable description, e.g. "http_input" or "sql_sink".
	Label string `json:"label,omitempty"`
}

type FederationACLConfig struct {
	// AllowReadFrom is the list of project names (directory basenames) that
	// this project is allowed to query. An empty or nil list means deny-all
	// (no cross-project reads). Use ["*"] to allow all registered projects.
	AllowReadFrom []string `json:"allow_read_from,omitempty"`
}

type FederationEntry struct {
	// Path is the filesystem path to the sibling project root.
	// May be absolute or relative to the directory containing synapses.json.
	Path string `json:"path"`
	// Alias is a short name used in MCP tool params and response labels.
	// Must not contain whitespace. Must be unique across all entries.
	Alias string `json:"alias"`
}

type ForbiddenEdge struct {
	// FromFilePattern matches the source node's file path (glob).
	FromFilePattern string `json:"from_file_pattern,omitempty"`
	// ToFilePattern matches the target node's file path (glob).
	ToFilePattern string `json:"to_file_pattern,omitempty"`
	// FromType restricts the source node type.
	FromType graph.NodeType `json:"from_type,omitempty"`
	// ToType restricts the target node type.
	ToType graph.NodeType `json:"to_type,omitempty"`
	// EdgeType restricts the relationship type.
	EdgeType graph.EdgeType `json:"edge_type,omitempty"`
	// ToNamePattern is a substring that must appear in the target node's name.
	ToNamePattern string `json:"to_name_pattern,omitempty"`
	// PathPattern enables multi-hop constraint checking. When non-empty, the
	// rule fires when a from-matching node can reach a to-matching node by
	// traversing edges in the exact sequence specified here. Each element is
	// an edge type that must be followed in order.
	//
	// Example: PathPattern=["CALLS","CALLS"] with FromFilePattern="*/handlers/*"
	// and ToFilePattern="*/db/*" fires when a handler calls an intermediary
	// that directly calls a database entity — the two-hop path is forbidden.
	//
	// When PathPattern is set, EdgeType is ignored (the pattern defines the
	// edge sequence). Maximum depth is 8 hops; longer patterns are capped.
	PathPattern []graph.EdgeType `json:"path_pattern,omitempty"`
}

type PluginConfig struct {
	// Extensions is the list of file extensions this plugin handles (e.g. [".prisma", ".graphql"]).
	// The leading dot is required. If two plugins claim the same extension the last one wins.
	Extensions []string `json:"extensions"`
	// Command is the shell command to execute, e.g. "./parsers/prisma-parser" or
	// "node parsers/graphql.js". Words are split on whitespace; use a wrapper
	// script for paths containing spaces.
	Command string `json:"command"`
}

type PulseConfig struct {
	// URL is the base URL of the pulse service, e.g. "http://localhost:11437".
	// Leave empty to disable pulse integration.
	URL string `json:"url,omitempty"`
	// TimeoutSec is the per-request HTTP timeout. Defaults to 2 if URL is set.
	// Pulse is fire-and-forget so a short timeout is appropriate.
	TimeoutSec int `json:"timeout_sec,omitempty"`
}

type RateLimitConfig struct {
	// WriteOpsPerMinute is the maximum number of write-category tool calls
	// (remember, send_message, annotate_node, upsert_rule, create_plan) per
	// session per minute. Default: 30. Set to -1 to disable.
	WriteOpsPerMinute int `json:"write_ops_per_minute,omitempty"`

	// ExpensiveReadsPerMinute is the maximum number of recall calls per session
	// per minute. Default: 20. Set to -1 to disable.
	ExpensiveReadsPerMinute int `json:"expensive_reads_per_minute,omitempty"`

	// CrossProjectPerMinute is the maximum number of cross-project queries
	// (any tool called with projects="*" or a specific project name) per
	// session per minute. Default: 60. Set to -1 to disable.
	CrossProjectPerMinute int `json:"cross_project_per_minute,omitempty"`
}

type RecallConfig struct {
	// FusionMode selects the multi-channel merging strategy.
	// "rrf" (default): Reciprocal Rank Fusion — uses rank positions only.
	// "convex": Score-aware convex combination — uses score magnitudes.
	//   Research shows 3.86% NDCG@10 improvement when channels have
	//   heterogeneous score distributions (Benham & Culpepper, 2017).
	FusionMode string `json:"fusion_mode,omitempty"`

	// ConvexAlpha controls the BM25 vs semantic balance in convex fusion.
	// score = α × norm_bm25 + (1-α) × norm_cosine + graph_bonus + temporal_bonus.
	// Range [0.0, 1.0]. Default 0.5 (equal weight). Higher = more BM25 influence.
	// Only used when FusionMode is "convex".
	ConvexAlpha *float64 `json:"convex_alpha,omitempty"`

	// ConvexGraphBonus is the additive weight for graph channel in convex fusion.
	// Range [0.0, 1.0]. Default 0.3.
	ConvexGraphBonus *float64 `json:"convex_graph_bonus,omitempty"`

	// ConvexTemporalBonus is the additive weight for temporal channel in convex fusion.
	// Range [0.0, 1.0]. Default 0.2.
	ConvexTemporalBonus *float64 `json:"convex_temporal_bonus,omitempty"`
}

type Rule struct {
	// ID is a unique, human-readable identifier for this rule.
	ID string `json:"id"`
	// Description explains what the rule prevents and why.
	Description string `json:"description"`
	// ForbiddenEdge describes the edge pattern that must never exist.
	// Empty for agent-type rules (no code-graph check).
	ForbiddenEdge ForbiddenEdge `json:"forbidden_edge"`
	// Severity is one of "error" or "warning".
	Severity string `json:"severity"`
	// RuleType distinguishes structural rules (code-graph enforcement) from
	// agent rules (behavioral constraints surfaced in session_init).
	// Values: "structural" (default) or "agent".
	RuleType string `json:"rule_type,omitempty"`
}

type SessionConfig struct {
	// AutoEndThresholdCalls is the number of tool calls before the daemon automatically
	// extracts and persists session memory without waiting for an explicit end_session call.
	// When exceeded, a session log is written with source="auto" and the "auto_session_log"
	// tag so it can be filtered if needed. If the agent later calls end_session explicitly,
	// the existing auto-log is reused (touched) rather than creating a duplicate.
	//
	// Default: 0 (disabled). Set to a positive integer to enable. Recommended: 80
	// (roughly 40 minutes of session time at ~2 calls/minute).
	// Example: auto_end_threshold_calls: 80
	AutoEndThresholdCalls int `json:"auto_end_threshold_calls,omitempty"`

	// ReconnectWindowSecs is the number of seconds within which a new session_init
	// from the same agent on the same MCP connection is treated as a reconnect
	// (resume) rather than a new session. This prevents duplicate session rows when
	// an agent restarts or the MCP transport reconnects briefly.
	//
	// Default: 300 (5 minutes). Must be > 0 to enable resume behaviour; set to 0
	// to always create a new session on every session_init call.
	// Example: reconnect_window_secs: 300
	ReconnectWindowSecs int `json:"reconnect_window_secs,omitempty"`

	// StaleThresholdMins is the number of minutes of inactivity after which a
	// session without a clean end_session is surfaced as stale at the next
	// session_init. Stale sessions are advisory — never auto-closed.
	//
	// Default: 30 minutes. Tune down for high-churn teams, up for long-running
	// background agents.
	// Example: stale_threshold_mins: 30
	StaleThresholdMins int `json:"stale_threshold_mins,omitempty"`

	// HibernateWindowSecs is the number of seconds a session can be dormant
	// before it is no longer resumable across a new MCP connection. When an
	// agent calls session_init on a new physical connection (e.g. after
	// restarting the editor or taking a break), Synapses looks for a prior
	// session from the same agent+project within this window and resumes it
	// transparently — carrying over intent, tool call count, and summary.
	//
	// Only sessions older than ReconnectWindowSecs (i.e. not currently live
	// on another connection) are candidates. This prevents two concurrent
	// editor windows from stealing each other's sessions.
	//
	// Default: 0 (uses built-in default of 14400 s / 4 hours). Set to a
	// positive value to override the default window. Set to a negative value
	// (e.g. -1) to disable cross-connection resume entirely.
	// Example: hibernate_window_secs: 7200   # 2-hour window
	// Example: hibernate_window_secs: -1      # disable
	HibernateWindowSecs int `json:"hibernate_window_secs,omitempty"`
}

type Violation struct {
	RuleID      string         `json:"rule_id"`
	Severity    string         `json:"severity"`
	Description string         `json:"description"`
	FromNode    graph.NodeID   `json:"from_node"`
	ToNode      graph.NodeID   `json:"to_node"`
	EdgeType    graph.EdgeType `json:"edge_type"`
	// FromFile and ToFile are the source files of the from/to nodes respectively.
	// Populated at detection time for indexed lookup in violation_log.
	FromFile string `json:"from_file,omitempty"`
	ToFile   string `json:"to_file,omitempty"`
	// SuggestedFix is a concise, actionable refactoring hint generated from the
	// rule pattern and the names of the two nodes involved in the violation.
	SuggestedFix string `json:"suggested_fix,omitempty"`
	// Explanation is a plain-English LLM-generated explanation of why this
	// violation matters, populated when synapses-intelligence is configured.
	Explanation string `json:"explanation,omitempty"`
}