/**
 * dashboard-server/routes-rag-settings-helpers.ts — SETTINGS inventory.
 *
 * The full catalog of user-adjustable MEGACOMPACT_* settings surfaced by the
 * dashboard Setup panel, grouped by category. Kept separate from the route
 * handler so the inventory can grow without bloating the handler file.
 *
 * PREVENT-011: no `any` type.
 */
import type { SettingSpec, SettingGroup } from "./routes-rag-settings-types.js";
import { VECTOR_CORTEX_SETTINGS } from "./routes-rag-settings-vector-cortex.js";
import { COMPACTION_SETTINGS } from "./routes-rag-settings-compaction.js";

export type { SettingSpec } from "./routes-rag-settings-types.js";

// Shorthand builders to keep the inventory terse and unambiguous.
const boolFlag = (
	key: string,
	label: string,
	description: string,
	def: boolean,
	requiresLlm = false,
): SettingSpec => ({
	key,
	label,
	description,
	type: "boolean",
	default: def,
	disabledConvention: true,
	requiresLlm,
});

const boolDirect = (
	key: string,
	label: string,
	description: string,
	def: boolean,
): SettingSpec => ({
	key,
	label,
	description,
	type: "boolean",
	default: def,
	disabledConvention: false,
	requiresLlm: false,
});

const num = (
	key: string,
	label: string,
	description: string,
	def: number,
	min: number,
	max: number,
	unit?: string,
): SettingSpec => ({
	key,
	label,
	description,
	type: "number",
	default: def,
	disabledConvention: false,
	requiresLlm: false,
	min,
	max,
	...(unit ? { unit } : {}),
});

const str = (
	key: string,
	label: string,
	description: string,
	def: string,
): SettingSpec => ({
	key,
	label,
	description,
	type: "string",
	default: def,
	disabledConvention: false,
	requiresLlm: false,
});

/** Every adjustable setting, grouped by category. Read-only after module load. */
export const SETTINGS: ReadonlyArray<SettingGroup> = [
	{
		name: "RAG Pipeline",
		settings: [
			boolFlag(
				"MEGACOMPACT_QUERY_REFORMULATION",
				"Query Reformulation",
				"TF-IDF keyword expansion for vague recall queries",
				true,
			),
			boolFlag(
				"MEGACOMPACT_TIERED_ROUTER",
				"Tiered Recall Router",
				"L0 cache → L1 FTS5 → L2 HNSW routing",
				true,
			),
			boolFlag(
				"MEGACOMPACT_RECALL_METRICS",
				"Recall Quality Metrics",
				"Precision/recall scoring and logging",
				true,
			),
			boolFlag(
				"MEGACOMPACT_MEMORY_GRAPH",
				"Memory Graph",
				"Dashboard-oriented memory graph traversal",
				true,
			),
			boolFlag(
				"MEGACOMPACT_HYDE",
				"HyDE",
				"Generate hypothetical answer via LLM, embed it, RRF-fuse",
				true,
				true,
			),
			boolFlag(
				"MEGACOMPACT_NEW_UI",
				"New Dashboard UI",
				"Tailwind + shadcn visual design (sidebar, glass panels)",
				true,
			),
			boolDirect(
				"MEGACOMPACT_MESSAGE_SEPARATION",
				"Message Separation (P2)",
				"PLAN_V2: split conversation thread from tool results to grow stable cache prefix",
				true,
			),
			boolDirect(
				"MEGACOMPACT_CACHE_STRIPING",
				"Cache Striping (P3)",
				"PLAN_V2: order stable context by stability score so durable chunks lead the prompt",
				true,
			),
		],
	},
	{
		name: "Wiki / Turns",
		settings: [
			boolFlag(
				"MEGACOMPACT_WIKI_ENHANCED",
				"Wiki Enhanced",
				"User curation (rename/merge/split) + topic evolution",
				true,
			),
			boolFlag(
				"MEGACOMPACT_WIKI_INCREMENTAL",
				"Wiki Incremental",
				"Assign new memories to nearest centroid",
				true,
			),
			boolDirect(
				"MEGACOMPACT_AUTO_WIKI",
				"Auto Wiki",
				"Auto-categorizing wiki (k-means + TF-IDF)",
				true,
			),
			boolDirect(
				"MEGACOMPACT_WIKI_SEED_FROM_TURNS",
				"Wiki Seed from Turns",
				"Seed topic model from raw_transcript when chunks thin",
				true,
			),
			boolDirect(
				"MEGACOMPACT_TURNS_DB",
				"Turns DB",
				"Isolated turns.db store",
				true,
			),
			num(
				"MEGACOMPACT_WIKI_SILHOUETTE_MIN",
				"Silhouette Minimum",
				"Full rebuild trigger threshold",
				0.2,
				0,
				1,
			),
			num(
				"MEGACOMPACT_TURNS_RETENTION_DAYS",
				"Turn Retention",
				"Per-turn provenance retention window",
				30,
				1,
				365,
				"days",
			),
			num(
				"MEGACOMPACT_TURNS_KEEP_MIN",
				"Turns Keep Minimum",
				"Min turns kept per conversation during prune",
				5,
				1,
				100,
			),
			num(
				"MEGACOMPACT_WIKI_LABEL_TOP_TERMS",
				"Wiki Label Terms",
				"How many TF-IDF terms form a topic label",
				5,
				1,
				20,
			),
			num(
				"MEGACOMPACT_WIKI_REBUILD_EVERY",
				"Wiki Rebuild Every",
				"Rebuild topic model every Nth compaction",
				3,
				1,
				50,
			),
		],
	},
	{
		name: "Dedup Tiers",
		settings: [
			boolDirect("MEGACOMPACT_L0_ENABLED", "L0 Exact Match", "Exact-hash dedup tier", true),
			boolDirect("MEGACOMPACT_L1_ENABLED", "L1 MinHash/LSH", "Near-dup tier", true),
			boolDirect("MEGACOMPACT_L2_ENABLED", "L2 Semantic", "Cosine similarity dedup tier", true),
			boolDirect("MEGACOMPACT_RAPTOR_ENABLED", "RAPTOR", "Hierarchical clustering tier", true),
			boolDirect("MEGACOMPACT_RAPTOR_MULTILEVEL", "RAPTOR Multi-level", "Multi-level retrieval (score all tree levels)", true),
			boolDirect("MEGACOMPACT_RAPTOR_LEAF_EXPANSION", "RAPTOR Leaf Expansion", "Leaf node expansion in retrieval", true),
			boolDirect("MEGACOMPACT_RAPTOR_INCREMENTAL", "RAPTOR Incremental", "Incremental rebuild mode", true),
			boolDirect("MEGACOMPACT_RAPTOR_INJECT_SUMMARIES", "RAPTOR Inject Summaries", "Inject top-level summary nodes into recall", true),
			boolDirect("MEGACOMPACT_MARK_ONLY_L0", "Mark Only L0", "L0 runs but does not collapse", false),
			boolDirect("MEGACOMPACT_MARK_ONLY_L1", "Mark Only L1", "L1 runs but does not collapse", false),
			boolDirect("MEGACOMPACT_MARK_ONLY_L2", "Mark Only L2", "L2 runs but does not collapse", false),
			boolDirect("MEGACOMPACT_MINILM", "MiniLM Embedder", "Use MiniLM instead of trigram", false),
			boolDirect(
				"MEGACOMPACT_DEDUP_DEGENERATE_GUARD",
				"Degenerate Match Guard",
				"Decline an L1/L2 collapse when the MATCHED stored checkpoint is a content-free skeleton (a ~30-40 token structural summary) and the incoming region is richer. Without this, one degenerate checkpoint absorbs every later compaction forever and the store can never heal. OFF = byte-identical pre-guard cascade. Calibrated by the two Degenerate floors under Dedup Thresholds.",
				true,
			),
			boolDirect(
				"MEGACOMPACT_DEDUP_AUDIT",
				"Dedup Audit Trail",
				"Append one events.log line per tier decision (which layer collapsed a region, onto what, at what similarity) to tune the thresholds below. Pure instrumentation — dedup behavior is identical either way.",
				true,
			),
		],
	},
	{
		name: "Dedup Thresholds",
		settings: [
			num("MEGACOMPACT_L2_THRESHOLD", "L2 Cosine Threshold", "L2 semantic dedup firing point", 0.85, 0, 1),
			num("MEGACOMPACT_L1_JACCARD", "L1 Jaccard Threshold", "L1 MinHash near-dup threshold", 0.8, 0, 1),
			num("MEGACOMPACT_DEDUP_SIM", "Dedup Similarity", "Legacy content-similarity fallback", 0.9, 0, 1),
			num("MEGACOMPACT_DEDUP_DEGEN_MIN_TOKENS", "Degenerate Min Tokens", "Absolute token floor below which a stored summary counts as a degenerate skeleton (Degenerate Match Guard)", 48, 0, 10000, "tokens"),
			num("MEGACOMPACT_DEDUP_DEGEN_MIN_PCT", "Degenerate Min Percent", "Relative floor as a fraction of the summary's original region size; a summary under max(min-tokens, pct x original) is degenerate", 0.005, 0, 1),
			num("MEGACOMPACT_RECALL_MIN_COSINE", "Recall Min Cosine (same-repo)", "3WF-3 same-repo floor the 3-source validator applies to the top winner (cross-repo 0.90 stays separate)", 0.12, 0, 1),
			num("MEGACOMPACT_MMR_LAMBDA", "MMR Lambda", "Maximal Marginal Relevance diversity", 0.5, 0, 1),
			num("MEGACOMPACT_SEMDEDUP_COSINE", "SemDeDup Cosine", "Offline SemDeDup pair threshold", 0.95, 0, 1),
			num("MEGACOMPACT_CONSOLIDATE_COSINE", "Consolidate Cosine", "Memory consolidation merge threshold", 0.7, 0, 1),
			num("MEGACOMPACT_SIMILARITY_BUDGET_MS", "Similarity Budget", "Time budget for similarity computation", 50, 1, 10000, "ms"),
			num("MEGACOMPACT_L1_VERIFY_BUDGET_MS", "L1 Verify Budget", "L1 verification time budget", 20, 1, 10000, "ms"),
			num("MEGACOMPACT_L1_CANDIDATE_CAP", "L1 Candidate Cap", "L1 candidate cap", 100, 1, 10000),
		],
	},
	{
		name: "RAPTOR Tuning",
		settings: [
			num("MEGACOMPACT_RAPTOR_BUDGET_MS", "RAPTOR Budget", "RAPTOR time budget", 5000, 100, 60000, "ms"),
			num("MEGACOMPACT_RAPTOR_CLUSTERS", "RAPTOR Clusters", "Clusters per level", 5, 1, 50),
			num("MEGACOMPACT_RAPTOR_CONSISTENCY", "RAPTOR Consistency", "Consistency threshold", 0.6, 0, 1),
			num("MEGACOMPACT_RAPTOR_MAX_LEAF_EXP", "RAPTOR Max Leaf Expansion", "Max leaf expansion nodes", 10, 1, 100),
			num("MEGACOMPACT_RAPTOR_FRESHNESS_HOURS", "RAPTOR Freshness", "Skip rebuild when tree is fresh", 4, 1, 168, "hours"),
			num("MEGACOMPACT_FP_RATE_L0", "FP Rate L0", "FP alert threshold for exact tier", 0.01, 0, 1),
			num("MEGACOMPACT_FP_RATE_L1L2", "FP Rate L1/L2", "FP alert threshold for fuzzy tiers", 0.05, 0, 1),
			num("MEGACOMPACT_ALERT_WINDOW_MS", "Alert Window", "Alert evaluation window", 600000, 1000, 3600000, "ms"),
			num("MEGACOMPACT_P95_BUDGET_MS", "P95 Budget", "Canary p95 budget per tier", 100, 1, 10000, "ms"),
		],
	},
	{
		name: "Models",
		settings: [
			str("MEGACOMPACT_HYDE_MODEL", "HyDE Model", "LLM model name for HyDE generation", "llama3.2"),
			str("MEGACOMPACT_RAPTOR_MODEL", "RAPTOR Summary Model", "Ollama model for cluster summarization (empty = extractive)", ""),
			str("MEGACOMPACT_RAPTOR_URL", "RAPTOR Ollama URL", "Ollama endpoint for RAPTOR summarization", "http://127.0.0.1:11434"),
			num("MEGACOMPACT_EMBED_CACHE", "Embed Cache Size", "Embedding cache entries (0 = disabled)", 256, 0, 10000),
			num("MEGACOMPACT_EMBEDDING_BATCH_TOKENS", "Embedding Batch Tokens", "Oversized-prompt chunking limit (tokens) for the BYO localhost embedder; text above this is chunked + mean-pooled", 2048, 64, 8192),
			num("MEGACOMPACT_EMBEDDING_CHARS_PER_TOKEN", "Embedding Chars per Token", "Estimated characters per token used for embedder chunking size", 4, 1, 32),
		],
	},
	// v0.21.9: compaction group extracted to keep this file under the
	// extensions/ soft limit (delegate-shell split); carries the overflow-
	// headroom + output-reserve flags alongside the pre-existing trio.
	COMPACTION_SETTINGS,
	{
		name: "Three-Way Failback",
		settings: [
			boolDirect(
				"MEGACOMPACT_THREE_WAY_FAILBACK",
				"Three-Way Failback",
				"Umbrella for the 3-way failback safety system: TriggerGuard (stages a recall block even when session_start never fires), the live-window ReductionValidator + persisted ThrashGuard (stops ineffective compaction re-fire loops), the 3-source read-only recall vote + same-repo relevance floor, and InjectionConfirm (asserts the staged block reached the message list pi sends). OFF = byte-identical pre-3WF behavior (v0.20.83). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
				true,
			),
			boolDirect(
				"MEGACOMPACT_ITHACUS_BRIDGE",
				"ithacus Bridge",
				"Mega↔ithacus bridge: gate the child extension + bridge usage that tie this extension to ithacus's durable compaction. Default ON; OFF (=0/`=false`) is byte-identical to pre-bridge behavior — the bridge is only consulted when this is ON. Positive sprint flag. Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
				true,
			),
			boolDirect(
				"MEGACOMPACT_RECALL_TAIL_INJECT",
				"Recall Tail Inject",
				"Compose the staged recall block as a trailing user message on the context event (tail inject) instead of the legacy system-prompt prepend. Tail mode keeps the cache prefix stable and is the mode InjectionConfirm verifies against ContextEvent.messages; OFF falls back to the legacy prepend path (verified by string-contains). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
				true,
			),
		],
	},
	VECTOR_CORTEX_SETTINGS,
	{
		name: "Cost API",
		settings: [
			boolDirect(
				"MEGACOMPACT_COST_API_ENABLED",
				"Cost API Lookup",
				"Fetch model pricing from an external API (PREVENT-PI-004 network exception — opt-in). Enriches the dashboard Cache/Repos tabs with real $/token rates for models not in the local pricing table.",
				false,
			),
			str(
				"MEGACOMPACT_COST_API_URL",
				"Cost API URL",
				"OpenRouter-compatible model pricing endpoint (e.g. https://openrouter.ai/api/v1/models). Only contacted when Cost API Lookup is ON.",
				"",
			),
		],
	},
];

/** Flat index of every setting by key for O(1) lookup + validation. */
export const SETTING_BY_KEY: ReadonlyMap<string, SettingSpec> = new Map(
	SETTINGS.flatMap((c) => c.settings).map((s) => [s.key, s]),
);

/**
 * Adjustable MEGACOMPACT_* env vars intentionally NOT surfaced in the settings
 * UI. Handled by other panels, install-time paths, dev-only, internal tuning,
 * or special string formats the generic form cannot represent.
 * Kept as string literals so regression_check.py's coverage scan sees them.
 */
export const EXCLUDED_SETTINGS: readonly string[] = [
	// Embedder telemetry — handled by EmbedderSetup.
	"MEGACOMPACT_EMBEDDING_URL",
	"MEGACOMPACT_EMBEDDING_KEY",
	"MEGACOMPACT_EMBEDDING_HEADERS",
	"MEGACOMPACT_EMBEDDING_DIM",
	"MEGACOMPACT_OLLAMA_MODEL",
	"MEGACOMPACT_ALLOW_REMOTE_EMBEDDER",
	// Install-time paths.
	"MEGACOMPACT_STATE_DIR",
	"MEGACOMPACT_INDEX_DIR",
	"MEGACOMPACT_VECTOR_INDEX_DIR",
	"MEGACOMPACT_TURNS_DB_PATH",
	// Dev-only.
	"MEGACOMPACT_EXT_SCAN_DIR",
	"MEGACOMPACT_EXT_USER_DIR",
	// PGlite internal tuning.
	"MEGACOMPACT_PGLITE_DISABLED",
	"MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS",
	"MEGACOMPACT_PGLITE_CLOSE_TIMEOUT_MS",
	"MEGACOMPACT_PGLITE_QUERY_TIMEOUT_MS",
	// Special string formats the generic form cannot represent.
	"MEGACOMPACT_WIKI_K_RANGE",
	"MEGACOMPACT_RAPTOR_LEVEL_WEIGHTS",
	// Internal calibration, not user-facing.
	"MEGACOMPACT_FTS5_MAX_BM25",
	// Boot-fallback context window — display-seed only, never a firing gate.
	"MEGACOMPACT_DEFAULT_CONTEXT_WINDOW",
	// COS-FP-A: per-content-type L2 override landing slots. Null/unset by
	// default and NOT wired into the live L2 decision this sprint — the
	// top-level MEGACOMPACT_L2_THRESHOLD is the single runtime firing point. A
	// default-OFF numeric slot is not yet an adjustable firing knob, so it is
	// excluded (the report carries the recommendation; adoption is a separate
	// gated sprint).
	"MEGACOMPACT_L2_THRESHOLD_CODE",
	"MEGACOMPACT_L2_THRESHOLD_PROSE",
];